PEAR Manual
Next

PEAR Manual

2009-07-26

Edited By

Daniel Convissor
Martin Jansen
Alexander Merz

Copyright © 2001-2009, by The PEAR Documentation Group

Table of Contents
  • About the manual
    • Copyright
    • XML-RPC documentation copyright
  • User Guide
    • Basic concepts all PEAR users should understand
    • Installation (Pyrus)
    • Installation (PEAR)
    • Command line installer (PEAR)
  • Using Pyrus, the PEAR Installer for PHP 5.3+
    • About Pyrus
    • Commands available in Pyrus
    • Pyrus configuration
    • Differences from the PEAR Installer
    • Creating plugins for Pyrus
    • Developer Tools for Pyrus
  • PEAR Developer Guide
    • About PEAR and PEAR2
    • Becoming a PEAR developer: how to get involved
    • PEAR Developer Guide
    • Coding Standards
    • PEAR Installer: Core components (Installer API, error handling)
    • PEAR Installer: customizing the installer itself
    • RFCs
  • Channels: distributing your packages
    • channel.xml, REST, XML-RPC
    • Creating your own channel with Pyrus and PEAR2_SimpleChannelServer
  • PEAR Packages
    • Authentication
    • Benchmarking
    • Caching
    • Configuration
    • Console
    • Database
    • Date and Time
    • Encryption
    • Event
    • File Formats
    • File System
    • Gtk
    • Gtk2
    • HTML
    • HTTP
    • Images
    • Internationalization
    • Logging
    • Mail
    • Math
    • Networking
    • Numbers
    • PEAR
    • PHP
    • QA Tools
    • Streams
    • Structures
    • System
    • Text
    • Tools and Utilities
    • Validate
    • Web Services
    • XML
Next
About the manual


About the manual
Prev Next

About the manual

Preface

PEAR is the PHP Extension and Application Repository.

This Manual

This manual is written in XML using a slightly enhanced version of the DocBook 5 XML DTD, using PHP's very own DocBook rendering system PhD.

The structure of the Manual

This guide explains the general structure, layout, and conventions used in the PEAR manual. The manual is divided into six main parts, they are:

  • About PEAR

    This section contains a gentle introduction to what PEAR is and has to offer. Included is general information about installing and using PEAR, support options, and answers to frequently asked PEAR related questions.

  • Developer Guide

    General information about developing and releasing PEAR-Packages.

  • Core components

    This section contains documentation about the core PEAR classes. These core components are the base to every PEAR class and understanding the basics will allow general use of the PEAR library. Topics include the PEAR base, PEAR administration, error handling through use of the PEAR_Error object, and system commands. These classes are generally shipped with every source PHP distribution.

  • Packages

    There are many PEAR packages with the number growing every day. Most every package is documented and most are not installed by default. For information on installing PEAR classes on your system, be sure to read the Installation chapter.

    Each documented class contains basic documentation about the packages publically available functions. There may also be additional information like an introduction, list of available constants, and example uses of the given package. Additional information may also exist within the package source files themselves.

    The description of each function may contain some or all of the following parts:

    • Synopsis

      Shows the structure and prototype of the function.

    • Description

      Gives a description about what the function does.

    • Parameter

      Describes each parameter for the function along with the parameter types and names. Both required and optional parameters are listed.

    • Returns

      Describes the returned value, if the function doesn't fail.

    • Throws

      Describes the returned PEAR_Error objects, if the function fails.

    • Note

      Additional notes and information about the function. An example note would be if the function can be called statically.

    • See

      Links to other related functions or manual entries.

    • Example

      An example use of the function or class.

  • Contributing to PEAR

    Contains information for writing your own PEAR Packages.

Authors and Contributors

The following is a list of people that are helping to maintain this documentation. If you would like to contact one of them, please write to pear-doc@lists.php.net.

  • Edited By

    Lorenzo Alberton

  • Edited By

    Gregory Beaver

  • Edited By

    David Coallier

  • Edited By

    Daniel Convissor

  • Edited By

    David Costa

  • Edited By

    Thomas V.V. Cox

  • Edited By

    Michael Gauthier

  • Edited By

    Christophe Gesché

  • Edited By

    Ken Guest

  • Edited By

    Martin Jansen

  • Edited By

    Alan Knowles

  • Edited By

    Clay Loveless

  • Edited By

    Alexander Merz

  • Edited By

    Stefan Neufeind

  • Edited By

    Jon Parise

  • Edited By

    Tobias Schlitt

  • Edited By

    Stephan Schmidt

  • Edited By

    Mika Tuupola

  • Edited By

    Michael Wallner

  • Edited By

    Christian Weiske

  • Edited By

    Mark Wiesemann

(In alphabetic order.)

Prev |  | Next
PEAR Manual | PEAR Manual | Copyright


Copyright

Copyright

Copyright © 2001 - 2008 by the PEAR Documentation Group. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.

The PEAR Documentation Group consists of all the people that have contributed documentation to the PEAR manual. Representatives are listed on the front page of this manual. In case you would like to contact the group, please write to pear-doc@lists.php.net.

Prev | About the manual | Next
About the manual | PEAR Manual | XML-RPC documentation copyright


XML-RPC documentation copyright

XML-RPC documentation copyright

The documentation of the XML_RPC package has originally been written by Edd Dumbill as an independent document on his homepage and is published as part of the PEAR Manual under the following license restrictions:

Copyright © 1999,2000,2001 by Edd Dumbill, Useful Information Company

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the "XML-RPC for PHP" nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Prev | About the manual | Next
Copyright | PEAR Manual | User Guide


User Guide

User Guide

Table of Contents
  • Basic concepts all PEAR users should understand
  • Installation (Pyrus)
  • Installation (PEAR)
  • Command line installer (PEAR)
Prev |  | Next
XML-RPC documentation copyright | PEAR Manual | Basic concepts all PEAR users should understand


Basic concepts all PEAR users should understand

Basic concepts all PEAR users should understand

Table of Contents
  • PEAR Packages
  • API (Application Program Interface)
  • Package stability
  • Package version
  • Abstract Package Name (for install/uninstall command)
  • PEAR Channels
  • File roles
  • File tasks

Edited By

Gregory Beaver

2009-06-26

This chapter describes basic concepts that are important for all users of Pyrus, the PEAR Installer, or PEAR packages to understand.

Prev | User Guide | Next
User Guide | PEAR Manual | PEAR Packages


PEAR Packages

PEAR Packages

The smallest unit that can be managed by Pyrus or the PEAR Installer is a package. A package is a collection of files that are organized and defined by a meta-information file called package.xml.

A package also contains meta-information about the collected files, such as the name of the package, the channel that the package is from, the version of the package, information on the developers who created the package, and any external dependencies the package has on other packages or installation requirements (such as minimum PHP version).

Packages can exist as a collection of files on disk, or can be placed into an archive in phar, tar, or zip format and then later installed on another system.

Prev | Basic concepts all PEAR users should understand | Next
Basic concepts all PEAR users should understand | PEAR Manual | API (Application Program Interface)


API (Application Program Interface)

API (Application Program Interface)

A package's API is the publicly documented entry points to the library or program within the package. For example, the classes or methods that are to be used with a PEAR package, or the commands for a command-line program are all elements of an API. Another example might be the templating language.

Any element of the program that is not intended to be used by the outside world, or is not documented, is not considered part of the API, and thus should not be relied upon in your programs as it may change in any future release.

Prev | Basic concepts all PEAR users should understand | Next
PEAR Packages | PEAR Manual | Package stability


Package stability

Package stability

Versioning and stability are separate entities for packages. The stability of a package determines how likely the package is to contain bugs or to have changes to its API. A distinction is made between the version/stability of the API and the version/stability of the code.

This simple chart shows the meaning of a package's stability:

What a package's stability means
Stability type | Stability | Description
Release | devel | The package is under development and will change dramatically, both adding new features, changing the design, and fixing many bugs. It may not function at all and be more of a proof-of-concept. There may be little to no documentation or unit tests. Use at your own risk.
Release | alpha | The package is ready for testing by hard core users. Features are still being developed, but the program should work. Subsequent releases may have major changes.
Release | beta | The package is nearly ready for public release and usage in production. Documentation is complete, unit tests are complete, and the API is frozen (will not change) unless major problems are found.
Release | stable | The package is ready for use in production. Documentation is complete, unit tests are complete, and the API is frozen completely and will not change.
API | devel | The API will change dramatically between releases, and cannot be relied upon.
API | alpha | The API is starting to stabilize, but may still have major changes.
API | beta | The API will only have changes if major bugs are found.
API | stable | The API will not change and can be relied upon.

There are a few conventions that should be followed when deciding which stability to use for your package. In general, the API stability should be equal to or better than the release stability.

Here is a helpful chart of stabilities:

Which stability to use
Release Stability | API Stability | Scenario
devel | devel | This package is brand new, no documentation, no tests, more of a proof-of-concept. It may not work at all.
alpha | alpha | This package has been developed extensively, and is ready for testing by the outside world, has some documentation or full documentation and tests, but the API or design is subject to dramatic change if necessary. Bugs are likely
alpha | beta | This package has a relatively certain API, but may contain bugs, and the API may change, but most changes will be small.
beta | beta | This package is approaching release, the code is stabilizing as well as the API
beta | stable | This package is in the release candidate stage, has full documentation and tests, as well as a frozen API. Bugs may still be present in the code.
stable | stable | This package is ready for use in production, has full documentation and tests, and the API can be relied upon as frozen.
Prev | Basic concepts all PEAR users should understand | Next
API (Application Program Interface) | PEAR Manual | Package version


Package version

Package version

Versioning and stability are separate entities for packages. The version of a package is a numeric string like 1.2.3 that is incremented every time a new version of the package is released. The stability of a package determines how likely the package is to contain bugs or to have changes to its API.

In addition, PEAR makes a distinction between the API version and the package version.

Versioning guidelines

There are a few conventions that should be followed when deciding which version number or stability to use for your package. Version numbers should always contain three decimals such as 1.2.3. This is because of the way that PHP's version_compare() function calculates the difference between versions:

<?php
 var_dump(version_compare("1.0", "1.0.0")); // int(-1)
 ?>

The example above shows that in fact version 1.0 is considered to be a different version from version 1.0.0, a distinction that is confusing at best for users. Use of 3 decimals for every version will ensure that both your users and PHP will not be confused by which of two versions is the same or newer.

Package versions can be abstractly referred to as X.Y.Z. For version 1.2.3, X is 1, Y is 2 and Z is 3.

Generally speaking, it is best if X is used to refer to major API changes, sweeping addition of new features, or any break of backwards compatibility. The Y component should be reserved for small to large feature additions, but should never be used for breaks of backwards compatibility. The Z component should only be used for bugfixes.

These three questions can be used to determine how to increase the version number:

  1. Breaking backwards compatibility? Yes = increment X, set Y = Z = 0

  2. Adding new features? Yes = increment Y, set Z = 0

  3. Fixing bugs? Yes = increment Z

Here is a typical life cycle for a package:

A version life cycle for a package
Release Notes | Release Stability | API Stability | Release Version | API Version
Initial release | devel or alpha | devel or alpha | 0.1.0 | 0.1.0
Bugs fixed | devel or alpha | devel or alpha | 0.1.1 | 0.1.0
More bugs fixed | devel or alpha | devel or alpha | 0.1.2 | 0.1.0
API changed, more bugs fixed | devel or alpha | devel or alpha | 0.2.0 | 0.2.0
API changed, more bugs fixed | devel or alpha | devel or alpha | 0.3.0 | 0.3.0
API changed, documentation started, tests expanding | alpha | alpha | 0.4.0 | 0.4.0
API stabilizing, documentation nearly finished, tests expanding | alpha | beta | 0.5.0 | 0.4.1
API stabilizing, code stabilizing, documentation nearly finished, tests expanding | beta | beta | 0.5.1 | 0.4.1
API problem fixed, code stabilizing, documentation nearly finished, tests expanding | beta | beta | 0.6.0 | 0.5.0
API stabilized, code stabilizing, documentation nearly finished, tests expanding | beta | stable | 0.6.1 | 1.0.0
API stabilized, code stabilizing, documentation finished, tests expanding | beta | stable | 1.0.0RC1 | 1.0.0
API stabilized, code stabilizing, documentation finished, tests full coverage | beta | stable | 1.0.0RC2 | 1.0.0
code ready for use in production | stable | stable | 1.0.0 | 1.0.0
bugs fixed | stable | stable | 1.0.1 | 1.0.0
bugs fixed | stable | stable | 1.0.2 | 1.0.0
new features added, bugs fixed | stable | stable | 1.1.0 | 1.1.0
bugs fixed, package enters maintenance mode to develop next generation | stable | stable | 1.1.1 | 1.1.0

Note that the PEAR coding standards require packages to be renamed when they break backwards compatibility. Thus, a PEAR package can never reach version 2.0.0.

Prev | Basic concepts all PEAR users should understand | Next
Package stability | PEAR Manual | Abstract Package Name (for install/uninstall command)


Abstract Package Name (for install/uninstall command)

Abstract Package Name (for install/uninstall command)

There are several different ways of referring to a package that Pyrus and the PEAR Installer understand. Three ways are concrete, in that they refer to deterministic entities such as a package.xml file on disk, or a URI (Uniform Resource Identifier) such as http://pear.php.ne/get/PEAR-1.8.1.tgz that refers to a file on a remote server.

Ways of specifying a package for installation
Package type | Local/Remote | Example
package.xml file | Local | php pyrus.phar install /path/to/package.xml
Package release archive | Local | php pyrus.phar install /path/to/PackageName-1.2.3.tgz
Static url | Remote | php pyrus.phar install http://example.com/PackageName-1.2.3.tgz
Abstract package | Remote | php pyrus.phar install PackageName

The first three ways of specifying a package are concrete: the package name always refers to one and only one package. Abstract packages are more flexible, and there are several ways of requesting a package. Note that if the channel is not explicitly requested (as it is in the last example), Pyrus or the PEAR Installer prepends the default channel. The default channel is set by the default_channel configuration variable, and is set to one of pear.php.net (pear command), pecl.php.net (pecl command), or pear2.php.net (Pyrus) unless explicitly changed by a call to the config-set (pear/pecl command) or set (pyrus) command. A request for PackageName will be interpreted by the PEAR Installer or Pyrus to be a request for package PackageName from the default channel, as if the user had requested pear.php.net/PackageName (pear command), pecl.php.net/PackageName (pecl command) or pear2.php.net/PackageName (pyrus).

Ways of specifying an abstract package
Example | Description
PackageName-1.2.3 This forces Pyrus to download version 1.2.3 of package PackageName, but will will attempt to download a release in one of the following file formats, in this order:

  1. phar

  2. tgz (only if zlib extension is enabled)

  3. tar

  4. zip
PackageName-alpha This causes Pyrus to download the latest version of package PackageName that is alpha stability or better (the hierarchy of stabilities is devel, alpha, beta, stable). After finding a matching version, it will attempt to download a release in one of the following file formats, in this order:

  1. phar

  2. tgz (only if zlib extension is enabled)

  3. tar

  4. zip
PackageName This causes Pyrus to download the latest version of package PackageName that is preferred_state (configuration variable) stability or better (the hierarchy of stabilities is devel, alpha, beta, stable). After finding a matching version, it will attempt to download a release in one of the following file formats, in this order:

  1. phar

  2. tgz (only if zlib extension is enabled)

  3. tar

  4. zip

The preferred_state configuration variable can be seen with the config-show command.
PackageName#groupname | This causes Pyrus to download and install a release of Pyrus as specified above, and it also causes Pyrus to download and install the contents of the groupname dependency group (dependency groups are documented here). Note that PackageName in PackageName#groupname can be any of the above examples, such as PackageName-1.2.3#groupname.
channelname/PackageName | This causes Pyrus to download and install a release of PackageName from the channel channelname. Another syntax that can be used is channel://channelname/PackageName which is useful if there is a sub-directory of the current working directory named channelname and a file or directory within it named PackageName. Note that in the example above, PackageName can be any of the previous syntaces such as channelname/PackageName-1.2.3#groupname.

Abstract Package for installed packages

Note that the uninstall, run-scripts, and other commands that operate on installed packages only support a simple package name as in PackageName or channelname/PackageName. Any fancy stuff like pear2.php.net/PackageName-1.2.3#group is ignored.

Prev | Basic concepts all PEAR users should understand | Next
Package version | PEAR Manual | PEAR Channels


PEAR Channels

PEAR Channels

A PEAR Channel is a web site that distributes package archives for remote installation by users of Pyrus or the PEAR Installer. In addition to providing the package archives for download, a PEAR Channel must also provide some meta-information that the installer can use to locate the package releases and determine which is the best release to download.

Channels have a file that defines the capabilities of the channel named channel.xml located in its document root (for instance, pear.php.net's channel.xml) and some meta-information in REST format.

A channel can also provide a public frontend for users to browse the contents of the channel online, such as PEAR's public frontend.

Prev | Basic concepts all PEAR users should understand | Next
Abstract Package Name (for install/uninstall command) | PEAR Manual | File roles


File roles

File roles

Pyrus and The PEAR Installer categorize file types by their role. A file role is equivalent to the web's concept of MIME type, a concept that allows web browsers to determine how a file should be displayed or processed. A file role allows Pyrus and the PEAR Installer to determine where a file should be installed, the conditions under which the role can be used, and even whether the file should be installed at all. A file may only have one role in a package.

Generally speaking, each file role has its own installation location. For example, php files (files whose file role is php) are installed into the location specified by the php_dir configuration variable, data files (files whose file role is data) are installed into the location specified by the data_dir configuration variable. Some file roles do not have a direct mapping of role name to configuration variable, such as Pyrus's customcommand file role. This file role is installed into the location specified by the data_dir configuration variable.

File roles also control how package.xml attributes are handled. The php file role installs files into the exact relative path as specified in package.xml. The data file role always installs files into a subdirectory containing the package name for PEAR packages, and both the channel and package name for packages designed to be installed by Pyrus.

Here is an example of the same file path in package.mxl as php role and as data role. All examples assume this is a package named PackageName in the pear2.php.net channel.

  <contents>
   <dir name="\">
    <dir name="base">
     <file name="foo" role="php">
    </dir>
   </dir>
  </contents>

This installs as base/foo in the location specified by php_dir.

  <contents>
   <dir name="\">
    <dir name="base">
     <file name="foo" role="data">
    </dir>
   </dir>
  </contents>

For PEAR Installer packages, this installs as PackageName/base/foo in the location specified by php_dir. For Pyrus packages, this installs as pear2.php.net/PackageName/base/foo.

How the baseinstalldir attribute is handled by different file roles

The baseinstalldir (base installation directory) attribute is a tool that can be used to install a file into a different directory than its location in the source repository.

As an example, the path in the subversion repository to the file PEAR2\Foo.php is at Foo.php. To inform the installer to install this package into the PEAR2 directory, we would use a baseinstalldir attribute:

   <contents>
    <dir name="\">
     <file name="Foo.php" role="php" baseinstalldir="PEAR2">
    </dir>
   </contents>

The attribute can also be used on <dir> tags to apply the base installation directory to all files within the directory:

   <contents>
    <dir name="\" baseinstalldir="PEAR2">
     <file name="Foo.php" role="php">
    </dir>
   </contents>

The baseinstalldir role can also be used to inform the PEAR Installer or Pyrus to strip all relative paths by using / as the base installation directory. Here is an example from the PEAR package:

   <dir name="scripts" baseinstalldir="/">
    <file name="pear.bat" role="script"/>

This file would be installed as scripts/pear.bat, but the baseinstalldir attribute of / informs the installer to instead install it to pear.bat.

Each file role reacts differently to the baseinstalldir attribute. Packages designed to be installed by the PEAR Installer also handle them differently from packages designed for installation by Pyrus. The php, script and www file roles react the same way as documented above. In packages designed for the PEAR Installer, the other file roles do not honor the baseinstalldir attribute, meaning they ignore it. For example:

   <contents>
    <dir name="\" baseinstalldir="PEAR2">
     <file name="Foo.dat" role="data">
    </dir>
   </contents>

installs Foo.dat into the PackageName/Foo.dat directory. The same XML in a package designed for installation by Pyrus will install the file into pear2.php.net/PackageName/PEAR2/Foo.dat.

Prev | Basic concepts all PEAR users should understand | Next
PEAR Channels | PEAR Manual | File tasks


File tasks

File tasks

Pyrus allows special handling of files through tasks. File tasks can perform any action necessary both when installing a package and when creating a package. Both Pyrus and the PEAR Installer ship with 4 built-in tasks, replace, windowseol, unixeol, and postinstallscript.

The built-in tasks are documented here. The documentation also describes how to create custom tasks for the PEAR Installer. Custom tasks for Pyrus are documented here.

Tasks are specifically designed to allow customization of an installation, and particularly modification of a specific file's contents. The unixeol task, for instance, transforms line endings to UNIX \n and is useful for shell scripts that must have the proper line endings. The replace task can be used to update the version of a package directly in the source code, or to automatically set up the path to a PEAR Installation in a shell script.

Tasks are defined using the XML namespace http://pear.php.net/dtd/tasks-1.0. Most often, this is declared using tasks as the namespace prefix, as in xmlns:tasks="http://pear.php.net/dtd/tasks-1.0". More than one task can be used for a single file, as shown by this example from the PEAR package:

    <file name="pearcmd.php" role="php">
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
     <tasks:replace from="@pear_version@" to="version" type="package-info" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
    </file>
Prev | Basic concepts all PEAR users should understand | Next
File roles | PEAR Manual | Installation (Pyrus)


Installation (Pyrus)

Installation (Pyrus)

Table of Contents
  • Introduction: it's simple

Edited By

Gregory Beaver

2009-06-17

This chapter describes how to install Pyrus, the package manager for PEAR2 and PHP 5.3+.

Prev | User Guide | Next
File tasks | PEAR Manual | Introduction: it's simple


Introduction: it's simple

Introduction: it's simple

Installing Pyrus is much simpler than installing PEAR. Installing PEAR requires downloading a separate installation and installing PEAR before you can use it to install any packages.

To install pyrus, you must follow two simple steps:

  1. Install PHP 5.3.0 or newer. Pyrus needs the phar, simplexml, libxml2, spl and pcre extensions in order to work. Fortunately, these are all enabled by default in PHP 5.3.

  2. download pyrus.phar from the pear2.php.net website front page

That's it, pyrus has no external dependencies. Using Pyrus is also simple, one simply passes it to the command-line interface (CLI) like so:

php pyrus.phar install packagename

The first time pyrus is run on your system, it will ask where you would like to install packages. After this, one can simply use it.

To match PEAR, it is also possible to create a convenience script for accessing pyrus. Here is a sample script for unix systems:

#!/bin/bash
/usr/local/bin/php -dphar.readonly=0 /home/username/pyrus.phar $*

If your system has open_basedir enabled, the script should instead look like:

#!/bin/bash
/usr/local/bin/php -dphar.readonly=0 -dopen_basedir= -dsafe_mode= /home/username/pyrus.phar $*

Windows users can create a batch file similar to the unix script named pyrus.bat:

@ECHO OFF
C:\php5\php -dphar.readonly=0 -dopen_basedir= -dsafe_mode= C:\php5\pyrus.phar %*

Place the shell script (on unix) or batch file (on windows) in your path, and then you can run commands like so:

pyrus install packagename

Prev | Installation (Pyrus) | Next
Installation (Pyrus) | PEAR Manual | Installation (PEAR)


Installation (PEAR)

Installation (PEAR)

Table of Contents
  • Introduction
  • Getting and installing the PEAR package manager
  • Installation of a local PEAR copy on a shared host
  • Checking if PEAR works

Edited By

Martin Jansen

2006-11-25

This chapter describes how to install the PEAR package manager.

Prev | User Guide | Next
Introduction: it's simple | PEAR Manual | Introduction


Introduction

Introduction

Before you install PEAR, we recommend you understand what PEAR is and why you should install it.

The base installation that comes with the PHP distribution contains all the stuff that is needed to run the PEAR installation tools etc. If you have a recent installation of PHP, you can relax: The PEAR base installation is already there - unless you have compiled your PHP with the ./configure flag --without-pear.

The packages that do not come with PHP can be installed with the PEAR package manager. The manager handles installation similar to Debian's "apt-get" package management utility, as well as others such as "yum". Again: If you are running a recent version of PHP (> 4.3.0) you can skip the next section. But if you are running PHP 4.2.* or earlier, you need to manually install the manager.

Apart from installing packages, the PEAR package manager also handles some other tasks: It can create new packages on your machine, manage a registry of installed packages, check dependencies and it can interact with services on pear.php.net, and other PEAR compatible channel servers to get information about available packages.

Prev | Installation (PEAR) | Next
Installation (PEAR) | PEAR Manual | Getting and installing the PEAR package manager


Getting and installing the PEAR package manager

Getting and installing the PEAR package manager

Windows

After you have downloaded and installed PHP, you have to manually execute the batch file located in e.g. c:\php\go-pear.bat. The setup will ask you some questions and afterwards the PEAR Package Manager will be installed in the path, which you have specified during installation.

Finally you have to add that installation path to your PATH environment. Either do this manually (Start > Control Panel > System > Environment) or run (double-click) the newly generated PEAR_ENV.reg that's now found in the PHP source directory.

After that you can access the PEAR Package Manager by running the command pear in a Windows Command Prompt.

To update your PEAR installation, request http://pear.php.net/go-pear in your browser and save the output to a local file go-pear.php. You can then run

php go-pear.php

in a Windows Command Prompt to start the update process.

Note: After changing php.ini , you need to restart your web server.

Now check that PEAR works.

Unix/Linux/BSD

When using PHP >= 4.3.0, the PEAR Package Manager is already installed unless one has used the ./configure option --without-pear.

If one uses a version of PHP that is supplied by Unix/Linux/BSD distributors it may be necessary to manually install PEAR. Users should consult the documentation for the respective distribution in this case.

For all versions prior to 4.3.0 or if you want to re-install the Package Manager, you can use the following provisional way:

$ lynx -source http://pear.php.net/go-pear | php
Note: Some Linux distributions (e.g. Redhat) seem to be using links instead of lynx as the name for their command line browser. If this is the case for you, you need to change the above line correspondingly.
Note: You can also save http://pear.php.net/go-pear as go-pear.php and run it with:

php go-pear.php

Now check that PEAR works.

Mac OS X

On Mac OS 10.4 and earlier, the PEAR Package Manager is already installed in /usr/bin/pear.

If you are using Mac OS 10.5 (Leopard), would like to install a new copy, or re-install the PEAR Package Manager use the following command:

$ curl http://pear.php.net/go-pear | sudo php
Note: You can also save http://pear.php.net/go-pear as go-pear.php and run it with:

php go-pear.php

Now check that PEAR works.

PEAR in hosting environments

If you are running your site at a web hosting provider with no direct access to the server (via local logins, Telnet or SSH), you can use the PEAR Installer using the Web Frontend or (S)FTP.

Go to http://pear.php.net/go-pear and save as go-pear.php. Copy go-pear.php to your server and open the corresponding URL in your browser, for example http://example.com/pear/go-pear.php.

Do not forget to protect the pear directory if you did not do already before the installation: Make it unreadable and not executable from external (i.e. put it outside public_html).

Now check that PEAR works.

Prev | Installation (PEAR) | Next
Introduction | PEAR Manual | Installation of a local PEAR copy on a shared host


Installation of a local PEAR copy on a shared host

Installation of a local PEAR copy on a shared host

Many users have a shared provider that grants access to a system-wide PEAR installation. However, in many cases, it is advantageous to have a local copy of PEAR that can be used for packages that are not installed by the host provider. There are ways of installing PEAR both for users with a telnet/ssh shell access and users who only have ftp access.

Installing a local copy of PEAR through SSH

To install PEAR through SSH, you can use this command sequence to set up a local copy of PEAR:

The following instructions are for PEAR 1.4+, older pear installations should be upgraded immediately.

$ pear config-create /home/user/pear .pearrc

This will create a local configuration file in a file in your home directory named .pearrc.

Then, if you add ~/pear/bin to your path as the first entry in .bashrc (or whatever your startup file is), and run the command:

$ pear install -o PEAR

This will create a directory structure based on a subdirectory of your home directory named pear that contains all of the packages that you install. You will have a local version of PEAR that supersedes the system's copy. To use the files you have installed, you should set your PHP include_path in either the code that uses your PEAR packages like so:

<?php
ini_set('include_path', '~/pear/lib' . PATH_SEPARATOR
        . ini_get('include_path'));

// From PHP 4.3.0 onward, you can use the following,
// which especially useful on shared hosts:
set_include_path('~/pear/lib' . PATH_SEPARATOR
                 . get_include_path());
?>

Or, in an .htaccess file for apache using php_value.

Installing a local copy of PEAR through ftp/ftps/sftp

There are two ways to install a local copy of PEAR through ftp: the old, difficult way, and the new, easy way. The new, easy way requires an upgrade to version 1.4.3 or newer of PEAR.

New improved method using PEAR 1.4.3+ and PEAR_RemoteInstaller

Installing a local copy of PEAR through ftp has become a piece of cake in PEAR 1.4.3+.

One of the banes of many user's existence is trying to install PEAR on a remote host that does not have shell access. Often, the only choice is to use FTP, but even this is a problem for more complex packages that take advantage of installer features like replacements.

Here is the sequence necessary to get things running:

  1. Make sure you are running PHP 5.0 or newer on your local computer

  2. If you wish to use ftps, make sure you have enabled the openssl extension on your local computer in php.ini.

  3. If you wish to use sftp, make sure you have enabled the ssh2 extension on your local computer in php.ini.

  4. Make sure you have a working copy of the CLI version of PEAR on your local computer (the "pear" command, not the web interface)

  5. Make sure you have ftp access to the remote host, and write access through ftp. (sftp or ftps is highly recommended for security reasons).

  6. Note the full path to your home directory

  7. Create a customized configuration file for both the local and remote host

  8. Upload the remote configuration file to the remote host

  9. Using the local configuration file, set the remote_config value to the location of the configuration file on the remote host

  10. Manage packages at will using the remote-install, remote-uninstall, remote-upgrade and remote-upgrade-all commands.

1. Make sure you have a working copy of the CLI version of PEAR (the "pear" command, not the web interface)

Read The installation instructions.

2. Install package PEAR_RemoteInstaller locally if not already done.

3. Make sure you have ftp access to the remote host, and write access through ftp

This is pretty straightforward - if you can login using the ftp command in a DOS prompt or from a unix shell, you have ftp access.

Write down the user and password that you need to login.

Testing write access is easy. If you can upload a file, you have write access.

4. Note the full path to your home directory

This is also pretty straightforward. Upload this script to the root directory of your web host to find out:

<?php
echo dirname(__FILE__);
?>

Chances are, it will be something like: /home/username/htdocs or /home/username/public_html. When you log into ftp, if you can change directory to /home/username, that's great.

5. create a customized config file for both the local and the remote host

This is also quite simple. Here is how to do this on windows and unix.

Windows first:

Pick a location to store your local copy of the remote code. For example, C:\remote\pear. From a Command prompt (click Start here => Programs and search for the Command Prompt), type:

C:\> mkdir remote
C:\> cd remote
C:\remote\> mkdir pear
C:\remote\> cd pear
C:\remote\pear> pear config-create -w C:\remote\pear remote.ini
C:\remote\pear> pear config-create /home/username/pear .pearrc

In Unix, follow a similar process:

$ cd
$ mkdir remote
$ cd remote
$ mkdir pear
$ cd pear
$ pear config-create /home/mylocaluser remote.conf
$ pear config-create /home/username/pear .pearrc

6. upload the remote configuration file to the remote host

This is straightforward - in both operating systems, use ftp to upload .pearrc to /home/username/pear/.pearrc

7. using the local configuration file, set the remote_config value to the location of the configuration file on the remote host

If you wish to use unencrypted ftp (remember: this is inherently insecure), then use ftp:// as your stream. If you wish to use ftps, then use ftps:// as your stream. If you wish to use sftp, then use ssh2.sftp as your stream.

The path you use for the remote_config variable may need to be a full pathname, as in:

ssh2.sftp://user:pass@myremotehost.com/home/username/.pearrc

If the initial connection attempt fails, try a relative path as in:

ftps://user:pass@myremotehost.com/.pearrc

To set the value of the remote_config configuration variable, use this syntax:

In windows:

C:\remote\pear\> pear -c remote.ini config-set remote_config \
    ftp://user:pass@myremotehost.com/.pearrc

In Unix:

$ pear -c remote.conf config-set remote_config \
    ftp://user:pass@myremotehost.com/.pearrc

8. Manage packages at will using the remote-install, remote-uninstall, remote-upgrade and remote-upgrade-all commands.

From this point on, you can synchronize the local and the remote repositories.

How does it work?

The installer installs the package locally, and then uses ftp streams and uploads a copy of each locally installed file to its equivalent location remotely. All commands that affect installation (install, uninstall, upgrade, and upgrade-all) have corresponding remote- commands (remote-install, remote-uninstall, remote-upgrade, remote-upgrade-all). The "remote_config" option tells the installer how to retrieve the remote configuration file containing absolute paths where packages should be installed.

The remote configuration file is used for any special tasks such as replacements. In other words, if a file expects to get the path to data files through the data_dir configuration directive, then it will have the path on the remote host (/home/username/pear/data) rather than the local copy ( C:\remote\pear\data). Note that packages installed this way will not work on the local machine, and should be thought of as a backup copy. In an emergency, you can always just upload the entire contents to the remote host using ftp or scp.

It is important to note that some packages install themselves differently on windows and on unix. Be sure you know whether this is the case before installing, or ensure that your local and remote systems are the same kind of operating system. In addition, your local packages may depend on PHP extensions. To ensure these are available on the remote server, use the output of phpinfo(); to determine which extensions are available.

The traditional way of installing a local copy of PEAR through ftp

In order to install a local copy of PEAR through ftp, you must have an ftp client that can set permissions on upload. First, create a directory that is NOT in your publicly accessible web space, and name it anything you'd like. Set it to be readable and writable by any user (permissions 0777). Then, download a copy of http://pear.php.net/go-pear and save it as go-pear.php. Upload go-pear.php to a subdirectory of your publicly accessible web space. It is a very good idea to password-protect the directory containing go-pear.php with an .htaccess file.

Next, browse to the go-pear.php file. If your web address is http://www.example.com/, you have placed go-pear.php in public_html/install/go-pear.php, and http://www.example.com/ will browse to public_html/, then browse to http://www.example.com/install/go-pear.php. Follow the installation prompts. When asked where to install PEAR, choose the directory you created to be readable and writable by any user. You will need to know the location of the cli version of PHP. To find this, browse to this script and copy the output:

<?php
echo `which php`;
// if this does not work, also try echo PHP_BIN;
?>

After PEAR has been installed, you can use the web installer to install and upgrade packages just as you would with any other PEAR installation. To use the files, you must set the include path in scripts on the website.

<?php
ini_set('include_path', '~/pear/lib' . PATH_SEPARATOR
        . ini_get('include_path'));

// From PHP 4.3.0 onward, you can use the following,
// which especially useful on shared hosts:
set_include_path('~/pear/lib' . PATH_SEPARATOR
                 . get_include_path());
?>
Prev | Installation (PEAR) | Next
Getting and installing the PEAR package manager | PEAR Manual | Checking if PEAR works


Checking if PEAR works

Checking if PEAR works

Verifying command line tool

Both pear and pecl tools should be available everywhere on command line. For that to work, pear's binary (bin) directory should be in your PATH variable.

To verify it works, simply type pear. A list of commands should be shown:

$ pear
Commands:
build                  Build an Extension From C Source
bundle                 Unpacks a Pecl Package
channel-add            Add a Channel
...

You should further test that PEAR is up to date:

$ pear version
PEAR Version: 1.7.2
PHP Version: 5.2.6RC4-pl0-gentoo
Zend Engine Version: 2.2.0
Running on: Linux ...

Verifying the include path

To use PEAR and PEAR compatible packages in your applications, you normally include them into your PHP scripts using require_once(). For this to work, PEAR's php_dir must be a part of PHP's include path.

  1. First, check where PEAR installs .php files:

    $ pear config-get php_dir
    /usr/share/lib/php/

    This directory will contain System.php.

  2. Now it's time to find which configuration file is used by your PHP installation. On command line, execute:

    $ php --ini
    Configuration File (php.ini) Path: /etc/php/cli-php5
    Loaded Configuration File:         /etc/php/cli-php5/php.ini
    Scan for additional .ini files in: /etc/php/cli-php5/ext-active
    Additional .ini files parsed:      /etc/php/cli-php5/ext-active/php_gtk2.ini,
    /etc/php/cli-php5/ext-active/xdebug.ini

    To see which php.ini is used by PHP on your web server, create a file with only <?php phpinfo(); ?> as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to find the path to the php.ini file your web server is using.

  3. Now check PHP's include_path setting on command line:

    $ php -c /path/to/php.ini -r 'echo get_include_path()."\n";'

    To check PHP's include_path in your web server, create a file with only <?php phpinfo(); ?> as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to verify the include_path your web server is using.

    In every case, PEAR's php_dir should be in the include path. If not, add it in your system's php.ini.

  4. Now that this is done, try including a file. Create a new check_pear.php file with the following contents:

    <?php
    require_once 'System.php';
    var_dump(class_exists('System'));
    ?>

    System.php is shipped with every PEAR installation and thus should be on your computer, too. Open the file with the browser from your web server, and also try it on command line. The only output should be

    bool(true)

    A message like:

    Warning: require_once(System.php): failed to open stream:
     No such file or directory in /path/to/check_pear.php on line 2

    means that your include path is not correct. (So go and fix it!)

    A completely white page in your browser hints two things:

    • Your server is configured to not display any errors to the user/browser (display_errors Off)

    • There was an error including System.php, and you should check you server's error log.

That's it! Now go on and install some packages.

Things that could be in your way

  • After changing php.ini, you need to restart your web server.

    Few people also reported they had to restart the whole machine physically, probably due to PATH changes not propagating correctly. Before wasting hours and after you tried everything else, just try that.

  • Newer Linux distributions use multiple php.ini files; mostly one for the web server (e.g. /etc/php/apache2-php5/) and one for command line (like /etc/php/cli-php5/). Make sure you edit the right ones.

  • On Windows, recent versions of PHP use php.ini from their own directory (where php.exe is). You still might have an old php.ini in your windows or system(32) directory that fools you.

  • You cannot get away with using absolute paths in your own require_once() statements as an altervative to fixing your include_path, because all the other files that are then required by your scripts are all coded for relative pathing based on include_path.

Modifying php.ini

To get PEAR working properly, you need to adjust PHP's include_path. After you found php.ini, open it in an editor.

Search for the line include_path.

Now that you found it, you probably will see a semicolon ; at the beginning. This means the line is a comment. Add a new line below it.

In this line, write:

include_path="."

Depending on your operating system, add a : (Unix/Linux/FreeBSD/Mac OS X) or a ; (Windows) after the dot. Add PEAR's php_dir after it. (The directory System.php is located in!)

The result should look like that:

; Unix
include_path=".:/usr/local/php/pear/"

or

; Windows
include_path=".;C:\php\pear\"
Prev | Installation (PEAR) | Next
Installation of a local PEAR copy on a shared host | PEAR Manual | Command line installer (PEAR)


Command line installer (PEAR)

Command line installer (PEAR)

Table of Contents
  • Before you begin
  • Configuring your PEAR setup
  • Installing packages
  • Getting information about packages
  • Using channels
  • Command list
Prerequisites

The following description requires the latest version of the PEAR package manager to be installed.

This chapter shows you how to use the PEAR command line installer.

Prev | User Guide | Next
Checking if PEAR works | PEAR Manual | Before you begin


Before you begin

Before you begin

Always remember that PEAR has a help command:

$ pear help

.. list of commands follows ..
Note: Command examples will have a dollar sign $ before each line that is typed. This helps to distinguish input from the output of the PEAR installer.
Note: $ is just an example for a command prompt. Depending on your distribution or personal preferences, your shell might display a username, often combined with the current path: joe:~/some/path>

Help for a command is just as easy to get:

$ pear help <command>

$ pear help install

.. help for install follows ..
Prev | Command line installer (PEAR) | Next
Command line installer (PEAR) | PEAR Manual | Configuring your PEAR setup


Configuring your PEAR setup

Configuring your PEAR setup

PEAR has a number of configuration options that you can change. Getting an overview about them is as easy as issuing a

$ pear config-show

The default settings suffice for novice users, there is rarely a need to change them when getting started. You can go on with installing packages.

Reading single values is accomplished by using config-get. The following command will show you where all the .php files of your installed pear packages reside.

$ pear config-get php_dir

/usr/share/pear

Changing a value is as easy as retrieving it:

$ pear config-set preferred_state beta

config-set succeeded
Note: When changing a config setting, it does not immediately get applied to already installed packages. This is especially true when changing variables like data_dir. Use $ pear upgrade --force to reinstall all packages in such cases.

Config options

Variable Name | Description | Default Value
bin_dir | Directory where executables are installed | /usr/bin
doc_dir | Directory where documentation is installed | /usr/lib/php/docs
ext_dir | Directory where loadable extensions are installed | ./
php_dir | Directory where PHP files are installed (like PEAR files) | /usr/lib/php
cache_dir | PEAR installer cache directory, and used by XMLRPC | /tmp/pear/cache
data_dir | Directory where data files are installed | /usr/lib/php/data
php_bin | The PHP CLI or CGI binary for executing scripts | /usr/bin/php
test_dir | Directory where regression tests are installed | /usr/lib/php/tests
cache_ttk | Number of seconds that the local cache is used, and not updated (Time To Kill) | 3600
preferred_state | Preferred package state: stable, beta, alpha, devel, or snapshot | stable
umask | umask used when creating files (Unix-like systems only) | 22
verbose | Debug log level: 0-3 where 3 is full debug mode. | 1
http_proxy | The optional HTTP proxy address (host:port) used when downloading packages |
remote_config | Remote configuration file, used to mirror a local installation on a remote server through ftp. (PEAR 1.4+) |
auto_discover | Auto-discover new channels from command line or dependencies | 0
default_channel | Default channel (PEAR 1.4+) | pear.php.net (pecl.php.net if using the pecl command)
preferred_mirror | Preferred channel mirror (PEAR 1.4+) | pear.php.net (pecl.php.net if using the pecl command)
master_server | PEAR server [deprecated in PEAR 1.4+] | pear.php.net
password | PEAR password (used by maintainers) |
sig_bin | Signature handling program | /sw/bin/gpg
sig_keydir | Signature key directory | /etc/pearkeys
sig_keyid | The key used for signing |
sig_type | Package signature type (only gpg) | gpg
username | PEAR username (used by maintainers) |
Prev | Command line installer (PEAR) | Next
Before you begin | PEAR Manual | Installing packages


Installing packages

Installing packages

After getting PEAR working on your machine (see Installation) you most likely want to install some packages. This guide shows people new to the PEAR command line installer how to get started.

Normal installation procedure

The general command to install a PEAR package named "foo" is

$ pear install foo

Typing this and pressing return, the package will be downloaded and installed on your computer. It does not matter if you write the package name in lowercase, UPPERCASE or MixedCase - the installer will find the package by lowercasing the name.

When a package is already installed, you will get the following message:

$ pear install foo

Ignoring installed package pear/foo

Nothing to install

This happens even if there is a newer version of the package! The correct command to upgrade to the lastest version is

$ pear upgrade foo

upgrade ok: channel://pear.php.net/Foo-1.2.3

If the package already has the lastest version, you will get a message similar to the following:

Ignoring installed package pear/Foo

Nothing to upgrade

In the case you deleted some file and really really want to re-install the package, you have two choices:

  • Uninstall the package, and reinstall it afterwards

  • Force the installation

Forcing an command should only be done when you absolutely know what you are doing - you might in some circumstances break PEAR otherwise. Forcing something should always be the last option.

$ pear install -f foo

$ pear upgrade -f foo

Unstable alpha/beta packages

Now and then, you will get error messages like

Failed to download pear/foo within preferred state "stable",

 latest release is version 0.1.2, stability "beta",

 use "channel://pear.php.net/foo-0.1.2" to install

Cannot initialize 'channel://pear.php.net/foo', invalid or missing package file

Package "channel://pear.php.net/foo" is not valid

install failed

Reason for this is that PEAR by default installs stable packages only. When a package is in state devel, alpha or beta it will refuse to install them. You can easily persuade it by adding either the version number or the stability you are willing to accept:

$ pear install Foo-beta

$ pear install Foo-alpha

You can also install a specific version, or upgrade to a specific version regardless of the state:

$ pear install Foo-1.2.3

$ pear upgrade Foo-1.2.3

Living on the edge

If you don't care about stability and don't want to specify the -alpha or -beta suffix everytime, you can change the global stability config option:

$ pear config-set preferred_state alpha

config-set succeeded

You can switch between the following stability states (sorted by stability):

  • stable

  • beta

  • alpha

  • devel

Dependencies

A package often requires other packages to be installed to function correctly. Such a relation is called a dependency. The PEAR installer has full support for dependencies; it can automatically install required and/or optional dependencies if you wish so.

If you try to install a package with required dependencies, you will get an error that the installation failed. Looking deeper and actually reading the messages shows you that the package needs dependencies that are not installed on your system:

$ pear install html_page2

Did not download dependencies: pear/HTML_Common,

 use --alldeps or --onlyreqdeps to download automatically

pear/HTML_Page2 requires package "pear/HTML_Common" (version >= 1.2)

No valid packages found

install failed

You have several choices:

  • Install dependent packages by hand

  • Let PEAR automatically install necessary dependencies only

  • Let PEAR automatically install necessary and optional dependencies

The first method can be a painful and daunting process, because dependent packages itself can have dependencies.

Both other methods just require a switch to the install command, either --onlyreqdeps (install required dependencies only) or --alldeps (install all dependencies).

$ pear install --onlyreqdeps html_page2

WARNING: "pear/HTML_Common" is deprecated in favor of "pear/HTML_Common2"

downloading HTML_Page2-0.5.0beta.tgz ...

Starting to download HTML_Page2-0.5.0beta.tgz (15,467 bytes)

......done: 15,467 bytes

downloading HTML_Common-1.2.4.tgz ...

Starting to download HTML_Common-1.2.4.tgz (4,519 bytes)

...done: 4,519 bytes

install ok: channel://pear.php.net/HTML_Common-1.2.4

install ok: channel://pear.php.net/HTML_Page2-0.5.0beta

Offline installation

You can download individual packages for e.g. offline installation on a second machine just as you would install or upgrade a package:

$ pear download Foo

After downloading, you will have a file like Foo-1.2.3.tgz if the latest version of Foo was 1.2.3. Installing it is as easy as typing

$ pear install Foo-1.2.3.tgz

Manual package installation

We removed this section, because, today, manually installing a package requires a deeper understanding of the way how packages are organized and what happens during the installation process. You should read the section about the package.xml in the Developers Guide (package.xml and package.xml 2.0), if you really want install a package without the PEAR installer.

If you want to install PEAR on a remote host without shell access, you should look into Installation of a local PEAR copy on a shared host.

Installing packages from CVS

This passage will describe how to install the latest development version of a PEAR package from CVS.

It is NOT recommended to run a package from CVS in working environments! Because CVS versions are not regular releases, this means:

  • You could get no kind of help from the maintainer or anybody other.

  • Versions in CVS may break the upgrade mechanism of the PEAR Installer.

You should use a package from CVS only, if:

  • The maintainer recommended it for you.

  • You want to help in development of a package.

  • You really need a special patch or function, which is not currently released.

If you still want to install a package from CVS, you have to do the same steps like a package maintainer creating a new release of a package. If you have problems following the next steps, take a look into the Developers Section of the manual.

  1. Get the package files from CVS like described in http://www.php.net/anoncvs.php

    The name of the module to checkout is pear/<packagename>, i.e. cvs -d :pserver:cvsread@cvs.php.net:/repository checkout pear/HTTP_Client.

  2. Check the package.xml file, especially the dir and file entries. They must match the existing files and directory structure. If they differ, contact the package maintainer and ask for an update of the package.xml.

  3. Create a valid package using the PEAR Installer pear package <path to package.xml>

  4. If you have already installed the package: remove it to avoid version conflicts: pear uninstall <package>

  5. Install your package archive: pear install <package-file>

    Now, you have a CVS version installed!

You should upgrade to an official release of the package as early as possible. Before you install the official release, uninstall the CVS version to avoid version conflicts.

Installing PECL packages

The procedure of installing PECL packages is described in the pecl manual section on the PHP website.

Prev | Command line installer (PEAR) | Next
Configuring your PEAR setup | PEAR Manual | Getting information about packages


Getting information about packages

Getting information about packages

Package information

If you simply want to get to know the installed version of a package or see its description, issue an info command:

$ pear info PEAR

About pear.php.net/PEAR-1.7.1

.. more info follows ..

Package files

You often don't know which files belong to a certain installed package. list-files is helping you here. It shows you the file's role and its full path:

$ pear list-files log

Installed Files For log

=======================

Type Install Path

doc  /usr/share/pear/docs/Log/docs/guide.txt

...

php  /usr/share/pear/Log/composite.php

php  /usr/share/pear/Log/console.php

...

data /usr/share/pear/data/Log/misc/log.sql

test /usr/share/pear/tests/Log/tests/composite.phpt

...

php  /usr/share/pear/Log.php

Package examples

While we try to document each package in the manual, many packages - with or without a manual entry - come with examples. They have the file role "doc" and can be located with list-files, too:

$ pear list-files log | grep ^doc

doc  /usr/share/pear/docs/Log/docs/guide.txt

doc  /usr/share/pear/docs/Log/examples/composite.php

doc  /usr/share/pear/docs/Log/examples/console.php

doc  /usr/share/pear/docs/Log/examples/display.php

doc  /usr/share/pear/docs/Log/examples/error_log.php

doc  /usr/share/pear/docs/Log/examples/file.php

doc  /usr/share/pear/docs/Log/examples/firebug.php

...

List all packages

list shows you all installed packages with their version and stability:

$ pear list

Installed packages, channel pear.php.net:

=========================================

Package                   Version   State

Archive_Tar               1.3.2     stable

Auth                      1.5.4     stable

Cache                     1.5.4     stable

Console_Getargs           1.3.4     stable

Console_Getopt            1.2.3     stable

...

To see all available packages on the channel server, use remote-list:

$ pear remote-list

... output follows ...
Note: This command takes some time if there are many packages on the server

Search remote packages

Instead of going to the PEAR website, you can use the pear installer to search for package names.

$ pear search w3c

Retrieving data...0%.

Matched packages, channel pear.php.net:

=======================================

Package                    Stable/(Latest) Local

Services_W3C_CSSValidator  0.1.0 (alpha)         An Object Oriented Interface ...

The result list shows name, remote version and stability and the package description. Alternatively, you can use the package browser on pear.php.net.

Prev | Command line installer (PEAR) | Next
Installing packages | PEAR Manual | Using channels


Using channels

Using channels

Channels?

Channels are alternative package sources. See the channel section of the manual for more information.

What you need to know now: By using channels, you can install packages that are not part of PEAR. Prominent PHP projects like Horde and PHPUnit distribute their software through PEAR-compatible channels.

Channel discovery

Before you can use a channel, your pear installation needs to know about it. This process is called "channel discovery".

Once you know the project's channel url, just type:

$ pear channel-discover http://pear.phpunit.de

Adding Channel "pear.phpunit.de" succeeded

Downloading a channel.xml file, you can add a channel just using that file using channel-add:

$ pear channel-add my-channel.xml

...

Using list-channels, you can get an overview of known channels:

$ pear list-channels

Registered Channels:

====================

Channel                  Summary

components.ez.no         eZ Enterprise components

demochanserv.bogo        Simple demo channel server

gnope.org                PHP-Gtk2 applications

pear.chiaraquartet.net   Chiara Testing Channel

pear.phing.info          Channel for Phing build tool releases

pear.php.net             PHP Extension and Application Repository

pear.phpunit.de          PHPUnit channel server

pear.symfony-project.com symfony project PEAR channel

pearified.com            PEAR-Compatible Extension and Application

                         Repository

pecl.php.net             PHP Extension Community Library

__uri                    Pseudo-channel for static packages

More insight about a channel can be gotten with channel-info. It prints out a description, the channel's shortcut name (alias) as well as mirror information.

$ pear channel-info pear.php.net

Channel pear.php.net Information:

=================================

Name and Server         pear.php.net

Alias                   pear

Summary                 PHP Extension and Application Repository

...

Work with packages on a channel

When installing or doing anything else with a package that is not in your default channel, you need to specify the channel by full name or alias:

$ pear install gnope/Dev_Inspector

... installation of package "Dev_Inspector" in channel "gnope"

$ pear list -c pear.phpunit.de

Installed packages, channel pear.phpunit.de:

============================================

Package Version State

PHPUnit 3.2.5   stable

General rule is that when you would specify a package name, use $channel/$packagename now. All other functions with channel support have a -c option to specify the channel name or alias.

Password protected channels

PEAR compatible channels can be password protected. You could use this to e.g. distribute custom proprietary software to your clients, and don't want to publicy publish those packages anywhere.

Password protection is done via a HTTP Basic Authentication (.htaccess and .htpassword on Apache). When trying to discover such a password protected channel, you will get a message like this:

$ pear channel-discover pear.company.com

Discovery of channel "pear.company.com" failed

 (channel-add: Cannot open "http://pear.company.com/channel.xml"

 (File http://pear.company.com:80/channel.xml not valid

 (received: HTTP/1.1 401 Authorization Required

)))

In this case, download the channel.xml file manually, for example with your browser or wget. A channel.xml is always in the root directory of the channel server. After that, discover the channel with the saved file:

$ pear channel-add /path/to/saved/channel.xml

Adding Channel "pear.company.com" succeeded

Now the PEAR manager needs to know about the channel's username and password. We tell him by using set-config in connection with the channel option:

$ pear config-set -c pear.company.com username johndoe

config-set succeeded

$ pear config-set -c pear.company.com password secret

config-set succeeded

Now test if we did everything right by showing available packages on the channel:

$ pear list-all -c pear.company.com

Retrieving data...0%

All packages [Channel pear.company.com]:

==========================

Package             Latest Local

comp/WorldDominator 0.8.1        Tool to dominate the world
Note: If you changed your creditentials, you should issue a pear clear-cache command to make sure that the installer does not use cached data.
Prev | Command line installer (PEAR) | Next
Getting information about packages | PEAR Manual | Command list


Command list

Command list

Here's a list of commands available to the pear command line tool. Many of these commands may require root access to the server.

Command | Description
build | Build the extension from source
bundle | Download and unpack a PECL extension
channel-add | Add a Channel (PEAR 1.4+)
channel-alias | Specify an alias to a channel name (PEAR 1.4+)
channel-delete | Remove a channel from the list (PEAR 1.4+)
channel-discover | Initialize a channel from its server name (PEAR 1.4+)
channel-info | Retrieve information on a channel (PEAR 1.4+)
channel-update | Update an existing channel (PEAR 1.4+)
clear-cache | Clear the REST/XML-RPC cache
config-create | Create a default configuration file (PEAR 1.4+)
config-get | Echo a specific configuration setting
config-help | Show information about a setting
config-set | Set a specific configuration setting value
config-show | Show all configuration setting values
convert | Convert a package.xml 1.0 format to package.xml 2.0 format (PEAR 1.4+)
cvsdiff | Execute and display a "cvs diff -u" on all files within the package
cvstag | Set a CVS release tag
download | Download a package but not install it
download-all | Downloads every available package
info | Display information about a package
install | Install a package, will report with success or failure
list | List installed packages
list-all | List all packages, packaged and/or available
list-channels | List available channels (PEAR 1.4+)
list-files | List files in an installed package (PEAR 1.4+)
list-upgrades | List available upgrades for the installed packages
login | Connects and authenticates to the remote PEAR server
logout | Logs out from the remote PEAR server
makerpm | Builds a RPM spec file from a PEAR package
package | Build a package
package-dependencies | Show package dependencies
package-validate | Validate package consistency
remote-info | Information about remote packages
remote-list | List remote packages
run-scripts | Run post-install scripts bundled with a package (PEAR 1.4+)
run-tests | Run regression tests
search | Search the remote package database
shell-test | Do a shell script test
sign | Sign a package distribution file
uninstall | Uninstall and remove a package
update-channels | Update the channel list (PEAR 1.4+)
upgrade | Upgrade a package to the current version (see also: preferred_state)
upgrade-all | Upgrade all packages (see also: list-upgrades)
Prev | Command line installer (PEAR) | Next
Using channels | PEAR Manual | Using Pyrus, the PEAR Installer for PHP 5.3+


Using Pyrus, the PEAR Installer for PHP 5.3+

Using Pyrus, the PEAR Installer for PHP 5.3+

Table of Contents
  • About Pyrus
  • Commands available in Pyrus
  • Pyrus configuration
  • Differences from the PEAR Installer
  • Creating plugins for Pyrus
  • Developer Tools for Pyrus
Prev |  | Next
Command list | PEAR Manual | About Pyrus


About Pyrus

About Pyrus

Table of Contents
  • What is a "Pyrus"?

Edited By

Gregory Beaver

2009-06-16

This documentation is organized with progressive complexity in mind. If you are new to PEAR, you should read the PEAR Concepts section of the manual first, and then return to learn more about Pyrus.

If you are migrating from using the PEAR installer, it will be helpful to read the section on differences from PEAR.

To get started with information on the features available in Pyrus, start with the Pyrus commands section to familiarize yourself with the commands available for users of Pyrus, then read about the configuration options available in Pyrus.

If you wish to extend Pyrus's functionality, read the section on plugins. Finally, if you are inspired to distribute your own software using Pyrus, you can either apply for a PEAR developer account (information here) or read the section on releasing packages through your own channel here.

PEAR, PEAR2 and PECL developers should read the documentation on how to use Pyrus to manage your existing or new packages here.

Prev | Using Pyrus, the PEAR Installer for PHP 5.3+ | Next
Using Pyrus, the PEAR Installer for PHP 5.3+ | PEAR Manual | What is a "Pyrus"?


What is a "Pyrus"?

What is a "Pyrus"?

Pyrus

In botany (the science of plants), Pyrus is the genus of the pear family, and thus includes all of the pear-producing trees and shrubs under its taxonomical umbrella.

In PHP (the hypertext programming language), Pyrus is the next-generation PEAR Installer, a revolutionary package management and distribution system that extends the functionality of the PEAR Installer's already advanced functionality. Pyrus is also friendlier to projects outside of PEAR that wish to take advantage of the strengths of PEAR through channels.

Pyrus represents the cumulative effort of years of work, experience with the PEAR Installer since its inception in 1999, and feedback from users like you. We are very proud to present the best installation tool for PHP.

Prev | About Pyrus | Next
About Pyrus | PEAR Manual | Commands available in Pyrus


Commands available in Pyrus

Commands available in Pyrus

Table of Contents
  • install - install a package
  • upgrade - upgrade or install a package
  • uninstall - remove a package
  • run-scripts - execute post-install scripts for specified packages
  • download - download a package
  • channel-add - add a channel by its channel.xml
  • channel-discover - add a channel by channel name
  • channel-del - remove a channel
  • info - get information on a package
  • list-packages - list all installed packages in all channels
  • list-channels - list known channels
  • remote-list - list remote packages on a channel
  • list-upgrades - list all available upgrades
  • upgrade-registry - convert a registry from PEAR format to Pyrus format
  • config-show - show all configuration values
  • set - set a configuration value
  • mypear - set the pear path: location of PEAR installations to manage by default
  • run-phpt - execute PHPT tests
  • make - create a package.xml from its source directory
  • package - create a packaged release in phar, tar, tgz or zip format
  • pickle - automatically create a PECL package.xml and package release from source directory
  • build - build a PECL PHP extension package

Edited By

Gregory Beaver

2009-06-25

Commands available for the Pyrus command-line script.

Prev | Using Pyrus, the PEAR Installer for PHP 5.3+ | Next
What is a "Pyrus"? | PEAR Manual | install - install a package


install - install a package

install - install a package

Introduction

The install command is used to install packages and accepts a list of package names to install as arguments. Unlike upgrade, the install command will only install new packages.

Install recognizes several different ways of specifying a package:

Ways of specifying a package for installation
Package type | Local/Remote | Example
package.xml file | Local | php pyrus.phar install /path/to/package.xml
Package release archive | Local | php pyrus.phar install /path/to/PackageName-1.2.3.tgz
Static url | Remote | php pyrus.phar install http://example.com/PackageName-1.2.3.tgz
Abstract package | Remote | php pyrus.phar install PackageName

Abstract Packages are documented here.

--optionaldeps

By default, required package dependencies are also installed. To also automatically install optional dependencies (not dependency groups, but dependencies specified using the <optional> tag in package.xml), pass the -o or --optionaldeps option to the install command:

php pyrus.phar install -o PackageName

--plugin

Plugins (documented here) must be explicitly installed with the -p or --plugin option. Plugins are installed into the location specified by the plugins_dir configuration variable, which defaults to the same location that the user configuration file is located ($HOME/.pear in unix, <My Documents>\pear on windows).

php pyrus.phar install -p PEAR2_Pyrus_Developer

--packagingroot

Developers packaging RPMs or other forms of distribution for OS vendors should use the -r or --packagingroot option to install a package into a subdirectory for creating the RPM.

php pyrus.phar install -r /home/myuser/package PackageName

For the example above, if the default Pyrus installation is in /usr/local/lib/pear, all files will be installed into /home/myuser/package/usr/local/lib/pear. Another way of understanding this is that the packagingroot option instructs Pyrus to treat /home/myuser/package as if it were the root directory /.

Developers packaging RPMs or other forms of distribution for OS vendors should use the -r or --packagingroot option to install a package into a subdirectory for creating the RPM.

php pyrus.phar install -r /home/myuser/package PackageName

--force

The --force or -f option can be used to force installation if there are errors. For instance, this can be used to override problems in dependency validation, or to force installation of a package that is not stable enough. As such, it should be used sparingly if at all. Better is to request a specific version for installation.

Prev | Commands available in Pyrus | Next
Commands available in Pyrus | PEAR Manual | upgrade - upgrade or install a package


upgrade - upgrade or install a package

upgrade - upgrade or install a package

Introduction

The upgrade command is almost identical to the install command. The only difference is that upgrade will also upgrade an existing package as well as install a new one.

The --packagingroot option is also unavailable, --packagingroot should only be used for installing new files.

Prev | Commands available in Pyrus | Next
install - install a package | PEAR Manual | uninstall - remove a package


uninstall - remove a package

uninstall - remove a package

Introduction

The uninstall command removes a package and accepts a list of installed packages to remove as arguments.

--plugin

Plugins (documented here) must be explicitly uninstalled with the -p or --plugin option. Plugins are installed into the location specified by the plugins_dir configuration variable, which defaults to the same location that the user configuration file is located ($HOME/.pear in unix, <My Documents>\pear on windows).

php pyrus.phar uninstall -p PEAR2_Pyrus_Developer

--force

The --force or -f option can be used to force uninstallation if there are errors. For instance, this can be used to override problems in dependency validation. As such, it should be used sparingly if at all. Better is to uninstall the packages tha depend on the package being uninstalled.

Prev | Commands available in Pyrus | Next
upgrade - upgrade or install a package | PEAR Manual | run-scripts - execute post-install scripts for specified packages


run-scripts - execute post-install scripts for specified packages

run-scripts - execute post-install scripts for specified packages

Introduction

The run-scripts command is used to execute post-install scripts of a package. It accepts a list of abstract package names.

Prev | Commands available in Pyrus | Next
uninstall - remove a package | PEAR Manual | download - download a package


download - download a package

download - download a package

Introduction

This command downloads a remote package to the current directory. It will accept any package name, abstract or concrete, and save the resulting file in the current directory.

Prev | Commands available in Pyrus | Next
run-scripts - execute post-install scripts for specified packages | PEAR Manual | channel-add - add a channel by its channel.xml


channel-add - add a channel by its channel.xml

channel-add - add a channel by its channel.xml

Introduction

Add a channel to the registry by its local channel.xml file. Use channel-discover to add a channel by its name.

Prev | Commands available in Pyrus | Next
download - download a package | PEAR Manual | channel-discover - add a channel by channel name


channel-discover - add a channel by channel name

channel-discover - add a channel by channel name

Introduction

This command searches for a channel.xml first at a secure https and then unsecured http address.

Examples:

php pyrus.phar channel-discover pear.example.com

This tries to locate https://pear.example.com/channel.xml and if that fails, http://pear.example.com/channel.xml, then adds the channel to the registry.

Use channel-add to add a local channel.xml to the registry.

Prev | Commands available in Pyrus | Next
channel-add - add a channel by its channel.xml | PEAR Manual | channel-del - remove a channel


channel-del - remove a channel

channel-del - remove a channel

Introduction

Remote a channel from the registry. Note that the default channels cannot be removed from the registry.

Default channels in Pyrus:

  • __uri

  • pear.php.net

  • pear2.php.net

  • pecl.php.net

  • doc.php.net

Prev | Commands available in Pyrus | Next
channel-discover - add a channel by channel name | PEAR Manual | info - get information on a package


info - get information on a package

info - get information on a package

Introduction

This command is used to display a list of information on a package, such as the maintainers, the stability and version or versions available for installation (for remote packages).

If passed description or notes, it displays the complete text of these fields. If passed files, it lists the files in the package and their on-disk location for installed packages. For example:

php pyrus.phar info PackageName description

The command will accept any concrete or abstract package names as its argument. Note that if there is an ambiguity between an installed package and the remote package, Pyrus will assume that information is being requested on the installed package.

--forceremote

The --forceremote or -r option is used to instruct Pyrus to resolve any ambiguity between an installed package and a remote package to assume that information is requested on the remote package.

Prev | Commands available in Pyrus | Next
channel-del - remove a channel | PEAR Manual | list-packages - list all installed packages in all channels


list-packages - list all installed packages in all channels

list-packages - list all installed packages in all channels

Introduction

This command lists all installed packages in all channels, organized by the installation location.

Prev | Commands available in Pyrus | Next
info - get information on a package | PEAR Manual | list-channels - list known channels


list-channels - list known channels

list-channels - list known channels

Introduction

List all known channels alphabetically.

Prev | Commands available in Pyrus | Next
list-packages - list all installed packages in all channels | PEAR Manual | remote-list - list remote packages on a channel


remote-list - list remote packages on a channel

remote-list - list remote packages on a channel

Introduction

The remote-list command lists all remote packages in a channel, organized by category. This command present an alphabetized list of all packages with the latest release and package summary. Installed packages are marked with an asterisk (*).

--basic

If the --basic or -b option is specified, only package name, latest release, and latest stable release are listed.

Prev | Commands available in Pyrus | Next
list-channels - list known channels | PEAR Manual | list-upgrades - list all available upgrades


list-upgrades - list all available upgrades

list-upgrades - list all available upgrades

Introduction

This command lists all packages that have upgrades available within the current preferred_state or the installed package's stability, whichever is less stable. This command does not list releases that are incompatible with the current PHP version.

If package X is installed with version 0.3.0, stability alpha, and preferred_state is stable, Pyrus will list the newest version available that satisfies stability of alpha, beta or stable. If package Y is also installed, with version 1.2.3, stability stable, only the latest stable release will be listed. In both cases, if the latest available version that satisfies these requirements is not found, none will be listed.

Another example: If package X is installed with version 1.0.0, stability stable, and the preferred_state is alpha, Pyrus will list the newest version available that satisfies stability of alpha, beta or stable.

Prev | Commands available in Pyrus | Next
remote-list - list remote packages on a channel | PEAR Manual | upgrade-registry - convert a registry from PEAR format to Pyrus format


upgrade-registry - convert a registry from PEAR format to Pyrus format

upgrade-registry - convert a registry from PEAR format to Pyrus format

Introduction

The upgrade-registry command is used to convert a registry from the old PEAR Installer format into the new Pyrus format, and then optionally remove the old registry.

The command creates registries in Sqlite3 and XML formats in the path passed as the argument to upgrade-registry. Note that Pyrus registries are stored in the parent directory as the installed PHP files, whereas PEAR registries are stored in the same directory as the installed PHP files, so it is necessary for Pyrus to have write access to the parent directory.

--removeold

The --removeold or -r option instructs Pyrus to remove the old PEAR registry when finished upgrading.

Prev | Commands available in Pyrus | Next
list-upgrades - list all available upgrades | PEAR Manual | config-show - show all configuration values


config-show - show all configuration values

config-show - show all configuration values

Introduction

The config-show command lists all system and user configuration variables. Documentation on currently supported configuration variables and how Pyrus organizes configuration can be found here.

Prev | Commands available in Pyrus | Next
upgrade-registry - convert a registry from PEAR format to Pyrus format | PEAR Manual | set - set a configuration value


set - set a configuration value

set - set a configuration value

Introduction

Set a configuration value. Documentation on how Pyrus organizes configuration values can be found here. Also note that mypear can be used as a simpler method of setting the my_pear_path configuration value.

For example:

php pyrus.phar set download_dir /home/blah/downloads
Prev | Commands available in Pyrus | Next
config-show - show all configuration values | PEAR Manual | mypear - set the pear path: location of PEAR installations to manage by default


mypear - set the pear path: location of PEAR installations to manage by default

mypear - set the pear path: location of PEAR installations to manage by default

Introduction

The mypear command sets up the path or paths in which Pyrus will look for installed packages. If multiple paths are specified, they should be separated by PATH_SEPARATOR, which is : on unix systems, and ; on Windows-based systems. If multiple paths are specified, only the first path will be used for installing packages. The other paths are only used to validate package dependencies.

mypear is a convenient alternative to using the set command to set the my_pear_path configuration variable.

Prev | Commands available in Pyrus | Next
set - set a configuration value | PEAR Manual | run-phpt - execute PHPT tests


run-phpt - execute PHPT tests

run-phpt - execute PHPT tests

Introduction

The run-phpt command is used to execute tests in the PHPT format. If the xdebug extension is present, the command can also be used to generate code coverage. This coverage can then be used to construct a coverage report and even to intelligently detect both modified tests and tests that are affected by changes to the source code in between test runs.

The command takes as arguments a list of paths containing tests to execute, unless the --modified option is specified, then it takes as arguments the path to the tests directory and the path to the source directory. If the --modified option is not specified, and no arguments are passed, the command searches for tests in the current working directory.

--modified

The --modified or -m option, if present, implies both the --recursive and --coverage options, and is used to generate a coverage database and to use that database to detect modifications in the tests and the source. These modified tests are then executed.

The command places a file named pear2coverage.db in the tests directory, which is an Sqlite3 database containing the coverage information. The coverage can be viewed as a web-based report by taking the pear2coverage.phar.php file installed with the developer tools and placing it in a web server directory, and then browsing to it. The web server must have the phar and sqlite3 extensions enabled in order to function properly.

To illustrate how powerful this option is, imagine a hypothetical directory structure as follows:

  src/

      File1.php

      File2.php

      File3.php

  tests/

      test1.phpt

      test2.phpt

      test3.phpt

      test4.phpt

Here are the source files:

File1.php:

<?php
class File1
{
    var $a = 1;
    function __construct($a = 1)
    {
        $this->a = $a;
    }

    function setInternalThing($thing)
    {
        $this->internal = $thing;
        $this->internal->initialize($this);
    }
}
?>

File2.php:

<?php
class File2
{

    function initialize(File1 $parent)
    {
        $parent->a = 2;
    }
}
?>

File3.php:

<?php
class File3 extends File2
{

    function initialize(File1 $parent)
    {
        $parent->a = 3;
    }
}
?>

test1.phpt:

--TEST--
test 1
--FILE--
<?php
function __autoload($class) { include __DIR__ . '/../src/' . $class . '.php'; }

$test = new File1(6);
if ($test->a != 6) {
    echo '$a is not 6, it is ' . $test->a, "\n";
}
?>
===DONE===
--EXPECT--
===DONE===

test2.phpt:

--TEST--
test 2
--FILE--
<?php
function __autoload($class) { include __DIR__ . '/../src/' . $class . '.php'; }

$test2 = new File2;

$test = new File1;
$test->setInternalThing($test2);

if ($test->a != 2) {
    echo '$a is not 2, it is ' . $test->a, "\n";
}
?>
===DONE===
--EXPECT--
===DONE===

test3.phpt:

--TEST--
test 3
--FILE--
<?php
function __autoload($class) { include __DIR__ . '/../src/' . $class . '.php'; }

$test2 = new File2;

$test = new stdClass;
$test2->initialize($test);

if ($test->a != 2) {
    echo '$a is not 2, it is ' . $test->a, "\n";
}
?>
===DONE===
--EXPECT--
===DONE===

test4.phpt:

--TEST--
test 4
--FILE--
<?php
function __autoload($class) { include __DIR__ . '/../src/' . $class . '.php'; }

$test3 = new File3;

$test = new File1;
$test->setInternalThing($test3);

if ($test->a != 3) {
    echo '$a is not 3, it is ' . $test->a, "\n";
}
?>
===DONE===
--EXPECT--
===DONE===

If a modification is made to File3.php, the run-phpt command will detect that only test4.phpt uses this file, and will run that test. If a modification is made to File2.php, test2.phpt, test3.phpt and test4.phpt will all be executed, even though test4.phpt does not directly use the File2 class, because File3 extends File2 and so the file is loaded. If a modification is made to File1.php, test1.phpt, test2.phpt and test4.phpt will all be executed. Finally, if any of the phpt test files are executed, or any external files that they include are modified, they will be run again. If a new test, test5.phpt is added, the run-phpt command will also detect the test and run it.

This allows extremely efficient development, as surgically running only tests that are affected by source code changes allows assurance that even the most remote file dependencies are validated, and irrelevant tests are not executed unnecessarily. By relying upon the coverage report, it is also easy to catch subtle logic bugs preventing code blocks from being executed, resulting in far more robust code much faster. Pyrus itself was developed using this technique.

--recursive

The --recursive or -r option causes Pyrus to recursively traverse directories specified

--coverage

the --coverage or -x option causes Pyrus to record coverage using the xdebug extension's code coverage capabilities.

Prev | Commands available in Pyrus | Next
mypear - set the pear path: location of PEAR installations to manage by default | PEAR Manual | make - create a package.xml from its source directory


make - create a package.xml from its source directory

make - create a package.xml from its source directory

Introduction

Note: The make command is available through the developer tools. If you do not have the developer tools installed, simply run
php pyrus.phar make
and Pyrus will ask if you would like to install the developer tools. If you assent with the word yes, Pyrus will automatically download them and install them for you.

This command creates a package.xml file from a standard PEAR2 directory layout, and then optionally creates a package release.

This command looks for these standard files:

  • CREDITS

  • README

  • RELEASE-X.Y.Z (where X.Y.Z is the release version)

  • API-X.Y.Z (where X.Y.Z is the API version)

and for a standard directory layout of

Standard directory layout
Sub-directory | Description
src/ | PHP files
data/ | Data files
test/ | Test files
doc/ | Documentation files
examples/ | Example files (documentation)
scripts/ | Executable files, scripts
www/ | Web files
customrole/ | Custom installer role XML definition files
customtask/ | Custom installer task XML definition files
customcommand/ | Custom command XML definition files

The CREDITS file must have this format:

;; comments ignored
Maintainer One [handle1] <email@example.com> (role)
Maintainer Two [handle2] <email@example.com> (role)

Where role is one of lead, developer, contributor, or helper.

The first line of README is used as the summary of the package, the rest is used as the description. RELEASE-X.Y.Z is used as the release notes. Pyrus will scan all release notes (such as RELEASE-1.0.0 and RELEASE-1.2.3) and use the most recent version number (1.2.3 in our example) as the version, and the contents of the file (RELEASE-1.2.3 in our example) as the release notes.

API-X.Y.Z is used as notes about the API and the version X.Y.Z is used as the API version.

--packagexmlsetup

if --packagexmlsetup or -s is specified, it should be passed the name of a file in the package base directory that is used to fine-tune the generated package.xml. This file should work with variable $package for modifying the package.xml, and $compatible for the compatible one (if present). If --packagexmlsetup is not specified, and packagexmlsetup.php exists in the package base directory, it will be used.

Here is an example packagexmlsetup.php:

<?php
$package->dependencies['required']->package['pear2.php.net/PEAR2_Autoload']->save();
$package->dependencies['required']->package['pear2.php.net/PEAR2_Exception']->save();
$package->dependencies['required']->package['pear2.php.net/PEAR2_MultiErrors']->save();

$compatible->dependencies['required']->package['pear2.php.net/PEAR2_Autoload']->save();
$compatible->dependencies['required']->package['pear2.php.net/PEAR2_Exception']->save();
$compatible->dependencies['required']->package['pear2.php.net/PEAR2_MultiErrors']->save();
?>

--nocompatible

If --nocompatible or -n option is passed in, Pyrus will not generate a package.xml that is compatible with the PEAR Installer.

--package

This option instruct the make command to pass off the finished package.xml to the package command. It accepts a comma-delimited list of file formats, and can be any of phar, tar, tgz or zip.

--stub

This option is identical to the option for the --stub option of the package command, and is ignored if --package or -p is not also specified.

--extrasetup

This option is identical to the option for the --extrasetup option of the package command, and is ignored if --package or -p is not also specified.

Prev | Commands available in Pyrus | Next
run-phpt - execute PHPT tests | PEAR Manual | package - create a packaged release in phar, tar, tgz or zip format


package - create a packaged release in phar, tar, tgz or zip format

package - create a packaged release in phar, tar, tgz or zip format

Introduction

Note: The package command is available through the developer tools. If you do not have the developer tools installed, simply run
php pyrus.phar package
and Pyrus will ask if you would like to install the developer tools. If you assent with the word yes, Pyrus will automatically download them and install them for you.

The package command bundles up the files of a package and its package.xml into an archive for distribution. It accepts a single optional argument, the path to a package.xml.

If the optional path is not provided, the command searches for a file named package.xml in the current directory. If this file is an older version 1.0, it also searches for package2.xml in the current directory, and uses that as the package file. This allows creating packages that are compatible with ancient versions of PEAR older than version 1.4.0

If package.xml exists and is a PEAR2 package (requires pear installer version equal to or newer than 2.0.0a1), the command will also look for a file in the current directory named package_compatible.xml. This file should be a package.xml customized for use by the PEAR Installer, and is automatically generated by the make command unless explicitly prevented. This file makes it possible for the PEAR Installer to install packages generated for Pyrus.

The created archive can be in any or all of the following formats:

  1. phar

  2. tar

  3. tgz

  4. zip

The formats are requested by passing their name as an option like so:

php pyrus.phar package --phar --tar --tgz --zip

.

The phar file format is a format that can be used to create self-installing archives, or even archives that are self-contained commands. pyrus.phar, for instance, is a complete application that runs directly from its archive. Due to security considerations, the ability to create executable phar archives is disabled by default. To create a phar archive, the phar.readonly php.ini setting must be disabled like so:

php -dphar.readonly=0 pyrus.phar package --phar

The tar and tgz file formats are the formats familiar to users of PEAR. tgz is a gzipped tar archive, and requires the zlib extension be enabled in order to create it.

The zip file format is most familiar to Windows users.

PEAR2 packages

All packages designed for Pyrus automatically have PEAR2/Autoload.php, PEAR2/Exception.php, PEAR2/MultiErrors.php, and PEAR2/MultiErrors/Exception.php bundled so that these dependencies are available when a package is extracted without use of Pyrus to install it. Packages designed for installation by the PEAR Installer and not for Pyrus do not bundle any dependencies.

Package signing

Pyrus supports creating archives that have a mandatory signature using OpenSSL certificates such as those available from CACert. Signed archives cannot be processed without the presence of the openssl PHP extension. In addition, a bug in the phar extension's verification of openssl signatures requires PHP version 5.3.1 or newer. Creation of signatures only requires PHP version 5.3.0 or newer.

To create a package signature, set the openssl_cert configuration variable to the path of your PKCS#12 certificate (generally saved with a file extension of p12), and the handle configuration variable to your handle in package.xml.

--stub

The --stub or -s option specifies a PHP script to use as the stub to a phar archive, and is ignored if --phar is not passed to the command. The stub is a short executable script that is executed as a boot strap when a phar archive is passed to PHP like

php pyrus.phar

. All stubs must end with the __HALT_COMPILER(); directive to be a valid stub.

If the --stub option is not explicitly specified and a phar archive is being created, Pyrus will look for a file named stub.php in the same directory as the package.xml, and will use that as the stub for the phar archive if found.

Here is pyrus's stub:

<?php
if (version_compare(phpversion(), '5.3.0', '<')) {
    if (substr(phpversion(), 0, 5) != '5.3.0') {
        // this small hack is because of running RCs of 5.3.0
        echo "Pyrus requires PHP 5.3.0 or newer.\n";
        exit -1;
    }
}
foreach (array('phar', 'spl', 'pcre', 'simplexml') as $ext) {
    if (!extension_loaded($ext)) {
        echo 'Extension ', $ext, " is required\n";
        exit -1;
    }
}
try {
    Phar::mapPhar();
} catch (Exception $e) {
    echo "Cannot process Pyrus phar:\n";
    echo $e->getMessage(), "\n";
    exit -1;
}
function pyrus_autoload($class)
{
    if (file_exists('phar://' . __FILE__ . '/php/' . implode('/', explode('_', $class)) . '.php')) {
        include 'phar://' . __FILE__ . '/php/' . implode('/', explode('_', $class)) . '.php';
    }
}
spl_autoload_register("pyrus_autoload");
$frontend = new PEAR2_Pyrus_ScriptFrontend_Commands;
@array_shift($_SERVER['argv']);
$frontend->run($_SERVER['argv']);
__HALT_COMPILER();

--extrasetup

The --extrasetup or -e option is used to specify the path to a PHP script that is used to include files in the created packages that are not in the package.xml list of files. This is used to create archives that are designed to be friendly to users simply "trying before they buy" the archive, or to provide support files needed to create self-installing archives.

If the --extrasetup option is not explicitly specified, then Pyrus looks for a file named extrasetup.php in the same directory as the package.xml, and will use this if found.

The extrasetup script should create a variable named $extrafiles that contains an associative array mapping relative path within the archive to an absolute path of a file on disk.

Here is Pyrus's extrasetup, which demonstrates bundling of the required dependencies PEAR2_HTTP_Request and PEAR2_Console_Commandline:

<?php
/**
 * This file generates the pyrus.phar file and PEAR2 package for Pyrus.
 */
$rp = __DIR__ . '/../HTTP_Request/src/HTTP';
$cc = __DIR__ . '/../sandbox/Console_CommandLine/src/Console';
$extrafiles = array(
    'php/PEAR2/HTTP/Request.php' => $rp . '/Request.php',
    'php/PEAR2/HTTP/Request/Adapter.php' => $rp . '/Request/Adapter.php',
    'php/PEAR2/HTTP/Request/Adapter/Curl.php' => $rp . '/Request/Adapter/Curl.php',
    'php/PEAR2/HTTP/Request/Adapter/Http.php' => $rp . '/Request/Adapter/Http.php',
    'php/PEAR2/HTTP/Request/Adapter/Phpsocket.php' => $rp . '/Request/Adapter/Phpsocket.php',
    'php/PEAR2/HTTP/Request/Adapter/Phpstream.php' => $rp . '/Request/Adapter/Phpstream.php',
    'php/PEAR2/HTTP/Request/Exception.php' => $rp . '/Request/Exception.php',
    'php/PEAR2/HTTP/Request/Headers.php' => $rp . '/Request/Headers.php',
    'php/PEAR2/HTTP/Request/Listener.php' => $rp . '/Request/Listener.php',
    'php/PEAR2/HTTP/Request/Response.php' => $rp . '/Request/Response.php',
    'php/PEAR2/HTTP/Request/Uri.php' => $rp . '/Request/Uri.php',

    'php/PEAR2/Console/CommandLine.php' => $cc . '/CommandLine.php',
    'php/PEAR2/Console/CommandLine/Result.php' => $cc . '/CommandLine/Result.php',
    'php/PEAR2/Console/CommandLine/Renderer.php' => $cc . '/CommandLine/Renderer.php',
    'php/PEAR2/Console/CommandLine/Outputter.php' => $cc . '/CommandLine/Outputter.php',
    'php/PEAR2/Console/CommandLine/Option.php' => $cc . '/CommandLine/Option.php',
    'php/PEAR2/Console/CommandLine/MessageProvider.php' => $cc . '/CommandLine/MessageProvider.php',
    'php/PEAR2/Console/CommandLine/Exception.php' => $cc . '/CommandLine/Exception.php',
    'php/PEAR2/Console/CommandLine/Element.php' => $cc . '/CommandLine/Element.php',
    'php/PEAR2/Console/CommandLine/Command.php' => $cc . '/CommandLine/Command.php',
    'php/PEAR2/Console/CommandLine/Argument.php' => $cc . '/CommandLine/Argument.php',
    'php/PEAR2/Console/CommandLine/Action.php' => $cc . '/CommandLine/Action.php',
    'php/PEAR2/Console/CommandLine/Renderer/Default.php' => $cc . '/CommandLine/Renderer/Default.php',
    'php/PEAR2/Console/CommandLine/Outputter/Default.php' => $cc . '/CommandLine/Outputter/Default.php',
    'php/PEAR2/Console/CommandLine/MessageProvider/Default.php' => $cc . '/CommandLine/MessageProvider/Default.php',
    'php/PEAR2/Console/CommandLine/Action/Callback.php' => $cc . '/CommandLine/Action/Callback.php',
    'php/PEAR2/Console/CommandLine/Action/Counter.php' => $cc . '/CommandLine/Action/Counter.php',
    'php/PEAR2/Console/CommandLine/Action/Help.php' => $cc . '/CommandLine/Action/Help.php',
    'php/PEAR2/Console/CommandLine/Action/StoreFloat.php' => $cc . '/CommandLine/Action/StoreFloat.php',
    'php/PEAR2/Console/CommandLine/Action/StoreInt.php' => $cc . '/CommandLine/Action/StoreInt.php',
    'php/PEAR2/Console/CommandLine/Action/StoreString.php' => $cc . '/CommandLine/Action/StoreString.php',
    'php/PEAR2/Console/CommandLine/Action/StoreTrue.php' => $cc . '/CommandLine/Action/StoreTrue.php',
    'php/PEAR2/Console/CommandLine/Action/Version.php' => $cc . '/CommandLine/Action/Version.php',
);
Prev | Commands available in Pyrus | Next
make - create a package.xml from its source directory | PEAR Manual | pickle - automatically create a PECL package.xml and package release from source directory


pickle - automatically create a PECL package.xml and package release from source directory

pickle - automatically create a PECL package.xml and package release from source directory

Introduction

The pickle command is designed to make the creation of an extension for PECL developers very easy. It scans a CVS checkout of a PECL package directory, generates package.xml, and packages a release in one step.

The pickle command looks for these standard files:

  • CREDITS

  • README

  • RELEASE-X.Y.Z (where X.Y.Z is the release version)

  • API-X.Y.Z (where X.Y.Z is the API version)

and for a standard directory layout of

/                Extension source files

data/            Data files

tests/           Test files

doc/             Documentation files

examples/        Example files (documentation)

The CREDITS file must have this format for the pickle command to recognize it:

;; extensionname
Maintainer One [handle1] <email@example.com> (role)
Maintainer Two [handle2] <email@example.com> (role)

Where role is one of lead, developer, contributor, helper. The first line of README is used as the summary of the package. RELEASE-X.Y.Z is used as the release notes.

X.Y.Z in the filename RELEASE-X.Y.Z is also used to automatically calculate the stability, and X.Y.Z in the filename API-X.Y.Z is used to calculate the API stability. The formula is relatively simple: if X is 0, the stability is set to alpha. Otherwise, if X is 1 or greater, the following methods are used to calculate the stability.

  • If Z contains a as in the version 1.0.0a1 the stability is set to alpha

  • If Z contains b as in the version 1.0.0b1 the stability is set to beta

  • If Z contains RC as in the version 1.0.0RC1 the stability is set to beta

  • Otherwise, stability is set to stable.

Arguments to the pickle command

The pickle command has 4 arguments:

php pyrus.phar pickle extname channelname /path/to/packagedir extensions...

/path/to/packagedir specifies the location in which to package up the release. If not present, it defaults to the current working directory. The pickle command usually should be executed from that directory, this argument is present to allow batch creation of package.xml files for multiple extensions with a single shell script.

If package.xml does not exist in the location packaging will take place, then the first argument is required. The first argument is the name of the package, which is usually the same name as the extension, and the second argument is the channel name. If not specified, the package is assumed to be in the pecl.php.net channel.

The final argument, extensions is a list of file extensions that should be considered source files. By default, the file extensions recognized as source files are:

  • c

  • cc

  • h

  • m4

  • w32

  • re

  • y

  • l

  • frag

--donotpackage

If --donotpackage or -n is specified, then the pickle command will only generate package.xml, and will not package up a release. The package command can be used to build the release after reviewing package.xml.

Prev | Commands available in Pyrus | Next
package - create a packaged release in phar, tar, tgz or zip format | PEAR Manual | build - build a PECL PHP extension package


build - build a PECL PHP extension package

build - build a PECL PHP extension package

Introduction

This command builds an installed PECL extension. It accepts as its arguments a list of installed php extension packages to build. It performs an automatic version of:

phpize --clean

phpize

./configure

make

make install

In the source directory of the package. It also will prompt the user if any <configureoption> tags exist in package.xml (see the documentation for <configureoption> here)

Prev | Commands available in Pyrus | Next
pickle - automatically create a PECL package.xml and package release from source directory | PEAR Manual | Pyrus configuration


Pyrus configuration

Pyrus configuration

Table of Contents
  • Pyrus user configuration variables
  • Pyrus system configuration variables

Edited By

Gregory Beaver

2009-06-26

Pyrus has two kinds of configuration files, system configuration files, which are stored directly in the installation location, and user configuration files, which are stored in the home directory of the user, or in the Windows equivalent, My Documents.

Each installation is tightly bound to the configuration that defines where files should be installed, which PHP executable to use, and which php.ini is used to manage that installation.

On the other hand, user-specific preferences are tightly bound to each user, by placing them in the user's home directory. These values are universal to all installations and include things like the amount of information to display, the preferred mirror to use for a channel, the openssl certificate to use for package signing, and so on.

This way, multiple PEAR installations can be managed very safely without ambiguity over what configuration values should be used.

Prev | Using Pyrus, the PEAR Installer for PHP 5.3+ | Next
build - build a PECL PHP extension package | PEAR Manual | Pyrus user configuration variables


Pyrus user configuration variables

Pyrus user configuration variables

Introduction

The user configuration file is always stored in the user's personal directory, the home directory on unix, and My Documents on Windows. For a unix user with username user, the user configuration file is stored in /home/user/.pear/pearconfig.xml. For a Windows user, the configuration is stored in My Documents\pear\pearconfig.xml. The file is saved in XML format and can be hand-edited if necessary.

Unlike the system configuration file, the user configuration file is always saved when an operation that writes to disk is called, such as installing a package. On startup, Pyrus uses the configuration file's existence to determine whether it is being executed for the first time, and if so, prompts the user to initialize a few default settings such as the PEAR path.

There are two kinds of user configuration variables, installation-wide variables such as verbose, and channel-specific variables such as openssl_cert. Channel-specific variables can have different values for different channels. This allows setting a different certificate for each channel, for instance. The channel name is used as a tag, with non-XML friendly characters translated into simple mnemonics (such as . becoming DOT).

Here is a sample user configuration file (with line breaks added for readability):

<?xml version="1.0"?>
<pearconfig version="1.0">
 <default_channel>pear2.php.net</default_channel>
 <auto_discover>0</auto_discover>
 <http_proxy></http_proxy>
 <cache_dir>/home/user/testpear/cache</cache_dir>
 <temp_dir>/home/user/testpear/temp</temp_dir>
 <verbose>1</verbose>
 <paranoia>2</paranoia>
 <preferred_state>stable</preferred_state>
 <umask>0022</umask>
 <cache_ttl>3600</cache_ttl>
 <my_pear_path>/home/user/testpear:/usr/local/lib/php</my_pear_path>
 <plugins_dir>/home/user/.pear</plugins_dir>
 <openssl_cert>
  <pear2DOTphpDOTnet>/home/user/mykey.p12</pear2DOTphpDOTnet>
 </openssl_cert>
 <handle>
  <pear2DOTphpDOTnet>cellog</pear2DOTphpDOTnet>
 </handle>
</pearconfig>

auto_discover

Introduction

auto_discover is a flag (boolean), defaulting to 0 or off. If on, this flag instructs Pyrus to automatically discover channels of dependencies (see channel-discover for a more in-depth description of what channel discovery means).

For example, let's say we are installing Package foo from channel pear2.php.net, and that foo depends on package bar from channel pear.example.com. If Pyrus does not know the pear.example.com channel, and auto_discover is set to 1, it will attempt to discover information on the channel, and after successfully adding its information to the registry, will then successfully download and install the dependency bar. However, if auto_discover is disabled, Pyrus will simply fail with an error explaining that nothing is known about the pear.example.com channel, and that it must be added prior to installation.

cache_dir

Introduction

cache_dir is the location where HTTP caching of PEAR channel REST files is cached.

cache_ttl

Introduction

the cache_ttl configuration variable is used to determine when to consider the PEAR Channel REST cache to have been invalidated. It is measured in seconds, and by default is 3600, or 1 hour.

default_channel

Introduction

The default channel is the channel that should be implied when an Abstract Package is ambiguous. By default, it is pear2.php.net.

As an example, when executing:

php pyrus.phar install PEAR2_HTTP_Request

The abstract package PEAR2_HTTP_Request is ambiguous - it does not specify a channel. Pyrus assumes, therefore, that the requested package is from the default channel, and acts as if the user had in fact typed:

php pyrus.phar install pear2.php.net/PEAR2_HTTP_Request

The default_channel value is also used for all channel-specific configuration values.

download_dir

Introduction

Note: This is a channel-specific configuration value

The download_dir is where downloaded packages are kept. This can allow later repairing or easy cloning of an installation. There is no penalty if the files are removed, and they may be easily removed to conserve space.

handle

Introduction

Note: This is a channel-specific configuration value

The handle variable should be set to the handle you use to identify yourself in the <maintainers> section of package.xml for packages in a specific channel.

For example, if your <maintainer> entry in package.xml is:

 <lead>
  <name>Greg Beaver</name>
  <user>cellog</user>
  <email>cellog@php.net</email>
  <active>no</active>
 </lead>

Your handle is cellog.

This configuration variable is used in conjunction with the openssl_cert configuration variable to implement package signing.

http_proxy

Introduction

The http_proxy configuration variable should be set to the full URI of your local HTTP proxy, or left blank for none.

my_pear_path

Introduction

The my_pear_path configuration value controls the order in which Pyrus cascades PEAR installations. The path should have the same syntax as include_path, a PATH_SEPARATOR-separated list of full paths to PEAR installations. The my_pear_path configuration variable can be easily set with the mypear command.

Only the first path is considered to be read/write, the others are only used to validate package dependencies on download.

For instance, the my_pear_path /home/user/testpear:/usr/local/lib/php instructs Pyrus to install all packages into the PEAR installation at /home/user/testpear, and to also use the PEAR installation in /usr/local/lib/php to validate dependencies.

On Windows, an example my_pear_path is D:\customPear;C:\php5.

openssl_cert

Introduction

Note: This is a channel-specific configuration value

The openssl_cert configuration variable should be set to the full path to your personal PKCS#12 certificate, as signed by a recognized certificate authority such as CACert. Pyrus uses this certificate along with your handle to implement package signing.

Your certificate must have the email address you use in package.xml as its alternate name, otherwise Pyrus will refuse to use it. Pyrus uses the email address as stated in package.xml of the releasing maintainer of a package to verify that the package was actually created by the maintainer. This makes a man-in-the-middle attack far more difficult to execute, as well as verifying package integrity.

password

Introduction

Note: This is a channel-specific configuration value

This configuration variable is a legacy variable from PEAR, is not yet used in Pyrus, and may be removed before the stable release.

plugins_dir

Introduction

The plugins_dir directory is where all Pyrus plugins are installed. By default, it is the directory in which the user configuration file is stored.

preferred_mirror

Introduction

Note: This is a channel-specific configuration value

This variable controls which mirror of a channel should be used to retrieve package releases and PEAR Channel REST information. By default, it is set to the main channel path.

preferred_state

Introduction

The preferred_state configuration variable controls the release stability level of packages that will be installed. By default it is stable, which instructs Pyrus to ignore any releases with lesser stabilities beta, alpha or devel unless explicitly requested by the user.

This can be changed to allow riskier installation of newer, less-tested releases that are on the cutting edge of development.

temp_dir

Introduction

The temp_dir configuration directive is where all temporary files are extracted by Pyrus.

umask

Introduction

The umask configuration value is used to control the default file mask used when setting file permissions. By default it is octal value 0022. The value is a bitmask that is used to clear any bits. Thus, a umask of 0000 will cause files to be installed with 0666 permissions. A umask of 0022 causes files to be installed with 0644 permissions.

username

Introduction

Note: This is a channel-specific configuration value

This configuration variable is a legacy variable from PEAR, is not yet used in Pyrus, and may be removed before the stable release.

verbose

Introduction

The verbose setting controls how much information Pyrus echoes as it performs its task. The higher the setting, the more information Pyrus will spew. By default, it is set to 1.

verbose

Introduction

The paranoia setting controls how Pyrus handles automatic upgrades to new versions of packages. The API version of the installed package is compared against the API version of remote packages, and chooses a release that is compatible with the current version based on the paranoia level. This setting does not affect upgrades of local packages, only those retrieved from a remote PEAR channel server.

The paranoia setting is a numeric setting with levels 1 to 4 supported, anything above 4 is automatically converted to 4. The levels work as follows:

  1. API version is ignored, only package stability and PHP version compatibility is used to determine which package to download for installation.

  2. This is the default setting, and specifies that backwards compatibility must be maintained.

    This is performed by checking that the API version first digit does not change. Thus a package with API version of 1.2.3 cannot upgrade to a new package with API version 2.0.0. Upgrades are allowed to versions such as 1.2.4 or 1.3.0.

  3. This is a strict setting, only allowing security and other API bugfixes.

    This is performed by checking that the API version's first and second digits do not change. Thus a package with API version of 1.2.3 cannot upgrade to a new package with API version 2.0.0. Upgrades are allowed to versions such as 1.2.4, but not to 1.3.0.

  4. Do not allow any API changes

    This is the most paranoid setting, and prevents upgrading to any package that changes API version whatsoever.

If using pyrus.phar, the setting can also be changed with the -p command-line option. This example sets paranoia temporarily to 1:

php pyrus.phar -p install PackageName

This example sets paranoia temporarily to 4:

php pyrus.phar -pppp install PackageName
Prev | Pyrus configuration | Next
Pyrus configuration | PEAR Manual | Pyrus system configuration variables


Pyrus system configuration variables

Pyrus system configuration variables

Introduction

The system configuration file is always saved in a file named .config in the base of the PEAR installation. Thus, if php files are installed in /usr/local/lib/pear/php, then the configuration for that installation is installed in /usr/local/lib/pear/.config. The configuration is stored in XML format, and can be modified by hand if necessary.

The configuration will not be saved if no values are modified from the default values

Here is a sample system configuration file (with line breaks added for readability):

<?xml version="1.0"?>
<pearconfig version="1.0">
 <ext_dir>/usr/local/lib/php/extensions/debug-non-zts-20090115</ext_dir>
 <cfg_dir>/home/user/testpear/cfg</cfg_dir>
 <doc_dir>/home/user/testpear/mydata</doc_dir>
 <bin_dir>/usr/local/bin</bin_dir>
 <www_dir>/home/user/testpear/www</www_dir>
 <test_dir>/home/user/testpear/tests</test_dir>
 <src_dir>/home/user/testpear/src</src_dir>
 <php_bin>/usr/local/bin/php</php_bin>
 <php_ini>/usr/local/lib/php.ini</php_ini>
 <php_prefix></php_prefix>
 <php_suffix></php_suffix>
</pearconfig>

bin_dir

Introduction

executable files (files with a script role) are installed into bin_dir

cfg_dir

Introduction

Customizable configuration files (files with cfg role) are installed into this directory. These files are intended to be manipulated by the user, and Pyrus will not overwrite them if any changes have been made.

data_dir

Introduction

Files with roles data, customcommand, customrole and customtask are installed into the data_dir configuration variable.

In Pyrus, this is a pseudo-configuration variable: its value cannot be changed without creating an entirely new repository. Data is always stored in the directory data/ relative to the location of the installation.

doc_dir

Introduction

files with the doc role are installed into doc_dir.

ext_dir

Introduction

Compiled extension files are installed into the ext_dir, and files with role ext.

php_bin

Introduction

the php_bin configuration variable refers to the location of PHP that should be used for installed executable scripts.

php_dir

Introduction

Files with roles php are installed into the php_dir configuration variable.

In Pyrus, this is a pseudo-configuration variable: its value cannot be changed without creating an entirely new repository. PHP files are always stored in the directory php/ relative to the location of the installation.

php_ini

Introduction

the php_ini variable should be set to the location of php.ini that is used by this installation, and is used to automatically enable extensions on installation.

php_prefix

Introduction

This variable should be set to the value that --program-prefix was set to when PHP was configured, and is used when building PECL extensions.

php_suffix

Introduction

This variable should be set to the value that --program-suffix was set to when PHP was configured, and is used when building PECL extensions.

src_dir

Introduction

Files with the src role are installed into src_dir, and building of PECL packages also happens in this directory.

test_dir

Introduction

Files with test role are installed into this directory.

www_dir

Introduction

Files with www role are installed into this directory.

Prev | Pyrus configuration | Next
Pyrus user configuration variables | PEAR Manual | Differences from the PEAR Installer


Differences from the PEAR Installer

Differences from the PEAR Installer

Table of Contents
  • Pyrus: Improvements from the PEAR Installer
  • Pyrus Post-install scripts: differences from PEAR
  • Pyrus Custom Commands: differences from PEAR
  • Pyrus Custom File Roles: differences from PEAR
  • Pyrus Custom File Tasks: differences from PEAR

Edited By

Gregory Beaver

2009-06-25

Differences between Pyrus and the PEAR Installer. This documentation is a work in progress.

Prev | Using Pyrus, the PEAR Installer for PHP 5.3+ | Next
Pyrus system configuration variables | PEAR Manual | Pyrus: Improvements from the PEAR Installer


Pyrus: Improvements from the PEAR Installer

Pyrus: Improvements from the PEAR Installer

Overview

Pyrus is a re-factored version of the PEAR installer, re-designed for new features available in PHP 5.3 and newer. As a result, Pyrus is more robust than PEAR as well as faster. Several of the subtle design flaws in the PEAR Installer have been fixed, and so Pyrus is more stable than the PEAR Installer for handling an existing PEAR repository.

Here is a brief summary of the differences from PEAR:

Simpler to use than PEAR

Pyrus is distributed as a single file, pyrus.phar. Because of PHP's new phar extension, Pyrus does not need to be installed, and can run directly from the file pyrus.phar.

Pyrus also simplifies the command-line options available, and provides a far greater range of developer tools for creating, managing and distributing packages through tools such as the simple channel server and package.xml creation command make.

More secure than PEAR

Several security vulnerabilities in the design of PEAR were discovered due to the particular Command Pattern implementation used to detect file roles, commands, and other plugins. Pyrus fixes this by requiring that all plugins be installed into a centralized location separate from the actual PEAR installation. In addition, installation of plugins cannot happen at the same time as installation of packages, thus the enforced separation ensures a level of security that is much higher than PEAR supports, while preserving the flexibility that extending the installer provides.

Pyrus also feaures true package signing and signature verification using OpenSSL PKCS#12 and X.509 certificates. This allows users to directly verify the validity of a package, protecting from man-in-the-middle attacks and other potential disruptions of a package release. This feature requires the openssl extension, which is not enabled by default.

PEAR supports signing packages using PGP keys, but has no mechanism in place to verify the signed packages. Pyrus will refuse to install a signed package without verifying the signature even if the openssl extension is not enabled.

In addition, the new paranoia setting can be used to control how upgrades are performed to releases that change the API, helping to guarantee safe upgrades to future releases.

Smaller than PEAR

Because Pyrus takes advantage of PHP 5.3's built in support for XML processing, archive handling, and advanced structures through the simplexml, libxml2, phar, sqlite3, and spl extensions, Pyrus is significantly smaller than PEAR, and as a result consumes far less memory to accomplish its tasks.

Faster than PEAR

Pyrus is also faster than PEAR because of its reliance on built-in features of PHP 5.3 and a more structured object-oriented design.

More robust than PEAR

Pyrus has redundant registries in XML and Sqlite3 database formats, as well as support for the existing PEAR registry. Reconstruction of a corrupted registry is simple and fully supported.

In addition, all installation tasks occur within an atomic transaction, including file installation and removal, so that if an installation or uninstall command fails mid-stream, or something as drastic as a power failure occurs, the PEAR installation will be not be left in a half-installed state.

More flexible than PEAR

Pyrus supports cascading installations, so that a system-wide installation of core packages can be recognized. By default, include_path is used to detect PEAR installations, but a different location for a PEAR installation can be passed directly to Pyrus as its first argument.

Convention over configuration allows packages constructed with the new PEAR2 coding standards to be installed simply by extracting the archive, and then later upgraded using Pyrus without the intermediate step of using Pyrus to install the packages. For the first time, this allows a try-before-you-buy approach to be possible.

The same principle also makes bundling a PEAR2 package in another package's source repository possible, and Pyrus can be used to easily upgrade the package or revert to a previous version.

More tested than PEAR

Pyrus has been developed with extensive unit testing and xdebug coverage data has been used to verify that the code is being executed. As a result, the first alpha release of Pyrus has 10% higher code coverage than the most recent stable version of the PEAR Installer.

Configuration files

One of the most important conceptual changes in Pyrus is how configuration is handled. PEAR was designed to handle at most 2 installations by default, a system and a user PEAR installation, and it excels at this. As soon as PEAR is used on multiple installations, a separate configuration file must be specified (as in pear -c /path/to/another/pear.conf install blah). This leads to what is colloquially referred to as "config hell", where it is easy to accidentally install things into the wrong place without realizing it. Pyrus's configuration handling is specifically engineered to eliminate config hell, and to make handling multiple PEAR installations simple.

PEAR stores all configuration values in a single configuration file, and allows specifying a different configuration file for different setups. In addition, PEAR supports automatic cascade of a system configuration file and a user configuration file. The configuration values are used when installing applications, and for customizing things like the path to php in the PEAR Installer's pear command. Configuration files are stored separate from the PEAR installations that they represent.

Pyrus instead splits up configuration files into two separate components: one file contains user customizations such as the preferred stability of packages to install, the username and password for logging into a channel, the verbose setting and so on. Configuration variables that affect where to install files are stored in a separate configuration that is tightly bound to the PEAR installation.

Thus, a PEAR configuration setup might look like:

  • System configuration in /etc/pear.conf, defines php_dir as /usr/local/lib/php

  • User configuration in /home/username/.pearrc, defines php_dir as /home/username/pear.

  • include_path is set to /home/username/pear:/usr/local/lib/php.

The equivalent configuration setup with Pyrus would look like:

  • Pyrus-based installation in /usr/local/lib/pear, system configuration stored in /usr/local/pear/.config and php files in /usr/local/lib/pear/php.

  • Another Pyrus-based installation in /home/username/pear, system configuration stored in /home/username/pear/.config and php files in /home/username/pear/php.

  • User configuration in /home/username/.pear/pearconfig.xml.

  • include_path is set to /home/username/pear:/usr/local/lib/pear/php.

By default, Pyrus uses the include_path to locate PEAR installations, but this is configurable with the new user configuration variable my_pear_path, which is a PATH_SEPARATOR separated list of paths to PEAR installations.

In addition, an explicit path can be directly passed to Pyrus:

php pyrus.phar /home/username/pear:/usr/local/lib/pear list-packages

The above command will list the installed packages in both registries in /home/username/pear and in /usr/local/lib/pear/php.

A detailed reference of Pyrus's handling of configuration files is here

Registries

Pyrus fully supports PEAR's registry format, but introduces 2 new registry formats, an sqlite3 database-based registry, and an XML file-based registry. These registries are fully redundant, and can be used to repair or reconstruct a corrupt registry.

In addition, unlike PEAR, which stores the registry in the same directory as the PHP source files, Pyrus stores the registry in its parent directory. Thus, PHP files stored in /usr/local/lib/php have their registry in /usr/local/lib.

Note: For backwards compatibility, an older PEAR registry is always stored in the location the PEAR Installer expects it to be stored.

Pyrus is intelligent enough to detect which registries are present, and to use them. If only an older PEAR registry exists, Pyrus will not automatically upgrade to the newer format. However, the upgrade-registries command is available to convert from an older registry to the newer format.

Some of the benefits of the newer registry format include much speedier processing of a large registry at installation time due to Sqlite3's speedy processing. Additionally, truly safe uninstall-time resolution of dependencies is possible, something that PEAR can only do for relatively simple package dependency trees.

In addition, the XML registry consists of storing the package.xml and channel.xml files for package releases in the same location that they are packaged. This is what makes it possible to extract a package created with Pyrus and then later use Pyrus to upgrade it.

For instance, the hypothetical PEAR2_Foo package from channel pear2.php.net version 1.2.3 will store its package.xml in path .xmlregistry/packages/pear2.php.net/PEAR2_Foo/1.2.3-package.xml inside the archive, so that when it is extracted, it lines up exactly with how the package would look on disk when installed with the XML registry.

package.xml changes

Pyrus no longer supports package.xml version 1.0, although it will include a package.xml version 1.0 in an archive designed to support both earlier PEAR versions and the more recent versions. It does not validate the package.xml, however, and so it is important to validate any older package.xml format using PEAR and not Pyrus.

In addition, Pyrus has introduced support for PEAR2 packages that can be extracted to disk and then later upgraded using Pyrus. To implement this feature, Pyrus transforms paths in a different way from PEAR.

For example, this entry from a package.xml:

   <dir name="php" baseinstalldir="PEAR2">
    <dir name="Pyrus">
     <dir name="Developer">
      <dir name="CoverageAnalyzer">
       <dir name="SourceFile">
        <file role="php" name="PerTest.php"/>
       </dir>
      </dir>
     </dir>
    </dir>
   </dir>

would cause PEAR to install PerTest.php into the relative path PEAR2/php/Pyrus/Developer/CoverageAnalyzer/SourceFile/PerTest.php. Pyrus, however, recognizes that php is actually the default value of the php_dir system configuration variable, and strips it from the path, resulting in PerTest.php being installed into the path: PEAR2/Pyrus/Developer/CoverageAnalyzer/SourceFile/PerTest.php.

To enable this handling, one need only set the <pearinstaller> dependency to version 2.0.0a1 or newer. Pyrus will automatically recognize any package.xml with a <pearinstaller> dependency on any version of the PEAR Installer as an older package.xml, and will not perform the magic removal of configuration values from directories.

No other changes have been made to package.xml handling, except that the default version of package.xml used when generating a package.xml is version 2.1, which has been supported by the PEAR Installer since version 1.5.0.

Extending Pyrus: plugins

The PEAR Installer allowed packages to install custom commands as well as custom file roles and custom file tasks that are used in package.xml. Pyrus also allows this, but the format of plugins is very different. If you are simply a user of PEAR, you probably won't notice the difference, except that some packages that use custom file roles or tasks will not be installable by Pyrus until the maintainer releases an update that will work with both PEAR and Pyrus.

PEAR extensions are installed directly into the location where the PEAR installer is located. Thus, if PEAR is located in /usr/local/lib/php/PEAR, a custom command must install its XML information file and PHP script into /usr/local/lib/php/PEAR/Command, a custom file role must install its XML information file and PHP script into /usr/local/lib/php/PEAR/Installer/Role and a custom file task must install its PHP script into /usr/local/lib/php/PEAR/Task.

Pyrus is distributed as a phar archive, so this model is no longer physically possible, one cannot just magically insert files into the phar archive without considerable pain and annoyance (the phar.readonly INI setting must be disabled by hand). Instead, Pyrus installs all plugins into a location specified by the new plugins_dir user configuration variable. By default, this installs plugins into $HOME/.pear/plugins on unix systems, and My Documents\pear\plugins on Windows.

All plugins to Pyrus now must provide an xml file with one of the three new file roles customcommand, customrole or customtask in package.xml. Pyrus uses the information in the XML file to locate the PHP script that will execute the plugin. In addition, only one plugin is allowed per package, and the first one Pyrus encounters is the one that will be used. More information on custom plugins is provided in the Pyrus plugins section of the manual.

For developers of existing PEAR custom roles/tasks and post-install scripts, a special kind of file role that allows configuration of your package after installation, making your work compatible with Pyrus can be accomplished. See the documentation on Custom Roles, Custom Tasks, and Post-install scripts.

Installing and Building PECL extensions

PEAR's handling of PECL extensions has been somewhat dodgy, with reports of issues with phpize failing, and other problems. Pyrus attempts to fix this through two major changes to the way PECL packages are built and installed.

  1. PECL packages are installed into a new location src/ and then built directly inside this location.

  2. The same tool process used to build extensions by hand is used verbatim by pyrus to build the extension

PECL installation changes

PEAR builds PECL packages by creating a temporary directory, installing all of the source files into this directory, building the extension, harvesting built files, and finally removes the temporary directory. This system works most of the time, but if there is a problem, it is impossible to debug because the sources are removed.

Pyrus solves this by splitting PECL package installation into two components, installation and build. The installation process simply places the source files into a sub-directory of the src_dir configuration variable, and thus makes it possible to debug problems or even apply patches to the source and re-build.

In addition, because installation is separate from the actual building, PECL packages can now implement post-install scripts to handle truly complex configuration of extensions beyond what configure options can handle.

PECL build

The new build command enhances PEAR's package building by directly calling this sequence:

phpize --clean
phpize
./configure [any options specified by <configureoptions>]
make
make install

This is the same sequence one would use to build a PECL extension by hand. In addition, proc_open() is used instead of popen(), which allows better monitoring and control of the processes in question.

Lastly, Pyrus is more cross-platform than PEAR, as it replaces a call to find and xargs with native PHP iteration over the modules directory when listing extension components that were built.

Prev | Differences from the PEAR Installer | Next
Differences from the PEAR Installer | PEAR Manual | Pyrus Post-install scripts: differences from PEAR


Pyrus Post-install scripts: differences from PEAR

Pyrus Post-install scripts: differences from PEAR

Overview

Post-install scripts (documented here and here) are mostly the same in Pyrus with a few important differences.

The XML format in package.xml is identical, so no change need be made to the <paramgroup> or other tags. The script itself should still follow the naming conventions of PEAR. The only real difference is the naming of methods within the script.

PEAR requires that all post-install scripts implement init(), run() and optionally postProcessPrompts(). Pyrus requires post-install scripts to implement init2(), run2(), and optionally postProcessPrompts2(). This allows PEAR and Pyrus-based post-install scripts to co-exist in the same package without difficulty. Note that post-install scripts must be E_STRICT and E_DEPRECATED compliant, otherwise many PHP warnings will be emitted. One way of handling this issue is to put PHP4 non-E_STRICT-compatible code into a separate file and include it dynamically at run-time. The same should be done for any PHP5+ non-PHP4 compatible code if the post-install script is expected to be able to run in PHP 4.

The init2 method

The init2() method should accept two parameters like so:

<?php
function init2($pkg, $lastversion)
{
}
?>

$pkg is an object representing the package, and $lastversion is the last installed version of the package.

The run2 and postProcessPrompts2 methods

These two methods should accept identical parameters to what the PEAR equivalent accepted. The only reason these are called is to allow easy differentiation between what kind of installer is calling the post-install script.

Prev | Differences from the PEAR Installer | Next
Pyrus: Improvements from the PEAR Installer | PEAR Manual | Pyrus Custom Commands: differences from PEAR


Pyrus Custom Commands: differences from PEAR

Pyrus Custom Commands: differences from PEAR

Overview

Custom commands have changed substantially in Pyrus. PEAR commands draw their information from Xml files located in the directory PEAR/Command and require all commands to be implemented in a single file. Pyrus is much more flexible on this account, and extends the custom XML format used to define commands. Because of this difference, it is theoretically possible to create custom commands that will work in both the PEAR Installer and in Pyrus, although the internal implementation of these commands will necessarily be quite different.

The biggest difference between how a custom command is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom commands.

Here is PEAR's version of the xml for the install command:

<commands version="1.0">
 <install>
  <summary>Install Package</summary>
  <function>doInstall</function>
  <shortcut>i</shortcut>
  <options>
   <force>
    <shortopt>f</shortopt>
    <doc>will overwrite newer installed packages</doc>
   </force>
   <loose>
    <shortopt>l</shortopt>
    <doc>do not check for recommended dependency version</doc>
   </loose>
   <nodeps>
    <shortopt>n</shortopt>
    <doc>ignore dependencies, install anyway</doc>
   </nodeps>
   <register-only>
    <shortopt>r</shortopt>
    <doc>do not install files, only register the package as installed</doc>
   </register-only>
   <soft>
    <shortopt>s</shortopt>
    <doc>soft install, fail silently, or upgrade if already installed</doc>
   </soft>
   <nobuild>
    <shortopt>B</shortopt>
    <doc>don&#039;t build C extensions</doc>
   </nobuild>
   <nocompress>
    <shortopt>Z</shortopt>
    <doc>request uncompressed files when downloading</doc>
   </nocompress>
   <installroot>
    <shortopt>R</shortopt>
    <doc>root directory used when installing files (ala PHP&#039;s INSTALL_ROOT), use packagingroot for RPM</doc>
    <arg>DIR</arg>
   </installroot>
   <packagingroot>
    <shortopt>P</shortopt>
    <doc>root directory used when packaging files, like RPM packaging</doc>
    <arg>DIR</arg>
   </packagingroot>
   <ignore-errors>
    <shortopt></shortopt>
    <doc>force install even if there were errors</doc>
   </ignore-errors>
   <alldeps>
    <shortopt>a</shortopt>
    <doc>install all required and optional dependencies</doc>
   </alldeps>
   <onlyreqdeps>
    <shortopt>o</shortopt>
    <doc>install all required dependencies</doc>
   </onlyreqdeps>
   <offline>
    <shortopt>O</shortopt>
    <doc>do not attempt to download any urls or contact channels</doc>
   </offline>
   <pretend>
    <shortopt>p</shortopt>
    <doc>Only list the packages that would be downloaded</doc>
   </pretend>
  </options>
  <doc>[channel/]&lt;package&gt; ...
Installs one or more PEAR packages.  You can specify a package to
install in four ways:

&quot;Package-1.0.tgz&quot; : installs from a local file

&quot;http://example.com/Package-1.0.tgz&quot; : installs from
anywhere on the net.

&quot;package.xml&quot; : installs the package described in
package.xml.  Useful for testing, or for wrapping a PEAR package in
another package manager such as RPM.

&quot;Package[-version/state][.tar]&quot; : queries your default channel&#039;s server
({config master_server}) and downloads the newest package with
the preferred quality/state ({config preferred_state}).

To retrieve Package version 1.1, use &quot;Package-1.1,&quot; to retrieve
Package state beta, use &quot;Package-beta.&quot;  To retrieve an uncompressed
file, append .tar (make sure there is no file by the same name first)

To download a package from another channel, prefix with the channel name like
&quot;channel/Package&quot;

More than one package may be specified at once.  It is ok to mix these
four ways of specifying packages.
</doc>
 </install>
  </commands>

And the same command as implemented in Pyrus:

<?xml version="1.0" encoding="UTF-8"?>
<commands version="2.0" xmlns="http://pear2.php.net/dtd/customcommand-2.0">
 <command>
  <name>install</name>
  <class>PEAR2_Pyrus_ScriptFrontend_Commands</class>
  <function>install</function>
  <summary>Install a package.  Use install --plugin to install plugins</summary>
  <shortcut>i</shortcut>
  <options>
   <option>
    <name>plugin</name>
    <shortopt>p</shortopt>
    <type><bool/></type>
    <doc>Manage plugin installation only</doc>
   </option>
   <option>
    <name>packagingroot</name>
    <shortopt>r</shortopt>
    <type><string/></type>
    <doc>Install the package in a directory in preparation for packaging with tools like RPM</doc>
   </option>
   <option>
    <name>optionaldeps</name>
    <shortopt>o</shortopt>
    <type><bool/></type>
    <doc>Automatically download and install all optional dependencies</doc>
   </option>
   <option>
    <name>force</name>
    <shortopt>f</shortopt>
    <type><bool/></type>
    <doc>Force the installation to proceed independent of errors.  USE SPARINGLY.</doc>
   </option>
  </options>
  <arguments>
   <argument>
    <name>package</name>
    <multiple>1</multiple>
    <optional>0</optional>
    <doc>package.xml, local package archive, remove package archive, or abstract package.</doc>
   </argument>
  </arguments>
  <doc>Installs listed packages.

local package.xml example:
php pyrus.phar install package.xml

local package archive example:
php pyrus.phar install PackageName-1.2.0.tar

remote package archive example:
php pyrus.phar install http://www.example.com/PackageName-1.2.0.tgz

Examples of an abstract package:
php pyrus.phar install PackageName
 installs PackageName from the default channel with stability preferred_state
php pyrus.phar pear/PackageName
 installs PackageName from the pear.php.net channel with stability preferred_state
php pyrus.phar install channel://doc.php.net/PackageName
 installs PackageName from the doc.php.net channel with stability preferred_state
php pyrus.phar install PackageName-beta
 installs PackageName from the default channel, beta or stable stability
php pyrus.phar install PackageName-1.2.0
 installs PackageName from the default channel, version 1.2.0</doc>
 </command>
</commands>

The format for commands in Pyrus is much more fine-grained, and provides both better validation and better presentation of options and arguments as passed in from the user. In addition, Pyrus allows fine-grained specification of where a command is located, and automatically registers an autoloader to load the class implementing the command, and any dependent classes in the same location.

The details of new tags like <classprefix> and <autoloadpath> are documented in the full documentation of custom roles here.

This XML metadata file is identified by Pyrus through the use of the file role customcommand, which is used in the custom command's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="commands.xml" role="customcommand"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...
Prev | Differences from the PEAR Installer | Next
Pyrus Post-install scripts: differences from PEAR | PEAR Manual | Pyrus Custom File Roles: differences from PEAR


Pyrus Custom File Roles: differences from PEAR

Pyrus Custom File Roles: differences from PEAR

Overview

Custom file roles (documented here) have changed substantially in Pyrus. Fortunately, the usage of roles in package.xml remains unchanged, and Pyrus's expectation of custom role implementation does not conflict or overlap with PEAR's at all, so custom role packages can easily be designed to work with both PEAR and Pyrus.

The biggest difference between how a custom role is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom roles.

Pyrus modifies the XML description file for custom file roles slightly, here is the PEAR version of a role:

<role version="1.0">
 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
 <releasetypes>zendextsrc</releasetypes>
 <releasetypes>zendextbin</releasetypes>
 <installable>1</installable>
 <locationconfig>php_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <phpfile>1</phpfile>
 <executable />
 <phpextension />
 <config_vars />
</role>

And the same role as implemented in Pyrus:

<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
 <name>php</name>
 <class>PEAR2_Pyrus_Installer_Role_Php</class>
 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
 <releasetypes>zendextsrc</releasetypes>
 <releasetypes>zendextbin</releasetypes>
 <installable>1</installable>
 <locationconfig>php_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <executable />
</role>

The most obvious difference is that Pyrus now includes the name of the role, PEAR extracts the role name from the name of the file (which in the example above was Php.xml). In addition, the <phpfile> and <phpextension> elements have been removed.

The details of new tags like <class> and <autoloadpath> are documented in the full documentation of custom roles here.

This XML metadata file is identified by Pyrus through the use of the file role customrole, which is used in the custom role's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="myrole.xml" role="customrole"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...
Prev | Differences from the PEAR Installer | Next
Pyrus Custom Commands: differences from PEAR | PEAR Manual | Pyrus Custom File Tasks: differences from PEAR


Pyrus Custom File Tasks: differences from PEAR

Pyrus Custom File Tasks: differences from PEAR

Overview

Custom file tasks (documented here) have changed substantially in Pyrus. Fortunately, the XML format of tasks used in package.xml remains the same, and Pyrus's expectation of custom task implementation does not conflict or overlap with PEAR's at all, so custom task packages can easily be designed to work with both PEAR and Pyrus.

The biggest difference between how a custom task is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom tasks.

In PEAR, custom tasks are detected simply by scanning the PEAR/Tasks directory, and no differentiation is made between tasks built into PEAR, and external custom tasks.

Pyrus custom tasks are detected through the use a new XML metadata format. The format is simple, and looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<task xmlns="http://pear2.php.net/dtd/customtask-2.0" version="2.0">
 <name>mytask</name>
 <classprefix>vendor_PackageName</classprefix>
 <autoloadpath/>
</task>

The details of what <classprefix> and <autoloadpath> mean are revealed in the full documentation of custom tasks here.

This XML metadata file is identified by Pyrus through the use of the file role customtask, which is used in the custom task's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="mytask.xml" role="customtask"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...
Prev | Differences from the PEAR Installer | Next
Pyrus Custom File Roles: differences from PEAR | PEAR Manual | Creating plugins for Pyrus


Creating plugins for Pyrus

Creating plugins for Pyrus

Table of Contents
  • Telling Pyrus how to load your plugin: <class> and <autoloadpath>
  • Pyrus plugins: custom commands
  • Pyrus plugins: custom file roles
  • Pyrus plugins: custom file tasks

Edited By

Gregory Beaver

2009-06-16

Pyrus defines three kinds of plugins: commands, file roles, and file tasks. Commands add new commands to a frontend for Pyrus, file roles and file tasks add new features to package.xml.

Pyrus, by necessity, requires a clear separation between its plugins and its core. This is because Pyrus is distributed as a phar archive, which cannot be modified without jumping through several hoops. For this reason, plugins are installed in a special directory whose location is specified by the plugins_dir user configuration variable.

Pyrus also makes a clear separation between regular packages and plugin packages. Plugins must be installed separate from any non-plugin packages using the --plugin option of the install, upgrade, and uninstall command. Here is an example, installing the developer tools plugin:

php pyrus.phar install -p PEAR2_Pyrus_Developer

Pyrus defines a plugin as any package that contains one of the three file roles that identify a plugin: customcommand, customrole, or customtask. In addition, a plugin package can only contain one plugin. This helps users by mapping one package to one plugin so that when they list plugin packages, it clearly shows all of the plugins that are installed.

A plugin's definition is handled by an XML file, which must be referenced using one of the three plugin file roles in package.xml. Here is an example identifying a custom command in package.xml:

...
  <dir name="/">
   <dir name="customcommand" baseinstalldir="/">
    <file role="customcommand" name="commands.xml"/>
   </dir>
...
Prev | Using Pyrus, the PEAR Installer for PHP 5.3+ | Next
Pyrus Custom File Tasks: differences from PEAR | PEAR Manual | Telling Pyrus how to load your plugin: <class> and <autoloadpath>


Telling Pyrus how to load your plugin: <class> and <autoloadpath>

Telling Pyrus how to load your plugin: <class> and <autoloadpath>

Pyrus relies upon PHP5's autoloading capabilities to automatically load a plugin class. All plugins should include the <autoloadpath> element to specify a path relative to the php_dir location for the plugin registry. For plugin classes that conform to PEAR2 standards, the autoloadpath should be an empty string:

<autoloadpath></autoloadpath>

The pyrus autoloader will automatically replace _ and the namespace separator \ with DIRECTORY_SEPARATOR and append .php to determine the class name to load. To instruct Pyrus to prepend a particular relative path, put this path in the <autoloadpath> element. As an example, the following XML will prompt Pyrus to load the file /home/user/.pear/MyPackage/customcommands/Command/Line/Obj.php if the user's plugins_dir is /home/user/.pear:

<autoloadpath>MyPackage/customcommands</autoloadpath>
<class>Command_Line\Obj</class>

The <class> element is used by Pyrus to determine which object to instantiate. If <class> is:

<class>FooBar_Willy\Dilly</class>

Pyrus will instantiate an object of class FooBar_Willy\Dilly.

Prev | Creating plugins for Pyrus | Next
Creating plugins for Pyrus | PEAR Manual | Pyrus plugins: custom commands


Pyrus plugins: custom commands

Pyrus plugins: custom commands

Introduction

Custom commands add new functionality to pyrus.phar. An example of a plugin that implements custom commands is the PEAR2_Pyrus_Developer package, which implements the make, package, pickle, and run-phpt commands.

Custom command plugins can implement multiple commands, and are defined by an xml file that is noted in package.xml with the customcommand file role. The XML format is defined and validated by pyrus with the customcommand.xsd XSchema file.

Command Arguments and Options: a brief primer

Commands can have arguments and options. Here is an example of a command with a single argument:

php pyrus.phar install PackageName

The command is install, and the argument is PackageName.

Here is an example of a command with multiple arguments:

php pyrus.phar install PackageName package.xml http://example.com/Foo.tgz

The command is install, and the arguments are PackageName, package.xml and http://example.com/Foo.tgz.

An option is a special argument that is preceded by 1-2 dashes (- or --). Short arguments are single letters preceded by a dash, and long arguments are words preceded by two dashes. Here is an example of a command with both a short and a long option

php pyrus.phar package -p --tar

The command is package, the short option is -p and the long option is --tar. Short options are aliases for long options. For the package command, the -p short option is an alias to the --phar long option.

Options can also accept arguments in 2 formats. If an option accepts an argument, there are two ways of passing that argument. Short options consider the next argument to be their argument:

php pyrus.phar install -r /path/to/packagingroot PackageName

/path/to/packagingroot is the argument to the short option -r, PackageName is the argument to the install command.

Long options require an = sign in between the option and the argument as in:

php pyrus.phar install --packagingroot=/path/to/packagingroot PackageName

/path/to/packagingroot is the argument to the long option --packagingroot, PackageName is the argument to the install command.

Overview of the Custom Command XML Format

Here is a human-readable overview of a custom command's XML definition file. Optional tags are enclosed in [brackets]. If there is a choice of tags, they are separated by a vertical line | and enclosed in parentheses like (<this>|<example>).

<?xml version="1.0" encoding="UTF-8"?>
<commands version="2.0" xmlns="http://pear2.php.net/dtd/customcommand-2.0">
 <command>
  <name>commandname</name>
  <class>CommandClass\Name</class>
  <function>makePackageXml</function>
[ <webfunction>webCommand</webfunction>]
[ <gtkfunction>gtkCommand</gtkfunction>]
[ <autoloadpath>CommandClass</autoloadpath>]
  <summary>Short description of command purpose</summary>
  <shortcut>CN</shortcut>
  <options>
  [<option>
    <name>optionname</name>
    <shortopt>O</shortopt>
    <type>(<bool/>|<string/>|<int/>|<float/>|<counter/>|
           <callback>optionProcessorCallback</callback>|
           <set><value>value1</value><value>value2</value>...</set>)</type>
   [<default>defaultvalue</default>]
    <doc>Short description of option purpose</doc>
   </option>]
  </options>
  <arguments>
  [<argument>
    <name>argname</name>
    <multiple>0</multiple>
    <optional>1</optional>
    <doc>Short argument description</doc>
   </argument>]
  </arguments>
  <doc>
Long description of command usage for help output
  </doc>
 </command>
</commands>

A command need not require or accept any arguments or options, and can accept multiple arguments and multiple options. In addition, a custom command definition XML file may declare multiple commands.

Commands can also implement a shortcut, which is a shorter alias. The upgrade command, for instance, has a shortcut of up.

By convention, all command names of external projects should be prefixed with the vendor name. For instance, if the vendor is Zend Framework, commands should be prefixed with something like zf- or with zend-. An install command would be zf-install.

In addition, all shortcuts from external vendors should be upper-cased and consist of the first letter of the vendor, and the first two letters of the command. zf-install would have a shortcut of Zin. This helps to avoid name collisions between vendors.

Telling Pyrus how to load your command: <class> and <autoloadpath>

This is the same method used for all plugins, and is documented here.

The three frontend command handlers are discussed in the CLI section, Web section, and the Gtk section.

Defining arguments

Pyrus recognizes both optional and required arguments, as well as the ability to specify repeating arguments. The logic is very similar to function signatures in PHP. Each argument is placed by name into an associative array and passed to the function. Note that invalid input is not passed to custom commands, so a command can assume valid input if it is called.

Here is a sample argument definition and the way that Pyrus will handle different valid inputs for the hypothetical foo command:

 <arguments>
  <argument>
   <name>argname</name>
   <multiple>0</multiple>
   <optional>0</optional>
   <doc>required arg</doc>
  </argument>
  <argument>
   <name>argname2</name>
   <multiple>0</multiple>
   <optional>1</optional>
   <doc>optional arg</doc>
  </argument>
  <argument>
   <name>argname3</name>
   <multiple>1</multiple>
   <optional>1</optional>
   <doc>optional arg, multiple</doc>
  </argument>
 </arguments>
php pyrus.phar foo arg1
<?php
function foo($frontend, $args, $options)
    {
        // $args = array('argname' => 'arg1')
    }
?>
php pyrus.phar foo arg1 arg2
<?php
function foo($frontend, $args, $options)
    {
        // $args = array('argname' => 'arg1', 'argname2' => 'arg2')
    }
?>
php pyrus.phar foo arg1 arg2 arg3
<?php
function foo($frontend, $args, $options)
    {
        // $args = array('argname' => 'arg1', 'argname2' => 'arg2', 'argname3' => array('arg3'))
    }
?>
php pyrus.phar foo arg1 arg2 arg3 arg4
<?php
function foo($frontend, $args, $options)
    {
        // $args = array('argname' => 'arg1', 'argname2' => 'arg2', 'argname3' => array('arg3', 'arg4'))
    }
?>

Defining options

Options must define a short and a long option, a type for the option, and a short description of the option for help text.

Options fall into two categories, those that accept arguments, and those that don't. Options that don't accept arguments are of type <bool/> and <counter/>.

The types recognized are:

  • <bool/>

  • <counter/>

  • <string/>

  • <int/>

  • <float/>

  • <callback></callback>

  • <set></set>

<bool/>

A <bool/> option sets its value to TRUE if present, and FALSE if not.

  <options>
   <option>
    <name>nocompatible</name>
    <shortopt>n</shortopt>
    <type><bool/></type>
    <doc>Do not generate package_compatible.xml</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('nocompatible' => false)
    }
?>
php pyrus.phar foo -n
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('nocompatible' => true)
    }
?>
php pyrus.phar foo --nocompatible
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('nocompatible' => true)
    }
?>

<counter/>

A <counter/> option sets its value to 0 if not present, and to the number of times the option is present if it is. This is the only option type for which multiple occurrences of the option are allowed.

  <options>
   <option>
    <name>verbose</name>
    <shortopt>v</shortopt>
    <type><counter/></type>
    <doc>How verbose to be with output</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('verbose' => 0)
    }
?>
php pyrus.phar foo -v
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('verbose' => 1)
    }
?>
php pyrus.phar foo --verbose -vv --verbose
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('verbose' => 4)
    }
?>

<string/>

A <string/> option sets its value to the argument passed in if present, or to NULL if not present.

  <options>
   <option>
    <name>name</name>
    <shortopt>n</shortopt>
    <type><string/></type>
    <doc>Name of foo</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('name' => null)
    }
?>
php pyrus.phar foo -n myname
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('name' => 'myname')
    }
?>
php pyrus.phar foo --name=myname
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('name' => 'myname')
    }
?>

<int/>

An <int/> option sets its value to the integer argument passed in if present, or to NULL if not present.

  <options>
   <option>
    <name>namecount</name>
    <shortopt>n</shortopt>
    <type><int/></type>
    <doc>Number of foo names</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('namecount' => null)
    }
?>
php pyrus.phar foo -n 3
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('namecount' => 3)
    }
?>
php pyrus.phar foo --namecount=3
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('namecount' => 3)
    }
?>

<float/>

A <float/> option sets its value to the float argument passed in if present, or to NULL if not present.

  <options>
   <option>
    <name>foopercent</name>
    <shortopt>f</shortopt>
    <type><float/></type>
    <doc>Foo percent in decimal notation</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('foopercent' => null)
    }
?>
php pyrus.phar foo -f .2
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('foopercent' => 0.2)
    }
?>
php pyrus.phar foo --foopercent=0.3
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('foopercent' => 0.3)
    }
?>

<callback></callback>

A <callback/> option calls the specified callback with the value passed in by the user as a string. The callback must be a static method in the same class that implements the command.

  <options>
   <option>
    <name>foocallback</name>
    <shortopt>f</shortopt>
    <type><callback>processfoo</callback></type>
    <doc>Foo date</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('foocallback' => null)
    }

    static function processfoo($value)
    {
        // $value = null
        return null;
    }
?>
php pyrus.phar foo -f 2009-12-31
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('foocallback' => new DateTime('2009-12-31', new DateTimeZone('UTC')))
    }

    static function processfoo($value)
    {
        // $value = '2009-12-31';
        $date = new DateTime($value, new DateTimeZone('UTC'));
        return $date;
    }
?>
php pyrus.phar foo --foocallback=2009-12-31
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('foocallback' => new DateTime('2009-12-31', new DateTimeZone('UTC')))
    }

    static function processfoo($value)
    {
        // $value = '2009-12-31';
        $date = new DateTime($value, new DateTimeZone('UTC'));
        return $date;
    }
?>

<set></set>

A <set/> option sets its value to NULL if not present. Otherwise it ensures that the value passed in by the user is within a pre-defined acceptable list of values.

  <options>
   <option>
    <name>numbah</name>
    <shortopt>n</shortopt>
    <type>
     <set>
      <value>one</value>
      <value>two</value>
      <value>three</value>
      <value>four</value>
     </set>
    </type>
    <doc>Numbers less than five</doc>
   </option>
  </options>
php pyrus.phar foo
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('numbah' => null)
    }
?>
php pyrus.phar foo -n four
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('numbah' => 'four')
    }
?>
php pyrus.phar foo --numbah=one
<?php
function foo($frontend, $args, $options)
    {
        // $options = array('numbah' => 'one')
    }
?>

Declaring CLI command method

A class must implement a command-line handler, which should have this method signature:

<?php
function commandhandler($frontend, $args, $options)
    {
        // perform command here
    }
?>

The first argument is the CLI frontend, and can be used for asking the user a question with the ask() method, or passing control to a built-in command. $args is an associative array of arguments. Only required arguments are guaranteed to be present, all optional arguments must be verified as present before using. $options is an associative array of options. All options will be present, those not present will be initialized to NULL.

Options should be accessed using their long names, and arguments using their names (see examples in the documentation sections for arguments and options above).

The ask() method accepts 3 arguments:

  1. string $question the question to ask the user. It should end in a question mark

  2. (optional) array $choices an array of possible answers

  3. (optional) string $default the default answer

Declaring Web command method

Although a Web frontend has not yet been written for Pyrus, the XML command format supports the eventual addition of a Web frontend. A separate method should be used for the Web handling, and is named via the <webfunction> tag.

Declaring GTK command method

Although a GTK frontend has not yet been written for Pyrus, the XML command format supports the eventual addition of a GTK frontend. A separate method should be used for the GTK handling, and is named via the <gtkfunction> tag.

Prev | Creating plugins for Pyrus | Next
Telling Pyrus how to load your plugin: <class> and <autoloadpath> | PEAR Manual | Pyrus plugins: custom file roles


Pyrus plugins: custom file roles

Pyrus plugins: custom file roles

Introduction

If you are not familiar with how file roles install, read the introduction to file roles first. This segment of the documentation assumes you are familiar with concepts such as baseinstalldir and with what a file role means in terms of installation location.

Custom file roles can implement a single role, and are defined by an xml file that is noted in package.xml with the customrole file role. The XML format is defined and validated by pyrus with the customrole-2.0.xsd XSchema file.

Here is a human-readable custom file role xml file definition. Optional elements are enclosed in [brackets], and if there is a choice of values, they are delimited with a vertical bar | and enclosed in (parentheses).

<?xml version="1.0" encoding="UTF-8"?>
<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
 <name>rolename</name>
 <class>MyPlugin_Rolename</class>
[<validationmethod>validate</validationmethod>]
[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
(<releasetype>php</releasetype>|<releasetype>extsrc</releasetype>|
 <releasetype>extbin</releasetype>|<releasetype>zendextsrc</releasetype>|
 <releasetype>zendextbin</releasetype>)
 <installable>(1|0)</installable>
 <locationconfig>config_var</locationconfig>
 <honorsbaseinstall>(1|0)</honorsbaseinstall>
 <unusualbaseinstall>(1|0)</unusualbaseinstall>
 <executable>(1|0)</executable>
[<configvar>
  <name>config_name</name>
  <type>string</type>
  <default>
   <![CDATA[
    <?php $default = 'hi'; ?>
   ]]>
  </default>
  <doc>Extensive, multi-line documentation</doc>
 [<validset>val1</validset><validset>val2</validset>...]
  <prompt>summary documentation</prompt>
  <group>Custom</group>
  <configtype>(system|user|channel-specific)</configtype>
 </configvar>]*
</role>

Telling Pyrus how to load your role: <class> and <autoloadpath>

This is the same method used for all plugins, and is documented here.

Validating your custom role at packaging time

Some roles benefit from the ability to validate the files they represent at packaging time. For instance, a customcommand file is checked to ensure it conforms to its XML schema, so that a custom command with invalid XML cannot be distributed by mistake.

By convention, a validation method should be named validate, although the xml supports any name. The method name should be placed in the <validationmethod tag, and the method itself should have the same method signature as this example from Pyrus's customrole validation:

<?php
function validate(PEAR2_Pyrus_IPackage $package, array $file)
    {
        $parser = new PEAR2_Pyrus_XMLParser;
        $schemapath = PEAR2_Pyrus::getDataPath();
        if (!file_exists(PEAR2_Pyrus::getDataPath() . '/customrole-2.0.xsd')) {
            $schemapath = realpath(__DIR__ . '/../../../../data');
        }
        $taskschema = $schemapath . '/customrole-2.0.xsd';
        try {
            $taskinfo = $parser->parse($package->getFilePath($file['attribs']['name']), $taskschema);
        } catch (Exception $e) {
            throw new PEAR2_Pyrus_Installer_Role_Exception('Invalid custom role definition file,' .
                                                           ' file does not conform to the schema', $e);
        }
    }
?>

A custom file role package-time validator should throw a PEAR2_Pyrus_Installer_Role_Exception exception object with an error message describing the reason for validation failure, or simply return on success.

Release Types and file roles

The <releasetype> element is used to tell Pyrus which releases can contain a file with this role. For instance, the src role only has meaning in a PHP extension source release, and is only allowed in extsrc and zendextsrc release types.

There are 5 release types that Pyrus recognizes:

  • php - this is for PEAR-style packages distributing PHP code

  • extsrc - this is for PHP extension source packages

  • extbin - this is for PHP extension binary packages

  • zendextsrc - this is for PHP Zend extension source packages

  • zendextbin - this is for PHP Zend extension binary packages

<installable>

If set to 0, the file will not actually be installed onto the system. Most file roles should set this to 1.

<locationconfig>

This element is used to tell Pyrus which configuration variable should be used to determine where to install the file. This can be a custom configuration variable.

<honorsbaseinstall> and <unusualbaseinstall>

The <honorsbaseinstall> element tells Pyrus to honor the baseinstalldir attribute (documentation on baseinstalldir is here) for roles like php.

The <unusualbaseinstall> element tells Pyrus to honor the baseinstalldir attribute for roles like data that also prepend channel/package name to the installation location.

<executable>

If <executable> is set to 1, Pyrus will make the installed file an executable file on unix systems (the equivalent of

chmod +x filename

).

Defining custom configuration variables

A custom file role can optionally define a single or multiple custom configuration variables. There are 3 kinds of configuration variables that Pyrus supports, system, user and channel-specific. Documentation on configuration is available here. Read that before continuing in order to understand how different configuration variables work.

Pyrus supports one type of configuration variable: string. The values can be restricted to a specific set of values with the <validset> element.

Prev | Creating plugins for Pyrus | Next
Pyrus plugins: custom commands | PEAR Manual | Pyrus plugins: custom file tasks


Pyrus plugins: custom file tasks

Pyrus plugins: custom file tasks

Introduction

If you are not familiar with how file tasks work, read the introduction to file tasks first.

Custom file tasks can implement a single task, and are defined by an xml file that is noted in package.xml with the customtask file role. The XML format is defined and validated by pyrus with the customtask-2.0.xsd XSchema file.

Here is a human-readable custom file task xml file definition. Optional elements are enclosed in [brackets].

<?xml version="1.0" encoding="UTF-8"?>
<task version="2.0" xmlns="http://pear2.php.net/dtd/customtask-2.0">
 <name>taskname</name>
 <class>MyPlugin_Taskname</class>
[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
</task>

Telling Pyrus how to load your task: <class> and <autoloadpath>

This is the same method used for all plugins, and is documented here.

Defining the task: the task class

A custom file task must extend the PEAR2_Pyrus_Task_Common class, and must implement a few methods:

  • validateXml()

  • startSession()

Optionally, __construct() may be used to do special pre-processing, storing of information or other setup tasks.

A task must also define two class constants, TYPE and PHASE. TYPE should be one of 'simple' or 'script'. 'script' tasks are post-install scripts, and are executed by the run-scripts command. 'simple' tasks are executed while installation is in progress.

PHASE should be one of:

  • PEAR2_Pyrus_Task_Common::PACKAGE

  • PEAR2_Pyrus_Task_Common::INSTALL

  • PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL

  • PEAR2_Pyrus_Task_Common::POSTINSTALL

PEAR2_Pyrus_Task_Common::POSTINSTALL is only used by post-install scripts, the other 3 are used to determine at what time the task should be called. If your custom task only works at installation-time, use PEAR2_Pyrus_Task_Common::INSTALL. If the task can perform only at package time (this is exceedingly rare), use PEAR2_Pyrus_Task_Common::PACKAGE. Most tasks should use PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL. If your task can perform its task at packaging time, then you should override the isPreProcessed() method and return true. Some tasks, such as the replace task, perform some of their actions at package time, and the rest at install time. The isPreProcessed() method should only return true if the XML of the specific task could be processed at package time.

The startSession() method is used to actually execute the task, and is passed a read/write file resource that is set to the beginning of the file being installed. The full path of the file's final installation location is also passed in, and can be used for throwing exceptions. All errors should be handled by throwing a PEAR2_Pyrus_Task_Exception or one of its descendants.

The validateXml() method should validate the XML as represented in an array format. The array uses associative arrays for tags, the attribs index for attributes, and for a tag with both attributes and content, the _content index contains the content. If present, the tasks: namespace is removed from the tags prior to passing to validateXml(). On encountering validation errors, the method should throw one of the four exceptions in the example below.

Example Custom Task

<?php
class MyPlugin_Taskname extends PEAR2_Pyrus_Task_Common
{
    const TYPE = 'simple';
    const PHASE = PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL;

    /**
     * Initialize a task instance with the parameters
     * @param array raw, parsed xml
     * @param array attributes from the <file> tag containing this task
     * @param string|null last installed version of this package
     */
    function __construct($pkg, $phase, $xml, $attribs, $lastversion)
    {
        parent::__construct($pkg, $phase, $xml, $attribs, $lastversion);
        // do any special parsing of attributes/contents here
        // phase is one of PEAR2_Pyrus_Task_Common::PACKAGE,
        // PEAR2_Pyrus_Task_Common::INSTALL, or
        // PEAR2_Pyrus_Task_Common::POSTINSTALL
    }

    /**
     * Validate the basic contents of a <taskname> tag
     * @param PEAR_Pyrus_IPackageFile
     * @param array
     * @param array the entire parsed <file> tag
     * @param string the filename of the package.xml
     * @throws PEAR2_Pyrus_Task_Exception_InvalidTask
     * @throws PEAR2_Pyrus_Task_Exception_NoAttributes
     * @throws PEAR2_Pyrus_Task_Exception_MissingAttribute
     * @throws PEAR2_Pyrus_Task_Exception_WrongAttributeValue
     */
    static function validateXml(PEAR2_Pyrus_IPackage $pkg, $xml, $fileXml, $file)
    {
        if (!isset($xml['attribs'])) {
            throw new PEAR2_Pyrus_Task_Exception_NoAttributes('taskname', $file);
        }
        if (!isset($xml['attribs']['attributename'])) {
            throw new PEAR2_Pyrus_Task_Exception_MissingAttribute('taskname',
                                                                  $attrib, $file);
        }
        if ($xml['attribs']['attributename'] != 'hi'
            && $xml['attribs']['attributename'] != 'bye') {
            throw new PEAR2_Pyrus_Task_Exception_WrongAttributeValue('taskname',
                                                                     'attributename',
                                                                     $xml['attribs']['attributename'],
                                                                     $file,
                                                                     array('hi', 'bye'));
            }
        }
        if (MyPlugin_Other_Class::somecondition()) {
            throw new PEAR2_Pyrus_Task_Exception_InvalidTask(
                'general validation errors should use this exception');
        }
        return true;
    }

    /**
     * Perform the taskname task
     * @param PEAR2_Pyrus_IPackage
     * @param resource open file pointer, set to the beginning of the file
     * @param string the eventual final file location (informational only)
     * @return string|false
     */
    function startSession($fp, $dest)
    {
        // use PEAR2_Pyrus_Log::log() to send messages to the user
        PEAR2_Pyrus_Log::log(3, 'doing stuff');
        PEAR2_Pyrus_Log::log(0, 'doing more important stuff');
        // operate directly on the file pointer
        $contents = stream_get_contents($fp);
        $contents .= 'hi';
        rewind($fp);
        ftruncate($fp, 0);
        fwrite($fp, $contents);
        return true;
    }

    /**
     * This is used to tell the installer to skip a task that has already been
     * executed.
     *
     * For example, package-info replacement tasks are performed at packaging
     * time, and do not need to be re-applied on installation
     * @return bool true if task has already been executed on the file at
     *              packaging time
     */
    function isPreProcessed()
    {
        // do not implement this method unless your task does its processing
        // at package-time!
        return true;
    }
}
?>
Prev | Creating plugins for Pyrus | Next
Pyrus plugins: custom file roles | PEAR Manual | Developer Tools for Pyrus


Developer Tools for Pyrus

Developer Tools for Pyrus

Table of Contents
  • Using Pyrus to create PEAR2 packages
  • Using Pyrus to create PEAR packages
  • Using Pyrus to create PECL packages

Edited By

Gregory Beaver

2009-06-16

How to use Pyrus to develop packages for installation by Pyrus. This documentation is a work in progress.

Prev | Using Pyrus, the PEAR Installer for PHP 5.3+ | Next
Pyrus plugins: custom file tasks | PEAR Manual | Using Pyrus to create PEAR2 packages


Using Pyrus to create PEAR2 packages

Using Pyrus to create PEAR2 packages

Introduction

Pyrus is particularly well-suited to maintaining a PEAR2 package, and can be used to easily create a package.xml with the make command. Once the requisite files are in place for this command, creating a release is as simple as

php -dphar.readonly=0 pyrus.phar make -pphar,tar,tgz,zip
Prev | Developer Tools for Pyrus | Next
Developer Tools for Pyrus | PEAR Manual | Using Pyrus to create PEAR packages


Using Pyrus to create PEAR packages

Using Pyrus to create PEAR packages

Introduction

Using Pyrus to manage your existing PEAR package is simple, although not as easy as managing a PEAR2 package or PECL extension. Generally speaking, the command you will take advantage of the most is the package command, which can be used to create the release needed.

Prev | Developer Tools for Pyrus | Next
Using Pyrus to create PEAR2 packages | PEAR Manual | Using Pyrus to create PECL packages


Using Pyrus to create PECL packages

Using Pyrus to create PECL packages

Introduction

As a PECL developer, managing your extensions could not be simpler with Pyrus. The new pickle command makes creating a package.xml as simple as creating a few text files and then running the command. In addition, the PECL packages created with the pickle command are installable by the most widely installed version of PEAR as well as by the newest versions of PEAR and by Pyrus.

Pyrus's pickle command fully eliminates the need to ever even look at package.xml, greatly simplifying the lives of PECL extension developers.

In addition, the run-phpt command can be used to run all the extension's phpt test files.

Creating a new PECL package with Pyrus

If you are creating a brand new extension, after running a tool such as ext_skel to set up the basic extension, a few extra steps are needed to prepare the extension for installation by Pyrus or the PEAR Installer.

When creating a new extension, first create a file named CREDITS and put your information in the file like so:

;; extensionname
My Name (myhandle) <myemail@php.net> (lead)

Add any additional maintainers using the same format.

Next, create a README file that describes your package. The first line should be a brief summary of what the extension does, and the rest of the file should be a detailed description of information the user should know about the origin of the extension, and perhaps a simple example of its usage.

Next, create a file named RELEASE-0.1.0. Put any release notes in here. Generally initial release is enough information for the first release.

Last, you can optionally create a file named API-0.1.0. Pyrus and the PEAR Installer differentiate between API version and release version, to allow clearly defining an API change or backwards compatibility break. Put information on any API changes into API-0.1.0.

After creating these files, simply run:

php pyrus.phar pickle extensionname

where extensionname is the name of your extension. If you have not yet installed the developer tools, Pyrus will ask if you would like to download and install them. Choose yes and then re-run the command.

Pyrus will create a package.xml and a release called extensionname-0.1.0.tgz, or extensionname-0.1.0.tar if the zlib extension is not enabled. This release can be uploaded to pecl.php.net for immediate distribution.

Note that the directory structure described in pickle command documentation is required for pickle to detect documentation, tests, or data files.

Readying an existing PECL package for Pyrus

To prepare an existing PECL package for Pyrus, you should follow all of the steps in the section Creating a new PECL Package with Pyrus, but instead of creating RELEASE-0.1.0 and API-0.1.0, you would create a file named RELEASE-X.Y.Z where X.Y.Z is the version of the extension. So if your extension's version is 1.2.3 you would create a file named RELEASE-1.2.3. For each of the files above, rather than putting new content, you can copy/paste the existing description, summary and release notes from your existing package.xml. Note that any entities such as &lt; should be converted to their values <, as Pyrus escapes automatically from the text files.

Note that the directory structure described in pickle command documentation is required for pickle to detect documentation, tests, or data files.

Future releases

When the time rolls around for the next release, readying for this is also simple. If you are about to release version 0.2.0, create a file named RELEASE-0.2.0 and put the release notes into the file. Pyrus will automatically detect that 0.2.0 is newer than 0.1.0 and create a new release with those notes.

Prev | Developer Tools for Pyrus | Next
Using Pyrus to create PEAR packages | PEAR Manual | PEAR Developer Guide


PEAR Developer Guide

PEAR Developer Guide

Table of Contents
  • About PEAR and PEAR2
  • Becoming a PEAR developer: how to get involved
  • PEAR Developer Guide
  • Coding Standards
  • PEAR Installer: Core components (Installer API, error handling)
  • PEAR Installer: customizing the installer itself
  • RFCs
Prev |  | Next
Using Pyrus to create PECL packages | PEAR Manual | About PEAR and PEAR2


About PEAR and PEAR2

About PEAR and PEAR2

Table of Contents
  • Introduction
  • Support
  • Contributing
  • FAQ -- FAQ - Frequently Asked Questions
  • Constitution
  • PEAR Group Administrative Documents
Prev | PEAR Developer Guide | Next
PEAR Developer Guide | PEAR Manual | Introduction


Introduction

Introduction

Table of Contents
  • What is PEAR?

The PEAR Manifest

Edited By

Stig Bakken

Edited By

Gregory Beaver

2007-03-14

PEAR is dedicated to Malin Bakken, born 1999-11-21.

Prev | About PEAR and PEAR2 | Next
About PEAR and PEAR2 | PEAR Manual | What is PEAR?


What is PEAR?

What is PEAR?

PEAR is short for "PHP Extension and Application Repository" and is pronounced just like the fruit. The purpose of PEAR is to provide:

  • A structured library of open-source code for PHP users

  • A system for code distribution and package maintenance

  • A standard style for code written in PHP, specified here

  • The PHP Extension Community Library (PECL), see more below

  • A web site, mailing lists and download mirrors to support the PHP/PEAR community

PEAR is a community-driven project governed by its developers. PEAR's governing bodies are subdivided into the PEAR Group, Collectives, and a President. PEAR's constitution (adopted in March 2007) defining these groups is documented here. The PEAR project was founded in 1999 by Stig S. Bakken and quite a lot of people have joined the project.

PEAR Mission Statement

PEAR's mission is to provide reusable components, lead innovation in PHP, provide best practices for PHP development and educate developers.

Structured Libraries and Applications of PHP Code

The code in PEAR is partitioned in "packages". Each package is a separate project with its own development team, version number, release cycle, documentation and a defined relation to other packages (including dependencies). Packages are distributed as gzipped tar files with a description file inside, and installed on your local system using the PEAR installer.

Packages may relate to each other through explicit dependencies, but there is no automatic dependency relationship between packages based on the package name. For example, "HTTP_Post" is by default independent of "HTTP". Dependencies between packages with similar names is not forbidden, and does happen. As an example,the "DB_DataObject" package depends on the "DB" package.

A style guide, the PEAR Coding Standards (short PCS), exists to ease collaboration between PEAR developers, to enforce quality, and to enforce a consistent visual appearance of all source code distributed as a PEAR package.

Code Distribution and Package Maintenance

All PEAR packages are registered in and downloaded from a central server at pear.php.net. Other third-party servers called "channels" also distribute packages that can be installed by the PEAR Installer, see the Channels list for more information. pear.php.net does not endorse the packages from these channels, and only provides support for packages distributed from pear.php.net.

Pear.php.net provides both a human-friendly (HTML) and machine-friendly (currently REST) interface to the packages available from pear.php.net. All communication occurs over the HTTP protocol. Other functions the pear.php.net site provides are:

  • user account management (independent of the CVS server)

  • package management

  • release management

Packages are distributed as a gzipped tar file with an XML description file inside. The description file (package.xml) contains some information about the package, a list of files and their roles, and dependencies.

The PHP Extension Community Library (PECL)

PECL

PECL (pronounced "pickle") is a separate project that distributes PHP extensions (compiled code written in C, such as the PDO extension). PECL extensions are also distributed as packages and can be installed using the PEAR installer with the pecl command.

More information and all PECL packages can now be found on the PECL homepage.

Prev | Introduction | Next
Introduction | PEAR Manual | Support


Support

Support

Table of Contents
  • The mailing lists
  • Web resources
  • #PEAR on IRC

This chapter describes, how you can get support, if you have questions concerning PEAR.

Prev | About PEAR and PEAR2 | Next
What is PEAR? | PEAR Manual | The mailing lists


The mailing lists

The mailing lists

Overview

As in most other open-source projects, the support is done via mailing lists. In our case, we currently have seven PEAR related mailing lists:

  • General list

  • Developers list

  • Documentation list

  • Webmaster list

  • CVS commit list

  • Core list

  • Quality Assurance list

The first four lists are intended to help you, if you have questions. Please read below to get to know, what list fits to your needs. The CVS commit list is intended for people that are contributing to PEAR: All commits to our revision control system (CVS) are sent to this list. The core and QA lists are intended for people that want to take part in the development of PEAR.

You can subscribe to the PEAR mailing lists via this website.

The General mailing list

The PEAR general mailing list is the mailing list, where you ask, if you have a question about installing PEAR, using a certain PEAR package etc.

The list is not a support forum for questions concerning the usage of PHP. Please use php-general@lists.php.net instead.

The Developers mailing list

As the name implies, this list is where the developers of PEAR come together to make decisions, to discuss code and to handle things that are related to PEAR.

If you are not a developer of PEAR itself, this list is of no real interest to you, unless

  • you want to get to know what's going on behind PEAR

  • you want to contribute code to PEAR

  • you have found a bug in a PEAR package and want to supply a patch for that.

The address for this list is pear-dev@lists.php.net.

The documentation mailing list

This list is the place where all the things concerning the PEAR documentation, the manual etc. are discussed.

If you want to help out documenting PEAR packages don't hesitate to drop a mail there.

The QA mailing list

People interested in improving the overall quality of PEAR come together on the QA list.

The Quality Assurance team is always seeking people that want to help. If you are interested, just sign up and announce yourself on the mailing list.

The Webmaster mailing list

If you have found a problem on our website or have a question concerning the site, you can email the guys on pear-webmaster@lists.php.net .

The core mailing list

This list is the place, where the core infrastructure of PEAR is discussed. Members of this list also come from other PHP projects such as PECL and PHP QA, since the PEAR infrastructure is also relevant to these projects (like the PEAR installer, the PEAR website etc.).

Specifically the list is concerned with the following topics:

  • New features for the PEAR website

  • PEAR installer development

  • PEAR standards definition

Prev | Support | Next
Support | PEAR Manual | Web resources


Web resources

Web resources

There are a number of web sites that deal with PEAR. We have compiled a list of them here. If a site is missing, you can email the webmaster.

Prev | Support | Next
The mailing lists | PEAR Manual | #PEAR on IRC


#PEAR on IRC

#PEAR on IRC

The PEAR project has its own IRC channel #PEAR, which is available on EFnet. Come along and meet the gurus, which don't have to pay for their internet connection and can hang around in IRC the whole day.

Prev | Support | Next
Web resources | PEAR Manual | Contributing


Contributing

Contributing

Table of Contents
  • Introduction
  • Writing New Packages
  • Submitting Patches
  • Reporting Bugs
  • Writing & Translating Documentation
  • Wishlists

Edited By

Tal Peer

Edited By

Martin Jansen

Edited By

Daniel Convissor

2004-04-15

This chapter describes the different ways in which one could contribute to PEAR.

Prev | About PEAR and PEAR2 | Next
#PEAR on IRC | PEAR Manual | Introduction


Introduction

Introduction

PEAR is an open source project, which means that everyone can help improving it. Improving doesn't always mean writing code. It can also mean reporting bugs, giving feedback, submitting feature requests and even financial support.

Prev | Contributing | Next
Contributing | PEAR Manual | Writing New Packages


Writing New Packages

Writing New Packages

Explanations about submitting new packages can be found in the Developers' Guide.

Prev | Contributing | Next
Introduction | PEAR Manual | Submitting Patches


Submitting Patches

Submitting Patches

If you have modified a package to expand its functionality or to fix a bug, you should contribute your changes back to the community (some licenses force you to do so, and it is generally considered immoral not to).

Before creating the patch, you must first obtain the latest sources of the package you wish to patch from CVS by running the commands (the package in this example is Foo_Bar):

cvs -d:pserver:cvsread@cvs.php.net:/repository login

password is phpfi

cvs -d:pserver:cvsread@cvs.php.net:/repository co pear/Foo_Bar

Now that you have the latest sources, you can edit the relevant file(s). Make sure that your patch is fully compatible with the PEAR coding standards.

After you have finished adding/changing the code, TEST it: We will not accept code that hasn't been carefully tested. When you are absolutely sure the new code doesn't introduce bugs, create a unified diff by running:

cd pear/Foo_Bar
cvs diff -u >Foo_Bar.diff

The resulting .diff file contains your patch. This diff makes it easy for us to see what has been changed.

The next step is to submit the patch. There are basically two options to do this: The first option is to submit the patch by creating a bug report for the package in question. You can do this by visiting the package homepage on pear.php.net and clicking on the "Bugs" tab at the top of the page. Another option is sending a mail to pear-dev@lists.php.net and Cc'ing the maintainer(s) of the package. The subject of the mail should be prefixed with '[Patch]' to make it clear you are submitting a patch. Also include a verbose explanation of what the patch does. Don't forget to attach the .diff file to the mail. The maintainers of the package are usually listed in the header of each source file. Apart from that their email addresses are available on the package information page on http://pear.php.net/.

Note: If you are using Outlook or Outlook Express, please change the file extension of the diff file to .txt, because Outlook's MIME-Type detection depends on the file extension and attachments with a MIME-Type not equal to text/plain will be rejected by our mailinglist software.
Note: If your patch does break backwards compatibility, the chances are fairly good that the maintainers won't be happy about it. Thus you should always try to fix a bug in a way that does not seriously change the public API. But if there is absolutely no way to keep backwards compatibility and/or if your patch contains a groundbreaking improvement, even API changes are fine.
Prev | Contributing | Next
Writing New Packages | PEAR Manual | Reporting Bugs


Reporting Bugs

Reporting Bugs

If you think that you have found a bug in a PEAR package, please take care that you are using the latest version of the package and that your system does meet the packages' requirements.

If the bug still persists with the latest version of the package, don't hesitate to fill out a bug report. The easiest way is to click the link "Bugs" on the package information page for the package on the PEAR Homepage, which you think contains a bug. This will take you to a list of existing bugs of the package. Please double check if the bug hasn't already been reported! If you are unable to find it in the list, you can click on "Report new bug" to fill out the bug form.

More information and tips on how to report bugs in a proper way can be found at http://bugs.php.net/how-to-report.php.

If you have already fixed a bug that you have found in a package, please read this.

Prev | Contributing | Next
Submitting Patches | PEAR Manual | Writing & Translating Documentation


Writing & Translating Documentation

Writing & Translating Documentation

Good documentation is essential for users to fully understand any software. Several PEAR packages lack documentation or have docs which need improvement. Writing documentation provides more information about helping out on this front.

Translating documentation is another important task. Not only does new documentation need to be translated into the existing languages, additional languages are welcome. Also, existing translations need to be brought up to date because the English versions have been changed. Help on how to perform the translation process is in the Revision Tracking section of the manual.

Prev | Contributing | Next
Reporting Bugs | PEAR Manual | Wishlists


Wishlists

Wishlists

Some of the PEAR developers have wishlists at Amazon or a similar service. If you appreciate the work of a certain developer, feel free to buy something for her from her wishlist. To find out if a developer has one of those wishlists, go to the account browser, look for the details of the developer and there you'll see if she has a wishlist. Buying something from people's wishlists may even speed up the time in which annoying bugs are fixed ;-).

Prev | Contributing | Next
Writing & Translating Documentation | PEAR Manual | FAQ


FAQ

FAQ - Frequently Asked Questions

Table of Contents
  • User FAQ
  • Developer FAQ
  • Documentation/translation FAQ
Prev | About PEAR and PEAR2 | Next
Wishlists | PEAR Manual | User FAQ


User FAQ

User FAQ

What is PEAR?

This is described here.

How do I install a package when I get the error message "No release with state equal to: 'stable' found for 'Packagename'"?

answer by Greg Beaver

The package in question does have releases, but none that are stable. There are two solutions.

  1. Set preferred_state to alpha or beta and then install

    $ pear config-set preferred_state alpha

    $ pear install Packagename

  2. Find out the stability or version number of the latest release and install it directly.

    $ pear install Packagename-alpha

    $ pear install Packagename-1.5.3

Why do I get "No handlers for package.xml version 2.0" when I try to install a package?

You are using a PEAR version lower than 1.4.0.

To install the package, you have to update PEAR via:

$ pear upgrade PEAR

This will install the latest available version of PEAR which is capable of installing packages that have only a package.xml version 2.0.

If you have an old PEAR version installed (i.e. < 1.3.6), you need to use the following two commands to install the latest available version of PEAR:

$ pear upgrade -a PEAR-1.3.6

$ pear upgrade -a PEAR

There is no end-user documentation for this package! How am I supposed to know how it works?

Even if not all packages do have end-user documentation in the PEAR manual, nearly all of the packages do include examples. The examples are automatically installed when you install a package via the command line installer and are located in $peardir/docs/$packagename/.

You can find the example/documentation directory by executing $ pear config-get doc_dir on command line.

I have a question about PEAR. Where should I ask?

  • General questions about the usage of PEAR components should be posted to the mailing list pear-general@lists.php.net.

  • All technical discussions concerning the development of PEAR components should be posted to pear-dev@lists.php.net.

  • Question concerning the website can be sent to pear-webmaster@lists.php.net.

Information on subscribing this mailing lists can be found here.

On all mailing lists mentioned above the language is english and the way you ask questions should always be polite :-).

Does PEAR work on Mac OS X?

answer by Brett Bieber

All Mac OS X versions up until 10.5 come with PEAR by default. Mac OS X 10.5 (Leopard) users will need to install PEAR using the standard installation instructions.

If you are a OS X 10.4 or lower user, you may wish to upgrade to a newer version of PHP using a binary installable package such as Marc Liyanage's PHP packages. If you have installed another PHP package, you may have two versions of PHP and PEAR installed on your system. To be sure which version you are using, type which pear in your console to find out where PEAR is located, and pear -V to find out some info about the pear version, and also pear config-show to see the configuration details.

If you have not made any modifications to the default Max OS X install, the PEAR version you are running is the /usr/bin/pear which is configured for the PHP 4 version distributed with OS X. If this is the case, there are a couple options to use a PHP 5 version on your Mac.

If you're using Marc Liyanage's PHP package, you can specify the full path to your PHP5 PEAR installation. For example /usr/local/php5/bin/pear install {packagename} to install a package for your PHP 5 installation (installing/upgrading packages will probably require sudo).

Alternatively, you can change every path for the OS X provided PEAR using pear config-set. Remember to specify all paths necessary to point to your PHP 5 installation.

What I prefer to do, is remove the Apple supplied PHP 4 with sudo rm /usr/bin/php /usr/bin/pear and then symbolically link php and PEAR in /usr/bin to the location where Marc Liyanage's packages are installed: sudo ln -s /usr/local/php5/bin/php /usr/bin/php && sudo ln -s /usr/local/php5/bin/pear /usr/bin/pear. Keep in mind, Apple occasionally updates PHP on OSX, which will revert your /usr/bin/php to their distributed version. Pay attention to software update, and read the information regarding updated software bundled with OS X updates.

Note: It is uncertain if Apple will continue to distribute PHP version 4 for Mac OS X <= 10.4. So these instructions may change, and may differ for your specific version of Mac OS X. Always consult the Apple documentation to understand the default install provided before making modifications.

Does PEAR work on windows?

To make PEAR work on Windows, you simple need to add the PEAR installation dir (e.g. c:\php\pear) to the include_path directive in your php.ini.

Note: There are some classes (like Schedule/At.php), that do not work on Windows, because they use *nix specific commands.

go-pear.php or bundled packages in the windows build of PHP 4.3.x is out of date!

Unlike other aspects of PEAR development, the windows build of PHP 4.3.x is not tracked in CVS. Instead, it is located on the machine that builds windows snapshots. Often, this will not be updated when the rest of PEAR is updated. Note that PHP 5.x releases use a different build system and are automatically updated to the latest versions of PEAR.

If you find that PHP 4.3.x has out-of-date versions of packages, or no longer works, then please report that the windows bundle of PEAR is out of date to pear-dev@lists.php.net

Why does my browser show strange warnings when logging in to the website?

You are seeing the warnings because pear.php.net uses a SSL key that is signed by CAcert, whose root certificate is unfortunately not bundled with most browsers.

If you are using a Mozilla browser, you can import the certificate on this site by clicking on the link "Root Certificate (PEM Format)". When asked if you want to trust the new Certificate Authority, you need to check at least the "Trust this CA to identify web sites." box and click "Ok".

People using Internet Explorer may find help here.

Mac OS X users must download the above mentioned PEM file. The certificate can then be imported with the "Keychain Access" utility via "Import" in the "File" menu.

Installing into customized windows folders fails

To know that the folder has a customized view, Windows sets the "read-only" attribute to the folder. The "read-only" attribute is not actually used to control write access. You can create files in a "read-only" folder. http://support.microsoft.com/default.aspx?scid=kb;en-us;326549

The PEAR Installer detects the read-only attribute and refuses to install into these folders. Unfortunately, there is no way to distinguish between customized folders and actual read-only folders on Windows.

The work-around is to avoid installing PEAR packages into customized Windows folders.

I've got an old installation of PEAR and don't have the permissions to install a new version - what now?

If $ which pear gives you something like /usr/local/bin/pear and $ pear -V shows a very old version or if you don't want to use it for other reasons, you have to install PEAR in your home directory.

Go to http://pear.php.net/go-pear, save as gopear.php and do $ php gopear.php or try $ lynx -source http://pear.php.net/go-pear | php -q.

Use /home/user/pear as prefix while installing PEAR, where user is your username.

Once the installation is done, edit your PATH variable to include your planned new PEAR directory before the old one.

For example put a export PATH=/home/user/pear/bin:$PATH at the end of your ~/.bashrc or ~/.profile under Linux. $ echo $PATH should give you now /home/user/pear/bin:[...]

$ which pear should result in /home/user/pear/bin/pear and $ pear -V something like "PEAR Version: 1.4.8" (at the time of writing) or newer. Check the latest stable version at http://pear.php.net/package/PEAR under Current Release.

Now all you need is to set your include_path correctly, most likely via

<?php
 $path = ini_get('include_path');
 ini_set('include_path', '/home/user/pear'.PATH_SEPARATOR.$path);
 ?>

I have updated package X to get rid of errors like "undefined function Y", but PHP still shows the error message(s). What's wrong?

It is very likely that you have defined two PEAR directories in your include_path, and that you have updated the package in the directory that is defined behind the first directory in your include_path. If you either remove the wrong directory from your include_path or change the order of the directories in your include_path, the error messages should not be shown anymore.

The downloaded go-pear.php isn't parsed by PHP! Why?

If you have followed the instructions for getting go-pear.php and you are using e.g. Windows and the Internet Explorer, you might get the strange effect that -- although you have named the file go-pear.php -- the file isn't parsed and the PHP source code of it is shown.

The problem is that e.g. the Internet Explorer saves the file as a HTML file with some HTML code around the PHP source code to display the code nicely.

To avoid this problem, you should use the source code view of your browser, e.g. by clicking with the right mouse key and selecting "Show source code" from the context menu. If you save now the file that is shown in your editor as go-pear.php, PHP will be able to parse the file properly.

Please note that the Windows versions of PHP have a file named go-pear.bat bundled. It is recommended to use this batch file on Windows instead of using go-pear.php.

Prev | FAQ | Next
FAQ | PEAR Manual | Developer FAQ


Developer FAQ

Developer FAQ

How do I become a PEAR contributor and/or how do I get CVS access to PEAR?

This is described here.

I have written a PHP module in C. What are the rules of including this in PEAR?

The PECL project (a spin-off from PEAR) is the place where C extensions for PHP are published.

Why is PEAR separated into pear/ and pear-core/?

The first elements of PEAR were stored in the directory pear-core (once php-src/pear) and so they were bundled with each new PHP release.

For future releases of PEAR this isn't workable because PEAR will become too big to be bundled with every release of PHP. So there was a decision to commit all new elements to an own top level directory pear. The other elements which are currently remaining in php-src/pear will be moved to the new top level directory soon. Only the PEAR package manager code will be bundled with every new release automatically.

Why does the directory structure of pear/ and pear-core/ differ?

The directory structure of pear-core/ matches that of the install tree (by default /usr/local/lib/php), and are organized as a simple hierarchy. However, the directory structure of pear/ is based on what package the files belong to. Where files are located in each package directory is completely independent from where they end up being installed, this is all determined by the package description file.

Why a flat directory structure instead of a deep?

In CVS, PEAR code is organized by package instead of hierarchical like it would finally be installed. For example, if you want to use the XML_RPC class, you include "XML/RPC.php". It's easy to think that in CVS, this file should be in pear/XML/RPC.php, but that's not the case. XML_RPC is an independent package with its own directory in CVS, in this case the RPC.php file is actually located at pear/XML_RPC/RPC.php. The package description file (package.xml) is used to say where the files should finally be installed.

The reason CVS is organized this way is that it makes package administration much easier.

Can I commit experimental/unstable stuff?

Yes. But make sure, that you mark up the experimental/unstable status of the project in the documentation. The best place to do this is in the package.xml in the <state>-tag. The values for this tag are

alpha

early stages of development, all things could change (API, behavoir) without notice, expect lots of bugs

beta

API should normally not change, usable software, expect bugs

devel

a release for other developers who want early access to test and give feedback, code quality may vary from pre-alpha to stable

stable

the software has a fixed API, it has undergone tests, and documentation exists. This release is a recommended release for use in production environments.

snapshot

a CVS snapshot from a certain date

Am I expected to add examples and/or test files to my package and where to store them?

Examples are a good idea, especially when your class has a complex API. But examples are only a part of a documentation. Don't create examples instead of a documentation. You should store the documentation and the examples in a sub directory 'docs' of the package directory.

Test scripts are recommended when your class has to be compiled, requires special extensions/programs or needs correctly installed additional files (i.e. templates, graphics). Store them in sub directory called 'tests'.

Are different packages or classes with similar features allowed?

There is no problem with competitive packages, but we want to avoid pollution with 10 template classes, 7 different mail classes, and 3 different layers for databases doing the same only with different function names.

First of all, do a reality check: Why do I want to commit a new package? Really bad answers are "To see my name in PEAR" or "I didn't understand the API of the existing class".

A good reason for a new class is often, that you are missing a function, behaviour or speed in an existing implementation. In this case, you should take a look at this class, if it possible to extend this class. If not, then you have a good reason to commit a new class. "If not" means, it isn't possible to add the required functionality without changing the basics of this class.

If you write a new class, try to keep API compatibility with existing classes as far as possible! If it isn't possible to keep the class compatible himself, try to create a wrapper class to keep compatibility. Don't care, if this wrapper needs a lot of time or memory, a wrapper class only has to keep compatibility and make migration easier.

Committing a competitive class has to be announced on the PEAR developers mailinglist!

A required package includes a package, my package needs it too. Should I include it again?

Yes. You should include every package, you need with require_once() or include_once (), also when it is included already by another package.

What licenses are allowed in PEAR/PECL?

Currently PEAR supports the following list of licenses:

  • PHP License

  • Apache License

  • LGPL

  • BSD style

  • MIT License

Other licenses may be added to this list on a case-by-case basis. Please get in touch with the PEAR developers mailing list for this.

The allowed licenses were chosen to allow integration into closed source, open source as well as commercial applications. The only limitation is that the original credits must stay in the sources. For LGPL the license additionally requires that all changes to the source code must be licensed under the LGPL to anyone the source is distributed to.

From time to time people raise concerns of using PEAR packages licensed under the PHP license in GPL'ed code. In a discussion about this topic, the creator of PHP, Rasmus Lerdorf, issued the following statement:

It all comes down to semantics of what linking means. The PHP license is pretty much identical to the Apache license and you could indeed make a case for not allowing any GPL'ed software to be "linked to" from Apache either.

See http://www.apache.org/licenses/LICENSE-1.1.

The PHP license was chosen to match the Apache license because Apache and PHP are tied so closely to each other.

This hair splitting over linking, derivation and aggregation has been going on since the beginning of time. My stance is that you can indeed ship PHP licensed PEAR components on the same cd or in the same tarball as GPL'ed code because I see it as an aggregate work. This changes if you take PEAR code, modify it and copy-paste it directly into your own work. Then it moves from aggregate to derived. But the intent of the PEAR components is to be used in aggregate form. The PHP license allows you to use it in derived form as well, of course, but then you should be choosing a license other than the GPL for the derived work.

The FSF has a FAQ on aggregation here: http://www.fsf.org/licensing/licenses/gpl-faq.html#MereAggregation

That text is heavily biased towards compiled software and they talk about executables and memory spaces which don't really apply in this case. If you don't consider using a PEAR component as aggregation then it logically follows that you also cannot have Apache call your code so you will have to stipulate that nobody can use your code from Apache. I think this is an extreme interpretation that pretty much nobody out there shares.

In short, I don't see an issue here. Move along.

For PECL extensions that are linked into PHP, the license must be compatible with the PHP license. That means you can not GPL a PECL extension or you would be violating the GPL. Note also that if you write an extension that links against a GPL'ed library you will be violating the GPL. If you need to link against a GPL'ed library, get permission from the author of the library to use the library under a compatible license.

The license of any PEAR/PECL package can be found in the head of all source code files, inside the <license> tag of the package description file (package.xml) and also on the package homepage.

Why does the PEAR coding standard insist on space-only indentation?

Using spaces and avoiding tabs is the only way to ensure that a piece of code is rendered consistently in all editors and viewers. Many editors render tabs as 4 spaces, and a lot of editors, terminal programs and utilities render tabs as 8 spaces. Example:

printf("%s",
$arg);

Here, there are 7 spaces before "$arg". If this code was written in an editor with 4-space tabs, it would store it as one tab and three spaces. Now, if another developer edits the same file in an editor with 8-space tabs, it will look like this:

printf("%s",
$arg);

Likewise, consider this code written with 8-space tabs:

if ($foo &&
$bar) {
}

If viewed in a 4-space-tab editor, it will look like this:

if ($foo &&
$bar) {
}

In a community like PEAR where people use lots of different systems and editors, using tabs simply doesn't work. People will end up doing whitespace commits fixing rendering in their editor, while breaking it for others. With only spaces it will look the same to everyone.

Jamie Zawinski has written a piece on the subject too.

There is also a tool called Astyle which can help you convert your code to the appropriate style.

Prev | FAQ | Next
User FAQ | PEAR Manual | Documentation/translation FAQ


Documentation/translation FAQ

Documentation/translation FAQ

I added some new package documentation, but the pages don't show up in the compiled manual!

Most likely you forgot to ./configure again. This will make sure that new pages are detected and included.

Another reason could be that you did not add links in the parent page. In en/package/ are the category xml files that contain links to the package documentation files. Add the link to your new pages there.

This also applies if you get a message stating cannot generate system identifier for general entity "package.networking.net-ldap.search".

Compiling the manual shows it on the terminal, but does not generate files!

configure did not find the Docbook DSSSL or XSLT stylesheets. Install them first.

If the style sheets are installed, ./configure will list the found directories like this:

checking for docbook.dsl... autodetected: /path/to/dsssl-stylesheets-x.yz
checking for docbook.xsl... autodetected: /path/to/xsl-stylesheets-x.y.z

Is there a tool to help PEAR manual translators to track files changes?

Working on the translations is not just translating an English file and committing the results. Much of the work is needed to update the already translated ones, to get in sync with the content of the English files. To follow the modifications in the English tree, you should subscribe to the PEAR documentation mailing list to get CVS commit messages, or read the archives. If you never update your files, the translations can get useless.

Updating a foreign language file can get difficult, as you may not know when and who translated that file, so you may not know where you should look for the updates needed. We have one system for tracking the revisions and modification dates of the files in peardoc.

The Revision Comments

Instead of storing all responsibilities in a central file, the revision comment system stores them in the files they provide information about. Information about translator, revision numbers, and status information is stored in the revision comment. Let's see what would be in the header of the example file bookinfo.xml file in this case:

<!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->

We can see the revision number for the last english file used to update the translation (EN-Revision: 1.16), the translator cvs account name. But we can also add some other status information in the case it is needed (eg. "partial" for incomplete translations). This revision comment system is basically about storing the information in the XML files, and not in a central place. This is extremely convenient now, as there are more than 2400 files in the English tree.

Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a CVS user name, or some nickname without a space, status can be anything without a space. Note, that this header is not updated by CVS (in contrast with $Revision, which is updated automatically). This is only updated when you edit the contents of the comment yourself.

You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. No, you do not lose this, but get much more! If you would like to build a full list of you files, you can go to the /peardoc/ directory and run:

./scripts/revcheck_pear.php xx > revcheck.html

Here xx is the imaginary language code. After running this script you'll get a revcheck.html in the same directory. You can find revision comparisons and links to diffs for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer.

There are some optional extensions introduced for this script, to be available in this generated HTML page. This is why the translation.xml files are introduced. Here comes a simple translation.xml file for the imaginary xx language :

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">

<translation>

<intro>
This is some introductory text for the xx language translators
about who is the manager of the translation, and where to find
more information. This paragraph is printed on the top of the
generated revcheck.html page.
</intro>

<translators>
<person name="Joe Doe" email="joe@hotmail.com"
nick="joedoe" cvs="yes" editor="yes"/>
<person name="Jane Smith" email="jsmith@yahoo.com"
nick="jane" cvs="yes"/>
<person name="Joe Forever" email="joe@forever.net"
nick="joefo" cvs="no"/>
</translators>

<work-in-progress>
<file name="appendices/aliases.xml" person="joedoe"
type="working"/>
<file name="functions/dbx.xml" person="joefo"
type="working"/>
</work-in-progress>

</translation>

In this file, you can add users without a CVS account, and can assign ready documents or work-in-progress files to them. The biggest advantage of using this addon is that all this information is used to generate dynamic tables of translators and files in the revcheck.html file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for all the translators. Assigning ready files may be needed if a time consuming update is in progress on that file.

There are two optional parameters you can add to a <file>, if you would like to record it: the date and revision. Date is assumed to be the date when the work was started, revision is the checked out revision of the English file used to start the work (denoted as CO-Revision in the generated table). There is currently no fixed format for the date parameter.

Another addon to this system is just to give credit to all people who worked on one file, and not just the current maintainer. To achieve this goal, we added the credit comments. One credit comment in eg. history.xml may look like this (in case Joe Doe translated the file initially, but Jane followed him to be the maintainer):

<!-- CREDITS: joedoe -->

The credits comment can contain a comma-separated list. These comments only affect the display of the translators table in revcheck.html.

Prev | FAQ | Next
Developer FAQ | PEAR Manual | Constitution


Constitution

Constitution

Table of Contents
  • Summary of Important points
  • What is the purpose of this document?
  • Official Constitution

The PEAR Constitution

2007-03-14

PEAR's constitution was adopted by majority vote of active PEAR developers on 2007-03-08, see the Official Results.

Prev | About PEAR and PEAR2 | Next
Documentation/translation FAQ | PEAR Manual | Summary of Important points


Summary of Important points

Summary of Important points

The following summary of the constitution is only intended to clarify the most important features of the constitution. The text starting with Constitution is the official Constitution of PEAR.

  • Most importantly, this document's main purpose is to enable developers to innovate in a supportive environment, to foster good will between developers, to encourage best practices and to provide a clear path for resolving disputes. PEAR is about bringing PHP developers together to provide great solutions to the problems we encounter every day through the PHP language, it is ideal if the constitution is ancillary to the main activity at pear.php.net: coding.

  • Developers have supreme power over ultimately what bugs/features will be assigned to specific roadmap versions, and to releasing package versions. Developers will have to cede some control over API decisions/QA/docs to the collective that contains their package. Developers may be expected to mentor a new developer and help introduce them to the systems within PEAR (how to package, document, test, etc.)

  • In other words, the bulk of the day-to-day power will remain with developers, but some of the QA decisions and individual ownership will be relinquished to the collective that contains the package.

  • Collectives have supreme power over packages within the collective in terms of API decisions, QA, documentation, defining the way collaboration works in the collective, choosing a collective leader or leaders, self-promotion of packages within the collective and assigning mentors to new developers of packages within the collective.

  • The PEAR Group only has power over issues that affect all of PEAR such as coding standards, CVS karma, and all major decisions made about PEAR as a whole. For example, licenses allowed and what defines a collective are two issues that only the PEAR Group can resolve.

  • The PEAR president has no power over any of the things above, except for the ability to veto a PEAR Group decision. The president cannot create policy. The president's main job is public relations, talking to people outside of PEAR like an ambassador, trying to recruit new developers or bring packages into PEAR, and to solve big emergencies in a hurry such as finding a new hosting provider should the donated space for pear.php.net disappear.

Prev | Constitution | Next
Constitution | PEAR Manual | What is the purpose of this document?


What is the purpose of this document?

What is the purpose of this document?

  • Clarify who is responsible for what actions within PEAR's sprawling complex of packages and developers.

  • Define a clear chain of command.

  • Create a structure for resolving disputes on all levels.

Prev | Constitution | Next
Summary of Important points | PEAR Manual | Official Constitution


Official Constitution

Official Constitution

I. Governing structure (who runs things in PEAR?)

  • One elected president

  • An elected PEAR group of 7 developers

  • Collectives of related packages

  • Each package has developers assigned to the package

  • Extra-governmental technical gurus - these people have shell access on the pear.php.net website, CVS karma for everything, and generally can do things that others cannot do.

II. Checks and balances

  • Inactive collectives will be handled by the PEAR Group

  • PEAR Group members have a term of 1 year, renewable indefinitely through election by PEAR developers

  • PEAR president may be impeached by a 2/3 vote (5 votes) of the PEAR Group

  • PEAR president may veto decisions from PEAR Group within 1 month of PEAR Group vote

  • PEAR Group may override presidential veto with a 2/3 vote (5 votes) within 1 month of presidential veto

  • PEAR president has a 1 year term, renewable indefinitely through election by PEAR developers

  • This document may be amended by referendum (election)

  • Any responsibility may be delegated as necessary, as long as the delegation is clearly and prominently documented at pear.php.net

III. President responsibilities

  • Liaise with PHP Group

  • Liaise with external projects/funders

  • Promote PEAR as a repository, be the public voice of PEAR

  • Approve or veto decisions from the PEAR Group

  • Call elections through the web site

  • Appoint committees to solve pressing problems, if approved by PEAR Group

  • Appoint temporary handlers (people or groups of people) to solve emergency problems (problems with 24 hour to 1 week time frame)

  • Recruit specific developers from outside of PEAR to enhance PEAR's quality

  • Appoint people to fill temporary vacancies on PEAR Group until election can be held

IV. PEAR Group responsibilities

  • Choose 1 member of the PEAR Group to act as vice president, who will stand in as the president if the president is incapacitated in some way (i.e. on vacation, or more serious issues). This position may rotate.

  • Create and vote on actual language for all official PEAR policy that affects more than 1 collective (simple majority approves policy)

  • Resolve disputes between collectives or between individuals and collectives

  • Grant CVS karma requests

  • Handle inactive collectives (either demote all packages to unmaintained, re-assign developers, or other logical solutions)

  • Call elections through the web site

  • Promote PEAR as a repository (working with the president as much as makes sense)

  • Define coding standards

  • Resolve larger licensing and legal issues (working with the president as much as makes sense)

  • Define what constitutes a Collective (how to define it - categories? Related packages only?) and make final decisions about which collective a package should go in

  • Document all communications and archive them, either through email list or some other publicly accessible format like a forum or wiki - the first elected PEAR Group should decide how to do this and amend the constitution. The PEAR Group may occasionally choose to hold secret communications until a bill is voted on, and then the communications must be made public. A summary of communications is acceptable, and should at the least document topics debated and alternatives to the final decision.

IVa. Vice President responsibilities

  • Post PEAR Group decisions on the web site, and add them to official documentation if necessary. Decisions are not binding until documented on the website.

  • Stand in as president until the next election if the president resigns, or is otherwise unable to serve.

  • Appoint a replacement on the PEAR Group if he/she becomes president

V. Collective responsibilities

  • Create actual language for all official PEAR policy that only affects the collective

  • Choose a person or persons who will liaise with the PEAR group. No restrictions are placed upon how to do this, each collective may decide internally

  • Define and enforce API compatibility (self-police)

  • Enforce Coding Standards as defined by the PEAR Group

  • Enforce documentation creation. This can be done by outsourcing to volunteers, but it must be done for all packages in a collective.

  • Define clear, public guidelines on code access (who has commit access to which packages, and what is acceptable boundaries).

  • Self-promote the collective as a whole (this is non-restrictive, each collective should do this in their own way)

  • Assign "mentors" for new developers in the collective (specific developers who are available through email/chat to answer questions of developers new to PEAR)

  • Collectives are encouraged but not required to directly contact and collaborate with other collectives.

VI. Developer responsibilities

  • Define package roadmap

  • Fix bugs, implement new features

  • Adhere to the collective requirements (documentation, allowing QA commits/releases)

  • Package releases

  • Meet coding standards

  • Appeal to the collective if there are any package-related questions or technical issues

  • Appeal to the PEAR Group if there are disputes with the Collective that cannot be resolved in the Collective.

VII. Extra-Governmental technical gurus responsibilities

  • Accept the will of the developers: no changing election results, improper abuse of power or other evils that jeopardize the legitimacy of PEAR.

  • Quick database fixes, upgrade of the PEAR database when changes are needed

  • Cron job administration

  • Details of who these people are, their karma, and their tech powers should be clearly and prominently displayed at pear.php.net

IX. Website Collective

The Website Collective is a special collective, consisting of developers with pear.admin karma (Website Administrators), and developers who contribute to and maintain the actual infrastructure code for pear.php.net.

Website Administrators responsibilities (as part of website collective)

  • Approve/Deny new pear.php.net account requests

  • Manage karma requests for existing accounts

  • Pull invalid releases (QA)

Communication

pear-dev@lists.php.net (or php.pear.dev newsgroup) remain the official channels for all PEAR communications. Specific enhancements to the website may of course be created in the future to facilitate better communication.

Prev | Constitution | Next
What is the purpose of this document? | PEAR Manual | PEAR Group Administrative Documents


PEAR Group Administrative Documents

PEAR Group Administrative Documents

Table of Contents
  • Package Directory Structure
  • License Announcement
  • New guidelines for BC breaking releases
  • Orphaned Packages
  • Orphaned PEPr Proposals

One of the jobs of the PEAR Group is to issue administrative documents about diverse topics in PEAR. This chapter contains all of them.

Prev | About PEAR and PEAR2 | Next
Official Constitution | PEAR Manual | Package Directory Structure


Package Directory Structure

Package Directory Structure

This document was issued on 4th November 2003 and describes which directory structure must be used in PEAR packages. The goal of this document is to unify the directory naming in CVS and after installations.

Let's assume we have a package The_Package_Name that contains one or more sub-classes (eg. The_Package_Name_Module), with some documentation (perhaps a README, copies of RFCs, etc.), a battery of test scripts (unit tests, regression tests, etc.), and it uses some data files (localization strings, etc.), the dir tree would look like:

The_Package_Name

|-- Name (contains Module.php)

|-- data

|-- docs

|   `-- examples

|-- misc

|-- scripts

`-- tests

Name refers to the last part of the The_Package_Name, all subclasses of the main class, should be put in there or subdirectories of it. You can refer to http://cvs.php.net/cvs.php/pear/Cache_Lite/ - the directory Lite as an example (this basically documents what we currently do anyway).

The data and misc directories are optional, because it will not make sense to have them for every single package in PEAR.

The directories that are required are docs/examples and tests. A package may have no extra documentation, but it should have at least one example. There must also be some basics test to be able to verify that the package is working. The preferred type of testing script system to use is PHPUnit or .phpt. But for now we would be content with any sort of test script.

Files in scripts will be installed into a directory available in $PATH, such as /usr/local/bin.

Anything that does not fit any of the above categories is placed into the misc directory.

Maintainers are expected to modify their existing packages to match this new standard.

Prev | PEAR Group Administrative Documents | Next
PEAR Group Administrative Documents | PEAR Manual | License Announcement


License Announcement

License Announcement

This document was issued on 02 April 2004 and was revised on 08 January 2006 when adding the MIT License. It lists the licenses that PEAR packages can be released under.

The PEAR Group would like to announce the following refinement of the current license FAQ entry.

Vote result: 5 (+1), 0 (-1), 3 (+0)

The current list allows a great number of licenses which vary greatly. This means that users may have to learn the in's and out's of a lot of licenses. Also some of the license choices impose comparatively high restrictions to the standard PHP license (GPL, QPL ..). As PEAR aims to extend the functionality provided by PHP users of PHP should fairly safely be able to also use any PEAR package without licensing worries, be it for commercial or non commercial, closed or opensource use.

Therefore with this announcement the license choices are reduced to the following short list:

  • PHP License

  • Apache License

  • LGPL

  • BSD style

  • MIT License

Other licenses may be accepted on a case by case basis, but will have to fit the above criteria. This decision has been made to simplify the current situation, and as with all decisions is open to be refined in the future using the RFC proposal methodology.

All packages, which are already part of PEAR as of now, which use other licenses, do not need to follow this regulation.

Note: In the meantime the FAQ entry linked above has also been updated to reflect the decisions from this document.
Prev | PEAR Group Administrative Documents | Next
Package Directory Structure | PEAR Manual | New guidelines for BC breaking releases


New guidelines for BC breaking releases

New guidelines for BC breaking releases

This document has been published on 14th November 2003 and describes how releases that break backwards compatibility (BC) have to be handled.

The goal is to make it possible to be able to run multiple major versions in one script.

For this reason new major versions (BC break or when the maintainer feels it makes sense as a result of dramatic feature additions or rewrites) require a new package using the following naming convention in the following order of preference (where 'Foo' is the package name and 'X' the major version number):

  1. FooX

  2. FoovX

  3. Foo_vX

The choice should be made based on preventing current and future misleading or ambiguous names. This means good care should be taken in making the right choice for the package. Obviously the first two allow for some ambiguity (is DB2 a package for IBM's DB2 or just the major version 2 of DB? - is IPv4 a package for IPv4 or is it the 4th major release if IP?). They don't break the idea of "_" mapping to directories (the class DB_NestedSet implies that there is a nestedset.php in the DB dir). The last one prevents any ambiguity but it's the least visually pleasing and also breaks the '_' to directory mapping and is therefore the last choice.

We also came to the conclusion that the pear installer should not be clever about the relationship between two major releases aside from printing out notices about the fact that there is a newer major version when a user installs an earlier one. However all major versions of a package will be listed on one package home. This is especially important in order to not break tutorials that cover older major releases (tutorial xyz for major version 1 simply says 'pear install Foo' - if the system would then install 'Foo2' the user might be in for an unpleasant surprise).

Therefore, new major versions are for all intents and purposes new packages with the above mentioned exceptions. The names of these new packages are derived using one of the above mentioned naming conventions.

Prev | PEAR Group Administrative Documents | Next
License Announcement | PEAR Manual | Orphaned Packages


Orphaned Packages

Orphaned Packages

Edited By

Arnaud Limbourg

This document is based on the PEPr voting initiated by PEAR's Arnaud Limbourg. The purpose is to define when a package is orphaned and how to handle this.

The Problem

Sometimes a package is left without care for a long time. It becomes lonely and full of bugs. This is a very sad situation and somebody needs to step up to remedy it.

What can be considered an orphaned package ?

The following are considered orphaned packages:

  • A package with bugs open for longer than 2 months and the developers have not commented on the bug or made any commits to CVS during that time frame.

  • A package that has no open bugs and has bug fixes committed to CVS but does not have a release within 6 months of the bugs being fixed.

  • A package owned by somebody who is commonly known to be inactive.

  • A package denounced by its leads (i.e. The lead actually says that he is no longer maintaining it on pear-dev)

Contact process

A QA core-team member tries to contact the current maintainers and developers (cc'ing the QA list) asking about an update about their work on the package.

A package lead answers:

  • he states that he has no interest in the package anymore, he allows QA team to take the necessary steps

  • he states that he still intends to work on the package, but is busy at that point. Either a timeframe will then be decided upon by the lead and QA during which some activity must occur (i.e. I'm going to be busy the rest of this month but I'll get back to it on the 3rd of next month) OR a second lead developer will be sought to continue development

he states that he still intends to work on the package, but is busy at that point. Either a timeframe will then be decided upon by the lead and QA during which some activity must occur (i.e. I'm going to be busy the rest of this month but I'll get back to it on the 3rd of next month) OR a second lead developer will be sought to continue development

Finding a new lead

A message will be sent to pear-dev asking for volunteers.

Somebody steps up

If you are willing to take over a package you must notify the QA list and state who you are and why you want to take over.

If the QA team feels the person who stepped up is appropriate and capable, the team will make this person a new maintainer. In case several persons step up a case by case study will be carried out to assign new maintainer-ship.

Nobody wishes to take over

A QA core team member will mark the package as orphaned.

Orphan status

If a package is orphaned, a warning and a call for maintainers will be displayed on the main package page.

Glossary

Descriptions of terms used on this page

Glossary
Term | Definition
QA team | Refers to the whole QA team (core and mailing list members)
QA core | Refers to the 6 elected QA team members
Prev | PEAR Group Administrative Documents | Next
New guidelines for BC breaking releases | PEAR Manual | Orphaned PEPr Proposals


Orphaned PEPr Proposals

Orphaned PEPr Proposals

Edited By

Tobias Schlitt

This document is based on the PEPr voting initiated by PEAR's Tobias Schlitt. The purpose is to define what to do with orphaned PEPr proposals.

The problem

It happens more or less often that

  1. PEPr proposals get stuck in a specific proposal phase,

  2. PEPr proposals get accepted, but no package is registered / released.

The solution

In these two cases PEAR QA should step in and try to get in touch with the specific proposers. If the proposer is no longer interested in the proposal, PEAR QA should search for a new maintainer for the package or the proposal should be deleted.

For these steps the following time frames are proposed:

  • For proposals in stages "draft" and "proposal"

    • PEAR QA posts a reminder comment to the proposal after 1 week of inactivity.

    • If the proposer does not react within 2 weeks, the proposal gets deleted.

  • For proposals in stage "finished"

    • PEAR QA tries to contact the maintainer 4 weeks after the proposal is finished and no package has been released.

    • If the maintainer can not be contacted within 4 weeks, PEAR QA starts searching for a new maintainer.

    • If no new maintainer is found within 4 weeks, the proposal gets marked as orphan.

Orphan marker

Finished proposals should not be deleted, but marked as orphan. This marker should have the following content:

  • To the name of the proposal the following tag will be added: [QA-ORPHAN].

  • To the description of the proposal the following text will be added at the top: "This proposal has been marked orphan by PEAR-QA on <DATE> because of the inactivity of the proposer. This means, that the proposal is invalid from this date on. If you have a similar proposal or want to re-activate this proposal, feel free to create a new PEPr proposal for it.".

Prev | PEAR Group Administrative Documents | Next
Orphaned Packages | PEAR Manual | Becoming a PEAR developer: how to get involved


Becoming a PEAR developer: how to get involved

Becoming a PEAR developer: how to get involved

Table of Contents
  • Introduction
  • Contributing -- How best to contribute to PEAR
  • Getting started -- Joining the PEAR community
  • Proposing -- The formal proposal process
  • Taking over a package -- Taking over an unmaintained package
Prev | PEAR Developer Guide | Next
Orphaned PEPr Proposals | PEAR Manual | Introduction


Introduction

Introduction

Edited By

Martin Jansen

$Date: 2008/10/09 15:16:18 $

If you are planning to contribute a new package to the PEAR project, this guide will provide you with the necessary information to get you started The Right Way (tm).

We will start by describing the cases in which it makes sense to contribute and in which not. After we have ensured that the package you want to contribute fits into PEAR, we will describe how to get started with the community. Once you are confident about the inner workings of the PEAR developer community, we will explain how to start the formal process of proposing a new package and we will give some tips for making your first package as successful as possible.

Prev | Becoming a PEAR developer: how to get involved | Next
Becoming a PEAR developer: how to get involved | PEAR Manual | Contributing


Contributing

How best to contribute to PEAR

Table of Contents
  • Cases in which it makes sense to propose a new package
  • Cases in which it is better to improve existing packages

Edited By

Martin Jansen

Edited By

Gregory Beaver

$Date: 2008/10/09 15:16:18 $

In this chapter the different ways of contributing to PEAR will be discussed. The most common way of contributing to PEAR is to open a bug or feature request at our Bug Tracker. You might also add a patch to an existing bug, or add a helpful note to the user manual for a package that you use regularly. If you wish to step in deeper, some packages are in need of better documentation, and you could mail suggestions in text or docbook format to pear-doc@lists.php.net. The next level of commitment to PEAR is offering to become a regular developer for a specific package that you use often. This is easily accomplished by emailing the current active developers and asking where to begin.

If you decide to take the full plunge and contribute a brand new package to PEAR, then you will need to fulfill a number of guidelines and requirements. If you are unsure if your package belongs in PEAR, contact the developers mailing list.

Prev | Becoming a PEAR developer: how to get involved | Next
Introduction | PEAR Manual | Cases in which it makes sense to propose a new package


Cases in which it makes sense to propose a new package

Cases in which it makes sense to propose a new package

As you may have already noticed while browsing the list of existing packages, the PEAR packages provide a (often abstract) solution for a general problem. Thus your code will most likely fit into PEAR if it solves a problem that will not only occur in one (e.g. your) specific application, but that occurs in a lot of (web) applications. Examples are:

  • Support for Network protocols

  • Object oriented wrappers that provide easy access to otherwise complicated or less intuitive PHP extensions.

  • Parsing different XML dialects.

    The PEAR packages that provide XML parsing functionalities can be found in the category browser.

No matter which area is covered by a package, the API should be as abstract as possible (while not becoming too complex), so that it can be utilized painlessly in as much use cases as possible.

Prev | Contributing | Next
Contributing | PEAR Manual | Cases in which it is better to improve existing packages


Cases in which it is better to improve existing packages

Cases in which it is better to improve existing packages

There are two kinds of packages that are not likely to be accepted as new contributions to PEAR:

  1. A package that duplicates an existing package very closely

  2. A framework or other full-fledged web application

There are exceptions to the duplication rule, for instance a package that requires a higher PHP version, and takes advantage of newer versions in PHP will definitely be considered seriously. Also, packages that provide a completely new paradigm for accessing the same thing are a good candidate for consideration.

Frameworks or other applications may also be considered if they are developer tools, such as phpDocumentor. However, if you have a great idea that you think would fit into PEAR, don't let this document discourage you. PEAR developers can be surprisingly open to new ideas. Remember, the best ideas are well documented and carefully presented. Be prepared to have patience and thick skin! We are a picky bunch about quality, but in the end we will all learn a lot and develop some stellar code in the process.

As the parameters for proposing a package change, this site will be regularly updated.

Prev | Contributing | Next
Cases in which it makes sense to propose a new package | PEAR Manual | Getting started


Getting started

Joining the PEAR community

Table of Contents
  • Communication -- Communication with other PEAR developers
  • More information -- More written information

Edited By

Martin Jansen

Edited By

Gregory Beaver

$Date: 2008/10/09 15:16:18 $

Welcome to the PEAR community! By this point, you have decided to contribute some of your time and effort to improving the PEAR repository. Before you go any further, we'd like to introduce you to the common practices and communication channels that PEAR developers use in order to collaborate across geographical and national divides. Additionally we will tell you the different places where you can find more information about the inner workings and rules of PEAR.

Prev | Becoming a PEAR developer: how to get involved | Next
Cases in which it is better to improve existing packages | PEAR Manual | Communication


Communication

Communication with other PEAR developers

Mailing lists are the most important way to communicate in PEAR. We are running a number of public mailing lists, which are listed on the PEAR website. For starters the PEAR developers mailing list pear-dev@lists.php.net is the primary place where discuss various aspects of their packages and of the PEAR repository as a whole. pear-general@lists.php.net is a general support list that should be used for questions on using PEAR packages, installing PEAR, and other issues not directly related to the development of PEAR packages.

If you would like to get started with maintaining packages in PEAR, you are expected to be subscribed to pear-dev@lists.php.net. (Subscription instructions)

Note: During your first steps in the PEAR community, you may stumble across the term "pear-dev", which is the abbreviation for the developers mailing list in PEAR's lingo.

Some people enjoy communicating via IRC channels. We are running the #pear channel in the EFnet network. Some of the most active PEAR developers hang out regularly on this channel. However, for serious inquiries or discussions, you should email the developers mailing list pear-dev@lists.php.net, as these discussions are the only official communication method of PEAR, and are archived for future reference.

Prev | Getting started | Next
Getting started | PEAR Manual | More information


More information

More written information

  • The PEAR Group occasionally publishes Administrative Documents, which describe the Group's decisions. You should read those documents before starting serious contributions to PEAR, because they contain important information about the inner workings of PEAR. The developers mailing list will be informed when new documents are added.

  • This manual contains the Developer Guide, which provides valuable information for using the tools of a PEAR developer.

  • The Coding Standards describe the standards which PEAR code must adhere to.

Prev | Getting started | Next
Communication | PEAR Manual | Proposing


Proposing

The formal proposal process

Table of Contents
  • Step 1 -- Step 1: Requirements for a proposal
  • Step 2 -- Step 2: Initiating a discussion
  • Step 3 -- Step 3: Using PEPr
  • Changing a proposal

Edited By

Martin Jansen

Edited By

Tobias Schlitt

$Date: 2008/10/09 15:16:18 $

In the early times of PEAR, all new packages were proposed by an informal email to the PEAR developers mailing list. Over the time, the number of new proposals increased quite dramatically, making it hard to keep track of all the proposals.

A web-based proposal handling system was established to solve these problems. The system is called PEPr. It is pronounced like the spice and stands for "PEAR Proposal system".

This chapter describes the requirements and the workflow for a PEPr-based proposal. After that we will provide you with information, on how to actually start a proposal. Finally, you will learn what to do once the proposal is finished.

After reading this chapter, you will be able to start a proposal for your code right away.

Prev | Becoming a PEAR developer: how to get involved | Next
More information | PEAR Manual | Step 1


Step 1

Step 1: Requirements for a proposal

The following enumeration lists the most important things that need to be done or be made available before starting a new proposal.

  • Finding a name for the package

    It is obvious that each package needs to have a unique name. To get a "feeling" for proper package names, you should browse the list of existing packages.

    Choosing a name for the package is an iterative process and it is likely that you will change the name at a later stage of the proposal process.

  • Finding a category for the package

    Similar to each package having a unique name, it has to be placed in one of the categories, which are listed in the package browser as well.

  • Writing a package description

    For starting the proposal you will need to write a description of the package. This description does not need to mention every detail of the package, but it should at least outline the basic concept and feature set. When your package has been accepted, you will have to come up with a single-line summary and a fulltext description.

  • Choosing a license for the package

    Each package has to be licensed under an accepted OpenSource license. If you are unsure about the license, you should opt for the New BSD License. The PEAR Group has issued a License Announcement, which provides further details concerning this topic.

  • Writing examples and documentation

    Without proper usage examples and documentation, neither will the PEAR developers be able to evaluate your package nor will users be able to make use of your package.

  • Listing dependencies

    Making a list of dependencies basically means that you write down all external entities such as other PEAR packages, certain operating systems or external applications, which are required to use your proposed package.

    Example for a dependency list

    If your package does only work on Linux, requires the DB package, version 1.8.4 or higher of the Log package and at least PHP 4.3.0, your dependency list looks like this:

Linux

DB

Log >= 1.8.4

PHP >= 4.3.0

Prev | Proposing | Next
Proposing | PEAR Manual | Step 2


Step 2

Step 2: Initiating a discussion

For every package you should start a proposal in PEPr as a draft to initiate discussion on the developers mailing list.

By discussing the package with the PEAR developers you will easily be able to find out if:

  • there are technical issues with the package/code

  • a package with similar functionality already exists

  • there are people working on something similar, so you can join forces

  • etc.

By reading between the lines, you should also be able to find out if you will be able to gather enough positive votes in the formal proposal process.

Be aware that people will scrutinize your code, so be prepared for criticism (both positive and negative) and save everybody a bunch of time by making sure your scripts adhere to the Coding Standards. By using PHP_CodeSniffer you will see quickly if your code complies to the standards.

Please note that PEAR is an international project. People come from different cultural backgrounds where English may not be their native tongue. Misunderstandings may happen because of that, so assume the person is trying to do good. Do not worry if your English is not perfect but do try to be as clear as possible and do not hesitate to ask for advice.

Prev | Proposing | Next
Step 1 | PEAR Manual | Step 3


Step 3

Step 3: Using PEPr

To be able to use the proposal tool (PEPr), you have to apply for a PEAR website account. This account will usually be granted within one or two days. After that you can open a new proposal using the "New Package Proposal" interface.

The package proposal process is divided into 4 stages: "Draft", "Proposal", "Call for Votes" and "Finished". Every proposal has to run through all of these stages. During each stage (except for the draft stage) an email is send to you (the proposer) and the PEAR developers mailing list for any action.

Stage 1: Creating a draft

At first your proposal is a draft. This simply means you can edit it, view it and it is shown up on the PEPr overview page as a draft. This stage is for you to play around with PEPr, to shape your proposal nicely and to prepare it for the proposal process. You can switch to the next stage whenever you want to publish your proposal and get feedback from the PEAR community.

Stage 2: Moving to the Proposal stage

After switching to the stage Proposal you have a real proposal. Either through email or through PEPr itself the community will give you hints and ask questions about the proposed package. Generally it is a good idea to follow these suggestions, but sometimes people in the community will have different visions for your package, which should be sorted out during this stage. After a week of comments you may switch to the next phase. You should only switch to the next stage, if you are sure that the PEAR community will accept your package.

Stage 3: Calling for votes

The next stage is the voting stage, during which you may not change your proposal anymore. You may not edit nor delete the proposal from now on. During the proposal stage, "Call for Votes," every active PEAR maintainer may give one vote on the proposal. Votes are given using the numbers -1, 0 and +1, where -1 means "I'm against this package to be added to PEAR in the current form," +1 says "I'm in favor of getting this package into PEAR in the current form" and 0 means "I have looked at your package, but I am undecided." The time to vote for a package is 7 calendar days. If after this time less than 5 votes have been cast, the developers get another 7 days to cast their votes. After this time the voting is ended, whether there are 5 votes or not.

Votes on proposals can be bound to a condition. These conditional votes indicate that you have to fulfill a certain condition the voters expect to be fulfilled. If there are conditional votes you are expected to read and follow them! The conditions on a vote will be provided in the votes comment. Each vote may have comments. Reading those is always a good idea!

Stage 4: Proposal Finished

Now your proposal is finished. To determine if the proposal was successful or not, the sum of all votes is computed. If the result is greater or equal to 5 the proposal has been accepted. Otherwise we are sorry to say, that the community has decided to reject it. Have a look at their comments during proposal and vote stage to find out why. Maybe you can rework your package and propose it again, but please do not try to hand in a proposal the same way twice.

If your proposal has been accepted, you may put your package into PEAR. If this is your first proposal, please contact the PEAR Group via email to get your current PEAR website account upgraded to a full featured developer account. After that, you can register your package and upload releases.

The process of preparing and uploading a release is described in the Developer Guide.

Prev | Proposing | Next
Step 2 | PEAR Manual | Changing a proposal


Changing a proposal

Changing a proposal

In general you may not edit or delete your proposal after it has left the Proposal stage. In urgent cases you can contact the PEAR community via the developers mailing list to reach a PEAR website administrator to do a change. This is heavily discouraged however! You should have made everything clear to the community during the Proposal stage to ensure a hassle free voting process. Even if the voting has a negative result, this is no reason to delete it.

Prev | Proposing | Next
Step 3 | PEAR Manual | Taking over a package


Taking over a package

Taking over an unmaintained package

Edited By

Arnaud Limbourg

$Date: 2008/10/09 15:16:18 $

If you want to become the new lead maintainer of a package that is marked as unmaintained on the PEAR website, the following section will explain to you the necessary steps for this to happen.

  1. The first thing is to inform the PEAR Quality Assurance mailing list about your intention. If you have not been involved in PEAR prior to that, it is a good idea to write a few words about you and your motivations.

  2. The QA team will then state whether you can take over the package or not, eventually explaining why. You can then apply for an account for the PEAR website unless you already have one. The PEAR Group will have to grant this account, and afterwards the QA team will assign you as the new lead maintainer for the package.

  3. If the sources of the package are kept in the PHP CVS repository, you will also need an account for this. You can sign up for it on the PHP website. Please mention in the purpose field of the request form that the PEAR QA team has told you to get an account, so that your request can be processed faster. CVS accounts are managed by the PHP Group, so PEAR unfortunately has only limited influence on this process.

    Note: If you already have a CVS account for cvs.php.net, it is only necessary for you to get additional "karma" for the module where the package resides. You can request this karma by sending an email to the PEAR Group. (Please also mention in this mail that you have already talked to the QA team.)

  4. If everything has worked out well, you should by now be the lead maintainer of the previously unmaintained package. If not, don't hesitate to ask the people on the QA mailing list for help.

Prev | Becoming a PEAR developer: how to get involved | Next
Changing a proposal | PEAR Manual | PEAR Developer Guide


PEAR Developer Guide

PEAR Developer Guide

Table of Contents
  • Introduction
  • Meaning for developers -- PEAR's meaning for developers
  • Contributing code to PEAR -- Writing new packages, or enhancing existing packages
  • package.xml 2.0 -- The package definition file package.xml, version 2.0
  • Releasing A Package
  • Supporting PEAR development
  • Documentation
  • package.xml -- The package definition file package.xml (deprecated)
Prev | PEAR Developer Guide | Next
Taking over a package | PEAR Manual | Introduction


Introduction

Introduction

A guide to PEAR written for developers by developers.

Edited By

Martin Jansen

Edited By

Gregory Beaver

2007-03-23

Who needs this guide?

The intention of this guide is to provide you, a new developer of PEAR packages, with all necessary information to start working effectively.

The first part of this guide covers the advantages a developer has when using PEAR code in everyday work. After that we will show you how to contribute your own code to PEAR. Finally the guide describes the ways a developer can give back to the PEAR project.

Prev | PEAR Developer Guide | Next
PEAR Developer Guide | PEAR Manual | Meaning for developers


Meaning for developers

PEAR's meaning for developers

Table of Contents
  • Code of high quality
  • Collaborating -- Chance to collaborate with and learn from other developers
  • Releasing code -- Chance to release your own code
Prev | PEAR Developer Guide | Next
Introduction | PEAR Manual | Code of high quality


Code of high quality

Code of high quality

PEAR is first and foremost a repository of reliable and high quality code. All packages comply with the PEAR Coding Standards. A new PEAR package should provide an API that is consistent, be written for PHP version 5.0.0 or newer, make use of PEAR_Exception for error handling, and adhere to the requirements of the package collective that it is accepted into.

Prev | Meaning for developers | Next
Meaning for developers | PEAR Manual | Collaborating


Collaborating

Chance to collaborate with and learn from other developers

PEAR provides a stable, robust community of developers with years of experience and a great place to collaborate. New and exciting ways of using PHP to solve the most pressing problems of web development and beyond happen here in PEAR every day.

Prev | Meaning for developers | Next
Code of high quality | PEAR Manual | Releasing code


Releasing code

Chance to release your own code

PEAR gives you the chance to contribute your code to an enormous number of PHP developers: To get more information about how to contribute your code in PEAR, read here.

Prev | Meaning for developers | Next
Collaborating | PEAR Manual | Contributing code to PEAR


Contributing code to PEAR

Writing new packages, or enhancing existing packages

Table of Contents
  • Requirements -- Requirements for contributing code
  • How to contribute -- How to contribute code in practice
  • How to document -- How to document code in practice

PEAR is driven by an open source developer community. Thus anyone may contribute code in the form of a new package or as an improvement to an existing package. Over the years, PEAR has developed a set of conventions. Some of them are evolving, but others have solidified. This document defines those requirements that you must adhere to in order to contribute to PEAR.

Prev | PEAR Developer Guide | Next
Releasing code | PEAR Manual | Requirements


Requirements

Requirements for contributing code

We are making certain demands on both the code and the maintainers of packages:

  1. Code must conform to the Coding Standards.

    If you want to contribute your code to PEAR in form of a new package or as an addition to an existing package, it has to be compliant to a set of Coding Standards. There have been numerous discussions about whether those standards are good or not, and we have arbitrarily decided that they are good and that the discussion is over. Please respect this decision and don't bring up changes to the basic coding standards, or you risk being ignored mercilessly.

    Using PHP_CodeSniffer on your code is the most easy way to see if you comply to the PEAR coding standards.

  2. Code must be appropriately licensed.

    Each package has to be licensed under an accepted OpenSource license. If you are unsure about the license, you should opt for the New BSD License. The PEAR Group has issued a License Announcement, which provides further details concerning this topic.

  3. Code must be available in a public code repository.

    The latest revision of the package's source code has to be available in a public SCM (Source Code Management) system such as the CVS server at cvs.php.net, the Subversion repository of Google Code, or at sites such as SourceForge. Hosting at Google Code or SourceForge is freely available under their terms of use at any time. Write access to cvs.php.net is available once the package has been accepted as a PEAR package.

    All packages must have a publicly available source repository in order to honor the need for access in order to provide patches for bugs or new features.

  4. Extensible and "forward-compatible" code.

    Always keep in mind that your code should be extensible and that it has to be easy to add new features in the future. If it is easily predictable for you that there is no clean way to add new functionality to the codebase without breaking backwards compatibility, you should consider to review the code and to adapt it, before contributing it to PEAR.

    To this end, most PEAR packages make use of object oriented programming. Through concepts such as inheritance, polymorphism, patterns like singleton/factory/command, PEAR packages solve problems in elegant ways. There are numerous resources about object oriented programming all around the web and you will also find tons of books available for your reading pleasure. However we can can recommend Object-Oriented Programming Concepts on Sun's Java Homepage for a quick start.

  5. Documentation in an appropriate format (plain text, docbook)

    Your code must come with appropriate documentation in one of the following formats:

    • Docbook XML

    • Plain Text

    If you write the documentation in Docbook XML and if the markup is valid, the documentation can be easily added to the official PEAR Manual, which you are reading right now.

    Note: As of August 2003, phpDocumentor is fully capable of converting in-code API documentation and external tutorials into Docbook XML. PhpDocumentor version 1.2.2 or greater is required. Install with pear install phpDocumentor. Use the XML:DocBook/peardoc2:default converter on your source code to generate output. The output should be generated directly into the peardoc/lang/package directory, where lang is en, or fr, etc.
    Be aware though that only shipping the API documentation does not suffice! Additionally your package has to come with usage examples and (even better) tutorials about its usage. More information can be found in the section describing how to write documentation

  6. Regression tests in .phpt or PHPUnit format

    All developers have experienced the frustration of bugs. They are a fact of life in programming, but fortunately there are a few systems that can be used to catch them, kill them, and prevent their return. Regression tests should be included with every stable release, so that users can run them if a bug occurs to help you debug the package. Examples of .phpt regression tests can be found as part of the PEAR package in CVS. For examples of PHPUnit tests, see the Auth package.

  7. The contributor ("you") must be willing to provide support for the package and must be willing to release future versions that at the very least fix bugs.

    If you are not willing to maintain your code over a long period of time, it makes little sense to contribute it. PEAR is the standard repository of PHP packages, and this comes with great responsibility. Maintaining means more than just providing support via the various mailing lists:

    You must be willing to not only fix bugs, but also integrate useful enhancements contributed by users of your packages, if they fit the design specifications of your package. You should expect to release new versions of your package regularly with bug fixes. If you will be unable to maintain your package for an extended period of time, it is expected that you will announce this to the PEAR developer mailing list, and assign another temporary lead maintainer or publicly document the fact that your package is temporarily unmaintained, and the approximate date that users can expect to receive support and bug fixes, if possible.

    Code can be removed from PEAR if the lead maintainers are not willing to maintain the code anymore and if there is no other person that is willing to take over as the maintainer.

Prev | Contributing code to PEAR | Next
Contributing code to PEAR | PEAR Manual | How to contribute


How to contribute

How to contribute code in practice

  1. Finding an appropriate package name

    One of the most important tasks while contributing a new package to PEAR is finding an appropriate name for your package.

    The general syntax for package names is <Category>_<Name>. The value for <Category> should be chosen from a predefined list of categories that are available in PEAR (e.g. "HTTP", "Net", "HTML"). The second part is the name of the package (like "Upload", "Portscan", "Table").

    The categories that are currently available in PEAR are represented by the bold headings at the Package Browser. If you think that your package does not fit in any of the existing categories, you can ask the on the mailing list to create a new category. (PEAR is usually reluctant to do that.)

    Apart from this general syntax, the package names can also contain more than one category name. An example for this is HTML_Template_PHPLIB: The multiple categories indicate that the package PHPLIB is part of the category Template, that again is part of the HTML category. This naming scheme is necessary here since it's possible that there are Template systems in PEAR that don't work with HTML but with another technology. (The cases where more than one "category" is used are pretty rare.)

    If you need further advice or help for finding a name for your package, you should ask on the developers mailing list.

  2. Announcing to the PEAR developers

    The second step while contributing is to announce your package in PEPr. Usually this announcement will spawn some discussion. After one week you may call for votes with PEPr and the developers will then start to vote for or against your proposal. (You are of course urged to join the upcoming discussion.) Announcing a package does of course not mean that it is already accepted! That will still take some time and likely some more efforts from your side.

    Note: The following passages are taken from the administrative document Handling Package Proposals, which describes proposing new packages in more details. Reading this document should be a mandatory step for PEAR newbies.

    Only the votes of active members of the PEAR community (must have a PEAR web account, however the proposer himself is not counted) are counted, however anyone may vote. Votes require that a final choice of package name is specified.

    The votes are added up, which means that one -1 offsets a +1. However -1 vote should always be considered to be serious and may lead to decisions being made on a case by case basis by the PEAR Group who reserves a veto (it is intended that in the future the PEAR QA team will assist the PEAR Group in such situations). Therefore a -1 vote *must* contain a comment explaining that decision, it is desirable that votes in favour (+1) should also be accompanied with an explanation when appropriate.

    A vote is accepted if the total of all votes exceeds +5.

    In case the proposal is not accepted the package can be further discussed on the list and the proposer may attempt to make another "call for vote" (it is expected that this is only done for sensible reasons).

  3. Getting the necessary accounts

    Right now one can distinguish between two types of accounts related to PEAR:

    1. Pear.php.net account

      This account is always necessary for you, if you want to release your package through PEAR. With this account you have access to the necessary infrastructure on pear.php.net in order to propose, upload and roll new releases. The PEAR Group manages PEAR accounts and pearweb karma levels (i.e.: karma to use the web site to maintain packages).

    2. PHP CVS account

      If you want to administrate your code via CVS , you can also apply for a CVS account to have access to the pear CVS module on cvs.php.net. This makes it easier for other users to contribute to your code. The PHP Group (group@php.net) manage the PHP CVS server, which is used for maintaining PEAR packages. If you already have a PHP CVS account you will ask the PEAR Group for Karma for a given package or set of packages. Please send an email to pear-group@php.net specifying what packages you need commit access along with credentials (e.g.: the package "lead" email giving you his go or a QA member email announcing you are to be given access).

      If you already have a CVS repository somewhere else (e.g. on SourceForge), or if you don't want to maintain your code via CVS, you don't need the PHP CVS account. It is highly recommended to use some kind of public repository, so that users can try out any bug fixes you apply to the code, before a new release is rolled.

    To sign up for your pear.php.net account, go to the PEAR account request page and fill out the form there. The PEAR Group will then receive your request and someone will open your account, if the request sounds reasonable. You will be notified about that via email. Please note that you do NOT need a pear.php.net account to download packages from there.

    To get a PHP CVS account, go here to sign up for it. The PHP CVS account has to be approved by the PHP Group.

  4. Registering the package

    Once you successfully went through the contribution procedure and got your pear.php.net account, you finish with registering your package. Registering does not mean that you are going to release a first version of your package. It just means that some basic information about the package will be added to the PEAR package database.

    The registration process is quite straightforward: Fill out the form on this site and submit the information. After you have done that, the PEAR Group has to finally approve your submission. This usually happens in a few hours and you will be notified about it via email.

    After having registered your package, you can create a first release, which is described here.

Prev | Contributing code to PEAR | Next
Requirements | PEAR Manual | How to document


How to document

How to document code in practice

Writing documentation is covered in a dedicated section.

Prev | Contributing code to PEAR | Next
How to contribute | PEAR Manual | package.xml 2.0


package.xml 2.0

The package definition file package.xml, version 2.0

Table of Contents
  • Introduction -- A quick and dirty guide to version 2.0 of the package definition file package.xml
  • Special information for PECL developers
  • Detailed Tag Reference for package.xml version 2.0
Prev | PEAR Developer Guide | Next
How to document | PEAR Manual | Introduction


Introduction

A quick and dirty guide to version 2.0 of the package definition file package.xml

The package definition file package.xml is, as the name already implies, a well-formed XML file that contains all information about a PEAR package. Version 2.0 contains several important enhancements over version 1.0, including

  • Channel support

  • Binary PECL packages support (not fully implemented in PEAR 1.4.0)

  • More specific dependency resolution

For those of you with an existing package.xml version 1.0, you can create an approximate equivalent package using the

$ pear convert

command. Note that as of version 1.6.0, PEAR_PackageFileManager supports package.xml 2.0 with the PEAR_PackageFileManager2 class.

PECL developers: for more information on pecl-specific features, read here.

Note: package.xml version 2.0 is supported from PEAR 1.4 on. As of 2007-04, PEAR 1.4 or greater is used in more than 99.8% of all installations in the wild that downloaded packages - there is no need to support v1.0 for backwards compatibility anymore.

An example file with all elements

<?xml version="1.0"?>
<package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0"
    xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
http://pear.php.net/dtd/tasks-1.0.xsd
http://pear.php.net/dtd/package-2.0
http://pear.php.net/dtd/package-2.0.xsd">
 <name>PEAR</name>
<channel>
pear.php.net</channel>
<extends>
OldPackage</extends>
 <summary>Any one-line summary</summary>
 <description>any static long description.
 This text should not change very much between releases, use the "notes" tag
 for release notes
 </description>
<lead>
<name>Greg Beaver</name>
  <user>cellog</user>
  <email>cellog@php.net</email>
  <active>yes</active>
 </lead>
 <date>2005-02-26</date>
 <time>20:30:13</time> <-- note: <time> is optional -->
<version>
<release>1.4.0a2</release>
  <api>1.4.0</api>
 </version>
<stability>
<release>alpha</release>
  <api>alpha</api>
 </stability>
<license uri="
http://www.php.net/license/">PHP License</license>
 <notes>
 Put release notes here.
 They can be multi-line
 </notes>
<contents> <dir name="/">
<dir name="PEAR">
    <dir name="ChannelFile">
<file name="Parser.php" role="php" />
</dir> <!-- /PEAR/ChannelFile -->
    <file name="Dependency2.php" role="php">
     <tasks:replace from="@PEAR-VER@" to="version" type="package-info"/>
    </file>
   </dir> <!-- /PEAR -->
   <dir name="scripts" baseinstalldir="/">
    <file name="pear.bat" role="script">
<tasks:replace from="@bin_dir@" to="bin_dir" type="pear-config" />
<tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
<tasks:windowseol/>
</file>
    <file name="pecl.bat" role="script">
     <tasks:replace from="@bin_dir@" to="bin_dir" type="pear-config" />
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
     <tasks:windowseol/>
    </file>
    <file name="pear.sh" role="script">
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
     <tasks:replace from="@pear_version@" to="version" type="package-info" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
<tasks:unixeol/>
</file>
    <file name="pecl.sh" role="script">
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
     <tasks:replace from="@pear_version@" to="version" type="package-info" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
     <tasks:unixeol/>
    </file>
    <file name="pearcmd.php" role="php">
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
     <tasks:replace from="@pear_version@" to="version" type="package-info" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
    </file>
    <file name="peclcmd.php" role="php">
     <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
     <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
     <tasks:replace from="@pear_version@" to="version" type="package-info" />
     <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
     <tasks:footask/>
    </file>
   </dir> <!-- /scripts -->
   <file name="package.dtd" role="data" />
   <file name="postinstall.php" role="php">
<tasks:postinstallscript/>
</file>
   <file name="template.spec" role="foo" />
  </dir> <!-- / -->
 </contents>
<compatible>
<name>FooPackage</name>
  <channel>pear.php.net</channel>
  <min>1.3.0</min>
  <max>1.5.0</max>
 </compatible>
<dependencies>
<required>
<php>
<min>4.2</min>
    <max>6.0.0</max>
   </php>
<pearinstaller>
<min>1.4.0dev13</min>
   </pearinstaller>
<package>
<name>Archive_Tar</name>
    <channel>pear.php.net</channel>
    <min>1.1</min>
    <recommended>1.2</recommended>
   </package>
<package>
<name>Foo</name>
    <uri>http://www.example.com/Foo-1.2.0.tgz</uri>
   </package>
<extension>
<name>xml</name>
   </extension>
<os>
<name>windows</name>
    <conflicts/>
   </os>
<arch>
<pattern>*-i?86-*-*</pattern>
   </arch>
  </required>
<optional>
<package>
    <name>PEAR_Frontend_Web</name>
    <channel>pear.php.net</channel>
    <min>0.5.0</min>
   </package>
   <package>
    <name>PEAR_Frontend_Gtk</name>
    <channel>pear.php.net</channel>
    <min>0.4.0</min>
   </package>
  </optional>
  <group name="remoteinstall" hint="adds the ability to install packages to a remote ftp server">
   <package>
    <name>Net_FTP</name>
    <channel>pear.php.net</channel>
    <min>1.3.0RC1</min>
    <recommended>1.3.0</recommended>
   </package>
  </group>
  <group name="webinstaller" hint="PEAR's web-based installer">
   <package>
    <name>PEAR_Frontend_Web</name>
    <channel>pear.php.net</channel>
    <min>0.5.0</min>
   </package>
  </group>
  <group name="gtkinstaller" hint="PEAR's PHP-GTK-based installer">
   <package>
    <name>PEAR_Frontend_Gtk</name>
    <channel>pear.php.net</channel>
    <min>0.4.0</min>
   </package>
  </group>
 </dependencies>
<usesrole>
<role>foo</role>
  <package>Foo</package>
  <channel>pear.example.com</channel>
 </usesrole>
<usestask>
<task>footask</task>
  <package>Footask</package>
  <channel>pear.example.com</channel>
 </usestask>
<phprelease>
<installconditions>
   <os>
    <name>windows</name>
   </os>
  </installconditions>
  <filelist>
   <install as="pear.bat" name="scripts/pear.bat" />
   <install as="pecl.bat" name="scripts/pecl.bat" />
   <install as="pearcmd.php" name="scripts/pearcmd.php" />
   <install as="peclcmd.php" name="scripts/peclcmd.php" />
   <ignore name="scripts/pear.sh" />
   <ignore name="scripts/pecl.sh" />
  </filelist>
 </phprelease>
 <phprelease>
  <filelist>
   <install as="pear" name="scripts/pear.sh" />
   <install as="pecl" name="scripts/pecl.sh" />
   <install as="pearcmd.php" name="scripts/pearcmd.php" />
   <install as="peclcmd.php" name="scripts/peclcmd.php" />
   <ignore name="scripts/pear.bat" />
   <ignore name="scripts/pecl.bat" />
  </filelist>
 </phprelease>
 <changelog>
  <release>
   <version>
    <release>1.3.5</release>
    <api>1.3.0</api>
   </version>
   <stability>
    <release>stable</release>
    <api>stable</api>
   </stability>
   <date>2005-02-26</date>
   <license uri="http://www.php.net/license/3_0.txt">PHP License</license>
   <notes>
 * fix Bug #3505: pecl can't install PDO
 * enhance pear run-tests dramatically
 * fix Bug #3506: pear install should export the pear version into the environment

   </notes>
  </release>
  <release>
   <version>
    <release>1.4.0a1</release>
    <api>1.4.0</api>
   </version>
   <stability>
    <release>alpha</release>
    <api>alpha</api>
   </stability>
   <date>2005-02-26</date>
   <license uri="http://www.php.net/license/3_0.txt">PHP License</license>
   <notes>
  This is a major milestone release for PEAR.  In addition to several killer features,
  every single element of PEAR has a regression test, and so stability is much higher
  than any previous PEAR release, even with the alpha label.

  New features in a nutshell:
  * full support for channels
  * pre-download dependency validation
  * new package.xml 2.0 format allows tremendous flexibility while maintaining BC
  * support for optional dependency groups and limited support for sub-packaging
  * robust dependency support
  * full dependency validation on uninstall
  * support for binary PECL packages
  * remote install for hosts with only ftp access - no more problems with
    restricted host installation
  * full support for mirroring
  * support for bundling several packages into a single tarball
  * support for static dependencies on a url-based package

  Specific changes from 1.3.5:
  * Implement request #1789: SSL support for xml-rpc and download
  * Everything above here that you just read
   </notes>
  </release>
 </changelog>
</package>
Prev | package.xml 2.0 | Next
package.xml 2.0 | PEAR Manual | Special information for PECL developers


Special information for PECL developers

Special information for PECL developers

Table of Contents
  • extsrcrelease and extbinrelease changes for PECL developers -- PECL-specific details of package.xml 2.0
Prev | package.xml 2.0 | Next
Introduction | PEAR Manual | extsrcrelease and extbinrelease changes for PECL developers


extsrcrelease and extbinrelease changes for PECL developers

extsrcrelease and extbinrelease changes for PECL developers

extsrcrelease and extbinrelease changes for PECL developers – PECL-specific details of package.xml 2.0

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.

PECL extsrc/extbin-specific tags in package.xml 2.0
Tag Description of usage
<providesextension> The <providesextension> tag must be right after <dependencies>. This tag tells the installer the name of the extension provided by the package, allowing different package names from the extension. This could be important for binary packages (such as PDO and PDO_windows or something along those lines).
<providesextension>PDO</providesextension>
<srcpackage> or <srcuri> <srcpackage> or <srcuri> must follow <providesextension>. Extension binary packages must define either a <srcpackage> tag (for package.xml containing <channel>) or a <srcuri> tag (for package.xml containing <uri>).
<name>PDO_windowsbin</name>
<channel>pecl.php.net</channel>
<!-- snip -->
<providesextension>PDO</providesextension>
<srcpackage>PDO</srcpackage>
or,
<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>
<configureoption> The <configureoption> tag is used to ask a user a specific question, which is then used to influence the building of the extension. Any configure option beginning with "with" is assumed to be a question about enabling a feature. Other options have the user's response automatically passed to configure. The following configureoptions:
<configureoption name="with-blah" prompt="enable blah?" default="yes"/>
<configureoption name="foo" prompt="what foo to use?" default="bar"/>
will generate a configure line similar to:
--with-blah --foo=bar
if the user accepts the default values.
Prev | Special information for PECL developers | Next
Special information for PECL developers | PEAR Manual | Detailed Tag Reference for package.xml version 2.0


Detailed Tag Reference for package.xml version 2.0

Detailed Tag Reference for package.xml version 2.0

Table of Contents
  • <channel> -- What is a channel?
  • <extends> -- Superseding a package
  • <uri> -- When should I use <uri>?
  • <lead>, <developer>, <contributor>, and <helper> -- Developer documentation for a release
  • <version> -- versioning in package.xml 2.0
  • <stability> -- specifying release and API stability
  • <license> -- specifying software license and optional reference to license text
  • <contents> -- specifying the contents of a release
  • <dir> -- documenting a directory in the <contents> tag
  • <file> -- documenting a file in the <contents> tag
  • tasks for <file>s -- specialized file installation and manipulation
  • <compatible> -- Alleviating strict versioning with <compatible>
  • <dependencies> -- Dependency Specification in package.xml 2.0
  • <usesrole> -- documenting custom file roles used in <contents>
  • <usestask> -- documenting custom tasks used in <contents>
  • <phprelease>, <extbinrelease>, <extsrcrelease>, <bundle> -- specifying the content type of a release

Each tag that needs further explanation is documented here (unfinished)

Prev | package.xml 2.0 | Next
extsrcrelease and extbinrelease changes for PECL developers | PEAR Manual | <channel>


<channel>

<channel>

<channel> – What is a channel?

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.

See also:

<uri>

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
Detailed Tag Reference for package.xml version 2.0 | PEAR Manual | <extends>


<extends>

<extends>

<extends> – Superseding a package

Saying goodbye to an old package

By adding an <extends> tag to your package.xml, you tell the world that your new package extends an old package in some way. The new package could supersede the old one, or give new functionality to it.

Using extends

...
 <name>Package_Name2</name>
 <channel>pear.php.net</channel>
 <extends>Package_Name</extends>
 <summary>Any one-line summary</summary>
...

Examples for <extends> usage in PEAR

  • HTML_Common2 extends HTML_Common

  • HTML_Progress2 extends HTML_Progress

  • MDB2 extends MDB

  • MDB2_Schema extends MDB2

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<channel> | PEAR Manual | <uri>


<uri>

<uri>

<uri> – When should I use <uri>?

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.

See also:

<channel>

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<extends> | PEAR Manual | <lead>, <developer>, <contributor>, and <helper>


<lead>, <developer>, <contributor>, and <helper>

<lead>, <developer>, <contributor>, and <helper>

<lead>, <developer>, <contributor>, and <helper> – Developer documentation for a release

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.

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<uri> | PEAR Manual | <version>


<version>

<version>

<version> – versioning in package.xml 2.0

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.

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<lead>, <developer>, <contributor>, and <helper> | PEAR Manual | <stability>


<stability>

<stability>

<stability> – specifying release and API stability

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.

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<version> | PEAR Manual | <license>


<license>

<license>

<license> – specifying software license and optional reference to license text

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.

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<stability> | PEAR Manual | <contents>


<contents>

<contents>

<contents> – specifying the contents of a release

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.

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<license> | PEAR Manual | <dir>


<dir>

<dir>

<dir> – documenting a directory in the <contents> tag

Documenting directories

The <dir> tag describes a directory in the package sources. A <dir> tag may contain other <dir> tags as well as <file> tags.

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

Attributes

Required attributes
Attribute name | Description
name | Name of the directory in the sources
Optional attributes
Attribute name | Description
baseinstalldir | Relative location where all files and subdirectories will be installed

Examples

An excerpt of the <contents> tag of a real package.xml:

 <contents>
  <dir name="/">
   <dir name="examples">
    <file name="authors.php" role="doc" />
   </dir>
   <dir name="HTML">
    <dir name="Template">
     <file name="PHPLIB.php" role="php" />
     <dir name="PHPLIB">
      <!-- more files -->
     </dir>
    </dir>
  </dir>
 </contents>

The baseinstalldir attribute is mostly used when the directory structure in the package source tree does not match the layout when installed (e.g. when the QuickForm/ directory needs to be installed as HTML/QuickForm/:

 <contents>
  <dir name="/" baseinstalldir="HTML">
   <dir name="QuickForm">
    <file name="Element.php" role="php" />
    <!-- would be installed as HTML/QuickForm/Element.php -->
   </dir>
  </dir>
</contents>
Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<contents> | PEAR Manual | <file>


<file>

<file>

<file> – documenting a file in the <contents> tag

Describing files

The <file> tag describes a file in a directory in the package sources. File tags may only occur as children of <dir> tags.

File Tasks can be used to modify files at package time or at installation.

Attributes

Required attributes
Attribute name | Description
name | Name of the file in the sources
role | Type of the file. See roles.
Optional attributes
Attribute name | Description
baseinstalldir | Relative location where all files and subdirectories will be installed
md5sum | MD5 hash about file contents.This is automatically generated when executing pear package, so you should never set it manually.
Note: Previous optional attributes (package.xml v1) 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.

Roles

The role attribute in the <file> tag defines what type the file has and in which location it should be installed.

Possible values
Role value | Description | Destination dir
"php" | PHP source file | $php_dir (your include path)
"doc" | Documentation or example file | $doc_dir/Package_Name/
"data" | Package related data files (graphics, data tables, CSS etc.) | $data_dir/Package_Name/
"www" | Files for the HTTPd document root | $www_dir/
"test" | Package related test files (unit-tests etc) | $test_dir/Package_Name/
"script" | Package related shell scripts | the PHP binary directory ($bin_dir) or PHP_PEAR_BIN_DIR if defined
"ext" | Extension, dynamically loadable library | the PHP extension directory ($ext_dir) or PHP_PEAR_EXTENSION_DIR if defined
"src" / "extsrc" | C or C++ source code | not copied directly - used to build a extension

Directory locations like $php_dir are configurable in PEAR. You can use pear config-show or pear config-get php_dir to retrieve their values.

Examples

<contents>
<dir name="/">
<dir name="examples">
<!-- gets installed as $doc_dir/Package_Name/examples/authors.php -->
<file name="authors.php" role="doc" />
<file name="authors.tpl" role="doc" />
<file name="README" role="doc" />
</dir>

<dir name="HTML">
<dir name="Template">
<!-- gets installed as $php_dir/HTML/Template/PHPLIB.php -->
<file name="PHPLIB.php" role="php" />
<dir name="PHPLIB">
<file name="Generator.php" role="php" />
<file name="Helper.php" role="php" />
<file name="Tool.php" role="php" />
<file name="Validator.php" role="php" />
</dir>
</dir>
</dir>
<dir name="tests">
<file name="AllTests.php" role="test" />
<file name="GeneratorTest.php" role="test" />
<file name="HelperTest.php" role="test" />
<file name="ValidatorTest.php" role="test" />
</dir>
</dir>
</contents>
Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<dir> | PEAR Manual | tasks for <file>s


tasks for <file>s

tasks for <file>s

tasks for <file>s – specialized file installation and manipulation

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.

<tasks:replace> - customizing file contents

The replace task has 3 required attributes:

  1. type - This must be either package-info or pear-config. package-info replacements extract information from package.xml itself to use as the replacement text. pear-config replacements use the value of a configuration variable (as displayed by

    pear config-show

    ) as the text for replacement.

  2. from - Text to search for in a file. Traditionally, this text is enclosed in "@" to differentiate it from normal text, as in from="@version@"

  3. to - Abstract item to use as a replacement for all occurrences of "from". package-info replacements can be one of api-state, api-version, channel, date, description, license, license-uri, name, notes, release_date, release-license, release_notes, state, summary, time, version, and for some packages extends, providesextension, srcpackage, and srcuri.

Note that package-info replacements are performed at packaging time, so files contain package-info replacements inside a .tgz/.tar release. pear-config replacements can only occur on the installation system, and are performed at install-time.

<tasks:windowseol> - converting line endings to \r\n

This task can be used to enable packaging of windows-specific files (like DOS batch files) on a non-windows system, such as unix systems that convert line endings to \n. Note that this task is performed at package-time, as well as at install-time, so files will contain the correct line endings inside a .tgz/.tar release.

<tasks:unixeol> - converting line endings to \n

This task can be used to enable packaging of unix-specific files (like sh shell scripts) on a non-unix system, such as windows systems that convert line endings to \r\n. Note that this task is performed at package-time, as well as at install-time, so files will contain the correct line endings inside a .tgz/.tar release.

<tasks:postinstallscript> - extreme customization

The postinstallscript task informs the installer that the file it references is a post-installation script.

For security reasons, post-install scripts must be manually executed by the users, and as such the installer has special code that is separate from other tasks.

The <postinstallscript> tag may define parameters that are used by the installer to retrieve user input. In order to support both the web installer and the command-line installer, all processing of input is performed by PEAR and passed to the post-install script in a strict format. All you need to do is define the parameters using xml inside the <postinstallscript> tag.

Here is the xml representing a simple post-install script with parameters:

<tasks:postinstallscript>
 <tasks:paramgroup>
  <tasks:id>first</tasks:id>
  <tasks:param>
   <tasks:name>test</tasks:name>
   <tasks:prompt>Testing Thingy</tasks:prompt>
   <tasks:type>string</tasks:type>
  </tasks:param>
 </tasks:paramgroup>
</tasks:postinstallscript>

Note that the only type recognized at this stage is "string" but others will follow. A more complex example follows:

<tasks:postinstallscript>
 <tasks:paramgroup>
  <tasks:id>first</tasks:id>
  <tasks:instructions>The first group of questions relates
   primarily to your favorite color.  Answer wisely.
  </tasks:instructions>
  <tasks:param>
   <tasks:name>test</tasks:name>
   <tasks:prompt>Testing Thingy</tasks:prompt>
   <tasks:type>string</tasks:type>
   <tasks:default>hi</tasks:default>
  </tasks:param>
  <tasks:param>
   <tasks:name>test2</tasks:name>
   <tasks:prompt>Testing Thingy 2</tasks:prompt>
   <tasks:type>string</tasks:type>
  </tasks:param>
 </tasks:paramgroup>
 <tasks:paramgroup>
  <tasks:id>second</tasks:id>
  <tasks:name>first::test</tasks:name>
  <tasks:conditiontype>preg_match</tasks:conditiontype>
  <tasks:value>g+</tasks:value>
  <tasks:param>
   <tasks:name>test</tasks:name>
   <tasks:prompt>Testing Thingy a</tasks:prompt>
   <tasks:type>string</tasks:type>
   <tasks:default>hi</tasks:default>
  </tasks:param>
  <tasks:param>
   <tasks:name>test2</tasks:name>
   <tasks:prompt>Testing Thingy b</tasks:prompt>
   <tasks:type>string</tasks:type>
  </tasks:param>
 </tasks:paramgroup>
</tasks:postinstallscript>

This post-installation script has two parameter groups. The first parameter group has special instructions that are displayed to the user to assist in answering the required prompts. After the first group is processed, the second group is processed (naturally). However, in this case, the second group is a conditional parameter group. A conditional parameter group examines the user input from previous parameter groups and only displays its parameter prompts if a single parameter fits a test. The condition is defined by three tags, <tasks:name>, <tasks:conditiontype>, and <tasks:value>. Note that all three tags are required or xml validation will fail.

<tasks:name> is the parameter name from a previous parameter group. The format of name is groupID::parameterName, so as you see above, "first::test" refers to the <tasks:param> test from the <tasks:paramgroup> first.

<tasks:conditiontype> determines how the parameter input function will process the value of the parameter specified in <tasks:name>, and can be one of three values, "=" "!=" or "preg_match".

  • =: This (obviously) tests whether the parameters value is equal to the <tasks:value> tag

  • !=: This (obviously) tests whether the parameters value is not equal to the <tasks:value> tag

  • preg_match: This uses the content of the <tasks:value> tag as if it were the stuff between / and / in a preg_match() function call. Do NOT include // brackets in the regular expression. In the <tasks:paramgroup> second, the value "g+" will become:

    <?php
    preg_match    ('/g+/', first::test value)
    ?>
Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<file> | PEAR Manual | <compatible>


<compatible>

<compatible>

<compatible> – Alleviating strict versioning with <compatible>

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.

See also:

<package> dependencies

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
tasks for <file>s | PEAR Manual | <dependencies>


<dependencies>

<dependencies>

<dependencies> – Dependency Specification in package.xml 2.0

Introduction to dependencies in package.xml 2.0

Dependencies can be tricky to manage. Using code written by other people requires a robust and simple mechanism to manage the risk of breaking your code because of bugs in the external package, or worse, an unexpected API change. PEAR excels at dependency handling, which mitigates these risks. As a PEAR developer, it is crucial to understand how to specify a dependency on other packages as well as the system requirements of your package.

In package.xml 1.0, dependencies are relatively simple, but not as powerful. 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.

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 (documented here).

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.

Structure of <dependencies>

The <dependencies> tag re-organizes dependencies into groups and "extracts" attributes into tags. It also un-abbreviates words for clarity and human-readability. The following excerpt of a package.xml version 1.0:

<deps>
 <dep type="pkg" rel="ge" version="1.3.1">Archive_Tar</dep>
 <dep type="php" rel="ge" version="4.2.0"/>
 <dep type="pkg" rel="has" optional="yes">PEAR_Frontend_Web</dep>
</deps>

Approximately translates into this format in package.xml 2.0:

<dependencies>
 <required>
  <pearinstaller>
   <min>1.4.8</min>
  </pearinstaller>
  <php>
   <min>4.2.0</min>
  </php>
  <package>
   <name>Archive_Tar</name>
   <channel>pear.php.net</channel>
   <min>1.3.1</min>
  </package>
 </required>
 <optional>
  <package>
   <name>PEAR_Frontend_Web</name>
   <channel>pear.php.net</channel>
  </package>
 </optional>
</dependencies>

These changes were made to simplify xml validation and parsing. Note that unlike package.xml 1.0, the <pearinstaller> and <php> dependencies are required in all package.xml. In addition the <min> tag is required in both <pearinstaller> and <php> dependencies.

Optional Dependency Groups

Optional dependency groups define feature sets that are not required, but should be installed in a block. These feature sets consist of <package> and <extension> dependencies. For instance, if a package can optionally perform operations on a remote shell, it would create an optional dependency group named remoteshell with dependencies on the ssh2 PECL extension and the (fictional) SSH_RemoteShell package. The dependency group could look like this in package.xml:

<group name="remoteshell" hint="Add support for Remote Shell Operations">
 <package>
  <name>SSH_RemoteShell</name>
  <channel>pear.php.net</channel>
 </package>
 <extension>
  <name>ssh2</name>
 </extension>
</group>

To install this dependency group, the user would simply use pear install Packagename#remoteshell.

<pearinstaller> dependencies

The <pearinstaller> dependency defines the minimum version of PEAR that can properly parse and install the package.xml containing it. As with all dependency tags that support versioning, these 4 tags are supported to define versioning:

  • <min> - minimum version of PEAR required to install this package.xml. This tag is required in all package.xml <pearinstaller> dependencies.

  • <max> - maximum version of PEAR installer supported. Use with caution! This tag will prevent the package from being installed by anyone with a newer version of PEAR!

  • <recommended> - recommended version of PEAR installer. This tag is used for strict version control. The installer will refuse to install a package without the --force option unless the version exactly matches recommended. This can be used to provide a level of extra security, as a package can be set to install using a version that is known to work without limiting future upgrades.

  • <exclude> - incompatible versions of PEAR installer. Use this to prevent the package from being installed by any PEAR version that cannot properly install the package. Multiple <exclude> tags may be used to exclude more than one version.

<php> dependencies

As with all dependency tags that support versioning, these 4 tags are supported to define versioning:

  • <min> - minimum version of PHP required to install this package.xml. This tag is required in all package.xml <php> dependencies.

  • <max> - maximum version of PHP supported.

  • <exclude> - incompatible versions of PHP. Use this to prevent the package from being installed by any PHP version that cannot properly work with the package. Multiple <exclude> tags may be used to exclude more than one version.

<subpackage> dependencies

Subpackage dependencies share the same xml format as package dependencies. The subpackage dependency should only be used if a package is split into more than one package. In other words, if the child package contains the same files as any earlier version of the parent package, the child package would normally conflict with the parent package because it would be attempting to overwrite the parent package's files with its own files.

A simple example should make this clear. Package Foo 1.0.0 contains Foo.php and Foo/Bar.php. Package Foo's developers decide to split Foo into two packages: Foo and Foo_Bar. Foo 1.1.0 contains foo.php, and Foo_Bar 0.1.0 contains Foo/Bar.php. Foo_Bar 0.1.0 conflicts directly with Foo 1.0.0, as both contain the file Foo/Bar.php.

If Foo has a subpackage dependency on Foo_Bar, then the installer will ignore the conflict between Foo 1.0.0's Foo/Bar.php and Foo_Bar 0.1.0's Foo/Bar.php just as it ignores the conflict between Foo 1.0.0's Foo.php and Foo 1.1.0's Foo.php.

<package> dependencies

Understandably, the <package> dependency is PEAR's most complex dependency. PEAR 1.4.0 supports 3 different kinds of package dependencies:

  1. Normal, traditional channel server-based package dependencies (same idea as package.xml 1.0).

  2. Dependencies on packages that provide PHP extensions (like PECL packages). (These can be both server-based and uri-based dependencies)

  3. Static, non-traditional uri-based package dependencies.

channel-based <package> depedendencies

The most common kind of package dependency is a channel-based dependency. This dependency from package.xml version 1.0:

<deps>
 <dep type="pkg" rel="has">PEAR</dep>
</deps>

translates to this dependency in package.xml version 2.0:

<dependencies>
 <required>
<!-- ... -->
  <package>
   <name>PEAR</name>
   <channel>pear.php.net</channel>
  </package>
 </required>
</dependencies>

Note that <channel> is a required tag for all typical package dependencies. Use pear.php.net for all packages that were packaged using package.xml 1.0, regardless of where they are downloaded from.

As with all dependency tags that support versioning, all standard versioning tags are supported (min, max, recommended, exclude). In addition, the <conflicts> tag is supported to create a negative dependency.

  • <min> - minimum version of a dependency. If the dependency package is installed, and is older than this version, installation will fail.

  • <max> - maximum version of a dependency. If the dependency package is installed, and is newer than this version, installation will fail.

  • <recommended> - recommended version of a dependency. This tag is used for strict version control. The installer will refuse to install a package without the --force option unless the version exactly matches recommended. This can be used to provide a level of extra security, as a package can be set to install using a version that is known to work without limiting future upgrades.

    Note that use of the <compatible> tag in the dependency's package.xml can be used to circumvent the installer's strictness. In essence, the <compatible> tag tells the installer that a dependent package is compatible with the current package, even though it is not the recommended version.

  • <exclude> - incompatible versions of a package. Multiple <exclude> tags may be used to exclude more than one version of a dependency.

  • <conflicts> - Negates the dependency. If the package is installed, it cannot satisfy the requirements of the dependency or installation will fail.

Here is a rough chart describing how to convert from package.xml 1.0 "rel" attributes to a package.xml 2.0 equivalent.

Converting package.xml 1.0 package dependencies to package.xml 2.0
1.0 2.0 equivalent
<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>

uri-based <package> dependencies

Let's look at uri-based package dependencies. Here is a simple example:

<package>
 <name>Foo<name>
 <uri>http://www.example.com/Foo-1.3.0</uri>
</package>

This dependency tells the installer to fetch http://www.example.com/Foo-1.3.0.tgz or http://www.example.com/Foo-1.3.0.tar (both must be available!) if the package Foo is not installed. All uri packages must contain a <uri> tag rather than a <channel> tag and will automatically belong to the pseudo-channel "__uri", but that is not important to the discussion of how to format the xml to create the uri-based package dependency.

uri-based package dependencies cannot contain any versioning information, as this is irrelevant: there is only one version possible with a static uri. uri-based dependencies can contain the <conflicts/> tag to specify an absolute conflict with the package, and the <providesextension> tag to specify an extension provided by the static package.

PEAR-style <package> dependencies vs. PECL-style <package> dependencies

package.xml 2.0 supports differentiating release types, and as such also supports dependencies on PECL-style packages that use the extbinrelease or extsrcrelease type.

To specify a dependency on a PHP extension that can be distributed as a PECL package, but could also be bundled with PHP by default, such as the PDO extension, use this dependency style:

<package>
 <name>PDO</name>
 <channel>pecl.php.net</channel>
 <min>0.3.1</min>
 <providesextension>PDO</providesextension>
</package>

The magic is in the <providesextension> tag. This tag tells the installer to take this process when validating the dependency:

  1. Is the extension "PDO" present in memory? If so, is it version 0.3.1 or higher?

  2. If not, is the user also installing pecl.php.net/PDO at the same time as this package? If so, is it version 0.3.1 or higher?

  3. If not, is pecl.php.net/PDO installed, and is the version 0.3.1 or higher?

If any of the three conditions above validate in the order specified, the dependency will be satisfied and installation will continue. This system allows users to use a different php.ini to install PHP extensions and also provides a fail-safe system to depend on extensions.

<providesextension>, like all other extension-related functions in PHP, is case-sensitive. Do not use "pdo" for the "PDO" extension, or your dependency will always fail.

<extension> dependencies

As with all dependency tags that support versioning, all standard versioning tags are supported (min, max, recommended, exclude). In addition, the <conflicts> tag is supported to create a negative dependency.

  • <min> - minimum version of PHP extension to install this package.xml.

  • <max> - maximum version of PHP extension supported.

  • <recommended> - recommended version of PHP extension. This tag is used for strict version control. The installer will refuse to install a package without the --force option unless the version exactly matches recommended. This can be used to provide a level of extra security, as a package can be set to install using a version that is known to work without limiting future upgrades.

  • <exclude> - incompatible versions of PHP extension. Multiple <exclude> tags may be used to exclude more than one version.

  • <conflicts> - Negates the dependency. If the extension is present, it cannot satisfy the requirements of the dependency or installation will fail.

<os> dependencies

The OS dependency is used to restrict a package to both a particular class of OSes (like unix) and to a specific OS (like darwin, or freebsd). Here is an example:

<os>
 <name>linux</name>
</os>

To specify that a package can be installed on every OS except the one specified, use the <conflicts/> tag:

<os>
 <name>windows</name>
 <conflicts/>
</os>

Possible OS values are:

  • windows

  • unix

  • linux

  • freebsd

  • darwin (use for Mac OS X)

  • sunos

  • irix

  • hpux

  • aix

In addition, any esoteric OS that supports the php_uname() function can be used. Note that the "unix" OS is defined as any of linux, freebsd, darwin, sunos, irix, hpux, or aix.

<arch> dependencies

The arch dependency is used to restrict a package to a specific os and processor architecture. Here is an example:

<arch>
 <pattern>linux-*-i386-*</pattern>
</arch>

To specify that a package can be installed on every architecture except the one specified, use the <conflicts/> tag:

<arch>
 <pattern>linux-*-i?86-*</pattern>
 <conflicts/>
</arch>

The arch pattern is defined by the OS_Guess->matchSignature() method, and is as follows: sysname[-release[-cpu[-extra]]]. All segments within [] are optional, and the wildcard "*" can be used in all segments instead of a value. In addition, the "?" wildcard can be used to specify a single character that can match any value. i?86 will match i386, i686, i586 and so on.

sysname is the same as the os dependency, except unix is not supported.

release is the version of the operating system.

cpu is the specific cpu, and is typically i?86, sparc, powerpc.

extra is any other stuff on the end of php_uname(), including the glibc version

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<compatible> | PEAR Manual | <usesrole>


<usesrole>

<usesrole>

<usesrole> – documenting custom file roles used in <contents>

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>
Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<dependencies> | PEAR Manual | <usestask>


<usestask>

<usestask>

<usestask> – documenting custom tasks used in <contents>

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>
Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<usesrole> | PEAR Manual | <phprelease>, <extbinrelease>, <extsrcrelease>, <bundle>


<phprelease>, <extbinrelease>, <extsrcrelease>, <bundle>

<phprelease>, <extbinrelease>, <extsrcrelease>, <bundle>

<phprelease>, <extbinrelease>, <extsrcrelease>, <bundle> – specifying the content type of a release

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.

<phprelease>

The phprelease release type is designed for PEAR-style PHP script package releases. It causes a few specific validation changes. First of all, the <contents> tag must contain <file> and <dir> tags. The only valid roles for files are role="php", role="data", role="doc", and role="test" plus any custom roles that the user has installed for use in php releases.

<extsrcrelease>

The extsrcrelease release type is for PECL-style PHP extension releases that must be compiled in order to be useable. It causes a few specific validation changes. First of all, the <contents> tag must contain <file> and <dir> tags. The only valid roles for files are role="src", role="data", role="doc", and role="test" plus any custom roles that the user has installed for use in extension source releases.

In addition, the <providesextension> tag must be present in order to document the name of the extension this package provides must be in the package.xml as well.

<extbinrelease>

The extbinrelease release type is for PECL-style PHP Extension binary releases that are pre-compiled. It causes a few specific validation changes. First of all, the <contents> tag must contain <file> and <dir> tags. The only valid roles for files are role="ext", role="data", role="doc", and role="test" plus any custom roles that the user has installed for use in extension binary releases.

In addition, the <srcpackage> or <srcuri> and the <providesextension> tags must be present in order to document the package that provides extension source for this binary release, and the name of the extension this package provides must be in the package.xml as well.

<bundle>

The bundle release type is designed to allow packaging several other package releases into a single bundle of packages that will all be installed at the same time. This can be used to distribute a complete application as one tarball, or to distribute a library of packages in a single tarball.

Unlike the other release types, a bundle release's <contents> tag must contain only the <bundledpackage> tag. The contents of the bundledpackage should be release names like "Foo-1.2.3.tgz"

In addition, the <bundle/> tag must be empty.

Prev | Detailed Tag Reference for package.xml version 2.0 | Next
<usestask> | PEAR Manual | Releasing A Package


Releasing A Package

Releasing A Package

Table of Contents
  • Prerequisites
  • Validating The Package Definition File
  • Packaging The Release Tarball
  • Releasing The Package Through The Web Interface

The steps required from package maintainers to release a package.

Edited By

Tal Peer

2003-03-20

Prev | PEAR Developer Guide | Next
<phprelease>, <extbinrelease>, <extsrcrelease>, <bundle> | PEAR Manual | Prerequisites


Prerequisites

Prerequisites

Rolling a new release requires that the package to which the release belongs has been approved by the PEAR developers and that you have a valid PEAR website account. Information about meeting these two requirements can be found in the chapter Contributing your own code.

Please also read the various PEAR Group regulations that cover aspects like Version Naming, File Layout and other important topics not yet discussed in this manual. Furthermore there are a number of RFC's that followed these group regulations. These can be found under R for RFC in the finished PEPr proposals. Unfortunately these documents have not yet been included in a summarized coherent format in this manual. Please ask questions if you are in doubt about any of these documents.

Prev | Releasing A Package | Next
Releasing A Package | PEAR Manual | Validating The Package Definition File


Validating The Package Definition File

Validating The Package Definition File

Next, you should check the package definition file (package.xml) for validity. This is done by running the command: pear package-validate package.xml. Fix the errors and warnings, if any, and proceed to the next step.

Note: For help with writing the package definition file see the package definition file description.
Prev | Releasing A Package | Next
Prerequisites | PEAR Manual | Packaging The Release Tarball


Packaging The Release Tarball

Packaging The Release Tarball

Now that your package has a valid package definition file, you can package the release tarball. Cd to the top-level directory of the package and run: pear package This will create the release tarball that will be used later to upload the new release.

Note: Please note that the zlib extension needs to be enabled in your PHP build in order to create the release tarball.

Next, you should install the package locally by running: pear install <file> (file is the tarball you just created). This is done to ensure that the package definition file is not only valid but also contains valid information. You should manually check that every file is installed in the right place. If your package contains test scripts, which is highly recommended, you should run them.

If anything fails at this stage, correct it and re-package and re-test. When everything seems OK, proceed.

Prev | Releasing A Package | Next
Validating The Package Definition File | PEAR Manual | Releasing The Package Through The Web Interface


Releasing The Package Through The Web Interface

Releasing The Package Through The Web Interface

First, you should login to the PEAR website using the account you've been given (see the first step).

Now, finally, you can release your package. This is done again using the convenient web interface. Use the form at http://pear.php.net/release-upload.php.

That's it! Your package has been released, an announcement has been sent to the mailing lists.

Note: You should subscribe yourself to the pear-general mailing list. This, besides IRC, is the first place users of your package will ask for help.
Prev | Releasing A Package | Next
Packaging The Release Tarball | PEAR Manual | Supporting PEAR development


Supporting PEAR development

Supporting PEAR development

Table of Contents
  • Supporting PEAR -- How to support the PEAR community

Edited By

Martin Jansen

2002-05-27

Prev | PEAR Developer Guide | Next
Releasing The Package Through The Web Interface | PEAR Manual | Supporting PEAR


Supporting PEAR

How to support the PEAR community

There are numerous ways to support the PEAR project, that are described in this part of the guide.

Reporting and fixing bugs

There is a chapter devoted to reporting and fixing bugs in the "Reporting Bugs" section of the manual, found here.

Contributing new features to packages

If you have a feature you would like to see included in a package, don't hesitate to contact the maintainer of the package. You can find out who the maintainer of a package is by browsing the package list on the PEAR website and selecting the desired package. The maintainer(s) is/are listed on the package information page.

Becoming the new maintainer for an unmaintained package

If a developer has given up the maintainership of his package, you can take over this job. If you feel brave enough to answer support questions, fix bugs and manage release cycles, you can contact the previous maintainer or the PEAR developers mailing list and announce your will to maintain the package.

Buying things from wishlists

For all the PEAR developers, PEAR is a project they are working on in their free-time, which means that they don't earn any money with it. If you or the company you are working for is using a PEAR package in one of your/their (commercial) products, you/they can do this for free, of course. But if you think that the author of the package you are using desires some credits, it would be nice to buy something from his wishlist at Amazon or another internet store. To see if a PEAR developer has registered his wishlist, surf to the Account information page and select the developer from the list there. If he has a wishlist, it's noted somewhere on the detail page.

Prev | Supporting PEAR development | Next
Supporting PEAR development | PEAR Manual | Documentation


Documentation

Documentation

Table of Contents
  • Obtaining the manual sources
  • Rendering the manual
  • Docbook XML
  • Writing documentation
  • Translating PEAR's documentation
  • Questions?

Documentation is a critical part of PEAR. Even the most interesting and helpful package will not be used without proper documentation that helps users understand it.

Documentation for a package in PEAR means two things:

  • API documentation that explains all classes, methods and functions a package provides

  • Chapters and paragraphs about the package itself: What the package can be used for, how to use it, and examples.

API documentation is automatically generated after a package has been released on pear.php.net from the code using phpDocumentor.

The second type of documentation needs to be created manually. It is the documentation you see in this very manual below the packages book.

At first you will learn how to obtain and render this manual before going into detail about writing documentation for your own package.

Prev | PEAR Developer Guide | Next
Supporting PEAR | PEAR Manual | Obtaining the manual sources


Obtaining the manual sources

Obtaining the manual sources

The Docbook XML sources of the documentation are hosted on php.net's CVS server in the peardoc module.

The checkout process is relatively simple:

$ cvs -d :pserver:&lt;user&gt;@cvs.php.net:/repository login
[password]
$ cvs -d :pserver:&lt;user&gt;@cvs.php.net:/repository co
peardoc

Details about this process as well as anonymous login data can be found on php.net's CVS page.

Note: You need rights for the peardoc CVS module to be able to commit. Along with pear karma, every developer should have gotten the appropriate rights to peardoc. This is how it should be in theory, but one will probably have to send a mail to pear-dev@lists.php.net asking for documentation karma.
Prev | Documentation | Next
Documentation | PEAR Manual | Rendering the manual


Rendering the manual

Rendering the manual

The PEAR documentation gets - like the PHP Manual - built using PHP's very own DocBook rendering system called PhD. Installation is a breeze using pear:

$ pear install doc.php.net/phd-beta
...
$ phd --version
PhD version: phd-from-cvs
Copyright (c) 2007-2009 The PHP Documentation Group
Note: When using PEAR before verson 1.8.0, you need to discover the channel first.

Besides that, one only needs a CVS checkout of the peardoc module.

Preparing the build

Before building, you need to use the configure.php script provided by peardoc. This script serves two purposes:

  • Validate XML

  • Combine all xml files into one large single file to speed up the build process

Just change into your peardoc source folder and run:

$ php configure.php
Generating chapters.ent for en
 3376 xml files
 6 php example files
 done
Loading manual into one giant file
Validating done
Now call phd: phd -L en -f xhtml -t pearchunkedhtml -o build/en -d .manual.xml

If you see that lines, everything is fine and you can continue compiling the manual.

Note: Like with every proper unix tool, you can use php configure.php --help to get an overview about the supported command line parameters.

In case something goes wrong, the config script will tell you either where it failed, or which commands to execute to find the right spot:

$ php configure.php
Generating chapters.ent for en
 3376 xml files
 6 php example files
 done
Loading manual into one giant file
There were warnings loading the manual Warning:
 DOMDocument::load(): Opening and ending tag mismatch:
 set line 46 and book in
 /home/cweiske/Dev/cvs/pear/peardoc/manual.xml, line: 67 in
 /home/cweiske/Dev/cvs/pear/peardoc/configure.php on line 278
....
Exception: Failed to load manual.xml

Fix the error and run configure.php again until it tells you everything is ok.

Compiling the manual

Now that you configured everything properly, run the command that configure.php told you. The command will be something along that:

$ phd -L en -f xhtml -t pearchunkedhtml -o build/en/ -d .manual.xml
Note: configure.php generated a giant manual file named .manual.xml. If you use plain manual.xml your build will take about double as long as with .manual.xml (note the leading dot).

When PhD doesn't report any errors, your generated HTML documentation will be available in build/en/html/.

Partial builds

When writing documentation for a single package, you probably don't always want to compile the whole manual. PhD allows you to compile a small part of the manual which is faster than doing the whole thing. Just pass "-p package.category.packagename" as parameter to PhD, and only the part of the manual below that ID will be created.

Note: At the time of writing, partial rendering in PhD is not noticable faster than creating the whole manual. This will change in the future, though.
Tip

In case you didn't change the structure (adding or removing IDs), you can skip PhD index creation (-I) which will save you about 15-20 seconds build time.

Other sources to test your documentation

Several PEAR members regularly build the documentation on their own machine in shorter cycles than the pear.php.net server. When you don't have the chance to test and build your changes, you can use any of this build servers to check everything is fine:

Regular builds provided by PEAR members
PEAR member | Build interval | Format | Build log
Brett Bieber | 2 hours | Chunked HTML | log
Benedikt Hallinger | at 06:00 and 18:00 CEST | Chunked HTML | log
Prev | Documentation | Next
Obtaining the manual sources | PEAR Manual | Docbook XML


Docbook XML

Docbook XML

DocBook is an XML dialect that is used by a wide range of projects to maintain their documentation. Examples for DocBook usage in OpenSource projects are the documentations of KDE and PHP. PEAR has opted for using DocBook because we believe that it provides a solid foundation for the technical documentation for PEAR packages.

The trade-off for using DocBook is that it is relatively hard to use. Testing documentation requires a special tool to be installed and one needs to learn a (not very complicated) XML dialect. Once one is familiar with how DocBook works they will enjoy writing documentation with it though.

The book DocBook: The Definitive Guide, written by Norman Walsh and Leonard Muellner and published by O'Reilly & Associates, Inc., is available online and it makes up a great resource for people interested in learning DocBook.

Definitely check out the book's DocBook Element Reference section. This portion provides detailed information about each element, including which elements can (and must) be used as parents and children.

Prev | Documentation | Next
Rendering the manual | PEAR Manual | Writing documentation


Writing documentation

Writing documentation

Instead of a long and boring description for writing documentation using DocBook, we would like to point you to a bunch of "reference documents", from which you should be able to learn quickly:

  • Console_ProgressBar - small documentation for a small package

  • System_Daemon - medium sized documentation on several pages

The scope of your package's documentation should be:

  • Explain which problem your package solves

  • Describe differences to other packages solving identical or similar problems

  • Give example how to use the package

  • (Maybe) give an introduction to concepts your package uses and that the user probably does not know/is not aware of

The documentation should not repeat the API docs! You should only link to it. The documentation for older packages often contains the whole API reference, but that is not the manual's scope anymore - phpDocumentor does a much better job at generating it automatically.

Package documentation file structure

Files in peardoc
Filename | Description
packages/ | Directory containing all package-specific documentation
category.xml | Description of a category
category-entities.xml | File with links to all packages in that category. Exists in english documentation only.
category/ | Directory with documentation of packages in that category
package.xml | Main file for documentation of a specific package
package/ | Files for the package documentation are collected in here, e.g. examples.xml

Committing changes into CVS

Before committing your changes into peardoc CVS, test and build it! This is absolutely necessary - it makes sure that other people writing documentation can build the manual without problems, and that the official pear.php.net build works.

The manual on pear.php.net is build once a week, 12:00 UTC every sunday. If it breaks, it will take a whole week until the next build attempt is made!

So do not commit updates shortly before the main build happens.

Note: If you don't have peardoc karma, write to the peardoc mailing list to get it. It is also possible to send a patch to the list and get someone with karma to commit it.

Tips for good documentation

This section of the chapter does not deal with the specifics of organizing documentation in the peardoc standard, but instead with how to organize documentation logically.

  1. Every package solves a problem. What is this problem? Try to figure out what assumptions your end-users might not have about the problem (they may not realize that this is a problem that needs solving). For instance, a template package solves the problem of both separating design from code, and separating business logic from display logic. If possible, explain the problem in terms that even a novice programmer can understand.

  2. Next, how does the package uniquely solve the problem? This is something that most documentation lacks. For example, there are many template engines. All of them solve the same problem, but none of them do it in the same way. A block-based template engine does not have any logic at all, whereas a template like Smarty defines a whole new template language. Some template engines compile their templates, others don't. What is unique about your package? Can someone who has never seen the code get a good idea of how it solves the problem?

  3. Provide examples! Start right away with simple examples that show the basic feature set -- they will show users how to quickly start using the package. More complex examples will help the users in understanding advanced ways of using the package.

  4. If your package exposes complex interfaces or multiple constants that can't be fully explained in one or two examples (which is very likely), it is still important to explain them thoroughly in the documentation. Document any interfaces that users must use, such as a database DSN, command-line arguments for applications, configuration file contents, or any other non-code elements.

  5. Last, proofread your documentation. If possible, have someone else who is not as familiar with your project take a look at the documentation. They will catch assumptions that you have missed.

Software assistance

PEAR documentation is mostly written using plain text editors like vim or Kate. XML editors mostly don't help enough to be more useful than text editors; plus no tool yet is able to work with the entity linking structure used in peardoc.

One way to get documentation easily is writing initial package documentation using an XML editor like XXE, and make the necessary adjustments for peardoc after that. After doing that, you probably won't be able to use the XML editor anymore without losing data.

Prev | Documentation | Next
Docbook XML | PEAR Manual | Translating PEAR's documentation


Translating PEAR's documentation

Translating PEAR's documentation

FIXME

Prev | Documentation | Next
Writing documentation | PEAR Manual | Questions?


Questions?

Questions?

We are well aware that we cannot cover all questions about writing DocBook documentation in this chapter. If you have more questions or problems, do not hesitate to get in touch with the documentation team at pear-doc@lists.php.net. To join the pear-doc list send an email to pear-doc-subscribe@lists.php.net.

Prev | Documentation | Next
Translating PEAR's documentation | PEAR Manual | package.xml


package.xml

The package definition file package.xml (deprecated)

Table of Contents
  • Introduction -- Introduction to the package definition file package.xml
Prev | PEAR Developer Guide | Next
Questions? | PEAR Manual | Introduction


Introduction

Introduction to the package definition file package.xml

package.xml version 1.0 is deprecated

package.xml 1.0 is deprecated. You should really be using package.xml version 2.0. Documentation can be found at package.xml 2.0 documentation.

As of 2007-04, More than 99.8% of all PEAR installations in the wild are capable of using package.xml 2.0 files, so you should not worry about backwards compatibility.

The package definition file package.xml is, as the name already implies, a well-formed XML file that contains all information about a PEAR package.

This chapter will describe the allowed elements of the package definition file and it will discuss how to create such a file for your package.

The PEAR_PackageFileManager package simplifies the creation of package.xml. You can install PEAR_PackageFileManager via the usual command

$ pear install PEAR_PackageFileManager

Allowed elements

The toplevel element in package.xml is the element <package version="1.0">. The allowed sub elements are:

  • <name>: The name of the package.

  • <summary>: Short summary of the package's description.

  • <description>: Full length description of the package.

  • <license>: The license of the package (LGPL, PHP License etc.).

  • <maintainers>: Information about the maintainers of the package.

    • maintainer: Information about a single maintainer. (May be used multiple times.)

      • <user>: The account name of the user.

      • <role>: The role the user has during package development. (Can be either lead, developer, helper.)

      • <name>: The realname of the user.

      • <email>: The email address of the user.

  • <release>: Information about the current release.

    • <version>: The version number of the release.

    • <state>: The state of the release. (Can be one of stable, beta, alpha, devel, or snapshot.)

    • <date>: The date when the release has been rolled.

    • <license>: The license under which the code is available.

    • <notes>: Releasenotes

    • <filelist>

      • <file name="xxx" role="xxx" />: Filename

      • <dir name="xxx" [role="xxx"]>: Name of a subdirectory. This subdirectory can again contain <file role="xxx"> entries.

    • <deps>: List of dependencies of the package.

      • <dep type="xxx" rel="yyy" optional="yes">name</dep> : For more information about dependencies, please see below.

  • <changelog>: Changelog-like information about the package.

    • <release>

      • <version>: Version of the specific release.

      • <state>: State of the specific release.

      • <date>: Date when the specific release has been rolled.

      • <notes>: Changelog information

Allowed characters

The letters allowed inside elements are A-Z and a-z. Other characters, such as é must use entities (in this case: &eacute;).

If you create your package.xml files using the PEAR_PackageFileManager, upgrade your PEAR installation to version 1.4.0a2 or greater and you won't have to worry about this because the file manager takes care of this automatically.

If you write your package.xml files manually, you will need to enter the entities yourself. A list of the most common entities can be found at: http://www.evolt.org/article/A_Simple_Character_Entity_Chart/17/21234/ If the characters you need aren't in that list, go to http://www.oasis-open.org/docbook/xmlcharent/0.1/index.shtml and look at the other entity lists.

Validating

In order to validate package.xml files one can use the xmllint tool that comes with libxml2.

xmllint --dtdvalid http://pear.php.net/dtd/package-1.0 --noout package.xml

Creating a package definition file

Basic package.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0">
 <name>Money_Fast</name>
 <summary>Make money fast.</summary>
 <description>
  This package helps you to make money pretty fast.
 </description>
 <license>PHP License</license>
 <maintainers>
  <maintainer>
   <user>foo</user>
   <name>Joe Foo</name>
   <email>foo@example.com</email>
   <role>lead</role>
  </maintainer>
 </maintainers>

 <release>
  <version>1.0</version>
  <date>2002-05-27</date>
  <state>stable</state>
  <notes>
   This is the first release.
  </notes>
  <filelist>
   <dir name="/" baseinstalldir="Money">
    <file role="php" name="Fast.php" />
   </dir>
  </filelist>
 </release>
</package>

This package.xml can serve as a template for you as it already contains all necessary elements. In most cases you only need to change the character data between the tags in order to use the example in your package.

Example for nested directories

<?xml version="1.0" encoding="ISO-8859-1" ?>

[...]

 <release>
  <version>1.0</version>
  <date>2002-07-23</date>
  <state>stable</state>
  <notes>
   This is the first release.
  </notes>
  <filelist>
   <dir name="/" baseinstalldir="Money">
    <file role="php" name="Fast.php" />
    <dir name="Calculator">
     <file name="Calculator.php" role="php" />
     <file name="Currency.php" role="php" />
     <file name="Stocks.php" role="php" />
    </dir>
    <dir name="docs">
     <file name="README.txt" role="doc" />
     <file name="tutorial.txt" role="doc" />
     <dir name="examples">
      <file name="NASDAQ.php" role="php" />
      <file name="DAX.php" role="php" />
     </dir>
    </dir>
   </dir>
  </filelist>
 </release>
</package>

In this example you get to know a very handy feature: When you have a directory in your package that only contains files of the same type, you can add to role attribute even to the <dir> tag instead of adding it to every single <file> tag.

With the knowledge you've acquired from this chapter you should now be able to produce a package definition file for your own package. If you still have questions concerning the topic, don't hesitate to ask on the mailinglist.

The file roles

The role-attribute in the <file> tag defines what type the file has and in which location it should be installed.

Possible values
Value |  | Destination dir
php | PHP source file | the directory is determined by the package name
ext | Extension, dynamically loadable library | the PHP extension directory or PHP_PEAR_EXTENSION_DIR if defined
doc | Documentation file | {PEAR_documentation_dir}/Package_Name/
data | Package related data files (graphics, data tables etc) | {PEAR_data_dir}/Package_Name/
test | Package related test files (unit-tests etc) | {PEAR_test_dir}/Package_Name/
script | Package related shell scripts | the PHP binary directory or PHP_PEAR_BIN_DIR if defined
src and extsrc | C or C++ source code | not copied directly - used to build a extension

Defining Dependencies

The PEAR Package Manager supports checking for different system capabilities. You define those dependencies with the <dep> tag:

package.xml with dependencies

The following example shows how to specify dependencies for PHP 4.3.0 or better and XML_Parser 1.0.

<?xml version="1.0" encoding="ISO-8859-1" ?>

[...]
 </release>
 <deps>
  <dep type="php" rel="ge" version="4.3.0" />
  <dep type="pkg" rel="has" version="1.0">XML_Parser</dep>
 </deps>
</package>

The type-attribute

The following types are supported:

type values
Value |  | Meaning | Example
pkg | Package | depends on a certain Package | "HTML_Flexy"
ext | Extension | depends on a certain PHP extension | "curl"
php | PHP | depends on a certain PHP version | "4.2"
prog | Program | depends on a certain Program available in the system path. This is not supported in the PEAR installer. | "latex"
os | Operating System | depends on a certain OS version | "Linux"
sapi | Server API | depends on a certain Server API. This is not supported in the PEAR installer. | "Apache"
zend | Zend | depends on a certain version of the Zend API. This is not supported in the PEAR installer. | "2"

The DTD for the package definition file supports further types, but those are not supported yet.

The rel-attribute

The rel-attribute defines the relationship between the existing capability and the required.

rel values
Value |  | Meaning | Can be used with
has | has | the existing capability must have the requirement - version-attribute is ignored | pkg, ext, php, prog, os, sapi, zend
eq | equal | the existing capability must exactly match the version value | pkg, ext, php, prog, os, sapi, zend
lt | less than | the existing capability must be less than the version value | pkg, ext, php, zend
le | less than or equal | the existing capability must be less than or equal to the version value | pkg, ext, php, zend
gt | greater than | the existing capability must be greater than the version value | pkg, ext, php, zend
ge | greater than or equal | the existing capability must greater than or equal to the version value | pkg, ext, php, zend
not | conflicting dependency | the dependency conflicts with the package, the two cannot co-exist. version is ignored. | ext, php

Has will be used if no other value has been defined. Note that rel is required in PEAR 1.4.0 and newer.

The version-attribute

The attribute version defines the version that is used to compare.

The optional-attribute

The attribute optional can be used when a dependency is not required but having the package installed can bring enhanced functionalities. The only legal values are "yes" and "no". If the optional attribute is not present, a dependency is required. When optional="yes" is used, this attribute will result in installation messages similar to the following messages:

$ pear install <package>
Optional dependencies:
Package `XML_Tree' is recommended to utilize some features.
Package `MDB' is recommended to utilize some features.

Prev | package.xml | Next
package.xml | PEAR Manual | Coding Standards


Coding Standards

Coding Standards

Table of Contents
  • Coding Standards
  • PEAR2 Coding Standards
  • PEAR2 Policies
  • Recommendations
Prev | PEAR Developer Guide | Next
Introduction | PEAR Manual | Coding Standards


Coding Standards

Coding Standards

Table of Contents
  • Indenting and Line Length
  • Control Structures
  • Function Calls
  • Class Definitions
  • Function Definitions
  • Arrays
  • Comments
  • Including Code
  • PHP Code Tags
  • Header Comment Blocks
  • Using CVS
  • Example URLs
  • Naming Conventions
  • File Formats
  • E_STRICT-compatible code
  • Error Handling Guidelines
  • Best practices
  • Sample File (including Docblock Comment standards)
  • The PEAR toolbox
Note: The PEAR Coding Standards apply to code that is part of the official PEAR distribution. Coding standards often abbreviated as CS among developers and they aim to keep code consistent to be easily readable and maintainable by most of PEAR folks.

The original coding standards have been adjusted several times through RFCs:

  • Coding standard enhancements

  • Error Handling Guidelines for PHP5 packages

  • Header Comment Blocks

  • Protected members

  • Requiring E_STRICT Compatibility for New PEAR Packages

Those RFCs have been integrated into this document.

Note: The PEAR2 Coding Standards define several other rules that have to be followed once PEAR2 is in place.
Prev | Coding Standards | Next
Coding Standards | PEAR Manual | Indenting and Line Length


Indenting and Line Length

Indenting and Line Length

Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, CVS history and annotations.

For Emacs you should set indent-tabs-mode to nil. Here is an example mode hook that will set up Emacs (ensure that it is called when you are editing PHP files):

(defun php-mode-hook ()
  (setq tab-width 4
        c-basic-offset 4
        c-hanging-comment-ender-p nil
        indent-tabs-mode
  (not
    (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
      (string-match "\.php$" (buffer-file-name))))))

Here are Vim rules for the same thing:

set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4

It is recommended to keep lines at approximately 75-85 characters long for better code readability. Paul M. Jones has some thoughts about that limit.

Prev | Coding Standards | Next
Coding Standards | PEAR Manual | Control Structures


Control Structures

Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:

<?php
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<?php
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}
?>

Split long if statements onto several lines

Long if statements may be split onto several lines when the character/line limit would be exceeded. The conditions have to be positioned onto the following line, and indented 4 characters. The logical operators (&&, ||, etc.) should be at the beginning of the line to make it easier to comment (and exclude) the condition. The closing parenthesis and opening brace get their own line at the end of the conditions.

Keeping the operators at the beginning of the line has two advantages: It is trivial to comment out a particular line during development while keeping syntactically correct code (except of course the first line). Further is the logic kept at the front where it's not forgotten. Scanning such conditions is very easy since they are aligned below each other.

<?php

if (($condition1
    || $condition2)
    && $condition3
    && $condition4
) {
    //code here
}
?>

The first condition may be aligned to the others.

<?php

if (   $condition1
    || $condition2
    || $condition3
) {
    //code here
}
?>

The best case is of course when the line does not need to be split. When the if clause is really long enough to be split, it might be better to simplify it. In such cases, you could express conditions as variables an compare them in the if() condition. This has the benefit of "naming" and splitting the condition sets into smaller, better understandable chunks:

<?php

$is_foo = ($condition1 || $condition2);
$is_bar = ($condition3 && $condtion4);
if ($is_foo && $is_bar) {
    // ....
}
?>
Note: There were suggestions to indent the parantheses "groups" by 1 space for each grouping. This is too hard to achieve in your coding flow, since your tab key always produces 4 spaces. Indenting the if clauses would take too much finetuning.

Ternary operators

The same rule as for if clauses also applies for the ternary operator: It may be split onto several lines, keeping the question mark and the colon at the front.

<?php

$a = $condition1 && $condition2
    ? $foo : $bar;

$b = $condition3 && $condition4
    ? $foo_man_this_is_too_long_what_should_i_do
    : $bar;
?>
Prev | Coding Standards | Next
Indenting and Line Length | PEAR Manual | Function Calls


Function Calls

Function Calls

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:

<?php
$var = foo($bar, $baz, $quux);
?>

As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:

<?php
$short         = foo($bar);
$long_variable = foo($baz);
?>

To support readability, parameters in subsequent calls to the same function/method may be aligned by parameter name:

<?php

$this->callSomeFunction('param1',     'second',        true);
$this->callSomeFunction('parameter2', 'third',         false);
$this->callSomeFunction('3',          'verrrrrrylong', true);
?>

Split function call on several lines

The CS require lines to have a maximum length of 80 chars. Calling functions or methods with many parameters while adhering to CS is impossible in that cases. It is allowed to split parameters in function calls onto several lines.

<?php

$this->someObject->subObject->callThisFunctionWithALongName(
    $parameterOne, $parameterTwo,
    $aVeryLongParameterThree
);
?>

Several parameters per line are allowed. Parameters need to be indented 4 spaces compared to the level of the function call. The opening parenthesis is to be put at the end of the function call line, the closing parenthesis gets its own line at the end of the parameters. This shows a visual end to the parameter indentations and follows the opening/closing brace rules for functions and conditionals.

The same applies not only for parameter variables, but also for nested function calls and for arrays.

<?php

$this->someObject->subObject->callThisFunctionWithALongName(
    $this->someOtherFunc(
        $this->someEvenOtherFunc(
            'Help me!',
            array(
                'foo'  => 'bar',
                'spam' => 'eggs',
            ),
            23
        ),
        $this->someEvenOtherFunc()
    ),
    $this->wowowowowow(12)
);
?>

Nesting those function parameters is allowed if it helps to make the code more readable, not only when it is necessary when the characters per line limit is reached.

Using fluent application programming interfaces often leads to many concatenated function calls. Those calls may be split onto several lines. When doing this, all subsequent lines are indented by 4 spaces and begin with the "->" arrow.

<?php

$someObject->someFunction("some", "parameter")
    ->someOtherFunc(23, 42)
    ->andAThirdFunction();
?>

Alignment of assignments

To support readability, the equal signs may be aligned in block-related assignments:

<?php

$short  = foo($bar);
$longer = foo($baz);
?>

The rule can be broken when the length of the variable name is at least 8 characters longer/shorter than the previous one:

<?php

$short = foo($bar);
$thisVariableNameIsVeeeeeeeeeeryLong = foo($baz);
?>

Split long assigments onto several lines

Assigments may be split onto several lines when the character/line limit would be exceeded. The equal sign has to be positioned onto the following line, and indented by 4 characters.

<?php

$GLOBALS['TSFE']->additionalHeaderData[$this->strApplicationName]
    = $this->xajax->getJavascript(t3lib_extMgm::siteRelPath('nr_xajax'));
?>
Prev | Coding Standards | Next
Control Structures | PEAR Manual | Class Definitions


Class Definitions

Class Definitions

Class declarations have their opening brace on a new line:

<?php
class Foo_Bar
{

    //... code goes here

}
?>
Prev | Coding Standards | Next
Function Calls | PEAR Manual | Function Definitions


Function Definitions

Function Definitions

Function declarations follow the "K&R style":

<?php
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
?>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<?php
function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}
?>

Split function definitions onto several lines

Functions with many parameters may need to be split onto several lines to keep the 80 characters/line limit. The first parameters may be put onto the same line as the function name if there is enough space. Subsequent parameters on following lines are to be indented 4 spaces. The closing parenthesis and the opening brace are to be put onto the next line, on the same indentation level as the "function" keyword.

<?php

function someFunctionWithAVeryLongName($firstParameter = 'something', $secondParameter = 'booooo',
    $third = null, $fourthParameter = false, $fifthParameter = 123.12,
    $sixthParam = true
) {
    //....
?>
Prev | Coding Standards | Next
Class Definitions | PEAR Manual | Arrays


Arrays

Arrays

Assignments in arrays may be aligned. When splitting array definitions onto several lines, the last value may also have a trailing comma. This is valid PHP syntax and helps to keep code diffs minimal:

<?php

$some_array = array(
    'foo'  => 'bar',
    'spam' => 'ham',
);
?>
Prev | Coding Standards | Next
Function Definitions | PEAR Manual | Comments


Comments

Comments

Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the phpDocumentor website.

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

Prev | Coding Standards | Next
Arrays | PEAR Manual | Including Code


Including Code

Including Code

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once will not be included again by include_once.

Note: include_once and require_once are statements, not functions. Parentheses should not surround the subject filename.
Prev | Coding Standards | Next
Comments | PEAR Manual | PHP Code Tags


PHP Code Tags

PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups.

Prev | Coding Standards | Next
Including Code | PEAR Manual | Header Comment Blocks


Header Comment Blocks

Header Comment Blocks

All source code files in the PEAR repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.

<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.01 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_01.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_01.txt  PHP License 3.01
 * @version    CVS: <?php
$
?> Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */

/*
* Place includes, constant defines and $_GLOBAL settings here.
* Make sure they have appropriate docblocks to avoid phpDocumentor
* construing they are documented by the page-level docblock.
*/

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_01.txt  PHP License 3.01
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class Foo_Bar
{
}

?>

Required Tags That Have Variable Content

Short Descriptions

Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item. Please read the Coding Standard's Sample File about how to write good descriptions.

PHP Versions

One of the following must go in the page-level docblock:

* PHP version 4
 * PHP version 5
 * PHP versions 4 and 5
@license

There are several possible licenses. One of the following must be picked and placed in the page-level and class-level docblocks:

* @license   http://www.apache.org/licenses/LICENSE-2.0  Apache License 2.0
 * @license   http://www.freebsd.org/copyright/freebsd-license.html  BSD License (2 Clause)
 * @license   http://www.debian.org/misc/bsd.license  BSD License (3 Clause)
 * @license   http://www.freebsd.org/copyright/license.html  BSD License (4 Clause)
 * @license   http://www.opensource.org/licenses/mit-license.html  MIT License
 * @license   http://www.gnu.org/copyleft/lesser.html  LGPL License 2.1
 * @license   http://www.php.net/license/3_01.txt  PHP License 3.01

For more information, see the PEAR Group's Licensing Announcement.

@link

The following must be used in both the page-level and class-level docblocks. Of course, change "PackageName" to the name of your package. This ensures the generated documentation links back your package.

* @link      http://pear.php.net/package/PackageName
@author

There's no hard rule to determine when a new code contributor should be added to the list of authors for a given source file. In general, their changes should fall into the "substantial" category (meaning somewhere around 10% to 20% of code changes). Exceptions could be made for rewriting functions or contributing new logic.

Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors.

@since

This tag is required when a file or class is added after the package's initial release. Do not use it in an initial release.

@deprecated

This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.

Optional Tags

@copyright

Feel free to apply whatever copyrights you desire. When formatting this tag, the year should be in four digit format and if a span of years is involved, use a hyphen between the earliest and latest year. The copyright holder can be you, a list of people, a company, the PHP Group, etc. Examples:

* @copyright 2003 John Doe and Jennifer Buck
 * @copyright 2001-2004 John Doe
 * @copyright 1997-2004 The PHP Group
 * @copyright 2001-2004 XYZ Corporation
License Summary

If you are using the PHP License, use the summary text provided above. If another license is being used, please remove the PHP License summary. Feel free to substitute it with text appropriate to your license, though to keep things easy to locate, please preface the text with LICENSE: .

@see

Add a @see tag when you want to refer users to other sections of the package's documentation. If you have multiple items, separate them with commas rather than adding multiple @see tags.

Order and Spacing

To ease long term readability of PEAR source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard.

@package_version@ Usage

There are two ways to implement the @package_version@ replacements. The procedure depends on whether you write your own package.xml files or if you use the PackageFileManager.

For those authoring package.xml files directly, add a <replace> element for each file. The XML for such would look something like this:

<file name="Class.php">
  <replace from="@package_version@" to="version" type="package-info" />
</file>

Maintainers using the PackageFileManager need to call addReplacement() for each file:

<?php
$pkg->addReplacement('filename.php', 'package-info',
                     '@package_version@', 'version');
?>

Transition Policy

Existing Small Packages

Existing packages that have only a few files are required to adopt these docblocks before the next release.

Existing Large Packages

Existing packages with many files are encouraged to adopt the new headers as soon as possible. When such packages come out with a new major version upgrade, these docblocks must be implemented therein.

New and Unreleased Packages

New packages and existing packages which have no releases yet must include these docblocks before their first release.

Prev | Coding Standards | Next
PHP Code Tags | PEAR Manual | Using CVS


Using CVS

Using CVS

This section applies only to packages using CVS at cvs.php.net.

Include the $Id$ CVS keyword in each file.

The rest of this section assumes that you have basic knowledge about CVS tags and branches.

CVS tags are used to label which revisions of the files in your package belong to a given release. Below is a list of the required and suggested CVS tags:

RELEASE_n_n_n

(required) Used for tagging a release. If you don't use it, there's no way to go back and retrieve your package from the CVS server in the state it was in at the time of the release.

QA_n_n_n

(branch, optional) If you feel you need to roll out a release candidate before releasing, it's a good idea to make a branch for it so you can isolate the release and apply only those critical fixes before the actual release. Meanwhile, normal development may continue on the main trunk.

MAINT_n_n_n

(branch, optional) If you need to make "micro-releases" (for example 1.2.1 and so on after 1.2.0), you can use a branch for that too, if your main trunk is very active and you want only minor changes between your micro-releases.

Only the RELEASE tag is required, the rest are recommended for your convenience.

Below is an example of how to tag the 1.2.0 release of the Money_Fast package:

$ cd pear/Money_Fast
$ cvs tag RELEASE_1_2_0
T Fast.php
T README
T package.xml

By doing this you make it possible for the PEAR web site to take you through the rest of your release process.

Here's an example of how to create a QA branch:

$ cvs tag QA_2_0_0_BP

...

$ cvs rtag -b -r QA_2_0_0_BP QA_2_0_0
$ cvs update -r QA_2_0_0
$ cvs tag RELEASE_2_0_0RC1

...and then the actual release, from the same branch:

$ cvs tag RELEASE_2_0_0

The QA_2_0_0_BP tag is a "branch point" tag, which is the start point of the tag. It's always a good idea to start a CVS branch from such branch points. MAINT branches may use the RELEASE tag as their branch point.

Prev | Coding Standards | Next
Header Comment Blocks | PEAR Manual | Example URLs


Example URLs

Example URLs

Use example.com, example.org and example.net for all example URLs and email addresses, per RFC 2606.

Prev | Coding Standards | Next
Using CVS | PEAR Manual | Naming Conventions


Naming Conventions

Naming Conventions

Global Variables and Functions

If your package needs to define global variables, their names should start with a single underscore followed by the package name and another underscore. For example, the PEAR package uses a global variable called $_PEAR_destructor_object_list.

Global functions should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). In addition, they should have the package name as a prefix, to avoid name collisions between packages. The initial letter of the name (after the prefix) is lowercase, and each letter that starts a new "word" is capitalized. An example:

XML_RPC_serializeData()

Classes

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter. The PEAR class hierarchy is also reflected in the class name, each level of the hierarchy separated with a single underscore. Examples of good class names are:

Log

Net_Finger

HTML_Upload_Error

Class Variables and Methods

Class variables (a.k.a properties) and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Some examples (these would be "public" members):

$counter

connect()

getData()

buildSomeWidget()

Private class members are preceded by a single underscore. For example:

$_status

_sort()

_initTree()

Note: The following applies to PHP5.

Protected class members are not preceded by a single underscore. For example:

protected $somevar

protected function initTree()

Constants

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercased name of the class/package they are used in. Some examples:

DB_DATASOURCENAME

SERVICES_AMAZON_S3_LICENSEKEY

Note: The true, false and null constants are excepted from the all-uppercase rule, and must always be lowercase.
Prev | Coding Standards | Next
Example URLs | PEAR Manual | File Formats


File Formats

File Formats

All scripts contributed to PEAR must:

  • Be stored as ASCII text

  • Use ISO-8859-1 or UTF-8 character encoding. The encoding may be declared using declare(encoding = 'utf-8'); at the top of the file.

  • Be Unix formatted

    "Unix formatted" means two things:

    1) Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

    2) There should be one line feed after the closing PHP tag (?>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.

Prev | Coding Standards | Next
Naming Conventions | PEAR Manual | E_STRICT-compatible code


E_STRICT-compatible code

E_STRICT-compatible code

Starting on 01 January 2007, all new code that is suggested for inclusion into PEAR must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

The development of existing packages that are not E_STRICT-compatible can continue as usual. If however a new major version of the package is released, this major version must then be E_STRICT-compatible.

More details on this part of the Coding Standards can be found in the corresponding RFC.

Prev | Coding Standards | Next
File Formats | PEAR Manual | Error Handling Guidelines


Error Handling Guidelines

Error Handling Guidelines

This part of the Coding Standards describes how errors are handled in PEAR packages that are developed for PHP 5 and 6. It uses Exceptions, introduced in PHP 5.0 with Zend Engine 2, as the error handling mechanism.

Definition of an error

An error is defined as an unexpected, invalid program state from which it is impossible to recover. For the sake of definition, recovery scope is defined as the method scope. Incomplete recovery is considered a recovery.

One pretty straightforward example for an error

<?php
/*
 * Connect to Specified Database
 *
 * @throws Example_Datasource_Exception when it can't connect
 * to specified DSN.
 */
function connectDB($dsn)
{
    $this->db =& DB::connect($dsn);
    if (DB::isError($this->db)) {
        throw new Example_Datasource_Exception(
                "Unable to connect to $dsn:" . $this->db->getMessage()
        );
    }
}
?>

In this example the objective of the method is to connect to the given DSN. Since it can't do anything but ask PEAR DB to do it, whenever DB returns an error, the only option is to bail out and launch the exception.

Error handling with recovery

<?php
/*
 * Connect to one of the possible databases
 *
 * @throws Example_Datasource_Exception when it can't connect to
 * any of the configured databases.
 *
 * @throws Example_Config_Exception when it can't find databases
 * in the configuration.
 */

function connect(Config $conf)
{
    $dsns =& $conf->searchPath(array('config', 'db'));
    if ($dsns === FALSE) throw new Example_Config_Exception(
        'Unable to find config/db section in configuration.'
    );

    $dsns =& $dsns->toArray();

    foreach($dsns as $dsn) {
        try {
            $this->connectDB($dsn);
            return;
        } catch (Example_Datasource_Exception e) {
            // Some warning/logging code recording the failure
            // to connect to one of the databases
        }
    }
    throw new Example_Datasource_Exception(
        'Unable to connect to any of the configured databases'
    );
}
?>

This second example shows an exception being caught and recovered from. Although the lower level connectDB() method is unable to do anything but throw an error when one database connection fails, the upper level connect() method knows the object can go by with any one of the configured databases. Since the error was recovered from, the exception is silenced at this level and not rethrown.

Incomplete recovery

<?php
/*
 * loadConfig parses the provided configuration. If the configuration
 * is invalid, it will set the configuration to the default config.
 *
 */
function loadConfig(Config $conf)
{
    try {
        $this->config = $conf->parse();
    } catch (Config_Parse_Exception e) {
        // Warn/Log code goes here
        // Perform incomplete recovery
        $this->config = $this->defaultConfig;
    }
}
?>

The recovery produces side effects, so it is considered incomplete. However, the program may proceed, so the exception is considered handled, and must not be rethrown. As in the previous example, when silencing the exception, logging or warning should occur.

Error Signaling in PHP 5 PEAR packages

Error conditions in PEAR packages written for PHP 5 must be signaled using exceptions. Usage of return codes or return PEAR_Error objects is deprecated in favor of exceptions. Naturally, packages providing compatibility with PHP 4 do not fall under these coding guidelines, and may thus use the error handling mechanisms defined in the PHP 4 PEAR coding guidelines.

An exception should be thrown whenever an error condition is met, according to the definition provided in the previous section. The thrown exception should contain enough information to debug the error and quickly identify the error cause. Note that, during production runs, no exception should reach the end-user, so there is no need for concern about technical complexity in the exception error messages.

The basic PEAR_Exception contains a textual error, describing the program state that led to the throw and, optionally, a wrapped lower level exception, containing more info on the lower level causes of the error.

The kind of information to be included in the exception is dependent on the error condition. From the point of view of exception throwing, there are three classes of error conditions:

  1. Errors detected during precondition checks

  2. Lower level library errors signaled via error return codes or error return objects

  3. Uncorrectable lower library exceptions

Errors detected during precondition checks should contain a description of the failed check. If possible, the description should contain the violating value. Naturally, no wrapped exception can be included, as there isn't a lower level cause of the error. Example:

<?php
function divide($x, $y)
{
    if ($y == 0) {
        throw new Example_Aritmetic_Exception('Division by zero');
    }
}
?>

Errors signaled via return codes by lower level libraries, if unrecoverable, should be turned into exceptions. The error description should try to convey all information contained in the original error. One example, is the connect method previously presented:

<?php
/*
 * Connect to Specified Database
 *
 * @throws Example_Datasource_Exception when it can't connect to specified DSN.
 */
function connectDB($dsn)
{
    $this->db =& DB::connect($dsn);
    if (DB::isError($this->db)) {
        throw new Example_Datasource_Exception(
                "Unable to connect to $dsn:" . $this->db->getMessage()
        );
    }
}
?>

Lower library exceptions, if they can't be corrected, should either be rethrown or bubbled up. When rethrowing, the original exception must be wrapped inside the one being thrown. When letting the exception bubble up, the exception just isn't handled and will continue up the call stack in search of a handler.

Rethrowing an exception

<?php
function preTaxPrice($retailPrice, $taxRate)
{
    try {
        return $this->divide($retailPrice, 1 + $taxRate);
    } catch (Example_Aritmetic_Exception e) {
        throw new Example_Tax_Exception('Invalid tax rate.', e);
    }
}
?>

Letting exceptions bubble up

<?php
function preTaxPrice($retailPrice, $taxRate)
{
    return $this->divide($retailPrice, 1 + $taxRate);
}
?>

The case between rethrowing or bubbling up is one of software architecture: Exceptions should be bubbled up, except in these two cases:

  1. The original exception is from another package. Letting it bubble up would cause implementation details to be exposed, violating layer abstraction, conducing to poor design.

  2. The current method can add useful debugging information to the received error before rethrowing.

Exceptions and normal program flow

Exceptions should never be used as normal program flow. If removing all exception handling logic (try-catch statements) from the program, the remaining code should represent the "One True Path" -- the flow that would be executed in the absence of errors.

This requirement is equivalent to requiring that exceptions be thrown only on error conditions, and never in normal program states.

One example of a method that wrongly uses the bubble up capability of exceptions to return a result from a deep recursion:

<?php
/**
 * Recursively search a tree for string.
 * @throws ResultException
 */
public function search(TreeNode $node, $data)
{
    if ($node->data === $data) {
        throw new ResultException( $node );
    } else {
        search( $node->leftChild, $data );
        search( $node->rightChild, $data );
    }
}
?>

In the example the ResultException is simply using the "eject!" qualities of exception handling to jump out of deeply nested recursion. When actually used to signify an error this is a very powerful feature, but in the example above this is simply lazy development.

Exception class hierarchies

All of PEAR packages exceptions must be descendant from PEAR_Exception. PEAR_Exception provides exception wrapping abilities, absent from the top level PHP Exception class, and needed to comply with the previous section requirements.

Additionally, each PEAR package must provide a top level exception, named <Package_Name>_Exception. It is considered best practice that the package never throws exceptions that aren't descendant from its top level exception.

Documenting Exceptions

Because PHP, unlike Java, does not require you to explicitly state which exceptions a method throws in the method signature, it is critical that exceptions be thoroughly documented in your method headers.

Exceptions should be documented using the @throws phpdoc keyword

<?php
/**
 * This method searches for aliens.
 *
 * @return array Array of Aliens objects.
 * @throws AntennaBrokenException If the impedence readings indicate
 * that the antenna is broken.
 *
 * @throws AntennaInUseException If another process is using the
 * antenna already.
 */
public function findAliens($color = 'green');
?>

In many cases middle layers of an application will rewrap any lower-level exceptions into more meaningful application exceptions. This also needs to be made clear:

<?php
/**
 * Load session objects into shared memory.
 *
 * @throws LoadingException Any lower-level IOException will be wrapped
 * and re-thrown as a LoadingException.
 */
public function loadSessionObjects();
?>

In other cases your method may simply be a conduit through which lower level exceptions can pass freely. As challenging as it may be, your method should also document which exceptions it is not catching.

<?php
/**
 * Performs a batch of database queries (atomically, not in transaction).
 * @throws SQLException Low-level SQL errors will bubble up through this method.
 */
public function batchExecute();
?>

Exceptions as part of the API

Exceptions play a critical role in the API of your library. Developers using your library depend on accurate descriptions of where and why exceptions might be thrown from your package. Documentation is critical. Also maintaining the types of messages that are thrown is also an important requirement for maintaining backwards-compatibility.

Because Exceptions are critical to the API of your package, you must ensure that you don't break backwards compatibility (BC) by making changes to exceptions.

Things that break BC include:

  • Any change to which methods throw exceptions.

  • A change whereby a method throws an exception higher in the inheritance tree. For example, if you changed your method to throw a PEAR_Exception rather than a PEAR_IOException, you would be breaking backwards compatibility.

Things that do not break BC:

  • Throwing a subclass of the original exception. For example, changing a method to throw PEAR_IOException when before it had been throwing PEAR_Exception would not break BC (provided that PEAR_IOException extends PEAR_Exception).

Prev | Coding Standards | Next
E_STRICT-compatible code | PEAR Manual | Best practices


Best practices

Best practices

There are other things not covered by PEAR Coding Standards which are mostly subject of personal preference and not directly related to readability of the code. Things like "single quotes vs double quotes" are features of PHP itself to make programming easier and there are no reasons not use one way in preference to another. Such best practices are left solely on developer to decide. The only recommendation could be made to keep consistency within package and respect personal style of other developers.

Readability of code blocks

Related lines of code should be grouped into blocks, seperated from each other to keep readability as high as possible. The definition of "related" depends on the code :)

For example:

<?php

if ($foo) {
    $bar = 1;
}
if ($spam) {
    $ham = 1;
}
if ($pinky) {
    $brain = 1;
}
?>

is a lot easier to read when seperated:

<?php

if ($foo) {
    $bar = 1;
}

if ($spam) {
    $ham = 1;
}

if ($pinky) {
    $brain = 1;
}
?>

Return early

To keep readability in functions and methods, it is wise to return early if simple conditions apply that can be checked at the beginning of a method:

<?php

function foo($bar, $baz)
{
    if ($foo) {
        //assume
        //that
        //here
        //is
        //the
        //whole
        //logic
        //of
        //this
        //method
        return $calculated_value;
    } else {
        return null;
    }
}
?>

It's better to return early, keeping indentation and brain power needed to follow the code low.

<?php

function foo($bar, $baz)
{
    if (!$foo) {
        return null;
    }

    //assume
    //that
    //here
    //is
    //the
    //whole
    //logic
    //of
    //this
    //method
    return $calculated_value;
}
?>
Prev | Coding Standards | Next
Error Handling Guidelines | PEAR Manual | Sample File (including Docblock Comment standards)


Sample File (including Docblock Comment standards)

Sample File (including Docblock Comment standards)

The source code of PEAR packages are read by thousands of people. Also, it is likely other people will become developers on your package at some point in the future. Therefore, it is important to make life easier for everyone by formatting the code and docblocks in standardized ways. People can then quickly find the information they are looking for because it is in the expected location. Your cooperation is appreciated.

Each docblock in the example contains many details about writing Docblock Comments. Following those instructions is important for two reasons. First, when docblocks are easy to read, users and developers can quickly ascertain what your code does. Second, the PEAR website now contains the phpDocumentor generated documentation for each release of each package, so keeping things straight here means the API docs on the website will be useful.

Please take note of the vertical and horizontal spacing. They are part of the standard.

The "fold markers" (// {{{ and // }}}) are optional. If you aren't using fold markers, remove foldmethod=marker from the vim header.

<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.01 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_01.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_01.txt  PHP License 3.01
 * @version    CVS: <?php
$
?> Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */

/**
 * This is a "Docblock Comment," also known as a "docblock."  The class'
 * docblock, below, contains a complete description of how to write these.
 */
require_once 'PEAR.php';

// {{{ constants

/**
 * Methods return this if they succeed
 */
define('NET_SAMPLE_OK', 1);

// }}}
// {{{ GLOBALS

/**
 * The number of objects created
 * @global int $GLOBALS['_NET_SAMPLE_Count']
 */
$GLOBALS['_NET_SAMPLE_Count'] = 0;

// }}}
// {{{ Net_Sample

/**
 * An example of how to write code to PEAR's standards
 *
 * Docblock comments start with "/**" at the top.  Notice how the "/"
 * lines up with the normal indenting and the asterisks on subsequent rows
 * are in line with the first asterisk.  The last line of comment text
 * should be immediately followed on the next line by the closing asterisk
 * and slash and then the item you are commenting on should be on the next
 * line below that.  Don't add extra lines.  Please put a blank line
 * between paragraphs as well as between the end of the description and
 * the start of the @tags.  Wrap comments before 80 columns in order to
 * ease readability for a wide variety of users.
 *
 * Docblocks can only be used for programming constructs which allow them
 * (classes, properties, methods, defines, includes, globals).  See the
 * phpDocumentor documentation for more information.
 * http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
 *
 * The Javadoc Style Guide is an excellent resource for figuring out
 * how to say what needs to be said in docblock comments.  Much of what is
 * written here is a summary of what is found there, though there are some
 * cases where what's said here overrides what is said there.
 * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide
 *
 * The first line of any docblock is the summary.  Make them one short
 * sentence, without a period at the end.  Summaries for classes, properties
 * and constants should omit the subject and simply state the object,
 * because they are describing things rather than actions or behaviors.
 *
 * Below are the tags commonly used for classes. @category through @version
 * are required.  The remainder should only be used when necessary.
 * Please use them in the order they appear here.  phpDocumentor has
 * several other tags available, feel free to use them.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_01.txt  PHP License 3.01
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class Net_Sample
{
    // {{{ properties

    /**
     * The status of foo's universe
     *
     * Potential values are 'good', 'fair', 'poor' and 'unknown'.
     *
     * @var string
     */
    var $foo = 'unknown';

    /**
     * The status of life
     *
     * Note that names of private properties or methods must be
     * preceeded by an underscore.
     *
     * @var bool
     * @access private
     */
    var $_good = true;

    // }}}
    // {{{ setFoo()

    /**
     * Registers the status of foo's universe
     *
     * Summaries for methods should use 3rd person declarative rather
     * than 2nd person imperative, beginning with a verb phrase.
     *
     * Summaries should add description beyond the method's name. The
     * best method names are "self-documenting", meaning they tell you
     * basically what the method does.  If the summary merely repeats
     * the method name in sentence form, it is not providing more
     * information.
     *
     * Summary Examples:
     *   + Sets the label              (preferred)
     *   + Set the label               (avoid)
     *   + This method sets the label  (avoid)
     *
     * Below are the tags commonly used for methods.  A @param tag is
     * required for each parameter the method has.  The @return
     * and @access tags are mandatory.  The @throws tag is required if
     * the method uses exceptions.  @static is required if the method can
     * be called statically.  The remainder should only be used when
     * necessary.  Please use them in the order they appear here.
     * phpDocumentor has several other tags available, feel free to use
     * them.
     *
     * The @param tag contains the data type, then the parameter's
     * name, followed by a description.  By convention, the first noun in
     * the description is the data type of the parameter.  Articles like
     * "a", "an", and  "the" can precede the noun.  The descriptions
     * should start with a phrase.  If further description is necessary,
     * follow with sentences.  Having two spaces between the name and the
     * description aids readability.
     *
     * When writing a phrase, do not capitalize and do not end with a
     * period:
     *   + the string to be tested
     *
     * When writing a phrase followed by a sentence, do not capitalize the
     * phrase, but end it with a period to distinguish it from the start
     * of the next sentence:
     *   + the string to be tested. Must use UTF-8 encoding.
     *
     * Return tags should contain the data type then a description of
     * the data returned.  The data type can be any of PHP's data types
     * (int, float, bool, string, array, object, resource, mixed)
     * and should contain the type primarily returned.  For example, if
     * a method returns an object when things work correctly but false
     * when an error happens, say 'object' rather than 'mixed.'  Use
     * 'void' if nothing is returned.
     *
     * Here's an example of how to format examples:
     * <code>
     * require_once 'Net/Sample.php';
     *
     * $s = new Net_Sample();
     * if (PEAR::isError($s)) {
     *     echo $s->getMessage() . "\n";
     * }
     * </code>
     *
     * Here is an example for non-php example or sample:
     * <samp>
     * pear install net_sample
     * </samp>
     *
     * @param string $arg1 the string to quote
     * @param int    $arg2 an integer of how many problems happened.
     *                     Indent to the description's starting point
     *                     for long ones.
     *
     * @return int the integer of the set mode used. FALSE if foo
     *             foo could not be set.
     * @throws exceptionclass [description]
     *
     * @access public
     * @static
     * @see Net_Sample::$foo, Net_Other::someMethod()
     * @since Method available since Release 1.2.0
     * @deprecated Method deprecated in Release 2.0.0
     */
    function setFoo($arg1, $arg2 = 0)
    {
        /*
         * This is a "Block Comment."  The format is the same as
         * Docblock Comments except there is only one asterisk at the
         * top.  phpDocumentor doesn't parse these.
         */
        if ($arg1 == 'good' || $arg1 == 'fair') {
            $this->foo = $arg1;
            return 1;
        } elseif ($arg1 == 'poor' && $arg2 > 1) {
            $this->foo = 'poor';
            return 2;
        } else {
            return false;
        }
    }

    // }}}
}

// }}}

/*
 * Local variables:
 * tab-width: 4
 * c-basic-offset: 4
 * c-hanging-comment-ender-p: nil
 * End:
 */

?>
Prev | Coding Standards | Next
Best practices | PEAR Manual | The PEAR toolbox


The PEAR toolbox

The PEAR toolbox

PEAR provides some tools to help developers keep their code clean and free of coding standards related errors.

For one there is PHP_CodeSniffer which can be used to detect coding standard errors in your scripts. Further, whole PEAR CVS repository is checked each night for violations - the results can be found at PEAR QA results overview page as well as on the linked subpages which explain the errors in detail.

Prev | Coding Standards | Next
Sample File (including Docblock Comment standards) | PEAR Manual | PEAR2 Coding Standards


PEAR2 Coding Standards

PEAR2 Coding Standards

Table of Contents
  • Introduction
  • Rules

Coding Standards to be used in PEAR2 (version 1)

2007-12-24

Note: This document cannot be considered complete (e.g.: the future of namespaces is uncertain).

  • This document describes the coding standards and coding conventions for the new PEAR2 repository.

  • These coding standards will expire on March 1, 2008, and must be reviewed and renewed by the PEAR Group in order to continue

  • Packages that wish to be accepted into the PEAR2 repository must conform to these standards

  • The minimum PHP version supported will be the earliest version that supports namespaces, most likely PHP version 5.3.0. This RFC will be updated as soon as the exact version is known.

  • package.xml 2.0 or newer is required for all packages

Prev | Coding Standards | Next
The PEAR toolbox | PEAR Manual | Introduction


Introduction

Introduction

PEAR 1.x is very successful at managing the universe of PEAR-installable code. The new Pyrus installer is designed to expand that universe to include code that can also be easily embedded in non-PEAR applications and that runs identically when simply unzipped and when installed. The PEAR2 repository must adhere to different coding conventions than the PEAR repository to make this possible. This document itemizes all the changes to existing rules and coding standards found here. Any conflict between these standards and the existing standards resolves in favor of the new standards. These standards do not affect the coding standards for PEAR packages hosted at pear.php.net, only PEAR2 packages hosted at pear2.php.net.

require_once introduces a rigidity to package structure that limits the possible uses of a PEAR package. Some of the problems:

  • require_once can introduce up to a 10% performance penalty on high-volume sites using multi-processor web servers due to increased latency. However, most users would experience at most 2% performance penalty on single-processor systems (as measured by Yahoo! engineer Gopal Vijayaraghavan)

  • include_path is required in order to use a package. This makes it difficult to bundle a PEAR package within another application with its own include_path, to create a single file containing needed classes, to move a PEAR package to a phar archive without extensive source code modification.

  • When top-level require_once is mixed with conditional require_once, this can result in code that is uncacheable by opcode caches such as APC (to be bundled with PHP 6).

  • Relative require_once requires that include_path already be set up to the correct value, making it impossible to use a package without proper include_path.

Some of the benefits of require_once:

  • You know right away if a file is missing, with a Fatal Error: missing file X (this is mitigated by using __autoload() with PEAR2_Autoload()).

  • End-users don't need to know what files are within a package to use it (also mitigated by using __autoload() with PEAR2_Autoload()).

The removal of require_once necessitates another method for loading internal dependencies, both files within a package and external files. This proposal introduces 2 possible methods for doing this:

  • use __autoload() in conjunction with PEAR2's custom autoload solution (found here in svn)

  • construct a customized solution for loading needed files

In all cases, the onus of loading needed files is shifted to the end user. However, for beginning users, the only required step is to load PEAR2/Autoload.php, which will be always bundled with new packages, but only extracted if used as unzip-and-go (pyrus would simply install the dependency on PEAR2, which would contain the needed base files PEAR2_Exception and PEAR2_Autoload).

<?php
  require '/full/path/to/PEAR2/Autoload.php';
  // now you can start using all PEAR2 packages
?>

PEAR2/Autoload.php automatically sets up include_path if it does not contain the correct value, and also automatically declares an autoloader either using __autoload() or spl_autoload_register(), preserving existing autoloaders set up by the user.

Prev | PEAR2 Coding Standards | Next
PEAR2 Coding Standards | PEAR Manual | Rules


Rules

Rules

We will describe the list of rules that form the standards

Namespace prefix

All classes and functions must have a namespace of at the minimum PEAR2. An example:

<?php
namespace PEAR2;
class MyClass {}
?>

Classes may use longer namespaces, for instance an HTTP_Request class may instead choose to use this declarative syntax:

<?php
namespace PEAR2::HTTP;
class Request {}
?>

As such, underscores are no longer required of any classes if there is a namespace. Class PEAR2_HTTP_Request instead becomes PEAR2::HTTP::Request. Package names, however, will use underscores, making PEAR2_HTTP_Request the package name.

Requirement

No Exceptions to this rule

use of include/require/require_once/include_once not allowed

include/require/require_once/include_once is not allowed for loading class files. Users will be expected to load files either with __autoload() or a customized solution for more advanced users. Instead, classes should simply be used. import with a comment describing the class's location must be used to document all internal dependencies (as written below). Instead of:

<?php
require_once 'PEAR2/OtherPackage.php';
$class = new PEAR2::OtherPackage;
?>

this class should simply be used:

<?php
$class = new PEAR2::OtherPackage;
?>

This allows packages to work without modification no matter how they are structured on-disk, including running out of a single large file, inside a phar archive, and provides much-needed flexibility.

Requirement

No Exceptions to this rule

Directory structure

Follows the directory structure in the PEAR2 Subversion repository:

PEAR2/Package_Name/
    src/      <-- all role="php"
    data/     <-- all role="data"
    tests/    <-- all role="tests"
    doc/      <-- all role="doc"
    www/      <-- all role="www"
    examples/ <-- role="doc" example files
                  (php executable files that exemplify package usage)

Note that all package.xml files must specify a baseinstalldir of "/" for the src/ directory:

<contents>
  <dir name="/">
  <dir name="src" baseinstalldir="/">
  ...
</contents>

Requirement

Exceptions may be made to this rule with approval from the PEAR Group

Class-to-file convention

All public classes must be in their own file with underscores (_) or namespace separators (::) replaced by directory separator, so that PEAR2_PackageName_Base class or PEAR2::PackageName::Base class is always located in PEAR2/PackageName/Base.php (this is required to make autoload work)

Requirement

Exceptions may be made to this rule only with explicit approval from the PEAR Group via a public vote

Base Exception class

PEAR2::Exception is used as base class for all exception classes. Each package must define a base class that is packagename_Exception. For example, the PEAR2::PackageName class defines an exception as follows in PEAR2/PackageName/Exception.php:

<?php
namespace PEAR2::PackageName;
class Exception extends PEAR2::Exception {}
?>

'PEAR2::Exception will be its own package'

Requirement

No Exceptions to this rule

Data files

package.xml replacement tasks should not be used to retrieve path locations for php, data, or www files. Replacements are still allowed in doc and test files.

The installation structure of a package has implicit php_dir/src installation location, and data files are always located in php_dir/data/channel/PackageName/. To retrieve a data file within PEAR2/PackageName/Subfile.php, you could use code like this example

<?php
...
// retrieve data from info.txt
$info = file_get_contents(dirname(__FILE__) .
    '../../../data/pear2.php.net/PEAR2_PackageName/info.txt');
?>

Requirement

No Exceptions to this rule

Loading other classes

Inside optional component loading methods (like factory or driver loading, etc.) class_exists($classname, true) should be used where a "class not found" fatal error would be confusing. For example, when loading a driver, a graceful exit via exception with helpful error message is preferrable to the fatal error:

<?php
if (!class_exists("PEAR2_PackageName_Driver_$class", true)) {
    throw new PEAR2::PackageName::Exception('Unknown driver ' .
    $class . ', be sure the driver exists and is loaded
    prior to use');
}
?>

Requirement

This rule is optional and is a suggested coding practice

Prev | PEAR2 Coding Standards | Next
Introduction | PEAR Manual | PEAR2 Policies


PEAR2 Policies

PEAR2 Policies

Table of Contents
  • General policy rules

Policies in use in PEAR2 (version 0.2.0)

2008-04-07

Note: This document cannot be considered complete.

  • This document contains the general policies for how coding and collaboration works in PEAR2.

  • These policies will expire on December 1, 2008, and must be reviewed and renewed by the PEAR Group in order to continue

Prev | Coding Standards | Next
Rules | PEAR Manual | General policy rules


General policy rules

General policy rules

List of rules that apply to PEAR2

Commit access to the repository

All collective members have full commit access and can commit minor bugfixes without requesting permission or notifying lead developers. However, as a courtesy, it is expected that all developers will communicate with a package's lead developers prior to taking action. If a dispute over a commit arises, it is also expected that the commit in question will be reverted pending a review.

This rule is intended to encourage open and friendly collaboration. For an example of this commit model, the PHP project developers often commit minor fixes for thread-safe errors, spelling mistakes, and other obvious mistakes without consultation. Exceptions can be made to this rule with explicit PEAR Group approval documented on the website.

Handling package design

All design decisions should be discussed freely in a Collective, and each Collective is responsible for enforcing these decisions in their own way. Some Collectives may require packages to adhere to basic interfaces, others may require common data storage formats, but individual package maintainers must adhere to these decisions or discuss ways of improving them. No cowboy coding! Ultimately, individual package developers have the full freedom to innovate without expecting too much interference, but are expected to learn how to both give and receive constructive criticism as a part of the privilege of having their code hosted at pear.php.net.

Pulling releases

All collective members can pull a release within 24 hours if there is a major regression or security bug. If at all possible, the primary lead maintainers should perform this action, but Collectives function as a unit, and have the role of policing huge problems.

Competing packages

Competing packages are allowed at the alpha level in PEAR2.

All alpha/devel stability packages have no claim to a package name. If a better package comes along that does the same thing, wants your package's name and achieves beta status, you have to either join forces or change the name of your package. The limit is that newer packages have to be unarguably better in implementation. It is up to the Collective to define "unarguably better"

Stale packages

Any package that is alpha (in svn.pear.php.net/PEAR2/sandbox) and inactive for more than a year will be deleted

What beta status means

To become beta, a package must undergo extensive review.

  • documentation must be complete.

  • full test suite must demonstrate 50% code coverage

  • API must be approved by 2/3 of the collective developers (this will probably be a blanket stamp for most packages)

  • all developers in a collective (including alpha package maintainers) can vote on whether a package is ready for beta status

  • a final name for the package must be chosen by the lead developers of the package that does not conflict with the existing beta+ packages. Names are chosen on a first-come-first-serve basis.

Package acceptance into PEAR2

Packages can be proposed either as 1) A completed, or relatively complete package to Pepr 2) A concept, or proof-of-concept to svn.pear.php.net/PEAR2/sandbox For proof-of-concept packages they should

  • Post a public notice to the pear-dev mailing list stating the intention to begin development.

  • Request a new package be created on the pear.php.net website

  • Undergo a review by the collective (as defined in the previous section) when ready to move from alpha to beta stability

  • Once the review is complete, the package developers may request an official vote by the collective on whether the package is ready. The vote is conducted through PEPr. Unsuccessful packages may request a second review after fixing issues noted by the collective.

  • Successful packages may then move their development directly from svn.pear.php.net/PEAR2/alpha into svn.pear.php.net/PEAR2 using svn move.

Packages listed in the channel

Only packages with a status of beta or stable are added to the public channel

Version Control System

In order to submit code to PEAR2 you will need to use the provided svn repository.

Prev | PEAR2 Policies | Next
PEAR2 Policies | PEAR Manual | Recommendations


Recommendations

Recommendations

Table of Contents
  • Why recommendations?
  • Color Representation -- Color Representation inside PEAR Packages
  • Checking if a driver can be loaded
  • Writing informative release notes
  • Unit test configuration

Edited By

Stefan Neufeind

2004-02-29

Prev | Coding Standards | Next
General policy rules | PEAR Manual | Why recommendations?


Why recommendations?

Why recommendations?

The following best practises describe topics which were discussed and agreed upon by the PEAR developers on the developers mailinglist. They aren't strict rules, which you need to follow (like Coding Standards), but are intended as guidelines for a common API scheme and easier package interoperability. Please consider following them in your packages where possible.

Prev | Recommendations | Next
Recommendations | PEAR Manual | Color Representation


Color Representation

Color Representation inside PEAR Packages

In case a package has to deal with colors, it is recommended that developers store and use an array representation of the color values in their PEAR packages. All values are in the range of 0..255.

RGB representation

The following snippet defines an array that holds the RGB definition of the green coloring that is used in the official PEAR logo.

<?php
$color = array(0x33, 0x99, 0x00);
?>

or

<?php
$color = array(51, 153, 0);
?>

Please note that the internal, numerical representation of both forms of the example are equal. The values represent the RGB (red, green, blue) values. It was decided not to use "r", "g" and "b" as indices for the array, because numerical indices allow easier creation of color arrays in the sourcecode, make handling less complicated and are an already commonly used array representation for colors.

RGB representation with alpha-values

Since this an extension of the RGB representation above, it is recommended to use a fourth value for alpha-channel-presentation. An example of the "PEAR-green" with approximately 80% intensity would be:

<?php
$color = array(0x33, 0x99, 0x00, 0xCC);
?>

For consistency the alpha-value is also from the range 0..255. A value of 255 means fully opaque (full color-intensity, same as in RGB- notation), 0 means fully transparent.

Please note this is in contrast to the alpha-value used by imagecolorallocate(). The alpha-representation used in PEAR was chosen for consistency with the other RGB values and because it is commonly accepted practice in many other applications (image-processing tools, etc.).

Other color representations than RGB(A)

Since RGB/RGBA will used for graphic generation on a computer we decided to leave out an optional type-identifier classifying colors as RGB/RGBA. However for different color-representations an identifier is needed. The optional identifier "type" can be added to the color array.

<?php
$color = array(0x33, 0x99, 0x00, 0xCC, "type" => "RGB");
?>

Currently the following types are defined, with array-indices from 0..n following the color names listed beside them:

  • RGB - red, green, blue

  • CYMK - cyan, yellow, magenta, black (key)

Please note that also the RGBA representation has the type "RGB" since it's closely related.

Conversion to/between the color-representations

The PEAR-package Image_Color will (hopefully soon) contain all needed functions to convert arbitrary color formats to the internal RGBA representation and convert different color representations.

Status: Currently Image_Color already offers functions to convert color-names (e.g. "green") and hex-representations-strings (e.g. "#339900") to the PEAR-RGBA-format. We are working to get alpha- channel support added hopefully soon and will later add functions for CYMK-conversion as well.

Prev | Recommendations | Next
Why recommendations? | PEAR Manual | Checking if a driver can be loaded


Checking if a driver can be loaded

Checking if a driver can be loaded

In driver-based packages you should check if the driver exists before loading it. A simple file_exists() does not work since it does not check the include path. fopen()'s third parameter does that, so we use it.

<?php
$driver = 'SomeDriver';
$class  = 'My_Package_Driver_' . $driver;
$file   = str_replace('_', '/', $class) . '.php';

//check if it exists and can be loaded
if (!@fclose(@fopen($file, 'r', true))) {
    throw new My_Package_Driver_Exception(
        'Driver ' . $driver . ' cannot be loaded.'
    );
}

//continue with including the driver
require_once $file;

//...
?>
Prev | Recommendations | Next
Color Representation | PEAR Manual | Writing informative release notes


Writing informative release notes

Writing informative release notes

Before releasing a new package, you need to write the release notes in package.xml. The release notes should clearly say what has changed in comparison to the last release, or - when going to the next stablility level, like from beta to stable - list the changes since the last release of the same stability.

You probably want to outline new features, as well as list the bugs which have been fixed. It is important not only to plainly write down the bug numbers, but also the bug titles. People tend to recall words better than remembering the issues associated with a number. The PEAR web interface automatically links structures like "bug #<number>". In case several people fixed patches, the user's handle can be appended to the message.

Bad release notes

- Fixed bug #11495

Good release notes

Changes since the last stable version 1.2.3:

- Added foo and bar feature

- Blubber is far more efficient

Fixed bugs:

- Removed deprecated cURL option CURLOPT_MUTE (Bug #13489) [ashnazg]

- Changed the license to the New BSD License (Bug #13831) [helgi]

Minor issues:

- Converted package.xml to version 2.0

- Cleaned up code to (mostly) comply with phpcs

Prev | Recommendations | Next
Checking if a driver can be loaded | PEAR Manual | Unit test configuration


Unit test configuration

Unit test configuration

Every now and then your unit tests depend on external services - be it a database or LDAP server or a company's web service. Access to those services and servers require creditentials, be it username and password combinations or API keys.

Such confidential information may often not be distributed, and your unit tests should not have them coded into. Instead a separate config file template, config.php.dist, should be shipped. To run the tests, the user creates a copy of that configuration template, saves it as config.php and adjusts it.

Exemplary directory layout

tests/
    config.php.dist
    config.php

Exemplary configuration template

<?php
$GLOBALS['My_Package_UnittestConfig'] = array(
    'host'     => 'FIXME',
    'username' => 'FIXME',
    'password' => 'FIXME',
    'host'     => 'FIXME',
);
?>

You should not die() if no config file is found but let the unit test continue gracefully - this is important in combined suites, when several packages are unit tested in a row.

Instead, you should check if it exists first:

Checking if the configuration file exists

<?php
//...

class My_Package_ClassTest extends PHPUnit_Framework_TestCase
{
    protected $configExists = null;

    //...

    public function __construct($name = null)
    {
        parent::__construct($name);

        $configFile = dirname(__FILE__) . '/config.php';
        $this->configExists = file_exists($configFile);
        if ($this->configExists) {
            include_once $configFile;
        }
    }

    //...

    public function setUp()
    {
        if (!$this->configExists) {
            $this->markTestSkipped('Unit test configuration is missing.');
        }
        //...
    }

    //...
}
?>
Prev | Recommendations | Next
Writing informative release notes | PEAR Manual | PEAR Installer: Core components (Installer API, error handling)


PEAR Installer: Core components (Installer API, error handling)

PEAR Installer: Core components (Installer API, error handling)

Table of Contents
  • PEAR base classes
  • PEAR Installer classes
Prev | PEAR Developer Guide | Next
Unit test configuration | PEAR Manual | PEAR base classes


PEAR base classes

PEAR base classes

Table of Contents
  • PEAR base and error handling class -- PEAR
  • PEAR_Exception -- PEAR_Exception - PHP 5 and versions above
  • PEAR_ErrorStack
  • PEAR Error object -- PEAR_Error [deprecated]
  • System

The Core section provides information about the base classes in PEAR

Prev | PEAR Installer: Core components (Installer API, error handling) | Next
PEAR Installer: Core components (Installer API, error handling) | PEAR Manual | PEAR base and error handling class


PEAR base and error handling class

PEAR

Table of Contents
  • Introduction -- How to handle the PEAR base class (destructors, error handling)
  • Constants -- Predefined Constants
  • PEAR::PEAR() -- constructor (package developer related)
  • PEAR::_PEAR() -- Deconstructor (package developer related)
  • PEAR::getStaticProperty() -- handle static properties (package developer related)
  • PEAR::registerShutdownFunc() -- set a shutdown function for static classes (package developer related)
  • PEAR::isError() -- checks for a PEAR_Error object
  • PEAR::raiseError() -- Create a new PEAR_Error object and optionally specify error-handling instructions
  • PEAR::setErrorHandling() -- sets handling of errors generated through PEAR packages
  • PEAR::expectError() -- add an error code for non-disabling temporary error handling
  • PEAR::popExpect() -- removes the last error code for non-disabling temporary error handling
  • PEAR::loadExtension() -- OS independent PHP extension load

PEAR provides functions for handling errors and sets the behaviour in case of error. And, it gives package developers a set of functions to make their lives easier.

Prev | PEAR base classes | Next
PEAR base classes | PEAR Manual | Introduction


Introduction

Introduction

Introduction – How to handle the PEAR base class (destructors, error handling)

Synopsis

require_once "PEAR.php";
class classname extends PEAR { ... }

Description

The PEAR base class provides standard functionality that is used by most PEAR classes. Normally you never make an instance of the PEAR class directly, you use it by subclassing it.

Its key features are:

  • request-shutdown object "destructors"

  • error handling

PEAR "destructors"

If you inherit PEAR in a class called ClassName, you can define a method in it called _ClassName (the class name with an underscore prepended) that will be invoked when the request is over. This is not a destructor in the sense that you can "delete" an object and have the destructor called, but in the sense that PHP gives you a callback in the object when PHP is done executing. See the example below.

Important!

In order for destructors to work properly, you must instantiate your class with the "=& new" operator like this:

<?php
$obj =& new MyClass();
?>

If you only use "= new", the object registered in PEAR's shutdown list will be a copy of the object at the time the constructor is called, and it will be this copy's "destructor" that will be called upon request shutdown.

PEAR Error Handling

PEAR's base class also provides a way of passing around more complex errors than a true/false value or a numeric code. A PEAR error is an object that is either an instance of the class PEAR_Error, or some class inheriting PEAR_Error.

One of the design criteria of PEAR's errors is that it should not force a particular type of output on the user, it should be possible to handle errors without any output at all if that is desirable. This makes it possible to handle errors gracefully, also when your output format is different from HTML (for example WML or some other XML format).

The error object can be configured to do a number of things when it is created, such as printing an error message, printing the message and exiting, raising an error with PHP's trigger_error() function, invoke a callback, or none of the above. This is typically specified in PEAR_Error's constructor, but all of the parameters are optional, and you can set up defaults for errors generated from each object based on the PEAR class. See the PEAR error examples for how to use it and the PEAR_Error reference for the full details.

Examples

The example below shows how to use the PEAR's "poor man's kinda emulated destructors" to implement a simple class that holds the contents of a file, lets you append data to the object and flushes the data back to the file at the end of the request:

PEAR: emulated destructors

<?php
require_once "PEAR.php";

class FileContainer extends PEAR
{
    var $file = '';
    var $contents = '';
    var $modified = 0;

    function FileContainer($file)
    {
        $this->PEAR(); // this calls the parent class constructor
        $fp = fopen($file, "r");
        if (!is_resource($fp)) {
            return;
        }
    $this->file = $file;
        while ($data = fread($fp, 2048)) {
            $this->contents .= $data;
        }
        fclose($fp);
    }

    function append($str)
    {
        $this->contents .= $str;
        $this->modified++;
    }

    // The "destructor" is named like the constructor
    // but with an underscore in front.
    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");

// When the request is done and PHP shuts down, $fileobj's
// "destructor" is called and updates the file on disk.
?>

Note: PEAR "destructors" use PHP's shutdown callbacks (register_shutdown_function()), and in PHP < 4.1, you can't output anything from these when PHP is running in a web server. So anything printed in a "destructor" gets lost except when PHP is used in command-line mode. In PHP 4.1 and higher, output can be also generated in the destructor. Also, see the warning about how to instantiate objects if you want to use the destructor.

The next examples illustrate different ways of using PEAR's error handling mechanism.

PEAR error example (1)

<?php
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()."\n";
}
?>

This example shows a wrapper to fsockopen() that delivers the error code and message (if any) returned by fsockopen in a PEAR error object. Notice that PEAR::isError() is used to detect whether a value is a PEAR error.

PEAR_Error's mode of operation in this example is simply returning the error object and leaving the rest to the user (programmer). This is the default error mode.

In the next example we're showing how to use default error modes:

PEAR error example (2)

<?php
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\n";
?>

Here, we set the default error mode to PEAR_ERROR_DIE, and since we don't specify any error mode in the raiseError call (that'd be the third parameter), raiseError uses the default error mode and exits if fsockopen fails.

Global Variables Used

The PEAR class uses some global variables to register global defaults, and an object list used by the "destructors". All of the global variables associated with the PEAR class have a _PEAR_ name prefix.

$_PEAR_default_error_mode

If no default error mode is set in an object, this mode will be used. Must be one of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT, PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE or PEAR_ERROR_CALLBACK.

Don't set this variable directly, call PEAR::setErrorHandling() as a static method like this:

<?php
PEAR::setErrorHandling(PEAR_ERROR_DIE);
?>
$_PEAR_default_error_options

If the error mode is PEAR_ERROR_TRIGGER, this is the error level (one of E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).

Don't set this variable directly, call PEAR::setErrorHandling() as a static method like this:

<?php
PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR);
?>
$_PEAR_default_error_callback

If no options parameter is used when an error is raised and the error mode is PEAR_ERROR_CALLBACK, the value of this variable is used as the callback. This means that you can switch the error mode temporarily and return to callback mode without specifying the callback function again. A string value represents a function, a two-element array with an object at index 0 and a string at index 1 represents a method.

Again, don't set this variable directly, call PEAR::setErrorHandling() as a static method like this:

<?php
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler");
?>

Here is an example of how you can switch back and forth without specifying the callback function again:

<?php
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_function_handler");
do_some_stuff();
PEAR::setErrorHandling(PEAR_ERROR_DIE);
do_some_critical_stuff();
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK);
// now we're back to using my_function_handler again
?>
Prev | PEAR base and error handling class | Next
PEAR base and error handling class | PEAR Manual | Constants


Constants

Constants

Constants – Predefined Constants

PEAR_ERROR_CALLBACK

PEAR error handling related.

See PEAR_Error, setErrorHandling()

PEAR_ERROR_DIE

PEAR error handling related.

See PEAR_Error, setErrorHandling()

PEAR_ERROR_PRINT

PEAR error handling related.

See PEAR_Error, setErrorHandling()

PEAR_ERROR_RETURN

PEAR error handling related.

See PEAR_Error, setErrorHandling()

PEAR_ERROR_TRIGGER

PEAR error handling related.

See PEAR_Error, setErrorHandling()

Prev | PEAR base and error handling class | Next
Introduction | PEAR Manual | PEAR::PEAR()


PEAR::PEAR()

PEAR::PEAR()

PEAR::PEAR() – constructor (package developer related)

Synopsis

require_once 'PEAR.php';

void PEAR::PEAR ( string $errorClass = PEAR_Error )

Description

If you want to use the deconstructor functionality provide by PEAR, you have to call $this->PEAR() in the constructor of your class.

Parameter

  • string $errorClass - the name of the error class to use.

Note

This function can be called statically.

Prev | PEAR base and error handling class | Next
Constants | PEAR Manual | PEAR::_PEAR()


PEAR::_PEAR()

PEAR::_PEAR()

PEAR::_PEAR() – Deconstructor (package developer related)

Synopsis

require_once 'PEAR.php';

void PEAR::_PEAR ( )

Description

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

Prev | PEAR base and error handling class | Next
PEAR::PEAR() | PEAR Manual | PEAR::getStaticProperty()


PEAR::getStaticProperty()

PEAR::getStaticProperty()

PEAR::getStaticProperty() – handle static properties (package developer related)

Synopsis

require_once 'PEAR.php';

mixed &PEAR::getStaticProperty ( string $class , string $var )

Description

If you have a class that's mostly/entirely static, and you need static properties, you can use this method to simulate them. Eg. in your method(s) do this:

<?php
$myVar = &PEAR::getStaticProperty('myVar');
?>

You must use a reference, or they will not persist!

Parameter

  • string $class - the name of your class, where you call getStaticProperty()

  • string $var the variable to retrieve.

Return value

mixed - A reference to the variable. If not set, it will be auto initialised to NULL.

Example

Using getStaticProperty()

<?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();
?>

This would print

value = foo
Prev | PEAR base and error handling class | Next
PEAR::_PEAR() | PEAR Manual | PEAR::registerShutdownFunc()


PEAR::registerShutdownFunc()

PEAR::registerShutdownFunc()

PEAR::registerShutdownFunc() – set a shutdown function for static classes (package developer related)

Synopsis

require_once 'PEAR.php';

void PEAR::registerShutdownFunc ( array $func , array $var = array() )

Description

The indicated function is called, before the PHP interpreter will be finished.

Parameter

  • array $func - the name of the class and of the function to ccore.

  • array $var - possible required function parameters. The parameters are handed over to the function in accordance with their succession of the array.

Example

Using registerShutdownFunc()

<?php

require_once 'PEAR.php';

class myClass {

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

function shutdown( $param1, $param2)
{
 // do something before we will die
}

}

?>
Prev | PEAR base and error handling class | Next
PEAR::getStaticProperty() | PEAR Manual | PEAR::isError()


PEAR::isError()

PEAR::isError()

PEAR::isError() – checks for a PEAR_Error object

Synopsis

require_once 'PEAR.php';

boolean PEAR::isError ( mixed $data , mixed $msgcode )

Description

isError() examines whether a variable is a PEAR_Error object and - optional - contains a specific error message or code.

Parameter

mixed $data

variable to check

mixed $msgcode

additional error message or error code to check

Return value

mixed - returns TRUE, if the variable was a PEAR_Error and, if given, contains $msgcode

Prev | PEAR base and error handling class | Next
PEAR::registerShutdownFunc() | PEAR Manual | PEAR::raiseError()


PEAR::raiseError()

PEAR::raiseError()

PEAR::raiseError() – Create a new PEAR_Error object and optionally specify error-handling instructions

Synopsis

require_once 'PEAR.php';

PEAR_Error PEAR::raiseError ( mixed $message , int $code , int $mode , int|array $options , mixed $userinfo , string $error_class , boolean $skipmsg )

Description

raiseError()

Parameter

string $message

Error message string or PEAR_Error object. The default message is unknown error if left blank.

integer $code

Error code. It is recommended to use an error code for even the simplest errors, in order to simplify error handling and processing.

integer $mode

Error mode. This is one of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT, PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE, PEAR_ERROR_CALLBACK, or PEAR_ERROR_EXCEPTION. See setErrorHandling() for detailed information and examples of the meaning of these constants.

mixed $options

Error options. This depends on the value of $mode , and is documented in setErrorHandling().

mixed $userinfo

Optional user information. This can be used to store any error-specific information, and has an unspecified format.

string $error_class

Error class name to use as the error object. The default error class is PEAR_Error. Use this parameter to specify another class to use, such as a custom class extending PEAR_Error

boolean $skipmsg

Use this parameter if you are using a custom class that does not accept an error message in its constructor. Never use this parameter without the $error_class parameter - it will not work.

Return value

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

Prev | PEAR base and error handling class | Next
PEAR::isError() | PEAR Manual | PEAR::setErrorHandling()


PEAR::setErrorHandling()

PEAR::setErrorHandling()

PEAR::setErrorHandling() – sets handling of errors generated through PEAR packages

Synopsis

require_once 'PEAR.php';

void PEAR::setErrorHandling ( integer $mode = null , mixed $options = null )

Description

setErrorHandling() can be invoked as both a standard object method ($obj->setErrorHandling) and as a static method (PEAR::setErrorHandling). If called statically, PEAR::setErrorHandling() sets the default error handling behaviour for all PEAR objects (global error handling behaviour). If called as an object method, $obj->setErrorHandling() sets the default error handling for only that object (local error handling behaviour).

Parameter

  • integer $mode - one of the following constants

    • PEAR_ERROR_RETURN If an error occurs, a PEAR_Error is returned from the error-generation method (normally raiseError().)

    • PEAR_ERROR_PRINT Like PEAR_ERROR_RETURN, but an error message will be printed additionally.

    • PEAR_ERROR_TRIGGER Like PEAR_ERROR_RETURN, but the PHP builtin-function trigger_error() will be called in PEAR_Error's constructor with the error message.

    • PEAR_ERROR_DIE The script will terminate and an error message will be printed on instantiation of a PEAR_Error.

    • PEAR_ERROR_CALLBACK If a error occurs, the callback passed to $options is called.

    • PEAR_ERROR_EXCEPTION If Zend Engine 2 is present, then an exception will be thrown using the PEAR_Error object.

  • mixed $options - the value for $options depends on $mode

    • PEAR_ERROR_PRINT and PEAR_ERROR_DIE support an optional printf() format string used when printing the error message. This format string should contain a single %s, which will be used to insert the error message into the string. Use the string to enclose the error message with other useful information not included in the error message prefix or error message.

    • PEAR_ERROR_TRIGGER requires an user error level constant used by trigger_error() (possible constants: E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR). Note that if the error constant is not one of these valid error constants, a PHP warning will be triggered.

    • PEAR_ERROR_CALLBACK The callback must be a function name in the format described in the Pseudo-Type section of the PHP manual (either a string, or an array). The callback must accept a single parameter, the PEAR_Error object generated by an error condition. Note that if the callback is not a valid callback, a PHP warning will be triggered.

Here's an example of a few ways to use setErrorHandling:

<?php
require_once 'PEAR.php';
// dummy error constant for this example
define('MYCLASS_ERROR_CODE', 1);

// demonstration of default global error handling
// in this case, all PEAR Errors will trigger a PHP warning
PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_WARNING);
// Note that the file and line number will be in the constructor of PEAR_Error
// in PEAR.php
PEAR::raiseError('test warning', MYCLASS_ERROR_CODE);

// this error specifies a mode, and overrides the default global error handling
$e = PEAR::raiseError('return only', MYCLASS_ERROR_CODE, PEAR_ERROR_RETURN);

PEAR::setErrorHandling(PEAR_ERROR_PRINT, "Gronk error: %s<br />\n");

// prints "Gronk error: test warning<br />\n"
PEAR::raiseError('test warning', MYCLASS_ERROR_CODE);

/**
 * Fake class to demonstrate error handling
 * @package myClass
 */
class myClass extends PEAR {
    /**
     * Demonstration of default local error handling
     */
    function myClass()
    {
        // object method callback
        $this->setErrorHandling(PEAR_ERROR_CALLBACK, array(&$this, 'handleErr'));
        // prints "custom handler...is working"
        PEAR::raiseError('custom handler', MYCLASS_ERROR_CODE);
        // static class method callback
        $this->setErrorHandling(PEAR_ERROR_CALLBACK,
            array('myClass', 'handleErrStatic'));
        PEAR::raiseError('custom handler', MYCLASS_ERROR_CODE);
        // function callback
        $this->setErrorHandling(PEAR_ERROR_CALLBACK, 'standardCallback');
        PEAR::raiseError('custom handler', MYCLASS_ERROR_CODE);
    }

    /**
     * Callback set by the constructor
     * @param PEAR_Error The error object
     */
    function handleErr($error)
    {
        $this->lastError = $error->getMessage();
        print $error->getMessage() . "...is working\n";
    }

    /**
     * Static callback set by the constructor
     *
     * Note that in PHP 5, $this is not set if the method is declared with
     * the "static" access modifier.  In PHP 4, $this is set, but is not
     * set to the myClass object, so don't use it!
     * @param PEAR_Error The error object
     * @static
     */
    function handleErrStatic($error)
    {
        print 'static ' . $error->getMessage() . "...is working\n";
    }
}

/**
 * @param PEAR_Error The error object
 */
function standardCallback($error)
{
    print 'normal function callback: ' . $error->getMessage();
}
// This causes the printing of three messages through error callbacks:
// "custom handler...is working"
// "static custom handler... is working"
// "normal function callback: custom handler"
$mine = new myClass;

PEAR::setErrorHandling(PEAR_ERROR_DIE);
// terminates the script with the error message "oops"
PEAR::raiseError('oops', MYCLASS_ERROR_CODE);
?>
Prev | PEAR base and error handling class | Next
PEAR::raiseError() | PEAR Manual | PEAR::expectError()


PEAR::expectError()

PEAR::expectError()

PEAR::expectError() – add an error code for non-disabling temporary error handling

Synopsis

require_once 'PEAR.php';

integer PEAR::expectError ( mixed $errorCode = '*' )

Description

This method is used to tell which errors you expect to get. Expected errors are always returned with error mode PEAR_ERROR_RETURN. Expected error codes are stored in a stack, and this method pushes a new element onto it. The list of expected errors are in effect until they are popped off the stack with the popExpect() method.

Parameter

  • mixed $errorCode - the expected PEAR_Error error code or an array of error codes. If set to '*' every error is expected.

Return value

integer - the size of the error code stack.

Note

This function can not be called statically.

See

popExpect()

Prev | PEAR base and error handling class | Next
PEAR::setErrorHandling() | PEAR Manual | PEAR::popExpect()


PEAR::popExpect()

PEAR::popExpect()

PEAR::popExpect() – removes the last error code for non-disabling temporary error handling

Synopsis

require_once 'PEAR.php';

mixed PEAR::popExpect ( )

Description

This method pops one element off the expected error codes stack.

Return value

mixed - the removed error code or array of error codes

Note

This function can not be called statically.

See

expectError()

Prev | PEAR base and error handling class | Next
PEAR::expectError() | PEAR Manual | PEAR::loadExtension()


PEAR::loadExtension()

PEAR::loadExtension()

PEAR::loadExtension() – OS independent PHP extension load

Synopsis

require_once 'PEAR.php';

boolean PEAR::loadExtension ( string $ext )

Description

Loads an extension by name

Parameter

string $ext

The case-sensitive name of the PHP extension without filename suffix or php_ prefix.

Return value

boolean - returns TRUE, if extension could be loaded

Note

This function can be called statically.

Example

Loading the domxml-extension

<?php
if(!PEAR::loadExtension("domxml")) {
 echo 'Could not load DomXML-Extension!';
 exit();
}
?>
Prev | PEAR base and error handling class | Next
PEAR::popExpect() | PEAR Manual | PEAR_Exception


PEAR_Exception

PEAR_Exception - PHP 5 and versions above

Table of Contents
  • Using PEAR_Exception for advanced error handling in PHP 5+ -- Using PEAR_Exception

PEAR_Exception is the recommended error handling solution for PHP 5-based packages in PEAR. PEAR_Exception is a lightweight wrapper above the built-in Exception class in PHP 5 that provides the ability to specify causes for errors, register observers, and many more features.

Exceptions in general should be used only for exceptional circumstances - for error conditions that require termination of execution. PEAR_Exception should mainly be used for transmitting error information outside the existing package, and not for normal flow control. Use Control Structures in favor of exceptions wherever possible.

Prev | PEAR base classes | Next
PEAR::loadExtension() | PEAR Manual | Using PEAR_Exception for advanced error handling in PHP 5+


Using PEAR_Exception for advanced error handling in PHP 5+

Using PEAR_Exception for advanced error handling in PHP 5+

Using PEAR_Exception for advanced error handling in PHP 5+ – Using PEAR_Exception

Synopsis

Introduction to the usage of PEAR_Exception

Introduction

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

  • Nestable exceptions (

    <?php throw new PEAR_Exception($msg, $prev_exception); ?>

    )

  • Subject/Observer pattern, triggered when an exception is instantiated

  • Clear, detailed and attractively formatted error messages

  • Extra context information available compared to built-in Exception. For instance, a cause of the exception (PEAR_Error/PEAR_ErrorStack/another Exception).

  • Exception cause can be a PEAR_Error object, PEAR_Exception object or an array of mixed PEAR_Exceptions/PEAR_ErrorStack warnings

  • callbacks for specific exception classes and their children

Usage example:

<?php
require_once 'PEAR/Exception.php';

class Test {
    function foo() {
        throw new PEAR_Exception('Error Message', ERROR_CODE);
    }
}

function myLogger($pear_exception) {
    echo $pear_exception->getMessage();
}
// each time a exception is thrown the 'myLogger' will be called
// (its use is completely optional)
PEAR_Exception::addObserver('myLogger');
$test = new Test;
try {
    $test->foo();
} catch (PEAR_Exception $e) {
    print $e;
}
?>

API documentation is documented in the documentation for the PEAR package generated by phpDocumentor. The class is very simple, examine the source in the PEAR package to get a better idea of how it works.

Prev | PEAR_Exception | Next
PEAR_Exception | PEAR Manual | PEAR_ErrorStack


PEAR_ErrorStack

PEAR_ErrorStack

Table of Contents
  • Introduction to using PEAR_ErrorStack for advanced error handling -- Using PEAR_ErrorStack to do both simple and advanced error handling
  • constructor PEAR_ErrorStack::PEAR_ErrorStack -- Set up a new error stack instance
  • PEAR_ErrorStack::getErrorMessage -- Standard error message generation callback
  • PEAR_ErrorStack::getErrorMessageTemplate -- Standard Error Message Template generator from error code
  • PEAR_ErrorStack::getErrors -- Retrieve all errors since last purge
  • PEAR_ErrorStack::getFileLine -- Standard file/line number/function/class context callback
  • PEAR_ErrorStack::getMessageCallback -- Get an error code => error message mapping callback
  • PEAR_ErrorStack::hasErrors -- Determine whether there are any errors on the stack
  • PEAR_ErrorStack::pop -- Pop an error off of the error stack
  • PEAR_ErrorStack::popCallback -- Remove a callback from the error callback stack
  • PEAR_ErrorStack::push -- Add an error to the stack
  • PEAR_ErrorStack::pushCallback -- Set an error Callback If set to a valid callback, this will be called every time an error is pushed onto the stack. The return value will be used to determine whether to allow an error to be pushed or logged.
  • PEAR_ErrorStack::raiseError -- emulate PEAR::raiseError
  • PEAR_ErrorStack::setContextCallback -- Set a callback that generates context information (location of error) for an error stack
  • PEAR_ErrorStack::setDefaultCallback -- Sets a default callback to be used by all error stacks
  • PEAR_ErrorStack::setDefaultLogger -- Set up a PEAR::Log object for all error stacks that don't have one
  • PEAR_ErrorStack::setErrorMessageTemplate -- Set the Error Message Template array
  • PEAR_ErrorStack::setLogger -- Set up a PEAR::Log object for this error stack
  • PEAR_ErrorStack::setMessageCallback -- Set an error code => error message mapping callback
  • PEAR_ErrorStack::singleton -- Return a single error stack for this package.
  • PEAR_ErrorStack::staticGetErrors -- Get a list of all errors since last purge, organized by package
  • PEAR_ErrorStack::staticHasErrors -- Determine whether there are any errors on any error stack
  • PEAR_ErrorStack::staticPop -- Static version of pop
  • PEAR_ErrorStack::staticPopCallback -- Remove a callback from every error callback stack
  • PEAR_ErrorStack::staticPush -- Static version of push
  • PEAR_ErrorStack::staticPushCallback -- Set an error Callback for every package's error stack
  • PEAR_ErrorStack::_log -- Log an error using PEAR::Log
  • Package PEAR_ErrorStack Constants -- Constants defined in and used by PEAR_ErrorStack

PEAR_ErrorStack is an experimental error raising and handling implementation for PEAR that is designed to replace PEAR_Error when it has stabilized. PEAR_ErrorStack is both backwards compatible with PEAR_Error and forward compatible with PHP 5's PEAR_Exception class. There are many other features, all described in the Introduction.

Usage:

1      // global error stack
2      $global_stack = &PEAR_ErrorStack::
singleton
('MyPackage');
3      // local error stack
4      $local_stack = new
PEAR_ErrorStack
('MyPackage');
Prev | PEAR base classes | Next
Using PEAR_Exception for advanced error handling in PHP 5+ | PEAR Manual | Introduction to using PEAR_ErrorStack for advanced error handling


Introduction to using PEAR_ErrorStack for advanced error handling

Introduction to using PEAR_ErrorStack for advanced error handling

Introduction to using PEAR_ErrorStack for advanced error handling – Using PEAR_ErrorStack to do both simple and advanced error handling

Synopsis

Introduction to the usage of PEAR_ErrorStack

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

Error Context Display

In some cases, you may want to customize error generation. For instance, for many exceptions, it is useful to include file, line number, and class/function context information in order to trace an error. A default option is available which will be sufficient for most cases, and that is PEAR_ErrorStack::getFileLine().

Not all package errors occur in the PHP source file. For instance, compiling template engines errors can occur in the template source files. Database errors can occur in the text of a query, or internal to the database server. Internet package errors can occur on another server. All of this information can be included in an error message using a context grabbing callback.

<?php
require_once 'PEAR/ErrorStack.php';
class DatabaseClass
{
    var $_dbError;
    var $_dbErrorMsg;
    var $_dbQuery;
    var $_dbPos;
    /**
     * Context grabber for the Database package
     * @param integer Error Code
     * @param array   Error parameters passed into {@link PEAR_ErrorStack::push()}
     * @param array   Output of debug_backtrace() (not used in this callback)
     */
    function getErrorContext($code, $params, $backtrace)
    {
        $context = array(
            'errorcode' => $this->_dbError,
            'errormsg' => $this->_dbErrorMsg,
            'query' => $this->_dbQuery,
            'pos' => $this->_dbPos,
        );
        return $context;
    }
}
$db = new DatabaseClass;
PEAR_ErrorStack::staticSetContextCallback('Database', array(&$db, 'getErrorContext'));
?>

The context information is formatted to be easily processed by an external application. If you wish context information to be in the error message, the error message callback should be used to add the information in a human-readable format to the error message, as described in the next section.

Custom Error Message Generation

There are three methods of PEAR_ErrorStack designed for use with generating error messages efficiently. To use them, you must do one of three things:

  • Call PEAR_ErrorStack::setErrorMessageTemplate(), and set an array mapping error codes to error message templates, like so:

    <?php
    define    ('ERROR_ONE', 1);
    define('ERROR_TWO', 2);
    define('ERROR_THREE', 3);
    define('ERROR_FOUR', 4);
    require_once     'PEAR/ErrorStack.php';
    $stack = &PEAR_ErrorStack::singleton('mypackage');
    $messages = array(
            ERROR_ONE => 'The gronk number %num% dropped a %thing%',
            ERROR_TWO => 'The %list% items were missing',
            ERROR_THREE => 'I like chocolate, how about %you%?',
            ERROR_FOUR => 'and a %partridge% in a pear %tree%',
    );
    $stack->setErrorMessageTemplate($messages);
    ?>

    Substitution is done using str_replace, and is very simple. Basically, if a variable name is enclosed in percent signs (%), it will be replaced with the value passed in the associative array. If an array

    <?php
    array('varname' => 'value');
    ?>

    is passed to either method, all occurrences of %varname% will be replaced by value.

    In addition, if values are objects, the methods will search for a method named "__toString()" and if found, will use that to convert the object to a string. If an array of strings is passed in, they will be joined by commas.

    <?php
    array('varname' => array('first', 'second', 'third'));
    // this will become 'first, second, third'
    ?>

  • Call PEAR_ErrorStack::setMessageCallback(), and set a custom error message generating function or method. This is probably the best option for the majority of complex situations, as it allows users to override or even extend the existing error message callback using PEAR_ErrorStack::getMessageCallback(). For example:

    <?php
    require_once 'PEAR/ErrorStack.php';
    class     foo
    {
        var     $_oldcallback;
        function     callback(&$stack, $err)
        {
                $message = call_user_func_array($this->_oldcallback, array(&$stack, $err));
                $message .= "File " . $err['context']['file'];
            return     $message;
        }
    }
    $a = new foo;
    $stack = &PEAR_ErrorStack::singleton('otherpackage');
    $a->_oldcallback = $stack->getMessageCallback('otherpackage');
    $stack->setMessageCallback(array(&$a, 'callback'));
    ?>

  • Extend PEAR_ErrorStack with your own class, and override PEAR_ErrorStack::getErrorMessageTemplate() or PEAR_ErrorStack::getErrorMessage(). To guarantee that this class will be used by other packages/applications, use this code right after the class declaration:

    <?php
    PEAR_ErrorStack    ::singleton('mypackage', false, null, 'MyPEAR_ErrorStack');
    ?>

Controlling error generation

There are many scenarios in which fine-grained control over error raising is absolutely necessary. A generic error handling callback means that every single error raised will be handled in the same error callback. Although PEAR_ErrorStack is designed to operate with independent callbacks for each package, generic error handling is possible through the PEAR_ErrorStack::staticPushCallback() method. This is no different from PEAR_Error's PEAR_ERROR_CALLBACK error handling mode.

PEAR_ErrorStack's real strength comes from the callback itself. PEAR_Error's callback has no actual effect on the error message - all error handling must happen in the callback method or function itself. PEAR_ErrorStack's callback can influence the error through the use of three constants:

  • PEAR_ERRORSTACK_IGNORE

  • PEAR_ERRORSTACK_PUSH

  • PEAR_ERRORSTACK_LOG

PEAR_ERRORSTACK_IGNORE informs the stack to ignore the error, as if it never occurred. The error will be neither logged, nor pushed on the stack. It will, however, be returned from PEAR_ErrorStack::push()

PEAR_ERRORSTACK_PUSH informs the stack to push the error onto the error stack, but not to log the error.

PEAR_ERRORSTACK_LOG informs the stack not to push the error onto the error stack, but only to log the error.

<?php
define('ERROR_CODE_ONE',1);
define('ERROR_CODE_TWO',2);
define('ERROR_CODE_THREE',3);
require_once 'PEAR/ErrorStack.php';
require_once 'Log.php';
function somecallback($err)
{
    switch($err['code']){
        case ERROR_CODE_ONE:
                return PEAR_ERRORSTACK_IGNORE;
                break;
        case ERROR_CODE_TWO:
                return PEAR_ERRORSTACK_PUSH;
                break;
        case ERROR_CODE_THREE:
                return PEAR_ERRORSTACK_LOG;
                break;
    } // switch
}
$log = &Log::factory('display');
$stack = &PEAR_ErrorStack::singleton('mypackage');
$stack->setLogger($log);
$stack->pushCallback('somecallback');
$stack->push(ERROR_CODE_ONE);
$stack->push(ERROR_CODE_TWO);
$stack->push(ERROR_CODE_THREE);
var_dump(PEAR_ErrorStack::staticGetErrors());

// simulate PEAR_ERROR_CALLBACK, with specific callback for mypackage
// every other package will only log errors, only mypackage's errors
// are pushed on the stack, conditionally
class myclass {
    function acallback($err)
    {
        return PEAR_ERRORSTACK_LOG;
    }
}
$stack2 = PEAR_ErrorStack::singleton('anotherpackage');
$stack3 = &PEAR_ErrorStack::singleton('thirdpackage');
PEAR_ErrorStack::setDefaultCallback(array('myclass', 'acallback'));
?>

Repackaging errors from one package to another

The most obvious usage for an error callback involves a common scenario in many user-level applications that use system-level packages. If you write a Content Management System (CMS) with the PEAR DB package, it is usually a bad idea to display database-level errors when a user clicks on a link to add a message to a forum. PEAR_ErrorStack can be used to repackage this error as a MyPackage error.

<?php
define('MYPACKAGE_ERROR_DBDOWN',1);
require_once 'PEAR/ErrorStack.php';
function repackage($err)
{
    if ($err['package'] == 'DB') {
        $mystack = &PEAR_ErrorStack::singleton('mypackage');
        $mystack->push(MYPACKAGE_ERROR_DBDOWN, 'error', array('olderror' => $err));
        // ignore the DB error, but save it in the mypackage error, for logging
        return PEAR_ERRORSTACK_IGNORE;
    }
}
?>

Emulating the @ operator

One of the difficult-to-use strengths of PEAR_Error involves the PEAR::expectError() method. With regular PHP errors, it is possible to silence them using the @ operator like so:

<?php
@file_get_contents();
?>

Emulating this behavior with PEAR_ErrorStack is simple.

<?php
define('ERROR_CODE_SOMETHING', 1);
require_once 'PEAR/ErrorStack.php';
function silence($err)
{
    // ignore all errors
    return PEAR_ERRORSTACK_IGNORE;
}
$stack = &PEAR_ErrorStack::singleton('mypackage');
$stack->pushCallback('silence');
$stack->push(ERROR_CODE_SOMETHING);
?>

PEAR_ErrorStack can take this one step further, and only log errors or only put errors on the error stack, using the other two constants. Finally, particular errors can be singled out, and all others ignored.

<?php
define('SOMEPACKAGE_ERROR_THING', 1);
require_once 'PEAR/ErrorStack.php';
function silenceSome($err)
{
    if ($err['package'] != 'somepackage') {
        // ignore all errors from other packages
        return PEAR_ERROR_IGNORE;
    }
    if ($err['code'] != SOMEPACKAGE_ERROR_THING) {
        // ignore all other error codes
        return PEAR_ERRORSTACK_IGNORE;
    }
}
$stack = &PEAR_ErrorStack::singleton('mypackage');
$stack->pushCallback('silenceSome');
$stack->push(ERROR_CODE_SOMETHING);
?>

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());
?>
Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack | PEAR Manual | constructor PEAR_ErrorStack::PEAR_ErrorStack


constructor PEAR_ErrorStack::PEAR_ErrorStack

constructor PEAR_ErrorStack::PEAR_ErrorStack

constructor PEAR_ErrorStack::PEAR_ErrorStack() – Set up a new error stack instance

Synopsis

require_once 'PEAR/ErrorStack.php';

void constructor PEAR_ErrorStack::PEAR_ErrorStack ( string $package , callback $msgCallback = false , callback $contextCallback = false , boolean $throwPEAR_Error = false )

Backwards Compatibility Warning

As of PEAR 1.3.2, PEAR_ErrorStack no longer instantiates and returns an Exception object in PHP5, and the last parameter has been removed. Code that relies upon this behavior will break.

Description

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

Parameter

string $package

name of the package this error stack represents

callback $msgCallback

callback used for error message generation

callback $contextCallback

callback used for context generation, defaults to getFileLine()

boolean $throwPEAR_Error

string $exceptionClass

exception class to instantiate if in PHP 5

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
Introduction to using PEAR_ErrorStack for advanced error handling | PEAR Manual | PEAR_ErrorStack::getErrorMessage


PEAR_ErrorStack::getErrorMessage

PEAR_ErrorStack::getErrorMessage

PEAR_ErrorStack::getErrorMessage() – Standard error message generation callback

Synopsis

require_once 'PEAR/ErrorStack.php';

string PEAR_ErrorStack::getErrorMessage ( PEAR_ErrorStack &$stack , array $err , string|false $template = false )

Description

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"

Parameter

PEAR_ErrorStack &$stack

array $err

string|false $template

Pre-generated error message template

Throws

throws no exceptions thrown

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
constructor PEAR_ErrorStack::PEAR_ErrorStack | PEAR Manual | PEAR_ErrorStack::getErrorMessageTemplate


PEAR_ErrorStack::getErrorMessageTemplate

PEAR_ErrorStack::getErrorMessageTemplate

PEAR_ErrorStack::getErrorMessageTemplate() – Standard Error Message Template generator from error code

Synopsis

require_once 'PEAR/ErrorStack.php';

string PEAR_ErrorStack::getErrorMessageTemplate ( mixed $code )

Description

Standard Error Message Template generator from error code

Parameter

mixed $code

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::getErrorMessage | PEAR Manual | PEAR_ErrorStack::getErrors


PEAR_ErrorStack::getErrors

PEAR_ErrorStack::getErrors

PEAR_ErrorStack::getErrors() – Retrieve all errors since last purge

Synopsis

require_once 'PEAR/ErrorStack.php';

array PEAR_ErrorStack::getErrors ( boolean $purge = false , string|false $level = false )

Description

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.

Parameter

boolean $purge

set in order to empty the error stack

string $level

Level name to check for a particular severity. Use this to determine whether only a particular class of errors has occurred, such as whether any warnings have occurred (errors will be ignored)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::getErrorMessageTemplate | PEAR Manual | PEAR_ErrorStack::getFileLine


PEAR_ErrorStack::getFileLine

PEAR_ErrorStack::getFileLine

PEAR_ErrorStack::getFileLine() – Standard file/line number/function/class context callback

Synopsis

require_once 'PEAR/ErrorStack.php';

array|false PEAR_ErrorStack::getFileLine ( array $code , unused $params , integer $backtrace = null )

Description

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.

Parameter

array $code

Results of debug_backtrace()

unused $params

integer $backtrace

backtrace frame.

Return value

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

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::getErrors | PEAR Manual | PEAR_ErrorStack::getMessageCallback


PEAR_ErrorStack::getMessageCallback

PEAR_ErrorStack::getMessageCallback

PEAR_ErrorStack::getMessageCallback() – Get an error code => error message mapping callback

Synopsis

require_once 'PEAR/ErrorStack.php';

array|string|false PEAR_ErrorStack::getMessageCallback ( )

Description

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

Return value

returns Callback function/method or false if none

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::getFileLine | PEAR Manual | PEAR_ErrorStack::hasErrors


PEAR_ErrorStack::hasErrors

PEAR_ErrorStack::hasErrors

PEAR_ErrorStack::hasErrors() – Determine whether there are any errors on the stack

Synopsis

require_once 'PEAR/ErrorStack.php';

boolean PEAR_ErrorStack::hasErrors ( string $level = false )

Description

Determine whether there are any errors on the stack

Parameter

string $level

Level name to check for a particular severity. Use this to determine whether only a particular class of errors has occurred, such as whether any warnings have occurred (errors will be ignored)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::getMessageCallback | PEAR Manual | PEAR_ErrorStack::pop


PEAR_ErrorStack::pop

PEAR_ErrorStack::pop

PEAR_ErrorStack::pop() – Pop an error off of the error stack

Synopsis

require_once 'PEAR/ErrorStack.php';

false|array PEAR_ErrorStack::pop ( )

Description

Pop an error off of the error stack

Throws

throws no exceptions thrown

Note

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

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::hasErrors | PEAR Manual | PEAR_ErrorStack::popCallback


PEAR_ErrorStack::popCallback

PEAR_ErrorStack::popCallback

PEAR_ErrorStack::popCallback() – Remove a callback from the error callback stack

Synopsis

require_once 'PEAR/ErrorStack.php';

array|string|false PEAR_ErrorStack::popCallback ( )

Description

Remove a callback from the error callback stack

Throws

throws no exceptions thrown

See

see PEAR_ErrorStack::pushCallback()

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::pop | PEAR Manual | PEAR_ErrorStack::push


PEAR_ErrorStack::push

PEAR_ErrorStack::push

PEAR_ErrorStack::push() – Add an error to the stack

Synopsis

require_once 'PEAR/ErrorStack.php';

PEAR_Error|array PEAR_ErrorStack::push ( integer $code , string $level = 'error' , array $params = array() , string $msg = false , array $repackage = false , array $backtrace = false )

Backwards Compatibility Warning

As of PEAR 1.3.2, PEAR_ErrorStack no longer instantiates and returns an Exception object in PHP5. Code that relies upon this behavior will break.

Description

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'

Next, if the error should contain context information, this is handled by the context grabbing method. Finally, the error is pushed onto the proper error stack

Parameter

integer $code

Package-specific error code

string $level

Error level. This is NOT spell-checked

array $params

associative array of error parameters

string $msg

Error message, or a portion of it if the message is to be generated

array $repackage

If this error re-packages an error pushed by another package, place the array returned from pop() in this parameter

array $backtrace

Protected parameter: use this to pass in the http://www.php.net/manual-lookup.php?pattern=debug_backtrace that should be used to find error context.

Return value

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.

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::popCallback | PEAR Manual | PEAR_ErrorStack::pushCallback


PEAR_ErrorStack::pushCallback

PEAR_ErrorStack::pushCallback

PEAR_ErrorStack::pushCallback() – Set an error Callback If set to a valid callback, this will be called every time an error is pushed onto the stack. The return value will be used to determine whether to allow an error to be pushed or logged.

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::pushCallback ( string|array $cb )

Description

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

Parameter

string|array $cb

Throws

throws no exceptions thrown

See

see PEAR_ErrorStack::popCallback()

see PEAR_ERRORSTACK_PUSHANDLOG, PEAR_ERRORSTACK_PUSH, PEAR_ERRORSTACK_LOG

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::push | PEAR Manual | PEAR_ErrorStack::raiseError


PEAR_ErrorStack::raiseError

PEAR_ErrorStack::raiseError

PEAR_ErrorStack::raiseError() – emulate PEAR::raiseError()

Synopsis

require_once 'PEAR/ErrorStack.php';

PEAR_Error PEAR_ErrorStack::raiseError ( )

Description

See PEAR::raiseError()

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::pushCallback | PEAR Manual | PEAR_ErrorStack::setContextCallback


PEAR_ErrorStack::setContextCallback

PEAR_ErrorStack::setContextCallback

PEAR_ErrorStack::setContextCallback() – Set a callback that generates context information (location of error) for an error stack

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::setContextCallback ( array|string|null $contextCallback )

Description

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()

Parameter

mixed $contextCallback

A valid callback as defined by is_callable()

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::raiseError | PEAR Manual | PEAR_ErrorStack::setDefaultCallback


PEAR_ErrorStack::setDefaultCallback

PEAR_ErrorStack::setDefaultCallback

PEAR_ErrorStack::setDefaultCallback() – Sets a default callback to be used by all error stacks

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::setDefaultCallback ( array|string $callback = false )

Description

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

Parameter

array|string $callback

Callback function/method

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::setContextCallback | PEAR Manual | PEAR_ErrorStack::setDefaultLogger


PEAR_ErrorStack::setDefaultLogger

PEAR_ErrorStack::setDefaultLogger

PEAR_ErrorStack::setDefaultLogger() – Set up a PEAR::Log object for all error stacks that don't have one

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::setDefaultLogger ( Log &$log )

Description

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

Parameter

Log &$log

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::setDefaultCallback | PEAR Manual | PEAR_ErrorStack::setErrorMessageTemplate


PEAR_ErrorStack::setErrorMessageTemplate

PEAR_ErrorStack::setErrorMessageTemplate

PEAR_ErrorStack::setErrorMessageTemplate() – Set the Error Message Template array

Synopsis

require_once 'PEAR/ErrorStack.php';

string PEAR_ErrorStack::setErrorMessageTemplate ( mixed $template )

Description

The array format must be: array(error code => 'message template',...)

Error message parameters passed into push() will be used as input for the error message. If the template is 'message %foo% was %bar%', and the parameters are array('foo' => 'one', 'bar' => 'six'), the error message returned will be 'message one was six'

Parameter

mixed $template

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::setDefaultLogger | PEAR Manual | PEAR_ErrorStack::setLogger


PEAR_ErrorStack::setLogger

PEAR_ErrorStack::setLogger

PEAR_ErrorStack::setLogger() – Set up a PEAR::Log object for this error stack

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::setLogger ( Log &$log )

Description

Set a PEAR::Log object to use for a specific error stack instance

Parameter

Log &$log

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::setErrorMessageTemplate | PEAR Manual | PEAR_ErrorStack::setMessageCallback


PEAR_ErrorStack::setMessageCallback

PEAR_ErrorStack::setMessageCallback

PEAR_ErrorStack::setMessageCallback() – Set an error code => error message mapping callback

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::setMessageCallback ( mixed $msgCallback )

Description

This method sets the callback that can be used to generate error messages for any PEAR_ErrorStack instance

Parameter

mixed $msgCallback

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::setLogger | PEAR Manual | PEAR_ErrorStack::singleton


PEAR_ErrorStack::singleton

PEAR_ErrorStack::singleton

PEAR_ErrorStack::singleton() – Return a single error stack for this package.

Synopsis

require_once 'PEAR/ErrorStack.php';

PEAR_ErrorStack & PEAR_ErrorStack::singleton ( string $package , callback $msgCallback = false , callback $contextCallback = false , boolean $throwPEAR_Error = false , string $stackClass = 'PEAR_ErrorStack' )

Backwards Compatibility Warning

As of PEAR 1.3.2, PEAR_ErrorStack no longer instantiates and returns an Exception object in PHP5, and the second-to-last parameter has been removed. Code that relies upon this behavior will break.

Description

Note that all parameters are ignored if the stack for package $package has already been instantiated

Parameter

string $package

name of the package this error stack represents

callback $msgCallback

callback used for error message generation

callback $contextCallback

callback used for context generation, defaults to getFileLine()

boolean $throwPEAR_Error

If TRUE, then PEAR::raiseError() will be called and a PEAR_Error object will be returned from calls to PEAR_ErrorStack::push()

string $stackClass

class to instantiate

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::setMessageCallback | PEAR Manual | PEAR_ErrorStack::staticGetErrors


PEAR_ErrorStack::staticGetErrors

PEAR_ErrorStack::staticGetErrors

PEAR_ErrorStack::staticGetErrors() – Get a list of all errors since last purge, organized by package

Synopsis

require_once 'PEAR/ErrorStack.php';

array PEAR_ErrorStack::staticGetErrors ( boolean $purge = false , string|false $level = false , boolean $merge = false , array $sortfunc = array('PEAR_ErrorStack', '_sortErrors') )

Backwards Compatibility Warning

As of PEAR 1.3.2, the second parameter is a new parameter $level. Any code that relies on $merge being the second parameter will break.

Description

Static version of PEAR_ErrorStack::getErrors() , returns all errors from all singleton stacks.

Parameter

boolean $purge

Set to purge the error stack of existing errors

string $level

Level name to check for a particular severity. Use this to determine whether only a particular class of errors has occurred, such as whether any warnings have occurred (errors will be ignored)

boolean $merge

Set to return a flat array, not organized by package

array $sortfunc

Function used to sort a merged array - default sorts by time, and should be good for most cases

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::singleton | PEAR Manual | PEAR_ErrorStack::staticHasErrors


PEAR_ErrorStack::staticHasErrors

PEAR_ErrorStack::staticHasErrors

PEAR_ErrorStack::staticHasErrors() – Determine whether there are any errors on any error stack

Synopsis

require_once 'PEAR/ErrorStack.php';

boolean PEAR_ErrorStack::staticHasErrors ( string|false $package = false , string $level = false )

Description

Static version of PEAR_ErrorStack::hasErrors(). Returns TRUE if any singleton stack has any errors pending. Since PEAR 1.3.2, If $package is specified, it will call PEAR_ErrorStack::hasErrors for the singleton error stack of that package. If level is specified, hasErrors will ignore any errors not conforming to the error level specified. Use this to simulate error_reporting(E_NOTICE), for example

Parameter

string|FALSE $package

Package name to retrieve error information from, or false to retrieve error information from all singleton stacks

string $level

Level name to check for a particular severity. Use this to determine whether only a particular class of errors has occurred, such as whether any warnings have occurred (errors will be ignored)

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::staticGetErrors | PEAR Manual | PEAR_ErrorStack::staticPop


PEAR_ErrorStack::staticPop

PEAR_ErrorStack::staticPop

PEAR_ErrorStack::staticPop() – Static version of pop()

Synopsis

require_once 'PEAR/ErrorStack.php';

false|array PEAR_ErrorStack::staticPop ( string $package )

Description

Pop an error off of the error stack, static method

Parameter

string $package

Package name to retrieve error message from

Return value

returns if compatibility mode is on, a PEAR_Error is also thrown.

Note

since PEAR 1.5.0a1

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::staticHasErrors | PEAR Manual | PEAR_ErrorStack::staticPopCallback


PEAR_ErrorStack::staticPopCallback

PEAR_ErrorStack::staticPopCallback

PEAR_ErrorStack::staticPopCallback() – Remove a callback from every error callback stack

Synopsis

require_once 'PEAR/ErrorStack.php';

array|string|false PEAR_ErrorStack::staticPopCallback ( )

Description

Pop a callback from every Error Stack. No check is made to determine whether this is a good idea, so use with discretion.

Throws

No exceptions thrown.

See

see PEAR_ErrorStack::staticPushCallback()

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::staticPop | PEAR Manual | PEAR_ErrorStack::staticPush


PEAR_ErrorStack::staticPush

PEAR_ErrorStack::staticPush

PEAR_ErrorStack::staticPush() – Static version of push()

Synopsis

require_once 'PEAR/ErrorStack.php';

PEAR_Error|array PEAR_ErrorStack::staticPush ( string $package , integer $code , string $level = 'error' , array $params = array() , string $msg = false , array $repackage = false , array $backtrace = false )

Description

Parameter

string $package

Package name this error belongs to

integer $code

Package-specific error code

string $level

Error level. This is NOT spell-checked

array $params

associative array of error parameters

string $msg

Error message, or a portion of it if the message is to be generated

array $repackage

If this error re-packages an error pushed by another package, place the array returned from pop() in this parameter

array $backtrace

Protected parameter: use this to pass in the debug_backtrace that should be used to find error context

Return value

returns if compatibility mode is on, a PEAR_Error is also thrown.

Throws

No exceptions thrown.

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::staticPopCallback | PEAR Manual | PEAR_ErrorStack::staticPushCallback


PEAR_ErrorStack::staticPushCallback

PEAR_ErrorStack::staticPushCallback

PEAR_ErrorStack::staticPushCallback() – Set an error Callback for every package's error stack

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::staticPushCallback ( string|array $cb )

Description

Set an error callback for every package's singleton error stack.

Parameter

string|array $cb

Throws

No exceptions thrown.

See

see PEAR_ErrorStack::staticPopCallback() , PEAR_ErrorStack::pushCallback()

see PEAR_ERRORSTACK_PUSHANDLOG , PEAR_ERRORSTACK_PUSH , PEAR_ERRORSTACK_LOG

Note

This function should be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::staticPush | PEAR Manual | PEAR_ErrorStack::_log


PEAR_ErrorStack::_log

PEAR_ErrorStack::_log

PEAR_ErrorStack::_log() – Log an error using PEAR::Log

Synopsis

require_once 'PEAR/ErrorStack.php';

void PEAR_ErrorStack::_log ( array $err , array $levels = array( 'exception' => PEAR_LOG_CRIT, 'alert' => PEAR_LOG_ALERT, 'critical' => PEAR_LOG_CRIT, 'error' => PEAR_LOG_ERR, 'warning' => PEAR_LOG_WARNING, 'notice' => PEAR_LOG_NOTICE, 'info' => PEAR_LOG_INFO, 'debug' => PEAR_LOG_DEBUG) )

Description

This is a protected function, and should only be called by child classes that extend PEAR_ErrorStack

Parameter

array $err

Error array

array $levels

Error level => Log constant map

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::staticPushCallback | PEAR Manual | Package PEAR_ErrorStack Constants


Package PEAR_ErrorStack Constants

Package PEAR_ErrorStack Constants

Package PEAR_ErrorStack Constants – Constants defined in and used by PEAR_ErrorStack

All Constants

Constants defined in ErrorStack.php

Constants defined in ErrorStack.php
Name | Value | Line Number
PEAR_ERRORSTACK_ERR_NONCLASS | 1 | 110
PEAR_ERRORSTACK_ERR_OBJTOSTRING | 2 | 116
PEAR_ERRORSTACK_IGNORE | 4 | 103
PEAR_ERRORSTACK_LOG | 3 | 99
PEAR_ERRORSTACK_PUSH | 2 | 94
PEAR_ERRORSTACK_PUSHANDLOG | 1 | 89
Prev | PEAR_ErrorStack | Next
PEAR_ErrorStack::_log | PEAR Manual | PEAR Error object


PEAR Error object

PEAR_Error [deprecated]

Table of Contents
  • PEAR_Error::addUserInfo() -- add user information
  • PEAR_Error::getCallback() -- get callback function name
  • PEAR_Error::getCode() -- get error code
  • PEAR_Error::getMessage() -- get error message
  • PEAR_Error::getMode() -- get error mode
  • PEAR_Error::getDebugInfo() -- get debug information
  • PEAR_Error::getType() -- get error type
  • PEAR_Error::getUserInfo() -- get additional user-supplied information
  • PEAR_Error::PEAR_Error() -- constructor
  • PEAR_Error::toString() -- make string representation

PEAR_Error is an object created by every function in PEAR in case of a failure. It provides information on why a function fails.

How you get the object depends on PEAR::SetErrorHandling()

Prev | PEAR base classes | Next
Package PEAR_ErrorStack Constants | PEAR Manual | PEAR_Error::addUserInfo()


PEAR_Error::addUserInfo()

PEAR_Error::addUserInfo()

PEAR_Error::addUserInfo() – add user information

Synopsis

require_once 'PEAR.php';

void PEAR_Error::addUserInfo ( string $info )

Description

Adds an user information to the error object.

Parameter

  • string - user info

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR Error object | PEAR Manual | PEAR_Error::getCallback()


PEAR_Error::getCallback()

PEAR_Error::getCallback()

PEAR_Error::getCallback() – get callback function name

Synopsis

require_once 'PEAR.php';

string PEAR_Error::getCallback ( )

Description

Returns the name of the function called in case of throwing a PEAR_Error object.

Return value

string - function name

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::addUserInfo() | PEAR Manual | PEAR_Error::getCode()


PEAR_Error::getCode()

PEAR_Error::getCode()

PEAR_Error::getCode() – get error code

Synopsis

require_once 'PEAR.php';

integer PEAR_Error::getCode ( )

Description

Returns the error code coming with the error object.

Return value

integer - error number

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getCallback() | PEAR Manual | PEAR_Error::getMessage()


PEAR_Error::getMessage()

PEAR_Error::getMessage()

PEAR_Error::getMessage() – get error message

Synopsis

require_once 'PEAR.php';

string PEAR_Error::getMessage ( )

Description

Returns the error message coming with the error object.

Return value

string - error message

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getCode() | PEAR Manual | PEAR_Error::getMode()


PEAR_Error::getMode()

PEAR_Error::getMode()

PEAR_Error::getMode() – get error mode

Synopsis

require_once 'PEAR.php';

integer PEAR_Error::getMode ( )

Description

Returns the error mode used for throwing the error object.

Return value

integer - error mode

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getMessage() | PEAR Manual | PEAR_Error::getDebugInfo()


PEAR_Error::getDebugInfo()

PEAR_Error::getDebugInfo()

PEAR_Error::getDebugInfo() – get debug information

Synopsis

require_once 'PEAR.php';

string PEAR_Error::getDebugInfo ( )

Description

Returns debug information about an error

Return value

string - error debug information

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getMode() | PEAR Manual | PEAR_Error::getType()


PEAR_Error::getType()

PEAR_Error::getType()

PEAR_Error::getType() – get error type

Synopsis

require_once 'PEAR.php';

integer PEAR_Error::getType ( )

Description

Returns the name of the error class of the object.

Return value

string - error class name

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getDebugInfo() | PEAR Manual | PEAR_Error::getUserInfo()


PEAR_Error::getUserInfo()

PEAR_Error::getUserInfo()

PEAR_Error::getUserInfo() – get additional user-supplied information

Synopsis

require_once 'PEAR.php';

string PEAR_Error::getUserInfo ( )

Description

Returns additional information about an error

Return value

string - error information

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getType() | PEAR Manual | PEAR_Error::PEAR_Error()


PEAR_Error::PEAR_Error()

PEAR_Error::PEAR_Error()

PEAR_Error::PEAR_Error() – constructor

Synopsis

require_once 'PEAR.php';

void PEAR_Error::PEAR_Error ( string $message = 'unknown error' , integer $code = null , integer $mode = null , mixed $options = null , string $userinfo = null )

Description

Constructor

Parameter

  • string $message - the error message. A brief description of the occured failure or problem.

  • string $code - the error code. An error specific number.

  • integer $mode - the error mode

  • mixed $options - error mode specific options

  • string $userinfo - a string for additional user or debug info

Note

This function can be called statically.

Prev | PEAR Error object | Next
PEAR_Error::getUserInfo() | PEAR Manual | PEAR_Error::toString()


PEAR_Error::toString()

PEAR_Error::toString()

PEAR_Error::toString() – make string representation

Synopsis

require_once 'PEAR.php';

string PEAR_Error::toString ( )

Description

Makes a string representation of the error object.

Return value

string - object representation

Note

This function can not be called statically.

Prev | PEAR Error object | Next
PEAR_Error::PEAR_Error() | PEAR Manual | System


System

System

Table of Contents
  • Introduction -- General usage informations
  • System::rm -- remove files
  • System::mkDir -- create directories
  • System::&cat -- concatenate files
  • System::mktemp -- Create temporary files or directories
  • System::tmpdir -- Get path of temporal directory
  • System::which -- show full path of a command

Commandline functions

System provides an API for cross platform compatible commandline programs.

Prev | PEAR base classes | Next
PEAR_Error::toString() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – General usage informations

Command line style

The System functions are called like there commandline pendants

<?php
if (!System::rm('-r file1 dir1')) {
    print "Could not delete all the files";
}
?>

The arguments of the functions can be introduced as string or array:

<?php
System::rm(array('-r', 'file1', 'dir1'));
?>

System works like any other PHP function and will return FALSE , when the operation could not be completed entirely or partially. System won't stop when a error is found, it will try to continue. For example, if you are trying to delete three files and the first one can't be deleted, the next two files will be deleted but the function will return FALSE .

Errors will be printed out using the PHP function trigger_error()() so all the System methods can be silenced prefix a '@' sign before the function call (for example: @System::mkdir('-p dir1/dir2/dir3');).

Compatibility

System provides file system functions. They are named like the file system commands on Unix systems and supports the same options independent of your operation system.

At the moment the functions are tested under Linux and Windows. Further reports about compatibility on other systems are welcome.

In earlier versions of PHP 4, unlink() may fail on Windows. This bug is already fixed in up-to-date versions.

Man Pages

This manual describes the parameters of the System functions, most only a string. The arguments and options of the specific command are not documented in the manual. Please take a look on the man-pages on unix-like systems

man commandname

or when man-pages not available on your system, visit the On-line UNIX manual pages

Prev | System | Next
System | PEAR Manual | System::rm


System::rm

System::rm

System::rm – remove files

Synopsis

require_once "System.php";

mixed System::rm ( string $args )

Description

The rm command for removing files. Supports multiple files and dirs and also recursive deletes.

Parameter

  • string $args - the arguments for rm

Return value

mixed - TRUE for success

Note

This function can be called statically.

See

rm man page

Prev | System | Next
Introduction | PEAR Manual | System::mkDir


System::mkDir

System::mkDir

System::mkDir – create directories

Synopsis

require_once "System.php";

bool System::mkDir ( string $args )

Description

Creates directories.

Parameter

  • string $args - the name of the directory/-ies to create

Return value

bool - TRUE for success

Note

This function can be called statically.

See

mkdir man page

Prev | System | Next
System::rm | PEAR Manual | System::&cat


System::&cat

System::&cat

System::&cat – concatenate files

Synopsis

require_once "System.php";

boolean System::&cat ( string $args )

Description

Concatenate files. The method uses fopen(), URLs should work too.

Parameter

  • string $args - the arguments

Return value

boolean - TRUE on success

Note

This function can be called statically.

See

cat man page

Example

Using &cat()

<?php
$var = System::cat('sample.txt test.txt');
       System::cat('sample.txt test.txt > final.txt');
       System::cat('sample.txt test.txt >> final.txt');
?>
Prev | System | Next
System::mkDir | PEAR Manual | System::mktemp


System::mktemp

System::mktemp

System::mktemp – Create temporary files or directories

Synopsis

require_once "System.php";

mixed System::mktemp ( string $args = null )

Description

Creates temporary files or directories. This function will remove the created files when the scripts finish its execution.

Parameter

  • string $args - The arguments

    • prefix - The string that will be prepended to the temp name (defaults to tmp )

    • -d - A temporary dir will be created instead of a file.

    • -t - The target dir where the temporary file or directory will be created. If this parameter is missing, by default the environment vars TMP on Windows or TMPDIR on Unix will be used. If these vars are also missing c:\windows\temp or /tmp will be used.

Return value

mixed - the full path of the created file or dir, or FALSE

Note

This function can be called statically.

See

mktemp man page

Example

Using mktemp()

<?php
$tempfile = System::mktemp("prefix");
$tempdir  = System::mktemp("-d prefix");
$tempfile = System::mktemp();
$tempfile = System::mktemp("-t /var/tmp prefix");
?>
Prev | System | Next
System::&cat | PEAR Manual | System::tmpdir


System::tmpdir

System::tmpdir

System::tmpdir – Get path of temporal directory

Synopsis

require_once "System.php";

string System::tmpdir ( )

Description

Get the path of the temporal directory set in the system by looking in its environments variables.

Return value

string - The temporal directory on the system

Note

This function can be called statically.

php.ini-recommended removes the E from the variables_order setting, making unavailable the $_ENV array

See

tmpdir man page

Prev | System | Next
System::mktemp | PEAR Manual | System::which


System::which

System::which

System::which – show full path of a command

Synopsis

require_once "System.php";

mixed System::which ( string $program , boolean $fallback = false )

Description

The command shows the full path of a command.

Parameter

  • string $program - the command to search for

  • boolean $fallback - value to return in case of program not found

Return value

mixed - A string with the full path or FALSE if not found

Note

This function can be called statically.

See

which man page

Prev | System | Next
System::tmpdir | PEAR Manual | PEAR Installer classes


PEAR Installer classes

PEAR Installer classes

Table of Contents
  • PEAR_Autoload
  • PEAR_Builder
  • PEAR_ChannelFile
  • PEAR_Command
  • PEAR_Common
  • PEAR_Config
  • PEAR_Dependency
  • PEAR_Dependency2
  • PEAR_DependencyDB
  • PEAR_Frontend
  • PEAR_Installer
  • PEAR
  • PEAR_Packager
  • PEAR_Registry
  • PEAR_Remote
  • PEAR_REST
  • PEAR
  • PEAR_Validate
  • PEAR

The PEAR Installer classes provides an API for the administration and management of PEAR Packages.

Documentation is not fully up-to-date with PEAR version 1.4.0.

Prev | PEAR Installer: Core components (Installer API, error handling) | Next
System::which | PEAR Manual | PEAR_Autoload


PEAR_Autoload

PEAR_Autoload

Table of Contents
  • PEAR_Autoloader::addAggregateObject -- Add an aggregate object to object.
  • PEAR_Autoloader::addAutoload -- Add one or more autoload entries
  • PEAR_Autoloader::removeAggregateObject -- Remove an aggregate object
  • PEAR_Autoloader::removeAutoload -- Remove an autoload entry
  • PEAR_Autoloader::__call -- Overloaded object call handler

This class is for objects where you want to separate the code for some methods into separate classes. This is useful if you have a class with not-frequently-used methods that contain lots of code that you would like to avoid always parsing.

Class Trees for PEAR_Autoloader

  • PEAR

    • PEAR_Autoloader

Prev | PEAR Installer classes | Next
PEAR Installer classes | PEAR Manual | PEAR_Autoloader::addAggregateObject


PEAR_Autoloader::addAggregateObject

PEAR_Autoloader::addAggregateObject

PEAR_Autoloader::addAggregateObject() – Add an aggregate object to object.

Synopsis

require_once 'PEAR/autoloader.php';

void PEAR_Autoloader::addAggregateObject ( string $classname )

Description

Add an aggregate object to this object. If the specified class is not defined, loading it will be attempted following PEAR's file naming scheme. All the methods in the class will be aggregated, except private ones (name starting with an underscore) and constructors.

Parameter

string $classname

what class to instantiate for the object.

Note

This function can not be called statically.

Prev | PEAR_Autoload | Next
PEAR_Autoload | PEAR Manual | PEAR_Autoloader::addAutoload


PEAR_Autoloader::addAutoload

PEAR_Autoloader::addAutoload

PEAR_Autoloader::addAutoload() – Add one or more autoload entries

Synopsis

require_once 'PEAR/autoloader.php';

void PEAR_Autoloader::addAutoload ( string $method , string ''$classname = null )

Description

Add one or more autoload entries.

Parameter

string $method

which method to autoload

string $classname

which class to find the method in. If the $method parameter is an array, this parameter may be omitted (and will be ignored if not), and the $method parameter will be treated as an associative array with method names as keys and class names as values.

Note

This function can not be called statically.

Prev | PEAR_Autoload | Next
PEAR_Autoloader::addAggregateObject | PEAR Manual | PEAR_Autoloader::removeAggregateObject


PEAR_Autoloader::removeAggregateObject

PEAR_Autoloader::removeAggregateObject

PEAR_Autoloader::removeAggregateObject() – Remove an aggregate object

Synopsis

require_once 'PEAR/autoloader.php';

bool PEAR_Autoloader::removeAggregateObject ( string $classname )

Description

Remove an aggregate object.

Parameter

string $classname

the class of the object to remove

Return value

bool Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | PEAR_Autoload | Next
PEAR_Autoloader::addAutoload | PEAR Manual | PEAR_Autoloader::removeAutoload


PEAR_Autoloader::removeAutoload

PEAR_Autoloader::removeAutoload

PEAR_Autoloader::removeAutoload() – Remove an autoload entry

Synopsis

require_once 'autoloader.php';

bool PEAR_Autoloader::removeAutoload ( string $method )

Description

Remove an autoload entry.

Parameter

string $method

which method to remove the autoload entry for

Return value

bool Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | PEAR_Autoload | Next
PEAR_Autoloader::removeAggregateObject | PEAR Manual | PEAR_Autoloader::__call


PEAR_Autoloader::__call

PEAR_Autoloader::__call

PEAR_Autoloader::__call() – Overloaded object call handler

Synopsis

require_once 'PEAR/autoloader.php';

mixed PEAR_Autoloader::__call ( string $method , string $args , mixed &$retval )

Description

Overloaded object call handler, called each time an undefined/aggregated method is invoked. This method repeats the call in the right aggregate object and passes on the return value.

Parameter

string $method

which method that was called

string $args

An array of the parameters passed in the original call

mixed &$retval

Return value

mixed - The return value from the aggregated method, or a PEAR_Error if the called method was unknown.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Autoload | Next
PEAR_Autoloader::removeAutoload | PEAR Manual | PEAR_Builder


PEAR_Builder

PEAR_Builder

Table of Contents
  • PEAR_Builder::PEAR_Builder -- constructor
  • PEAR_Builder::build -- Build an extension from source
  • PEAR_Builder::log -- $level
  • PEAR_Builder::phpizeCallback -- Message callback function when running phpize

Class to handle building (compiling) extensions.

Class Trees for PEAR_Builder

  • PEAR_Common

    • PEAR_Builder

Prev | PEAR Installer classes | Next
PEAR_Autoloader::__call | PEAR Manual | PEAR_Builder::PEAR_Builder


PEAR_Builder::PEAR_Builder

PEAR_Builder::PEAR_Builder

PEAR_Builder::PEAR_Builder() – constructor

Synopsis

require_once 'PEAR/builder.php';

void PEAR_Builder::PEAR_Builder ( object &$ui )

Description

PEAR_Builder constructor

Parameter

object &$ui

user interface object (instance of PEAR_Frontend_*)

Note

This function can be called statically.

Prev | PEAR_Builder | Next
PEAR_Builder | PEAR Manual | PEAR_Builder::build


PEAR_Builder::build

PEAR_Builder::build

PEAR_Builder::build() – Build an extension from source

Synopsis

require_once 'PEAR/builder.php';

array PEAR_Builder::build ( string $descfile , mixed $callback = null )

Description

Build an extension from source. Runs phpize in the source directory, but compiles in a temporary directory (/var/tmp/pear-build-USER/PACKAGE-VERSION).

Parameter

string $descfile

path to XML package description file

mixed $callback

callback function used to report output

Return value

array - an array of associative arrays with built files, format:

<?php
array( array( 'file' => '/path/to/ext.so',
                    'php_api' => YYYYMMDD,
                    'zend_mod_api' => YYYYMMDD,
                    'zend_ext_api' =>; YYYYMMDD ),
       ... )
?>

See

PEAR_Common::infoFromDescriptionFile

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Builder | Next
PEAR_Builder::PEAR_Builder | PEAR Manual | PEAR_Builder::log


PEAR_Builder::log

PEAR_Builder::log

PEAR_Builder::log() –

Synopsis

require_once 'PEAR/builder.php';

void PEAR_Builder::log ( mixed $level , mixed $msg )

Description

This package is not documented yet.

Parameter

mixed $level

mixed $msg

Note

This function can not be called statically.

Prev | PEAR_Builder | Next
PEAR_Builder::build | PEAR Manual | PEAR_Builder::phpizeCallback


PEAR_Builder::phpizeCallback

PEAR_Builder::phpizeCallback

PEAR_Builder::phpizeCallback() – Message callback function when running phpize

Synopsis

require_once 'PEAR/builder.php';

void PEAR_Builder::phpizeCallback ( string $what , mixed $data )

Description

Message callback function used when running the phpize program. Extracts the API numbers used. Ignores other message types than "cmdoutput".

Parameter

string $what

the type of message

mixed $data

the message

Note

This function can not be called statically.

Prev | PEAR_Builder | Next
PEAR_Builder::log | PEAR Manual | PEAR_ChannelFile


PEAR_ChannelFile

PEAR_ChannelFile

Table of Contents
  • Class Summary PEAR_ChannelFile -- The Channel handling class
  • constructor PEAR_ChannelFile::PEAR_ChannelFile -- PEAR_ChannelFile
  • PEAR_ChannelFile::addFunction -- Add a protocol to the provides section
  • PEAR_ChannelFile::addMirror -- addMirror
  • PEAR_ChannelFile::addMirrorFunction -- Add a protocol to a mirror's provides section
  • PEAR_ChannelFile::fromAny -- Returns channel information from different sources
  • PEAR_ChannelFile::fromArray -- fromArray
  • PEAR_ChannelFile::fromXmlFile -- Parse a channel.xml file. Expects the name of a channel xml file as input.
  • PEAR_ChannelFile::fromXmlString -- fromXmlString
  • PEAR_ChannelFile::getAlias -- Return the suggested alias users can use to refer to this channel on the command-line.
  • PEAR_ChannelFile::getBaseURL -- Get the URL to access a base resource.
  • PEAR_ChannelFile::getErrors -- Wrapper to PEAR_ErrorStack::getErrors()
  • PEAR_ChannelFile::getFunction -- getFunction
  • PEAR_ChannelFile::getFunctions -- Retrieve a list of all xmlrpc/soap functions
  • PEAR_ChannelFile::getMirror -- Get the unserialized XML representing a mirror
  • PEAR_ChannelFile::getMirrors -- Retrieve a list of all mirrors and their contents
  • PEAR_ChannelFile::getName -- retrieve the channel name
  • PEAR_ChannelFile::getPath -- getPath
  • PEAR_ChannelFile::getPort -- retrieve the socket port used to connect to the server
  • PEAR_ChannelFile::getServer -- Retrieve the channel server
  • PEAR_ChannelFile::getSSL -- get SSL support for a channel or mirror
  • PEAR_ChannelFile::getSummary -- Get channel summary
  • PEAR_ChannelFile::getValidationObject -- Retrieve the object that can be used for custom validation
  • PEAR_ChannelFile::getValidationPackage -- Retrieve the name of the validation package for this channel
  • PEAR_ChannelFile::isIncludeable -- Determine whether a file exists in the include_path and is readable
  • PEAR_ChannelFile::lastModified -- This function is used by the channel updater and retrieves a value set by the registry, or the current time if it has not been set
  • PEAR_ChannelFile::resetFunctions -- Empty all protocol definitions
  • PEAR_ChannelFile::resetREST -- Since REST does not implement RPC, provide this as a logical wrapper around resetFunctions for REST
  • PEAR_ChannelFile::setAlias -- Set the channel alias
  • PEAR_ChannelFile::setBaseURL -- set the base URL for a REST resource, or set of REST resources
  • PEAR_ChannelFile::setDefaultPEARProtocols -- Set a channel's protocols to the protocols supported by pearweb
  • PEAR_ChannelFile::setName -- setName
  • PEAR_ChannelFile::setPath -- Set the file path for xmlrpc or soap
  • PEAR_ChannelFile::setPort -- Set the socket number (port) that is used to connect to this channel
  • PEAR_ChannelFile::setServer -- set the Channel server
  • PEAR_ChannelFile::setSSL -- Sets whether SSL is used to connect to this channel
  • PEAR_ChannelFile::setSummary -- set the summary of a channel's purpose
  • PEAR_ChannelFile::setValidationPackage -- Set the package validation object if it differs from PEAR's default.
  • PEAR_ChannelFile::supports -- determines whether a webservices function is supported by a channel
  • PEAR_ChannelFile::supportsREST -- Determines whether a channel supports any Representational State Transfer (REST) resources
  • PEAR_ChannelFile::toArray -- return the channel representation in array format
  • PEAR_ChannelFile::toXml -- Return an XML document based on the internal representation of this channel
  • PEAR_ChannelFile::validate -- Validate channel information.
  • PEAR_ChannelFile::validChannelServer -- Test whether a string contains a valid channel server.
  • Package PEAR Constants -- Constants defined in and used by PEAR
Prev | PEAR Installer classes | Next
PEAR_Builder::phpizeCallback | PEAR Manual | Class Summary PEAR_ChannelFile


Class Summary PEAR_ChannelFile

Class Summary PEAR_ChannelFile

Class Summary PEAR_ChannelFile – The Channel handling class

The Channel handling class

Represents channel.xml

Class Trees for PEAR_ChannelFile

  • PEAR_ChannelFile

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile | PEAR Manual | constructor PEAR_ChannelFile::PEAR_ChannelFile


constructor PEAR_ChannelFile::PEAR_ChannelFile

constructor PEAR_ChannelFile::PEAR_ChannelFile

constructor PEAR_ChannelFile::PEAR_ChannelFile() – PEAR_ChannelFile

Synopsis

require_once '/ChannelFile.php';

void constructor PEAR_ChannelFile::PEAR_ChannelFile ( )

Description

Simply creates the local error stack for the PEAR_ChannelFile object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
Class Summary PEAR_ChannelFile | PEAR Manual | PEAR_ChannelFile::addFunction


PEAR_ChannelFile::addFunction

PEAR_ChannelFile::addFunction

PEAR_ChannelFile::addFunction() – Add a protocol to the provides section

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::addFunction ( string $type , string $version , string $name = '' , string $mirror = false )

Description

Adds a supported xml-rpc or SOAP function to a channel definition file. The type should be xmlrpc or soap in lower-cased letters. No validation is performed on insert. For example:

<?php
require_once 'PEAR/ChannelFile.php';
$chan = new PEAR_ChannelFile;
$chan->setName('foo.example.com');
$chan->setSummary('demonstrate addFunction');
$chan->addFunction('xmlrpc', '1.0', 'people.list');
$chan->addFunction('oops', '1.0', 'bad.type');
?>

The oops protocol will be successfully created, but will fail upon validation.

Adding a function to a mirror simply validated to ensure that the mirror already exists.

<?php
require_once 'PEAR/ChannelFile.php';
$chan = new PEAR_ChannelFile;
$chan->setName('foo.example.com');
$chan->setSummary('demonstrate addFunction');
// fails: mirror not found
$chan->addFunction('soap', '1.0', 'people.list', 'mirror.example.com');
$chan->addMirror('mirror.example.com');
// succeeds
$chan->addFunction('soap', '1.0', 'people.list', 'mirror.example.com');
?>

Parameter

string $type

protocol type

string $version

protocol version

string $name

protocol name, if any

string $mirror

mirror name, if this is a mirror's protocol

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
constructor PEAR_ChannelFile::PEAR_ChannelFile | PEAR Manual | PEAR_ChannelFile::addMirror


PEAR_ChannelFile::addMirror

PEAR_ChannelFile::addMirror

PEAR_ChannelFile::addMirror() – addMirror

Synopsis

require_once '/ChannelFile.php';

boolean PEAR_ChannelFile::addMirror ( string $server , int $port = null )

Description

Add a mirror server. Note that mirrors must be added to a channel.xml in order for users to use them. Unofficial mirrors are not allowed without user intervention.

Parameter

string $server

mirror server

integer $port

mirror http port

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::addFunction | PEAR Manual | PEAR_ChannelFile::addMirrorFunction


PEAR_ChannelFile::addMirrorFunction

PEAR_ChannelFile::addMirrorFunction

PEAR_ChannelFile::addMirrorFunction() – Add a protocol to a mirror's provides section

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::addMirrorFunction ( string $mirror , string $type , string $version , string $name = '' )

Description

This is a direct way to add a xmlrpc or soap function to a mirror. See docs for addFunction().

Parameter

string $mirror

mirror name (server)

string $type

protocol type

string $version

protocol version

string $name

protocol name, if any

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::addMirror | PEAR Manual | PEAR_ChannelFile::fromAny


PEAR_ChannelFile::fromAny

PEAR_ChannelFile::fromAny

PEAR_ChannelFile::fromAny() – Returns channel information from different sources

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::fromAny ( string $info )

Description

Parse data from either a string or a channel.xml file.

Parameter

string $info

Filename of the source, or the source itself

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::addMirrorFunction | PEAR Manual | PEAR_ChannelFile::fromArray


PEAR_ChannelFile::fromArray

PEAR_ChannelFile::fromArray

PEAR_ChannelFile::fromArray() – fromArray

Synopsis

require_once '/ChannelFile.php';

PEAR_ChannelFile |false PEAR_ChannelFile::fromArray ( array $data , mixed $compatibility = false , mixed $stackClass = 'PEAR_ErrorStack' )

Description

Use this method with caution. This is intended to allow easy import of a pre-parsed channel.xml from another PEAR_ChannelFile class. It also makes possible the registry storage of channel.xml.

Parameter

array $data

The pre-parsed channel data

mixed $compatibility

mixed $stackClass

Return value

returns false if invalid

Throws

throws no exceptions thrown

Note

This function should be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::fromAny | PEAR Manual | PEAR_ChannelFile::fromXmlFile


PEAR_ChannelFile::fromXmlFile

PEAR_ChannelFile::fromXmlFile

PEAR_ChannelFile::fromXmlFile() – Parse a channel.xml file. Expects the name of a channel xml file as input.

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::fromXmlFile ( string $descfile )

Description

Parse the contents of a channel.xml and store in the current PEAR_ChannelFile object.

Parameter

string $descfile

name of channel xml file

Return value

returns success of parsing

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::fromArray | PEAR Manual | PEAR_ChannelFile::fromXmlString


PEAR_ChannelFile::fromXmlString

PEAR_ChannelFile::fromXmlString

PEAR_ChannelFile::fromXmlString() – fromXmlString

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::fromXmlString ( string $data )

Description

Parse the contents of a channel.xml and store in the current PEAR_ChannelFile object.

Parameter

string $data

contents of package.xml file

Return value

returns success of parsing

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::fromXmlFile | PEAR Manual | PEAR_ChannelFile::getAlias


PEAR_ChannelFile::getAlias

PEAR_ChannelFile::getAlias

PEAR_ChannelFile::getAlias() – Return the suggested alias users can use to refer to this channel on the command-line.

Synopsis

require_once '/ChannelFile.php';

string PEAR_ChannelFile::getAlias ( )

Description

This returns the channel alias. For instance, channel pear.php.net's alias is pear, channel pecl.php.net's alias is pecl.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::fromXmlString | PEAR Manual | PEAR_ChannelFile::getBaseURL


PEAR_ChannelFile::getBaseURL

PEAR_ChannelFile::getBaseURL

PEAR_ChannelFile::getBaseURL() – Get the URL to access a base resource.

Synopsis

require_once '/ChannelFile.php';

string PEAR_ChannelFile::getBaseURL ( string $resourceType , string|false $mirror = false )

Description

Hyperlinks in the returned xml will be used to retrieve the proper information needed. This allows extreme extensibility and flexibility in implementation

Parameter

string $resourceType

Resource Type to retrieve

mixed $mirror

Mirror name, or false for primary server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getAlias | PEAR Manual | PEAR_ChannelFile::getErrors


PEAR_ChannelFile::getErrors

PEAR_ChannelFile::getErrors

PEAR_ChannelFile::getErrors() – Wrapper to PEAR_ErrorStack::getErrors()

Synopsis

require_once '/ChannelFile.php';

array PEAR_ChannelFile::getErrors ( boolean $purge = false )

Description

Retrieve any errors from the last validation attempt.

Parameter

boolean $purge

determines whether to purge the error stack after retrieving

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getBaseURL | PEAR Manual | PEAR_ChannelFile::getFunction


PEAR_ChannelFile::getFunction

PEAR_ChannelFile::getFunction

PEAR_ChannelFile::getFunction() – getFunction

Synopsis

require_once '/ChannelFile.php';

array PEAR_ChannelFile::getFunction ( string $type , string $name = null , string $mirror = false )

Description

Retrieve the xml representation of a function. If found, the array is of format:

<?php
array(
 '_content' => 'functionname',
 'attribs' => array('version' => 'version.number')
);
?>

Parameter

string $type

Protocol type

string $name

Function name (NULL to return the first protocol of the type requested)

string $mirror

Mirror name, if any

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getErrors | PEAR Manual | PEAR_ChannelFile::getFunctions


PEAR_ChannelFile::getFunctions

PEAR_ChannelFile::getFunctions

PEAR_ChannelFile::getFunctions() – Retrieve a list of all xmlrpc/soap functions

Synopsis

require_once '/ChannelFile.php';

array|false PEAR_ChannelFile::getFunctions ( string $protocol , string $mirror = false )

Description

This retrieves an array of all defined xmlrpc and soap functions. Use getBaseURL() to access rest base URLs.

The format of each function is the same as is returned by getFunction()

Parameter

string $protocol

protocol type (xmlrpc, soap)

string $mirror

Mirror name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getFunction | PEAR Manual | PEAR_ChannelFile::getMirror


PEAR_ChannelFile::getMirror

PEAR_ChannelFile::getMirror

PEAR_ChannelFile::getMirror() – Get the unserialized XML representing a mirror

Synopsis

require_once '/ChannelFile.php';

array|false PEAR_ChannelFile::getMirror ( mixed $server )

Description

This returns the entire contents of the <mirror> tag as unserialized by the parser.

Parameter

mixed $server

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getFunctions | PEAR Manual | PEAR_ChannelFile::getMirrors


PEAR_ChannelFile::getMirrors

PEAR_ChannelFile::getMirrors

PEAR_ChannelFile::getMirrors() – Retrieve a list of all mirrors and their contents

Synopsis

require_once '/ChannelFile.php';

array PEAR_ChannelFile::getMirrors ( )

Description

This returns an array of mirror information in the format defined by getMirror()

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getMirror | PEAR Manual | PEAR_ChannelFile::getName


PEAR_ChannelFile::getName

PEAR_ChannelFile::getName

PEAR_ChannelFile::getName() – retrieve the channel name

Synopsis

require_once '/ChannelFile.php';

string|false PEAR_ChannelFile::getName ( )

Description

Note that the channel name is the channel server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getMirrors | PEAR Manual | PEAR_ChannelFile::getPath


PEAR_ChannelFile::getPath

PEAR_ChannelFile::getPath

PEAR_ChannelFile::getPath() – getPath

Synopsis

require_once '/ChannelFile.php';

string PEAR_ChannelFile::getPath ( string $protocol , string|false $mirror = false )

Description

Retrieve the relative path to access the protocol desired. If the channel is named foo.example.com and xmlrpc is accessed at foo.example.com/xml/rpc then path will be xml/rpc.

Parameter

string $protocol

xmlrpc or soap

string|FALSE $mirror

mirror name or FALSE for primary server

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getName | PEAR Manual | PEAR_ChannelFile::getPort


PEAR_ChannelFile::getPort

PEAR_ChannelFile::getPort

PEAR_ChannelFile::getPort() – retrieve the socket port used to connect to the server

Synopsis

require_once '/ChannelFile.php';

int|80 PEAR_ChannelFile::getPort ( mixed $mirror = false )

Description

web services are served through http servers, and so most servers use port 80. This function can be used to determine if a non-standard port is in use at a channel.

Parameter

mixed $mirror

Mirror name or FALSE for primary server

Return value

returns port number to connect to

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getPath | PEAR Manual | PEAR_ChannelFile::getServer


PEAR_ChannelFile::getServer

PEAR_ChannelFile::getServer

PEAR_ChannelFile::getServer() – Retrieve the channel server

Synopsis

require_once '/ChannelFile.php';

string|false PEAR_ChannelFile::getServer ( )

Description

This is an alias for getName().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getPort | PEAR Manual | PEAR_ChannelFile::getSSL


PEAR_ChannelFile::getSSL

PEAR_ChannelFile::getSSL

PEAR_ChannelFile::getSSL() – get SSL support for a channel or mirror

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::getSSL ( mixed $mirror = false )

Description

This function can be used to determine whether a channel or mirror requires a secure connection through SSL in order to access the packages.

Parameter

string|FALSE $mirror

Mirror name or false for primary server

Return value

returns Determines whether secure sockets layer (SSL) is used to connect to this channel

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getServer | PEAR Manual | PEAR_ChannelFile::getSummary


PEAR_ChannelFile::getSummary

PEAR_ChannelFile::getSummary

PEAR_ChannelFile::getSummary() – Get channel summary

Synopsis

require_once '/ChannelFile.php';

string|false PEAR_ChannelFile::getSummary ( )

Description

Return the brief description of a channel's purpose.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getSSL | PEAR Manual | PEAR_ChannelFile::getValidationObject


PEAR_ChannelFile::getValidationObject

PEAR_ChannelFile::getValidationObject

PEAR_ChannelFile::getValidationObject() – Retrieve the object that can be used for custom validation

Synopsis

require_once '/ChannelFile.php';

PEAR_Validate|false & PEAR_ChannelFile::getValidationObject ( string|false $package = false )

Description

Retrieve the channel validation object. The package parameter is intended to notify getValidationObject() of the package to be validated. If the package is in fact the channel validation package, then PEAR_Validate will be used for validation. This prevents an endless loop that would otherwise occur.

Parameter

string|FALSE $package

The name of the package to validate. If the package is the channel validation package, PEAR_Validate is returned.

Return value

returns false is returned if the validation package cannot be located

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getSummary | PEAR Manual | PEAR_ChannelFile::getValidationPackage


PEAR_ChannelFile::getValidationPackage

PEAR_ChannelFile::getValidationPackage

PEAR_ChannelFile::getValidationPackage() – Retrieve the name of the validation package for this channel

Synopsis

require_once '/ChannelFile.php';

string|false PEAR_ChannelFile::getValidationPackage ( )

Description

Retrieve the name of the channel's validation package as defined in channel.xml

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getValidationObject | PEAR Manual | PEAR_ChannelFile::isIncludeable


PEAR_ChannelFile::isIncludeable

PEAR_ChannelFile::isIncludeable

PEAR_ChannelFile::isIncludeable() – Determine whether a file exists in the include_path and is readable

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::isIncludeable ( string $path )

Description

Determine whether a file exists in the include_path and is readable

Parameter

string $path

Relative path to file.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::getValidationPackage | PEAR Manual | PEAR_ChannelFile::lastModified


PEAR_ChannelFile::lastModified

PEAR_ChannelFile::lastModified

PEAR_ChannelFile::lastModified() – This function is used by the channel updater and retrieves a value set by the registry, or the current time if it has not been set

Synopsis

require_once '/ChannelFile.php';

string PEAR_ChannelFile::lastModified ( )

Description

\ This method is used by the channel-update command in order to determine whether the local copy of channel.xml is up-to-date.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::isIncludeable | PEAR Manual | PEAR_ChannelFile::resetFunctions


PEAR_ChannelFile::resetFunctions

PEAR_ChannelFile::resetFunctions

PEAR_ChannelFile::resetFunctions() – Empty all protocol definitions

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::resetFunctions ( string $type , string|false $mirror = false )

Description

Clear all functions defined in the channel.xml, in order to start adding a new list.

Parameter

string $type

protocol type (xmlrpc, soap)

string|FALSE $mirror

mirror name, if any

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::lastModified | PEAR Manual | PEAR_ChannelFile::resetREST


PEAR_ChannelFile::resetREST

PEAR_ChannelFile::resetREST

PEAR_ChannelFile::resetREST() – Since REST does not implement RPC, provide this as a logical wrapper around resetFunctions for REST

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::resetREST ( string|false $mirror = false )

Description

Similar to resetFunctions(), resetREST() removes all REST base URLs in order to start adding new REST functions to a channel.

Parameter

string|FALSE $mirror

mirror name, if any

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::resetFunctions | PEAR Manual | PEAR_ChannelFile::setAlias


PEAR_ChannelFile::setAlias

PEAR_ChannelFile::setAlias

PEAR_ChannelFile::setAlias() – Set the channel alias

Synopsis

require_once '/ChannelFile.php';

boolean PEAR_ChannelFile::setAlias ( string $alias , boolean $local = false )

Description

Set the suggested alias that users can use on the command-line as a shortcut access to this channel. For instance, channel pear.php.net's alias is pear.

Parameter

string $alias

The alias

boolean $local

determines whether the alias is in channel.xml or local. If local, then this is the result of a pear channel-alias command.

Return value

returns success

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::resetREST | PEAR Manual | PEAR_ChannelFile::setBaseURL


PEAR_ChannelFile::setBaseURL

PEAR_ChannelFile::setBaseURL

PEAR_ChannelFile::setBaseURL() – set the base URL for a REST resource, or set of REST resources

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::setBaseURL ( string $resourceType , string $url , string|false $mirror = false )

Description

Set the base URL that users should use to access a REST resource or set of REST resources.

Parameter

string $resourceType

Resource Type this url links to

string $url

URL

string|FALSE $mirror

mirror name, if this is not a primary server REST base URL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setAlias | PEAR Manual | PEAR_ChannelFile::setDefaultPEARProtocols


PEAR_ChannelFile::setDefaultPEARProtocols

PEAR_ChannelFile::setDefaultPEARProtocols

PEAR_ChannelFile::setDefaultPEARProtocols() – Set a channel's protocols to the protocols supported by pearweb

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::setDefaultPEARProtocols ( string $version = '1.0' , string|false $mirror = false )

Description

This method sets up a channel's xmlrpc protocols to match that of pearweb (pear.php.net). Note that it does not configure REST resources, that must be done manually through setBaseURL().

Parameter

string $version

version of pearweb protocols to use.

string|FALSE $mirror

Mirror name or false for primary server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setBaseURL | PEAR Manual | PEAR_ChannelFile::setName


PEAR_ChannelFile::setName

PEAR_ChannelFile::setName

PEAR_ChannelFile::setName() – setName

Synopsis

require_once '/ChannelFile.php';

string|false PEAR_ChannelFile::setName ( string $name )

Description

Set the primary server (and name) of the channel.

Parameter

string $name

Channel name.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setDefaultPEARProtocols | PEAR Manual | PEAR_ChannelFile::setPath


PEAR_ChannelFile::setPath

PEAR_ChannelFile::setPath

PEAR_ChannelFile::setPath() – Set the file path for xmlrpc or soap

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::setPath ( string $protocol , string|false $path , string|false $mirror = false )

Description

Set the relative location to the channel that should be used to connect to the selected protocol. Defaults are xmlrpc.php for xml-rpc and soap.php for SOAP.

Parameter

string $protocol

xmlrpc or soap

string|FALSE $path

name of the mirror server, or FALSE for the primary

string|FALSE $mirror

Mirror name or false for primary server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setName | PEAR Manual | PEAR_ChannelFile::setPort


PEAR_ChannelFile::setPort

PEAR_ChannelFile::setPort

PEAR_ChannelFile::setPort() – Set the socket number (port) that is used to connect to this channel

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::setPort ( integer $port , string|false $mirror = false )

Description

As web services connect to channels through web servers, this can be used to set the port that should be used to connect. Default is 80 for regular webservers, and 443 for SSL secure servers.

Parameter

integer $port

port number

string|FALSE $mirror

name of the mirror server, or FALSE for the primary server

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setPath | PEAR Manual | PEAR_ChannelFile::setServer


PEAR_ChannelFile::setServer

PEAR_ChannelFile::setServer

PEAR_ChannelFile::setServer() – set the Channel server

Synopsis

require_once '/ChannelFile.php';

string|false PEAR_ChannelFile::setServer ( string $server , string|false $mirror = false )

Description

This is an alias to setName().

Parameter

string $server

Server name

string|FALSE $mirror

Mirror server name or FALSE for primary server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setPort | PEAR Manual | PEAR_ChannelFile::setSSL


PEAR_ChannelFile::setSSL

PEAR_ChannelFile::setSSL

PEAR_ChannelFile::setSSL() – Sets whether SSL is used to connect to this channel

Synopsis

require_once '/ChannelFile.php';

void PEAR_ChannelFile::setSSL ( bool $ssl = true , string|false $mirror = false )

Description

This function is used to inform the PEAR installer to use SSL when connecting to this channel server.

Parameter

boolean $ssl

Determines whether to turn on SSL support or turn it off

string|FALSE $mirror

name of the mirror server, or FALSE for the primary server

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setServer | PEAR Manual | PEAR_ChannelFile::setSummary


PEAR_ChannelFile::setSummary

PEAR_ChannelFile::setSummary

PEAR_ChannelFile::setSummary() – set the summary of a channel's purpose

Synopsis

require_once '/ChannelFile.php';

boolean PEAR_ChannelFile::setSummary ( string $summary )

Description

This sets a human-readable description of a channel's purpose.

Parameter

string $summary

The channel summary

Return value

returns success

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setSSL | PEAR Manual | PEAR_ChannelFile::setValidationPackage


PEAR_ChannelFile::setValidationPackage

PEAR_ChannelFile::setValidationPackage

PEAR_ChannelFile::setValidationPackage() – Set the package validation object if it differs from PEAR's default.

Synopsis

require_once '/ChannelFile.php';

boolean PEAR_ChannelFile::setValidationPackage ( string|false $validateclass , string $version )

Description

The class must be either in memory (PEAR_Validate or PEAR_Validate_PECL) or be available for include_once() via a simple formula: Transform the underscores (_) into directory separators (/), append .php and include.

A validation class named Foo_Bar_Baz should be available for inclusion via this code:

<?php
include_once 'Foo/Bar/Baz.php';
?>

In addition, the validation package must be available for installation from the channel with the version number to install specified by the $version parameter.

Parameter

string|FALSE $validateclass

pass in FALSE to reset to the default packagename regex

string $version

The package version that must be installed for this channel to validate properly.

Return value

returns success

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setSummary | PEAR Manual | PEAR_ChannelFile::supports


PEAR_ChannelFile::supports

PEAR_ChannelFile::supports

PEAR_ChannelFile::supports() – determines whether a webservices function is supported by a channel

Synopsis

require_once '/ChannelFile.php';

boolean PEAR_ChannelFile::supports ( string $type , string $name = null , string|false $mirror = false , string $version = '1.0' )

Description

This is used in the installer to determine whether a protocol is supported before attempting to connect to a remote server and invoke the function needed.

Parameter

string $type

protocol type (xmlrpc or soap)

string $name

function name (like package.info)

string|FALSE $mirror

Mirror server name or FALSE for primary server

string $version

function version

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::setValidationPackage | PEAR Manual | PEAR_ChannelFile::supportsREST


PEAR_ChannelFile::supportsREST

PEAR_ChannelFile::supportsREST

PEAR_ChannelFile::supportsREST() – Determines whether a channel supports any Representational State Transfer (REST) resources

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::supportsREST ( string $mirror = false )

Description

This does not check to see which REST resources are supported, use getBaseURL() to check specific REST resource or resource group support.

Parameter

string|FALSE $mirror

Mirror server name or FALSE for the primary server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::supports | PEAR Manual | PEAR_ChannelFile::toArray


PEAR_ChannelFile::toArray

PEAR_ChannelFile::toArray

PEAR_ChannelFile::toArray() – return the channel representation in array format

Synopsis

require_once '/ChannelFile.php';

array PEAR_ChannelFile::toArray ( )

Description

This function should not be used to directly manipulate data, but instead as a means to serialize and transport the data in a more efficient manner than as the original xml.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::supportsREST | PEAR Manual | PEAR_ChannelFile::toXml


PEAR_ChannelFile::toXml

PEAR_ChannelFile::toXml

PEAR_ChannelFile::toXml() – Return an XML document based on the internal representation of this channel

Synopsis

require_once '/ChannelFile.php';

string PEAR_ChannelFile::toXml ( )

Description

This should be used to generate a channel.xml based on the data stored in the PEAR_ChannelFile class.

Return value

returns XML data

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::toArray | PEAR Manual | PEAR_ChannelFile::validate


PEAR_ChannelFile::validate

PEAR_ChannelFile::validate

PEAR_ChannelFile::validate() – Validate channel information.

Synopsis

require_once '/ChannelFile.php';

boolean PEAR_ChannelFile::validate ( )

Description

Specific errors can be retrieved post-validation with the getErrors() method. Errors are stored by the PEAR_ErrorStack class, more information on the format of the array can be found in the documentation for PEAR_ErrorStack.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::toXml | PEAR Manual | PEAR_ChannelFile::validChannelServer


PEAR_ChannelFile::validChannelServer

PEAR_ChannelFile::validChannelServer

PEAR_ChannelFile::validChannelServer() – Test whether a string contains a valid channel server.

Synopsis

require_once '/ChannelFile.php';

bool PEAR_ChannelFile::validChannelServer ( string $server )

Description

determines whether a channel server is a valid servername.

Parameter

string $server

Server name. May contain subpaths as in foo.example.com/path/to/channel

Throws

throws no exceptions thrown

Note

This function can be called statically.

Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::validate | PEAR Manual | Package PEAR Constants


Package PEAR Constants

Package PEAR Constants

Package PEAR Constants – Constants defined in and used by PEAR

All Constants

Constants defined in ChannelFile.php

Error Constants defined in ChannelFile.php
Name | Value | Line Number
PEAR_CHANNELFILE_ERROR_CANT_MAKE_PARSER | 4 | 48
PEAR_CHANNELFILE_ERROR_EMPTY_REGEX | 24 | 97
PEAR_CHANNELFILE_ERROR_INVALID | 23 | 93
PEAR_CHANNELFILE_ERROR_INVALID_HOST | 11 | 81
PEAR_CHANNELFILE_ERROR_INVALID_MIRROR | 21 | 85
PEAR_CHANNELFILE_ERROR_INVALID_MIRRORTYPE | 22 | 89
PEAR_CHANNELFILE_ERROR_INVALID_NAME | 7 | 65
PEAR_CHANNELFILE_ERROR_INVALID_PORT | 33 | 122
PEAR_CHANNELFILE_ERROR_INVALID_SSL | 37 | 138
PEAR_CHANNELFILE_ERROR_INVALID_VERSION | 2 | 38
PEAR_CHANNELFILE_ERROR_MIRROR_NOT_FOUND | 32 | 118
PEAR_CHANNELFILE_ERROR_MULTILINE_SUMMARY | 9 | 73
PEAR_CHANNELFILE_ERROR_NOBASEURLTYPE | 35 | 130
PEAR_CHANNELFILE_ERROR_NOVALIDATE_NAME | 27 | 109
PEAR_CHANNELFILE_ERROR_NOVALIDATE_VERSION | 28 | 113
PEAR_CHANNELFILE_ERROR_NO_FUNCTIONNAME | 26 | 105
PEAR_CHANNELFILE_ERROR_NO_FUNCTIONVERSION | 25 | 101
PEAR_CHANNELFILE_ERROR_NO_HOST | 10 | 77
PEAR_CHANNELFILE_ERROR_NO_NAME | 6 | 61
PEAR_CHANNELFILE_ERROR_NO_STATICVERSION | 34 | 126
PEAR_CHANNELFILE_ERROR_NO_SUMMARY | 8 | 69
PEAR_CHANNELFILE_ERROR_NO_VERSION | 1 | 33
PEAR_CHANNELFILE_ERROR_NO_XML_EXT | 3 | 43
PEAR_CHANNELFILE_ERROR_PARSER_ERROR | 5 | 53
PEAR_CHANNELFILE_URI_CANT_MIRROR | 36 | 134
Prev | PEAR_ChannelFile | Next
PEAR_ChannelFile::validChannelServer | PEAR Manual | PEAR_Command


PEAR_Command

PEAR_Command

Table of Contents
  • PEAR_Command::factory -- get object for executing a command.
  • PEAR_Command::getCommands -- get list of currently supported commands
  • PEAR_Command::getDescription -- get description for a command
  • PEAR_Command::getGetoptArgs -- compiles arguments for getopt
  • PEAR_Command::getHelp -- get help for command
  • PEAR_Command::getShortcuts -- get list of command shortcuts.
  • PEAR_Command::registerCommands -- scan the command directory

PEAR command class, a simple factory class for administrative commands.

Prev | PEAR Installer classes | Next
Package PEAR Constants | PEAR Manual | PEAR_Command::factory


PEAR_Command::factory

PEAR_Command::factory

PEAR_Command::factory() – get object for executing a command.

Synopsis

require_once 'PEAR/command.php';

object PEAR_Command::factory ( string $command , object &$config )

Description

Get the right object for executing a command.

Parameter

string $command

The name of the command

object &$config

Instance of PEAR_Config object

Return value

object the command object

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command | PEAR Manual | PEAR_Command::getCommands


PEAR_Command::getCommands

PEAR_Command::getCommands

PEAR_Command::getCommands() – get list of currently supported commands

Synopsis

require_once 'PEAR/command.php';

array PEAR_Command::getCommands ( ( void )

Description

Get the list of currently supported commands, and what classes implement them.

Return value

array command => implementing class

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command::factory | PEAR Manual | PEAR_Command::getDescription


PEAR_Command::getDescription

PEAR_Command::getDescription

PEAR_Command::getDescription() – get description for a command

Synopsis

require_once 'PEAR/command.php';

string PEAR_Command::getDescription ( string $command )

Description

Get description for a command.

Parameter

string $command

Name of the command

Return value

string command description

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command::getCommands | PEAR Manual | PEAR_Command::getGetoptArgs


PEAR_Command::getGetoptArgs

PEAR_Command::getGetoptArgs

PEAR_Command::getGetoptArgs() – compiles arguments for getopt

Synopsis

require_once 'PEAR/command.php';

void PEAR_Command::getGetoptArgs ( string $command , string &$short_args , array &$long_args )

Description

Compiles arguments for getopt.

Parameter

string $command

command to get optstring for

string &$short_args

(reference) short getopt format

array &$long_args

(reference) long getopt format

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command::getDescription | PEAR Manual | PEAR_Command::getHelp


PEAR_Command::getHelp

PEAR_Command::getHelp

PEAR_Command::getHelp() – get help for command

Synopsis

require_once 'PEAR/command.php';

string PEAR_Command::getHelp ( string $command )

Description

Get help for command.

Parameter

string $command

Name of the command to return help for

Return value

string help text

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command::getGetoptArgs | PEAR Manual | PEAR_Command::getShortcuts


PEAR_Command::getShortcuts

PEAR_Command::getShortcuts

PEAR_Command::getShortcuts() – get list of command shortcuts.

Synopsis

require_once 'PEAR/command.php';

array PEAR_Command::getShortcuts ( ( void )

Description

Get the list of command shortcuts.

Return value

array shortcut => command

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command::getHelp | PEAR Manual | PEAR_Command::registerCommands


PEAR_Command::registerCommands

PEAR_Command::registerCommands

PEAR_Command::registerCommands() – scan the command directory

Synopsis

require_once 'PEAR/command.php';

bool PEAR_Command::registerCommands ( bool $merge = false , string $dir = null )

Description

Scan through the Command directory looking for classes and see what commands they implement.

Parameter

boolean $merge

if FALSE (default), the new list of commands should replace the current one. If TRUE, new entries will be merged with old.

string $dir

where (what directory) to look for classes, defaults to the Command subdirectory of the directory from where this file (__FILE__) is included.

Return value

bool TRUE on success

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function should be called statically.

Prev | PEAR_Command | Next
PEAR_Command::getShortcuts | PEAR Manual | PEAR_Common


PEAR_Common

PEAR_Common

Table of Contents
  • PEAR_Common::PEAR_Common -- PEAR_Common constructor
  • PEAR_Common::addTempFile -- register a temporary file or directory
  • PEAR_Common::analyzeSourceCode -- analyze the source code of the given PHP file
  • PEAR_Common::buildProvidesArray -- Build a array
  • PEAR_Common::downloadHttp -- Download a file through HTTP
  • PEAR_Common::infoFromAny -- Returns package information from different sources
  • PEAR_Common::infoFromDescriptionFile -- Returns information about a package file
  • PEAR_Common::infoFromString -- Returns information about a package file
  • PEAR_Common::infoFromTgzFile -- Returns information about a package file
  • PEAR_Common::log -- Logging method
  • PEAR_Common::mkDirHier -- Create a directory and necessary parent directories
  • PEAR_Common::mkTempDir -- Create and register a temporary directory.
  • PEAR_Common::setFrontendObject -- Set object representing frontend to use.
  • PEAR_Common::validatePackageInfo -- Validate XML package definition file
  • PEAR_Common::validPackageName -- Test whether a string is a valid package name
  • PEAR_Common::xmlFromInfo -- Return an XML document based on the package info

Class providing common functionality for PEAR administration classes.

Class Trees for PEAR_Common()

  • PEAR

    • PEAR_Common

Prev | PEAR Installer classes | Next
PEAR_Command::registerCommands | PEAR Manual | PEAR_Common::PEAR_Common


PEAR_Common::PEAR_Common

PEAR_Common::PEAR_Common

PEAR_Common::PEAR_Common() – PEAR_Common constructor

Synopsis

require_once 'PEAR/common.php';

void PEAR_Common::PEAR_Common ( ( void )

Description

PEAR_Common constructor

Note

This function can be called statically.

Prev | PEAR_Common | Next
PEAR_Common | PEAR Manual | PEAR_Common::addTempFile


PEAR_Common::addTempFile

PEAR_Common::addTempFile

PEAR_Common::addTempFile() – register a temporary file or directory

Synopsis

require_once 'PEAR/common.php';

void PEAR_Common::addTempFile ( string $file )

Description

Register a temporary file or directory. When the destructor is executed, all registered temporary files and directories are removed.

Parameter

string $file

name of file or directory

Note

This function can be called statically.

Prev | PEAR_Common | Next
PEAR_Common::PEAR_Common | PEAR Manual | PEAR_Common::analyzeSourceCode


PEAR_Common::analyzeSourceCode

PEAR_Common::analyzeSourceCode

PEAR_Common::analyzeSourceCode() – analyze the source code of the given PHP file

Synopsis

require_once 'PEAR/common.php';

array PEAR_Common::analyzeSourceCode ( string $file )

Description

Analyze the source code of the given PHP file

Parameter

string $file

Filename of the PHP file

Return value

array - hash list of declared_classes , declared_methods , declared_functions and used_classes

Note

This function can be called statically.

Prev | PEAR_Common | Next
PEAR_Common::addTempFile | PEAR Manual | PEAR_Common::buildProvidesArray


PEAR_Common::buildProvidesArray

PEAR_Common::buildProvidesArray

PEAR_Common::buildProvidesArray() – Build a array

Synopsis

require_once 'PEAR/common.php';

void PEAR_Common::buildProvidesArray ( array $srcinfo )

Description

Build a "provides" array from data returned by analyzeSourceCode(). The format of the built array is like this:

<?php
array(
        'class;MyClass' =>
           array(
           'type' => 'class',
           'name' => 'MyClass'
           ),
           ...
        )
?>

Parameter

array $srcinfo

array with information about a source file as returned by the analyzeSourceCode() method.

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::analyzeSourceCode | PEAR Manual | PEAR_Common::downloadHttp


PEAR_Common::downloadHttp

PEAR_Common::downloadHttp

PEAR_Common::downloadHttp() – Download a file through HTTP

Synopsis

require_once 'PEAR/common.php';

string PEAR_Common::downloadHttp ( string $url , object &$ui , string $save_dir = '.' , mixed $callback = null )

Description

Download a file through HTTP. Considers suggested file name in Content-disposition: header and can run a callback function for different events. The callback will be called with two parameters: the callback type, and parameters. The implemented callback types are:

  • 'setup' - called at the very beginning, parameter is a UI object that should be used for all output

  • 'message' - the parameter is a string with an informational message

  • 'saveas' - may be used to save with a different file name, the parameter is the filename that is about to be used. If a 'saveas' callback returns a non-empty string, that file name will be used as the filename instead. Note that $save_dir will not be affected by this, only the basename of the file.

  • 'start' - download is starting, parameter is number of bytes that are expected, or -1 if unknown

  • 'bytesread' - parameter is the number of bytes read so far

  • 'done' - download is complete, parameter is the total number of bytes read

  • 'connfailed' - if the TCP connection fails, this callback is called with

    <?php
    array(host,port,errno,errmsg)
    ?>

  • 'writefailed' - if writing to disk fails, this callback is called with

    <?php
    array(destfile,errmsg)
    ?>

If an HTTP proxy has been configured (http_proxy PEAR_Config setting), the proxy will be used.

Parameter

string $url

the URL to download

object &$ui

PEAR_Frontend_* instance

string $save_dir

directory to save file in

mixed $callback

function/method to call for status updates

object $config

PEAR_Config instance

Return value

string - Returns the full path of the downloaded file or a PEAR error on failure. If the error is caused by socket-related errors, the error object will have the fsockopen error code available through getCode().

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::buildProvidesArray | PEAR Manual | PEAR_Common::infoFromAny


PEAR_Common::infoFromAny

PEAR_Common::infoFromAny

PEAR_Common::infoFromAny() – Returns package information from different sources

Synopsis

require_once 'PEAR/common.php';

string PEAR_Common::infoFromAny ( string $info )

Description

Returns package information from different sources. This method is able to extract information about a package from a .tgz archive or from a XML package definition file.

Parameter

string $info

Filename of the source ('package.xml' , '<package>.tgz' )

Return value

string - Package information

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::downloadHttp | PEAR Manual | PEAR_Common::infoFromDescriptionFile


PEAR_Common::infoFromDescriptionFile

PEAR_Common::infoFromDescriptionFile

PEAR_Common::infoFromDescriptionFile() – Returns information about a package file

Synopsis

require_once 'PEAR/common.php';

array PEAR_Common::infoFromDescriptionFile ( string $descfile )

Description

Returns information about a package file. Expects the name of a package xml file as input.

Parameter

string $descfile

name of package xml file

Return value

array - array with package information

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::infoFromAny | PEAR Manual | PEAR_Common::infoFromString


PEAR_Common::infoFromString

PEAR_Common::infoFromString

PEAR_Common::infoFromString() – Returns information about a package file

Synopsis

require_once 'PEAR/common.php';

array PEAR_Common::infoFromString ( string $data )

Description

Returns information about a package file. Expects the contents of a package xml file as input.

Parameter

string $data

content of package xml file

Return value

array - array with package information

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::infoFromDescriptionFile | PEAR Manual | PEAR_Common::infoFromTgzFile


PEAR_Common::infoFromTgzFile

PEAR_Common::infoFromTgzFile

PEAR_Common::infoFromTgzFile() – Returns information about a package file

Synopsis

require_once 'PEAR/common.php';

array PEAR_Common::infoFromTgzFile ( string $file )

Description

Returns information about a package file. Expects the name of a gzipped tar file as input.

Parameter

string $file

name of .tgz file

Return value

array - array with package information

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::infoFromString | PEAR Manual | PEAR_Common::log


PEAR_Common::log

PEAR_Common::log

PEAR_Common::log() – Logging method

Synopsis

require_once 'PEAR/common.php';

void PEAR_Common::log ( int $level , string $msg )

Description

Logging method.

Parameter

integer $level

log level (0 is quiet, higher is noisier)

string $msg

message to write to the log

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::infoFromTgzFile | PEAR Manual | PEAR_Common::mkDirHier


PEAR_Common::mkDirHier

PEAR_Common::mkDirHier

PEAR_Common::mkDirHier() – Create a directory and necessary parent directories

Synopsis

require_once 'common.php';

bool PEAR_Common::mkDirHier ( string $dir )

Description

Wrapper to System::mkDir(), creates a directory as well as any necessary parent directories.

Parameter

string $dir

directory name

Return value

bool - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::log | PEAR Manual | PEAR_Common::mkTempDir


PEAR_Common::mkTempDir

PEAR_Common::mkTempDir

PEAR_Common::mkTempDir() – Create and register a temporary directory.

Synopsis

require_once 'PEAR/common.php';

string PEAR_Common::mkTempDir ( string $tmpdir = '' )

Description

Create and register a temporary directory.

Parameter

string $tmpdir

Directory to use as tmpdir. Will use system defaults (for example /tmp or c:\windows\temp ) if not specified.

Return value

string name of created directory

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::mkDirHier | PEAR Manual | PEAR_Common::setFrontendObject


PEAR_Common::setFrontendObject

PEAR_Common::setFrontendObject

PEAR_Common::setFrontendObject() – Set object representing frontend to use.

Synopsis

require_once 'common.php';

void PEAR_Common::setFrontendObject ( object &$ui )

Description

Set object that represents the frontend to be used.

Parameter

object $ui

Reference of the frontend object

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::mkTempDir | PEAR Manual | PEAR_Common::validatePackageInfo


PEAR_Common::validatePackageInfo

PEAR_Common::validatePackageInfo

PEAR_Common::validatePackageInfo() – Validate XML package definition file

Synopsis

require_once 'common.php';

boolean PEAR_Common::validatePackageInfo ( string $info , array &$errors , array &$warnings , string $dir_prefix = '' )

Description

Validate XML package definition file.

Parameter

string $info

Filename of the package archive or of the package definition file

array $errors

Array that will contain the errors

array $warnings

Array that will contain the warnings

string $dir_prefix

directory where source files may be found, or empty if they are not available

Return value

bool - TRUE if valid

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::setFrontendObject | PEAR Manual | PEAR_Common::validPackageName


PEAR_Common::validPackageName

PEAR_Common::validPackageName

PEAR_Common::validPackageName() – Test whether a string is a valid package name

Synopsis

require_once 'PEAR/common.php';

bool PEAR_Common::validPackageName ( string $name )

Description

Test whether a string contains a valid package name.

Parameter

string $name

the package name to test

Return value

bool - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::validatePackageInfo | PEAR Manual | PEAR_Common::xmlFromInfo


PEAR_Common::xmlFromInfo

PEAR_Common::xmlFromInfo

PEAR_Common::xmlFromInfo() – Return an XML document based on the package info

Synopsis

require_once 'PEAR/common.php';

string PEAR_Common::xmlFromInfo ( array $pkginfo )

Description

Return an XML document based on the package info (as returned by the PEAR_Common::infoFrom*() methods).

Parameter

array $pkginfo

package info

Return value

string - XML data

Note

This function can not be called statically.

Prev | PEAR_Common | Next
PEAR_Common::validPackageName | PEAR Manual | PEAR_Config


PEAR_Config

PEAR_Config

Table of Contents
  • PEAR_Config::PEAR_Config -- Constructor
  • PEAR_Config::apiVersion -- return API version (1.1 as of PEAR 1.4.0)
  • PEAR_Config::definedBy -- Tells what config layer that gets to define a key
  • PEAR_Config::deleteChannel -- deleteChannel
  • PEAR_Config::get -- Returns a configuration value
  • PEAR_Config::getConfFile -- Gets the file used for storing the config for a layer
  • PEAR_Config::getDefaultChannel -- Retrieve the default channel.
  • PEAR_Config::getDocs -- Get the documentation for a config value
  • PEAR_Config::getFTP -- The ftp server is set in readFTPConfigFile. It exists only if a remote configuration file has been specified
  • PEAR_Config::getGroup -- Get the parameter group for a config key
  • PEAR_Config::getGroupKeys -- Get the list of the parameters in a group
  • PEAR_Config::getGroups -- Get the list of parameter groups
  • PEAR_Config::getKeys -- Get all the current config keys
  • PEAR_Config::getLayers -- Returns the layers defined
  • PEAR_Config::getPrompt -- Get short documentation for a config value
  • PEAR_Config::getRegistry -- getRegistry
  • PEAR_Config::getRemote -- getRemote
  • PEAR_Config::getREST -- getREST
  • PEAR_Config::getSetValues -- Get the list of allowed set values for a config value
  • PEAR_Config::getType -- Get the type of a config value
  • PEAR_Config::isDefined -- Tells whether a key exists as config value
  • PEAR_Config::isDefinedLayer -- Tells whether a config layer exists
  • PEAR_Config::mergeConfigFile -- Merges data into a config layer from a file
  • PEAR_Config::noRegistry -- noRegistry
  • PEAR_Config::readConfigFile -- Reads configuration data from a file
  • PEAR_Config::readFTPConfigFile -- readFTPConfigFile
  • PEAR_Config::remove -- Remove a config key from a config layer
  • PEAR_Config::removeLayer -- Temporarily remove an entire config layer
  • PEAR_Config::set -- Set config value in specific layer
  • PEAR_Config::setChannels -- Set the list of channels.
  • PEAR_Config::setInstallRoot -- setInstallRoot
  • PEAR_Config::setRegistry -- This is to allow customization like the use of installroot
  • PEAR_Config::singleton -- Return a reference of a PEAR_Config object
  • PEAR_Config::store -- Stores configuration data in a layer
  • PEAR_Config::toDefault -- Revert value of config key to the system-defined one
  • PEAR_Config::validConfiguration -- Determine whether any configuration files have been detected, and whether a registry object can be retrieved from this configuration.
  • PEAR_Config::writeConfigFile -- Write data into config layer from file

Class Trees for PEAR_Config()

  • PEAR

    • PEAR_Config

Prev | PEAR Installer classes | Next
PEAR_Common::xmlFromInfo | PEAR Manual | PEAR_Config::PEAR_Config


PEAR_Config::PEAR_Config

PEAR_Config::PEAR_Config

PEAR_Config::PEAR_Config() – Constructor

Synopsis

require_once 'PEAR/config.php';

 void       PEAR_Config::PEAR_Config (
 string $user_file = ''
  , string $system_file = ''
)

Description

Constructor

Parameter

string $user_file

file to read user-defined options from

string $system_file

file to read system-wide defaults from

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config | PEAR Manual | PEAR_Config::apiVersion


PEAR_Config::apiVersion

PEAR_Config::apiVersion

PEAR_Config::apiVersion() – return API version (1.1 as of PEAR 1.4.0)

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

void PEAR_Config::apiVersion ( )

Description

Returns API version (1.1 as of PEAR 1.4.0).

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::PEAR_Config | PEAR Manual | PEAR_Config::definedBy


PEAR_Config::definedBy

PEAR_Config::definedBy

PEAR_Config::definedBy() – Tells what config layer that gets to define a key

Synopsis

require_once 'PEAR/config.php';

string PEAR_Config::definedBy ( string $key )

Description

Tells what config layer that gets to define a key.

Parameter

string $key

config key

Return value

string - the config layer, or an empty string if not found

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::apiVersion | PEAR Manual | PEAR_Config::deleteChannel


PEAR_Config::deleteChannel

PEAR_Config::deleteChannel

PEAR_Config::deleteChannel() – deleteChannel

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

void PEAR_Config::deleteChannel ( string $channel )

Description

remove a channel's configuration entirely.

Parameter

string $channel

Channel name to delete (channel server).

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::definedBy | PEAR Manual | PEAR_Config::get


PEAR_Config::get

PEAR_Config::get

PEAR_Config::get() – Returns a configuration value

Synopsis

require_once 'PEAR/config.php';

mixed PEAR_Config::get ( string $key , mixed $layer = null )

Description

Returns a configuration value, prioritizing layers as per the layers property.

Parameter

string $key

config key

mixed $layer

layer key

Return value

mixed the config value, or NULL if not found

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::deleteChannel | PEAR Manual | PEAR_Config::getConfFile


PEAR_Config::getConfFile

PEAR_Config::getConfFile

PEAR_Config::getConfFile() – Gets the file used for storing the config for a layer

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

void PEAR_Config::getConfFile ( string $layer )

Description

Use this to retrieve the name of the configuration file that provides values for a particular configuration layer.

Parameter

string $layer

user, system, or ftp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::get | PEAR Manual | PEAR_Config::getDefaultChannel


PEAR_Config::getDefaultChannel

PEAR_Config::getDefaultChannel

PEAR_Config::getDefaultChannel() – Retrieve the default channel.

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

string|false PEAR_Config::getDefaultChannel ( string $layer = null )

Description

On startup, channels are not initialized, so if the default channel is not pear.php.net, then initialize the config.

Parameter

string $layer

layer from which to retrieve the registry, or null for the first to match

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getConfFile | PEAR Manual | PEAR_Config::getDocs


PEAR_Config::getDocs

PEAR_Config::getDocs

PEAR_Config::getDocs() – Get the documentation for a config value

Synopsis

require_once 'PEAR/config.php';

string PEAR_Config::getDocs ( string $key )

Description

Get the documentation for a config value.

Parameter

string $key

config key

Return value

string - documentation string

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getDefaultChannel | PEAR Manual | PEAR_Config::getFTP


PEAR_Config::getFTP

PEAR_Config::getFTP

PEAR_Config::getFTP() – The ftp server is set in readFTPConfigFile(). It exists only if a remote configuration file has been specified

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

PEAR_FTP|false& PEAR_Config::getFTP ( )

Description

returns the object that can be used for accessing the remote FTP server, or false if none should be used.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getDocs | PEAR Manual | PEAR_Config::getGroup


PEAR_Config::getGroup

PEAR_Config::getGroup

PEAR_Config::getGroup() – Get the parameter group for a config key

Synopsis

require_once 'PEAR/config.php';

string PEAR_Config::getGroup ( string $key )

Description

Get the parameter group for a config key.

Parameter

string $key

config key

Return value

string - parameter group

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getFTP | PEAR Manual | PEAR_Config::getGroupKeys


PEAR_Config::getGroupKeys

PEAR_Config::getGroupKeys

PEAR_Config::getGroupKeys() – Get the list of the parameters in a group

Synopsis

require_once 'PEAR/config.php';

array PEAR_Config::getGroupKeys ( string $group )

Description

Get the list of the parameters in a group.

Parameter

string $group

parameter group

Return value

array list of parameters in $group

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getGroup | PEAR Manual | PEAR_Config::getGroups


PEAR_Config::getGroups

PEAR_Config::getGroups

PEAR_Config::getGroups() – Get the list of parameter groups

Synopsis

require_once 'PEAR/config.php';

array PEAR_Config::getGroups ( ( void )

Description

Get the list of parameter groups.

Return value

array - list of parameter groups

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getGroupKeys | PEAR Manual | PEAR_Config::getKeys


PEAR_Config::getKeys

PEAR_Config::getKeys

PEAR_Config::getKeys() – Get all the current config keys

Synopsis

require_once 'PEAR/config.php';

array PEAR_Config::getKeys ( ( void )

Description

Get all the current config keys

Return value

array - simple array of config keys

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getGroups | PEAR Manual | PEAR_Config::getLayers


PEAR_Config::getLayers

PEAR_Config::getLayers

PEAR_Config::getLayers() – Returns the layers defined

Synopsis

require_once 'PEAR/config.php';

array PEAR_Config::getLayers ( ( void )

Description

Returns the layers defined, except the 'default' one

Return value

array the defined layers

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getKeys | PEAR Manual | PEAR_Config::getPrompt


PEAR_Config::getPrompt

PEAR_Config::getPrompt

PEAR_Config::getPrompt() – Get short documentation for a config value

Synopsis

require_once 'PEAR/config.php';

string PEAR_Config::getPrompt ( string $key )

Description

Get the short documentation for a config value.

Parameter

string $key

config key

Return value

string short documentation string

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getLayers | PEAR Manual | PEAR_Config::getRegistry


PEAR_Config::getRegistry

PEAR_Config::getRegistry

PEAR_Config::getRegistry() – getRegistry

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

PEAR_Registry|false& PEAR_Config::getRegistry ( string $use = null )

Description

This package is not documented yet.

Parameter

string $use

This parameter determines which layer will be used to retrieve a registry based on the php_dir configuration variable for that layer. The default value of null will use the first layer that contains a valid php_dir, whereas if specified as user, system or ftp, it will attempt to return the registry for that layer.

On failure to retrieve a registry, it returns false

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getPrompt | PEAR Manual | PEAR_Config::getRemote


PEAR_Config::getRemote

PEAR_Config::getRemote

PEAR_Config::getRemote() – getRemote

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

PEAR_Remote& PEAR_Config::getRemote ( )

Description

This returns a PEAR_Remote based on the current PEAR_Config object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getRegistry | PEAR Manual | PEAR_Config::getREST


PEAR_Config::getREST

PEAR_Config::getREST

PEAR_Config::getREST() – getREST

Synopsis

require_once '/Config.php';

PEAR_REST& PEAR_Config::getREST ( string $version , array $options = array() )

Description

This package is not documented yet.

Parameter

string $version

This should be 1.0 in PEAR 1.4.0.

array $options

options for the PEAR_REST constructor

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getRemote | PEAR Manual | PEAR_Config::getSetValues


PEAR_Config::getSetValues

PEAR_Config::getSetValues

PEAR_Config::getSetValues() – Get the list of allowed set values for a config value

Synopsis

require_once 'PEAR/config.php';

array PEAR_Config::getSetValues ( string $key )

Description

Get the list of allowed set values for a config value. Returns NULL for config values that are not sets.

Parameter

string $key

config key

Return value

array - enumerated array of set values, or NULL if the config key is unknown or not a set

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getREST | PEAR Manual | PEAR_Config::getType


PEAR_Config::getType

PEAR_Config::getType

PEAR_Config::getType() – Get the type of a config value

Synopsis

require_once 'PEAR/config.php';

string PEAR_Config::getType ( string $key )

Description

Get the type of a config value.

Parameter

string $key

config key

Return value

string - type, one of "string", "integer", "file", "directory", "set" or "password".

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getSetValues | PEAR Manual | PEAR_Config::isDefined


PEAR_Config::isDefined

PEAR_Config::isDefined

PEAR_Config::isDefined() – Tells whether a key exists as config value

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::isDefined ( string $key )

Description

Tells whether a given key exists as a config value.

Parameter

string $key

config key

Return value

bool - whether $key exists in this object

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::getType | PEAR Manual | PEAR_Config::isDefinedLayer


PEAR_Config::isDefinedLayer

PEAR_Config::isDefinedLayer

PEAR_Config::isDefinedLayer() – Tells whether a config layer exists

Synopsis

require_once 'config.php';

bool PEAR_Config::isDefinedLayer ( string $layer )

Description

Tells whether a given config layer exists.

Parameter

string $layer

config layer

Return value

bool - whether $layer exists in this object

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::isDefined | PEAR Manual | PEAR_Config::mergeConfigFile


PEAR_Config::mergeConfigFile

PEAR_Config::mergeConfigFile

PEAR_Config::mergeConfigFile() – Merges data into a config layer from a file

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::mergeConfigFile ( string $file , bool $override = true , string $layer = 'user' )

Description

Merges data into a config layer from a file. Does the same thing as readConfigFile(), except it does not replace all existing values in the config layer.

Parameter

string $file

file to read from

boolean $override

whether to overwrite existing data

string $layer

config layer to insert data into ('user' or 'system' )

Return value

bool - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::isDefinedLayer | PEAR Manual | PEAR_Config::noRegistry


PEAR_Config::noRegistry

PEAR_Config::noRegistry

PEAR_Config::noRegistry() – noRegistry

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

void PEAR_Config::noRegistry ( )

Description

Use this method to disable automatic creation of PEAR_Registry objects when reading from a configuration file or changing php_dir configuration variable.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::mergeConfigFile | PEAR Manual | PEAR_Config::readConfigFile


PEAR_Config::readConfigFile

PEAR_Config::readConfigFile

PEAR_Config::readConfigFile() – Reads configuration data from a file

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::readConfigFile ( string $file = null , string $layer = 'user' )

Description

Reads configuration data from a file. All existing values in the config layer are discarded and replaced with data from the file.

Parameter

string $file

file to read from, if NULL or not specified, the last-used file for the same layer (second param) is used

string $layer

config layer to insert data into ('user' or 'system' )

Return value

bool - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::noRegistry | PEAR Manual | PEAR_Config::readFTPConfigFile


PEAR_Config::readFTPConfigFile

PEAR_Config::readFTPConfigFile

PEAR_Config::readFTPConfigFile() – readFTPConfigFile

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

true|PEAR_Error PEAR_Config::readFTPConfigFile ( string $path )

Description

Process a ftp configuration file by connecting to the server, retrieving the configuration file and parsing it normally. This function uses Net_FTP through the PEAR_FTP class.

Parameter

string $path

url to the remote config file, like ftp://www.example.com/pear/config.ini

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::readConfigFile | PEAR Manual | PEAR_Config::remove


PEAR_Config::remove

PEAR_Config::remove

PEAR_Config::remove() – Remove a config key from a config layer

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::remove ( string $key , string $layer = 'user' )

Description

Remove a config key from a specific config layer.

Parameter

string $key

config key

string $layer

config layer

Return value

bool - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::readFTPConfigFile | PEAR Manual | PEAR_Config::removeLayer


PEAR_Config::removeLayer

PEAR_Config::removeLayer

PEAR_Config::removeLayer() – Temporarily remove an entire config layer

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::removeLayer ( string $layer )

Description

Temporarily remove an entire config layer. USE WITH CARE!

Parameter

string $layer

config key

Return value

bool - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::remove | PEAR Manual | PEAR_Config::set


PEAR_Config::set

PEAR_Config::set

PEAR_Config::set() – Set config value in specific layer

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::set ( string $key , string $value , string $layer = 'user' )

Description

Set a config value in a specific layer (defaults to 'user' ). Enforces the types defined in the configuration_info array. An integer config variable will be cast to int, and a set config variable will be validated against its legal values.

Parameter

string $key

config key

string $value

config value

string $layer

config layer

Return value

bool - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::removeLayer | PEAR Manual | PEAR_Config::setChannels


PEAR_Config::setChannels

PEAR_Config::setChannels

PEAR_Config::setChannels() – Set the list of channels.

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

bool PEAR_Config::setChannels ( array $channels , bool $merge = false )

Description

This should be set via a call to PEAR_Registry::listChannels(). A call to this function sets up empty arrays for each channel in configurations.

Parameter

array $channels

a simple list of channel names.

boolean $merge

if true, then the list of channel is merged with the existing list, otherwise it replaces the existing list.

Return value

returns success of operation

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::set | PEAR Manual | PEAR_Config::setInstallRoot


PEAR_Config::setInstallRoot

PEAR_Config::setInstallRoot

PEAR_Config::setInstallRoot() – setInstallRoot

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

void PEAR_Config::setInstallRoot ( string|false $root )

Description

This is used to implement the --installroot option for installation. In earlier PEAR versions, this was implemented in PEAR_Installer::install(), but this makes it more difficult to track with the introduction of channels, and to satisfy better encapsulation, it has been moved to PEAR_Config.

Pass in a full path. On retrieving any directory configuration variable, the value will be prepended with the installroot specified in this method. For example, if php_dir is /usr/lib/php, and setInstallRoot() is used with /hoopla/boo, the value returned from get() would be /hoopla/boo/usr/lib/php. Use an empty string '' to reset an installroot.

Parameter

string|FALSE $root

installation directory to prepend to all _dir variables, or FALSE to disable

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::setChannels | PEAR Manual | PEAR_Config::setRegistry


PEAR_Config::setRegistry

PEAR_Config::setRegistry

PEAR_Config::setRegistry() – This is to allow customization like the use of installroot

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

bool PEAR_Config::setRegistry ( PEAR_Registry|false &$reg , string $layer = 'user' )

Description

Use this to override the automatic registry creation performed whenever the php_dir configuration variable is modified.

If noRegistry() has been called, this call will be ignored and FALSE returned. In addition, it is not possible to set the registry for the ftp layer.

Parameter

PEAR_Registry|false &$reg

The PEAR_Registry that will be used, or false to reset the registry.

string $layer

This must be either user or system

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::setInstallRoot | PEAR Manual | PEAR_Config::singleton


PEAR_Config::singleton

PEAR_Config::singleton

PEAR_Config::singleton() – Return a reference of a PEAR_Config object

Synopsis

require_once 'PEAR/config.php';

 object &PEAR_Config::singleton (
 string $user_file = ''
  , string $system_file = ''
)

Description

If you want to keep only one instance of this class in use, this method will give you a reference to the last created PEAR_Config object if one exists, or create a new object.

Parameter

string $user_file

file to read user-defined options from

string $system_file

file to read system-wide defaults from

Return value

object - an existing or new PEAR_Config instance

See

PEAR_Config::PEAR_Config()

Note

This function should be called statically.

Prev | PEAR_Config | Next
PEAR_Config::setRegistry | PEAR Manual | PEAR_Config::store


PEAR_Config::store

PEAR_Config::store

PEAR_Config::store() – Stores configuration data in a layer

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::store ( string $layer = 'user' )

Description

Stores configuration data in a layer.

Parameter

string $layer

config layer to store

Return value

bool - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::singleton | PEAR Manual | PEAR_Config::toDefault


PEAR_Config::toDefault

PEAR_Config::toDefault

PEAR_Config::toDefault() – Revert value of config key to the system-defined one

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::toDefault ( string $key )

Description

Unset the user-defined value of a config key, reverting the value to the system-defined one.

Parameter

string $key

config key

Return value

bool - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::store | PEAR Manual | PEAR_Config::validConfiguration


PEAR_Config::validConfiguration

PEAR_Config::validConfiguration

PEAR_Config::validConfiguration() – Determine whether any configuration files have been detected, and whether a registry object can be retrieved from this configuration.

Synopsis

require_once '/Config.php'; (since PEAR 1.4.0)

bool PEAR_Config::validConfiguration ( )

Description

This method can be used to ward off any real problems with the default configuration.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::toDefault | PEAR Manual | PEAR_Config::writeConfigFile


PEAR_Config::writeConfigFile

PEAR_Config::writeConfigFile

PEAR_Config::writeConfigFile() – Write data into config layer from file

Synopsis

require_once 'PEAR/config.php';

bool PEAR_Config::writeConfigFile ( string $file = null , bool $layer = 'user' )

Description

Writes data into a config layer from a file.

Parameter

string $file

file to read from

boolean $layer

whether to overwrite existing data

Return value

bool - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Config | Next
PEAR_Config::validConfiguration | PEAR Manual | PEAR_Dependency


PEAR_Dependency

PEAR_Dependency

Table of Contents
  • PEAR_Dependency::PEAR_Dependency -- constructor
  • PEAR_Dependency::callCheckMethod -- Maps the xml dependency definition
  • PEAR_Dependency::checkExtension -- Check Extension dependency
  • PEAR_Dependency::checkOS -- Check Operating system dependency
  • PEAR_Dependency::checkPackage -- check Package dependency
  • PEAR_Dependency::checkPHP -- Check PHP version
  • PEAR_Dependency::checkProgram -- Check external program
  • PEAR_Dependency::checkSAPI -- Check SAPI backend
  • PEAR_Dependency::checkZend -- Check Zend version

This class is deprecated by PEAR_Dependency2 in PEAR 1.4.0

Prev | PEAR Installer classes | Next
PEAR_Config::writeConfigFile | PEAR Manual | PEAR_Dependency::PEAR_Dependency


PEAR_Dependency::PEAR_Dependency

PEAR_Dependency::PEAR_Dependency

PEAR_Dependency::PEAR_Dependency() – constructor

Synopsis

require_once 'PEAR/Dependency.php';

void PEAR_Dependency::PEAR_Dependency ( object &$registry )

Description

Constructor

Parameter

object &$registry

a PEAR_Registry instance

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency | PEAR Manual | PEAR_Dependency::callCheckMethod


PEAR_Dependency::callCheckMethod

PEAR_Dependency::callCheckMethod

PEAR_Dependency::callCheckMethod() – Maps the xml dependency definition

Synopsis

require_once 'PEAR/Dependency.php';

void PEAR_Dependency::callCheckMethod ( mixed &$errmsg , array $opts )

Description

This method maps the xml dependency definition to the PEAR_Dependency one.

Parameter

mixed &$errmsg

this variable will contains an error message, if check fail

array $opts

An Array with all Dependency entries from the parsed XML package definition, ie:

<?php
$opts => Array
   (
       ['type'] => 'pkg',
       ['rel'] => 'ge',
       ['version'] => '3.4',
       ['name'] => 'HTML_Common'
    );
?>

Return value

mixed - FALSE if all dependencies could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependencies.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::PEAR_Dependency | PEAR Manual | PEAR_Dependency::checkExtension


PEAR_Dependency::checkExtension

PEAR_Dependency::checkExtension

PEAR_Dependency::checkExtension() – Check Extension dependency

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkExtension ( mixed &$errmsg , string $name , string $req = null , string $relation = 'has' )

Description

Extension dependencies check method

Parameter

mixed &$errmsg

this variable will contains an error message, if check fail

string $name

Name of the extension to test

string $req

Required extension version to compare with

string $relation

How to compare versions with eachother

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of an unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::callCheckMethod | PEAR Manual | PEAR_Dependency::checkOS


PEAR_Dependency::checkOS

PEAR_Dependency::checkOS

PEAR_Dependency::checkOS() – Check Operating system dependency

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkOS ( string &$errmsg , string $os )

Description

Operating system dependencies check method

Parameter

string &$errmsg

this variable will contains an error message, if check fail

string $os

Name of the operating system

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::checkExtension | PEAR Manual | PEAR_Dependency::checkPackage


PEAR_Dependency::checkPackage

PEAR_Dependency::checkPackage

PEAR_Dependency::checkPackage() – check Package dependency

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkPackage ( mixed &$errmsg , string $name , string $req = null , string $relation = 'has' )

Description

Package dependencies check method

Parameter

string &$errmsg

this variable will contains an error message, if check fail

string $name

Name of the package to test

string $req

Required package version to compare with

string $relation

How to compare versions with eachother

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::checkOS | PEAR Manual | PEAR_Dependency::checkPHP


PEAR_Dependency::checkPHP

PEAR_Dependency::checkPHP

PEAR_Dependency::checkPHP() – Check PHP version

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkPHP ( mixed &$errmsg , string $req , string $relation = 'ge' )

Description

PHP version check method

Parameter

mixed &$errmsg

this variable will contains an error message, if check fail

string $req

which version to compare

string $relation

how to compare the version

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::checkPackage | PEAR Manual | PEAR_Dependency::checkProgram


PEAR_Dependency::checkProgram

PEAR_Dependency::checkProgram

PEAR_Dependency::checkProgram() – Check external program

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkProgram ( mixed &$errmsg , string $program )

Description

External program check method. Looks for executable files in directories listed in the PATH environment variable.

Parameter

mixed &$errmsg

this variable will contains an error message, if check fail

string $program

which program to look for

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::checkPHP | PEAR Manual | PEAR_Dependency::checkSAPI


PEAR_Dependency::checkSAPI

PEAR_Dependency::checkSAPI

PEAR_Dependency::checkSAPI() – Check SAPI backend

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkSAPI ( mixed &$errmsg , string $name , string $req = null , string $relation = 'has' )

Description

SAPI backend check method. Version comparison is not yet available here.

Parameter

mixed &$errmsg

this variable will contains an error message, if check fail

string $name

name of SAPI backend

string $req

which version to compare (currently unused)

string $relation

how to compare versions (currently hardcoded to 'has')

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::checkProgram | PEAR Manual | PEAR_Dependency::checkZend


PEAR_Dependency::checkZend

PEAR_Dependency::checkZend

PEAR_Dependency::checkZend() – Check Zend version

Synopsis

require_once 'PEAR/Dependency.php';

mixed PEAR_Dependency::checkZend ( mixed &$errmsg , string $req , string ''}$relation = 'ge' )

Description

Zend version check method

Parameter

mixed &$errmsg

this variable will contains an error message, if check fail

string $req

which version to compare

string $relation

how to compare the version

Return value

mixed - FALSE if dependency could be resolved successfully(!); or an PEAR_DEPENDENCY_* constant in case of unresolved dependency.

Note

This function can not be called statically.

Prev | PEAR_Dependency | Next
PEAR_Dependency::checkSAPI | PEAR Manual | PEAR_Dependency2


PEAR_Dependency2

PEAR_Dependency2

Table of Contents
  • Class Summary PEAR_Dependency2 -- Dependency check for PEAR packages
  • constructor PEAR_Dependency2::PEAR_Dependency2 -- PEAR_Dependency2
  • PEAR_Dependency2::normalizeDep -- Convert a 1.0 dep into a 2.0 dep
  • PEAR_Dependency2::validateArchDependency -- Specify a complex dependency on an OS/processor/kernel version, Use OS for simple operating system dependency.
  • PEAR_Dependency2::validateDependency1 -- validate a package.xml 1.0 dependency
  • PEAR_Dependency2::validateExtensionDependency -- validate a dependency on a PHP extension
  • PEAR_Dependency2::validateOsDependency -- Specify a dependency on an OS. Use arch for detailed os/processor information
  • PEAR_Dependency2::validatePackage -- validatePackage
  • PEAR_Dependency2::validatePackageDependency -- validatePackageDependency
  • PEAR_Dependency2::validatePackageUninstall -- validatePackageUninstall
  • PEAR_Dependency2::validatePearinstallerDependency -- validatePearinstallerDependency
  • PEAR_Dependency2::validatePhpDependency -- validatePhpDependency
  • PEAR_Dependency2::validateSubpackageDependency -- validateSubpackageDependency
Prev | PEAR Installer classes | Next
PEAR_Dependency::checkZend | PEAR Manual | Class Summary PEAR_Dependency2


Class Summary PEAR_Dependency2

Class Summary PEAR_Dependency2

Class Summary PEAR_Dependency2 – Dependency check for PEAR packages

Dependency check for PEAR packages

This class handles both version 1.0 and 2.0 dependencies and supersedes PEAR_Dependency since PEAR 1.4.0

Class Trees for PEAR_Dependency2

  • PEAR_Dependency2

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2 | PEAR Manual | constructor PEAR_Dependency2::PEAR_Dependency2


constructor PEAR_Dependency2::PEAR_Dependency2

constructor PEAR_Dependency2::PEAR_Dependency2

constructor PEAR_Dependency2::PEAR_Dependency2() – PEAR_Dependency2

Synopsis

require_once '/Dependency2.php';

void constructor PEAR_Dependency2::PEAR_Dependency2 ( PEAR_Config &$config , array $installoptions , array $package , int $state = PEAR_VALIDATE_INSTALLING )

Description

This package is not documented yet.

Parameter

PEAR_Config &$config

Current configuration object.

array $installoptions

installation options

array $package

The current package. For installation dependencies, this is the package that contains dependencies. For uninstallation dependencies, this is the package that is going to be uninstalled.

format of PEAR_Registry::parsedPackageName()

integer $state

installation state (one of PEAR_VALIDATE_*)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
Class Summary PEAR_Dependency2 | PEAR Manual | PEAR_Dependency2::normalizeDep


PEAR_Dependency2::normalizeDep

PEAR_Dependency2::normalizeDep

PEAR_Dependency2::normalizeDep() – Convert a 1.0 dep into a 2.0 dep

Synopsis

require_once '/Dependency2.php';

array PEAR_Dependency2::normalizeDep ( array $dep )

Description

This converts an old-style package.xml 1.0 <dep> tag into the format used by package.xml 2.0. package.xml 2.0 can represent every kind of <dep> tag in its new syntax.

Parameter

array $dep

The package.xml 1.0 <dep> as parsed from xml.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
constructor PEAR_Dependency2::PEAR_Dependency2 | PEAR Manual | PEAR_Dependency2::validateArchDependency


PEAR_Dependency2::validateArchDependency

PEAR_Dependency2::validateArchDependency

PEAR_Dependency2::validateArchDependency() – Specify a complex dependency on an OS/processor/kernel version, Use OS for simple operating system dependency.

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validateArchDependency ( array $dep )

Description

This is the only dependency that accepts an ereg()able pattern. The pattern will be matched against the php_uname() output parsed by OS_Guess As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies (and the arch dependency is required). If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

array $dep

Contents of the dependency, as parsed from xml.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::normalizeDep | PEAR Manual | PEAR_Dependency2::validateDependency1


PEAR_Dependency2::validateDependency1

PEAR_Dependency2::validateDependency1

PEAR_Dependency2::validateDependency1() – validate a package.xml 1.0 dependency

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validateDependency1 ( array $dep , array $params = array() )

Description

Validate a package.xml version 1.0 <dep> dependency.

Parameter

array $dep

The contents of the <dep> tag as parsed from xml

array $params

The list of PEAR_Downloader_Package objects that will be installed.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validateArchDependency | PEAR Manual | PEAR_Dependency2::validateExtensionDependency


PEAR_Dependency2::validateExtensionDependency

PEAR_Dependency2::validateExtensionDependency

PEAR_Dependency2::validateExtensionDependency() – validate a dependency on a PHP extension

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validateExtensionDependency ( array $dep , bool $required = true )

Description

This validates against actual in-memory extensions, and will not attempt to locate extensions on disk. To do this, a dependency should be a package dependency with the <providesextension> tag.

As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies. If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

array $dep

dependency contents as parsed from xml

boolean $required

Whether this is a required or optional dependency

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validateDependency1 | PEAR Manual | PEAR_Dependency2::validateOsDependency


PEAR_Dependency2::validateOsDependency

PEAR_Dependency2::validateOsDependency

PEAR_Dependency2::validateOsDependency() – Specify a dependency on an OS. Use arch for detailed os/processor information

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validateOsDependency ( array $dep )

Description

There are two generic OS dependencies that will be the most common, unix and windows. Other options are linux, freebsd, darwin (OS X), sunos, irix, hpux, aix. As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies (and the OS dependency is required). If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

array $dep

Dependency contents as parsed from xml

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validateExtensionDependency | PEAR Manual | PEAR_Dependency2::validatePackage


PEAR_Dependency2::validatePackage

PEAR_Dependency2::validatePackage

PEAR_Dependency2::validatePackage() – validatePackage

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validatePackage ( array|PEAR_PackageFile_v2|PEAR_Downloader_Package $pkg , PEAR_Common &$dl )

Description

As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies (and the PEAR installer dependency is required). If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

array|PEAR_PackageFile_v2|PEAR_Downloader_Package $pkg

Either an array of format array('channel' => channelname, 'package' => package) or one of these objects.

PEAR_Common &$dl

Any object with a log() method that matches the signature of PEAR_Common

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validateOsDependency | PEAR Manual | PEAR_Dependency2::validatePackageDependency


PEAR_Dependency2::validatePackageDependency

PEAR_Dependency2::validatePackageDependency

PEAR_Dependency2::validatePackageDependency() – validatePackageDependency

Synopsis

require_once '/Dependency2.php';

array|true|PEAR_Error PEAR_Dependency2::validatePackageDependency ( array $dep , boolean $required , array $params , bool $depv1 = false )

Description

Validate a package-style dependency. Validation is performed in this sequence:

  1. If the dependency package provides an extension through the <providesextension> tag, then see if it passes the extension validation test first and return if so.

  2. If the list of packages to be installed contains a match for the dependency, use that to validate the dependency and return.

  3. If the dependency package is already installed, make sure the installed version passes the conditions.

  4. At this point, the dependency has failed. If the dependency is required, return a PEAR_Error containing the failure error message, otherwise return an array containing the error message.

Parameter

array $dep

dependency array as defined by package.xml 2.0

boolean $required

whether this is a required or optional dependency

array $params

array of PEAR_Downloader_Package objects representing packages to be downloaded that can be used to validate dependencies

boolean $depv1

if TRUE, then deps on pear.php.net that fail will also check against pecl.php.net packages to accommodate extensions that have moved to pecl.php.net from pear.php.net

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validatePackage | PEAR Manual | PEAR_Dependency2::validatePackageUninstall


PEAR_Dependency2::validatePackageUninstall

PEAR_Dependency2::validatePackageUninstall

PEAR_Dependency2::validatePackageUninstall() – validatePackageUninstall

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validatePackageUninstall ( PEAR_Installer &$dl )

Description

As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies (and the PEAR installer dependency is required). If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

PEAR_Installer &$dl

This method retrieves the list of packages to be uninstalled from the PEAR_Installer object, and makes sure no dependencies with existing packages would be broken if the current package were to be uninstalled.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validatePackageDependency | PEAR Manual | PEAR_Dependency2::validatePearinstallerDependency


PEAR_Dependency2::validatePearinstallerDependency

PEAR_Dependency2::validatePearinstallerDependency

PEAR_Dependency2::validatePearinstallerDependency() – validatePearinstallerDependency

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validatePearinstallerDependency ( array $dep )

Description

Validate the running PEAR version against the dependency. This dependency is designed to prevent PEAR versions incompatible with the current package.xml from attempting to install it. As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies (and the PEAR installer dependency is required). If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

mixed $dep

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validatePackageUninstall | PEAR Manual | PEAR_Dependency2::validatePhpDependency


PEAR_Dependency2::validatePhpDependency

PEAR_Dependency2::validatePhpDependency

PEAR_Dependency2::validatePhpDependency() – validatePhpDependency

Synopsis

require_once '/Dependency2.php';

true|PEAR_Error|array PEAR_Dependency2::validatePhpDependency ( array $dep )

Description

Validate the running PHP version against the dependency. The implicit assumption is that the installer's PHP version is the same as the final script's PHP version. As with all dependency validation, true is returned on success, PEAR_Error on failure for required dependencies (and the PHP dependency is required). If the soft, force or ignore-errors options are specified, an array containing the error message will be returned instead.

Parameter

array $dep

The dependency xml as represented in parsing

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validatePearinstallerDependency | PEAR Manual | PEAR_Dependency2::validateSubpackageDependency


PEAR_Dependency2::validateSubpackageDependency

PEAR_Dependency2::validateSubpackageDependency

PEAR_Dependency2::validateSubpackageDependency() – validateSubpackageDependency

Synopsis

require_once '/Dependency2.php';

array|true|PEAR_Error PEAR_Dependency2::validateSubpackageDependency ( array $dep , bool $required , array $params )

Description

Validate a subpackage-style dependency. This is identical to a package dependency from a validation perspective, and so documentation for validatePackageDependency() should be referenced for details.

Parameter

array $dep

dependency array as defined by package.xml 2.0

boolean $required

whether this is a required or optional dependency

array $params

array of PEAR_Downloader_Package objects representing packages to be downloaded that can be used to validate dependencies

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Dependency2 | Next
PEAR_Dependency2::validatePhpDependency | PEAR Manual | PEAR_DependencyDB


PEAR_DependencyDB

PEAR_DependencyDB

Table of Contents
  • Class Summary PEAR_DependencyDB -- Track dependency relationships between installed packages
  • PEAR_DependencyDB::assertDepsDB -- Create the dependency database, if it doesn't exist. Error if the database is newer than the code reading it.
  • PEAR_DependencyDB::dependsOn -- Determine whether $parent depends on $child, near or deep
  • PEAR_DependencyDB::getDependencies -- Get a list of dependencies of this installed package
  • PEAR_DependencyDB::getDependentPackageDependencies -- Get a list of the actual dependencies of installed packages that depend on a package.
  • PEAR_DependencyDB::getDependentPackages -- Get a list of installed packages that depend on this package
  • PEAR_DependencyDB::hasWriteAccess -- determines whether a dependency DB can be modified
  • PEAR_DependencyDB::installPackage -- Register dependencies of a package that is being installed or upgraded
  • PEAR_DependencyDB::rebuildDB -- Rebuild the dependency DB by reading registry entries.
  • PEAR_DependencyDB::setConfig -- Set up the registry/location of dependency DB
  • PEAR_DependencyDB::singleton -- Get a raw dependency database. Calls setConfig() and assertDepsDB()
  • PEAR_DependencyDB::uninstallPackage -- Remove dependencies of a package that is being uninstalled, or upgraded.
Prev | PEAR Installer classes | Next
PEAR_Dependency2::validateSubpackageDependency | PEAR Manual | Class Summary PEAR_DependencyDB


Class Summary PEAR_DependencyDB

Class Summary PEAR_DependencyDB

Class Summary PEAR_DependencyDB – Track dependency relationships between installed packages

Track dependency relationships between installed packages

This provides sophisticated dependency handling relationships between installed packages and downloaded to-be-installed packages.

Class Trees for PEAR_DependencyDB

  • PEAR_DependencyDB

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB | PEAR Manual | PEAR_DependencyDB::assertDepsDB


PEAR_DependencyDB::assertDepsDB

PEAR_DependencyDB::assertDepsDB

PEAR_DependencyDB::assertDepsDB() – Create the dependency database, if it doesn't exist. Error if the database is newer than the code reading it.

Synopsis

require_once '/DependencyDB.php';

void|PEAR_Error PEAR_DependencyDB::assertDepsDB ( )

Description

Assert that the dependency database exists, and attempt to create it if it doesn't.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
Class Summary PEAR_DependencyDB | PEAR Manual | PEAR_DependencyDB::dependsOn


PEAR_DependencyDB::dependsOn

PEAR_DependencyDB::dependsOn

PEAR_DependencyDB::dependsOn() – Determine whether $parent depends on $child, near or deep

Synopsis

require_once '/DependencyDB.php';

void PEAR_DependencyDB::dependsOn ( array|PEAR_PackageFile_v2|PEAR_PackageFile_v2 $parent , array|PEAR_PackageFile_v2|PEAR_PackageFile_v2 $child )

Description

This method is the central method of DependencyDB. Through the dependency database, it is possible to determine whether any two packages share a dependency relationship independent of how tightly bound the two packages are. In other words, if package A depends on package B depends on package C, this method can be used to determine that package A indirectly depends on package C.

Parameter

array|PEAR_PackageFile_v2|PEAR_PackageFile_v2 $parent

The parent package (as in package A in the example above)

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

array|PEAR_PackageFile_v2|PEAR_PackageFile_v2 $child

The child package (as in package B or package C in the example above)

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::assertDepsDB | PEAR Manual | PEAR_DependencyDB::getDependencies


PEAR_DependencyDB::getDependencies

PEAR_DependencyDB::getDependencies

PEAR_DependencyDB::getDependencies() – Get a list of dependencies of this installed package

Synopsis

require_once '/DependencyDB.php';

array|false PEAR_DependencyDB::getDependencies ( PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg )

Description

get an array of all immediate package dependencies of an installed package.

Parameter

PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::dependsOn | PEAR Manual | PEAR_DependencyDB::getDependentPackageDependencies


PEAR_DependencyDB::getDependentPackageDependencies

PEAR_DependencyDB::getDependentPackageDependencies

PEAR_DependencyDB::getDependentPackageDependencies() – Get a list of the actual dependencies of installed packages that depend on a package.

Synopsis

require_once '/DependencyDB.php';

array|false PEAR_DependencyDB::getDependentPackageDependencies ( PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg )

Description

This returns the complete tree of extended dependencies of a single installed package.

For instance, a real-world example. package SOAP depends on Mail_Mime, HTTP_Request, Net_URL, Net_DIME. package HTTP_Request depends on Net_URL, Net_Socket. This method will return an array similar to:

<?php
array(
'pear.php.net' =>
array(
'mail_mime' =>
array('name' => 'Mail_Mime',
'channel' => 'pear.php.net'),
'http_request' =>
array('name' => 'HTTP_Request',
'channel' => 'pear.php.net'),
'net_url' =>
array('name' => 'Net_URL',
'channel' => 'pear.php.net',
'min' => '1.0.12'),
'net_dime' =>
array('name' => 'Net_DIME',
'channel' => 'pear.php.net'),
'net_socket' =>
array('name' => 'Net_Socket',
'channel' => 'pear.php.net'),
),
);
?>

Note that this should not be relied upon for exact dependencies. In the example above, the returned dependency will be that of HTTP_Request upon Net_URL, which is stricter than SOAP's dependency upon Net_URL. In other words, if there are two similar dependencies, the last one encountered will be returned.

Parameter

PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::getDependencies | PEAR Manual | PEAR_DependencyDB::getDependentPackages


PEAR_DependencyDB::getDependentPackages

PEAR_DependencyDB::getDependentPackages

PEAR_DependencyDB::getDependentPackages() – Get a list of installed packages that depend on this package

Synopsis

require_once '/DependencyDB.php';

array|false PEAR_DependencyDB::getDependentPackages ( PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg )

Description

This is most useful at uninstall-time. A list of installed packages that depend upon the package can be used to prevent uninstallation, and to emit warnings for optional dependencies.

Parameter

PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::getDependentPackageDependencies | PEAR Manual | PEAR_DependencyDB::hasWriteAccess


PEAR_DependencyDB::hasWriteAccess

PEAR_DependencyDB::hasWriteAccess

PEAR_DependencyDB::hasWriteAccess() – determines whether a dependency DB can be modified

Synopsis

require_once '/DependencyDB.php';

bool PEAR_DependencyDB::hasWriteAccess ( )

Description

This method is used by the installer to prevent attempts to create/modify the dependency DB if the current user does not have write access to the registry. Without this method, simple read-only commands like pear info would not work.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::getDependentPackages | PEAR Manual | PEAR_DependencyDB::installPackage


PEAR_DependencyDB::installPackage

PEAR_DependencyDB::installPackage

PEAR_DependencyDB::installPackage() – Register dependencies of a package that is being installed or upgraded

Synopsis

require_once '/DependencyDB.php';

void PEAR_DependencyDB::installPackage ( PEAR_PackageFile_v2|PEAR_PackageFile_v2 &$package )

Description

This method is used by the registry when a package is installed or upgraded to register the package's dependencies in the dependency database.

Parameter

PEAR_PackageFile_v2|PEAR_PackageFile_v2 &$package

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::hasWriteAccess | PEAR Manual | PEAR_DependencyDB::rebuildDB


PEAR_DependencyDB::rebuildDB

PEAR_DependencyDB::rebuildDB

PEAR_DependencyDB::rebuildDB() – Rebuild the dependency DB by reading registry entries.

Synopsis

require_once '/DependencyDB.php';

true|PEAR_Error PEAR_DependencyDB::rebuildDB ( )

Description

This is used to create or re-create the dependency database by reading registry entries for each installed file to extract dependencies and save them in the dependency database.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::installPackage | PEAR Manual | PEAR_DependencyDB::setConfig


PEAR_DependencyDB::setConfig

PEAR_DependencyDB::setConfig

PEAR_DependencyDB::setConfig() – Set up the registry/location of dependency DB

Synopsis

require_once '/DependencyDB.php';

void PEAR_DependencyDB::setConfig ( PEAR_Config|false &$config , string|false $depdb = false )

Description

This crucial method is used to set the PEAR_Config object that should be used to retrieve both configuration information and a PEAR_Registry class for internal manipulation.

Parameter

PEAR_Config|FALSE &$config

string|FALSE $depdb

full path to the dependency database, or FALSE to use default

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::rebuildDB | PEAR Manual | PEAR_DependencyDB::singleton


PEAR_DependencyDB::singleton

PEAR_DependencyDB::singleton

PEAR_DependencyDB::singleton() – Get a raw dependency database. Calls setConfig() and assertDepsDB()

Synopsis

require_once '/DependencyDB.php';

PEAR_DependencyDB |PEAR_Error & PEAR_DependencyDB::singleton ( PEAR_Config &$config , string|false $depdb = false )

Description

Return a single dependency database based on the location of the database on disk. In other words, 1 dependency database is created for each registry location.

Parameter

PEAR_Config &$config

PEAR_Config object

string|$false; $depdb

full path to the dependency database, or FALSE to use default

Throws

throws no exceptions thrown

Note

This function should be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::setConfig | PEAR Manual | PEAR_DependencyDB::uninstallPackage


PEAR_DependencyDB::uninstallPackage

PEAR_DependencyDB::uninstallPackage

PEAR_DependencyDB::uninstallPackage() – Remove dependencies of a package that is being uninstalled, or upgraded.

Synopsis

require_once '/DependencyDB.php';

void PEAR_DependencyDB::uninstallPackage ( PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg )

Description

This method is used by the registry when a package is uninstalled or upgraded to remove the package's dependencies from the dependency database.

Upgraded packages first uninstall, then install

Parameter

PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg

This parameter, if an array, should be in format:

<?php
array(
'package' => 'packagename',
'channel' => 'channelname'
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_DependencyDB | Next
PEAR_DependencyDB::singleton | PEAR Manual | PEAR_Frontend


PEAR_Frontend

PEAR_Frontend

Table of Contents
  • Class Summary PEAR_Frontend -- Singleton-based frontend for PEAR user input/output
  • PEAR_Frontend::addTempFile -- This can be overridden to allow session-based temporary file management
  • PEAR_Frontend::isIncludeable -- isIncludeable
  • PEAR_Frontend::log -- log
  • PEAR_Frontend::setConfig -- setConfig
  • PEAR_Frontend::setFrontendClass -- setFrontendClass
  • PEAR_Frontend::singleton -- Retrieve the frontend object
Prev | PEAR Installer classes | Next
PEAR_DependencyDB::uninstallPackage | PEAR Manual | Class Summary PEAR_Frontend


Class Summary PEAR_Frontend

Class Summary PEAR_Frontend

Class Summary PEAR_Frontend – Singleton-based frontend for PEAR user input/output

Singleton-based frontend for PEAR user input/output (since PEAR 1.4.0)

This is also the base class for all frontends.

Class Trees for PEAR_Frontend

  • PEAR

    • PEAR_Frontend

Prev | PEAR_Frontend | Next
PEAR_Frontend | PEAR Manual | PEAR_Frontend::addTempFile


PEAR_Frontend::addTempFile

PEAR_Frontend::addTempFile

PEAR_Frontend::addTempFile() – This can be overridden to allow session-based temporary file management

Synopsis

require_once '/Frontend.php';

void PEAR_Frontend::addTempFile ( mixed $file )

Description

By default, all files are deleted at the end of a session. The web installer needs to be able to sustain a list over many sessions in order to support user interaction with install scripts

Parameter

mixed $file

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Frontend | Next
Class Summary PEAR_Frontend | PEAR Manual | PEAR_Frontend::isIncludeable


PEAR_Frontend::isIncludeable

PEAR_Frontend::isIncludeable

PEAR_Frontend::isIncludeable() – isIncludeable

Synopsis

require_once '/Frontend.php';

bool PEAR_Frontend::isIncludeable ( string $path )

Description

Simple utility class used to determine whether a file can be included via include_path

Parameter

string $path

relative or absolute include path

Throws

throws no exceptions thrown

Note

This function can be called statically.

Prev | PEAR_Frontend | Next
PEAR_Frontend::addTempFile | PEAR Manual | PEAR_Frontend::log


PEAR_Frontend::log

PEAR_Frontend::log

PEAR_Frontend::log() – log

Synopsis

require_once '/Frontend.php';

void PEAR_Frontend::log ( int $level , string $msg , bool $append_crlf = true )

Description

Log a message in a frontend-specific way. By default, nothing is done.

Parameter

integer $level

string $msg

boolean $append_crlf

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Frontend | Next
PEAR_Frontend::isIncludeable | PEAR Manual | PEAR_Frontend::setConfig


PEAR_Frontend::setConfig

PEAR_Frontend::setConfig

PEAR_Frontend::setConfig() – setConfig

Synopsis

require_once '/Frontend.php';

void PEAR_Frontend::setConfig ( PEAR_Config &$config )

Description

Set the configuration object used by this frontend.

Parameter

PEAR_Config &$config

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Frontend | Next
PEAR_Frontend::log | PEAR Manual | PEAR_Frontend::setFrontendClass


PEAR_Frontend::setFrontendClass

PEAR_Frontend::setFrontendClass

PEAR_Frontend::setFrontendClass() – setFrontendClass

Synopsis

require_once '/Frontend.php';

void& PEAR_Frontend::setFrontendClass ( string $uiclass )

Description

Set the kind of frontend that should be retrieved from the singleton() method. If the class does not exist, the method changes all underscores (_) into directory separators (like PEAR_Frontend_CLI to PEAR/Frontend/CLI) and appends .php and then checks to see if the file can be included. If the class does exist after all of this, a simple check is made to see if the userConfirm() method exists, and then a new frontend object is returned. Any failure causes a PEAR_Error to be returned.

Parameter

string $uiclass

the full classname (like PEAR_Frontend_Web)

Throws

throws PEAR_Error on any problem

Note

This function can not be called statically.

Prev | PEAR_Frontend | Next
PEAR_Frontend::setConfig | PEAR Manual | PEAR_Frontend::singleton


PEAR_Frontend::singleton

PEAR_Frontend::singleton

PEAR_Frontend::singleton() – Retrieve the frontend object

Synopsis

require_once '/Frontend.php';

PEAR_Frontend_CLI|PEAR_Frontend_Web|PEAR_Frontend_Gtk& PEAR_Frontend::singleton ( mixed $type = null )

Description

Get a single unique copy of the current PEAR frontend object.

Parameter

string|NULL $type

if being called for the first time, the user can specify the kind of frontend to return. Otherwise, this parameter is ignored, and the existing single frontend is returned.

Throws

throws no exceptions thrown

Note

This function can be called statically.

Prev | PEAR_Frontend | Next
PEAR_Frontend::setFrontendClass | PEAR Manual | PEAR_Installer


PEAR_Installer

PEAR_Installer

Table of Contents
  • PEAR_Installer::PEAR_Installer -- constructor
  • PEAR_Installer::install -- Installs package files

Administration class used to install PEAR packages and maintain the installed package database.

Class Trees for PEAR_Installer()

  • PEAR_Common

    • PEAR_Installer

Prev | PEAR Installer classes | Next
PEAR_Frontend::singleton | PEAR Manual | PEAR_Installer::PEAR_Installer


PEAR_Installer::PEAR_Installer

PEAR_Installer::PEAR_Installer

PEAR_Installer::PEAR_Installer() – constructor

Synopsis

require_once 'PEAR/Installer.php';

void constructor PEAR_Installer::constructor PEAR_Installer ( object &$ui )

Description

PEAR_Installer constructor.

Parameter

object &$ui

user interface object (instance of PEAR_Frontend_*)

Note

This function can not be called statically.

Prev | PEAR_Installer | Next
PEAR_Installer | PEAR Manual | PEAR_Installer::install


PEAR_Installer::install

PEAR_Installer::install

PEAR_Installer::install() – Installs package files

Synopsis

require_once 'PEAR/Installer.php';

array PEAR_Installer::install ( string $pkgfile , array $options = array() )

Description

Installs the files within the package file specified.

Parameter

string $pkgfile

path to the package file

array $options

installating options, to enable an option use the option name as array key and TRUE or 1 as value.

  • $options['force'] = 1 - force installation

  • $options['register-only'] = 1 - update registry but don't install files

  • $options['upgrade'] = 1 - upgrade existing install

  • $options['soft'] = 1 - fail silently

Return value

array package info if successful

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Installer | Next
PEAR_Installer::PEAR_Installer | PEAR Manual | PEAR


PEAR

PEAR

Table of Contents
  • Class Summary PEAR_PackageFile -- Abstraction for the package.xml package description file
  • constructor PEAR_PackageFile::PEAR_PackageFile -- PEAR_PackageFile
  • PEAR_PackageFile::factory -- factory
  • PEAR_PackageFile::fromAnyFile -- Returns package information from different sources
  • PEAR_PackageFile::fromArray -- Return a packagefile object from its toArray() method
  • PEAR_PackageFile::fromPackageFile -- Returns information about a package file. Expects the name of a package.xml file as input.
  • PEAR_PackageFile::fromTgzFile -- fromTgzFile
  • PEAR_PackageFile::fromXmlString -- fromXmlString
  • PEAR_PackageFile::parserFactory -- parserFactory
  • PEAR_PackageFile::rawReturn -- Turn off validation - return a parsed package.xml without checking it for errors
  • PEAR_PackageFile::setLogger -- setLogger
  • Package PEAR Constants -- Constants defined in and used by PEAR
Prev | PEAR Installer classes | Next
PEAR_Installer::install | PEAR Manual | Class Summary PEAR_PackageFile


Class Summary PEAR_PackageFile

Class Summary PEAR_PackageFile

Class Summary PEAR_PackageFile – Abstraction for the package.xml package description file

Abstraction for the package.xml package description file

Parse and retrieve a package.xml object from various sources.

Class Trees for PEAR_PackageFile

  • PEAR_PackageFile

Prev | PEAR | Next
PEAR | PEAR Manual | constructor PEAR_PackageFile::PEAR_PackageFile


constructor PEAR_PackageFile::PEAR_PackageFile

constructor PEAR_PackageFile::PEAR_PackageFile

constructor PEAR_PackageFile::PEAR_PackageFile() – PEAR_PackageFile

Synopsis

require_once '/PackageFile.php';

void constructor PEAR_PackageFile::PEAR_PackageFile ( PEAR_Config &$config , bool $debug = false , string $tmpdir = false )

Description

Prepare for parsing one or more package.xml files.

Parameter

PEAR_Config &$config

The configuration to use for parsing and channel registry (needed for channel-specific validators).

boolean $debug

The debug logging level (this is usually the value of the verbose configuration variable).

string $tmpdir

The temporary directory to extract files in. By default, a new temporary directory is created using System::mktemp().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
Class Summary PEAR_PackageFile | PEAR Manual | PEAR_PackageFile::factory


PEAR_PackageFile::factory

PEAR_PackageFile::factory

PEAR_PackageFile::factory() – factory

Synopsis

require_once '/PackageFile.php';

PEAR_PackageFile_v1|PEAR_PackageFile_v2& PEAR_PackageFile::factory ( string $version )

Description

Retrieve a raw PEAR_PackageFile_vX object where X is either 1 or 2.

Parameter

string $version

The package.xml version represented (1 or 2)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
constructor PEAR_PackageFile::PEAR_PackageFile | PEAR Manual | PEAR_PackageFile::fromAnyFile


PEAR_PackageFile::fromAnyFile

PEAR_PackageFile::fromAnyFile

PEAR_PackageFile::fromAnyFile() – Returns package information from different sources

Synopsis

require_once '/PackageFile.php';

string& PEAR_PackageFile::fromAnyFile ( string $info , int $state )

Description

This method is able to extract information about a package from a .tgz archive or from a XML package definition file.

Parameter

string $info

path to a file containing a package.xml (package archive or package.xml)

integer $state

package state (one of PEAR_VALIDATE_* constants)

Throws

throws no exceptions thrown

Note

This function should be called statically.

Prev | PEAR | Next
PEAR_PackageFile::factory | PEAR Manual | PEAR_PackageFile::fromArray


PEAR_PackageFile::fromArray

PEAR_PackageFile::fromArray

PEAR_PackageFile::fromArray() – Return a packagefile object from its toArray() method

Synopsis

require_once '/PackageFile.php';

PEAR_PackageFile_v1|PEAR_PackageFile_v2& PEAR_PackageFile::fromArray ( array $arr )

Description

WARNING: no validation is performed, the array is assumed to be valid, always parse from xml if you want validation.

Parameter

array $arr

Contents of a previously parsed package.xml object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_PackageFile::fromAnyFile | PEAR Manual | PEAR_PackageFile::fromPackageFile


PEAR_PackageFile::fromPackageFile

PEAR_PackageFile::fromPackageFile

PEAR_PackageFile::fromPackageFile() – Returns information about a package file. Expects the name of a package.xml file as input.

Synopsis

require_once '/PackageFile.php';

array& PEAR_PackageFile::fromPackageFile ( string $descfile , int $state , string|false $archive = false )

Description

parse and return a package.xml object from a package.xml file, or a PEAR_Error object upon error.

Parameter

string $descfile

name of package.xml file

integer $state

package state (one of PEAR_VALIDATE_* constants)

string|FALSE $archive

full path to the full package .tgz file containing the package.xml, or false for none.

Return value

returns array with package information

Throws

throws no exceptions thrown

Note

This function should be called statically.

Prev | PEAR | Next
PEAR_PackageFile::fromArray | PEAR Manual | PEAR_PackageFile::fromTgzFile


PEAR_PackageFile::fromTgzFile

PEAR_PackageFile::fromTgzFile

PEAR_PackageFile::fromTgzFile() – fromTgzFile

Synopsis

require_once '/PackageFile.php';

PEAR_PackageFile_v1|PEAR_PackageFile_v2|PEAR_Error& PEAR_PackageFile::fromTgzFile ( string $file , int $state )

Description

parse and return a package.xml object from a packaged archive, or a PEAR_Error object upon error.

Parameter

string $file

name of packaged .tgz or .tar to extract and parse package.xml from

integer $state

package state (one of PEAR_VALIDATE_* constants)

Return value

returns success of parsing

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_PackageFile::fromPackageFile | PEAR Manual | PEAR_PackageFile::fromXmlString


PEAR_PackageFile::fromXmlString

PEAR_PackageFile::fromXmlString

PEAR_PackageFile::fromXmlString() – fromXmlString

Synopsis

require_once '/PackageFile.php';

PEAR_PackageFile_v1|PEAR_PackageFile_v2|PEAR_Error& PEAR_PackageFile::fromXmlString ( string $data , int $state , string $file , string|false $archive = false )

Description

parse and return a package.xml object, or a PEAR_Error object upon error.

Parameter

string $data

contents of package.xml file

integer $state

package state (one of PEAR_VALIDATE_* constants)

string $file

full path to the package.xml file (and the files it references)

string|FALSE $archive

full path to the full package .tgz file containing the package.xml, or false for none.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_PackageFile::fromTgzFile | PEAR Manual | PEAR_PackageFile::parserFactory


PEAR_PackageFile::parserFactory

PEAR_PackageFile::parserFactory

PEAR_PackageFile::parserFactory() – parserFactory

Synopsis

require_once '/PackageFile.php';

PEAR_PackageFile_Parser_v1|PEAR_PackageFile_Parser_v2& PEAR_PackageFile::parserFactory ( string $version )

Description

Return a package.xml parsing object appropriate for the selected package.xml version.

Parameter

string $version

The package.xml version represented (1 or 2)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_PackageFile::fromXmlString | PEAR Manual | PEAR_PackageFile::rawReturn


PEAR_PackageFile::rawReturn

PEAR_PackageFile::rawReturn

PEAR_PackageFile::rawReturn() – Turn off validation - return a parsed package.xml without checking it for errors

Synopsis

require_once '/PackageFile.php';

void PEAR_PackageFile::rawReturn ( )

Description

This is used by the package-validate command

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_PackageFile::parserFactory | PEAR Manual | PEAR_PackageFile::setLogger


PEAR_PackageFile::setLogger

PEAR_PackageFile::setLogger

PEAR_PackageFile::setLogger() – setLogger

Synopsis

require_once '/PackageFile.php';

void PEAR_PackageFile::setLogger ( PEAR_Common &$l )

Description

set a logging class that matches the signature of PEAR_Common's log() method.

Parameter

PEAR_Common &$l

The PEAR_Common object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_PackageFile::rawReturn | PEAR Manual | Package PEAR Constants


Package PEAR Constants

Package PEAR Constants

Package PEAR Constants – Constants defined in and used by PEAR

All Constants

Constants defined in PackageFile.php

Constants defined in PackageFile.php
Name | Value | Line Number
PEAR_PACKAGEFILE_ERROR_INVALID_PACKAGEVERSION | 2 | 35
PEAR_PACKAGEFILE_ERROR_NO_PACKAGEVERSION | 1 | 30
Prev | PEAR | Next
PEAR_PackageFile::setLogger | PEAR Manual | PEAR_Packager


PEAR_Packager

PEAR_Packager

Table of Contents
  • PEAR_Packager::PEAR_Packager -- constructor
  • PEAR_Packager::package -- Create Package archive

Administration class used to make a PEAR release tarball.

Class Trees for PEAR_Packager

  • PEAR_Common

    • PEAR_Packager

Prev | PEAR Installer classes | Next
Package PEAR Constants | PEAR Manual | PEAR_Packager::PEAR_Packager


PEAR_Packager::PEAR_Packager

PEAR_Packager::PEAR_Packager

PEAR_Packager::PEAR_Packager() – constructor

Synopsis

require_once 'PEAR/Packager.php';

void PEAR_Packager:: PEAR_Packager ( ( void )

Description

constructor

Note

This function can be called statically.

Prev | PEAR_Packager | Next
PEAR_Packager | PEAR Manual | PEAR_Packager::package


PEAR_Packager::package

PEAR_Packager::package

PEAR_Packager::package() – Create Package archive

Synopsis

require_once 'PEAR/Packager.php';

string PEAR_Packager::package ( string $pkgfile = null , boolean $compress = true )

Description

Creates a Package archive from package definition file and package files

Parameter

string $pkgfile

path to package definition file

boolean $compress

if TRUE package archive will be compessed using gzip

Return value

string - name of the created package archive

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Packager | Next
PEAR_Packager::PEAR_Packager | PEAR Manual | PEAR_Registry


PEAR_Registry

PEAR_Registry

Table of Contents
  • PEAR_Registry::PEAR_Registry -- constructor
  • PEAR_Registry::addPackage -- Registers a package to the registry
  • PEAR_Registry::checkFileMap -- Test whether a file belongs to a package
  • PEAR_Registry::deletePackage -- Remove Package from registry
  • PEAR_Registry::listPackages -- List all registered Packages
  • PEAR_Registry::packageExists -- Check for Package
  • PEAR_Registry::packageInfo -- Get Package information
  • PEAR_Registry::rebuildDepsFile -- Rebuild dependencies file
  • PEAR_Registry::rebuildFileMap -- Rebuild file map
  • PEAR_Registry::removePackageDep -- Remove dependency information of a Package
  • PEAR_Registry::setPackageDep -- Update or insert dependencies of a Package
  • PEAR_Registry::updatePackage -- Update Package information

Administration class used to maintain the installed package database.

Class Trees for PEAR_Registry

  • PEAR

    • PEAR_Registry

Prev | PEAR Installer classes | Next
PEAR_Packager::package | PEAR Manual | PEAR_Registry::PEAR_Registry


PEAR_Registry::PEAR_Registry

PEAR_Registry::PEAR_Registry

PEAR_Registry::PEAR_Registry() – constructor

Synopsis

require_once 'PEAR/Registry.php';

void PEAR_Registry::PEAR_Registry ( string $pear_install_dir = PEAR_INSTALL_DIR )

Description

constructor

Parameter

string $pear_install_dir

PEAR install directory (for .php files)

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry | PEAR Manual | PEAR_Registry::addPackage


PEAR_Registry::addPackage

PEAR_Registry::addPackage

PEAR_Registry::addPackage() – Registers a package to the registry

Synopsis

require_once 'PEAR/Registry.php';

boolean PEAR_Registry::addPackage ( string $package , array $info )

Description

Adds a Package entry to the registry

Parameter

string $package

Package name

array $info

additional information for the package entry

Return value

boolean - FALSE if Package is already registered;

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::PEAR_Registry | PEAR Manual | PEAR_Registry::checkFileMap


PEAR_Registry::checkFileMap

PEAR_Registry::checkFileMap

PEAR_Registry::checkFileMap() – Test whether a file belongs to a package

Synopsis

require_once 'PEAR/Registry.php';

string PEAR_Registry::checkFileMap ( string $path )

Description

Test whether a file belongs to a package.

Parameter

string $path

file path, absolute or relative to the pear install dir

Return value

string - name of the package the file belongs to, or an empty string if the file does not belong to an installed package

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::addPackage | PEAR Manual | PEAR_Registry::deletePackage


PEAR_Registry::deletePackage

PEAR_Registry::deletePackage

PEAR_Registry::deletePackage() – Remove Package from registry

Synopsis

require_once 'PEAR/Registry.php';

boolean PEAR_Registry::deletePackage ( string $package )

Description

Removes a Package entry from the registry.

Parameter

string $package

Package name

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::checkFileMap | PEAR Manual | PEAR_Registry::listPackages


PEAR_Registry::listPackages

PEAR_Registry::listPackages

PEAR_Registry::listPackages() – List all registered Packages

Synopsis

require_once 'PEAR/Registry.php';

array PEAR_Registry::listPackages ( ( void )

Description

List all Packages registered in the registry.

Return value

array - list of package names

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::deletePackage | PEAR Manual | PEAR_Registry::packageExists


PEAR_Registry::packageExists

PEAR_Registry::packageExists

PEAR_Registry::packageExists() – Check for Package

Synopsis

require_once 'PEAR/Registry.php';

boolean PEAR_Registry::packageExists ( string $package )

Description

Checks wether a Package is registered in the registry or not.

Parameter

string $package

Package name

Return value

boolean - TRUE if package is registered

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::listPackages | PEAR Manual | PEAR_Registry::packageInfo


PEAR_Registry::packageInfo

PEAR_Registry::packageInfo

PEAR_Registry::packageInfo() – Get Package information

Synopsis

require_once 'PEAR/Registry.php';

mixed PEAR_Registry::packageInfo ( string $package = null , string $key = null )

Description

Returns (specific) information stored in the registry about a Package.

Parameter

string $package

Package name

string $key

the name of a specific information to get

Return value

mixed - an array with all information, or a key specific information, if $key was used; NULL if Package or specific information does not exist

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::packageExists | PEAR Manual | PEAR_Registry::rebuildDepsFile


PEAR_Registry::rebuildDepsFile

PEAR_Registry::rebuildDepsFile

PEAR_Registry::rebuildDepsFile() – Rebuild dependencies file

Synopsis

require_once 'PEAR/Registry.php';

void PEAR_Registry::rebuildDepsFile ( ( void )

Description

Rebuilds the dependencies file of the registry. Use this function if had trouble while installing Packages or a damaged registry.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::packageInfo | PEAR Manual | PEAR_Registry::rebuildFileMap


PEAR_Registry::rebuildFileMap

PEAR_Registry::rebuildFileMap

PEAR_Registry::rebuildFileMap() – Rebuild file map

Synopsis

require_once 'PEAR/Registry.php';

void PEAR_Registry::rebuildFileMap ( ( void )

Description

Rebuilds the registry filemap. Use this function if had trouble while installing Packages or a damaged registry.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::rebuildDepsFile | PEAR Manual | PEAR_Registry::removePackageDep


PEAR_Registry::removePackageDep

PEAR_Registry::removePackageDep

PEAR_Registry::removePackageDep() – Remove dependency information of a Package

Synopsis

require_once 'PEAR/Registry.php';

mixed PEAR_Registry::removePackageDep ( string $package )

Description

Removes the dependency information of a Package from the registry.

Parameter

string $package

Package name

Return value

mixed - TRUE if successful; or an array with a list of Packages depending on this Package

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::rebuildFileMap | PEAR Manual | PEAR_Registry::setPackageDep


PEAR_Registry::setPackageDep

PEAR_Registry::setPackageDep

PEAR_Registry::setPackageDep() – Update or insert dependencies of a Package

Synopsis

require_once 'PEAR/Registry.php';

mixed PEAR_Registry::setPackageDep ( string $package , string $new_version , array $rel_deps = array() )

Description

Update or insert a the dependencies of a package, prechecking that the package won't break any dependency in the process. (Dependencies of type 'pkg' only.

Parameter

string $package

Package name

string $new_version

Version of the Package

array $rel_deps

Package dependencies

Return value

mixed - TRUE if no dependencies found; or array with names of missing or outdated Packages

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::removePackageDep | PEAR Manual | PEAR_Registry::updatePackage


PEAR_Registry::updatePackage

PEAR_Registry::updatePackage

PEAR_Registry::updatePackage() – Update Package information

Synopsis

require_once 'PEAR/Registry.php';

boolean PEAR_Registry::updatePackage ( string $package , array $info , bool $merge = true )

Description

Updates the existing information of a Package in the registry.

Parameter

string $package

Package name

array $info

information to update

mixed $merge

if FALSE the old informations will be deleted completly an replaced with the new; if TRUE update only - unchanged values will remain.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Registry | Next
PEAR_Registry::setPackageDep | PEAR Manual | PEAR_Remote


PEAR_Remote

PEAR_Remote

Table of Contents
  • PEAR_Remote::PEAR_Remote -- constructor
  • PEAR_Remote::call -- Execute a server function

This is a class for doing remote operations against a PEAR Package Server.

Class Trees for PEAR_Remote()

  • PEAR

    • PEAR_Remote

Prev | PEAR Installer classes | Next
PEAR_Registry::updatePackage | PEAR Manual | PEAR_Remote::PEAR_Remote


PEAR_Remote::PEAR_Remote

PEAR_Remote::PEAR_Remote

PEAR_Remote::PEAR_Remote() – constructor

Synopsis

require_once 'PEAR/Remote.php';

void PEAR_Remote::PEAR_Remote ( object &$config )

Description

constructor

Parameter

object &$config

an instance of PEAR_Config

Note

This function can not be called statically.

Prev | PEAR_Remote | Next
PEAR_Remote | PEAR Manual | PEAR_Remote::call


PEAR_Remote::call

PEAR_Remote::call

PEAR_Remote::call() – Execute a server function

Synopsis

require_once 'PEAR/Remote.php';

mixed PEAR_Remote::call ( string $method , mixed $args,... )

Description

Sends a remote procedure call to a package server and returns the result.

Parameter

string $method

Name of the server method

mixed $args,...

server method specific parameters

Return value

mixed - result of the executed server method

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | PEAR_Remote | Next
PEAR_Remote::PEAR_Remote | PEAR Manual | PEAR_REST


PEAR_REST

PEAR_REST

Table of Contents
  • Class Summary PEAR_REST -- Intelligently retrieve data, following hyperlinks if necessary, and re-directing
  • constructor PEAR_REST::PEAR_REST -- PEAR_REST
  • PEAR_REST::downloadHttp -- Efficiently Download a file through HTTP. Returns downloaded file as a string in-memory This is best used for small files
  • PEAR_REST::getCache -- getCache
  • PEAR_REST::getCacheId -- getCacheId
  • PEAR_REST::retrieveCacheFirst -- Retrieve REST data, but always retrieve the local cache if it is available.
  • PEAR_REST::retrieveData -- Retrieve a remote REST resource
  • PEAR_REST::saveCache -- Save the value retrieved from a remote REST resource in the local cache.
  • PEAR_REST::useLocalCache -- useLocalCache
Prev | PEAR Installer classes | Next
PEAR_Remote::call | PEAR Manual | Class Summary PEAR_REST


Class Summary PEAR_REST

Class Summary PEAR_REST

Class Summary PEAR_REST – Intelligently retrieve data, following hyperlinks if necessary, and re-directing

Intelligently retrieve data, following hyperlinks if necessary, and re-directing (since PEAR 1.4.0)

as well

Class Trees for PEAR_REST

  • PEAR_REST

Prev | PEAR_REST | Next
PEAR_REST | PEAR Manual | constructor PEAR_REST::PEAR_REST


constructor PEAR_REST::PEAR_REST

constructor PEAR_REST::PEAR_REST

constructor PEAR_REST::PEAR_REST() – PEAR_REST

Synopsis

require_once '/REST.php';

void constructor PEAR_REST::PEAR_REST ( PEAR_Config &$config , array $options = array() )

Description

This package is not documented yet.

Parameter

PEAR_Config &$config

Configuration object

array $options

options passed to commands like install/download. The only option that affects PEAR_REST is offline, which causes all retrievals to look in the local cache without trying to retrieve a remote resource.

Note

This function can not be called statically.

Prev | PEAR_REST | Next
Class Summary PEAR_REST | PEAR Manual | PEAR_REST::downloadHttp


PEAR_REST::downloadHttp

PEAR_REST::downloadHttp

PEAR_REST::downloadHttp() – Efficiently Download a file through HTTP. Returns downloaded file as a string in-memory This is best used for small files

Synopsis

require_once '/REST.php';

string|array PEAR_REST::downloadHttp ( string $url , false|string|array $lastmodified = null , false|array $accept = false , string $save_dir )

Description

If an HTTP proxy has been configured (http_proxy PEAR_Config setting), the proxy will be used.

Parameter

string $url

the URL to download

FALSE|string|array $lastmodified

header values to check against for caching use FALSE to return the header values from this download

FALSE|array $accept

Accept headers to send. This should be a list of MIME types like text/xml, frog/legs, etc.

string $save_dir

directory to save file in

Return value

returns Returns the contents of the downloaded file or a PEAR error on failure. If the error is caused by socket-related errors, the error object will have the fsockopen error code available through getCode(). If caching is requested, then return the header values.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_REST | Next
constructor PEAR_REST::PEAR_REST | PEAR Manual | PEAR_REST::getCache


PEAR_REST::getCache

PEAR_REST::getCache

PEAR_REST::getCache() – getCache

Synopsis

require_once '/REST.php';

mixed|false PEAR_REST::getCache ( string $url )

Description

Retrieve the cache contents for a remote resource, or a PEAR_Error if the resource was not cached.

Parameter

string $url

REST resource URL

Throws

throws PEAR_Error object returned on error.

Note

This function can not be called statically.

Prev | PEAR_REST | Next
PEAR_REST::downloadHttp | PEAR Manual | PEAR_REST::getCacheId


PEAR_REST::getCacheId

PEAR_REST::getCacheId

PEAR_REST::getCacheId() – getCacheId

Synopsis

require_once '/REST.php';

array|false PEAR_REST::getCacheId ( string $url )

Description

Retrieve the HTTP caching information for a REST resource, or FALSE if no cache is found.

Parameter

string $url

REST resource URL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_REST | Next
PEAR_REST::getCache | PEAR Manual | PEAR_REST::retrieveCacheFirst


PEAR_REST::retrieveCacheFirst

PEAR_REST::retrieveCacheFirst

PEAR_REST::retrieveCacheFirst() – Retrieve REST data, but always retrieve the local cache if it is available.

Synopsis

require_once '/REST.php';

string|array PEAR_REST::retrieveCacheFirst ( string $url , array|false $accept = false , boolean $forcestring = false )

Description

This is useful for elements that should never change, such as information on a particular release

Parameter

string $url

full URL to this resource

array|FALSE $accept

contents of the accept-encoding header

boolean $forcestring

if TRUE, xml will be returned as a string, otherwise, xml will be parsed using PEAR_XMLParser

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_REST | Next
PEAR_REST::getCacheId | PEAR Manual | PEAR_REST::retrieveData


PEAR_REST::retrieveData

PEAR_REST::retrieveData

PEAR_REST::retrieveData() – Retrieve a remote REST resource

Synopsis

require_once '/REST.php';

string|array PEAR_REST::retrieveData ( string $url , array|false $accept = false , bool $forcestring = false )

Description

retrieve the contents of a remote resource.

Parameter

string $url

full URL to this resource

array|false $accept

contents of the accept-encoding header

boolean $forcestring

if TRUE, xml will be returned as a string, otherwise, xml will be parsed using PEAR_XMLParser

Throws

throws PEAR_Error objects are returned on error.

Note

This function can not be called statically.

Prev | PEAR_REST | Next
PEAR_REST::retrieveCacheFirst | PEAR Manual | PEAR_REST::saveCache


PEAR_REST::saveCache

PEAR_REST::saveCache

PEAR_REST::saveCache() – Save the value retrieved from a remote REST resource in the local cache.

Synopsis

require_once '/REST.php';

void PEAR_REST::saveCache ( string $url , mixed $contents , array $lastmodified , bool $nochange = false )

Description

Use this to save a resource after retrieving. Since the cache_ttl configuration variable is used in determining when to check the remote server, and HTTP caching is used as well, it is possible for this scenario to arise:

  1. retrieve REST resource

  2. cache the resource

  3. a few days later, retrieve the REST resource again

  4. HTTP caching returns 304 not modified

In this situation, it doesn't make much sense to save the resource contents redundantly. Instead, the last access time can be saved in the cache id by passing true into the last parameter.

Parameter

string $url

The REST resource's URL

mixed $contents

Contents retrieved from the REST resource (ignored if the last parameter is true)

array $lastmodified

The ETag and LastModified headers retrieved from the remote server, used for HTTP caching.

mixed $nochange

If false, the cache is saved normally. If true, only the $lastmodified parameter is saved in the cache id file, registering an HTTP cache hit.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_REST | Next
PEAR_REST::retrieveData | PEAR Manual | PEAR_REST::useLocalCache


PEAR_REST::useLocalCache

PEAR_REST::useLocalCache

PEAR_REST::useLocalCache() – useLocalCache

Synopsis

require_once '/REST.php';

mixed PEAR_REST::useLocalCache ( bool $url )

Description

Retrieve the contents of the local cached copy of a remote URL. FALSE is returned if there are any problems, under the assumption that REST contents will always be larger than a simple boolean due to HTTP overhead.

Parameter

string $url

The URL to retrieve data for.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_REST | Next
PEAR_REST::saveCache | PEAR Manual | PEAR


PEAR

PEAR

Table of Contents
  • Class Summary PEAR_RunTest -- Simplified version of PHP's test suite
  • constructor PEAR_RunTest::PEAR_RunTest -- Instantiate a PEAR_RunTest object.
  • PEAR_RunTest::generate_diff -- generate_diff
  • PEAR_RunTest::run -- run
Prev | PEAR Installer classes | Next
PEAR_REST::useLocalCache | PEAR Manual | Class Summary PEAR_RunTest


Class Summary PEAR_RunTest

Class Summary PEAR_RunTest

Class Summary PEAR_RunTest – Simplified version of PHP's test suite

Simplified version of PHP's test suite

Try it with:

$ php -r 'include "../PEAR/RunTest.php"; $t=new PEAR_RunTest; \
  $o=$t->run("./pear_system.phpt");print_r($o);'

Class Trees for PEAR_RunTest

  • PEAR_RunTest

Prev | PEAR | Next
PEAR | PEAR Manual | constructor PEAR_RunTest::PEAR_RunTest


constructor PEAR_RunTest::PEAR_RunTest

constructor PEAR_RunTest::PEAR_RunTest

constructor PEAR_RunTest::PEAR_RunTest() – Instantiate a PEAR_RunTest object.

Synopsis

require_once '/RunTest.php';

void constructor PEAR_RunTest::PEAR_RunTest ( PEAR_Common|null $logger = null , array $options = array() )

Description

If no logger is specified, a new PEAR_Common object will be instantiated and used to print output to the screen.

Parameter

PEAR_Common|NULL $logger

A class that contains a log() method matching the signature of PEAR_Common.

array $options

Currently supported options are simple and quiet. The simple option causes tests to simply print the title of the test and not the full path to the test file. The quiet option causes output of only failed tests.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
Class Summary PEAR_RunTest | PEAR Manual | PEAR_RunTest::generate_diff


PEAR_RunTest::generate_diff

PEAR_RunTest::generate_diff

PEAR_RunTest::generate_diff() – generate_diff

Synopsis

require_once '/RunTest.php';

void PEAR_RunTest::generate_diff ( string $wanted , string $output , array|false $return_value )

Description

Returns differences by line between the expected output ($wanted ) and the actual output ($output ). In addition, the value returned from the script can also be tested. The test should be performed outside generate_diff(). If the return value is as expected, pass in FALSE, otherwise pass in an array where the first element is the expected return value and the second is the actual return value.

Parameter

string $wanted

Expected output

string $output

Actual output

array|FALSE $return_value

False if return value was correct, otherwise an array of format:

<?php
array(
    1, // expected return
    2, // actual return value
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
constructor PEAR_RunTest::PEAR_RunTest | PEAR Manual | PEAR_RunTest::run


PEAR_RunTest::run

PEAR_RunTest::run

PEAR_RunTest::run() – run

Synopsis

require_once '/RunTest.php';

string|PEAR_Error PEAR_RunTest::run ( string $file , string $ini_settings = '' )

Description

Run a unit test. The return value is one of:

  • PASSED

  • SKIPPED

  • WARNED

  • FAILED

Parameter

string $file

Full path to the test file to run.

string $ini_settings

Additional customized settings to pass on the command-line to the PHP instance used for testing. For example, requesting disabling use of php.ini or a testing php.ini can be specified. For a full list of possible settings, type:

$ php -h

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_RunTest::generate_diff | PEAR Manual | PEAR_Validate


PEAR_Validate

PEAR_Validate

Table of Contents
  • Class Summary PEAR_Validate -- Validation class for package.xml - channel-level advanced validation
  • PEAR_Validate::_addFailure -- _addFailure
  • PEAR_Validate::_addWarning -- _addWarning
  • PEAR_Validate::getFailures -- getFailures
  • PEAR_Validate::getValidStates -- Get a list of valid stability levels
  • PEAR_Validate::setPackageFile -- setPackageFile
  • PEAR_Validate::validate -- validate
  • PEAR_Validate::validateChangelog -- validateChangelog
  • PEAR_Validate::validateDate -- validateDate
  • PEAR_Validate::validateDependencies -- for package.xml 2.0 only - channels can't use package.xml 1.0
  • PEAR_Validate::validateDeps -- validateDeps
  • PEAR_Validate::validateDescription -- validateDescription
  • PEAR_Validate::validateFilelist -- validateFilelist
  • PEAR_Validate::validateLicense -- validateLicense
  • PEAR_Validate::validateMainFilelist -- for package.xml 2.0 only
  • PEAR_Validate::validateMaintainers -- validateMaintainers
  • PEAR_Validate::validateNotes -- validateNotes
  • PEAR_Validate::validatePackageName -- validatePackageName
  • PEAR_Validate::validateReleaseFilelist -- for package.xml 2.0 only
  • PEAR_Validate::validateStability -- validateStability
  • PEAR_Validate::validateState -- validateState
  • PEAR_Validate::validateSummary -- validateSummary
  • PEAR_Validate::validateTime -- validateTime
  • PEAR_Validate::validateVersion -- protected function to validate a version
  • PEAR_Validate::validGroupName -- This validates a dependency group name, and dependency group names must conform to the PEAR naming convention, so the method is final and static.
  • PEAR_Validate::validPackageName -- utility method to validate a package name string
  • PEAR_Validate::validState -- Determine whether $state represents a valid stability level
  • PEAR_Validate::validVersion -- Determine whether a version is a properly formatted version number that can be used by version_compare
  • PEAR_Validate::_validPackageName -- Override this method to handle validation of normal package names
  • Package PEAR Constants -- Constants defined in and used by PEAR
Prev | PEAR Installer classes | Next
PEAR_RunTest::run | PEAR Manual | Class Summary PEAR_Validate


Class Summary PEAR_Validate

Class Summary PEAR_Validate

Class Summary PEAR_Validate – Validation class for package.xml - channel-level advanced validation

Validation class for package.xml - channel-level advanced validation

This package is not documented yet.

Class Trees for PEAR_Validate

  • PEAR_Validate

Prev | PEAR_Validate | Next
PEAR_Validate | PEAR Manual | PEAR_Validate::_addFailure


PEAR_Validate::_addFailure

PEAR_Validate::_addFailure

PEAR_Validate::_addFailure() – _addFailure

Synopsis

require_once '/Validate.php';

void PEAR_Validate::_addFailure ( string $field , string $reason )

Description

add a validation warning from one of the channel validation functions. Use this for a non-fatal warning of a potential problem situation.

Parameter

string $field

The package.xml section being validated (such as version or dependencies)

string $reason

A human-readable reason that validation failed.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
Class Summary PEAR_Validate | PEAR Manual | PEAR_Validate::_addWarning


PEAR_Validate::_addWarning

PEAR_Validate::_addWarning

PEAR_Validate::_addWarning() – _addWarning

Synopsis

require_once '/Validate.php';

void PEAR_Validate::_addWarning ( string $field , string $reason )

Description

add a validation warning from one of the channel validation functions. Use this for a non-fatal warning of a potential problem situation.

Parameter

string $field

The package.xml section being validated (such as version or dependencies)

string $reason

A human-readable reason that validation failed.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::_addFailure | PEAR Manual | PEAR_Validate::getFailures


PEAR_Validate::getFailures

PEAR_Validate::getFailures

PEAR_Validate::getFailures() – getFailures

Synopsis

require_once '/Validate.php';

void PEAR_Validate::getFailures ( )

Description

Returns a list of failures recorded by the last validation attempt. The list is in format:

<?php
array(
    'error' =>
        array(
            array('field' => 'name', 'name must contain only letters, numbers or underscore'),
        ),
    'warning' =>
        array(
            array('field' => 'version', 'version should be less than 2.0'),
        )
);
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::_addWarning | PEAR Manual | PEAR_Validate::getValidStates


PEAR_Validate::getValidStates

PEAR_Validate::getValidStates

PEAR_Validate::getValidStates() – Get a list of valid stability levels

Synopsis

require_once '/Validate.php';

array PEAR_Validate::getValidStates ( )

Description

Utility function for future extensibility of the list of valid stability levels.

Throws

throws no exceptions thrown

Final

final - this method must not be overridden

Note

This function should be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::getFailures | PEAR Manual | PEAR_Validate::setPackageFile


PEAR_Validate::setPackageFile

PEAR_Validate::setPackageFile

PEAR_Validate::setPackageFile() – setPackageFile

Synopsis

require_once '/Validate.php';

void PEAR_Validate::setPackageFile ( PEAR_PackageFile_v1|PEAR_PackageFile_v2 &$pf )

Description

Sets the packagefile object that will be used to retrieve data for validation.

Parameter

PEAR_PackageFile_v1|PEAR_PackageFile_v2 &$pf

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::getValidStates | PEAR Manual | PEAR_Validate::validate


PEAR_Validate::validate

PEAR_Validate::validate

PEAR_Validate::validate() – validate

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validate ( int $state = null )

Description

Validate the package.xml passed into setPackageFile(). The parameter passed in is the installer state that should be used, and is one of PEAR_VALIDATE_INSTALLING, PEAR_VALIDATE_DOWNLOADING, PEAR_VALIDATE_NORMAL, PEAR_VALIDATE_UNINSTALLING, or PEAR_VALIDATE_PACKAGING.

Parameter

integer $state

one of the PEAR_VALIDATE_* constants

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::setPackageFile | PEAR Manual | PEAR_Validate::validateChangelog


PEAR_Validate::validateChangelog

PEAR_Validate::validateChangelog

PEAR_Validate::validateChangelog() – validateChangelog

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateChangelog ( )

Description

Override this in a channel-specific validator to validate the contents of the <changelog> tag.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validate | PEAR Manual | PEAR_Validate::validateDate


PEAR_Validate::validateDate

PEAR_Validate::validateDate

PEAR_Validate::validateDate() – validateDate

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateDate ( )

Description

Override this in a channel-specific validator to validate the contents of the <date> tag.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateChangelog | PEAR Manual | PEAR_Validate::validateDependencies


PEAR_Validate::validateDependencies

PEAR_Validate::validateDependencies

PEAR_Validate::validateDependencies() – for package.xml 2.0 only - channels can't use package.xml 1.0

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateDependencies ( )

Description

Override this in a channel-specific validator to validate the <dependencies> tag of a package.xml 2.0-based release.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateDate | PEAR Manual | PEAR_Validate::validateDeps


PEAR_Validate::validateDeps

PEAR_Validate::validateDeps

PEAR_Validate::validateDeps() – validateDeps

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateDeps ( )

Description

Override this in a channel-specific validator to validate the contents of <deps> in a package.xml 1.0-based release.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateDependencies | PEAR Manual | PEAR_Validate::validateDescription


PEAR_Validate::validateDescription

PEAR_Validate::validateDescription

PEAR_Validate::validateDescription() – validateDescription

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateDescription ( )

Description

Override this in a channel-specific validator to validate the contents of the <description> tag.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateDeps | PEAR Manual | PEAR_Validate::validateFilelist


PEAR_Validate::validateFilelist

PEAR_Validate::validateFilelist

PEAR_Validate::validateFilelist() – validateFilelist

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateFilelist ( )

Description

Override this in a channel-specific validator to validate the contents of the <filelist> tag in a package.xml 1.0-based release.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateDescription | PEAR Manual | PEAR_Validate::validateLicense


PEAR_Validate::validateLicense

PEAR_Validate::validateLicense

PEAR_Validate::validateLicense() – validateLicense

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateLicense ( )

Description

Override this method in a channel-specific validator to validate the contents of the <license> tag.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateFilelist | PEAR Manual | PEAR_Validate::validateMainFilelist


PEAR_Validate::validateMainFilelist

PEAR_Validate::validateMainFilelist

PEAR_Validate::validateMainFilelist() – for package.xml 2.0 only

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateMainFilelist ( )

Description

Override this in a channel-specific validator to validate the contents of the <contents> tag in package.xml 2.0-based releases.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateLicense | PEAR Manual | PEAR_Validate::validateMaintainers


PEAR_Validate::validateMaintainers

PEAR_Validate::validateMaintainers

PEAR_Validate::validateMaintainers() – validateMaintainers

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateMaintainers ( )

Description

Override this in a channel-specific validator to validate the contents of <maintainers> in a package.xml 1.0-based release.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateMainFilelist | PEAR Manual | PEAR_Validate::validateNotes


PEAR_Validate::validateNotes

PEAR_Validate::validateNotes

PEAR_Validate::validateNotes() – validateNotes

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateNotes ( )

Description

Override this in a channel-specific validator to validate the contents of release notes in a <notes> tag.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateMaintainers | PEAR Manual | PEAR_Validate::validatePackageName


PEAR_Validate::validatePackageName

PEAR_Validate::validatePackageName

PEAR_Validate::validatePackageName() – validatePackageName

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validatePackageName ( )

Description

Override this in a channel-specific validator to validate a package name.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateNotes | PEAR Manual | PEAR_Validate::validateReleaseFilelist


PEAR_Validate::validateReleaseFilelist

PEAR_Validate::validateReleaseFilelist

PEAR_Validate::validateReleaseFilelist() – for package.xml 2.0 only

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateReleaseFilelist ( )

Description

Use this to validate the contents of a <filelist> tag in a package.xml 2.0-based package.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validatePackageName | PEAR Manual | PEAR_Validate::validateStability


PEAR_Validate::validateStability

PEAR_Validate::validateStability

PEAR_Validate::validateStability() – validateStability

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateStability ( )

Description

Override this in a channel-specific validator to validate the <stability> tag of a package.xml 2.0-based release.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateReleaseFilelist | PEAR Manual | PEAR_Validate::validateState


PEAR_Validate::validateState

PEAR_Validate::validateState

PEAR_Validate::validateState() – validateState

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateState ( )

Description

Override this in a channel-specific validator to validate the contents of a <state> tag in a package.xml 1.0-based release.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateStability | PEAR Manual | PEAR_Validate::validateSummary


PEAR_Validate::validateSummary

PEAR_Validate::validateSummary

PEAR_Validate::validateSummary() – validateSummary

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateSummary ( )

Description

Override this in a channel-specific validator to validate the <summary> tag.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateState | PEAR Manual | PEAR_Validate::validateTime


PEAR_Validate::validateTime

PEAR_Validate::validateTime

PEAR_Validate::validateTime() – validateTime

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateTime ( )

Description

Override this method to validate the <time> tag in a channel-specific validator.

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateSummary | PEAR Manual | PEAR_Validate::validateVersion


PEAR_Validate::validateVersion

PEAR_Validate::validateVersion

PEAR_Validate::validateVersion() – protected function to validate a version

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validateVersion ( )

Description

Override this function in a channel validator in order to apply a different version validation scheme. An example of this use is in the PEAR_Validate_PECL class, which overrides validateVersion() to be less strict than the default PEAR_Validate::validateVersion().

Errors should be reported using _addFailure() method, and non-fatal errors (warnings) should be reported using the _addWarning() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateTime | PEAR Manual | PEAR_Validate::validGroupName


PEAR_Validate::validGroupName

PEAR_Validate::validGroupName

PEAR_Validate::validGroupName() – This validates a dependency group name, and dependency group names must conform to the PEAR naming convention, so the method is final and static.

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validGroupName ( string $name )

Description

Dependency groups are documented here

Parameter

string $name

Dependency group name to validate

Throws

throws no exceptions thrown

Final

final - this method should not be overridden.

Note

This function should be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validateVersion | PEAR Manual | PEAR_Validate::validPackageName


PEAR_Validate::validPackageName

PEAR_Validate::validPackageName

PEAR_Validate::validPackageName() – utility method to validate a package name string

Synopsis

require_once '/Validate.php';

void PEAR_Validate::validPackageName ( string $name , string $validatepackagename = false )

Description

Validate a package name string. The second parameter should be the name of the channel validation package, as defined by channel.xml for the current channel. If the package name being validated is the same as the validation package (case-insensitive), then it will be validated using the default rules for PEAR packages.

Parameter

string $name

package name to validate

string $validatepackagename

name of channel-specific validation package

Throws

throws no exceptions thrown

Final

final - this method should not be overridden.

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validGroupName | PEAR Manual | PEAR_Validate::validState


PEAR_Validate::validState

PEAR_Validate::validState

PEAR_Validate::validState() – Determine whether $state represents a valid stability level

Synopsis

require_once '/Validate.php';

bool PEAR_Validate::validState ( string $state )

Description

This utility method can be used to determine whether a string is a valid state. Currently, states must be one of snapshot, devel, alpha, beta, and stable.

Parameter

string $state

State string to validate.

Throws

throws no exceptions thrown

Final

final - this method should not be overridden.

Note

This function should be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validPackageName | PEAR Manual | PEAR_Validate::validVersion


PEAR_Validate::validVersion

PEAR_Validate::validVersion

PEAR_Validate::validVersion() – Determine whether a version is a properly formatted version number that can be used by version_compare()

Synopsis

require_once '/Validate.php';

bool PEAR_Validate::validVersion ( string $ver )

Description

Use this method to test the validity of a version number string. All versions must be testable with PHP's version_compare().

Parameter

string $ver

Version string

Throws

throws no exceptions thrown

Final

final - this method should not be overridden.

Note

This function should be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validState | PEAR Manual | PEAR_Validate::_validPackageName


PEAR_Validate::_validPackageName

PEAR_Validate::_validPackageName

PEAR_Validate::_validPackageName() – Override this method to handle validation of normal package names

Synopsis

require_once '/Validate.php';

bool PEAR_Validate::_validPackageName ( string $name )

Description

This protected method can be used to change the normal package validation scheme. By default, all packages must begin with a letter and contain only letters, numbers and underscores. Using this method, it is possible to change this entirely to enforce another scheme.

For instance, enforcing java-style com.blah.package package names can be done simply by this code:

<?php
require_once 'PEAR/Validate.php';
class MyChannel_Validate extends PEAR_Validate
{
    function _validPackageName($name)
    {
        return preg_match('/[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)*/', $name);
    }
}
?>

Then, by using a customized channel validation package, the installer will enforce java-style package names for your channel.

Parameter

string $name

package name string to test for validity.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_Validate | Next
PEAR_Validate::validVersion | PEAR Manual | Package PEAR Constants


Package PEAR Constants

Package PEAR Constants

Package PEAR Constants – Constants defined in and used by PEAR

All Constants

Constants defined in Validate.php

Constants defined in Validate.php
Name | Value | Line Number
PEAR_VALIDATE_DOWNLOADING | 4 | 28
PEAR_VALIDATE_INSTALLING | 1 | 25
PEAR_VALIDATE_NORMAL | 3 | 27
PEAR_VALIDATE_PACKAGING | 7 | 29
PEAR_VALIDATE_UNINSTALLING | 2 | 26
Prev | PEAR_Validate | Next
PEAR_Validate::_validPackageName | PEAR Manual | PEAR


PEAR

PEAR

Table of Contents
  • Class Summary PEAR_XMLParser -- Parser for any xml file
  • PEAR_XMLParser::getData -- getData
  • PEAR_XMLParser::parse -- parse
  • PEAR_XMLParser::preProcessStupidSaxon -- pre-process xml to weed out characters/entities that would kill parsing
Prev | PEAR Installer classes | Next
Package PEAR Constants | PEAR Manual | Class Summary PEAR_XMLParser


Class Summary PEAR_XMLParser

Class Summary PEAR_XMLParser

Class Summary PEAR_XMLParser – Parser for any xml file

Parser for any xml file

This package is not documented yet.

Class Trees for PEAR_XMLParser

  • PEAR_XMLParser

Prev | PEAR | Next
PEAR | PEAR Manual | PEAR_XMLParser::getData


PEAR_XMLParser::getData

PEAR_XMLParser::getData

PEAR_XMLParser::getData() – getData

Synopsis

require_once '/XMLParser.php';

array PEAR_XMLParser::getData ( )

Description

Return the array representation of XML as parsed by parse().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
Class Summary PEAR_XMLParser | PEAR Manual | PEAR_XMLParser::parse


PEAR_XMLParser::parse

PEAR_XMLParser::parse

PEAR_XMLParser::parse() – parse

Synopsis

require_once '/XMLParser.php';

true|PEAR_Error PEAR_XMLParser::parse ( string $data )

Description

Return an array that matches the XML parsed. This code is lifted from Stephan Schmidt's XML_Unserializer class in the XML_Serializer package. As such, tags are represented by an associative array. Multiple tags are represented with a 0-based array of tag contents, and attributes are represented by an array index named attribs. If attributes are present, the array index _contents is used to hold the contents of the xml tag.

Parameter

string $data

xml content

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_XMLParser::getData | PEAR Manual | PEAR_XMLParser::preProcessStupidSaxon


PEAR_XMLParser::preProcessStupidSaxon

PEAR_XMLParser::preProcessStupidSaxon

PEAR_XMLParser::preProcessStupidSaxon() – pre-process xml to weed out characters/entities that would kill parsing

Synopsis

require_once '/XMLParser.php';

string PEAR_XMLParser::preProcessStupidSaxon ( string $data )

Description

This method examines xml data prior to parsing and replaces all entities like &agrave; with their equivalent (&#224; in this case). It also scans the file for any non-ascii characters like à and replaces them with their entity equivalent (&#224).

This prevents saxon in PHP 4 and PHP 5 from choking on non-ISO-8859-1 characters.

Parameter

string $data

The xml data.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR | Next
PEAR_XMLParser::parse | PEAR Manual | PEAR Installer: customizing the installer itself


PEAR Installer: customizing the installer itself

PEAR Installer: customizing the installer itself

Table of Contents
  • Introduction
  • Custom File Roles
  • Custom File Tasks
  • Post-installation Scripts
Prev | PEAR Developer Guide | Next
PEAR_XMLParser::preProcessStupidSaxon | PEAR Manual | Introduction


Introduction

Introduction

Edited By

Gregory Beaver

$Date: 2009/06/26 05:22:00 $

Extending the PEAR Installer is made possible through custom file roles, file tasks, post-installation scripts and custom commands.

  • Custom file installation roles in package.xml

  • Custom file tasks in package.xml

  • Post-installation scripts

Prev | PEAR Installer: customizing the installer itself | Next
PEAR Installer: customizing the installer itself | PEAR Manual | Custom File Roles


Custom File Roles

Custom File Roles

Table of Contents
  • custom roles in package.xml -- Using a customized role in a package.xml
  • creating custom roles -- Defining a customized role for use in a package.xml

Edited By

Gregory Beaver

$Date: 2008/10/09 15:16:18 $

As of PEAR version 1.4.3, the required format for custom file roles has been changed due to a minor security vulnerability. All custom file roles must now define a Role.xml file in order to properly declare a custom file role. See the example below for more information.

One of the programming features that the PEAR installer enforces is the separation of files into separate categories, and the important idea that files of a similar category are always installed into the same location, or at least handled the same way, as in the case of role="src" for PECL packages.

This has been quite successful for smaller library-style packages, but complete applications cannot function without customized installation locations. For instance, some files may be intended for use in a public web frontend, others for library location. PEAR 1.4 introduces the possibility of defining custom installation roles to fill this void.

Prev | PEAR Installer: customizing the installer itself | Next
Introduction | PEAR Manual | custom roles in package.xml


custom roles in package.xml

Using a customized role in a package.xml

To use a custom installation role that another programmer has written, there are three steps that are necessary. First, the <usesrole> tag should be used to define each custom role that is used in the package.xml. Next, the role should simply be used for the files it pertains to. Finally, a dependency on the package that provides the custom role should be added to the package.xml, just for completeness.

Pretty simple!

Prev | Custom File Roles | Next
Custom File Roles | PEAR Manual | creating custom roles


creating custom roles

Defining a customized role for use in a package.xml

To define a custom role, you need to create a package containing a single file. Here is a sample package.xml that could be a custom role:

<?xml version="1.0"?>
<package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0"
    xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
http://pear.php.net/dtd/tasks-1.0.xsd
http://pear.php.net/dtd/package-2.0
http://pear.php.net/dtd/package-2.0.xsd">
 <name>Chiarafoo</name>
 <channel>pear.chiaraquartet.net</channel>
 <summary>Chiarafoo role</summary>
 <description>
  The chiarafoo role installs files into your customized Foo directory
 </description>
 <lead>
  <name>Greg Beaver</name>
  <user>cellog</user>
  <email>cellog@php.net</email>
  <active>yes</active>
 </lead>
 <date>2005-03-21</date>
 <version>
  <release>1.0.0</release>
  <api>1.0.0</api>
 </version>
 <stability>
  <release>stable</release>
  <api>stable</api>
 </stability>
 <license uri="http://www.php.net/license">PHP License</license>
 <notes>
  Provides the chiarafoo file role
 </notes>
 <contents>
  <dir name="/" baseinstalldir="PEAR/Installer/Role">
   <file name="Chiarafoo.xml" role="php"/>
   <file name="Chiarafoo.php" role="php">
    <tasks:replace from="@package_version@" to="version" type="package-info"/>
   </file>
  </dir> <!-- / -->
 </contents>
 <dependencies>
  <required>
   <php>
    <min>4.2.0</min>
   </php>
   <pearinstaller>
    <min>1.4.3</min>
   </pearinstaller>
  </required>
 </dependencies>
 <phprelease/>
</package>

The XML file Chiarafoo.xml should be similar to this file:

<role version="1.0">
 <releasetypes>php</releasetypes>
 <installable>1</installable>
 <locationconfig>foo_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <phpfile>1</phpfile>
 <executable />
 <phpextension />
 <config_vars>
  <foo_dir>
   <type>directory</type>
   <default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default>
   <doc>directory where foo files are installed</doc>
   <prompt>PHP foo directory</prompt>
   <group>File Locations</group>
  </foo_dir>
 </config_vars>
</role>

The script in Chiarafoo.php is incredibly simple:

<?php
/**
 * PEAR_Installer_Role_Chiarafoo
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   pear
 * @package    Chiarafoo
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2005 Greg Beaver
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id: customroles.xml,v 1.6 2008/10/09 15:16:18 cweiske Exp $
 * @link       http://pear.chiaraquartet.net/index.php?package=Chiarafoo
 * @since      File available since Release 0.1.0
 */

/**
 * @category   pear
 * @package    Chiarafoo
 * @author     Greg Beaver <cellog@php.net>
 * @copyright  2005 Greg Beaver
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.chiaraquartet.net/index.php?package=Chiarafoo
 * @since      Class available since Release 0.1.0
 */
class PEAR_Installer_Role_Chiarafoo extends PEAR_Installer_Role_Common
{
    /**
     * @param PEAR_Installer
     * @param PEAR_PackageFile_v2
     * @param array file attributes
     * @param string relative path to file in package.xml
     */
    function setup(&$installer, $pkg, $atts, $file)
    {
        // do something special with the installer
    }
}
?>

Since PEAR 1.4.3, nothing else is necessary for a successful implementation of a file role.

The contents of the role's XML file must contain these tags:

  • <releasetypes>

  • <installable>

  • <locationconfig>

  • <honorsbaseinstall>

  • <unusualbaseinstall>

  • <phpfile>

  • <executable>

  • <phpextension>

  • (optional) <config_vars>

The <releasetypes> tag

This tag can only contain one of the following values:

  • php

  • extsrc

  • extbin

In order to specify compatibility with multiple release types, use multiple <releasetypes> tags as in:

 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>

releasetypes defines the kind of releases that this role can be used in. For instance, the "src" role is reserved for extsrc packages, and cannot be used in regular PEAR-style php releases. The "data" role can be used in any release, and would define <releasetypes> as:

<?php
<releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
?>

The <installable> tag

This tag must be either <installable>1</installable> or empty (<installable/>) and determines whether files utilizing this custom role can be installed. Any file that should be installed must set this to 1. Only roles such as the "src" role that is processed and used to create the files that are eventually installed should set this to an empty tag.

The <locationconfig> tag

This tag is used for all installable files to determine which configuration variable contains the directory in which the file should be installed. For instance, the php role uses the "php_dir" locationconfig, the data role uses "data_dir".

Our example role, chiarafoo, uses the "foo_dir" configuration variable, and then through the definition of <config_vars> tells the installer what foo_dir means. Note that once a custom role is installed, the user can config-set/ config-get/config-show the variable just like any other configuration variable!

<config_vars> can define more than one configuration variable, but note that more than 3 variables will trigger an error, disallowing any of them, as a security precaution.

The <honorsbaseinstall> tag

This tag controls whether a role reacts to the "baseinstalldir" attribute of a <file> or <dir> tag. Any role that honors baseinstalldir can potentially allow conflicting files from different packages, and so a check has to be made. A file role that does not honor baseinstalldir is always installed into:

Packagename/full/path/from/contents/file.ext

To specify this value, use <honorsbaseinstall>1</honorsbaseinstall> For all other cases, it should be an empty tag (<honorsbaseinstall/>)

The <unusualbaseinstall> tag

This tag controls whether a role that would normally ignore the "baseinstalldir" attribute of a <file> or <dir> tag would honor it, but still use the Packagename/baseinstalldir/full/path/from/contents/file.ext instead of baseinstalldir/full/path/from/contents/file.ext. Any role that supports the unusual baseinstalldir type cannot conflict with other files because the package name is always the parent directory. To specify this value, use <unusualbaseinstall>1</unusualbaseinstall> For all other cases, it should be an empty tag (<unusualbaseinstall/>)

The <phpfile> tag

This tag should be set to 1 (<phpfile>1</phpfile>) for any roles that contain php script files. These files are analyzed at package time, possibly catching errors before release. For all other cases, it should be an empty tag (<phpfile/>)

The <executable> tag

This tag should be set to 1 (<executable>1</executable>) for roles like the "script" role that should have their executable attribute set via chmod() on install. For all other cases, it should be an empty tag (<executable/>)

The <phpextension> tag

This tag should be used for roles like the "ext" role that provide a binary PHP extension. To specify this value, use <phpextension>1</phpextension> For all other cases, it should be an empty tag (<phpextension/>)

The optional <config_vars> tag

This tag is used to define configuration variables that should be added to the installer by this custom file role. Note that the installer will not allow a custom file role to create more than 3 configuration variables. To define configuration variables, create tags with the name of the configuration variable, and then sub-tags defining information about the configuration variable.

These tags are transformed into the PHP array format expected by the PEAR_Config class using an adapted version of Stephan Schmidt's excellent XML_Unserializer class (from the XML_Serializer package). As such, it is easiest to understand the XML format by examining existing configuration variables.

<?php
array(
        'password' => array(
            'type' => 'password',
            'default' => '',
            'doc' => '(maintainers) your PEAR account password',
            'prompt' => 'PEAR password (for maintainers)',
            'group' => 'Maintainers',
            ),
        // Advanced
        'verbose' => array(
            'type' => 'integer',
            'default' => PEAR_CONFIG_DEFAULT_VERBOSE,
            'doc' => 'verbosity level
0: really quiet
1: somewhat quiet
2: verbose
3: debug',
            'prompt' => 'Debug Log Level',
            'group' => 'Advanced',
            ),
        'preferred_state' => array(
            'type' => 'set',
            'default' => PEAR_CONFIG_DEFAULT_PREFERRED_STATE,
            'doc' => 'the installer will prefer releases with this state when installing packages without a version or state specified',
            'valid_set' => array(
                'stable', 'beta', 'alpha', 'devel', 'snapshot'),
            'prompt' => 'Preferred Package State',
            'group' => 'Advanced',
            ),
         );
?>

These sample configuration values from the actual PEAR_Config class would translate into this XML:

<config_vars>
 <password>
  <type>password</type>
  <default />
  <doc>(maintainers) your PEAR account password'</doc>
  <prompt>PEAR password (for maintainers)</prompt>
  <group>Maintainers</group>
 </password>
 <verbose>
  <type>integer</type>
  <default><constant>PEAR_CONFIG_DEFAULT_VERBOSE</constant></default>
  <doc>verbosity level
0: really quiet
1: somewhat quiet
2: verbose
3: debug</doc>
  <prompt>Debug Log Level</prompt>
  <group>Advanced</group>
 </verbose>
 <preferred_state>
  <type>set</type>
  <default><constant>PEAR_CONFIG_DEFAULT_PREFERRED_STATE</constant></default>
  <doc>the installer will prefer releases with this state when installing packages without a version or state specified</doc>
  <valid_set>stable</valid_set>
  <valid_set>beta</valid_set>
  <valid_set>alpha</valid_set>
  <valid_set>devel</valid_set>
  <valid_set>snapshot</valid_set>
  <prompt>Preferred Package State</prompt>
  <group>Advanced</group>
 </preferred_state>
</config_vars>

Note that the simple array defining the set converts each value into a separate <valid_set> tag for the preferred_state configuration variable.

The <default> tag's value can accept either a simple string, or three different kinds of tags:

  • <text> - this will be converted into a PHP string

  • <constant> - the contents of this sub-tag will be used to retrieve the value of a pre-defined PHP constant, or a pre-defined PEAR constant (as defined in PEAR_Config or PEAR_Common) and substitute the value for the <constant> tag.

  • any default configuration variable. These include default_channel, preferred_mirror, remote_config, auto_discover, master_server, http_proxy, php_dir, ext_dir, doc_dir, bin_dir, data_dir, test_dir, cache_dir, php_bin, username, password, verbose, preferred_state, umask, cache_ttl, sig_type, sig_bin, sig_keyid, and sig_keydir.

    when used, the configuration variable should simply be an empty tag like <php_dir/>. The tag will be replaced with the default value of the configuration variable, not the currently assigned value.

For instance, this example default value:

 <default><text0>hi there </text0><constant>PHP_OS</constant><text1> user, your default php_dir is </text1><php_dir/></default>

might convert into something like "hi there Linux user, your default php_dir is /usr/local/lib/php/pear".

Our example Chiarafoo role's foo_dir default value:

 <default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default>

might convert into something like "/usr/local/lib/php/Foo" or "C:\php5\pear\Foo".

Note that in order to use multiple <constant> or <text> tags, you must append a numbered suffix as in the <text0> <text1> example above. Only one PEAR configuration variable may be used per default value.

Note that if you use <type>integer</type>, no matter what default value is specified, it will be casted into an integer by PEAR_Config.

Prev | Custom File Roles | Next
custom roles in package.xml | PEAR Manual | Custom File Tasks


Custom File Tasks

Custom File Tasks

Table of Contents
  • custom tasks in package.xml -- Using a customized task in a package.xml
  • coding custom tasks -- Creating customized tasks in PHP

Edited By

Gregory Beaver

$Date: 2008/10/09 15:16:18 $

For many small library packages, very little customization is needed. Just install and go. package.xml 1.0 is very good at this task. As packages grow in size and complexity, it is often necessary to make slight changes to the contents of files, and occasionally to external components such as databases.

package.xml 1.0 provides a single undocumented system of customizing file contents through the <replace> tag, like so:

<file name="blah.php" role="php">
 <replace from="@token@" to="version" type="package-info"/>
 <replace from="@anothertoken@" to="php_dir" type="pear-config"/>
</file>

This example above would scan the blah.php file at installation, and then use str_replace() to replace all occurrences of the string @token@ with the package's version number. Then, it would replace all occurrences of the string @anothertoken@ with the value of the user's php_dir configuration variable.

Although powerful, the replace tag is the only customization tag available in package.xml version 1.0. When developing package.xml version 2.0, the replace tag and innovative work of other projects such as Phing became the inspiration for an expanded kind customization called a "task".

Tasks are defined by xml children of a <file> tag. Tasks are implemented by extending the PEAR_Task_Common task.

Prev | PEAR Installer: customizing the installer itself | Next
creating custom roles | PEAR Manual | custom tasks in package.xml


custom tasks in package.xml

Using a customized task in a package.xml

Tasks are defined in package.xml through the tasks namespace, which is currently http://pear.php.net/dtd/tasks-1.0. The current tasks namespace is defined by http://pear.php.net/dtd/tasks-1.0.xsd. Custom tasks bundled with PEAR include:

  • <tasks:replace>

  • <tasks:unixeol>

  • <tasks:windowseol>

  • <tasks:postinstallscript>

The xml for each of these tasks is documented here.

Prev | Custom File Tasks | Next
Custom File Tasks | PEAR Manual | coding custom tasks


coding custom tasks

Creating customized tasks in PHP

Creating a custom task involves creating a class that validates xml, and performs the task when called upon. Tasks can be invoked in two situations: at package-time and at install-time. Each task can control whether it should be called at package-time, install-time, or at both times.

There are two kinds of tasks: simple and multiple. Most tasks are simple tasks. Simple tasks are self-contained: all customization is limited to that file. Multiple tasks are collected during installation and processed fully as a unit after files have been committed to disk, allowing more complex processing.

All simple tasks must define 3 methods, all multiple tasks must define 4 methods. These are:

  • validateXml()

  • init()

  • startSession()

  • run() (multiple tasks only)

validateXml()

true|array validateXml ( PEAR_PackageFile_v2 $pkg , string|array $xml , PEAR_Config &$config , array $fileAttributes )

This method is called upon package.xml validation and should be used to validate the task's xml content. Upon error, a simple array of format array(CODE, message) must be returned. The code must be one of the following constants, as defined in PEAR/Task/Common.php:

  • PEAR_TASK_ERROR_NOATTRIBS - Attributes were expected, but none were present.

  • PEAR_TASK_ERROR_MISSING_ATTRIB - A specific attribute is not present.

  • PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE - The value of an attribute is incorrect.

  • PEAR_TASK_ERROR_INVALID - Any other error in validation.

The error message should include the file name as defined by $fileAttributes['name'], and include as much useful information about the location of the validation error as possible.

PEAR_PackageFile_v2 $pkg

This is the package.xml object that contains the task.

string|array $xml

The raw parsed content of the task's xml as parsed from package.xml. Tags like <tasks:windowseol> that have no attributes or child elements will be passed an empty string ''. Otherwise, simple text content will be a string, and nested tags/attributes will be passed in as an array. Here is a list of sample xml and their parsed values:

  • <tasks:blah/>

    string("");

  • <tasks:blah>hello
</tasks:blah>

    string("hello");

  • <tasks:blah>hello
 <tasks:boo/>
</tasks:blah>

    array('_content' => 'hello', 'tasks:boo' => string(''))

  • <tasks:blah foo="one">
 <tasks:boo/>
</tasks:blah>

    array('attribs' => array('foo' => 'one'),
          'tasks:boo' => string(''))

PEAR_Config $config

This is the current configuration object

array $fileAttributes

The parsed attributes of the <file> tag that encloses this tag. This is guaranteed to contain indices name, specifying the file name, and role, specifying the file role. Other attributes like baseinstalldir may be present but are not required, and so will not be guaranteed to be present for every file.

init()

void init ( string|array $xml , array $fileAttributes , string|null $lastVersion )

The init() function is called immediately prior to the startSession() method, and should be used for initialization that is not directly related to file modification. This method may move to another location in the installation process at any time. The logical separation of initialization from task action is important and the order of execution can be depended upon.

string|array $xml

The raw parsed content of the task's xml as parsed from package.xml. Tags like <tasks:windowseol> that have no attributes or child elements will be passed an empty string ''. Otherwise, simple text content will be a string, and nested tags/attributes will be passed in as an array. Here is a list of sample xml and their parsed values:

  • <tasks:blah/>

    string("");

  • <tasks:blah>hello
</tasks:blah>

    string("hello");

  • <tasks:blah>hello
 <tasks:boo/>
</tasks:blah>

    array('_content' => 'hello', 'tasks:boo' => string(''))

  • <tasks:blah foo="one">
 <tasks:boo/>
</tasks:blah>

    array('attribs' => array('foo' => 'one'),
          'tasks:boo' => string(''))

array $fileAttributes

The parsed attributes of the <file> tag that encloses this tag. This is guaranteed to contain indices name, specifying the file name, and role, specifying the file role. Other attributes like baseinstalldir may be present but are not required, and so will not be guaranteed to be present for every file.

string|null $lastVersion

This will be set to the string representing the version of the last installed version of this package. This is useful for determining whether the package is being upgraded or is a fresh installation. If the package is being installed for the first time, NULL will be passed in.

startSession()

string|false|PEAR_Error startSession ( string $contents , string $dest )

For non-script tasks, startSession() is called to actually execute a task. The task should perform all needed operations on the file contents, and on success return the file contents regardless of any modification. These contents will be written to disk, so it is imperative that they be the full, original file contents if no modification is made to them.

For script tasks, startSession() is called to determine whether the script can be safely executed. For both task types, script and non-script, a return value of FALSE will cause the task to be silently skipped. A return value of a PEAR_Error will cause processing of all operations to stop, and an error message to be displayed by the installer prior to exiting. Any other return value will cause the script to be processed normally by the frontend as a post-installation script.

string $contents

The original contents of the file whose <file> tag in package.xml contains the task tag.

string $dest

The full path to the final installed file location. This is strictly informational, as the file does not yet exist, and should only be used for error messages or other processing that does not attempt to modify the file.

run()

false|string run ( array $tasks )

The run() method should return FALSE on success, and an error message if there is a problem. This method is called only for tasks that define $this->type as multiple. For each task within package.xml that has this task, the run() method will be called with an array containing all of the task objects from the package.xml.

array $tasks

An array of task objects.

Prev | Custom File Tasks | Next
custom tasks in package.xml | PEAR Manual | Post-installation Scripts


Post-installation Scripts

Post-installation Scripts

Table of Contents
  • Naming the post-install script -- Naming requirements for a post-install script PHP file
  • Post-install script structure -- Structure of a post-install script

Edited By

Gregory Beaver

$Date: 2008/11/17 19:44:01 $

Incomplete documentation

Documentation is not yet complete

The XML format for defining a post-install script in package.xml is documented here. This document describes the required elements for the PHP post-install script itself.

Prev | PEAR Installer: customizing the installer itself | Next
coding custom tasks | PEAR Manual | Naming the post-install script


Naming the post-install script

Naming requirements for a post-install script PHP file

Post-install script files can be named anything one desires, but the class within the file must be the same name as the file with all path separators replaced by underscores plus "_postinstall". In other words, this postinstall script:

Path/To/Script.php

must contain a class named Path_To_Script_postinstall Due to casing differences between operating systems, it is recommended to always use lowercased file names.

Prev | Post-installation Scripts | Next
Post-installation Scripts | PEAR Manual | Post-install script structure


Post-install script structure

Structure of a post-install script

The post-install script class must contain two methods, one named init(), and the other named run(). The init() method is called at the same time as all other post-install scripts. The run() method is called at the conclusion of each parameter group in order to process the user's responses to queries.

The init() method

boolean init ( PEAR_Config $config , PEAR_PackageFile_v2 $self , string|null $lastInstalledVersion )

PEAR_Config $xml

The current configuration used for installation.

PEAR_PackageFile_v2 $self

The package.xml contents as abstracted by this object.

string|NULL $lastInstalledVersion

The last version of this package that was installed. This is a very important parameter, as it is the only way to determine whether a package is being installed from scratch, or upgraded from a previous version. Using this parameter, it is possible to determine what incremental changes, if any, need to be performed.

The function has to return TRUE when initialization succeeded, FALSE when it failed. In the latter case, the post install script it stopped.

The run() method

void run ( array $infoArray , string $paramGroupId )

array $infoArray

if $paramGroupId is _undoOnError, then $infoArray will contain a list of successfully completed parameter group sections. This can be used to restore any system changes made by the installation script.

Otherwise, $infoArray contains the results of the user input from the most recent <paramgroup> section.

string $paramGroupId

This variable either contains _undoOnError or the contents of the most recent <paramgroup>'s <id> tag. Note that paramgroup id cannot begin with an underscore (_), and so _undoOnError can only be triggered by the PEAR installer.

Prev | Post-installation Scripts | Next
Naming the post-install script | PEAR Manual | RFCs


RFCs

RFCs

Table of Contents
  • Coding standard enhancements
  • Error Handling Guidelines for PHP5 packages
  • Requiring E_STRICT Compatibility for New PEAR Packages
  • Header comment blocks
  • Orphaned packages
  • Orphan PEPr proposals
  • Protected Members
  • QA Team
  • Rules On Rules And Guidline Proposals
  • Version Naming

Request for comments are normative documents about how PEAR works. RFCs get proposed through PEAR's PEPr system.

All RFCs listed here have been accepted by the PEAR developers through PEPr voting.

Prev | PEAR Developer Guide | Next
Post-install script structure | PEAR Manual | Coding standard enhancements


Coding standard enhancements

Coding standard enhancements

Table of Contents
  • Split function definitions onto several lines
  • Split function call on several lines
  • Split long assigments onto several lines
  • Split long if statements onto several lines
  • Ternary operators
  • Alignment of function parameters
  • Alignment of assignments
  • Array formatting
  • Recommendations
  • Notes

2008-11-05

Note: The PEAR Group has voted and accepted this document. There will be no voting among developers.

This proposal has been in PEPr as proposal #538.

This RFC defines changes and enhancements to the current Coding Standards (CS) in PEAR. They are neccessary because the standards are not clear in some cases. With applications like PHP_CodeSniffer being used, is is important that those issues are worked out and tools can deliver reliable warnings and CS errors.

Most of the issues we currently have deal with long lines and how they should be split. General rule of thumb is that when splitting a line, the originating lines are indented by 4 spaces. Futher, the format shall allow it to easily comment out those lines - be it for debugging or development reasons. This implies that closing braces are to be put on a line on its own, and commas at the end of a line.

While it might seem archaic to some, the 75-80 line rule is still important. Please see http://paul-m-jones.com/?p=276 for an in-depth discussion on the topic.

Prev | RFCs | Next
RFCs | PEAR Manual | Split function definitions onto several lines


Split function definitions onto several lines

Split function definitions onto several lines

Functions with many parameters need to be split onto several lines to keep the 80 chars/line limit. The first parameters may be put onto the same line as the function name if there is enough space. Subsequent parameters on following lines are to be indented 4 spaces. The closing parenthesis and the opening brace are to be put onto the next line, on the same indentation level as the "function" keyword.

<?php

function someFunctionWithAVeryLongName($firstParameter = 'something', $secondParameter = 'booooo',
    $third = null, $fourthParameter = false, $fifthParameter = 123.12,
    $sixthParam = true
) {
    //....
?>
Prev | Coding standard enhancements | Next
Coding standard enhancements | PEAR Manual | Split function call on several lines


Split function call on several lines

Split function call on several lines

The CS require lines to have a maximum length of 80 chars. Calling functions or methods with many parameters while adhering to CS is impossible in that cases. It should be allowed to split parameters in function calls onto several lines.

<?php

$this->someObject->subObject->callThisFunctionWithALongName(
    $parameterOne, $parameterTwo,
    $aVeryLongParameterThree
);
?>

Several parameters per line should be allowed. Parameters need to be indented 4 spaces compared to the level of the function call. The opening parenthesis is to be put at the end of the function call line, the closing parenthesis gets its own line at the end of the parameters. This shows a visual end to the parameter indentations and follows the opening/closing brace rules for functions and conditionals. (See bug #11562)

The same applies not only for parameter variables, but also for nested function calls and for arrays.

<?php

$this->someObject->subObject->callThisFunctionWithALongName(
    $this->someOtherFunc(
        $this->someEvenOtherFunc(
            'Help me!',
            array(
                'foo'  => 'bar',
                'spam' => 'eggs',
            ),
            23
        ),
        $this->someEvenOtherFunc()
    ),
    $this->wowowowowow(12)
);
?>

Nesting those function parameters is allowed if it helps to make the code more readable, not only when it is necessary when the characters per line limit is reached.

Using fluent application programming interfaces often leads to many concatenated function calls. Those calls may be split onto several lines. When doing this, all subsequent lines are indented by 4 spaces and begin with the "->" arrow.

<?php

$someObject->someFunction("some", "parameter")
    ->someOtherFunc(23, 42)
    ->andAThirdFunction();
?>
Prev | Coding standard enhancements | Next
Split function definitions onto several lines | PEAR Manual | Split long assigments onto several lines


Split long assigments onto several lines

Split long assigments onto several lines

Assigments may be split onto several lines when the character/line limit would be exceeded. The equal sign has to be positioned onto the following line, and indented by 4 characters.

<?php

$GLOBALS['TSFE']->additionalHeaderData[$this->strApplicationName]
    = $this->xajax->getJavascript(t3lib_extMgm::siteRelPath('nr_xajax'));
?>
Prev | Coding standard enhancements | Next
Split function call on several lines | PEAR Manual | Split long if statements onto several lines


Split long if statements onto several lines

Split long if statements onto several lines

Long if statements may be split onto several lines when the character/line limit would be exceeded. The conditions have to be positioned onto the following line, and indented 4 characters. The logical operators (&&, ||, etc.) should be at the beginning of the line to make it easier to comment (and exclude) the condition. The closing parenthesis and opening brace get their own line at the end of the conditions.

Keeping the operators at the beginning of the line has two advantages: It is trivial to comment out a particular line during development while keeping syntactically correct code (except of course the first line). Further is the logic kept at the front where it's not forgotten. Scanning such conditions is very easy since they are aligned below each other.

<?php

if (($condition1
    || $condition2)
    && $condition3
    && $condition4
) {
    //code here
}
?>

The first condition may be aligned to the others.

<?php

if (   $condition1
    || $condition2
    || $condition3
) {
    //code here
}
?>

The best case is of course when the line does not need to be split. When the if clause is really long enough to be split, it might be better to simplify it. In such cases, you could express conditions as variables an compare them in the if() condition. This has the benefit of "naming" and splitting the condition sets into smaller, better understandable chunks:

<?php

$is_foo = ($condition1 || $condition2);
$is_bar = ($condition3 && $condtion4);
if ($is_foo && $is_bar) {
    // ....
}
?>
Note: There were suggestions to indent the parantheses "groups" by 1 space for each grouping. This is too hard to achieve in your coding flow, since your tab key always produces 4 spaces. Indenting the if clauses would take too much finetuning.
Prev | Coding standard enhancements | Next
Split long assigments onto several lines | PEAR Manual | Ternary operators


Ternary operators

Ternary operators

The same rule as for if clauses also applies for the ternary operator: It may be split onto several lines, keeping the question mark and the colon at the front.

<?php

$a = $condition1 && $condition2
    ? $foo : $bar;

$b = $condition3 && $condition4
    ? $foo_man_this_is_too_long_what_should_i_do
    : $bar;
?>
Prev | Coding standard enhancements | Next
Split long if statements onto several lines | PEAR Manual | Alignment of function parameters


Alignment of function parameters

Alignment of function parameters

To support readability, parameters in subsequent calls to the same function/method may be aligned by parameter name:

<?php

$this->callSomeFunction('param1',     'second',        true);
$this->callSomeFunction('parameter2', 'third',         false);
$this->callSomeFunction('3',          'verrrrrrylong', true);
?>
Prev | Coding standard enhancements | Next
Ternary operators | PEAR Manual | Alignment of assignments


Alignment of assignments

Alignment of assignments

To support readability, the equal signs may be aligned in block-related assignments:

<?php

$short  = foo($bar);
$longer = foo($baz);
?>

The rule can be broken when the length of the variable name is at least 8 characters longer/shorter than the previous one:

<?php

$short = foo($bar);
$thisVariableNameIsVeeeeeeeeeeryLong = foo($baz);
?>
Prev | Coding standard enhancements | Next
Alignment of function parameters | PEAR Manual | Array formatting


Array formatting

Array formatting

Assignments in arrays may be aligned. When splitting array definitions onto several lines, the last value may also have a trailing comma. This is valid PHP syntax and helps to keep code diffs minimal:

<?php

$some_array = array(
    'foo'  => 'bar',
    'spam' => 'ham',
);
?>
Prev | Coding standard enhancements | Next
Alignment of assignments | PEAR Manual | Recommendations


Recommendations

Recommendations

Readability of code blocks

Related lines of code should be grouped into blocks, seperated from each other to keep readability as high as possible. The definition of "related" depends on the code :)

For example:

<?php

if ($foo) {
    $bar = 1;
}
if ($spam) {
    $ham = 1;
}
if ($pinky) {
    $brain = 1;
}
?>

is a lot easier to read when seperated:

<?php

if ($foo) {
    $bar = 1;
}

if ($spam) {
    $ham = 1;
}

if ($pinky) {
    $brain = 1;
}
?>

Return early

To keep readability in functions and methods, it is wise to return early if simple conditions apply that can be checked at the beginning of a method:

<?php

function foo($bar, $baz)
{
    if ($foo) {
        //assume
        //that
        //here
        //is
        //the
        //whole
        //logic
        //of
        //this
        //method
        return $calculated_value;
    } else {
        return null;
    }
}
?>

It's better to return early, keeping indentation and brain power needed to follow the code low.

<?php

function foo($bar, $baz)
{
    if (!$foo) {
        return null;
    }

    //assume
    //that
    //here
    //is
    //the
    //whole
    //logic
    //of
    //this
    //method
    return $calculated_value;
}
?>
Prev | Coding standard enhancements | Next
Array formatting | PEAR Manual | Notes


Notes

Notes

We should keep to the 4 space indentation rule. Allowing 6, 8 or any other number for "personal preference" is an absurd line in a "standard".

Of course, the best rule is keeping your code easy and clean, avoing dozens of parameters to a function ("code smell" for long parameter lists). But sometimes there is no way to avoid functions with 6 parameters, and having default values for them does not simplfy the situation. The rules here are exactly for that code lines.

Prev | Coding standard enhancements | Next
Recommendations | PEAR Manual | Error Handling Guidelines for PHP5 packages


Error Handling Guidelines for PHP5 packages

Error Handling Guidelines for PHP5 packages

Table of Contents
  • Audience
  • Definition of error
  • Error Signaling in PHP5 PEAR packages
  • Exceptions and normal program flow
  • Exception class hierarchies
  • Documenting Exceptions
  • Exceptions as part of the API

This document defines guidelines for error handling within PEAR, for PHP5 packages. It was written to cope with Exceptions, introduced in Zend Engine 2 as the error handling mechanism. The final objective is to integrate the document text into the PEAR Coding Guidelines.

This RFC has been ratified in PEPr as proposal #132.

Prev | RFCs | Next
Notes | PEAR Manual | Audience


Audience

Audience

This document is targeted at PHP developers writing packages for submission into the PEAR repository. As any coding guidelines, it is useful to developers using PHP in other environments. The requirements for reading this text are only familiarity with PHP as a programming language, as well as familiarity with the mechanism of Exceptions as an error handling mechanism.

For those PHP developers unfamiliar with Exceptions, the wiki page from which this document was extracted provides a good introduction, as well as pointers to other references.

Prev | Error Handling Guidelines for PHP5 packages | Next
Error Handling Guidelines for PHP5 packages | PEAR Manual | Definition of error


Definition of error

Definition of error

An error is defined as an unexpected, invalid program state from which it is impossible to recover. For the sake of definition, recovery scope is defined as the method scope. Incomplete recovery is considered a recovery.

One pretty straightforward example for an error:

<?php
/**
 * Connect to Specified Database
 *
 * @throws Example_Datasource_Exception When it can't connect
 *                                      to specified DSN.
 */
function connectDB($dsn)
{
    $this->db =& DB::connect($dsn);
    if (DB::isError($this->db)) {
        throw new Example_Datasource_Exception(
            "Unable to connect to $dsn:" . $this->db->getMessage()
        );
    }
}
?>

In this example the objective of the method is to connect to the given DSN. Since it can't do anything but ask PEAR DB to do it, whenever DB returns an error, the only option is to bail out and launch the exception.

The next example will introduce the concept of recovery:

<?php
/**
 * Connect to one of the possible databases
 *
 * @throws Example_Datasource_Exception When it can't connect to
 *                                      any of the configured databases.
 * @throws Example_Config_Exception     When it can't find databases
 *                                      in the configuration.
 */
function connect(Config $conf)
{
    $dsns =& $conf->searchPath(array('config', 'db'));
    if ($dsns === false) {
        throw new Example_Config_Exception(
            'Unable to find config/db section in configuration.'
        );
    }

    $dsns =& $dsns->toArray();

    foreach ($dsns as $dsn) {
        try {
            $this->connectDB($dsn);
            return;
        } catch (Example_Datasource_Exception $e) {
            // Some warning/logging code recording the failure
            // to connect to one of the databases
        }
    }
    throw new Example_Datasource_Exception(
        'Unable to connect to any of the configured databases'
    );
}
?>

This second example shows an exception being caught and recovered from. Altough the lower level connectDB method is unable to do anything but throw an error when one database connection fails, the upper level connect method knows the object can go by with any one of the configured databases. Since the error was recovered from, the exception is silenced at this level and not rethrown.

The last example illustrates incomplete recovery:

<?php
/**
 * loadConfig parses the provided configuration. If the configuration
 * is invalid, it will set the configuration to the default config.
 */
function loadConfig(Config $conf)
{
    try {
        $this->config = $conf->parse();
    } catch (Config_Parse_Exception e) {
        // Warn/Log code goes here
        // Perform incomplete recovery
        $this->config = $this->defaultConfig;
    }
}
?>

The recovery produces side effects, so it is considered incomplete. However, the program may proceed, so the exception is considered handled, and must not be rethrown. As in the previous example, when silencing the exception, logging or warning should occur.

Prev | Error Handling Guidelines for PHP5 packages | Next
Audience | PEAR Manual | Error Signaling in PHP5 PEAR packages


Error Signaling in PHP5 PEAR packages

Error Signaling in PHP5 PEAR packages

Error conditions in PEAR packages written for PHP5 must be signaled using exceptions. Usage of return codes or return PEAR_Error objects is deprecated in favor of exceptions. Naturally, packages providing compatibility with PHP4 do not fall under these coding guidelines, and may thus use the error handling mechanisms defined in the PHP4 PEAR coding guidelines.

An exception should be thrown whenever an error condition is met, according to the definition provided in the previous section. The thrown exception should contain enough information to debug the error and quickly identify the error cause. Note that, during production runs, no exception should reach the end-user, so there is no need for concern about technical complexity in the exception error messages.

The basic PEAR_Exception contains a textual error, describing the program state that led to the throw and, optionally, a wrapped lower level exception, containing more info on the lower level causes of the error.

The kind of information to be included in the Exception is dependent on the error condition. From the point of view of exception throwing, there are three classes of error conditions:

  1. Errors detected during precondition checks

  2. Lower level library errors signaled via error return codes or error return objects.

  3. Uncorrectable lower library exceptions.

Errors detected during precondition checks should contain a description of the failed check. If possible, the description should contain the violating value. Naturally, no wrapped exception can be included, as there isn't a lower level cause of the error. Example:

<?php
function divide($x,$y)
{
    if ($y == 0) {
        throw new Example_Aritmetic_Exception('Divide by zero');
    }
    return $x/$y;
}
?>

Errors signaled via return codes by lower level libraries, if unrecoverable, should be turned into exceptions. The error description should try to convey all information contained in the original error. One example, is the connect method previously presented:

<?php
/**
 * Connect to Specified Database
 *
 * @throws Example_Datasource_Exception when it can't connect to specified DSN.
 */
function connectDB($dsn)
{
    $this->db =& DB::connect($dsn);
    if (DB::isError($this->db)) {
        throw new Example_Datasource_Exception(
            "Unable to connect to $dsn:" . $this->db->getMessage()
        );
    }
}
?>

Lower library exceptions, if they can't be corrected, should either be rethrown or bubbled up. When rethrowing, the original exception must be wrapped inside the one being thrown. When letting the exception bubble up, the exception just isn't handled and will continue up the call stack in search of a handler.

One example for rethrowing:

<?php
function preTaxPrice($retailPrice, $taxRate)
{
    try {
        return $this->divide($retailPrice, 1 + $taxRate);
    } catch (Example_Aritmetic_Exception e) {
        throw new Example_Tax_Exception('Invalid tax rate.', e);
    }
}
?>

And the same example for bubbling up:

<?php
function preTaxPrice($retailPrice, $taxRate)
{
    return $this->divide($retailPrice, 1 + $taxRate);
}
?>

The case between rethrowing or bubbling up is one of software architecture: Exceptions should be bubbled up, except in these two cases:

  1. The original exception is from another package. Letting it bubble up would cause implementation details to be exposed, violating layer abstraction, conducing to poor design.

  2. The current method can add useful debugging information to the received error before rethrowing.

Prev | Error Handling Guidelines for PHP5 packages | Next
Definition of error | PEAR Manual | Exceptions and normal program flow


Exceptions and normal program flow

Exceptions and normal program flow

Exceptions should never be used as normal program flow. If removing all exception handling logic (try-catch statements) from the program, the remaining code should represent the "One True Path" -- the flow that would be executed in the absence of errors.

This requirement is equivalent to requiring that exceptions be thrown only on error conditions, and never in normal program states.

One example of a method that wrongly uses the bubble up capability of exceptions to return a result from a deep recursion:

<?php

/**
 * Recursively search a tree for string.
 *
 * @throws ResultException
 */
public function search(TreeNode $node, $data)
{
    if ($node->data === $data) {
         throw new ResultException( $node );
    } else {
         search( $node->leftChild, $data );
         search( $node->rightChild, $data );
    }
}
?>

In the example the ResultException is simply using the "eject!" qualities of exception handling to jump out of deeply nested recursion. When actually used to signify an error this is a very powerful feature, but in the example above this is simply lazy development.

Prev | Error Handling Guidelines for PHP5 packages | Next
Error Signaling in PHP5 PEAR packages | PEAR Manual | Exception class hierarchies


Exception class hierarchies

Exception class hierarchies

All of PEAR packages exceptions must be descendant from PEAR_Exception. PEAR_Exception provides exception wrapping abilities, absent from the top level PHP Exception class, and needed to comply with the previous section requirements.

Aditionally, each PEAR package must provide a top level exception, named <Package_Name>_Exception. It is considered best practice that the package never throws Exceptions that aren't descendant from its top level exception.

Prev | Error Handling Guidelines for PHP5 packages | Next
Exceptions and normal program flow | PEAR Manual | Documenting Exceptions


Documenting Exceptions

Documenting Exceptions

Because PHP, unlike Java, does not require you to explicitly state which Exceptions a method throws in the method signature, it is critical that Exceptions be thoroughly documented in your method headers.

Exceptions should be documented using the @throws phpdoc keyword:

<?php
/**
 * This method searches for aliens.
 *
 * @return array Array of Aliens objects.
 *
 * @throws AntennaBrokenException If the impedence readings indicate
 *                                that the antenna is broken.
 * @throws AntennaInUseException  If another process is using the
 *                                antenna already.
 */
public function findAliens($color = 'green');
?>

In many cases middle layers of an application will rewrap any lower-level exceptions into more meaningful application exceptions. This also needs to be made clear:

<?php
/**
 * Load session objects into shared memory.
 *
 * @throws LoadingException Any lower-level IOException will be wrapped
 *                          and re-thrown as a LoadingException.
 */
public function loadSessionObjects();
?>

In other cases your method may simply be a conduit through which lower level exceptions can pass freely. As challenging as it may be, your method should also document which exceptions it is not catching.

<?php
/**
 * Performs a batch of database queries (atomically, not in transaction).
 *
 * @throws SQLException Low-level SQL errors will bubble up through this method.
 */
public function batchExecute();
?>
Prev | Error Handling Guidelines for PHP5 packages | Next
Exception class hierarchies | PEAR Manual | Exceptions as part of the API


Exceptions as part of the API

Exceptions as part of the API

Exceptions play a critical role in the API of your library. Developers using your library depend on accurate descriptions of where and why exceptions might be thrown from your package. Documentation is critical. Also maintaining the types of messages that are thrown is also an important requirement for maintaining backwards-compatibility.

Because Exceptions are critical to the API of your package, you must ensure that you don't break backwards compatibility by making changes to exceptions.

Things that break BC include:

  • Any change to which methods throw exceptions.

  • A change whereby a method throws an exception higher in the inheritance tree. For example, if you changed your method to throw a PEAR_Exception rather than a PEAR_IOException, you would be breaking backwards compatibility.

Things that do not break BC:

  • Throwing a subclass of the original exception. For example, changing a method to throw PEAR_IOException when before it had been throwing PEAR_Exception would not break BC (provided that PEAR_IOException extends PEAR_Exception).

Prev | Error Handling Guidelines for PHP5 packages | Next
Documenting Exceptions | PEAR Manual | Requiring E_STRICT Compatibility for New PEAR Packages


Requiring E_STRICT Compatibility for New PEAR Packages

Requiring E_STRICT Compatibility for New PEAR Packages

Table of Contents
  • The issue
  • The solution
  • Notes
  • A (Non-Exhaustive) List of E_STRICT-compatibility changes

2006-09-05

This RFC has been ratified in PEPr as proposal #419.

Prev | RFCs | Next
Exceptions as part of the API | PEAR Manual | The issue


The issue

The issue

First stable release of PHP version 5 was done two years ago. This version of language has matured a lot throughout these two years and with PHP version 4 development effectively stopped should already be considered the preferred platform by developers of new PHP libraries and applications.

PEAR policies encourage "backwards compatibility", which unfortunately means supporting the inadequate object model of PHP version 4. While it does make sense for existing packages, requiring such "backwards compatibility" for new packages that get accepted into PEAR has at least two problems:

  • It slows the adoption of PHP version 5 by users of PEAR

  • PEAR risks becoming a garbage dump of obsolescent code, or at least be perceived as one

Prev | Requiring E_STRICT Compatibility for New PEAR Packages | Next
Requiring E_STRICT Compatibility for New PEAR Packages | PEAR Manual | The solution


The solution

The solution

The proposed solution is to focus on "forward compatibility" instead. PHP version 5 has a builtin means to ensure that code is forward compatible, which is E_STRICT error reporting level.

Definition of E_STRICT-compatible package

The package is considered E_STRICT-compatible if

  • it can be used under PHP 5.1.4+

  • its files do not emit error messages when used with error reporting level set to E_ALL | E_STRICT under PHP 5.1.4+

  • it follows PEAR coding standards that apply to PHP5-only packages

  • it has only E_STRICT-compatible required dependencies

E_STRICT-compatible package may have optional dependencies that are not E_STRICT-compatible, but this is discouraged.

Proposed changes

After this RFC is accepted, a deadline for accepting the new non E_STRICT-compatible packages is set as January 1, 2007. This deadline should be prominently announced on PEAR website and in PEAR manual. All new PHP5-related coding standards should also be integrated into the manual.

Developers wishing to propose a new non E_STRICT-compatible package or start work on a non E_STRICT-compatible new major version (as defined in New guidelines for BC breaking releases) of an existing package should do so before the deadline.

After January 1, 2007 all new packages proposed via PEPr and all new major versions of existing packages should be E_STRICT-compatible. Proposals for non E_STRICT-compatible packages that reach this deadline not in "Called for votes" state should not be called for votes until the package is reworked to be E_STRICT-compatible.

Two versions exception

the person proposing a new package may choose to also provide a version of said package that can be run under PHP version 4. Such a version requires a separate proposal that may only be called for votes after the proposal of E_STRICT-compatible version is accepted. The package must have the name of E_STRICT-compatible version with 'PHP4' appended (ex.: Example_Foo and Example_FooPhp4).

Subpackages exception

if a package does not yet have E_STRICT-compatible version then non E_STRICT-compatible subpackages for it may be accepted at the discretion of base package's developers. If base package already has E_STRICT-compatible version then acceptance of such subpackages falls under the previous exception.

Impact on existing packages

Development and release process of existing PEAR packages which are not E_STRICT-compatible may continue as usual. The only new requirement is that if a new major version of a package is started, it should be E_STRICT-compatible.

If a new major version of an existing package was registered on PEAR website before the deadline is reached or the code of this new major version was present in PEAR CVS then this version is considered an "existing package" for the purpose of this RFC.

Nevertheless, developers of existing packages are strongly encouraged to update their packages for E_STRICT-compatibility if a BC break is still allowed by Version Naming guidelines.

Prev | Requiring E_STRICT Compatibility for New PEAR Packages | Next
The issue | PEAR Manual | Notes


Notes

Notes

Several people expressed the concern that mandating E_STRICT dependencies may slow the development. While this is true, one of the goals of this proposal is to encourage the rewrite of base PEAR classes to PHP5.

Prev | Requiring E_STRICT Compatibility for New PEAR Packages | Next
The solution | PEAR Manual | A (Non-Exhaustive) List of E_STRICT-compatibility changes


A (Non-Exhaustive) List of E_STRICT-compatibility changes

A (Non-Exhaustive) List of E_STRICT-compatibility changes

  • Methods that are intended to be called statically should be defined with static keyword

  • The $foo =& new Foo() construct should not be used

  • instanceof operator should be used instead of is_a() function

  • Declarations of methods in child classes should be compatible with those in parent classes

These changes obviously imply following the Error Handling Guidelines for PHP5 packages since PEAR class itself is not E_STRICT-compatible.

Also the new object model should be taken into account: this means removing unneded references when working with objects and using clone where needed.

Prev | Requiring E_STRICT Compatibility for New PEAR Packages | Next
Notes | PEAR Manual | Header comment blocks


Header comment blocks

Header comment blocks

Table of Contents
  • Base docblock
  • Required tags
  • Optional tags
  • Order and spacing
  • @package_version@ Usage
  • Transition policy

The current "Header Comment Blocks" portion of the Coding Standards was basically copied from PHP sources without alteration. Those headers are often construed to indicate that the license summary for the PHP License and the PHP Group copyright must be included in each file, even if a different license and/or copyright are used.

In addition, the header comments aren't parseable by phpDocumentor.

2005-02-02

This RFC has been ratified in PEPr as proposal #128.

This RFC has been integrated into the Coding Standards under the Header Comment Blocks section.

Prev | RFCs | Next
A (Non-Exhaustive) List of E_STRICT-compatibility changes | PEAR Manual | Base docblock


Base docblock

Base docblock

All source code files in the PEAR repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.

<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id: header-comments.xml,v 1.4 2009/05/04 20:16:19 cweiske Exp $
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */

// Place includes, constant defines and $_GLOBAL settings here.

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class foo
{
}
?>
Prev | Header comment blocks | Next
Header comment blocks | PEAR Manual | Required tags


Required tags

Required tags

Short Descriptions

Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item. Please read the Coding Standard's sample file about how to write good descriptions.

PHP Versions

One of the following must go in the page-level docblock:

  • PHP version 4

  • PHP version 5

  • PHP versions 4 and 5

@license

There are several possible licenses. One of the following must be picked and placed in the page-level and class-level docblocks:

  • @license http://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0

  • @license http://www.freebsd.org/copyright/freebsd-license.html BSD License (2 Clause)

  • @license http://www.debian.org/misc/bsd.license BSD License (3 Clause)

  • @license http://www.freebsd.org/copyright/license.html BSD License (4 Clause)

  • @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1

  • @license http://www.php.net/license/3_0.txt PHP License 3.0

For more information, see the PEAR Group's Licensing Announcement: http://pear.php.net/group/docs/20040402-la.php

@link

The following must be used in both the page-level and class-level docblocks. Of course, change "PackageName" to the name of your package. This ensures the generated documentation links back your package.

@link http://pear.php.net/package/PackageName

@author

There's no hard rule to determine when a new code contributor should be added to the list of authors for a given source file. In general, their changes should fall into the "substantial" category (meaning somewhere around 10% to 20% of code changes). Exceptions could be made for rewriting functions or contributing new logic.

Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors.

@since

This tag is required when a file or class is added after the package's initial release. Do not use it in an initial release.

@deprecated

This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.

Prev | Header comment blocks | Next
Base docblock | PEAR Manual | Optional tags


Optional tags

Optional tags

@copyright

Feel free to apply whatever copyrights you desire. When formatting this tag, the year should be in four digit format and if a span of years is involved, use a hyphen between the earliest and latest year. The copyright holder can be you, a list of people, a company, the PHP Group, etc.

Examples:

  • @copyright 2003 John Doe and Jennifer Buck

  • @copyright 2001-2004 John Doe

  • @copyright 1997-2004 The PHP Group

  • @copyright 2001-2004 XYZ Corporation

License Summary

If you are using the PHP License, use the summary text provided above. If another license is being used, please remove the PHP License summary. Feel free to substitute it with text appropriate to your license, though to keep things easy to locate, please preface the text with "LICENSE:".

@version

There were several comments about what to put in the @version tags. This proposal uses the CVS "Id" tag for the "page-level" docblock which covers the file, while the class-level docblocks will use @package_version@, which gets replaced with the release's version number by the PEAR installer.

This seems the best compromise because $Id: header-comments.xml,v 1.4 2009/05/04 20:16:19 cweiske Exp $'s talk about files while the release version numbers talk about the classes. $Id: header-comments.xml,v 1.4 2009/05/04 20:16:19 cweiske Exp $ is used rather than $Revision: 1.4 $ or other shorter tags because it is the standard and provides all of the potentially desired information.

@see

Add a @see tag when you want to refer users to other sections of the package's documentation. If you have multiple items, separate them with commas rather than adding multiple @see tags.

Prev | Header comment blocks | Next
Required tags | PEAR Manual | Order and spacing


Order and spacing

Order and spacing

To ease long term readability of PEAR source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard.

Prev | Header comment blocks | Next
Optional tags | PEAR Manual | @package_version@ Usage


@package_version@ Usage

@package_version@ Usage

There are two ways to implement the @package_version@ replacements. The procedure depends on whether you write your own package.xml files or if you use the PackageFileManager.

For those authoring package.xml files directly, add a <replace> element for each file. The XML for such would look something like this:

<file name="Class.php">
  <replace from="@package_version@" to="version" type="package-info" />
</file>

Maintainers using the PackageFileManager need to call addReplacement() for each file:

<?php
$pkg->addReplacement(
    'filename.php', 'package-info',
    '@package_version@', 'version'
);
?>
Prev | Header comment blocks | Next
Order and spacing | PEAR Manual | Transition policy


Transition policy

Transition policy

Existing Small Packages

Existing packages that have only a few files are required to adopt these docblocks before the next release.

Existing Large Packages

Existing packages with many files are encouraged to adopt the new headers as soon as possible. When such packages come out with a new major version upgrade, these docblocks must be implemented therein.

New Packages

New packages and existing packages which have no releases yet must include these docblocks before their first release.

Prev | Header comment blocks | Next
@package_version@ Usage | PEAR Manual | Orphaned packages


Orphaned packages

Orphaned packages

Table of Contents
  • The Problem
  • What can be considered an orphaned package?
  • Contact process
  • Finding a new lead

2005-02-18

This RFC has been ratified in PEPr as proposal #192.

Glossary

QA-Team

refers to the whole QA team (core and subscribed mailing list members)

QA core team

refers to the 7 elected members (only 6 presently)

Prev | RFCs | Next
Transition policy | PEAR Manual | The Problem


The Problem

The Problem

Sometimes a package is left without care for a long time. It becomes lonely and full of bugs. This is a very sad situation and somebody needs to step up to remedy it.

Prev | Orphaned packages | Next
Orphaned packages | PEAR Manual | What can be considered an orphaned package?


What can be considered an orphaned package?

What can be considered an orphaned package?

The following are considered orphaned packages:

  • A package with bugs open for longer than 2 months and the developers have not commented on the bug or made any commits to CVS during that time frame.

  • A package that has no open bugs and has bug fixes committed to CVS but does not have a release within 6 months of the bugs being fixed.

  • A package owned by somebody who is commonly known to be inactive.

  • A package denounced by its leads (i.e. The lead actually says that he is no longer maintaining it on pear-dev)

Prev | Orphaned packages | Next
The Problem | PEAR Manual | Contact process


Contact process

Contact process

A QA core-team member tries to contact the current maintainers and developers (cc'ing the QA list) asking about an update about their work on the package.

A package lead answers::

  • He states that he has no interest in the package anymore, he allows QA team to take the necessary steps

  • He states that he still intends to work on the package, but is busy at that point. Either a timeframe will then be decided upon by the lead and QA during which some activity must occur (i.e. I'm going to be busy the rest of this month but I'll get back to it on the 3rd of next month) OR a second lead developer will be sought to continue development

If no answer reaches the list in two weeks QA will consider the package orphaned. If the lead doesn't have the time he should write a mail to the list stating he needs more time to sort things out.

Prev | Orphaned packages | Next
What can be considered an orphaned package? | PEAR Manual | Finding a new lead


Finding a new lead

Finding a new lead

A message will be sent to pear-dev asking for volunteers.

Somebody steps up

If you are willing to take over a package you must notify the QA list and state who you are and why you want to take over.

If the QA team feels the person who stepped up is appropriate and capable, the team will make this person a new maintainer. In case several persons step up a case by case study will be carried out to assign new maintainer-ship.

Nobody wishes to take over

A QA core team member will mark the package as orphaned.

Orphan status

If a package is orphaned, a warning and a call for maintainers will be displayed on the main package page.

Prev | Orphaned packages | Next
Contact process | PEAR Manual | Orphan PEPr proposals


Orphan PEPr proposals

Orphan PEPr proposals

Table of Contents
  • The problem
  • The solution
  • Orphan marker
  • Initial cleanup

2005-01-26

This RFC has been ratified in PEPr as proposal #188.

Prev | RFCs | Next
Finding a new lead | PEAR Manual | The problem


The problem

The problem

It happens more or less often, that

  1. PEPr proposals get stuck in a specific proposal phase,

  2. PEPr proposals get accepted, but no package is registered / released.

Prev | Orphan PEPr proposals | Next
Orphan PEPr proposals | PEAR Manual | The solution


The solution

The solution

In these 2 cases PEAR QA should step in and try to get in touch with the specific proposers. If the proposer is no more interessted in the proposal, PEAR QA should search for a new maintainer for the package or the proposal should be deleted.

For these steps the following time frames are proposed:

For proposals in stages "draft" and "proposal"

  • PEAR QA posts a reminder comment to the proposal after 1 week of inactivity.

  • If the proposer does not react within 2 weeks, the proposal gets deleted.

For proposals in stage "finished"

  • PEAR QA tries to contact the maintainer 4 weeks after the proposal is finished and no release has been throwen.

  • If the maintainer can not be contacted within 4 weeks, PEAR QA starts searching for a new maintainer.

  • If no new maintainer is found within 4 weeks, the proposal gets marked as orphan.

The above stated actions maybe automized inside PEARWeb in future, as far as possible.

Prev | Orphan PEPr proposals | Next
The problem | PEAR Manual | Orphan marker


Orphan marker

Orphan marker

Finished proposals should not be deleted, but marked as orphan. This marker should have the following content:

  • To the name of the proposal the following tag will be added: "[QA-ORPHAN]".

  • To the describtion of the proposal the following text will be added at the top: "This proposal has been marked orphan by PEAR-QA on <DATE> because of the inactivity of the proposer. This means, that the proposal is invalid from this date on. If you have a similar proposal or want to re-activate this proposal, feel free to create a new PEPr proposal for it.".

Prev | Orphan PEPr proposals | Next
The solution | PEAR Manual | Initial cleanup


Initial cleanup

Initial cleanup

To get this process running, an initial cleanup is required. The procedure is only run once, when this proposal gets accepted. This cleanup should have the following steps:

Proposals in stages "proposal" and "draft"

PEAR QA will post a reminder comment to every proposal which shows no action since 4 weeks. If the proposer is not reachable within 1 week, the proposal is deleted.

Proposals in stage "finished"

PEAR QA will try to get in touch with the proposers of every proposal which is older than 4 weeks and for which no package has been registerd, yet. If the proposer is not reachable within 2 weeks, the proposal is marked as orphan.

Prev | Orphan PEPr proposals | Next
Orphan marker | PEAR Manual | Protected Members


Protected Members

Protected Members

Table of Contents
  • Preface
  • Voting
  • Information

2004-07-03

This RFC has been ratified in PEPr as proposal #99.

Prev | RFCs | Next
Initial cleanup | PEAR Manual | Preface


Preface

Preface

This RFC aims to resolve whether or not protected class members will be prefixed with an underscore, or prefixed with nothing.

Once a decision has been reached, the result will be added to the PEAR coding standards.

Private members will still be prefixed.

Note: These standards will only apply to PHP5 classes. In PHP4, if it's not public it's private and thus prefixed.
Prev | Protected Members | Next
Protected Members | PEAR Manual | Voting


Voting

Voting

Note: The voting resulted in a sum of +27 votes. Thus, the "no prefix" solution had been chosen.

A vote of 0 will not be counted.

If the overall score at the end of the call-for-votes is positive, class members will not be prefixed. If negative, they will be prefixed.

No prefix (accepted)

A vote of +1 suggests class members should not be prefixed.

<?php
class Foo
{
    protected $somevar;
    protected function somefunc();
}
?>

Prefix (not accepted)

A vote of -1 suggests class members should be prefixed with an underscore.

<?php
class Foo
{
    protected $_somevar;
    protected function _somefunc();
}
?>
Prev | Protected Members | Next
Preface | PEAR Manual | Information


Information

Information

What's changed?

PHP5 Introduces PPP - Private, Public and Protected.

What's protected and private?

Protected members can be accessed in classes extending the class they are declared in, where as private members can only be accessed by the class they belong to.

What did we use to do, and why?

In PHP4, both private and protected members were prefixed with an underscore. This was to ensure the user of the class knew what methods were available to them, and not to mess with anything else.

One of the key reasons for prefixed members is the visual expression of "Do not mess with this member, I may remove/rename it in the future". This is fine for private members, however will not follow for protected members when the class is extended by the user.

Is it possible to accidently ignore the declarations?

If a member is declared as protected (using the protected keyword), an E_FATAL error will be thrown if the member is used incorrectly.

PHP5 will also provide errors if a user attempts to redeclare a protected var as private. However protected members may be declared public by child classes.

In this regard 'protected' is like public in terms of the obligations of the library author. For example, if you want to keep your public API small, but allow extending classes to expose more functionality. Or, if you would prefer to access class properties directly rather than using setter methods, you can redeclare the properties public in a child class.

In these situations, public vars would be prefixed as "private".

Does prefixing enhance readability?

Some would argue yes, some would argue no. Most large classes consist almost completely of protected members, with the public members reserved for the API. In this situation, does having almost everything underscored really enhance readability?

Is private the same as protected? No, definitly not. Then why should it be prefixed the same? Some argue this actually decreases readability and confuses private members.

Is protected the same as public? No, definitly not. The user can't use a protected member (unless they are extending the class). In this example, protected has a lot more in common private. Should the user be protected visually (as well as with the language construct) from using protected members?

Prev | Protected Members | Next
Voting | PEAR Manual | QA Team


QA Team

QA Team

Table of Contents
  • Current issues
  • QA team membership
  • Voting
  • QA rights/responsibilities
  • pearweb QA subsection
  • Summary
  • Actions Required if accepted

There has been talked about forming QA team, but no action yet taken. The following is proposal of how the QA team will work, what rights they have and so on.

2004-05-04

This RFC has been ratified in PEPr as proposal #60.

Prev | RFCs | Next
Information | PEAR Manual | Current issues


Current issues

Current issues

There is no official QA team for PEAR. There are only a few people who try to help with QA issues but they don't have any official status or rights to resolve issues themselves if needed. PEAR claims quality but that can't be met if there is no real QA team. PEAR group has been talking about fine tuning karma for all users so the current "user has access to everything under /pear in cvs" karma policy will be eliminated and thus QA needs special karma when that happens. More importantly, there is currently no formal process or entity to handle orphaned packages or urgent fixes to packages.

To summarize the problem:

  1. No QA team = can't claim Quality

  2. Nobody has defined how the QA team is supposed to work, how it should be structured and what its rights (karma) are supposed to be.

Prev | QA Team | Next
QA Team | PEAR Manual | QA team membership


QA team membership

QA team membership

How the initial members are chosen

If there are more applicants than seats, there should be an open election, where everyone may cast as many votes as there are seats (only 1 vote may be cast per candidate). Of course, if there are less people than seats, all may be accepted and the remaining seats can be filled by QA group vote. Once the core team is formed all further team members can be voted in as per the rules stated below.

There will be a QA core team with a limited number (no more than 7, with the pear group this should give a sufficient amount of people with enough karma that can react to bad releases) people with extended "core-QA-karma". In order for the QA core team to react quickly, the core QA team should be spread out across all time zones as good as possible. This rather small number should empower the QA team sufficiently to handle issues but doesn't trivialize access rights.

Note: This issue needs more discussion since Klaus raised a good point in his post but the problem is that it isn't wise to give many users so much karma.

All other people interested are free to join the QA team. However potential new members for the QA team (core and non core) must be voted in by a 2/3 majority of the existing members of the QA team (core and non core). This is to prevent that the addition of new members is done even though there is a considerable amount of opposition, as this could lead to internal quarrels which could result in reducing the QA teams ability to efficiently address QA issues. Removing a member from either group requires a 2/3 majority as well.

For casual helpers the QA mailing list will of course remain open.

All members of the QA team (core and non core) are eligible to participate in QA team votes.

Any member that leaves the QA team loses all his special karma which he may have received due to his membership. If any member of the core QA team leaves and as a result a time zone gets under staffed, QA should actively try to find a replacement.

Note: When voting for a new member voters must be sure that the person has been helping with bug fixes in the past or has the potentials to help with that.
Prev | QA Team | Next
Current issues | PEAR Manual | Voting


Voting

Voting

All votes (except membership related votes; see above) require a simple 50% majority. Any member of the QA team may call for a vote at any time. All voting is done on the QA mailinglist.

The core team may overrule any decision (this includes votes on memberships) of the QA team and may decide to hold their own internal vote to make the ultimate decision on how to proceed. Furthermore, the core QA team may also hold votes without even consulting the QA team. However this should be only done in rare cases. All members of the core QA team may make decision on their own if a decision is time critical (like pulling a broken release). However the core QA team should be aware that making too many decisions on their own may lead to alienating the other members and therefore if possible it should always be attempted to at least consult other members of the team.

Prev | QA Team | Next
QA team membership | PEAR Manual | QA rights/responsibilities


QA rights/responsibilities

QA rights/responsibilities

Fixing bugs/making releases

If any QA related issues are found in a package that QA has not been granted permission to change without consulting the maintainer,the QA team will file a bug report. If the issue remains unresolved for 1 month (2+1+1 weeks; see below), QA may fix it themselves.

If the issue isn't fixed with in two weeks QA will email the maintainers about the issue (if the bug system won't have auto bug report notices every X week in the future) and if the problem isn't fixed within one week from that, QA will send yet another email to the maintainers and if no answer nor fix to the problem is provided within one week, all members of the core QA team will get the permission to modify any file needed to fix that QA issue as well as make a new release.

If any major QA issues are found in any package and the QA team doesn't have permission to change that package without contacting the lead first then the QA team will file a bug report. Any major issues can stay open for 2 weeks (5+5+4 days; see below), QA may fix it themselves.

If the issue isn't fixed within 5 days QA will email the maintainers about the issue (if the bug system won't have auto bug report notices every X week in the future) and if the problem isn't fixed with in 5 days, from that QA will send yet another email to the maintainers and if no answer nor fix to the problem is provided with in 4 days, all members of the core QA team will have permission to modify any file needed to fix that QA issue as well as make a new release.

The same time frames apply when the QA team want to make a release because of unreleased fixes/improvements which are only available via CVS, or when the QA team wants to determine if a package has been orphaned (using the time frames specified for non major issues).

The QA team can decide what are major issues after discussion on the QA Mailing-list.

The QA team will for this reason keep track of those QA issues in their pear web subsection. This would only be for having overview over which package maintainers need to be emailed for reminders and such things.

Orphaned Packages

The QA team can use the above stated rules to determine if a package is orphaned. The core QA team gets lead rights on all orphaned packages until the original maintainer returns or a new maintainer is found.

Deleting Package releases

The core QA team also has the permission to delete any release that might have any issues that have been found after the release, to reduce the effects of the problem. This right must be exercised with caution.

Package maintainers can also grant QA the rights to make a releases for their packages.

Prev | QA Team | Next
Voting | PEAR Manual | pearweb QA subsection


pearweb QA subsection

pearweb QA subsection

It seems that there is a lack of QA material in the manual that people agree on and there is also need to make it move visible for people so they will actually follow those rules/guidelines. The QA team will therefore get its own QA subsection in the manual and will have control over it just like package maintainer controls package related docs in the manual.

The QA team also gets its own subsection on pearweb so people can more easily access QA material which is too dynamic or just related to the QA team own internal documentation purposes. There the QA will, for example, publish their latest decisions.

Furthermore here the QA team will be able to provide interfaces to QA team services. For example, here the QA team could offer an interface for maintainers to configure the access rights they want to grant the QA. Finally the core QA team can add QA related notes to each package homepage to communicate QA related information to the user base.

Approving first stable release

The QA team needs to approve the first stable release of any major version.

For this purpose maintainers upload the release to PEARweb and contact the QA team with a link to the release, then QA will decide if the release is ready or not. The core QA team will at this point approve the release through PEAR web and release it for the maintainer.

Note: The QA team must always inform the current lead maintainers of any changes that are done to a given package using the currently configured email addresses on pear web.
Note: The core QA team may delegate tasks as much as possible to other QA team members. However no access rights will be assigned just for the sake of delegating a task (so members of the QA team may package a new release, but only members of the core QA team will have the necessary rights to upload the release).
Prev | QA Team | Next
QA rights/responsibilities | PEAR Manual | Summary


Summary

Summary

QA core group access rights:

  1. Max 7 core members that get the core-QA-karma

  2. The core QA team will get more permission to fix issues and make release of packages if reported problems are not fixed in a specific time frame

  3. The core QA team assumes lead over orphaned packages

  4. The core QA team gets the rights to delete releases of packages if it determines that the release has severe issues

  5. The QA team is allowed to add QA related notes to package homepages

  6. QA team needs to approve an first stable release for a given major version number (done by votes)

  7. The entire QA team will identify QA problems, will help writing QA related documents, will help people resolve their QA problems and such things

  8. More focus is needed on writing QA related things in the manual and make then more visible

  9. Make a little QA corner at pear.php.net so QA is more visible for people and package devs are more aware of the QA team and how it works.

  10. Keep track of what QA does regarding packages that QA doesn't have permission to edit through a wiki of some sort

Prev | QA Team | Next
pearweb QA subsection | PEAR Manual | Actions Required if accepted


Actions Required if accepted

Actions Required if accepted

  1. Forming of the QA team, electing the persons who should for the core of the QA team.

  2. Giving the core dudes full CVS karma on the pear CVS module, as well as full access rights to package management part of pear web

  3. Make that little QA pear page

  4. Improve the QA manual pages

  5. Discovering which packages' lead(s) allow QA to help keeping their package QA approved

  6. Better coordination of the work which is done, who is going to do what. Know in advance who is going to write some more entries to the manual and so on.

  7. Make a wiki page of some sort for the info tracking regarding QA editing package that QA doesn't have permission to edit.

Prev | QA Team | Next
Summary | PEAR Manual | Rules On Rules And Guidline Proposals


Rules On Rules And Guidline Proposals

Rules On Rules And Guidline Proposals

Table of Contents
  • The issues
  • The Proposed Solution
  • Actions Required if accepted
  • Comments

Due to recent events in the way that regulations have been proposed -the following is put for comment on the future method for introducing new standards, rules, conventions, recommendations or guidelines into the pear community.

2004-04-01

This RFC has been ratified in PEPr as proposal #39.

Prev | RFCs | Next
Actions Required if accepted | PEAR Manual | The issues


The issues

The issues

For PEAR to continue to grow, and encourage contributors, testers, writers and users. It is important (in the view of the RFC author) to make the decision process within PEAR to be as open and fair as possible.

Due to historical issues of long, rather pointless, and heated discussions on the pear-dev mailing list, Some rules have been made in the privacy of the pear-group mailing lists with little consultation with the community at large. This, (in the view of the author of this RFC) is something that is a serious mistake and must strongly be prevented in the future.

To summarize the problem

  1. No formal procedure for proposing and approving RFCs has been available.

  2. Public RFC's (or ideas) previously have ended up in 'flamewars' and pointless discussions.

  3. Long nested threads can become difficult to summarize, when the aim is to produce a consensus building document.

  4. This public battering has discouraged contributors to put forward ideas to improve PEAR, or even keep subscribing to pear-dev.

  5. It is impossible to gauge the community support for rules that have been decided and enforced by the pear group.

  6. Without clear wide ranging support, rules, guidelines will never represent the view of all users and contributors to PEAR.

(RFC = Request for comments) for those who are wondering..

Prev | Rules On Rules And Guidline Proposals | Next
Rules On Rules And Guidline Proposals | PEAR Manual | The Proposed Solution


The Proposed Solution

The Proposed Solution

  1. All RFC's should be proposed using the PEPR system (and hence cc'd to pear-dev)

  2. RFC's should be named by prefixed RFC_ to the Wiki style name of the RFC (eg. RFC_RulesOnRulesAndGuidlineProposals)

  3. Anyone may comment on the RFC using the PEPR system (or by emailing the author directly)

  4. NOBODY SHOULD RESPOND TO COMMENTS ON THE RFC

    • This includes the author themselves

    • Repeated abuse by the author may result in RFC being rejected

    • Repeated abuse by others may result in them being unsubscribed from pear-dev for 1 week.

    • If you have a need to repond to responses - please email the author and the original respondant (not the list). - a summary of this discussion should be noted in the RFC

  5. The RFC Author should update the RFC based on the comments received to represent the opinions presented. Either by updating the solution, or explaining differing opinion in the Comments section.

  6. RFC's should take the form of

    • Title Block Containing

      • Title

      • Author (email simply encoded)

      • Revision

      • Status (Active|Final|Rejected|Replaced)

      • Replaces : Name of original RFC (eg. RfcProposals1)

    • Introduction (Short ~1-2 paragraphs)

    • The Issues (Detail discussion of need for RFC)

    • The Proposed Solution

    • Actions required if accepted.

  7. After it has been proposed these section should be added

    • Comments - a summary of the opinion made about the RFC (if they are not represent in the updated RFC) Along with why the author has not included them in the Solution

    • Change log - a summary of the changes made to each revision

  8. RFC's may under go any number of revisions, and put to vote (normally after a new revision of the RFC has been issued via PEPr, and no comments where added.)

  9. Initial drafts of RFCs may be developed in private or in small groups. Once the RFC reaches a point nearing maturity, it should be made public (on the pear-dev mailing list) for comment.

  10. All RFC's will be licenced under "Open Publication License" http://www.opencontent.org/openpub/

  11. RFC's should not concern themselves with specific packages, or the addition of specific features. This should be done by discussions directly with package maintainers, or proposing competing packages.

  12. PEAR group was set up to oversee PEAR, it's continued existance relies on support from the community, It is intended that the group is to have the power of veto over all proposals (however it well understands that continually doing this would seriously undermine its own authority, and veto should only occur in extremely serious situations.)

  13. It is strongly recommended that contentious issues are broken out into separate RFCs, so they can be documented, discussed and voted on separatly.

Prev | Rules On Rules And Guidline Proposals | Next
The issues | PEAR Manual | Actions Required if accepted


Actions Required if accepted

Actions Required if accepted

Changes to the PEPr proposal system:

  1. While the current system could be used it would be appreciated if the author could add the following features

    • RFC Category

    • No requirement for tgz/etc for RFC 'packages'

  2. Wishlist for PEPr (not essential to use it however).

    • BIG warning messages on the bottom of package comments should say 'DO NOT EVER RESPOND TO THIS COMMENT - the RFC author will update the RFC to reflect these opinions' o reply to address on comments messages should be do_not_reply@localhost

    • Comments visible on 'a' Summary page, with tags saying "has been adressed by updating the RFC", "won't fix"

    • A licence link on the PEPr system indicating that all RFCs are published under the "Open Publication License"

Prev | Rules On Rules And Guidline Proposals | Next
The Proposed Solution | PEAR Manual | Comments


Comments

Comments

  • Greg Beaver: main comment added, "Poorly thought-out RFCs should not be made public." - was not added as it was considered obvious... and a little difficult to define..

  • Jon Praise: mentioned Pythons PEPs (Python Enhancement Proposals) http://www.python.org/peps/pep-0001.html (some modifications made based on this document)

  • Lukas Smith: mentions that any opinions not incorporated should detail the authors reasoning for not including them. (added)

  • IRC discussions:

    • RFCs would be created on pedantic issues - like adding feature X to a package (see rule on RFC issues)

    • how should Pear-group be involved in a proposal / approval.. what if in a whim of chaos it decided to add support for GPL packages without understanding the concequences (see pear-group veto)

  • Stefan Neufeind: Would like to see notes auto-attached to PEPr like : modified Action list to include wishlist.

  • Toby : Called for volunteers to help out implement Wishlist (see mailing list for details)

  • Richard York: Asked for automated tracking of responses to Comments - so they get appended to PEPr. (while nice, I'm not sure this is directly related to the RFC, and really depends on someone volunteering to do it.)

  • Ian Eure, Lukas Smith: Commented on the varying views about Comment on comments. (While the rule is not intended to restrict open discussion, it is there to focus comments on the issue at hand, helping the RFC author gather views for the document.) - The document has been updated a bit to clarify this issue.

  • Lukas Smith: copyright note - have added that to the wishlist for PEPr. - It's a bit silly to add it to each document if we can do it via PEPr.

Prev | Rules On Rules And Guidline Proposals | Next
Actions Required if accepted | PEAR Manual | Version Naming


Version Naming

Version Naming

Table of Contents
  • The issue
  • New version naming standard

This RFC has been ratified in PEPr as proposal #65.

As discussed previously on pear-group, where a full consensus could not be reached on the version naming standard, below is the proposed replacement RFC, which attempts to address the issues.

Prev | RFCs | Next
Comments | PEAR Manual | The issue


The issue

The issue

Pear-group announced a versioning naming standard which unfortunatly failed to explain the reasons behind the decisions made. The aim of the previous standard was

  • Formalize the version naming of packages.

  • Fix problems with version_compare going from 1.0.0RC1 to 1.0.1

  • To introduce a rule stating 'no-stable releases before 1.0.0'

  • Solve release naming for My_Package2 (second releases)

It also attemtped to introduce a number of more controversial ideas

  • Make the package status more visible.

The last one did not result in a complete consensus, and patches have now been made to the packager and installer to add state to the filename, output when installing a package.

Prev | Version Naming | Next
Version Naming | PEAR Manual | New version naming standard


New version naming standard

New version naming standard

The solution is to replace the existing standard with one a simpler and slightly clearer one.

MyPackage versions
Version | Description
0.1.0 ... 0.1335.0 | initial pre-stable releases (bug fix releases increment .z eg. 0.12.1 )
1.0.0 | first stable release
1.1.0 | first feature upgrade
1.1.1 | bug fixes on feature upgrade

The next major version is MyPackage2:

MyPackage2 versions
Version | Description
0.1.0 ... 0.1335.0 | initial pre-stable releases (bug fix releases increment .z eg. 0.12.1 )
2.0.0 | first stable release
2.1.0 | first feature upgrade
2.1.1 | bug fixes on feature upgrade

Deliberatly Breaking BC on packages

Breaking BC may only be done:

  • within the 0.*.* series

  • moving from Major Package Versions (eg. to My_Package2)

First Releases

  • should not be marked as stable

  • should use 0.1.0 or greater (as you may have already started revision controlling while proposing it)

Bug fix only Releases

  • in pre stable - you can either increase y (in x.y) or z (in x.y.z), for example

    • 0.2.0 -> 0.3.0

    • 0.2.0 -> 0.2.1

  • after a stable release

    • 1.3.0 -> 1.3.1

    • 2.4.0 -> 2.4.1

Feature addition Releases (that may also include bug fixes)

Should just increment the y (in x.y), for examples

  • 0.3.0 -> 0.4.0

  • 1.3.0 -> 1.4.0

  • 2.10.0 -> 2.11.0

Stable Releases

You should never release stable packages with a 0.x format (this is a common situation at present, and is the only significant change that is being proposed.)

Appending RC releases (Release Candidates)

RC releases are strongly recommended for larger, popular packages.

If you intend to append RC releases to your package, you should append a release number to after the RC, for example:

  • 0.123.0 -> 1.0.0RC1

  • 1.0.0RC1 -> 1.0.0RC2

  • 1.0.0RC2 -> 1.0.0

  • 1.0.0 -> 1.0.1

Defining BC breaks

At present this is left to the maintainer to define (using common sense), the exact definition should be defined later by future RFCs.

Prev | Version Naming | Next
The issue | PEAR Manual | Channels: distributing your packages


Channels: distributing your packages

Channels: distributing your packages

Table of Contents
  • channel.xml, REST, XML-RPC
  • Creating your own channel with Pyrus and PEAR2_SimpleChannelServer
Prev |  | Next
New version naming standard | PEAR Manual | channel.xml, REST, XML-RPC


channel.xml, REST, XML-RPC

channel.xml, REST, XML-RPC

Table of Contents
  • channel.xml: The channel definition file
  • PEAR channel server REST interface
  • (deprecated) XML-RPC functions

Edited By

Gregory Beaver

2009-06-25

What is a PEAR Channel? PEAR Channels make it possible to take advantage of the strengths of the PEAR Installer and Pyrus for your own personal packages. A channel is simply a website that provides packages for download and a few extra meta-information files.

A familiar example of a channel is pear.php.net. This channel was the first channel, and defines the standards to which other channels must adhere. Each channel has a channel.xml file in its document root (such as http://pear.php.net/channel.xml) and a series of files utilizing the REST (Representational State Transfer) paradigm to describe the packages available for installation and download. The pear.php.net channel's REST files can be viewed at http://pear.php.net/rest.

Prev | Channels: distributing your packages | Next
Channels: distributing your packages | PEAR Manual | channel.xml: The channel definition file


channel.xml: The channel definition file

channel.xml: The channel definition file

How to describe a channel

Discovery of a channel's capabilities is extremely flexible. The XSD schema defining channel.xml can be found at http://pear.php.net/dtd/channel-1.0.xsd. Channel.xml defines:

  1. the channel name

  2. an optional suggested user alias for the channel

  3. a brief summary of the channel's purpose

  4. an optional package to perform custom validation of packages on both download and packaging

  5. a list of protocols supported by a channel (XML-RPC, SOAP, and REST are supported)

  6. a list of mirrors and the protocols they support.

Here is a sample channel.xml with all elements:

<channel version="1.0"
         xsi:schemaLocation="http://pear.php.net/channel-1.0
                             http://pear.php.net/dtd/channel-1.0.xsd">
<name>
pear.example.com</name>
<suggestedalias>
foo</suggestedalias>
<summary>
Example channel.xml</summary>
<validatepackage
version="1.3.4">Foo_Validate</validatepackage>
<servers> <primary
port="8080" ssl="yes">
<xmlrpc>
<!-- default path is xmlrpc.php -->
    <function version="1.0">logintest</function>
    <function version="1.0">package.listLatestReleases</function>
    <function version="1.0">package.listAll</function>
    <function version="1.0">package.info</function>
    <function version="1.0">package.getDownloadURL</function>
    <function version="1.1">package.getDownloadURL</function>
    <function version="1.0">package.getDepDownloadURL</function>
    <function version="1.1">package.getDepDownloadURL</function>
    <function version="1.0">package.search</function>
    <function version="1.0">channel.listAll</function>
   </xmlrpc>
<rest>
<!-- no default path, all must be defined in baseurl -->
    <baseurl type="REST1.0">http://pear.example.com/rest/</baseurl>
    <baseurl type="REST1.1">http://pear.example.com/rest/</baseurl>
   </rest>
<soap
path="soapy.php"> <!-- default path is soap.php -->
    <function version="1.0">package.listAll</function>
   </soap>
  </primary>
<mirror
server="foo2.example.com/pearmirror">
   <xmlrpc path="mirrorxmlrpc.php"> <!-- default path is xmlrpc.php -->
    <function version="1.0">package.listLatestReleases</function>
    <function version="1.0">package.listAll</function>
    <function version="1.0">package.info</function>
    <function version="1.0">package.getDownloadURL</function>
    <function version="1.1">package.getDownloadURL</function>
    <function version="1.0">package.getDepDownloadURL</function>
    <function version="1.1">package.getDepDownloadURL</function>
    <function version="1.0">package.search</function>
   </xmlrpc>
   <rest> <!-- no default path, all must be defined in baseurl -->
    <baseurl type="REST1.0">http://foo2.example.com/rest/</baseurl>
   </rest>
  </mirror>
 </servers>
</channel>

<name>

A channel's name should be the name of the server that users would browse to in order to learn more about the packages being offered. For instance, PEAR packages are located in the pear.php.net channel. PECL packages are located in the pecl.php.net channel. Note that for backwards compatibility, all existing packages based on package.xml version 1.0 are in the pear.php.net channel.

The benefit that comes from using the server name as the channel name is that auto-discovery becomes a real possibility, as well as ease of locating packages increases dramatically.

A channel need not be located in the document root, a channel can contain a path. This is a perfectly valid channel name: foo.example.com/path/to/pear. Note that users would have to type:

$ pear install foo.example.com/path/to/pear/Packagename

Unless you provide a <suggestedalias>.

The channel's definition file "channel.xml" must be placed in the root channel directory. If a channel is "pear.example.com", the channel.xml must be located in "http://pear.example.com/channel.xml". If the channel is "pear.example.com/path/to/pear", then the channel.xml must be located in "http://pear.example.com/path/to/pear/channel.xml"

<suggestedalias>

<suggestedalias> defines a shorter, more friendly name to use when installing packages from a channel. For instance, the pear.php.net channel's suggested alias is "pear". The best aliases for a channel will be no more than 6 characters long - remember, a user must type them often when installing or upgrading, and this can be tedious for longer aliases.

Rather than call this tag <alias>, as it was originally named, the tag is named <suggestedalias> in order to provide the user some latitude. If the user does not like the alias suggested by the channel owners, he or she can easily re-alias a channel through the channel-alias command.

<summary>

This tag provides a short description of what packages the user should expect to find on this channel. The summary is what users will see when the use the list-channels command.

<validatepackage>

Most channels will be satisfied with the restrictions placed upon package naming, versioning, and so on that PEAR provides by default. However, for some channels, the validation will be too strict, and others, too relaxed. The <validatepackage> tag provides the next level of customization.

If omitted, the installer assumed that the PEAR_Validate class should be used. Note that a looser version validation is provided by the PEAR_Validate_PECL class, for channels like pecl.php.net that do not wish to deal with PEAR's warnings on version transgressions.

<validatepackage> requires a version attribute and text content. The text content must be the name of a package that can be installed via:

$ pear install channelname.example.com/Packagename-version

as in:

$ pear install pear.example.com/Foo_Validate-1.3.4

for the sample channel.xml at the beginning of this section. In addition, the package must provide a single class named after the package in a file using the PEAR naming conventions (all underscores "_" converted into path separators "/" so that Foo_Validate is located in Foo/Validate.php), and this class should extend PEAR_Validate. Methods beginning with "validate" like validateVersion() are intended to be overridden by validation classes for use in extending existing validation functionality.

<servers>: <primary> and <mirror>

Mirroring is explicitly supported in channel.xml and in the PEAR installer. Users can choose their favorite mirror via the default_channel configuration option, and channel.xml can list all the possible mirrors using the (surprise) <mirror> tag.

The <primary> tag is used to define the location of protocols, and to list the protocols that are supported by the main channel server. Optional attributes can be used to modify how the PEAR installer will attempt to connect to the server. The "port" attribute can be used to define how the installer will connect to XML-RPC and SOAP services. REST services are always controlled by the individual <baseurl> tags.

<xmlrpc>, <soap>, <rest>

channel.xml knows about the XML-RPC, SOAP, and REST protocols for web services. However, the PEAR installer only supports REST currently, and may support other methods in the future. No support for SOAP is planned for the near future. However, should it ever be implemented, channel.xml is ready.

The <xmlrpc> and <soap> tags have identical formats. Both tags can contain an optional attribute "path" that tells the PEAR installer which URL to query. By default, the path is protocol.php, as in xmlrpc.php or soap.php. In other words, to access XML-RPC functions for the pear.example.com channel defined in the sample channel.xml, the installer would query https://pear.example.com:8080/xmlrpc.php for XML-RPC functions, but would query https://pear.example.com:8080/soapy.php for SOAP functions.

The <rest> tag reflects the design concept behind REST: each resource is defined by a base URL in tag <baseurl> that is then used by the installer along with hyperlinks to glean the same information that XML-RPC or SOAP would provide. Required attribute "type" tells the installer what version of the PEAR installer REST interface is provided at the base URL.

<function>

The <function> tag is quite simple. A required version attribute informs the installer what the API is, and the text content informs the installer what the name of the function is. Note that multiple functions with different versions can co-exist peacefully, as in:

<function version="1.0">package.getDownloadURL</function>
<function version="1.1">package.getDownloadURL</function>

If a newer API is backwards-compatible, always define every possible API version in order to prevent older installer versions from giving up.

Why not use a standard such as wsdl?

Some of you may be asking "why create another standard for web services discovery?" The answer is simple: channel.xml does not supplant the role that WSDL has for java, or XML-RPC introspection occupies. channnel.xml is a layer on top of these technologies. The point is to quickly list the remote protocols that are supported, not to describe what they do.

The PEAR installer is specialized enough that a generic listing of parameters and return values is entirely unnecessary: the installer knows exactly what xml-rpc function package.info version 1.0 requires and what it returns. Any other information simply adds wasted bandwidth and disk space.

Prev | channel.xml, REST, XML-RPC | Next
channel.xml, REST, XML-RPC | PEAR Manual | PEAR channel server REST interface


PEAR channel server REST interface

PEAR channel server REST interface

This manual section describes how the REST interface of a PEAR channel server works, as well as the files and their formats look like.

Directory structure

A REST channel server simply delivers files in a certain directory structure. The content of those files is static. Their location is relative to the URLs given in the channel.xml baseurl tags.

Note: All files are static - you do not need a scripting language installed on your server.

The following table lists all known files, a tiny description as well as the version they appeared in first.

Directory- and file structure
Level 0 | Level 1 | Level 2 | Description | REST version
c/ |  |  | Categories | 1.0
 | categories.xml |  | List of all categories | 1.1
 | $CategoryName/ |  |  | 1.0
 |  | info.xml | Info about the category | 1.0
 |  | packages.xml | List of packages in category | 1.0
 |  | packagesinfo.xml | Info about all packages | 1.1
m/ |  |  | Maintainers | 1.0
 | allmaintainers.xml |  | List of all maintainers | 1.1
 | $maintainernick/ |  |  | 1.0
 |  | info.xml | Info about the maintainer | 1.0
p/ |  |  | Packages | 1.0
 | packages.xml |  | List of all packages | 1.0
 | $packagename/ |  |  | 1.0
 |  | info.xml | General package information | 1.0
 |  | maintainers.xml | List of package maintainers | 1.0
 |  | maintainers2.xml | List of developers and their roles | 1.2
r/ |  |  | Releases | 1.0
 | $packagename/ |  |  | 1.0
 |  | allreleases.xml | List of all releases | 1.0
 |  | allreleases2.xml | List of all releases including minimum PHP version | 1.3
 |  | latest.txt | Latest version number | 1.0
 |  | stable.txt | Latest stable version number | 1.0
 |  | beta.txt | Latest beta version number | 1.0
 |  | alpha.txt | Latest alpha version number | 1.0
 |  | devel.txt | Latest development version number | 1.0
 |  | 0.1.2.xml | Short package info for version 0.1.2 | 1.0
 |  | v2.0.1.2.xml | Short version of package.xml, version 2 | 1.3
 |  | package.0.1.2.xml | package.xml for version 0.1.2 | 1.0
 |  | deps.0.1.2.txt | Serialized dependencies for version 0.1.2 | 1.0

File formats

Here you will find detailled description of the file formats used for the REST interface.

Note: In file names that contain version numbers, we use 0.1.2 as example.

In general, the files try to be as small as possible so that only little bandwidth is required to fetch them. That's why all of the xml files (except the original package.xml have only tag names of one or two characters. Remember that operations like pear list-all download a large number of files, so every saved bit helps.

channel.xml

Information about the channel

This is the main file for a channel; nothing works without it. When discovering a channel, this file is retrieved. It defines the REST directory locations as well as mirrors.

The channel <name> is a full qualified domain name and is used as part of the URL when e.g. updating the channel.xml file.

PEAR provides aliases for channels as shortcuts in the daily work of your user's lifes. The <suggestedalias> should be a short and easy to write word. Benefit is that, instead of

pear install pear.mynicelittlespaceon.example.org/package

they just can type

pear install nice/package

if the alias was nice.

Location

/channel.xml

It needs to be in the root directory of the domain. While all other files can be located somewhere deep in a directory structure, channel.xml needs to be in /.

Example

<?xml version="1.0" encoding="utf-8"?>
<channel version="1.0"
         xmlns="http://pear.php.net/channel-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pear.php.net/channel-1.0
                             http://pear.php.net/dtd/channel-1.0.xsd"
>
 <name>pear.example.org</name><!-- URL, used to update channel.xml and such -->
 <suggestedalias>example</suggestedalias>
 <summary>Simple demo channel server</summary>
 <servers>
  <primary>
   <!-- you can ignore xmlrpc, it's deprecated anyway -->
   <xmlrpc>
    <function version="1.0">logintest</function>
    <function version="1.0">package.listLatestReleases</function>
    <function version="1.0">package.listAll</function>
    <function version="1.0">package.info</function>
    <function version="1.0">package.getDownloadURL</function>
    <function version="1.1">package.getDownloadURL</function>
    <function version="1.0">package.getDepDownloadURL</function>
    <function version="1.1">package.getDepDownloadURL</function>
    <function version="1.0">package.search</function>
    <function version="1.0">channel.listAll</function>
   </xmlrpc>
   <rest>
    <baseurl type="REST1.0">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.1">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.2">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.3">http://pear.example.org/rest/</baseurl>
   </rest>
  </primary>

  <mirror host="us.pear.example.org">
   <rest>
    <baseurl type="REST1.0">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.1">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.2">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.3">http://us.pear.example.org/rest/</baseurl>
   </rest>
  </mirror>

  <mirror host="de.pear.example.org" ssl="yes" port="3452">
   <rest>
    <baseurl type="REST1.0">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.1">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.2">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.3">https://de.pear.example.org:3452/rest/</baseurl>
   </rest>
  </mirror>

 </servers>
</channel>

categories.xml

List of all categories

Provides a names and links to for all categories known on the server. Links are URL-encoded.

Note: Unlike all other files, the channel name is wrapped in a <ch> instead of a plain <c> tag.

Location

c/categories.xml

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allcategories"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allcategories
                       http://pear.php.net/dtd/rest.allcategories.xsd"
>
 <ch>pear.example.org</ch>
 <c xlink:href="/rest/c/Tools/info.xml">Tools</c>
 <c xlink:href="/rest/c/Garbage%2Band%2BStuff/info.xml">Garbage and Stuff</c>
</a>

info.xml (category)

Information about a category

Here, the category is explained in detail. The file lists the name (<n>), channel server (<c>), alias (<a>) and a longer description of the category (<d>).

Location

c/${categoryname}/info.xml

Note: Category names may contain spaces and other special characters, so (x)links need to be url-encoded.

Example

<?xml version="1.0" encoding="utf-8" ?>
<c xmlns="http://pear.php.net/dtd/rest.category"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.category
                       http://pear.php.net/dtd/rest.category.xsd"
>
 <n>Tools</n>
 <c>pear.example.org</c>
 <a>Tools and Utilities</a>
 <d>This category holds all sorts of packages that might help you when
  trying to dominate the world.</d>
</c>

packages.xml (category)

List of all packages in category

The file simply contains a list of names and links to each package in the category.

Location

c/${categoryname}/packages.xml

Note: Category names may contain spaces and other special characters, so (x)links need to be url-encoded.

Example

<?xml version="1.0" encoding="utf-8" ?>
<l xmlns="http://pear.php.net/dtd/rest.categorypackages"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.categorypackages
                       http://pear.php.net/dtd/rest.categorypackages.xsd"
>
 <p xlink:href="/rest/p/earth">Earth</p>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
</l>

packagesinfo.xml

Extendet information about all packages

packagesinfo.xml is a collection of information about packages in the category. It contains the contents of the package's info.xml, release information from allreleases.xml and dependency information for each version.

Every package information piece is wrapped in an <pi> tag.

Location

c/${categoryname}/packagesinfo.xml

Note: Category names may contain spaces and other special characters, so (x)links need to be url-encoded.

Usage

Provides "summary" information in the list-all commmand.

Example

<?xml version="1.0" encoding="utf-8" ?>
<f xmlns="http://pear.php.net/dtd/rest.categorypackageinfo"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.categorypackageinfo
                       http://pear.php.net/dtd/rest.categorypackageinfo.xsd"
>
 <pi>
  <p>
   <n>WorldDominator</n>
   <c>pear.example.org</c>
   <!-- Full contents of p/${packagename}/info.xml follow -->
  </p>
  <a>
   <r><v>1.1.2</v><s>stable</s></r>
   <r><v>0.1.2</v><s>beta</s></r>
   <r><v>0.0.1</v><s>devel</s></r>
  </a>
  <deps>
   <v>0.1.2</v>
   <d><!-- serialized dependency information like deps.0.1.2.txt --></d>
  </deps>
  <deps>
   <v>0.0.1</v>
   <d><!-- serialized dependency information like deps.0.1.2.txt --></d>
  </deps>
 </pi>
</f>

allmaintainers.xml

Lists all maintainers

Simply lists names and links to all developers of any package on the server.

FIXME: full names or just nicks? FIXME: lowercased nicks?

Location

m/allmaintainers.xml

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.allmaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allmaintainers
                       http://pear.php.net/dtd/rest.allmaintainers.xsd"
>
 <h xlink:href="/rest/m/pinky">pinky</h>
 <h xlink:href="/rest/m/thebrain">the brain</h>
</m>

info.xml (maintainer)

Information about a maintainer

Contains maintainer information like handle (nickname, <h>), full name (<n>) and URL (<u>) to the developer's homepage.

Location

m/${maintainernick}/info.xml

FIXME: lowercasednick?

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.maintainer"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.maintainer
                       http://pear.php.net/dtd/rest.maintainer.xsd"
>
 <h>thebrain</h>
 <n>The Brain</n>
 <u>http://pinkyandthebrain.example.org</u>
</m>

packages.xml (p)

List of all packages

This file lists all packages in this channel, together with the channel server name itself.

Package names should not contain any spaces; the behavior of the installer in such cases is undefined.

Location

p/packages.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allpackages"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allpackages
                       http://pear.php.net/dtd/rest.allpackages.xsd"
>
 <c>pear.example.org</c>
 <p>Earth</p>
 <p>WorldDominator</p>
</a>

info.xml (package)

Information about a package

This file contains general version-independent information about the package: License, category, summary, description and a link to the release directory.

Location

r/${packagename}/info.xml

Note: The package name is lowercased.

Usage

remote-info fetches this file and displays its information.

Example

<?xml version="1.0" encoding="utf-8" ?>
<p xmlns="http://pear.php.net/dtd/rest.package"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.package
                       http://pear.php.net/dtd/rest.package.xsd"
>
 <n>WorldDomination</n>
 <c>pear.example.org</c>
 <ca xlink:href="/rest/c/Tools">Tools</ca>
 <l>Dictatoric License</l>
 <s>Tool to dominate the world</s>
 <d>
  Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42
 </d>
 <r xlink:href="/rest/r/worlddomination"/>
</p>

maintainers.xml

Lists all developers on the package

All package developers are listed in this file, regardless if active or inactive.

Each maintainer's handle (<h>) and activity state (<a>, 0 for inactive, 1 for active) is provided.

Location

r/${packagename}/maintainers.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.packagemaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.packagemaintainers
                       http://pear.php.net/dtd/rest.packagemaintainers.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <m>
  <h>pinky</h>
  <a>1</a>
 </m>
 <m>
  <h>thebrain</h>
  <a>1</a>
 </m>
 <m>
  <h>deadcow</h>
  <a>0</a>
 </m>
</m>

maintainers2.xml

Lists package developers

Same as maintainers.xml, except that the developer's role is written down, too.

Valid role names are lead, developer, contributor and helper.

Location

r/${packagename}/maintainers2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.packagemaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.packagemaintainers
                       http://pear.php.net/dtd/rest.packagemaintainers.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <m>
  <h>pinky</h>
  <a>1</a>
  <r>developer</r>
 </m>
 <m>
  <h>thebrain</h>
  <a>1</a>
  <r>lead</r>
 </m>
 <m>
  <h>deadcow</h>
  <a>0</a>
  <r>helper</r>
 </m>
</m>

allreleases.xml

List of all package versions

This file lists all known versions of a package, together with its stability.

Releases in this file are ordered, the latest version has to be first.

Location

r/${packagename}/allreleases.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allreleases"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allreleases
                       http://pear.php.net/dtd/rest.allreleases.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <r><v>0.8.1</v><s>beta</s></r>
 <r><v>0.0.2</v><s>alpha</s></r>
</a>

allreleases2.xml

List of all package versions with PHP version

Same as allreleases.xml, but with information about the minimum version of PHP required.

Location

r/${packagename}/allreleases2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allreleases2"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allreleases2
                       http://pear.php.net/dtd/rest.allreleases2.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <r><v>0.8.1</v><s>beta</s><m>4.4.2</m></r>
 <r><v>0.0.2</v><s>alpha</s><m>5.2.3</m></r>
</a>

latest.txt

The latest package version

The only content of this file is the version number of the latest version in pure plain text. The stability state does not matter; the highest version number is written down here.

Location

r/${packagename}/latest.txt

Note: The package name is lowercased.

This file does not exist when no release has been made yet.

Example

A package has a stable version 1.0.0, two beta versions 0.9.8 and 1.0.9 and a development version 1.0.1. The highest version number is 1.0.9, and this is put in latest.txt.

1.0.9

stable.txt

The latest stable version

The only content of this file is the version number of the latest stable version in pure plain text.

Location

r/${packagename}/stable.txt

Note: The package name is lowercased.

This file does not exist when no stable release exists.

Example

0.1.2

beta.txt

The latest beta version

The only content of this file is the version number of the latest beta version in pure plain text.

Location

r/${packagename}/beta.txt

Note: The package name is lowercased.

This file does not exist when the package has no beta version.

Example

0.1.2

alpha.txt

The latest alpha version

The only content of this file is the version number of the latest alpha version in pure plain text.

Location

r/${packagename}/alpha.txt

Note: The package name is lowercased.

This file does not exist when no alpha release exists.

Example

0.1.2

devel.txt

The latest development version

The only content of this file is the version number of the latest development version in pure plain text.

Location

r/${packagename}/devel.txt

Note: The package name is lowercased.

This file does not exist when no development release exists.

Example

0.1.2

0.1.2.xml (release)

Short xml file about the release

This file is a special size-optimized version of the full package.xml with only necessary information.

As in package.xml, the tag order is important and may not be shuffled.

Location

r/${packagename}/0.1.2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<r xmlns="http://pear.php.net/dtd/rest.release"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.release
                       http://pear.php.net/dtd/rest.release.xsd"
>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
 <c>pear.example.org</c>
 <v>0.1.2</v>
 <st>beta</st>
 <l>Dictatoric License</l>
 <m>thebrain</m>
 <s>Tool to dominate the world</s>
 <d>Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42</d>
 <da>2007-12-24 23:42:00</da>
 <n>* Fix atomic X-mas bug [thebrain]</n>
 <f>19588</f>
 <g>http://pear.example/get/WorldDominator-0.1.2</g>
 <x xlink:href="package.0.1.2.xml"/>
</r>

Tags

Tag description
Tag name | Description
<p> | Package name inclusive absolute path to the package directory
<c> | Channel server name
<v> | Release version
<st> | Stability state (e.g. stable, beta etc.)
<l> | License name
<m> | Handle/nickname of the releasing developer
<s> | Summary
<d> | Description, multiline
<da> | Date and time of release
<n> | Release notes
<f> | File size of the tgz in bytes
<g> | Full URL to the release archive
<x> | Link to the version's package.xml file.

v2.0.1.2.xml

Short xml file about the release, version 2

Same as 0.1.2.xml , but with additional API and minimum PHP version.

Location

r/${packagename}/v2.0.1.2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<r xmlns="http://pear.php.net/dtd/rest.release2"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.release2
                       http://pear.php.net/dtd/rest.release2.xsd"
>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
 <c>pear.example.org</c>
 <v>0.1.2</v>
 <a>0.1.2</a>
 <mp>5.2.3</mp>
 <st>beta</st>
 <l>Dictatoric License</l>
 <m>thebrain</m>
 <s>Tool to dominate the world</s>
 <d>Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42</d>
 <da>2007-12-24 23:42:00</da>
 <n>* Fix atomic X-mas bug [thebrain]</n>
 <f>19588</f>
 <g>http://pear.example/get/WorldDominator-0.1.2</g>
 <x xlink:href="package.0.1.2.xml"/>
</r>

Tags

New tags compared to 0.1.2.xml.

Tag description
Tag name | Description
<a> | API version
<mp> | Minimum PHP version

package.0.1.2.xml

Full package.xml

Full package.xml for the release. May be version 1 or version 2 of the package.xml format. The highest version should be made available if the package contains both.

Location

r/${packagename}/package.0.1.2.xml

Note: The package name is lowercased.

deps.0.1.2.txt

Serialized dependency information

The file contains an array of dependency information, serialized with PHP's serialize() function.

Location

r/${packagename}/deps.0.1.2.txt

Note: The package name is lowercased.

Example of an dependency array, unserialized and in xml

array(2) {
  ["required"]=>
  array(2) {
    ["php"]=>
    array(1) {
      ["min"]=>
      string(5) "5.2.3"
    }
    ["pearinstaller"]=>
    array(1) {
      ["min"]=>
      string(7) "1.7.1"
    }
  }
  ["optional"]=>
  array(1) {
    ["package"]=>
    array(2) {
      ["name"]=>
      string(4) "Toolbox"
      ["channel"]=>
      string(12) "pear.example.org"
      ["min"] =>
      string(7) "1.3.0"
    }
  }
}
<dependencies>
  <required>
   <php>
    <min>5.2.3</min>
   </php>
   <pearinstaller>
    <min>1.7.1</min>
   </pearinstaller>
  </required>
  <optional>
   <package>
    <name>Toolbox</name>
    <channel>pear.example.org</channel>
    <min>1.3.0</min>
   </package>
  </optional>
 </dependencies>

REST version history

This page lists the known REST versions and their changes they introduced.

REST 1.0

This was the initial and first supported version of the REST interface.

REST 1.1

This version added files to allow spidering channels without requiring the server to have directory listings enabled. These files are:

  • c/categories.xml

  • c/$categoryname/packagesinfo.xml

  • m/allmaintainers.xml

REST 1.2

Now the developer's roles are listed in the package's maintainer list.

  • p/${packagename}/maintainers2.xml

REST 1.3

This version makes it possible to resolve PHP version incompatibilities by downloading the releases list only. allreleases2.xml lists the minimum PHP version for each package release, thus the package name does not need to be changed when upgrading the package's minimun PHP version.

  • r/${packagename}/allreleases2.xml

  • r/${packagename}/v2.0.1.2.xml

Use cases

This section shows common actions on a channel server and what to do then.

The idea and initial cases have been taken from Jean-Lou Dupont's "PEAR Channel on Google Code" presentation.

Adding a new category

When creating a fresh category on your channel server, the following steps are necessary:

  1. Create c/${CategoryName} directory.

  2. Create the following files:

    • c/${CategoryName}/info.xml

    • c/${CategoryName}/packages.xml

    • c/${CategoryName}/packagesinfo.xml

  3. Update c/categories.xml .

Adding a new package

A new package shall be published on the server, and here are the steps you need to do:

  1. Check if the package category already exists, or a new category needs to be created.

  2. Create the package directory p/${packagename}/.

  3. Create those files:

    • r/${packagename}/info.xml

    • r/${packagename}/maintainers.xml

    • r/${packagename}/maintainers2.xml

  4. Update the category files:

    • c/${CategoryName}/packages.xml

    • c/${CategoryName}/packagesinfo.xml

Adding a release

The time has come to release a new version of an existing package. Those are the steps to do:

  1. Publish the release's package.xml as r/${packagename}/package.0.1.2.xml .

  2. Create the version specific r/${packagename}/0.1.2.xml .

  3. Update state files if appropriate: r/${packagename}/latest.txt , stable.txt , beta.txt , alpha.txt , devel.txt .

  4. Generate r/${packagename}/deps.0.1.2.xml .

  5. Update r/${packagename}/allreleases.xml and r/${packagename}/allreleases2.xml .

  6. Place package archives (tar and tgz) at the place specified in r/${packagename}/0.1.2.xml .

Channel server software

While you can use this documentation to build you own channel server, it is possibly easier for you to either get your package into PEAR itself, or setup your own channel server. The reference implementation of a PEAR channel server is the PEAR website itself, but it should not be used for your own server.

If you seek for an easy-to-setup software, try Chiara_PEAR_Server which resides on its own channel http://pear.chiaraquartet.net.

Another project is the SimpleChannelServer in SVN. The project is under development, though.

Prev | channel.xml, REST, XML-RPC | Next
channel.xml: The channel definition file | PEAR Manual | (deprecated) XML-RPC functions


(deprecated) XML-RPC functions

(deprecated) XML-RPC functions

What XML-RPC functions are available in a standard channel?

A standard PEAR channel should support this list of XML-RPC functions:

  • logintest - a stub function

  • package.getDownloadURL - retrieve a URL to download a package

  • package.getDepDownloadURL - retrieve a URL to download a package dependency

  • package.info - retrieve information on a package

  • package.listAll - list all packages and verbose information on each package

  • package.listLatestReleases - list all packages and their latest release versions

  • package.search - search all packages for a match

Channels can also implement channel.listAll, but we recommend that this only be implemented by pear.php.net and pecl.php.net channels, as the command is utilized by the update-channels command to retrieve an official list of channels.

logintest

The logintest xml-rpc function is called by the login command, and should return a boolean TRUE

package.getDownloadURL

false|struct package.getDownloadURL ( struct packageinfo , string preferred_state = stable , (v1.1) string installed_version = false )

false|struct packageinfo

an array of format:

array(
        'channel' => channel name,
        'package' => package name,
        ['version' => specific version to retrieve,]
        ['state' => specific state to retrieve,]
     )

if both version and state are set, the version index should be ignored.

string preferred_state = stable

The client-side preferred_state. This should be used to exclude releases that are too unstable.

string installed_version = false

The current installed version of the package on the client-side. This will either be a version string, or false if the package is not installed. Use this to ensure that older versions are never returned (as defined by version_compare(possible_version, installed_version, "<")).

The package.getDownloadURL function should return an array with either two or three indices.

  • "version" => version of the release returned

  • "info" => the complete package.xml contents from the release

  • "url" => a URL from which to download this release. If no releases exist that fit the constraints defined by preferred_state, installed_version, and the version/state indices of packageinfo, then do not return this index, and instead return the version and package.xml of the latest release.

    The url entry should NOT append .tgz or .tar, but should be something like "http://pear.php.net/get/PEAR-1.4.0" instead of "http://pear.php.net/get/PEAR-1.4.0.tgz"

Note that version 1.0 of package.getDownloadURL did not have the installed_version parameter. Version 1.1 of package.getDownloadURL does - that is the only difference between the two versions.

package.getDepDownloadURL

false|struct package.getDepDownloadURL ( string xsdversion , struct dependency , struct parentpackage , string preferred_state = stable , (v1.1) string installed_version = false )

string xsdversion

This should be either '1.0' or '2.0', and should match the version attribute from the top-level <package version="X.0"> tag. This should be used to determine how to process the second parameter.

struct dependency

if the first parameter xsdversion is '1.0', this should be an array of format:

array(
        'name' => package name
        'type' => 'pkg' - anything else is an error
        'rel' => 'has', 'ge', 'le', 'lt', 'le', 'not', 'ne'
        ['version' => specific version to retrieve,]
     )

if xsdversion is '2.0', this should be an array of format:

array(
        'name' => package name
        'channel' => package channel - see notes below
        ['min' => minimum version (inclusive),]
        ['max' => maximum version (inclusive),]
        ['exclude' => single version to exclude (string),
                      or array of versions to exclude,]
     )

Note that you must always verify that the channel matches your channel. If your channel server is not at pear.php.net or pecl.php.net, you must reject all xsdversion='1.0' requests, and all xsdversion='2.0' requests where the channel is not your channel.

struct parentpackage

This is information on the parent package, and is an array of format:

array(
        'channel' => channel name,
        'package' => package name,
        'version' => specific version to retrieve,
     )

string preferred_state = stable

The client-side preferred_state. This should be used to exclude releases that are too unstable.

string installed_version = false

The current installed version of the dependency on the client-side. This will either be a version string, or false if the package is not installed. Use this to ensure that older versions are never returned (as defined by version_compare(possible_version, installed_version, "<")).

Like package.getDownloadURL, package.getDepDownloadURL should return an array with either two or three indices.

  • "version" => version of the release returned

  • "info" => the complete package.xml contents from the release

  • "url" => a URL from which to download this release. If no releases exist that fit the constraints defined by preferred_state, installed_version, and the version/state indices of packageinfo, then do not return this index, and instead return the version and package.xml of the latest release.

    The url entry should NOT append .tgz or .tar, but should be something like "http://pear.php.net/get/PEAR-1.4.0" instead of "http://pear.php.net/get/PEAR-1.4.0.tgz"

Note that version 1.0 of package.getDepDownloadURL did not have the installed_version parameter. Version 1.1 of package.getDepDownloadURL does - that is the only difference between the two versions.

package.info

false|struct package.info ( string package , string field = null )

string package

Package name to retrieve information about

string field = null

specific field to retrieve information about. If null, this should return an array with this indices, although others could be set as well:

<?php
array(
    'name' => 'package name',
    'category' => 'category name',
    'license' => 'package license',
    'summary' => 'package summary',
    'description' => 'package description',
    'releases' =>
    array( // all releases indexed by version
        '0.1' =>
        array(
          'license' => 'release license',
          'summary' => 'release summary',
          'description' => 'release description',
          'releasedate' => 'date of release',
          'releasenotes' => 'release notes',
          'state' => 'release stability',
          // the next index is optional
          'deps' =>
          array(
            array( // release dependencies of latest release
              'type' => 'dep type from package.xml <dep>',
              'relation' => 'rel from package.xml <dep>',
              'version' => 'version from package.xml <dep>, or empty string',
              'name' => 'name from package.xml <dep>',
              'optional' => 'yes or no',
            ),
            // and so on with all deps
          ),
        ),
        // and so on with all releases
        // releases should be ordered by releasedate DESC
    ),
);
?>

The second parameter, if set, must be one of these choices:

  • authors - a current list of package maintainers in format:

    <?php
    array(
            'handle1' =>
        array(
              'name' => 'Maintainer Name',
              'email' => 'maintainer@example.com',
              'role' => 'role from package.xml (lead, developer, contributor, helper)',
        ),
            'handle2' =>
        array(
              'name' => 'Maintainer Name 2',
              'email' => 'maintainer2@example.com',
              'role' => 'role from package.xml (lead, developer, contributor, helper)',
        ),
            // etc.
    );
    ?>

  • category - the category this package is in

  • description - the description of the latest release

  • license - package license of latest release

  • notes - release notes of the latest release

  • releases - an array of the format documented above, containing information on all releases

  • summary - summary from latest release

package.listAll

struct package.listAll ( bool released_only = true , bool stable_only = true )

bool released_only = true

If TRUE, then packages that have no releases should not be returned in the listing of available packages

bool stable_only = true

If TRUE, then packages that have no stable releases should not be returned in the listing of available packages

This function should return an array of this format for all packages that match the constraints defined above:

<?php
array(
  array(
    'name' => 'packagename',
    'category' => 'category name',
    'license' => 'release license',
    'summary' => 'package summary',
    'description' => 'package description',
    'stable' => 'latest release version that matches constraints',
    'unstable' => 'latest unstable release version or false if stable_only',
    'state' => 'release state of latest release that matches constraints',
    'deps' =>
    array( // same format as for package.info
    )
  ),
  // etc.
);
?>

package.listLatestReleases

struct package.listLatestReleases ( string state = '' )

string state = ''

If '', then the newest release will be returned for all packages. Otherwise, it must be one of 'snapshot', 'devel', 'alpha', 'beta', or 'stable', and the function should return the newest release that is more stable than state.

If state is 'beta', then the function should return the latest release that is beta or stable. If state is 'devel', the function should return the latest release that is devel, alpha, beta, or stable, and so on.

This function should return an array of this format for all packages that have a release within the constraint defined by the "state" parameter:

<?php
array(
  array(
    'package' => 'packagename',
    'version' => 'release version',
    'state' => 'release stability',
    'filesize' => 'size of the .tgz file to download',
  ),
  // etc.
);
?>

package.search

struct package.listAll ( string fragment , string|bool summary = false , bool released_only = true , bool stable_only = true )

string fragment

A text fragment to use when searching for packages by name

string|bool summary = false

If set to false, this should be ignored. Otherwise, this should be used to search through the summaries of packages that match the first parameter to limit the list of returned packages.

bool released_only = true

If TRUE, then packages that have no releases should not be returned in the listing of available packages

bool stable_only = true

If TRUE, then packages that have no stable releases should not be returned in the listing of available packages

This function should return an array of this format for all packages that match the constraints defined above:

<?php
array(
  array(
    'name' => 'packagename',
    'category' => 'category name',
    'license' => 'release license',
    'summary' => 'package summary',
    'description' => 'package description',
    'stable' => 'latest release version that matches constraints',
    'unstable' => 'latest unstable release version or false if stable_only',
    'state' => 'release state of latest release that matches constraints',
    'deps' =>
    array( // same format as for package.info
    )
  ),
  // etc.
);
?>
Prev | channel.xml, REST, XML-RPC | Next
PEAR channel server REST interface | PEAR Manual | Creating your own channel with Pyrus and PEAR2_SimpleChannelServer


Creating your own channel with Pyrus and PEAR2_SimpleChannelServer

Creating your own channel with Pyrus and PEAR2_SimpleChannelServer

Table of Contents
  • Introduction to PEAR2_SimpleChannelServer
  • Commands Available In PEAR2_SimpleChannelServer

Edited By

Brett Bieber

2009-07-01

Documentation is a work in progress.

Prev | Channels: distributing your packages | Next
(deprecated) XML-RPC functions | PEAR Manual | Introduction to PEAR2_SimpleChannelServer


Introduction to PEAR2_SimpleChannelServer

Introduction to PEAR2_SimpleChannelServer

The SimpleChannelServer package allows developers to create a PEAR compatible channel server to distribute packages. This channel server is simple in that it only works with the local filesystem to create the necessary files for package distribution.

Note: At a minimum, the ability to post files to the webspace where your channel will be hosted.

It is possible to host your PEAR channel on webspace such as Google Code, just use the webpath to the svn directory as your channel name, and be sure to set the correct svn:mime-type on the xml files.

To get started, simply download the pearscs.phar file to your local filesystem, and execute the pearscs.phar file with the create command. Then, build the rest of the channel using the other SimpleChannelServer commands.

Prev | Creating your own channel with Pyrus and PEAR2_SimpleChannelServer | Next
Creating your own channel with Pyrus and PEAR2_SimpleChannelServer | PEAR Manual | Commands Available In PEAR2_SimpleChannelServer


Commands Available In PEAR2_SimpleChannelServer

Commands Available In PEAR2_SimpleChannelServer

The SimpleChannelServer command line script supports the following commands.

  • create - Creates a channel

  • release - Releases a package

  • update - Updates an existing PEAR channel

    Note: This command will scan the /get/ directory for all packages, and release them.

  • add-maintainer - Adds a maintainer to the channel

  • add-category - Adds a package category to the channel

Prev | Creating your own channel with Pyrus and PEAR2_SimpleChannelServer | Next
Introduction to PEAR2_SimpleChannelServer | PEAR Manual | PEAR Packages


PEAR Packages

PEAR Packages

Table of Contents
  • Authentication
  • Benchmarking
  • Caching
  • Configuration
  • Console
  • Database
  • Date and Time
  • Encryption
  • Event
  • File Formats
  • File System
  • Gtk
  • Gtk2
  • HTML
  • HTTP
  • Images
  • Internationalization
  • Logging
  • Mail
  • Math
  • Networking
  • Numbers
  • PEAR
  • PHP
  • QA Tools
  • Streams
  • Structures
  • System
  • Text
  • Tools and Utilities
  • Validate
  • Web Services
  • XML
Prev |  | Next
Commands Available In PEAR2_SimpleChannelServer | PEAR Manual | Authentication


Authentication

Authentication

Provides Packages for authentication management

Table of Contents
  • Auth
  • Auth_HTTP
  • Auth_PrefManager
  • Auth_RADIUS
  • LiveUser
  • LiveUser_Admin
Prev | PEAR Packages | Next
PEAR Packages | PEAR Manual | Auth


Auth

Auth

Provides a framework for user authentication.

Table of Contents
  • Introduction -- A usage example
  • Auth Options -- Options for controlling the behaviour of Auth
  • Logging -- Introduction
  • Storage drivers -- Introduction
  • Auth_Container_Array -- Authenticate against an array of usernames and passwords
  • Auth_Container_DB -- Authenticate against a database using DB
  • Auth_Container_DBLite -- Authenticate against a database using DB
  • Auth_Container_File -- Authenticate a password file using File_Passwd
  • Auth_Container_IMAP -- Authenticate against an IMAP server
  • Auth_Container_KADM5 -- Authenticate against a Kerberos 5 server
  • Auth_Container_LDAP -- Authenticate against an LDAP server
  • Auth_Container_MDB -- Authenticate against a database using MDB
  • Auth_Container_MDB2 -- Authenticate against a database using MDB2
  • Auth_Container_Multiple -- Authenticate against multiple Auth_Containers
  • Auth_Container_PEAR -- Authenticate against the PEAR website
  • Auth_Container_POP3 -- Authenticate against a POP3 server
  • Auth_Container_RADIUS -- Authenticate against a RADIUS server
  • Auth_Container_SAP -- Authenticate against a SAP server
  • Auth_Container_SMBPasswd -- Authenticate a SAMBA smbpasswd file using File_SMBPasswd
  • Auth_Container_SOAP -- Authenticate against a SOAP service
  • Auth_Container_SOAP5 -- Authenticate against a SOAP service
  • Auth_Container_vpopmail -- Authenticate against a vpopmail service
  • Custom Auth_Container -- Build a custom storage container
  • Auth_Frontend_HTML -- Default login form
  • Constants -- predefined constants
  • Auth::Auth() -- constructor
  • Auth::addUser() -- add a new user
  • Auth::attachLogObserver() -- Attach a log observer instance to the internal Log object
  • Auth::changePassword() -- change the password of a user
  • Auth::checkAuth() -- check if a session with valid authentication information exists
  • Auth::getAuth() -- check for an authenticated user
  • Auth::getAuthData() -- retrieve extra information stored within the auth session
  • Auth::getStatus() -- get the current status of the auth session
  • Auth::getUsername() -- get the username of the authenticated user
  • Auth::listUsers() -- list available users
  • Auth::logout() -- logout an authenticated user
  • Auth::removeUser() -- remove a user account
  • Auth::setAdvancedSecurity() -- Enables advanced security features. Turned off by default
  • Auth::setAllowLogin() -- Controls if the user will be allowed to login. Turned on by default
  • Auth::setAuth() -- set a specific user to be marked as logged in
  • Auth::setAuthData() -- store extra information with the Auth session
  • Auth::setCheckAuthCallback() -- set a callback to run when ever session validity is checked
  • Auth::setExpire() -- set expiration time for authentication
  • Auth::setFailedLoginCallback() -- set a callback for failed login attempts
  • Auth::setIdle() -- set maximum idle time for authentication
  • Auth::setLoginCallback() -- set a callback for successful login attempts
  • Auth::setLogoutCallback() -- set a callback for successful logout attempts
  • Auth::setSessionName() -- set a custom name for the Auth session variable
  • Auth::setShowLogin() -- controls if the login form will be displayed. Turned on by default
  • Auth::sessionValidThru() -- get the time up to the session is valid
  • Auth::start() -- start authentication
Prev | Authentication | Next
Authentication | PEAR Manual | Introduction


Introduction

Introduction

Introduction – A usage example

Auth tutorial

Our goal during this "mini tutorial" is to set up a system that secures your site with an easy to use authentication mechanism.

At the top of the site to secure, place the following code snippet:

Typical usage example for PEAR::Auth

<?php
require_once "Auth.php";

// Takes three arguments: last attempted username, the authorization
// status, and the Auth object.
// We won't use them in this simple demonstration -- but you can use them
// to do neat things.
function loginFunction($username = null, $status = null, &$auth = null)
{
    /*
     * Change the HTML output so that it fits to your
     * application.
     */
    echo "<form method=\"post\" action=\"test.php\">";
    echo "<input type=\"text\" name=\"username\">";
    echo "<input type=\"password\" name=\"password\">";
    echo "<input type=\"submit\">";
    echo "</form>";
}

$options = array(
  'dsn' => "mysql://user:password@localhost/database",
  );
$a = new Auth("DB", $options, "loginFunction");

$a->start();

if ($a->checkAuth()) {
    /*
     * The output of your site goes here.
     */
}
?>

This few lines of code instantiate the authentication system.

The first line in the above script includes the file from your PEAR directory. It contains all the necessary code to run PEAR::Auth. Next, we define a function to display the login form which the visitor of your page has to use to enter his login data. You can change all the HTML formatting in this function.

Since we want to use a database to verify the login data, we now create the variable $dsn, it contains a valid DSN string that will be used to connect to the database via PEAR::DB. For the default database table schema or to use a different storage container, please see below for more information.

After that we create the authentication object. The first parameter defines the name of the storage container. Because we want to use a database driven storage container, we pass "DB" here. The second parameter is the connection parameter for the container driver. We use the previously defined DSN string. The third parameter is the name of our function that we defined at the beginning of the script. It prints the login form.

Now our authentication object is initialized and we need to check if the user is logged in. This is done via the method checkAuth(). If it returns TRUE, we can pass the content of our page to the user.

Using optional authentication

<?php
// In this test, the file is named "test.php".

require_once "Auth.php";

function loginFunction()
{
     /*
      * Change the HTML output so that it fits to your
      * application.
      */
     echo "<form method=\"post\" action=\"test.php?login=1\">";
     echo "<input type=\"text\" name=\"username\">";
     echo "<input type=\"password\" name=\"password\">";
     echo "<input type=\"submit\">";
     echo "</form>";
}

if (isset($_GET['login']) && $_GET['login'] == 1) {
     $optional = true;
} else {
     $optional = false;
}

$options = array(
  'dsn' => "mysql://user:password@localhost/database",
  );
$a = new Auth("DB", $options, "loginFunction", $optional);

$a->start();

echo "Everybody can see this text!<br />";

if (!isset($_GET['login'])) {
     echo "<a href=\"test.php?login=1\">Click here to log in</a>\n";
}

if ($a->getAuth()) {
     echo "One can only see this if he is logged in!";
}
?>

This is a pretty nice example for the optional login feature: The last parameter $optional can be either TRUE or FALSE. If it is FALSE, the login form is not shown and the user only sees the text "Everybody can see this text!". If he clicks on the link above this text, he gets the same page but with the GET parameter "login=1". Now he can enter his login information in the login form. If he successfully logs in, he can then see the text "Everybody can see this text!" and the text "One can only see this if he is logged in!".

Logout functionality

The following example performs a "logout" for the current user and displays the login form again.

<?php
$myauth->start();
if ($_GET['action'] == "logout" && $myauth->checkAuth()) {
    $myauth->logout();
    $myauth->start();
}
?>

In the following passages we cover more detailed information about the functions of PEAR::Auth.

This SQL statement creates a table usable under the default database authentication scheme using MySQL:

CREATE TABLE auth (
   username VARCHAR(50) default '' NOT NULL,
   password VARCHAR(32) default '' NOT NULL,
   PRIMARY KEY (username),
   KEY (password)
);

These are the table and field names necessary for working authentication. When hashing the passwords with the MD5 algorithm, which is the default encryption method in PEAR::Auth, the password column must be at least 32 characters long. When using another encryption method like DES ("UNIX crypt"), the column size has to be changed correspondingly.

Prev | Auth | Next
Auth | PEAR Manual | Auth Options


Auth Options

Auth Options

Auth Options – Options for controlling the behaviour of Auth

Auth Options

In addition to the options available for each container a series of options can be included that control the behaviour of Auth itself.

Available Options
Option | Data Type | Default value | Description
"sessionName" | string | "_authsession" | The name used to identify this Auth session. See Auth::setSessionName()
"allowLogin" | boolean | TRUE | Whether to allow logins to be performed on this page. See Auth::setAllowLogin()
"postUsername" | string | "username" | The name of the form field that contains the username to authenticate.
"postPassword" | string | "password" | The name of the form field that contains the password to authenticate.
"advancedsecurity" | boolean | FALSE | Whether to enable the advanced security features. See Auth::setAdvancedSecurity()
"enableLogging" | boolean | FALSE | Whether to enable the internal logging system. See the Logging Examples and Auth::attachLogObserver()
"regenerateSessionId" | boolean | FALSE | Set to TRUE to regenerate the session id on every page load or leave as FALSE to regenerate only upon new login.
Prev | Auth | Next
Introduction | PEAR Manual | Logging


Logging

Logging

Logging – Introduction

Overview

Since version 1.5.0 PEAR::Auth provides a facility for retrieving logs of its internal behaviour. This is implemented using PEAR::Log and its log observer components.

Auth provides two levels of log messages which map to the Log priority levels PEAR_LOG_INFO and PEAR_LOG_DEBUG.

PEAR_LOG_INFO messages provide basic information about Auth's decisions, for example user authentication successful/failed, rendering login screen.

PEAR_LOG_DEBUG messages provide detailed information about what is happening within the internals of Auth, for example which functions are called, logic tracking for the Authentication method, what SQL queries are being run against the database backends.

Example

Typical usage example for accessing the logs from PEAR::Auth

<?php
require_once "Auth.php";
require_once 'Log.php';
require_once 'Log/observer.php';

// Callback function to display login form
function loginFunction($username = null, $status = null, &$auth = null)
{
    /*
     * Change the HTML output so that it fits to your
     * application.
     */
    echo "<form method=\"post\" action=\"".$_SERVER['PHP_SELF']."\">";
    echo "Username: <input type=\"text\" name=\"username\"><br/>";
    echo "Password: <input type=\"password\" name=\"password\"><br/>";
    echo "<input type=\"submit\">";
    echo "</form>";
}

class Auth_Log_Observer extends Log_observer {

    var $messages = array();

    function notify($event) {

        $this->messages[] = $event;

    }

}

$options = array(
        'enableLogging' => true,
        'cryptType' => 'md5',
        'users' => array(
            'guest' => md5('password'),
            ),
        );
$a = new Auth("Array", $options, "loginFunction");

$infoObserver = new Auth_Log_Observer(PEAR_LOG_INFO);

$a->attachLogObserver($infoObserver);

$debugObserver = new Auth_Log_Observer(PEAR_LOG_DEBUG);

$a->attachLogObserver($debugObserver);

$a->start();

if ($a->checkAuth()) {
    /*
     * The output of your site goes here.
     */
    print "Authentication Successful.<br/>";
}

print '<h3>Logging Output:</h3>'
    .'<b>PEAR_LOG_INFO level messages:</b><br/>';

foreach ($infoObserver->messages as $event) {
    print $event['priority'].': '.$event['message'].'<br/>';
}

print '<br/>'
    .'<b>PEAR_LOG_DEBUG level messages:</b><br/>';

foreach ($debugObserver->messages as $event) {
    print $event['priority'].': '.$event['message'].'<br/>';
}

print '<br/>';
?>

To enable logging pass the option "enableLogging" with the value TRUE in the options array in the second parameter to the Auth constructor.

To retrieve the log messages from Auth create a new subclass of Log_Observer that implements a notify() function to perform whatever actions you want on the log messages.

Once defined pass an instance of your new Log_Observer instance to Auth::attachLogObserver().

To limit the types of messages you receive in the Log_Observer pass either PEAR_LOG_INFO or PEAR_LOG_DEBUG as the first parameter to the Log_Observer. The default is PEAR_LOG_INFO. For more information on this filtering see the Log Documentation.

<?php
$observer = new My_Log_Observer(PEAR_LOG_DEBUG);
?>

Note

This container has only been available since version 1.5.0.

Prev | Auth | Next
Auth Options | PEAR Manual | Storage drivers


Storage drivers

Storage drivers

Storage drivers – Introduction

Overview

PEAR::Auth uses a number of so called storage containers to store the login data. The following passages describe all of them. If the containers that come with the package don't fit your needs, it is easy to create custom ones, also.

Available Containers

Array

Storage container using a PHP Array.

DB

Storage container using PEAR DB.

DBLite

A simplified version of the DB container that only provides user authentication. No user management functions are provided.

File

Storage container using PEAR File_Passwd.

IMAP

Storage container for use against IMAP servers.

KADM5

Storage container for use against Kerberos V servers.

LDAP

Storage container for use against LDAP servers.

MDB

Storage container using PEAR MDB.

MDB2

Storage container using PEAR MDB2.

Multiple

Storage container for using multiple Auth_Containers in a fall through manner.

PEAR

Storage container for use against the PEAR website.

POP3

Storage container for use against a POP3 server.

RADIUS

Storage container for use against a RADIUS server.

SAP

Storage container for use against a SAP server.

SMBPasswd

Storage container using PEAR File_SMBPasswd.

SOAP

Storage container for use against a SOAP service using PEAR SOAP as the client.

SOAP5

Storage container for use against a SOAP service using PHP5 SOAP as the client.

vpopmail

Storage container using vpopmail.

Custom

Instructions on creating a custom storage container.

Prev | Auth | Next
Logging | PEAR Manual | Auth_Container_Array


Auth_Container_Array

Auth_Container_Array

Auth_Container_Array – Authenticate against an array of usernames and passwords

Array

This storage container provides a simple way to store a limited number of username/password pairs within the source code of the script.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"cryptType" | string | "none" | The encryption type the password is stored in.
"users" array array() Named array of usernames and password hashes.
<?php
array(
    'guest' => '084e0343a0486ff05530df6c705c8bb4', // password guest
    'georg' => 'fc77dba827fcc88e0243404572c51325' // password georg
)
?>
Prev | Auth | Next
Storage drivers | PEAR Manual | Auth_Container_DB


Auth_Container_DB

Auth_Container_DB

Auth_Container_DB – Authenticate against a database using DB

DB Container

This container makes use of PEAR::DB abstraction layer for database access. That means that you can use all databases that are supported by the DB abstraction layer to store the login data.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"dsn" | string | " | A valid and well-formed DSN .
"table" | string | "auth" | The name of the database table, where the authorization data is stored.
"usernamecol" | string | "username" | The name of the column, where the username is stored
"passwordcol" | string | "password" | The name of the column, where the crypted password is stored.
"db_fields" | array | array() | An array of extra fields to retrieve when loading the user details.
"cryptType" | string | "md5" | The encryption type the password is stored in.
"auto_quote" | boolean | TRUE | Whether to enable automatic quoting of database table and field names.
"db_options" | array | array() | An array of options to be passed to the PEAR::DB constructor. See PEAR::DB::setOption() for more information.
"db_where" | string | " | A string to be appended to the WHERE clause of queries against the database. It is appended to the queries used in fetchData(), listUsers(), removeUser() and changePassword(). Available since Auth 1.5.0.
Prev | Auth | Next
Auth_Container_Array | PEAR Manual | Auth_Container_DBLite


Auth_Container_DBLite

Auth_Container_DBLite

Auth_Container_DBLite – Authenticate against a database using DB

DBLite Container

The DBLite container is a simplified version of the DB container. It does away with all the code related to user management and simply provides user authentication.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"dsn" | string | " | A valid and well-formed DSN .
"table" | string | "auth" | The name of the database table, where the authorization data is stored.
"usernamecol" | string | "username" | The name of the column, where the username is stored
"passwordcol" | string | "password" | The name of the column, where the crypted password is stored.
"db_fields" | array | array() | An array of extra fields to retrieve when loading the user details.
"cryptType" | string | "md5" | The encryption type the password is stored in.
"auto_quote" | boolean | TRUE | Whether to enable automatic quoting of database table and field names.
"db_options" | array | array() | An array of options to be passed to the PEAR::DB constructor. See PEAR::DB::setOption() for more information.
"db_where" | string | " | A string to be appended to the WHERE clause of queries against the database. It is appended to the queries used in fetchData(). Available since Auth 1.5.0.
Prev | Auth | Next
Auth_Container_DB | PEAR Manual | Auth_Container_File


Auth_Container_File

Auth_Container_File

Auth_Container_File – Authenticate a password file using File_Passwd

File Container

description

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"type" | string | "Cvs" | The format of the file we are authenticating against. For a list of available types see the PEAR::File_Passwd documentation.
"file" | string | " | The filename of the file to use.
Prev | Auth | Next
Auth_Container_DBLite | PEAR Manual | Auth_Container_IMAP


Auth_Container_IMAP

Auth_Container_IMAP

Auth_Container_IMAP – Authenticate against an IMAP server

IMAP Container

This storage container connects to the specified IMAP server and tries to login there with the specified username/password.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"host" | string | "localhost" | The hostname or the IP address of the IMAP server
"port" | integer | 143 | The port where the IMAP server is listening
"baseDSN" string "

This controls the methods used to connect. Like SSL, TLS and certificate validation.

To connect to an SSL IMAP server: "/imap/ssl"

To connect to an SSL IMAP server with a self-signed certificate: "'/imap/ssl/novalidate-cert'"

Further options may be available and can be found on the php site at http://www.php.net/manual/function.imap-open.php.

"timeout" | integer | 20 | Timeout in seconds for connecting to the server.
"checkServer" | boolean | TRUE | Whether to check if we can connect to the server when starting container.
Prev | Auth | Next
Auth_Container_File | PEAR Manual | Auth_Container_KADM5


Auth_Container_KADM5

Auth_Container_KADM5

Auth_Container_KADM5 – Authenticate against a Kerberos 5 server

KADM5 Container

This storage driver makes use of the PECL kadm5 extension to provide authentication services against a Kerberos V.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"hostname" | string | "localhost" | The hostname or IP address of the Kerberos V server.
"realm" | string | " | The Kerberos V realm to authenticate in.
"timeout" | integer | 10 | Timeout in seconds for connecting to the server.
"checkServer" | boolean | FALSE | Whether to check if we can connect to the server when starting container.
Prev | Auth | Next
Auth_Container_IMAP | PEAR Manual | Auth_Container_LDAP


Auth_Container_LDAP

Auth_Container_LDAP

Auth_Container_LDAP – Authenticate against an LDAP server

LDAP Container

This storage container makes use of the ldap extension to load user data from an LDAP server.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"host" | string | "localhost" | The host name or IP-adress to access
"port" | integer | 389 | The port of the LDAP server to access
"url" string " A fully qualified URL for specifying the protocol, url and port to connect to. It is useful for specifying ldaps://. Takes precedence over "host" and "port" options. Only works if PHP has been compiled against OpenLDAP 2+ libraries.
"version" | integer | 2 | LDAP version to use, usually 2 (default) or 3, must be an integer!
"referrals" | boolean | TRUE | If set, determines whether the LDAP library automatically follows referrals returned by LDAP servers or not.
"binddn" string " If set, searching for user will be done after binding as this user, if not set the bind will be anonymous. This is reported to make the container work with MS Active Directory, but should work with any server that is configured this way. This has to be a complete dn for now (basedn and userdn will not be appended).
"bindpw" string " The password to use for binding with binddn.
"basedn" string " The base DN of your server.
"userdn" string " Gets prepended to basedn when searching for users.
"userscope" | string | "sub" | Scope for user searching: one, sub (default), or base.
"userattr" | string | "uid" | Defines the attribute to search for.
"userfilter" | string | "(objectClass=posixAccount)" | Filter that will be added to the search filter this way: (&(userattr=username)(userfilter)).
"attributes" | array | array('') | Array of additional attributes to fetch from entry. These will added to auth data and can be retrieved via Auth::getAuthData() . An empty array will fetch all attributes, array('') will fetch no attributes at all (default). If you add 'dn' as a value to this array, the user's DN that was used for binding will be added to auth data as well.
"attrformat" string "AUTH"

The returned format of the additional data defined in the 'attributes' option. Two formats are available.

LDAP returns data formatted in a multidimensional array where each array starts with a 'count' element providing the number of attributes in the entry, or the number of values for attributes. When set to this format, the only way to retrieve data from the Auth object is by calling getAuthData('attributes'). This was the default format before version 1.3.0.

AUTH returns data formatted in a structure more compliant with other Auth Containers, where each attribute element can be directly called by getAuthData() method from Auth. This became the default as of 1.3.0.

"groupdn" string " Gets prepended to basedn when searching for group.
"groupattr" | string | "cn" | The group attribute to search for.
"groupfilter" | string | "(objectClass=groupOfUniqueNames)" | Filter that will be added to the search filter when searching for a group: (&(groupattr=group)(memberattr=username)(groupfilter)).
"memberattr" | string | "uniqueMember" | The attribute of the group object where the user dn may be found.
"memberisdn" | boolean | TRUE | Whether the memberattr is the dn of the user (default) or the value of userattr (usually uid).
"group" string " The name of the group users have to be a member of to authenticate successfully.
"groupscope" | string | "sub" | Scope for group searching: one, sub (default), or base.
"start_tls" | boolean | "false" | Enable/disable the use of START_TLS encrypted connection.
"try_all" | boolean | FALSE | If multiple entries are returned by the search attempt to authenticate against each entry in order or just the first one (default).
"debug" | boolean | FALSE | Enable debug output.

Authenticating against a LDAP server

<?php
$a1 = new Auth("LDAP", array(
   'host' => 'localhost',
   'port' => '389',
   'version' => 3,
   'basedn' => 'o=netsols,c=de',
   'userattr' => 'uid',
   'binddn' => 'cn=admin,o=netsols,c=de',
   'bindpw' => 'password'
   ));
?>

Requiring users to be within specific groups

<?php
$a2 = new Auth('LDAP', array(
   'url' => 'ldaps://ldap.netsols.de',
   'basedn' => 'o=netsols,c=de',
   'userscope' => 'one',
   'userdn' => 'ou=People',
   'groupdn' => 'ou=Groups',
   'groupfilter' => '(objectClass=posixGroup)',
   'memberattr' => 'memberUid',
   'memberisdn' => false,
   'group' => 'admin'
   ));
?>

Authenticating against a Microsoft Active Directory server

<?php
$a3 = new Auth('LDAP', array(
   'host' => 'ldap.netsols.de',
   'port' => 389,
   'version' => 3,
   'referrals' => false,
   'basedn' => 'dc=netsols,dc=de',
   'binddn' => 'cn=Jan Wagner,cn=Users,dc=netsols,dc=de',
   'bindpw' => 'password',
   'userattr' => 'samAccountName',
   'userfilter' => '(objectClass=user)',
   'attributes' => array(''),
   'group' => 'testing',
   'groupattr' => 'samAccountName',
   'groupfilter' => '(objectClass=group)',
   'memberattr' => 'member',
   'memberisdn' => true,
   'groupdn' => 'cn=Users',
   'groupscope' => 'one',
   ));
?>

When talking to a Microsoft ActiveDirectory server you have to use 'samaccountname' as the 'userattr' and follow special rules to translate the ActiveDirectory directory names into 'basedn'. The 'basedn' for the default 'Users' folder on an ActiveDirectory server for the ActiveDirectory Domain (which is not related to its DNS name) "win2000.example.org" would be: "CN=Users, DC=win2000, DC=example, DC=org" where every component of the domain name becomes a DC attribute of its own. If you want to use a custom users folder you have to replace "CN=Users" with a sequence of "OU" attributes that specify the path to your custom folder in reverse order. So the ActiveDirectory folder "win2000.example.org\Custom\Accounts" would become "OU=Accounts, OU=Custom, DC=win2000, DC=example, DC=org"

It seems that binding anonymously to an Active Directory is not allowed, so you have to set binddn and bindpw for user searching.

LDAP Referrals need to be set to false for AD to work sometimes.

Note also that if you want an encrypted connection to an MS LDAP server, then, on your webserver, you must specify "TLS_REQCERT never" in /etc/ldap/ldap.conf or in the webserver user's ~/.ldaprc (which may or may not be read depending on your configuration).

Prev | Auth | Next
Auth_Container_KADM5 | PEAR Manual | Auth_Container_MDB


Auth_Container_MDB

Auth_Container_MDB

Auth_Container_MDB – Authenticate against a database using MDB

MDB Container

This container makes use of PEAR::MDB abstraction layer for database access. That means that you can use all databases that are supported by the MDB abstraction layer to store the login data.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"dsn" | string | " | A valid and well-formed DSN .
"table" | string | "auth" | The name of the database table, where the authorization data is stored.
"usernamecol" | string | "username" | The name of the column, where the username is stored
"passwordcol" | string | "password" | The name of the column, where the crypted password is stored.
"db_fields" | array | array() | An array of extra fields to retrieve when loading the user details.
"cryptType" | string | "md5" | The encryption type the password is stored in.
"auto_quote" | boolean | TRUE | Whether to enable automatic quoting of database table and field names.
"db_options" | array | array() | An array of options to be passed to the PEAR::MDB constructor. See PEAR::MDB for more information.
"db_where" | string | " | A string to be appended to the WHERE clause of queries against the database. It is appended to the queries used in fetchData(), listUsers(), removeUser() and changePassword(). Available since Auth 1.5.0.
Prev | Auth | Next
Auth_Container_LDAP | PEAR Manual | Auth_Container_MDB2


Auth_Container_MDB2

Auth_Container_MDB2

Auth_Container_MDB2 – Authenticate against a database using MDB2

MDB2 Container

This container makes use of PEAR::MDB2 abstraction layer for database access. That means that you can use all databases that are supported by the MDB2 abstraction layer to store the login data.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"dsn" | string | " | A valid and well-formed DSN .
"table" | string | "auth" | The name of the database table, where the authorization data is stored.
"usernamecol" | string | "username" | The name of the column, where the username is stored
"passwordcol" | string | "password" | The name of the column, where the crypted password is stored.
"db_fields" | array | array() | An array of extra fields to retrieve when loading the user details.
"cryptType" | string | "md5" | The encryption type the password is stored in.
"auto_quote" | boolean | TRUE | Whether to enable automatic quoting of database table and field names.
"db_options" | array | array() | An array of options to be passed to the PEAR::MDB2 constructor. See PEAR::MDB2 for more information.
"db_where" | string | " | A string to be appended to the WHERE clause of queries against the database. It is appended to the queries used in fetchData(), listUsers(), removeUser() and changePassword(). Available since Auth 1.5.0.

Note

By default, MDB2's default portability setting of MDB2_PORTABILITY_ALL is used. This setting may cause unexpected behaviour, such as field names being converted to lowercase regardless of their definition in the database schema. The "db_options" option can be used to override this, as shown in the following example.

Example overriding MDB2's default portability

<?php
$options = array('dsn'         => 'mysql://user:password@localhost/database',
                 'usernamecol' => 'UserName',
                 'passwordcol' => 'PassWord',
                 'db_options'  => array('portability' => MDB2_PORTABILITY_ALL ^ MDB2_PORTABILITY_FIX_CASE)
                );
$auth = new Auth('MDB2', $options, 'loginFunction');
?>
Prev | Auth | Next
Auth_Container_MDB | PEAR Manual | Auth_Container_Multiple


Auth_Container_Multiple

Auth_Container_Multiple

Auth_Container_Multiple – Authenticate against multiple Auth_Containers

Multiple

This container provides a facility to attempt to authenticate against multiple Auth_Containers in order.

If a container's getAuthData() returns true Auth_Container_Multiple will return true.

When a container's getAuthData() returns false Auth_Container_Multiple will continue on through the list of available containers until a successful login is found or the list of containers is expired.

On receipt of an error from getAuthData() Auth_Container_Multiple will abort checking further containers and return the error.

The storage-specific argument for the Auth constructor() is an array of container configurations. Each container configuration has the following options:

Available Options
Option | Data Type | Default value | Description
"type" | string | " | The type of container to instanciate. This is the same value as used in the first parameter of the Auth constructor() .
"options" | array | array() | This is the standard array of options required for the container.

Example usage of Auth_Container_Multiple

<?php
require_once "Auth.php";
require_once 'Log.php';
require_once 'Log/observer.php';

// Callback function to display login form
function loginFunction($username = null, $status = null, &$auth = null)
{
    /*
     * Change the HTML output so that it fits to your
     * application.
     */
    echo "<form method=\"post\" action=\"".$_SERVER['PHP_SELF']."\">";
    echo "Username: <input type=\"text\" name=\"username\"><br/>";
    echo "Password: <input type=\"password\" name=\"password\"><br/>";
    echo "<input type=\"submit\">";
    echo "</form>";
}

class Auth_Log_Observer extends Log_observer {

    var $messages = array();

    function notify($event) {

        $this->messages[] = $event;

    }

}

$options = array(
    'enableLogging' => true,
    array(
        'type' => 'Array',
        'options' => array(
            'cryptType' => 'md5',
            'users' => array(
                'guest' => md5('password'),
            ),
        ),
    ),
    array(
        'type' => 'Array',
        'options' => array(
            'cryptType' => 'md5',
            'users' => array(
                'admin' => md5('password'),
            ),
        ),
    ),
);
$a = new Auth("Multiple", $options, "loginFunction");

$infoObserver = new Auth_Log_Observer(PEAR_LOG_INFO);

$a->attachLogObserver($infoObserver);

$debugObserver = new Auth_Log_Observer(PEAR_LOG_DEBUG);

$a->attachLogObserver($debugObserver);

$a->start();

if ($a->checkAuth()) {
    /*
     * The output of your site goes here.
     */
    print "Authentication Successful.<br/>";
}

print '<h3>Logging Output:</h3>'
    .'<b>PEAR_LOG_INFO level messages:</b><br/>';

foreach ($infoObserver->messages as $event) {
    print $event['priority'].': '.$event['message'].'<br/>';
}

print '<br/>'
    .'<b>PEAR_LOG_DEBUG level messages:</b><br/>';

foreach ($debugObserver->messages as $event) {
    print $event['priority'].': '.$event['message'].'<br/>';
}

print '<br/>';
?>

Note

This container has only been available since version 1.5.0.

Prev | Auth | Next
Auth_Container_MDB2 | PEAR Manual | Auth_Container_PEAR


Auth_Container_PEAR

Auth_Container_PEAR

Auth_Container_PEAR – Authenticate against the PEAR website

PEAR Container

This container provides authentication services against the PEAR website (http://pear.php.net/) and the developer accounts. The HTTP_Client package must be installed for this container to operate, as of Auth 1.5.3.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"url" | string | "https://pear.php.net/rest-login.php/" | The base URL of a PEAR website to authenticate against.
"karma" | array | array() | List of karma levels required for a valid authentication. If no karma levels are supplied than simply validating the username and password will result in success.
Prev | Auth | Next
Auth_Container_Multiple | PEAR Manual | Auth_Container_POP3


Auth_Container_POP3

Auth_Container_POP3

Auth_Container_POP3 – Authenticate against a POP3 server

POP3 Container

This storage container connects to the specified POP3 server and tries to login there with the specified username/password.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"host" | string | "localhost" | The hostname or IP address of the POP3 server.
"port" | integer | "110" | The port number the POP3 server is listening on.
"method" boolean or string TRUE

The authentication method to use with the POP3 server. Available options:

TRUE

Use Net_POP3's autodetection algorithm.

'DIGEST-MD5', 'CRAM-MD5', 'LOGIN', 'PLAIN', 'APOP', 'USER'

Attempt this authentication style first then fallback to autodetection.

Prev | Auth | Next
Auth_Container_PEAR | PEAR Manual | Auth_Container_RADIUS


Auth_Container_RADIUS

Auth_Container_RADIUS

Auth_Container_RADIUS – Authenticate against a RADIUS server

RADIUS Container

You need Auth_RADIUS and the PECL radius in order to get this container to work.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option Data Type Default value Description
"servers" array array("localhost", 0, "testing123", 3, 3)

Array of RADIUS servers, containing: host, port, shared secret, timeout, maxtries.

The host parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form.

The port parameter specifies the UDP port to contact on the server. If port is given as 0, the library looks up the radius/udp entry in the network services database, and uses the port found there. If no entry is found, the library uses the standard RADIUS port for authentication (1812).

The shared secret for the server host is passed to the secret parameter. The RADIUS protocol ignores all but the leading 128 bytes of the shared secret.

The timeout for receiving replies from the server is passed to the timeout parameter, in units of seconds.

The maximum number of repeated requests to make before giving up is passed into the maxtries parameter.

At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server's maxtries limit has been reached.

"authtype" string "PAP"

The authentication method for validating the request. Possible values are: PAP, CHAP_MD5, MSCHAPv1, MSCHAPv2.

There are dependencies for the different methods. For all authentication methods except PAP you need the Crypt_CHAP package, when you are using MS-CHAP you need also the mhash extension.

Prev | Auth | Next
Auth_Container_POP3 | PEAR Manual | Auth_Container_SAP


Auth_Container_SAP

Auth_Container_SAP

Auth_Container_SAP – Authenticate against a SAP server

SAP Container

This container allows authentication against a SAP server using the SAPRFC extension available at http://saprfc.sourceforge.net/.

The storage-specific argument for the Auth constructor() is an array of options which are passed directly to the SAPRFC extension. None of the options are used internally, for more details see the SAPRFC's documentation.

Prev | Auth | Next
Auth_Container_RADIUS | PEAR Manual | Auth_Container_SMBPasswd


Auth_Container_SMBPasswd

Auth_Container_SMBPasswd

Auth_Container_SMBPasswd – Authenticate a SAMBA smbpasswd file using File_SMBPasswd

SMBPasswd Container

This storage container provides authentication against SAMBA smbpasswd files. It makes use of the PEAR File_SMBPasswd package.

The storage-specific argument for the Auth constructor() is a string containing the filename of the SAMBA smbpasswd file to use.

Prev | Auth | Next
Auth_Container_SAP | PEAR Manual | Auth_Container_SOAP


Auth_Container_SOAP

Auth_Container_SOAP

Auth_Container_SOAP – Authenticate against a SOAP service

SOAP Container

This container makes use of the PEAR SOAP client to provide authentication against a SOAP service.

The storage-specific argument for the Auth constructor() is an array of options.

Available Options
Option | Data Type | Default value | Description
"endpoint" | string | The URI where the service is located.
"namespace" | string | The namespace of the web service.
"method" | string | The SOAP method you wish to call.
"encoding" | string | The content encoding that should be used (e.g. UTF-8).
"usernamefield" | string | The name of the field where the username is stored.
"passwordfield" | string | The name of the field where the password is stored.
"matchpasswords" boolean TRUE

If TRUE then the container will look for the password field in the returned result from the soap call and try to match that value with the one supplied from the end user.

If FALSE then it is assumed that the soap call will return an error if the user does not authenticate properly. If no error is returned than the user is assumed to valid and allowed to proceed.

"_features" array

A named array of extra parameters that are to be passed to the soap call in addition to the username and password fields. These are passed to the soap call as named parameters.

<?php
array(
  'field1'  => 'value1',
  'foo'     => 'bar',
);
?>
Prev | Auth | Next
Auth_Container_SMBPasswd | PEAR Manual | Auth_Container_SOAP5


Auth_Container_SOAP5

Auth_Container_SOAP5

Auth_Container_SOAP5 – Authenticate against a SOAP service

SOAP5 Container

This container makes use of the PHP SOAP extension's client to provide authentication against a SOAP service.

The storage-specific argument for the Auth constructor() is an array of options. In addition to the below options all options for the PHP SOAP Client can be passed in this array and they will be passed onto the client.

Available Options
Option | Data Type | Default value | Description
"wsdl" | string | The location of the WSDL file describing the SOAP service you wish to authenticate against. The WSDL file takes priority over a specified "location" and "uri".
"location" | string | The URI where the service is located, when not making use of a WSDL file.
"uri" | string | The namespace of the web service, when not making use of a WSDL file.
"method" | string | The SOAP method you wish to call.
"usernamefield" | string | "username" | The name of the field where the username is stored.
"passwordfield" | string | "password" | The name of the field where the password is stored.
"matchpasswords" boolean TRUE

If TRUE then the container will look for the password field in the returned result from the soap call and try to match that value with the one supplied from the end user.

If FALSE then it is assumed that the soap call will return an error if the user does not authenticate properly. If no error is returned than the user is assumed to valid and allowed to proceed.

"_features" array

A named array of extra parameters that are to be passed to the soap call in addition to the username and password fields. These are passed to the soap call as named parameters.

<?php
array(
  'field1'  => 'value1',
  'foo'     => 'bar',
);
?>
Prev | Auth | Next
Auth_Container_SOAP | PEAR Manual | Auth_Container_vpopmail


Auth_Container_vpopmail

Auth_Container_vpopmail

Auth_Container_vpopmail – Authenticate against a vpopmail service

vpopmail Container

This container uses an existing vpopmail service to validate the username and the password.

It does not require any storage-specific argument.

Prev | Auth | Next
Auth_Container_SOAP5 | PEAR Manual | Custom Auth_Container


Custom Auth_Container

Custom Auth_Container

Custom Auth_Container – Build a custom storage container

Custom Storage Containers

Here is a skeleton for a custom Auth storage container

CustomAuthContainer.php

<?php
include_once 'Auth/Container.php';

class CustomAuthContainer extends Auth_Container
{
    /**
     * Constructor
     */
    function CustomAuthContainer($params)
    {
      // Init Here
    }

    function fetchData($username, $password)
    {
        // Check If valid etc
        if($isvalid) {
            // Perform Some Actions
            return true;
        }
        return false;
    }
}
?>

And here is how to use it.

authcustom.php

<?php
include_once 'CustomAuthContainer.php';
include_once 'Auth/Auth.php';

$auth_container = new CustomAuthContainer($params);
$myauth = new Auth($auth_container);

$myauth->start();
?>
Prev | Auth | Next
Auth_Container_vpopmail | PEAR Manual | Auth_Frontend_HTML


Auth_Frontend_HTML

Auth_Frontend_HTML

Auth_Frontend_HTML – Default login form

Overview

PEAR::Auth_Frontend_HTML provides a generic default login page for use with PEAR::Auth. When building your own login page it is a reasonable place to start as it includes all the required elements of the login form.

Prev | Auth | Next
Custom Auth_Container | PEAR Manual | Constants


Constants

Constants

Constants – predefined constants

AUTH_IDLED

-1

Returned if a session exceeds its idle time.

AUTH_EXPIRED

-2

Returned if a session has expired.

AUTH_WRONG_LOGIN

-3

Returned if the Auth Container in use is unable to validate the username/password pair supplied.

AUTH_METHOD_NOT_SUPPORTED

-4

Returned if the requested function is not implemented by the Auth Container in use.

AUTH_SECURITY_BREACH

-5

Returned if the advanced security checking detects a breach.

AUTH_CALLBACK_ABORT

-6

Returned if the checkAuth callback function aborted the session.

Prev | Auth | Next
Auth_Frontend_HTML | PEAR Manual | Auth::Auth()


Auth::Auth()

Auth::Auth()

Auth::Auth() – constructor

Synopsis

Auth::Auth ( mixed $storageDriver , mixed $options = "" , string $loginFunction = "" , boolean $showLogin = true )

Description

Constructor for the authentication system.

The constructor will ensure that the PHP session management is started by calling session_start(). This is done as Auth requires a session to be active to operate correctly.

Parameter

string $storageDriver

Name of the storage driver that should be used, alternatively you can pass a custom Auth_Container object.

mixed $options

Array containing the options for both Auth itself and the storage driver. See Auth Options for global options and each storage driver's documentation for specific options.

string $loginFunction

The name of a user-defined function that prints the login screen. This function is passed three parameters when called $username, $status, &$auth. These are in order the previously attempted username, the status code that caused the previous auth attempt to fail and a reference to the Auth object itself.

boolean $showLogin

Defines if the login is optional or not.

Note

This function can not be called statically.

See

Introduction - The storage drivers

Example

Using different DB parameters

<?php
require_once "Auth/Auth.php";

function myOutput($username, $status, $auth)
{
    ...  /* See first example in introduction for the full listing */
}

$params = array(
            "dsn" => "mysql://martin:test@localhost/auth",
            "table" => "myAuth",
            "usernamecol" => "myUserColumn",
            "passwordcol" => "myPasswordColumn"
            );

$a = new Auth("DB", $params, "myOutput");

$a->start();

if ($a->getAuth()) {
    echo "You have been authenticated successfully.";
}
?>

This example shows you how you can specifiy alternative names for the database table and the column names. In our example, we use the table myAuth, select the username from the field myUserColumn and the password from the field myPasswordColumn. The default values for this fields are auth, username and password. Note that you can also specify an existing DB object with the dsn parameter instead of a DSN.

This feature is necessary if you want to use PEAR::Auth with a database layout that is different from the one PEAR::Auth uses by default.

Example

Using different DB parameters

<?php
require_once "Auth/Auth.php";

function myOutput($username, $status)
{
    ...  /* See first example in introduction for the full listing */
}

$a = new Auth(new CustomAuthContainer($options), null, "myOutput");

$a->start();

if ($a->getAuth()) {
    echo "You have been authenticated successfully.";
}
?>

This example shows you how you can pass your own storage container to Auth.

If the storage containers supplied with Auth are not capable of fulfilling your requirements, you can easliy create your own storage container. Read the storage containers section for more info Introduction - The storage drivers

Prev | Auth | Next
Constants | PEAR Manual | Auth::addUser()


Auth::addUser()

Auth::addUser()

Auth::addUser() – add a new user

Synopsis

mixed Auth::addUser ( string $username , string $password , mixed $additional = '' )

Description

Add a new user to the Auth Container.

Parameter

string $username

the username of the new user

string $password

the password of the new user

mixed $additional = ''

additional options to be passed to the creation of the new user. Each Auth_Container has different options for these, please see the containers documentation for what is supported.

Return value

mixed - TRUE on success, a PEAR Error on failure.

Note

This function can not be called statically.

Not all Auth Containers implement this functionality.

Prev | Auth | Next
Auth::Auth() | PEAR Manual | Auth::attachLogObserver()


Auth::attachLogObserver()

Auth::attachLogObserver()

Auth::attachLogObserver() – Attach a log observer instance to the internal Log object

Synopsis

void Auth::attachLogObserver ( object &$observer )

Description

Attach an instance of a Log_Observer to the internal Log object. This allows the internal logs to be accessed and used as you wish within your application.

Parameter

object &$observer

The instance of the Log_Observer to attach to the internal Log object.

Note

This function can not be called statically.

This function has only been available since version 1.5.0.

Prev | Auth | Next
Auth::addUser() | PEAR Manual | Auth::changePassword()


Auth::changePassword()

Auth::changePassword()

Auth::changePassword() – change the password of a user

Synopsis

mixed Auth::changePassword ( string $username , string $password )

Description

Change the password of a user within the Auth Container.

Parameter

string $username

the username of the user

string $password

the new password for the user

Return value

mixed - TRUE on success, a PEAR Error on failure.

Note

This function can not be called statically.

Not all Auth Containers implement this functionality.

Prev | Auth | Next
Auth::attachLogObserver() | PEAR Manual | Auth::checkAuth()


Auth::checkAuth()

Auth::checkAuth()

Auth::checkAuth() – check if a session with valid authentication information exists

Synopsis

boolean Auth::checkAuth ( )

Description

Checks if a session exists that contains valid authentication information.

Return value

boolean - If a session with valid authentication information exists, the function return TRUE. Otherwise it returns FALSE.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::changePassword() | PEAR Manual | Auth::getAuth()


Auth::getAuth()

Auth::getAuth()

Auth::getAuth() – check for an authenticated user

Synopsis

boolean Auth::getAuth ( )

Description

Check if the user has been authenticated.

In previous versions, this function had a different behaviour than Auth::checkAuth()(). Now it is just an alias for Auth::checkAuth()().

Return value

boolean - If the user has already been authenticated, the function returns TRUE. Otherwise it returns FALSE.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::checkAuth() | PEAR Manual | Auth::getAuthData()


Auth::getAuthData()

Auth::getAuthData()

Auth::getAuthData() – retrieve extra information stored within the auth session

Synopsis

mixed Auth::getAuthData ( string $name )

Description

This function retrieves the value of a previously registered data field.

Parameter

string $name

the name of the data field

Note

This function can not be called statically.

Prev | Auth | Next
Auth::getAuth() | PEAR Manual | Auth::getStatus()


Auth::getStatus()

Auth::getStatus()

Auth::getStatus() – get the current status of the auth session

Synopsis

int Auth::getStatus ( )

Description

Get the current status of the authentication session.

Return value

int - An Auth constant representing the current session state.

Note

This function can not be called statically.

See

"Auth Constants".

Prev | Auth | Next
Auth::getAuthData() | PEAR Manual | Auth::getUsername()


Auth::getUsername()

Auth::getUsername()

Auth::getUsername() – get the username of the authenticated user

Synopsis

string Auth::getUsername ( )

Description

Get the username of the logged in user.

Return value

string - The username of the logged in user.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::getStatus() | PEAR Manual | Auth::listUsers()


Auth::listUsers()

Auth::listUsers()

Auth::listUsers() – list available users

Synopsis

array Auth::listUsers ( )

Description

List all the users currently available within the current Auth Container.

Return value

array - An array of user details. Currently no consistency, see each Auth Container for details on how and what they return.

Note

This function can not be called statically.

Not all Auth Containers implement this functionality.

Prev | Auth | Next
Auth::getUsername() | PEAR Manual | Auth::logout()


Auth::logout()

Auth::logout()

Auth::logout() – logout an authenticated user

Synopsis

void Auth::logout ( )

Description

Logout any currently logged in user.

Example

<?php
//$a is our Auth object
$a->start();

if (isset($_GET['action']) && $_GET['action'] == 'logout'
    && $a->checkAuth()
) {
    $a->logout();
    $a->start();
}
?>
Prev | Auth | Next
Auth::listUsers() | PEAR Manual | Auth::removeUser()


Auth::removeUser()

Auth::removeUser()

Auth::removeUser() – remove a user account

Synopsis

mixed Auth::removeUser ( string $username )

Description

Remove a user from the Auth Container.

Parameter

string $username

the username of the user to remove

Return value

mixed - TRUE on success, a PEAR Error on failure.

Note

This function can not be called statically.

Not all Auth Containers implement this functionality.

Prev | Auth | Next
Auth::logout() | PEAR Manual | Auth::setAdvancedSecurity()


Auth::setAdvancedSecurity()

Auth::setAdvancedSecurity()

Auth::setAdvancedSecurity() – Enables advanced security features. Turned off by default

Synopsis

void Auth::setAdvancedSecurity ( bool $flag = true )

Description

Enables advanced security features to make man in the middle attacks and session hijacking much harder. Cookies and java script must be enabled on the client browser for some of these features to function correctly.

Enables the following security features of auth

  • Detection of client ip address change or User-Agent header change if such a change is detected the user will be logged out

  • Each client request a special unique cookie is given to the client. He must present this cookie on his next request. This cookie changes on every request. If client does not present the valid cookie he will be logged out.

  • Enables challenge responce for the default login screen of auth. The user password will be hashed with javascript before sent back to the server. Prevents the user password being stolen using password sniffing tools. Password is hashed with a random key so the md5 hash is not subject to brute force password cracking. This will only work for storage containers which support challenge responce password authenthication. Currently only the DB, MDB and MDB2 containers support this for md5 and clear text passwords

Note: This method is available since 1.3.0

Parameter

boolean $flag

TRUE if you want to enable advanced security features FALSE if you want to disable them.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::removeUser() | PEAR Manual | Auth::setAllowLogin()


Auth::setAllowLogin()

Auth::setAllowLogin()

Auth::setAllowLogin() – Controls if the user will be allowed to login. Turned on by default

Synopsis

void Auth::setAllowLogin ( bool $allowLogin = true )

Description

Controls if auth will process the post variables and attempt to login the user from those pages. For better security of your application it is recomended to disable login in all pages except your login page.

Parameter

boolean $allowLogin

If you want to allow login set this to TRUE otherwise set it to FALSE.

Note

This function can not be called statically.

This method is available since 1.3.0

Prev | Auth | Next
Auth::setAdvancedSecurity() | PEAR Manual | Auth::setAuth()


Auth::setAuth()

Auth::setAuth()

Auth::setAuth() – set a specific user to be marked as logged in

Synopsis

void Auth::setAuth ( string $username )

Description

Mark the session up to indicate that the username supplied has successfully logged in. Although normally used for internal purposes this function can be used to fake a login.

Parameter

string $name

the name of the data field

Note

This function can not be called statically.

This function will also call session_regenerate_id() so as to prevent session fixation attacks.

Prev | Auth | Next
Auth::setAllowLogin() | PEAR Manual | Auth::setAuthData()


Auth::setAuthData()

Auth::setAuthData()

Auth::setAuthData() – store extra information with the Auth session

Synopsis

void Auth::setAuthData ( string $name , mixed $value , boolean $overwrite = true )

Description

This function allows the registration of extra information to be stored allowing with the authentication data.

Parameter

string $name

the name of the data field

mixed $value

the value of the data field

boolean $overwrite

whether to overwrite the value of the data field if it already exists.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setAuth() | PEAR Manual | Auth::setCheckAuthCallback()


Auth::setCheckAuthCallback()

Auth::setCheckAuthCallback()

Auth::setCheckAuthCallback() – set a callback to run when ever session validity is checked

Synopsis

void Auth::setCheckAuthCallback ( string $checkAuthCallback )

Description

This function sets a callback function which is called whenever the validity of a logged in session is checked. This callback can be used to perform actions like checking the authentication source to see if the logged in user is still enabled.

The callback function will be passed two parameters, the username that successfully logged in and a reference to the Auth object. The callback function should return a boolean depending upon whether the session should continue or not. TRUE to allow the session to continue, FALSE to abort the session.

If the session is aborted by this callback the status will be set to AUTH_CALLBACK_ABORT.

Parameter

string $checkAuthCallback

the call back function to use

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setAuthData() | PEAR Manual | Auth::setExpire()


Auth::setExpire()

Auth::setExpire()

Auth::setExpire() – set expiration time for authentication

Synopsis

void Auth::setExpire ( integer $time , boolean $add = false )

Description

With this function you can set the maximum expire time that is used by auth to a new value.

Parameter

integer $time

expiration time, number of seconds

boolean $add

if TRUE $time is added to the existing expiration time, if FALSE the exitsing time value will be replaced.

Note

This function can not be called statically.

Auth uses PHP's session mechanism to recognize users between http calls. Setting Auth's expiry time larger than the session timeout will still expire the session to the time the php session expires.

Prev | Auth | Next
Auth::setCheckAuthCallback() | PEAR Manual | Auth::setFailedLoginCallback()


Auth::setFailedLoginCallback()

Auth::setFailedLoginCallback()

Auth::setFailedLoginCallback() – set a callback for failed login attempts

Synopsis

void Auth::setFailedLoginCallback ( string $loginFailedCallback )

Description

This function sets a callback function which is called upon failed login of a user account.

The callback function will be passed two parameters, the username that failed to login and a reference to the Auth object.

Parameter

string $loginFailedCallback

the call back function to use

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setExpire() | PEAR Manual | Auth::setIdle()


Auth::setIdle()

Auth::setIdle()

Auth::setIdle() – set maximum idle time for authentication

Synopsis

void Auth::setIdle ( integer $time , boolean $add = false )

Description

With this function one can set the maximum idle time to a new value. The term "idle time" describes the maximum time interval (in seconds) between two actions by the user. If the maximum idle time is reached, the user will be automatically logged out. If on the other hand the user performs any action within the maximum idle time interval, the idle time is reset.

Parameter

integer $time

idle time in seconds

boolean $add

if TRUE $time is added to the existing idle time, if FALSE the existing time value will be replaced.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setFailedLoginCallback() | PEAR Manual | Auth::setLoginCallback()


Auth::setLoginCallback()

Auth::setLoginCallback()

Auth::setLoginCallback() – set a callback for successful login attempts

Synopsis

void Auth::setLoginCallback ( string $loginCallback )

Description

This function sets a callback function which is called upon successful login of a user account.

The callback function will be passed two parameters, the username that successfully logged in and a reference to the Auth object.

Parameter

string $loginCallback

the call back function to use

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setIdle() | PEAR Manual | Auth::setLogoutCallback()


Auth::setLogoutCallback()

Auth::setLogoutCallback()

Auth::setLogoutCallback() – set a callback for successful logout attempts

Synopsis

void Auth::setLogoutCallback ( string $loginCallback )

Description

This function sets a callback function which is called upon successful logout of a user account.

The callback function will be passed two parameters, the username that successfully logged out and a reference to the Auth object.

Parameter

string $loginCallback

the call back function to use

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setLoginCallback() | PEAR Manual | Auth::setSessionName()


Auth::setSessionName()

Auth::setSessionName()

Auth::setSessionName() – set a custom name for the Auth session variable

Synopsis

void Auth::setSessionName ( string $name )

Description

This function is used to set the name of the session variable used to store the user's authentication details. The default for the session variable name is _authsession.

Parameter

string $name

the session variable name to use

Note

This function can not be called statically.

You have to use setSessionName(), if you are running two or more different applications with Auth on the same domain. If you don't use this function, a user who has once logged in at one of the applications can also use the other applications without logging in again!

Prev | Auth | Next
Auth::setLogoutCallback() | PEAR Manual | Auth::setShowLogin()


Auth::setShowLogin()

Auth::setShowLogin()

Auth::setShowLogin() – controls if the login form will be displayed. Turned on by default

Synopsis

void Auth::setShowLogin ( bool $showLogin = true )

Description

Controls if the login page will be displayed to the user. Normally you might need to display the login form only on a certain page of your web application.

Parameter

boolean $showLogin

true if you want to display the login form and false if you want to hide it.

Note

This function can not be called statically.

This is equivalent to the 4th paramether of Auth::Auth()

Prev | Auth | Next
Auth::setSessionName() | PEAR Manual | Auth::sessionValidThru()


Auth::sessionValidThru()

Auth::sessionValidThru()

Auth::sessionValidThru() – get the time up to the session is valid

Synopsis

void Auth::sessionValidThru ( )

Description

This method returns the time in seconds after which the idle time of the current authentication session has reached its limit, which will cause the user to be logged out automatically. If no maximum idle time is set, which is the default configuration of PEAR::Auth, this method will return 0.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::setShowLogin() | PEAR Manual | Auth::start()


Auth::start()

Auth::start()

Auth::start() – start authentication

Synopsis

void Auth::start ( )

Description

Start the authentication process. To do this Auth checks for an existing session and checks its validity. If there is no existing session or the previous session has been ended for some reason then the login form is generated either via the specified callback or using the default form implemented in Auth_Frontend_HTML.

Note

This function can not be called statically.

Prev | Auth | Next
Auth::sessionValidThru() | PEAR Manual | Auth_HTTP


Auth_HTTP

Auth_HTTP

Provides a framework for user authentication (aka an "User-Login") based on the HTTP

Table of Contents
  • Introduction -- to HTTP based authentication
  • Auth_HTTP::Auth_HTTP() -- constructor
  • Auth_HTTP Example -- Example: A simple password protected page
  • Auth_HTTP Example 2 -- Example: A password protected page with multiple rows fetch and md5 password
  • Auth_HTTP::getAuth() -- check for an authenticated user
  • Auth_HTTP::getStatus() -- returns informations about the current authentication status
  • Auth_HTTP::start() -- start authentication
Prev | Authentication | Next
Auth::start() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – to HTTP based authentication

Instead of generating an HTML driven form like PEAR::Auth does, this class sends header commands to the clients which cause them to present a login box like they are e.g. used in Apache's .htaccess mechanism.

Starting with Auth_HTTP 2.1.0, HTTP Digest Authentication (RFC2617) is experimentally supported.

Prev | Auth_HTTP | Next
Auth_HTTP | PEAR Manual | Auth_HTTP::Auth_HTTP()


Auth_HTTP::Auth_HTTP()

Auth_HTTP::Auth_HTTP()

Auth_HTTP::Auth_HTTP() – constructor

Synopsis

void Auth_HTTP::Auth_HTTP ( string $storageDriver = "DB" , mixed $options = "" )

Description

Constructor for the authentication system

Parameter

string $storageDriver

name of the storage driver that should be used

mixed $options

a string containing some login information or an array containing a bunch of options for the storage driver

Note

This function can not be called statically.

Example

Using different DB parameters

<?php
require_once "Auth/HTTP.php";

$a = new Auth_HTTP("DB", "mysql://test:test@localhost/test");

$a->start();
?>
Prev | Auth_HTTP | Next
Introduction | PEAR Manual | Auth_HTTP Example


Auth_HTTP Example

Auth_HTTP Example

Auth_HTTP Example – Example: A simple password protected page

Example

<?php

// example of Auth_HTTP basic implementation

require_once("Auth/HTTP.php");

// setting the database connection options
$AuthOptions = array(
'dsn'=>"pgsql://test:test@localhost/testdb",
'table'=>"testable",                            // your table name
'usernamecol'=>"username",            // the table username column
'passwordcol'=>"password",            // the table password column
'cryptType'=>"none",                // password encryption type in your db
);

$a = new Auth_HTTP("DB", $AuthOptions);

$a->setRealm('yourrealm');            // realm name
$a->setCancelText('<h2>Error 401</h2>');        // error message if authentication fails
$a->start();                    // starting the authentication process

if($a->getAuth())                // checking for autenticated user
{
    echo "Hello $a->username welcome to my secret page";

};

?>
Prev | Auth_HTTP | Next
Auth_HTTP::Auth_HTTP() | PEAR Manual | Auth_HTTP Example 2


Auth_HTTP Example 2

Auth_HTTP Example 2

Auth_HTTP Example 2 – Example: A password protected page with multiple rows fetch and md5 password

Example

<?php
// example of Auth_HTTP implementation with encrypted password and multiple columns fetch

require_once("Auth/HTTP.php");

// setting the database connection options
$AuthOptions = array(
'dsn'=>"pgsql://test:test@localhost/testdb",
'table'=>"testable",                            // your table name
'usernamecol'=>"username",            // the table username column
'passwordcol'=>"password",            // the table password column
'cryptType'=>"md5",                // password encryption type in your db
'db_fields'=>"*",                // enabling fetch for other db columns
);

$a = new Auth_HTTP("DB", $AuthOptions);

$a->setRealm('yourrealm');            // realm name
$a->setCancelText('<h2>Error 401</h2>');        // error message if authentication fails
$a->start();                    // starting the authentication process

if($a->getAuth())                // checking for autenticated user
{
    echo "Hello $a->username welcome to my secret page <BR>";
    echo "Your details on file are: <BR>";
    echo $a->getAuthData('userid');        // retriving other details from the database row
    echo $a->getAuthData('telephone');      // in this example the user id, telephone number
    echo $a->getAuthData('email');        // and email address
};
?>
Prev | Auth_HTTP | Next
Auth_HTTP Example | PEAR Manual | Auth_HTTP::getAuth()


Auth_HTTP::getAuth()

Auth_HTTP::getAuth()

Auth_HTTP::getAuth() – check for an authenticated user

Synopsis

boolean Auth_HTTP::getAuth ( )

Description

Check if the user has been authenticated.

Return value

boolean - If the user has already been authenticated, the function returns TRUE. Otherwise it returns FALSE.

Note

This function can not be called statically.

Prev | Auth_HTTP | Next
Auth_HTTP Example 2 | PEAR Manual | Auth_HTTP::getStatus()


Auth_HTTP::getStatus()

Auth_HTTP::getStatus()

Auth_HTTP::getStatus() – returns informations about the current authentication status

Synopsis

string Auth_HTTP::getStatus ( )

Description

This function returns the current status of PEAR::Auth. The return values are constants that are defined by PEAR Auth.

Return value

string - possible values are AUTH_IDLED, AUTH_EXPIRED, AUTH_EXPIRED

Note

This function can not be called statically.

See

PEAR Auth constants overview

Prev | Auth_HTTP | Next
Auth_HTTP::getAuth() | PEAR Manual | Auth_HTTP::start()


Auth_HTTP::start()

Auth_HTTP::start()

Auth_HTTP::start() – start authentication

Synopsis

void Auth_HTTP::start ( )

Description

Start the authentication process.

Note

This function can not be called statically.

Prev | Auth_HTTP | Next
Auth_HTTP::getStatus() | PEAR Manual | Auth_PrefManager


Auth_PrefManager

Auth_PrefManager

Provides a framework for managing preferences in applications.

Table of Contents
  • Introduction to Auth_PrefManager -- Auth_PrefManager is a simple class to manage user or application preferences from a DB compatible database.
  • Tutorial -- A short guide to using Auth_PrefManager
  • constructor Auth_PrefManager::Auth_PrefManager -- Constructor
  • Auth_PrefManager::clearCache -- Cleans out the cache.
  • Auth_PrefManager::deleteDefaultPref -- Deletes a preference for the default user.
  • Auth_PrefManager::deletePref -- Deletes a preference for the specified user.
  • Auth_PrefManager::getDefaultPref -- Retrieves a default value.
  • Auth_PrefManager::getPref -- Get a preference.
  • Auth_PrefManager::setDefaultPref -- Set the default value for a preference.
  • Auth_PrefManager::setPref -- Set a preference.
  • Auth_PrefManager::setReturnDefaults -- Set whether to return default values.
  • Auth_PrefManager::useCache -- Sets whether the cache should be used.
Prev | Authentication | Next
Auth_HTTP::start() | PEAR Manual | Introduction to Auth_PrefManager


Introduction to Auth_PrefManager

Introduction to Auth_PrefManager

Introduction to Auth_PrefManager – Auth_PrefManager is a simple class to manage user or application preferences from a DB compatible database.

A simple preference manager.

Supported features include:

  • Setting of default values.

  • Serialization of values before saving to the database.

  • Support for any database supported by DB

Prev | Auth_PrefManager | Next
Auth_PrefManager | PEAR Manual | Tutorial


Tutorial

Tutorial

Tutorial – A short guide to using Auth_PrefManager

Setting up the database

The first step is to setup a database to store the values in. For this tutorial it's assumed that you already know the basics of using the PEAR DB class.

To set up the default table layout run the following SQL statement:

SQL to setup the table

CREATE TABLE `preferences` (
   `user_id` varchar( 255 ) NOT NULL default '',
   `pref_id` varchar( 32 ) NOT NULL default '',
   `pref_value` longtext NOT NULL ,
    PRIMARY KEY ( `user_id` , `pref_id` )
);

Setting up your first PrefManager object

To use Auth_PrefManager we must first create an instance of the base object, as shown below.

Setting up the object

<?php
require_once('Auth/PrefManager.php');
$dsn = 'mysql://user:password@localhost/database';   // Change the DSN to fit your database.
$options = array('serialize' => true);               // Enable serialization of data before saving, this ensures that the values are retrieved cleanly.
$prefmanager = new Auth_PrefManager($dsn, $options); // Create the object.
?>

Setting and displaying default preferences

Now that we have a PrefManager object, we can make use of it to set some preferences.

For this tutorial we're going to allow users to specify their country, and assume that any user who hasn't set their country is somewhere on Earth.

First we need to set the default value, using setDefaultPref.

Setting up the object

<?php
// Continued from example 1.
$prefmanager->setDefaultPref("country", "Earth");
?>

Now that the default is set, we can create a (very) basic page, welcoming users with a customised message.

Currently this message will only ever display "Welcome to the people of Earth!", since no users have their country set.

Getting preferences

$username = "guest";
<h1>Welcome to the people of <?=$prefmanager->getPref($username, "country")?>!</h1>

Setting a user's preferences

Finally we need a way for people to choose which country they're in.

This is going to be done with a simple text box, and you should obviously be a little more careful in a real application about allowing users to set preferences for people!

The Reset Country button will delete the user's preference, and cause the default to be displayed again.

Setting preferences

<h1>Set Country</h1>
// Allow users to set their country and username.
if (isset($_POST['submit'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->setPref($username, 'country', $_POST['country']);
} else if (isset($_POST['reset'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->deletePref($username, 'country');
} else {
    $username = 'guest';
}
?>
<h1>Welcome to the people of <?=$prefmanager->getPref($username, "country")?>!</h1>
<h2>Set Country And Username</h2>
<form method="post" action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
  <label for="username">Username</label> <input name="username" value="<?=$username?>" /><br/>
  <label for="country">Country</label> <input name="country" value="<?=$prefmanager->getPref($username, 'country')?>"/><br/>
  <input type="submit" name="submit" value="Set Country" /> <input type="submit" name="reset" value="Reset Country" />
</form>

Now once a user has entered their username, and their country, whenever they login they'll get a personalized welcome.

Full sourcecode

Sourcecode for the example page

<h1>Set Country</h1>
<?php
require_once('Auth/PrefManager.php');

// Create the PrefManager object.

// Change the DSN to fit your database.
$dsn = 'mysql://user:password@localhost/database';

// Enable serialization of data before saving, this ensures that the values are retrieved cleanly.
$options = array('serialize' => true);

// Create the object.
$prefmanager = new Auth_PrefManager($dsn, $options);

// Set the default value (this doesn't need to be done everytime the script is run).
$prefmanager->setDefaultPref("country", "Earth");

// Allow users to set their country and username.
if (isset($_POST['submit'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->setPref($username, 'country', $_POST['country']);
} else if (isset($_POST['reset'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->deletePref($username, 'country');
} else {
    $username = 'guest';
}
?>
<h1>Welcome to the people of <?=$prefmanager->getPref($username, "country")?>!</h1>
<h2>Set Country And Username</h2>
<form method="post" action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
  <label for="username">Username</label> <input name="username" value="<?=$username?>" /><br/>
  <label for="country">Country</label> <input name="country" value="<?=$prefmanager->getPref($username, 'country')?>"/><br/>
  <input type="submit" name="submit" value="Set Country" /> <input type="submit" name="reset" value="Reset Country" />
</form>
Prev | Auth_PrefManager | Next
Introduction to Auth_PrefManager | PEAR Manual | constructor Auth_PrefManager::Auth_PrefManager


constructor Auth_PrefManager::Auth_PrefManager

constructor Auth_PrefManager::Auth_PrefManager

constructor Auth_PrefManager::Auth_PrefManager() – Constructor

Synopsis

require_once '/PrefManager.php';

bool constructor Auth_PrefManager::Auth_PrefManager ( string $dsn , array $properties = NULL , string $defaultUser )

Description

The $properties property should be an associative array, with the structure below. Any options not set will be set to the default.

'table'

The table to retrieve preferences from. [preferences]

'userColumn'

The field to use for matching user IDs. [user_id]

'nameColumn'

The field to use for matching preference names. [pref_name]

'valueColumn'

The field to retrieve preference values from. [pref_value]

'defaultUser'

The user ID to use for retrieving default values. [__default__]

'cacheName'

The key to use for the cache in $_SESSION . [prefsCache]

'useCache'

Should values be cached for later use. [true]

'serialize'

Should values be serialized before saving to the database, and unserialized on retrieval. [false]

Parameter

string $dsn

The DSN of the database connection to make, or a DB object.

array $properties

An array of properties to set.

string $defaultUser

The default user to manage for.

Return value

returns Success or failure.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Users with preferences created using Auth_PrefManager 1.0.4 or earlier shouldn't enable the serialize option, as it may result in data loss.

Prev | Auth_PrefManager | Next
Tutorial | PEAR Manual | Auth_PrefManager::clearCache


Auth_PrefManager::clearCache

Auth_PrefManager::clearCache

Auth_PrefManager::clearCache() – Cleans out the cache.

Synopsis

require_once '/PrefManager.php';

void Auth_PrefManager::clearCache ( )

Description

Clears the cache of preferences stored in the current user's session.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
constructor Auth_PrefManager::Auth_PrefManager | PEAR Manual | Auth_PrefManager::deleteDefaultPref


Auth_PrefManager::deleteDefaultPref

Auth_PrefManager::deleteDefaultPref

Auth_PrefManager::deleteDefaultPref() – Deletes a preference for the default user.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::deleteDefaultPref ( string $pref_id )

Description

Deletes the default value for the preference passed as $pref_id .

Parameter

string $pref_id

The preference to delete.

Return value

returns Success/Failure

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::clearCache | PEAR Manual | Auth_PrefManager::deletePref


Auth_PrefManager::deletePref

Auth_PrefManager::deletePref

Auth_PrefManager::deletePref() – Deletes a preference for the specified user.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::deletePref ( string $user_id , string $pref_id )

Description

Deletes the preference $pref_id for $user_id if one is set.

Parameter

string $user_id

The userid of the user to delete from.

string $pref_id

The preference to delete.

Return value

returns Success/Failure

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::deleteDefaultPref | PEAR Manual | Auth_PrefManager::getDefaultPref


Auth_PrefManager::getDefaultPref

Auth_PrefManager::getDefaultPref

Auth_PrefManager::getDefaultPref() – Retrieves a default value.

Synopsis

require_once '/PrefManager.php';

mixed Auth_PrefManager::getDefaultPref ( string $pref_id )

Description

Retrieves the default value for $pref_id , even if there is currently a user ID set for the object being used.

Parameter

string $pref_id

The name of the preference to get.

Return value

returns The value if it's found, or NULL if it isn't.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::deletePref | PEAR Manual | Auth_PrefManager::getPref


Auth_PrefManager::getPref

Auth_PrefManager::getPref

Auth_PrefManager::getPref() – Get a preference.

Synopsis

require_once '/PrefManager.php';

mixed Auth_PrefManager::getPref ( string $user_id , string $pref_id , bool $showDefaults = true )

Description

Retrieves the preference specified for a user, or, if returning default values is enabled, the default.

Parameter

string $user_id

The user to get the preference for.

string $pref_id

The preference to get.

boolean $showDefaults

Should default values be searched (overrides the global setting).

Return value

returns The value if it's found, or NULL if it isn't.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::getDefaultPref | PEAR Manual | Auth_PrefManager::setDefaultPref


Auth_PrefManager::setDefaultPref

Auth_PrefManager::setDefaultPref

Auth_PrefManager::setDefaultPref() – Set the default value for a preference.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::setDefaultPref ( string $pref_id , mixed $value )

Description

Sets the default value for $pref_id , which will be retrieved if a user doesn't have the preference set.

Parameter

string $pref_id

The name of the preference to set.

mixed $value

The value to set it to.

Return value

returns Success or failure.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::getPref | PEAR Manual | Auth_PrefManager::setPref


Auth_PrefManager::setPref

Auth_PrefManager::setPref

Auth_PrefManager::setPref() – Set a preference.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::setPref ( string $user_id , string $pref_id , mixed $value )

Description

Sets the value for $pref_id .

Parameter

string $user_id

The user to set for.

string $pref_id

The preference to set.

mixed $value

The value it should be set to.

Return value

returns Success or failure.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::setDefaultPref | PEAR Manual | Auth_PrefManager::setReturnDefaults


Auth_PrefManager::setReturnDefaults

Auth_PrefManager::setReturnDefaults

Auth_PrefManager::setReturnDefaults() – Set whether to return default values.

Synopsis

require_once '/PrefManager.php';

void Auth_PrefManager::setReturnDefaults ( mixed $returnDefaults = true )

Description

Set whether a default value should be returned by getPref() if no value was set for the specified user.

Parameter

mixed $returnDefaults

Throws

No exceptions thrown.

Note

This function can not be called statically.

getDefaultPref() will always return the default value.

Prev | Auth_PrefManager | Next
Auth_PrefManager::setPref | PEAR Manual | Auth_PrefManager::useCache


Auth_PrefManager::useCache

Auth_PrefManager::useCache

Auth_PrefManager::useCache() – Sets whether the cache should be used.

Synopsis

require_once '/PrefManager.php';

void Auth_PrefManager::useCache ( bool $use = true )

Description

Sets whether the caching system should be used or not.

If the cache is enabled then any values retrieved will be saved in the user's session to reduce load on the database.

Parameter

boolean $use

Should the cache be used.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Auth_PrefManager | Next
Auth_PrefManager::setReturnDefaults | PEAR Manual | Auth_RADIUS


Auth_RADIUS

Auth_RADIUS

Client implementation of RADIUS. This package contains wrapper classes for the RADIUS PECL extension. Provides RADIUS Authentication (RFC2865) and RADIUS Accounting (RFC2866).

Table of Contents
  • Introduction -- Basic usage of Auth_RADIUS
Prev | Authentication | Next
Auth_PrefManager::useCache | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Basic usage of Auth_RADIUS

What is Auth_RADIUS?

Auth_RADIUS is a php wrapper around the php radius extension. If you are unfamiliar with the RADIUS protocol, the Wikipedia article provides an excellent introduction.

Auth_RADIUS is structured around the facilities built into the radius extension. Understanding Auth_RADIUS generally first requires a basic understanding of how the radius extension is designed. Documentation of the radius extension is available through the PHP manual at http://www.php.net/radius

There are different Classes for the different authentication methods available through RADIUS. If you are using CHAP-MD5 or MS-CHAP authentication, you will also need the Crypt_CHAP package. In addition, if using MS-CHAP authentication, you will need to enable the mhash and mcrypt extension in php.ini, or compile them in statically.

Note that if you have the latest radius extension (version 1.2 or newer), you will not need to enable the mcrypt extension.

How do I use Auth_RADIUS?

Basic usage examples follow, pulled from the package itself.

<?php
/* vim: set expandtab tabstop=4 shiftwidth=4: */
/*
Copyright (c) 2003, Michael Bretterklieber <michael@bretterklieber.com>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The names of the authors may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This code cannot simply be copied and put under the GNU Public License or
any other GPL-like (LGPL, GPL2) License.

    $Id: intro.xml,v 1.4 2008/10/09 15:16:20 cweiske Exp $
*/

require_once 'Auth/RADIUS.php';
require_once 'Crypt/CHAP.php';

//$type = 'PAP';
//$type = 'CHAP_MD5';
$type = 'MSCHAPv1';
//$type = 'MSCHAPv2';

$username = 'sepp';
$password = 'sepp';

$classname = 'Auth_RADIUS_' . $type;
$rauth = new $classname($username, $password);
$rauth->addServer('localhost', 0, 'testing123');
$rauth->setConfigfile('/etc/radius.conf');
$rauth->username = $username;

switch($type) {
case 'CHAP_MD5':
case 'MSCHAPv1':
    $classname = $type == 'MSCHAPv1' ? 'Crypt_CHAP_MSv1' : 'Crypt_CHAP_MD5';
    $crpt = new $classname;
    $crpt->password = $password;
    $rauth->challenge = $crpt->challenge;
    $rauth->chapid = $crpt->chapid;
    $rauth->response = $crpt->challengeResponse();
    $rauth->flags = 1;
// If you must use deprecated and weak LAN-Manager-Responses use this:
//    $rauth->lmResponse = $crpt->lmChallengeResponse();
//    $rauth->flags = 0;
    break;

case 'MSCHAPv2':
    $crpt = new Crypt_CHAP_MSv2;
    $crpt->username = $username;
    $crpt->password = $password;
    $rauth->challenge = $crpt->authChallenge;
    $rauth->peerChallenge = $crpt->peerChallenge;
    $rauth->chapid = $crpt->chapid;
    $rauth->response = $crpt->challengeResponse();
    break;

default:
    $rauth->password = $password;
    break;
}

if (!$rauth->start()) {
    printf("Radius start: %s<br>\n", $rauth->getError());
    exit;
}

$result = $rauth->send();
if (PEAR::isError($result)) {
    printf("Radius send failed: %s<br>\n", $result->getMessage());
    exit;
} else if ($result === true) {
    printf("Radius Auth succeeded<br>\n");
} else {
    printf("Radius Auth rejected<br>\n");
}

// get attributes, even if auth failed
if (!$rauth->getAttributes()) {
    printf("Radius getAttributes: %s<br>\n", $rauth->getError());
} else {
    $rauth->dumpAttributes();
}

$rauth->close();

?>

Here is the second example:

<?php
/* vim: set expandtab tabstop=4 shiftwidth=4: */
/*
Copyright (c) 2003, Michael Bretterklieber <michael@bretterklieber.com>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The names of the authors may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This code cannot simply be copied and put under the GNU Public License or
any other GPL-like (LGPL, GPL2) License.

    $Id: intro.xml,v 1.4 2008/10/09 15:16:20 cweiske Exp $
*/

require_once 'Auth/RADIUS.php';
require_once 'Crypt/CHAP.php';
$username = 'sepp';

$starttime = time();

$racct = new Auth_RADIUS_Acct_Start;
$racct->addServer('localhost', 0, 'testing123');
$racct->username = $username;
// RADIUS_AUTH_RADIUS => authenticated via Radius
// RADIUS_AUTH_LOCAL => authenicated local
// RADIUS_AUTH_REMOTE => authenticated remote
$racct->authentic = RADIUS_AUTH_LOCAL;
$status = $racct->start();
if(PEAR::isError($status)) {
    printf("Radius start: %s<br>\n", $status->getMessage());
    exit;
}
// you can put any additional attributes here
// $racct->putAttribute(RADIUS_ACCT_INPUT_PACKETS, 45236);
// $racct->putAttribute(RADIUS_ACCT_OUTPUT_PACKETS, 1212);
$result = $racct->send();
if (PEAR::isError($result)) {
    printf("Radius send failed: %s<br>\n", $result->getMessage());
    exit;
} else if ($result === true) {
    printf("Radius Acounting succeeded<br>\n");
} else {
    printf("Radius Acounting rejected<br>\n");
}

$racct->close();

// Wait a bit, that we can put the session-time
sleep(2);

// send an accounting update
$racct = new Auth_RADIUS_Acct_Update;
$racct->addServer('localhost', 0, 'testing123');
$racct->username = $username;
$racct->session_time = time() - $starttime;
$status = $racct->start();
if(PEAR::isError($status)) {
    printf("Radius start: %s<br>\n", $status->getMessage());
    exit;
}
$result = $racct->send();
if (PEAR::isError($result)) {
    printf("Radius send failed: %s<br>\n", $result->getMessage());
    exit;
} else if ($result === true) {
    printf("Radius Acounting succeeded<br>\n");
} else {
    printf("Radius Acounting rejected<br>\n");
}

// Wait a bit, that we can put the session-time
sleep(2);

// send the stop
$racct = new Auth_RADIUS_Acct_Stop;
$racct->addServer('localhost', 0, 'testing123');
$racct->username = $username;
$racct->session_time = time() - $starttime;
$status = $racct->start();
if(PEAR::isError($status)) {
    printf("Radius start: %s<br>\n", $status->getMessage());
    exit;
}
// you can put any additional attributes here
// $racct->putAttribute(RADIUS_ACCT_TERMINATE_CAUSE, RADIUS_TERM_SESSION_TIMEOUT);
$result = $racct->send();
if (PEAR::isError($result)) {
    printf("Radius send failed: %s<br>\n", $result->getMessage());
    exit;
} else if ($result === true) {
    printf("Radius Acounting succeeded<br>\n");
} else {
    printf("Radius Acounting rejected<br>\n");
}

$racct->close();

?>
Prev | Auth_RADIUS | Next
Auth_RADIUS | PEAR Manual | LiveUser


LiveUser

LiveUser

Table of Contents
  • Introduction -- About LiveUser
  • Setting it up -- Making the package and examples work
Prev | Authentication | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – About LiveUser

About LiveUser

LiveUser is an advanced authentication and permission framework that comes with a large array of out of the box features which can be used optionally. The base class is called LiveUser and is often referred to as the "client" and is what will be commonly be used to authenticate a specific user and then optionally make permission checks on this user.

LiveUser provides the following key features: The LiveUser class takes care of the login process and can be configured to use a certain permission container and one or more different auth containers. That means, you can have your users' data scattered amongst many data containers and have the LiveUser class try each defined container until the user is found. For example, you can have all website users who can apply for a new account online on the webserver's local database. Also, you want to enable all your company's employees to login to the site without the need to create new accounts for all of them. To achieve that, a second container can be defined to be used by the LiveUser class.

You can also define a permission container of your choice that will manage the rights for each user. Depending on the container, you can implement any kind of permission schemes for your application while having one consistent API.

Using different permission and auth containers, it's easily possible to integrate newly written applications with older ones that have their own ways of storing permissions and user data. Just make a new container type and you're ready to go!

Currently available are containers using: PEAR::DB, PEAR::MDB, PEAR::MDB2, ext/PDO, PEAR::XML_Tree, Session and PEAR::Auth.

There is also an external wiki dedicated to LiveUser:

At this point LiveUser is still in beta stage. Even so LiveUser is already being used on a wide range of production websites. A non exhaustive list can be found here.

The current roadmap for LiveUser can be viewed here.

A detailed introduction to the core concepts of LiveUser can be found in the following phpmag article.

This article was published in april 2004 and is therefore not entirely uptodate. However the core principles remain unchanged and most of the recent changes resolve around making the API more consistent and flexible. As a result the API examples are mostly out of date. The article also fails to mention the fact that the permission containers are now separated in a logic and a storage layer. This was done to remove logic duplication as well as to allow the implementation of a stackable storage approach, where users could configure LiveUser to first call a cache storage layer, which in turn would fetch the necessary data on demand from the actual storage layer.

A more recent article providing a step by step guide to LiveUser and the different permission containers can be found here.

Before you can use LiveUser you will need to setup the necessary data structures for the chosen container. Through the use of the configuration options it is possible to customize alot of the aspects of the storage layer. Most notably it is possible to alias field and table names. This should make it possible to integrate any legacy data into LiveUser. Depending on the container chosen you may have to use the database schema installer. The installer requires the MDB2_Schema and MDB2 packages and is able to handle most configuration options properly to be able to install the database schema directly into your database. You can find the install class in "[PEAR]/data/misc/schema/install.php". There is some sample code which is partially commented out at the top. Basically it's a two step process for both the auth and perm: (1) generate the schema xml file, (2) install the schema.

During the installation process the installer will create backup files of the installed schema. These files will enable the installer to attempt to alter the database if run again with a different configuration. However if these files exist the installer will always attempt to alter instead of creating the tables from scratch as long as you are using the sam DSN. If for some reason you need to create the tables from scratch again then please delete the backup files with the matching DSN. You can find the installer inside the data directory of your pear install directory. Its called install.php and at the top of the file you will find a number of sample API calls which are commented out.

An ER diagram of the database structure can be found here.

The diagram details what tables are needed for what permission complexity level. If you want to prevent the installer from installing tables you don't need you can modify the "tables" property of the instance of the permission container you pass to the generateSchema() method in the installer.

In order to get started with LiveUser the following two articles should help in getting off the ground.

The observer support in LiveUser allows users to automatically have LiveUser call certain callbacks on a number of internal events. It is documented here.

LiveUser also ship with a wide range of examples. These will be installed into the "docs" directory in your PEAR install directory. They try to illustrate various usage scenarios. The database examples come with a schema file please see the demodata.php in the examples root folder of the LiveUser package for details on how to install these schema files from the command line or from a browser. You will once again need MDB2_Schema to be able to install the schema files.

LiveUser package:

  • example1 illustrates using only a single authentication source (in this case XML) with several aliased fields and a custom field.

  • example2 illustrates using a single authentication with permissions (in this case XML) with the optional remember me feature and several aliased fields

  • example4 illustrates using multiple authentication sources (XML and database) with permissions (database) in a more real world news administration scenario

  • example5 illustrates using single authentication sources (database) with permissions (database) in a more real world news administration scenario

Prev | LiveUser | Next
LiveUser | PEAR Manual | Setting it up


Setting it up

Setting it up

Setting it up – Making the package and examples work

Example Steps for Getting the Examples Going

Getting the LiveUser examples working can be somewhat difficult for developers who are new to PHP and PEAR. Here is a list of steps necessary to get the example4 and GVN examples working with a MySQL database in LiveUser 0.16.12.

  1. Install PHP and MySQL OR Sign up with a web host that provides PHP and MySQL.

  2. Install PEAR. This is done either with the command line installer, or by uploading go-pear.php to your web host through FTP.

  3. Now install the PEAR packages LiveUser, MDB2, MDB2_Driver_mysql, HTML_Template_IT, HTML_QuickForm, and Var_Dump. Command line will be something like pear install --alldeps LiveUser-beta (repeat for each package). If you used the go-pear.php, there's some web-based way to install packages through that, but I haven't used it.

  4. Now create your empty database in MySQL.

  5. Now copy the files of example4 to your web root. On my Linux system the examples ended up in /usr/share/pear/docs/LiveUser/docs/examples and my Apache web root is at /var/www. You can find out where the examples are by executing pear list-files LiveUser.

  6. Create the database by viewing the demodata.php through your web browser with a URL like http://www.example.com/LU/demodata.php?dsn=mysql://dbuser:pwd@localhost/databasename&file=/var/www/LU/demodata.xml&create=1. You must replace the file path values and the database user, password, host, and database name with values appropriate for your own system. If this gives you a "success" message and you have phpMyAdmin or something, you should be able to look at the database now and see tables with data in them.

    It is reported that on some systems, you must make alterations to the demodata.xml file before this will run properly. Within all <is_active>..</is_active> tags replace the value "Y" with "1" and "N" with "0".

  7. Edit the conf.php file and enter your database information.

  8. At this point you should be able to view the index.html page through a web browser and log in and use example4.

  9. To get the GVN samples going, first create a "GVN" folder under your web root.

  10. Go through the GVN tutorials, starting from the beginning because there are dependencies, and save all of the sample files.

  11. In most of the files I found that the include to LiveUser/LiveUser.php had to be corrected to just be LiveUser.php.

  12. Copy the file Auth_XML.xml from example4 into the GVN folder.

  13. Copy your database information and the LiveUser configuration array from example4/conf.php into GVN's conf.php and conf_admin.php files.

  14. In example4, the users that are in the database are deactivated for some reason... in the peoples table change the values in the isactive column to 1.

The above steps got me to the point where I have the working sample app and pages that demonstrate adding users, etc.

Prev | LiveUser | Next
Introduction | PEAR Manual | LiveUser_Admin


LiveUser_Admin

LiveUser_Admin

LiveUser_Admin class which provides various ways to manage all relevant data used in LiveUser, like users, groups/roles, rights and their relations.

LiveUser_Admin provides the following key features: It can associate data from multiple authentication containers with a single permission container. Using different permission and auth containers, it's easily possible to integrate newly written applications with older ones that have their own ways of storing permissions and user data. Just make a new container type and you're ready to go! Currently available are containers using: PEAR::DB, PEAR::MDB, PEAR::MDB2, ext/PDO. LiveUser_Admin provides the following key features You'll be able to add/edit/delete/get things like:

  • Rights

  • Users

  • Groups

  • Areas

  • Applications

  • Subgroups

  • ImpliedRights

There is also an external wiki dedicated to LiveUser.

At this point LiveUser_Admin is still in beta stage. Even so LiveUser_Admin is already being used on a wide range of production websites. A non exhaustive list can be found here.

The current roadmap for LiveUser_Admin can be viewed here.

A detailed introduction to the core concepts of LiveUser can be found in the following phpmag article: http://www.php-mag.net/magphpde/magphpde_article/psecom,id,595,nodeid,21.html

This article was published in april 2004 and is therefore not entirely uptodate. The article also does not mention the SQL generator used in the LiveUser_Admin package. This feature has made the API much more flexible since now the entire storage schema is configurable and extensible. It also means that more or less any sort of filtering can be applied with on demand joining. On overview of this API can be found here: http://wiki.pooteeweet.org/LiveUser/AdminFilters

A more recent article providing a step by step guide to LiveUser and the different permission containers can be found here.

An ER diagram of the database structure can be found here.

The diagram details what tables are needed for what permission complexity level. If you want to prevent the installer from installing tables you don't need you can modify the "tables" property of the instance of the permission container you pass to the generateSchema() method in the installer.

In order to get started with LiveUser the following two articles should help in getting off the ground.

LiveUser_Admin also ship with a wide range of examples. These will be installed into the "docs" directory in your PEAR install directory. They try to illustrate various usage scenarios. The database examples come with a schema file please see the demodata.php in the examples root folder of the LiveUser package for details on how to install these schema files from the command line or from a browser. You will once again need MDB2_Schema to be able to install the schema files.

LiveUser_Admin package:

  • example 1 illustrates various API calls to most methods in the admin API and custom fields

  • example3 illustrates using single authentication sources (database) with permissions (database) and the optional remember me feature in a more real world restricted page access scenario

Prev | Authentication | Next
Setting it up | PEAR Manual | Benchmarking


Benchmarking

Benchmarking

Provides Packages for Benchmarking and Profiling

Table of Contents
  • Benchmarking_Benchmark
Prev | PEAR Packages | Next
LiveUser_Admin | PEAR Manual | Benchmarking_Benchmark


Benchmarking_Benchmark

Benchmarking_Benchmark

Provides a simple framework for profiling and benchmarking your PHP applications.

Table of Contents
  • Introduction -- About Benchmarking_Benchmark
  • Benchmark_Timer -- About Benchmark_Timer
  • Benchmark_Profiler -- About Benchmark_Profiler
  • Benchmark_Iterate -- About Benchmark_Iterate
Prev | Benchmarking | Next
Benchmarking | PEAR Manual | Introduction


Introduction

Introduction

Introduction – About Benchmarking_Benchmark

About Benchmarking_Benchmark

Benchmark is a simple framework that allows you time, profile and benchmark your PHP scripts and applications. Benchmark provides you with three classes to enable you to profile: Benchmark_Timer, Benchmark_Profiler and Benchmark_Iterate.

The package is very easy to use. We'll discuss each of the three classes in detail, but some concepts are common. You basically instantiate one of the classes, begin your script (or portion of code that you want to profile) and analyze the results afterward.

All the three classes have two modes of operation: automatic and manual. In the automatic mode of operation, the profiling is automatically started and stopped, and results displayed. In the manual mode, you are responsible for starting, stopping and displaying the results.

The automatic mode makes sense in cases where you want to quickly test a fixed portion of code like a script or a single function. The manual mode offers you more control, which means arbitrary portions of code can be profiled, and the results can be carefully analyzed before being displayed. In the automatic mode of operation, the results are always displayed; while in the manual mode you have the option of logging them or storing them in a database.

If you wish to operate a class in automatic mode, simply pass the TRUE parameter to its constructor. Instantiating a class without a parameter or with the FALSE parameter sets the mode of operation to manual for that class.

Which class to choose?

Benchmark_Timer is the most fundamental class in the package. It performs the simple function of recording the amount of time it takes for a fixed amount of code to execute.

Benchmark_Profiler behaves just like Benchmark_Timer with the exception that you are allowed to specify sections between the start and stop times, at which point the timing details are recorded. This provides the ability to nest timers and profile functions which are called multiple times.

Benchmark_Iterate is a class that runs a particular function several times over and records the amount of time it took for each iteration to execute.

Prev | Benchmarking_Benchmark | Next
Benchmarking_Benchmark | PEAR Manual | Benchmark_Timer


Benchmark_Timer

Benchmark_Timer

Benchmark_Timer – About Benchmark_Timer

About Benchmark_Timer

As mentioned before, this class simply records the time taken for a particular snippet of code to execute. In the automatic mode, this means the code remaining after the class's instantiation. In manual mode, the snippet of code to be timed is specified between calls to the start() and stop() methods of the class.

Additionally, you may specify markers between the snippet of code to be timed. The timing information is recorded wherever markers are defined.

An example will make this clear.

Benchmark_Timer in automatic mode

<?php
require_once "Benchmark/Timer.php";

$timer = new Benchmark_Timer(TRUE);
// Timer is in automatic mode, so timing starts here.

$j = array();
for ($i = 0; $i < 100; $i++) {
    $j[] = $i;
    if ($i == 49)
        $timer->setMarker('Midway');
}

// Timer automatically stops and results are displayed.
?>

The example above will generate an output as shown below when run with the PHP CLI SAPI. Running it with the Apache SAPI will produce the same results, but formatted as HTML.

Results of a test run of Benchmark_Timer

----------------------------------------------------
marker  time index            ex time         perct
----------------------------------------------------
Start   1182558324.48638900   -                0.00%
----------------------------------------------------
Midway  1182558324.48655800   0.000169        62.13%
----------------------------------------------------
Stop    1182558324.48666100   0.000103        37.87%
----------------------------------------------------
total   -                     0.000272       100.00%
----------------------------------------------------

In most cases however, you would like to do something with that information. When you run the timer in manual mode, you can obtain the results as an associative array using the getProfiling() method. To display the information (as shown above) use the display() method. More information on the methods that Benchmark_Timer implements is available in the API Documentation.

Prev | Benchmarking_Benchmark | Next
Introduction | PEAR Manual | Benchmark_Profiler


Benchmark_Profiler

Benchmark_Profiler

Benchmark_Profiler – About Benchmark_Profiler

About Benchmark_Profiler

This class behaves mostly like Benchmark_Timer with the exception that you are allowed to specify the beginning and end of sections within the code to be profiled. sections are different from markers (markers) don't have ends in the sense that they are stateful and remember how many times they have been entered.

Timing information is recorded at the beginning and end of the code to be profiled and at the beginning and end of every section everytime it is encountered. An example follows.

Benchmark_Profiler in manual mode

<?php

require_once 'Benchmark/Profiler.php';

$profiler = new Benchmark_Profiler;

function wasteTime() {
    $j = 2;
    for ($i = 0; $i < 100; $i++) {
        $j = $j * 10;
    }
    return;
}

function myFunction() {
    global $profiler;
    $profiler->enterSection('myFunction');
    wasteTime();
    $profiler->leaveSection('myFunction');
    return;
}

// Manual mode, so start manually
$profiler->start();

wasteTime();
myFunction();
myFunction();
wasteTime();

// Manual mode, stop and display results
$profiler->stop();
$profiler->display();

?>

The example above will generate an output as shown below when run with the PHP CLI SAPI. Running it with the Apache SAPI will produce the same results, but formatted as HTML.

Results of a test run of Benchmark_Profiler

------------------------------------------------------------------------------------
Section             Total Ex Time         Netto Ex Time         #Calls    Percentage
------------------------------------------------------------------------------------
myFunction          5.8174133300781E-5    5.8174133300781E-5    2          17.22%
Global              0.00033783912658691   0.00027966499328613   1         100.00%

As you can see, the default output may not be too helpful. You can obtain detailed section by section profiling information in manual mode through methods like getSectionInformations() and getAllSectionsInformations(). Refer to the API documentation for more information.

Prev | Benchmarking_Benchmark | Next
Benchmark_Timer | PEAR Manual | Benchmark_Iterate


Benchmark_Iterate

Benchmark_Iterate

Benchmark_Iterate – About Benchmark_Iterate

About Benchmark_Iterate

This class is useful when you want to iterate over a single piece of code (a function) several times over. Timing information is recorded for every iteration. An example follows.

Benchmark_Iterate in manual mode

<?php

require_once 'Benchmark/Iterate.php';

$benchmark = new Benchmark_Iterate;

function calculation($num) {
    $x = sin($num) * 100;
    $y = tan($x);
    return;
}

$benchmark->run(100, 'calculation', 45.6);
$result = $benchmark->get();
print_r($result);

?>

The example above will generate an output as shown below when run with the PHP CLI SAPI.

Results of a test run of Benchmark_Iterate

Array
(
    [1] => 0.000073
    [2] => 0.000014
    [3] => 0.000011
    [4] => 0.000011
    [5] => 0.000011
    ..93 more results..
    [99] => 0.000011
    [100] => 0.000011
    [mean] => 0.000011
    [iterations] => 100
)

You can display formatted results either by running the script in automatic mode or by using the display() method. For more information of the methods this class implements, refer to the API documentation.

Prev | Benchmarking_Benchmark | Next
Benchmark_Profiler | PEAR Manual | Caching


Caching

Caching

Provides Packages for creating caches

Table of Contents
  • Cache_Lite
Prev | PEAR Packages | Next
Benchmark_Iterate | PEAR Manual | Cache_Lite


Cache_Lite

Cache_Lite

Cache_Lite provides a fast, light and safe cache system. It's optimized for file containers and protected against cache corruptions (because it uses file locking and/or hash tests).

Table of Contents
  • Introduction -- Introduction to Cache_Lite
  • constructor Cache_Lite::Cache_Lite -- Constructor
  • Cache_Lite::get -- Test if a cache is available and (if yes) return it
  • Cache_Lite::save -- Save some data in a cache file
  • Cache_Lite::remove -- Remove a cache file
  • Cache_Lite::clean -- Clean the cache
  • Cache_Lite::setToDebug -- Set to debug mode
  • Cache_Lite::setLifeTime -- Set a new life time
  • Cache_Lite::saveMemoryCachingState -- $id
  • Cache_Lite::getMemoryCachingState -- $id
  • Cache_Lite::lastModified -- Return the cache last modification time
  • Cache_Lite::raiseError -- Trigger a PEAR error
  • Cache_Lite::extendLife -- Extend the life of a valid cache file
  • constructor Cache_Lite_Output::Cache_Lite_Output -- Constructor
  • Cache_Lite_Output::start -- Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.
  • Cache_Lite_Output::end -- Stop the output buffering started by the start() method and store the output to a cache file
  • constructor Cache_Lite_Function::Cache_Lite_Function -- Constructor
  • Cache_Lite_Function::call -- Calls a cacheable function or method (or not if there is already a cache for it)
  • Cache_Lite_Function::drop -- Drop a cache file
  • constructor Cache_Lite_File::Cache_Lite_File -- Constructor
  • Cache_Lite_File::get -- Test if a cache is available and (if yes) return it
Prev | Caching | Next
Caching | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Cache_Lite

Description

PEAR::Cache_Lite is a little cache system. It's optimized for high traffic websites so it is really fast and safe (because it uses file locking and/or anti-corruption tests).

Note : An independent documentation of Cache_Lite is available in chinese on this page.

Goals and technical details

speed

Before all, PEAR::Cache_Lite has to be extremely fast. That returns the use of PEAR possible on sites with high traffic without falling in hi-level hardware solutions.

You can find more details about cache_lite technical choices on this document, but the main idea is to include PEAR.php file ONLY when an error occurs (very rare).

simplicity

Because the cache system is often embedded in the application layer, PEAR::Cache_Lite kernel has to be small and flexible with an adapted licence (LGPL). Advanced functionality can be found in files that extend the core.

security

On high traffic websites, the cache system has to be really protected against cache files corruptions (because of concurrent accesses in read/write mode). Very few cache systems offer a protection against this problem.

File locking is not a perfect solution because it is useless with NFS or multithreaded servers. So in addition to it, PEAR::Cache_Lite offers two fully transparent mechanisms (based on hash keys) to guarantee the security of the data in all circumstances. Just have a look at the link given in the previous paragraph for more details.

Usage

general usage

Every module of Cache_Lite follows the same philosophy.

Parameters (others than default ones) are passed to the constructor by using an associative array.

A cache file is identified by a cache ID (and eventually a group). For obvious flexibility reasons, the logic of IDs choice is left to the developer.

In the following, we will use the term "group" as a pool of cache files and the term "block" as a piece of an HTML page.

core

Let's start with a simple example : the page is built, then recovered with a unique variable (string):

<?php

// Include the package
require_once('Cache/Lite.php');

// Set a id for this cache
$id = '123';

// Set a few options
$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

// Create a Cache_Lite object
$Cache_Lite = new Cache_Lite($options);

// Test if thereis a valide cache for this id
if ($data = $Cache_Lite->get($id)) {

    // Cache hit !
    // Content is in $data
    // (...)

} else { // No valid cache found (you have to make the page)

    // Cache miss !
    // Put in $data datas to put in cache
    // (...)
    $Cache_Lite->save($data);

}

?>

If you wish use a cache per block and not a global cache, take as example the following script:

<?php
require_once('Cache/Lite.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

// Create a Cache_Lite object
$Cache_Lite = new Cache_Lite($options);

if ($data = $Cache_Lite->get('block1')) {
    echo($data);
} else {
    $data = 'Data of the block 1';
    $Cache_Lite->save($data);
}

echo('<br><br>Non cached line !<br><br>');

if ($data = $Cache_Lite->get('block2')) {
    echo($data);
} else {
    $data = 'Data of the block 2';
    $Cache_Lite->save($data);
}

?>

core

However, it is not always possible to recover all the contents of a page in a single string variable. Thus Cache_Lite_Output comes to our aid :

<?php

require_once('Cache/Lite/Output.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 10
);

$cache = new Cache_Lite_Output($options);

if (!($cache->start('123'))) {
    // Cache missed...
    for($i=0;$i<1000;$i++) { // Making of the page...
        echo('0123456789');
    }
    $cache->end();
}

?>

The idea is the same for a per block usage :

<?php

require_once('Cache/Lite/Output.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 10
);

$cache = new Cache_Lite_Output($options);

if (!($cache->start('block1'))) {
    // Cache missed...
    echo('Data of the block 1 !');
    $cache->end();
}

echo('Non cached line !');

if (!($cache->start('block2'))) {
    // Cache missed...
    echo('Data of the block 2 !');
    $cache->end();
}

?>

IMPORTANT NOTE

For a maximum efficiency with Cache_Lite, do not systematically include every package the page needs. ONLY load the modules you need when the page is not in the cache (and has to be recomputed) by using a conditional inclusion.

The BAD way :

<?php
   require_once("Cache/Lite.php");
   require_once("...")
   require_once("...")
   // (...)
   $cache = new Cache_Lite();
   if ($data = $Cache_Lite->get($id)) { // cache hit !
       echo($data);
   } else { // page has to be (re)constructed in $data
       // (...)
       $Cache_Lite->save($data);
   }
?>

Here is the good way (often more than twice faster) :

<?php
   require_once("Cache/Lite.php");
   // (...)
   $cache = new Cache_Lite();
   if ($data = $Cache_Lite->get($id)) { // cache hit !
       echo($data);
   } else { // page has to be (re)constructed in $data
       require_once("...")
       require_once("...")
       // (...)
       $Cache_Lite->save($data);
   }
?>

Conclusion

To go further with Cache_Lite, have a look at examples and technical details bundled with the package.

Prev | Cache_Lite | Next
Cache_Lite | PEAR Manual | constructor Cache_Lite::Cache_Lite


constructor Cache_Lite::Cache_Lite

constructor Cache_Lite::Cache_Lite

constructor Cache_Lite::Cache_Lite() – Constructor

Synopsis

require_once 'Cache/Lite.php';

void constructor Cache_Lite::Cache_Lite ( array $options = array(NULL) )

Description

The constructor of the Cache_Lite core class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options

Option | Data Type | Default Value | Description
cacheDir | string | /tmp/ | directory where to put the cache file (with a trailing slash at the end)
caching | boolean | TRUE | enable / disable caching
lifeTime | integer | 3600 | cache lifetime in seconds (since 1.6.0beta 1, you can use a null value for an eternal cache lifetime)
fileLocking | boolean | TRUE | enable / disable fileLocking. Can avoid cache corruption under bad circumstances.
writeControl | boolean | TRUE | enable / disable write control. Enable write control will lightly slow the cache writing but not the cache reading. Write control can detect some corrupt cache files but maybe it's not a perfect control.
readControl | boolean | TRUE | enable / disable read control. If enabled, a control key is embeded in cache file and this key is compared with the one calculated after the reading
readControlType | string | crc32 | Type of read control (only if read control is enabled). Must be 'md5' (for a md5 hash control (best but slowest)), 'crc32' (for a crc32 hash control (lightly less safe but faster)) or 'strlen' (for a length only test (fastest))
pearErrorMode | integer | CACHE_LITE_ERROR_RETURN | pear error mode (when raiseError is called) (CACHE_LITE_ERROR_RETURN for just returning a PEAR_Error object or CACHE_LITE_ERROR_DIE for immediate stop of the script (good for debug) )
fileNameProtection | boolean | TRUE | file Name protection (if set to true, you can use any cache id or group name, if set to false, it can be faster but cache ids and group names will be used directly in cache file names so be careful with special characters...)
automaticSerialization | boolean | FALSE | enable / disable automatic serialization (allows non-string data to be saved, with a small performance decrease)
memoryCaching | boolean | FALSE | enable / disable "Memory Caching" (NB : there is no lifetime for memory caching, only the end of the script)
onlyMemoryCaching | boolean | FALSE | enable / disable "Only Memory Caching" (if enabled, files are not used anymore)
memoryCachingLimit | integer | 1000 | max number of records to store into memory caching
automaticCleaningFactor | integer | 0 | Disable / Tune the automatic cleaning process. The automatic cleaning process destroy too old (for the given life time) cache files when a new cache file is written. 0 means "no automatic cache cleaning", 1 means "systematic cache cleaning" (slow), x>1 means "automatic cleaning randomly 1 times on x cache writes". A value between 20 and 200 is maybe a good start.
hashedDirectoryLevel | integer | 0 | Set the hashed directory structure level. 0 means "no hashed directory structure", 1 means "one level of directory", 2 means "two levels"... This option can speed up Cache_Lite only when you have many thousands of cache file. Only specific benchs can help you to choose the perfect value for you. Maybe, 1 or 2 is a good start.
errorHandlingAPIBreak | boolean | FALSE | If set to true, it introduces a little API break but the error handling is better in CACHE_LITE_ERROR_RETURN mode (especially with the save() method which can return a PEAR_Error object).

Throws

No exceptions thrown.

Note

This function can not be called statically.

Example

Using most common options

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);

$cache = new Cache_Lite($options);

?>
Prev | Cache_Lite | Next
Introduction | PEAR Manual | Cache_Lite::get


Cache_Lite::get

Cache_Lite::get

Cache_Lite::get() – Test if a cache is available and (if yes) return it

Synopsis

require_once 'Cache/Lite.php';

string Cache_Lite::get ( string $id , string $group = 'default' , boolean $doNotTestCacheValidity = false )

Description

One of the main method of Cache_Lite : test the validity of a cache file and return it if it's available (FALSE else)

Parameter

string $id

cache id

string $group

name of the cache group

boolean $doNotTestCacheValidity

if set to TRUE, the cache validity won't be tested

Return value

returns data of the cache (or false if no cache available)

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite($options);

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // Content is in $data
    // (...)

} else {

    // No valid cache found (you have to make and save the page)
    // (...)

}

?>
Prev | Cache_Lite | Next
constructor Cache_Lite::Cache_Lite | PEAR Manual | Cache_Lite::save


Cache_Lite::save

Cache_Lite::save

Cache_Lite::save() – Save some data in a cache file

Synopsis

require_once 'Cache/Lite.php';

boolean Cache_Lite::save ( string $data , string $id = NULL , string $group = 'default' )

Description

save the given data (which has to be a string if automaticSerialization is set to FALSE (default)).

Parameter

string $data

data to put in a cache file (can be another type than strings if automaticSerialization is TRUE).

string $id

cache id

string $group

name of the cache group

Return value

returns true if no problem

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite($options);

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // Content is in $data
    echo $data;

} else {

    // No valid cache found (you have to make and save the page)
    $data = '<html><head><title>test</title></head><body><p>this is a test</p></body></html>';
    echo $data;
    $cache->save($data);

}

?>
Prev | Cache_Lite | Next
Cache_Lite::get | PEAR Manual | Cache_Lite::remove


Cache_Lite::remove

Cache_Lite::remove

Cache_Lite::remove() – Remove a cache file

Synopsis

require_once 'Cache/Lite.php';

boolean Cache_Lite::remove ( string $id , string $group = 'default' )

Description

remove the given cache file (specified with its id and group)

Parameter

string $id

cache id

string $group

name of the cache group

Return value

returns true if no problem

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite($options);

$cache->remove('id_of_the_page');

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // [IMPOSSIBLE !]

} else {

    // No valid cache found (you have to make and save the page)
    $data = '<html><head><title>test</title></head><body><p>this is a test</p></body></html>';
    $cache->save($data);

}

?>

This is a dummy example because the cache is destroyed at the beginning of the script ! So the first case of the if statement is impossible.

Prev | Cache_Lite | Next
Cache_Lite::save | PEAR Manual | Cache_Lite::clean


Cache_Lite::clean

Cache_Lite::clean

Cache_Lite::clean() – Clean the cache

Synopsis

require_once 'Cache/Lite.php';

boolean Cache_Lite::clean ( string $group = false , string $mode = 'ingroup'; )

Description

if no group is specified all cache files will be destroyed ; else only cache files of the specified group will be destroyed

Parameter

string $group

name of the cache group

string $mode

flush cache mode : 'old' (clean too old cache files for the current lifetime), 'ingroup' (clean all cache files for the given group), 'notingroup' (clean all the cache files except for the given group), [since 1.5.0 beta] 'callback_myFunc' (call the function 'myFunc' with the complete path file and the group in parameters, if the callback return 'true', the cache file is deleted).

Return value

returns true if no problem

Note

This function can not be called statically.

Example

Usage

<?php
require_once 'Cache/Lite.php';

$options = array('cacheDir' => '/tmp/');
$cache = new Cache_Lite($options);

$cache->clean();

?>

This example cleans all of the cache files.

Prev | Cache_Lite | Next
Cache_Lite::remove | PEAR Manual | Cache_Lite::setToDebug


Cache_Lite::setToDebug

Cache_Lite::setToDebug

Cache_Lite::setToDebug() – Set to debug mode

Synopsis

require_once 'Cache/Lite.php';

void Cache_Lite::setToDebug ( )

Description

when an error is found, the script will stop and the message will be displayed (in debug mode only) ; same effect than pearErrorMode option in the constructor

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::clean | PEAR Manual | Cache_Lite::setLifeTime


Cache_Lite::setLifeTime

Cache_Lite::setLifeTime

Cache_Lite::setLifeTime() – Set a new life time

Synopsis

require_once 'Cache/Lite.php';

void Cache_Lite::setLifeTime ( int $newLifeTime )

Description

change the cache life time

Parameter

integer $newLifeTime

new life time (in seconds)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::setToDebug | PEAR Manual | Cache_Lite::saveMemoryCachingState


Cache_Lite::saveMemoryCachingState

Cache_Lite::saveMemoryCachingState

Cache_Lite::saveMemoryCachingState() –

Synopsis

require_once 'Cache/Lite.php';

void Cache_Lite::saveMemoryCachingState ( string $id , string $group = 'default' )

Description

save the current state of the memory caching array into a classical cache file

Parameter

string $id

cache id

string $group

name of the cache group

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::setLifeTime | PEAR Manual | Cache_Lite::getMemoryCachingState


Cache_Lite::getMemoryCachingState

Cache_Lite::getMemoryCachingState

Cache_Lite::getMemoryCachingState() –

Synopsis

require_once 'Cache/Lite.php';

void Cache_Lite::getMemoryCachingState ( string $id , string $group = 'default' , bool $doNotTestCacheValidity = false )

Description

load a previously saved state of a memory caching array from a classical cache file

Parameter

string $id

cache id

string $group

name of the cache group

boolean $doNotTestCacheValidity

if set to TRUE, the cache validity won't be tested

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::saveMemoryCachingState | PEAR Manual | Cache_Lite::lastModified


Cache_Lite::lastModified

Cache_Lite::lastModified

Cache_Lite::lastModified() – Return the cache last modification time

Synopsis

require_once 'Cache/Lite.php';

int Cache_Lite::lastModified ( )

Description

[ONLY FOR CACHE_LITE HACKERS] return the cache last modification time

Return value

returns last modification time

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::getMemoryCachingState | PEAR Manual | Cache_Lite::raiseError


Cache_Lite::raiseError

Cache_Lite::raiseError

Cache_Lite::raiseError() – Trigger a PEAR error

Synopsis

require_once 'Cache/Lite.php';

void Cache_Lite::raiseError ( string $msg , int $code )

Description

include dynamically the PEAR.php file and trigger a PEAR error

To improve performances, the PEAR.php file is included dynamically. The file is so included only when an error is triggered. So, in most cases, the file isn't included and perfs are much better.

Parameter

string $msg

error message

integer $code

error code

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::lastModified | PEAR Manual | Cache_Lite::extendLife


Cache_Lite::extendLife

Cache_Lite::extendLife

Cache_Lite::extendLife() – Extend the life of a valid cache file

Synopsis

require_once 'Cache/Lite.php';

void Cache_Lite::extendLife ( )

Description

[since Cache_Lite-1.7.0beta2] Extend the life of an existent cache file. The cache file is "touched", so it starts a new lifetime period. See this feature request for more details.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Example

Classical use

<?php
require_once "Cache/Lite.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);

$cache = new Cache_Lite($options);
$id = 'foo';
if (!($data = $cache->get($id))) {
    // the cache is not hit !
    $data = '123456789';
    $cache->save($data);
} else {
    // the cache is hit !
    if (isset($_GET['extend'])) {
        $cache->extendLife();
    }
}
echo($data);

?>
Prev | Cache_Lite | Next
Cache_Lite::raiseError | PEAR Manual | constructor Cache_Lite_Output::Cache_Lite_Output


constructor Cache_Lite_Output::Cache_Lite_Output

constructor Cache_Lite_Output::Cache_Lite_Output

constructor Cache_Lite_Output::Cache_Lite_Output() – Constructor

Synopsis

require_once 'Cache/Lite/Output.php';

void constructor Cache_Lite_Output::Cache_Lite_Output ( array $options )

Description

The constructor of the Cache_Lite_Output class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options (see Cache_Lite constructor for details)

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite::extendLife | PEAR Manual | Cache_Lite_Output::start


Cache_Lite_Output::start

Cache_Lite_Output::start

Cache_Lite_Output::start() – Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.

Synopsis

require_once 'Cache/Lite/Output.php';

boolean Cache_Lite_Output::start ( string $id , string $group = 'default' , boolean $doNotTestCacheValidity = false )

Description

Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.

Parameter

string $id

cache id

string $group

name of the cache group

boolean $doNotTestCacheValidity

if set to TRUE, the cache validity won't be tested

Return value

returns true if the cache is hit (false else)

Note

This function can not be called statically.

Example

classical using

<?php
require_once "Cache/Lite/Output.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite_Output($options);

if (!($cache->start('id_of_the_page'))) {

    // Cache not hit !
    // All the output is bufferised until the end() method
    // (...)

    $cache->end();

}

?>
Prev | Cache_Lite | Next
constructor Cache_Lite_Output::Cache_Lite_Output | PEAR Manual | Cache_Lite_Output::end


Cache_Lite_Output::end

Cache_Lite_Output::end

Cache_Lite_Output::end() – Stop the output buffering started by the start() method and store the output to a cache file

Synopsis

require_once 'Cache/Lite/Output.php';

void Cache_Lite_Output::end ( )

Description

Stop the output buffering started by the start() method and store the output to a cache file

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite/Output.php";

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 7200,
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = Cache_Lite_Output($options);

if (!($cache->start('id_of_the_page'))) {

    // Cache not hit !
    // All the output is bufferised until the end() method
    // (...)

    $cache->end(); // the bufferised output is now stored into a cache file

}

?>
Prev | Cache_Lite | Next
Cache_Lite_Output::start | PEAR Manual | constructor Cache_Lite_Function::Cache_Lite_Function


constructor Cache_Lite_Function::Cache_Lite_Function

constructor Cache_Lite_Function::Cache_Lite_Function

constructor Cache_Lite_Function::Cache_Lite_Function() – Constructor

Synopsis

require_once 'Cache/Lite/Function.php';

void constructor Cache_Lite_Function::Cache_Lite_Function ( array $options = array(NULL) )

Description

The constructor of the Cache_Lite_Output class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options (see Cache_Lite constructor for details). Be careful, with Cache_Lite_Function, additional options are available (comparatively to Cache_Lite). There are described on the following table.

Option | Data Type | Default Value | Description
[...] | [...] | [...] | See Cache_Lite constructor for more options
defaultGroup | string | Cache_Lite_Function | default cache group for function caching
debugCacheLiteFunction | boolean | FALSE | debug the caching process
dontCacheWhenTheOutputContainsNOCACHE | boolean | FALSE | Don't cache the method call when its output contains the string "NOCACHE". If set to true, the output of the method will never be displayed (because the output is used to control the cache)
dontCacheWhenTheResultIsFalse | boolean | FALSE | Don't cache the method call when its result is false
dontCacheWhenTheResultIsNull | boolean | FALSE | Don't cache the method call when its result is null

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite_Output::end | PEAR Manual | Cache_Lite_Function::call


Cache_Lite_Function::call

Cache_Lite_Function::call

Cache_Lite_Function::call() – Calls a cacheable function or method (or not if there is already a cache for it)

Synopsis

require_once 'Cache/Lite/Function.php';

mixed Cache_Lite_Function::call ( string$functionName , mixed$arg1 , mixed$arg2 , mixed$arg3 , mixed... )

Description

call the given function with given arguments only if there is no cache about it ; else, the output of the function is read from the cache then send to the browser and the return value if read also from the cache and returned.

Return value

returns result of the function/method

Note

This function can not be called statically.

Example

classical using with a function

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$cache->call('function_to_bench', 12, 45);

function function_to_bench($arg1, $arg2)
{
    echo "This is the output of the function function_to_bench($arg1, $arg2) !<br>";
    return "This is the result of the function function_to_bench($arg1, $arg2) !<br>";
}

?>

Example

classical using with a method

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$obj = new bench();
$obj->test = 666;

$cache->call('obj->method_to_bench', 12, 45);

class bench
{
    var $test;

    function method_to_bench($arg1, $arg2)
    {
        echo "\$obj->test = $this->test and this is the output of the method \$obj->method_to_bench($arg1, $arg2) !<br>";
        return "\$obj->test = $this->test and this is the result of the method \$obj->method_to_bench($arg1, $arg2) !<br>";
    }

}

?>

If you try to use Cache_Lite_Function with $this object ($cache->call('this->method',...) for example), have a look first at the last example of this page.

Example

classical using with a static method

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$cache->call('bench::static_method_to_bench', 12, 45);

class bench
{
    var $test;

    function static_method_to_bench($arg1, $arg2) {
        echo "This is the output of the function static_method_to_bench($arg1, $arg2) !<br>";
        return "This is the result of the function static_method_to_bench($arg1, $arg2) !<br>";
    }
}

?>

Example

another using with a method (how to use cache $this->method() calls)

<?php

// Since Cache_Lite-1.7.0beta2

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$obj = new foo($options);

class foo
{

    var $test;

    function foo($options)
    {
        $cache = new Cache_Lite_Function($options);
        $this->test = 'foobar';
        $cache->call(array(&$this, 'method_bar'), 12, 45);
    }

    function method_bar($arg1, $arg2)
    {
        echo "\$this->test = $this->test and this is the output of the method \$this->method_bar($arg1, $arg2) !<br>";
        return "\$this->test = $this->test and this is the result of the method \$this->method_bar($arg1, $arg2) !<br>";
    }

}

?>

So, for method calls, the best way is to use array(&$object, 'nameOfTheMethod') as first argument instead of '$object->nameOfTheMethod' which doesn't work with "$this" for example.

Prev | Cache_Lite | Next
constructor Cache_Lite_Function::Cache_Lite_Function | PEAR Manual | Cache_Lite_Function::drop


Cache_Lite_Function::drop

Cache_Lite_Function::drop

Cache_Lite_Function::drop() – Drop a cache file

Synopsis

require_once 'Cache/Lite/Function.php';

boolean Cache_Lite_Function::drop ( string$functionName , mixed$arg1 , mixed$arg2 , mixed$arg3 , mixed... )

Description

[since Cache_Lite 1.6.0beta1] Drop the cache file of the corresponding function call with given arguments.

Return value

returns true if ok

Note

This function can not be called statically.

Example

classical using with a function

<?php

require_once('Cache/Lite/Function.php');

$options = array(
    'cacheDir' => '/tmp/',
    'lifeTime' => 3600
);

$cache = new Cache_Lite_Function($options);

$cache->call('function_to_bench', 12,45);
$cache->call('function_to_bench', 12,45);

// clean the corresponding cache file
$cache->drop('function_to_bench', 12, 45);

function function_to_bench($arg1, $arg2)
{
    echo "This is the output of the function function_to_bench($arg1, $arg2) !<br>";
    return "This is the result of the function function_to_bench($arg1, $arg2) !<br>";
}

?>
Prev | Cache_Lite | Next
Cache_Lite_Function::call | PEAR Manual | constructor Cache_Lite_File::Cache_Lite_File


constructor Cache_Lite_File::Cache_Lite_File

constructor Cache_Lite_File::Cache_Lite_File

constructor Cache_Lite_File::Cache_Lite_File() – Constructor

Synopsis

require_once 'Cache/Lite/File.php';

void constructor Cache_Lite_File::Cache_Lite_File ( array $options )

Description

The constructor of the Cache_Lite_File class. You can give an associative array as an argument to set a lot of options.

Parameter

array $options

associative array to set a lot of options (see Cache_Lite constructor for details). Be careful, with Cache_Lite_File, there is an additional "mandatory option" described on the following table.

Option | Data Type | Default Value | Description
[...] | [...] | [...] | See Cache_Lite constructor for more options
masterFile [REQUIRED] | string | '' | complete path of the file used for controlling the cache lifetime

Note

This function can not be called statically.

Prev | Cache_Lite | Next
Cache_Lite_Function::drop | PEAR Manual | Cache_Lite_File::get


Cache_Lite_File::get

Cache_Lite_File::get

Cache_Lite_File::get() – Test if a cache is available and (if yes) return it

Synopsis

require_once 'Cache/Lite/File.php';

string Cache_Lite_File::get ( string $id , string $group = 'default' )

Description

test the validity of a cache file and return it if it's available (FALSE else)

Parameter

string $id

cache id

string $group

name of the cache group

Return value

returns data of the cache (or false if no cache available)

Note

This function can not be called statically.

Example

Usage

<?php
require_once "Cache/Lite/File.php";

$options = array(
    'cacheDir' => '/tmp/',
    'masterFile' => '/home/web/config.xml',
    'pearErrorMode' => CACHE_LITE_ERROR_DIE
);
$cache = new Cache_Lite_File($options);

if ($data = $cache->get('id_of_the_page')) {

    // Cache hit !
    // Content is in $data
    // (...)

} else {

    // No valid cache found (you have to make and save the page)
    // (...)

}

?>
Prev | Cache_Lite | Next
constructor Cache_Lite_File::Cache_Lite_File | PEAR Manual | Configuration


Configuration

Configuration

Provides Packages for managing configurations

Table of Contents
  • Config
Prev | PEAR Packages | Next
Cache_Lite_File::get | PEAR Manual | Config


Config

Config

The Config package provides methods for configuration manipulation.

Table of Contents
  • Introduction -- What Config can do
  • Editing a configuration -- How to manipulate your configuration content
  • Available Containers -- Supported formats
  • Config::Config -- constructor
  • Config::getRoot -- Return root container for config object
  • Config::isConfigTypeRegistered -- Returns TRUE if container is registered
  • Config::parseConfig -- Parse datasource contents
  • Config::registerConfigType -- Registers a custom Config container
  • Config::setRoot -- Set content of root Config_container object
  • Config::writeConfig -- Write container content to datasource
  • Config_Container::Config_Container -- Constructor
  • Config_Container::addItem -- Add item to this item.
  • Config_Container::countChildren -- Count children of container
  • Config_Container::createBlank -- Add blank line to item
  • Config_Container::createComment -- Add comment to item
  • Config_Container::createDirective -- Add directive to item
  • Config_Container::createItem -- Create new child for section item
  • Config_Container::createSection -- Add section to item
  • Config_Container::getAttribute -- Get attribute value of item
  • Config_Container::getAttributes -- Get item attributes
  • Config_Container::getChild -- Return child object at specified index.
  • Config_Container::getContent -- Get item content
  • Config_Container::getItem -- Tries to find specific items
  • Config_Container::getItemIndex -- Return item index in its parent children array
  • Config_Container::getItemPosition -- Return item rank in its parent children array
  • Config_Container::getName -- Get item name
  • Config_Container::getParent -- Return item parent object
  • Config_Container::getType -- Get item type
  • Config_Container::isRoot -- Check for root item
  • Config_Container::removeItem -- Deletes an item from the object
  • Config_Container::searchPath -- Finds a node using XPATH like format
  • Config_Container::setAttributes -- Set item attributes
  • Config_Container::setContent -- Set item content
  • Config_Container::setDirective -- Set child directive content or create new directive
  • Config_Container::setName -- Set item name
  • Config_Container::setType -- Set item type
  • Config_Container::toArray -- Return key/value pair array of container and its children
  • Config_Container::toString -- Return string representation
  • Config_Container::updateAttributes -- Update item attributes
  • Config_Container::writeDatasrc -- Write item to file
Prev | Configuration | Next
Configuration | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What Config can do

Introduction

Config helps you manipulate your configuration whether they are stored in XML files, PHP arrays or other kind of datasources. It supports these features:

  • Parse different configuration formats.

  • Manipulate sections, directives, comments, blanks the way you want.

  • Write them back to a datasource in your preferred format.

The Config object acts as a container for other Config_Container objects. It doesn't do much but makes handling IO operations easier. It contains the root Config_Container object which in turn contains a child Config_Container object. Config_Container objects store references to their parent and have an array of children. This structure makes it easy to access the different containers and their contents.

A Config_Container object can be of different type:

  • Section: a section contains other Config_Container objects.

  • Directive: a directive does not contain any other object but has content and a name. See them as key-value pairs.

  • Comment: just like directives, comments have content but they don't have a name. They are rendered in a special way according to the configuration type you choosed.

  • Blank: they don't have neither content or name but are used to indicate blank lines if your renderer uses them.

When using the Config package, most of the work is done with Config_Container objects.

An example that will create a new Config_Container

<?php
// initialize a Config_Container object

require_once('Config.php');
$conf =& new Config_Container('section', 'conf');
$conf_DB =& $conf->createSection('DB');
$conf_DB->createDirective('type', 'mysql');
$conf_DB->createDirective('host', 'localhost');
$conf_DB->createDirective('user', 'root');
$conf_DB->createDirective('pass', 'root');

// set this container as our root container child in Config

$config = new Config();
$config->setRoot($conf);

// write the container to a php array

$config->writeConfig('/tmp/config_test.php', 'phparray',
                     array('name' => 'test'));

// print the content of our conf section to screen

echo $conf->toString('phparray', array('name' => 'test'));
?>

The above example illustrates how Config and Config_Container can interact. There are other ways. You could have for example first created the Config object and then used $config->getRoot() to add sections and directives to the returned object reference.

Reading configuration from an XML file

<?php
require_once 'Config.php';

$conf = new Config;
$root =& $conf->parseConfig('config.xml', 'XML');

if (PEAR::isError($root)) {
    die('Error while reading configuration: ' . $root->getMessage());
}

$settings = $root->toArray();

printf('User settings: <a href="%s">%s %s</a>',
       $settings['root']['conf']['www'],
       $settings['root']['conf']['firstname'],
       $settings['root']['conf']['lastname']
       );
?>

In this example the XML file config.xml looks like this:

<?xml version="1.0" encoding="UTF-8"?>

<conf>
  <firstname>John</firstname>
  <lastname>Doe</lastname>

  <www>http://example.com/</www>
</conf>

For more information, You can read API doc, sample of package, tests of package, and a great tutorial of DevShed about the Config package.

Prev | Config | Next
Config | PEAR Manual | Editing a configuration


Editing a configuration

Editing a configuration

Editing a configuration – How to manipulate your configuration content

Create configuration content

There are many ways to create content in your Config object. You can simply pass it an array like it is shown in the example below:

Create configuration with array

<?php
// configuration array

$conf = array(
    'DB' => array(
        'type' => 'mysql',
        'host' => 'localhost',
        'user' => 'root',
        'pass' => 'root'
     )
);

// Config object

$config = new Config();
$root =& $config->parseConfig($conf,
                              'phparray',
                              array('name' => 'conf'));
echo $root->toString('phparray', array('name' => 'conf'));
?>

You can also ask Config to look for a file on your filesystem and try to parse it. You would then do it like this. This example assumes you have a valid XML file:

Create configuration with a file

<?php
// Config object

$config = new Config();
$root =& $config->parseConfig('/path/to/file.xml', 'xml');
echo $root->toString('phparray', array('name' => 'conf'));
?>

At the moment, Config can parse XML, PHP arrays, ini files, Apache conf and other generic type of configurations with comments and key-value pairs.

Of course, it is also possible to create the configuration from scratch as shown in the previous section example.

Prev | Config | Next
Introduction | PEAR Manual | Available Containers


Available Containers

Available Containers

Available Containers – Supported formats

Available Containers

Apache

Parses and saves Apache configuration files. No options are provided by this container.

GenericConf

Generic configuration files. The equals, comment start and new line characters in the parser can be customised to match your preferred configuration format.

Available Options
Option Data Type Default value Description
"comment" string "#" The character that signifies the start of a comment.
"equals" string ":" The character that separates keys from values.
"newline" string "\" The character that signifies that a value continues across multiple lines.
IniCommented

Parses standard INI files, maintaining comments within the file. No options are available for this container.

IniFile

Parse standard INI files using PHP's in built parse_ini_file(). Does not read in comments. No options are available for this container.

PHPArray

Parses PHP Array structures. Can read from a PHP Source file or from an in memory array. Due to technical limitations, this container does not parse blank lines or comments when reading from a configuration file, therefore any information contained within PHP comments will be lost.

Available Options
Option | Data Type | Default value | Description
"name" | string | "conf" | The name to use for the root configuration variable, both when parsing and writing PHP source files.
"useAttr" | boolean | TRUE | Controls whether attributes are parsed and saved.

Since config files containing php arrays are just included using the standard php methods, code comments and structure will be lost when saving.

PHPConstants

Parses a set of PHP define() from a PHP source file. Comments are maintained by this container, although blank lines will be lost. There are no options for this container.

XML

Parses a XML file using XML_Parser.

Available Options
Option | Data Type | Default value | Description
"version" | string | "1.0" | The XML version to use.
"encoding" | string | "ISO-8859-1" | The content encoding to use when parsing and storing data.
"name" | string | "conf" | As with PHPArray, this defines the name of the global configuration root.
"indent" string " " The character used for indentation when writing the XML document, if any. By default, two spaces are used.
"linebreak" | string | "\n" | The line-breaking character(s) to use when writing the XML document.
"addDecl" | boolean | TRUE | Controls whether the XML declaration is added to the start of the XML document.
"useAttr" | boolean | TRUE | Controls whether attributes are parsed and saved.
"isFile" | boolean | TRUE | If TRUE, the first argument to parseConfig() will be taken as the file name for the XML file to load. If FALSE, the argument will be taken as the XML data itself and parsed accordingly.
"useCData" | boolean | FALSE | Controls whether data is enclosed in CDATA blocks.
Prev | Config | Next
Editing a configuration | PEAR Manual | Config::Config


Config::Config

Config::Config

Config::Config() – constructor

Synopsis

require_once 'Config.php';

object Config::Config ( ( void )

Description

The Config constructor, it creates a config object.

The next thing you should do is getting the root Config_Container object with getRoot() .

Prev | Config | Next
Available Containers | PEAR Manual | Config::getRoot


Config::getRoot

Config::getRoot

Config::getRoot() – Return root container for config object

Synopsis

require_once 'Config.php';

object &Config::getRoot ( ( void )

Description

This method returns a reference to the root Config_Container object in the Config object. Use the returned Config_Container object reference to manipulate your configuration data.

Return value

object - a reference to config's root container object

Note

This function can not be called statically.

Example

Using getRoot()

<?php
$config = new Config();
$root =& $config->getRoot();
?>
Prev | Config | Next
Config::Config | PEAR Manual | Config::isConfigTypeRegistered


Config::isConfigTypeRegistered

Config::isConfigTypeRegistered

Config::isConfigTypeRegistered() – Returns TRUE if container is registered

Synopsis

require_once 'Config.php';

bool Config::isConfigTypeRegistered ( string $configType )

Description

This method checks if the required container type exists in $GLOBALS['CONFIG_TYPES'] .

Parameter

string $configType

Type of config (php array, xml, inifile...)

Return value

bool - TRUE if registered, FALSE otherwise.

Note

This function can not be called statically.

Prev | Config | Next
Config::getRoot | PEAR Manual | Config::parseConfig


Config::parseConfig

Config::parseConfig

Config::parseConfig() – Parse datasource contents

Synopsis

require_once 'Config.php';

mixed &Config::parseConfig ( mixed $datasrc , string $configType , array $options = array() )

Description

This method will parse the datasource given and fill the root Config_Container object with other Config_Container objects. It will return a reference to the root Config_Container object or a PEAR_Error if something went wrong.

Parameter

mixed $datasrc

Datasource to parse. For most containers, it is a file path. For the PHP array parser, it can be an array too.

string $configType

Type of configuration to parse

array $options

Options for the parser

Return value

object - a reference to Config_Container object

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
PEAR_ERROR_RETURN | "Configuration type '$configType' is not registered in Config::parseConfig." | The config type must be registered for use by Config. | Use one of the standard config types, or register your custom container using Config::registerConfigType

Other errors may be returned from the parser for the specific container you're using.

Note

This function can not be called statically.

Example

Using parseConfig()

<?php
$config = new Config();
$root =& $config->parseConfig('/path/to/file.php', 'phparray',
                                array('name' => 'conf'));
?>
Prev | Config | Next
Config::isConfigTypeRegistered | PEAR Manual | Config::registerConfigType


Config::registerConfigType

Config::registerConfigType

Config::registerConfigType() – Registers a custom Config container

Synopsis

require_once 'Config.php';

bool Config::registerConfigType ( string $configType , array $configInfo = false )

Description

This method registers a new container type with the Config class.

Parameter

string $configType

The name of the configuration type.

array $configInfo

An array defining the file containing the container's class definition and the class name. The format for this array is as follows:

<?php
$configInfo = array('path/to/Name.php',             // The path to the source file for the class.
                    'Config_Container_Class_Name'   // The name of the container class.
                   );
?>

If omitted, the default values are:

<?php
$configInfo = array("Config/Container/$configType.php",
                    "Config_Container_$configType"
                   );
?>

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Prev | Config | Next
Config::parseConfig | PEAR Manual | Config::setRoot


Config::setRoot

Config::setRoot

Config::setRoot() – Set content of root Config_container object

Synopsis

require_once 'Config.php';

mixed Config::setRoot ( object &$rootContainer )

Description

This method will replace the current child of the root Config_Container object by the given object.

Parameter

object $rootContainer

Container to be used as the first child of root

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Example

Using setRoot()

<?php
$container =& new Config_Container('section', 'conf');

$config = new Config();
$root =& $config->setRoot($container);
?>
Prev | Config | Next
Config::registerConfigType | PEAR Manual | Config::writeConfig


Config::writeConfig

Config::writeConfig

Config::writeConfig() – Write container content to datasource

Synopsis

require_once 'Config.php';

mixed Config::writeConfig ( mixed $datasrc = null , string $configType = null , array $options = array() )

Description

This method will call the root Config_Container::writeDatasrc() method which in turn will try to write the Config contents to the datasource.

Parameter

mixed $datasrc

Datasource to write to

string $configType

Type of configuration for writer

array $options

Options for writer

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

This example shows how to convert a configuration from a php file which contains a php array to an xml file.

Using writeConfig()

<?php
$config = new Config();
$config->parseConfig(
                       '/path/to/file.php',
               'phparray',
                       array('name' => 'conf')
            );
$config->writeConfig(  '/path/to/file.xml',
                       'xml',
                       array('name' => 'conf')
            );
?>
Prev | Config | Next
Config::setRoot | PEAR Manual | Config_Container::Config_Container


Config_Container::Config_Container

Config_Container::Config_Container

Config_Container::Config_Container() – Constructor

Synopsis

require_once 'Config/Container.php';

&Config_Container::Config_Container ( string $type = '' , string $name = '' , string $content = '' , mixed $attributes = null )

Description

Creates a new Config_Container and returns it by reference.

Parameter

string $type

Type of container object, should be something among 'section' , 'comment' , 'directive' , 'blank' .

string $name

Name of container object. The name is required for sections and directives, not for blanks or comments.

string $content

Content of container object. The content is used in directives and comments.

array $attributes

Array of attributes for container object. Optionally, you can add attributes to your container. These can be used by the chosen parser.

Return value

object - A reference to the created object.

Note

This function can not be called statically.

Prev | Config | Next
Config::writeConfig | PEAR Manual | Config_Container::addItem


Config_Container::addItem

Config_Container::addItem

Config_Container::addItem() – Add item to this item.

Synopsis

require_once 'Config/Container.php';

object Config_Container::addItem ( object &$item , string $where = 'bottom' , object $target = null )

Description

This method will add a Config_Container child to the current container children. Thus, addItem() can only be called one a section type container. If a position is specified, the object will be added at this position. If 'before' or 'after' are specified as position, a target object is required. The object will then be added before or after the target object position in the current container.

Parameter

object &$item

a container object

string $where

choose a position 'bottom' , 'top' , 'after' , 'before'

object $target

needed if you choose 'before' or 'after' in $where . $target must be one of this container's children. ZendEngine2 will accept references with default. It will then be possible to have &$target instead.

Return value

object - A reference to the added object

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

Adding an item using addItem()

<?php
$section =& new Config_Container('section', 'conf');
$directive =& new Config_Container('directive', 'user', 'mansion');
$section->addItem($directive);
?>

Adding an item using addItem() and a position relative to another item

<?php
$section =& new Config_Container('section', 'conf');
$directive =& new Config_Container('directive', 'user', 'mansion');
$section->addItem($directive);

$comment =& new Config_Container('comment', null, 'Here goes my name');
$section->addItem($comment, 'before', $directive);
?>
Prev | Config | Next
Config_Container::Config_Container | PEAR Manual | Config_Container::countChildren


Config_Container::countChildren

Config_Container::countChildren

Config_Container::countChildren() – Count children of container

Synopsis

require_once 'Config/Container.php';

int Config_Container::countChildren ( string $type = null , string $name = null )

Description

This method will return the number of children this container has. If either $name or $type , it will affine its search just to return the number of children corresponding to these parameters.

Parameter

string $type

Type of children to count.

string $name

Name of children to count.

Return value

int - number of children found

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::addItem | PEAR Manual | Config_Container::createBlank


Config_Container::createBlank

Config_Container::createBlank

Config_Container::createBlank() – Add blank line to item

Synopsis

require_once 'Config/Container.php';

objectConfig_Container::createBlank ( mixed $where = 'bottom' , mixed $target = null )

Description

The current item must be a section. This is a helper method that calls createItem()

Parameter

string $where

Where to create the new item ('top' , 'bottom' , 'before' , 'after' )

object $target

Required only if 'before' or 'after' is used for $where

Return value

object - reference to new item

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

Create a new directive using createBlank()

<?php
$section =& new Config_Container('section', 'conf');
$directive =& $section->createDirective('user', 'mansion');
$section->createBlank('before', $directive);
?>
Prev | Config | Next
Config_Container::countChildren | PEAR Manual | Config_Container::createComment


Config_Container::createComment

Config_Container::createComment

Config_Container::createComment() – Add comment to item

Synopsis

require_once 'Config/Container.php';

objectConfig_Container::createComment ( string $content = '' , string $where = 'bottom' , object $target = null )

Description

The current item must be a section. This is a helper method that calls createItem()

Parameter

string $content

Comment content

string $where

Where to create the new item ('top' , 'bottom' , 'before' , 'after' )

object $target

Required only if 'before' or 'after' is used for $where

Return value

object - reference to new item

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

Create a new directive using createComment()

<?php
$section =& new Config_Container('section', 'conf');
$section->createComment('Database Configuration');
?>
Prev | Config | Next
Config_Container::createBlank | PEAR Manual | Config_Container::createDirective


Config_Container::createDirective

Config_Container::createDirective

Config_Container::createDirective() – Add directive to item

Synopsis

require_once 'Config/Container.php';

object Config_Container::createDirective ( string $name , string $content , mixed $attributes = null , string $where = 'bottom' , mixed $target = null )

Description

The current item must be a section. This is a helper method that calls createItem()

Parameter

string $name

Name of new directive

string $content

Content of new directive

mixed $attributes

Directive attributes

string $where

Where to create the new item ('top' , 'bottom' , 'before' , 'after' )

object $target

Required only if 'before' or 'after' is used for $where

Return value

object - reference to new item

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

Create a new directive using createDirective()

<?php
$section =& new Config_Container('section', 'conf');
$section->createDirective('user', 'mansion');
?>
Prev | Config | Next
Config_Container::createComment | PEAR Manual | Config_Container::createItem


Config_Container::createItem

Config_Container::createItem

Config_Container::createItem() – Create new child for section item

Synopsis

require_once 'Config/Container.php';

object &Config_Container::createItem ( string $type , mixed $item , string $content , array $attributes = null , string $where = 'bottom' , object $target = null )

Description

This method must be called on a section, the created item can be anything. It adds a new child to the current item. If a position is specified, the child will be created at there. It is recommended to use the helper methods instead of calling this method directly.

Parameter

string $type

type of item: directive , section , comment , blank ...

mixed $item

item name

string $content

item content

array $attributes

item attributes

string $where

choose a position 'bottom' , 'top' , 'after' , 'before'

object $target

needed if you choose 'before' or 'after' for $where

Return value

object - reference to new item

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

Create some new items using createItem()

<?php
$section =& new Config_Container('section', 'conf');
$section->createItem('directive', 'user', 'root');
$section->createItem('directive', 'pass', 'root');
$header =& $section->createItem('comment', null, 'Database Configuration', 'top');
$section->createItem('blank', null, null, 'after', $header);
?>
Prev | Config | Next
Config_Container::createDirective | PEAR Manual | Config_Container::createSection


Config_Container::createSection

Config_Container::createSection

Config_Container::createSection() – Add section to item

Synopsis

require_once 'Config/Container.php';

objectConfig_Container::createSection ( string $name , array $attributes = null , string $where = 'bottom' , object $target = null )

Description

Must be called on a section. This is a helper method that calls createItem()

Parameter

string $name

Name of new section

array array $attributes

Section attributes

string $where

Where to create the new item ('top' , 'bottom' , 'before' , 'after' )

object $target

Required only if 'before' or 'after' is used for $where

Return value

object - reference to new item

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Example

Create a new section using createSection()

<?php
$conf =& new Config_Container('section', 'MAIN');
$dbConf =& $conf->createSection('DB');
$dbConf->createDirective('user', 'mansion');
?>
Prev | Config | Next
Config_Container::createItem | PEAR Manual | Config_Container::getAttribute


Config_Container::getAttribute

Config_Container::getAttribute

Config_Container::getAttribute() – Get attribute value of item

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::getAttribute ( string $attribute )

Description

This method returns the value associated with the key attribute. To get all attributes, see method getAttributes().

Parameter

string $attribute

Attribute key

Return value

mixed - item's attribute value

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::createSection | PEAR Manual | Config_Container::getAttributes


Config_Container::getAttributes

Config_Container::getAttributes

Config_Container::getAttributes() – Get item attributes

Synopsis

require_once 'Config/Container.php';

array Config_Container::getAttributes ( ( void )

Description

This method returns an array containing the attributes of this container.

Return value

array - item's attributes

Note

This function can not be called statically.

Example

Using attribute

<?php
$attributes = array('id' => 'db', 'language' => 'en');
     $section =& new Config_Container('section', 'main', null, $attributes);
     $section->createDirective('authentication', 'test', array('type' => 'mysql',
     'host' => 'localhost'));

     echo $section->toString('phparray');
     echo $section->toString('xml');
?>

Attributes are set for '@' key with php array type

<?php
$main['@']['id'] = 'db';
$main['@']['language'] = 'en';
$main['authentication']['#'] = 'test';
$main['authentication']['@']['type'] = 'mysql';
$main['authentication']['@']['host'] = 'localhost';
?>

Attributes are set the usual way with xml type

<?xml version="1.0" encoding="ISO-8859-1"?>
<main id="db" language="en">
<authentication type="mysql" host="localhost">
test
</authentication>;
</main>
Prev | Config | Next
Config_Container::getAttribute | PEAR Manual | Config_Container::getChild


Config_Container::getChild

Config_Container::getChild

Config_Container::getChild() – Return child object at specified index.

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::getChild ( int $index )

Description

Children are stored in an array. This method returns the Config_Container object at the specified index.

Parameter

integer $index

Child index

Return value

mixed - returns reference to child object or FALSE if child does not exist

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getAttributes | PEAR Manual | Config_Container::getContent


Config_Container::getContent

Config_Container::getContent

Config_Container::getContent() – Get item content

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::getContent ( ( void )

Description

Accessor method. Returns the item content.

Return value

mixed - item's content

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getChild | PEAR Manual | Config_Container::getItem


Config_Container::getItem

Config_Container::getItem

Config_Container::getItem() – Tries to find specific items

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::getItem ( string $type = null , string $name = null , mixed $content = null , array $attributes = null , int $index = -1 )

Description

This method tries to find the items that respond to the specified parameters.

This method can only be called on an object of type 'section' . Note that root is a section. This method is not recursive and tries to keep the current structure.

Parameter

string $type

type of item: directive , section , comment , blank ...

string $name

item name

mixed $content

find item with this content

array $attributes

find item with attribute set to the given value

integer $index

index of the item in the returned object list. If it is not set, will try to return the last item with this name.

Return value

mixed - reference to item found or FALSE when not found

Note

This function can not be called statically.

Example

A few examples on how to find items using getItem()

<?php
// will return the last directive found

$directives =& $obj->getItem('directive');

// will return the last directive found with content 'root'

$directives =& $obj->getItem('directive', null, 'root');

// will return the fourth directive with name 'bar'

$directive_bar_4 =& $obj->getItem('directive', 'bar', null, null, 4);

// will return the last section named 'foo'

$section_foo =& $obj->getItem('section', 'foo');

// will return the last section with attribute 'id' set to 'db'

$section_foo =& $obj->getItem('section', 'foo', null, array('id' => 'db'));
?>
Prev | Config | Next
Config_Container::getContent | PEAR Manual | Config_Container::getItemIndex


Config_Container::getItemIndex

Config_Container::getItemIndex

Config_Container::getItemIndex() – Return item index in its parent children array

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::getItemIndex ( ( void )

Description

Children Config_Container objects are stored in an array. This method will return the index of this item in its parent array.

Return value

mixed - returns int or NULL if root object

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getItem | PEAR Manual | Config_Container::getItemPosition


Config_Container::getItemPosition

Config_Container::getItemPosition

Config_Container::getItemPosition() – Return item rank in its parent children array

Synopsis

require_once 'Config/Container.php';

int Config_Container::getItemPosition ( ( void )

Description

Returns the item rank in its parent children array according to other items with same type and name.

Return value

mixed - returns int or NULL if root object

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getItemIndex | PEAR Manual | Config_Container::getName


Config_Container::getName

Config_Container::getName

Config_Container::getName() – Get item name

Synopsis

require_once 'Config/Container.php';

string Config_Container::getName ( ( void )

Description

Return the name of this item.

Return value

string - item's name

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getItemPosition | PEAR Manual | Config_Container::getParent


Config_Container::getParent

Config_Container::getParent

Config_Container::getParent() – Return item parent object

Synopsis

require_once 'Config/Container.php';

object Config_Container::getParent ( ( void )

Description

Returns the item parent object.

Return value

object - reference to parent object or NULL if root object

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getName | PEAR Manual | Config_Container::getType


Config_Container::getType

Config_Container::getType

Config_Container::getType() – Get item type

Synopsis

require_once 'Config/Container.php';

string Config_Container::getType ( ( void )

Description

Gets this item's type.

Return value

string - item type

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getParent | PEAR Manual | Config_Container::isRoot


Config_Container::isRoot

Config_Container::isRoot

Config_Container::isRoot() – Check for root item

Synopsis

require_once 'Config/Container.php';

bool Config_Container::isRoot ( ( void )

Description

There is only one root item. It has no parent, no name, no content and is of type 'section'. The root item is not used in the parsers, only its children.

Return value

bool - TRUE if item is the root item

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::getType | PEAR Manual | Config_Container::removeItem


Config_Container::removeItem

Config_Container::removeItem

Config_Container::removeItem() – Deletes an item from the object

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::removeItem ( ( void )

Description

This method removes the current item. References to its children are removed as well. This method does not accept parameters yet.

Return value

boolean - TRUE if object was removed, FALSE if not, or PEAR_Error if root

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::isRoot | PEAR Manual | Config_Container::searchPath


Config_Container::searchPath

Config_Container::searchPath

Config_Container::searchPath() – Finds a node using XPATH like format

Synopsis

require_once 'Config/Container.php';

mixed Config_Container::searchPath ( mixed $args )

Description

This method tries to find an item by following a given path from the current container.

This method can only be called on an object of type 'section' . Note that root is a section. This method is recursive.

This method takes as many parameters as is needed to define your path to the requested item. The format is array (item1, item2, ..., itemN). Items can be strings or arrays. Strings will match the item name , while arrays will match 'name' and/or 'attributes' properties of the requested item.

Parameter

mixed $args

Strings or arrays of item to match in the order they will be matched, separated by commas

Return value

mixed - reference to item found or FALSE when not found

Note

This function can not be called statically.

Example

Example for searchPath() usage

<?php
// Let's say our XML configuration looks like this:

// <config>
//   <db>
//     <user>root</user>
//     <password>pass</user>
//     <host>localhost</host>
//   </db>
// </config>

$config = new Config();
$root =& $menuObj->parseConfig('db.xml', 'xml');

// Will return the password directive in db
$passObj =& $root->searchPath(array('config', 'db', 'password'));
?>

More complex example with attributes for searchPath()

<?php
// Let's say our XML configuration looks like this:

// <menu>
//   <group id="company">
//     <page id="news"/>
//     <page id="jobs"/>
//   </group>
//   <group id="projects">
//     <page id="project1"/>
//     <page id="project2"/>
//   </group>
// </menu>

$menuObj = new Config();
$root =& $menuObj->parseConfig('menu.xml', 'xml');

// Will return the container in menu which 'id' is set to 'projects'
$section =& $root->searchPath(array('menu', array('group', array('id' => 'projects'))));

// To get a page we could also use
$page =& $root->searchPath(array('menu',
                                  array('group', array('id' => 'projects')),
                                  array('page',  array('id' => 'project2'))));
?>
Prev | Config | Next
Config_Container::removeItem | PEAR Manual | Config_Container::setAttributes


Config_Container::setAttributes

Config_Container::setAttributes

Config_Container::setAttributes() – Set item attributes

Synopsis

require_once 'Config/Container.php';

void Config_Container::setAttributes ( array $attributes )

Description

Attributes are stored in an array. They are used in some containers like PHP Array, XML, Apache. In IniFile or IniCommented containers, attributes are not used. See examples in getAttributes() method to have an idea of the attributes output. This method will replace existing attributes. Use updateAttributes() if you just want to change some of them.

Parameter

array $attributes

Array of attributes

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::searchPath | PEAR Manual | Config_Container::setContent


Config_Container::setContent

Config_Container::setContent

Config_Container::setContent() – Set item content

Synopsis

require_once 'Config/Container.php';

void Config_Container::setContent ( mixed $content )

Description

Set this item's content.

Parameter

mixed mixed $content

Item's content

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::setAttributes | PEAR Manual | Config_Container::setDirective


Config_Container::setDirective

Config_Container::setDirective

Config_Container::setDirective() – Set child directive content or create new directive

Synopsis

require_once 'Config/Container.php';

void Config_Container::setDirective ( string $name , mixed $content , int $index = -1 )

Description

This is an helper method that will first try to find the item with the desired name using getItem(). If the item is found, it will call its setContent() method. If not, it will just create a new directive at the bottom with the given name and content.

Parameter

string $name

Name of the directive to look for

mixed $content

New content, usually a string

integer $index

Index of the directive to set, in case there are more than one directive with the same name

Return value

object - Newly set directive

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::setContent | PEAR Manual | Config_Container::setName


Config_Container::setName

Config_Container::setName

Config_Container::setName() – Set item name

Synopsis

require_once 'Config/Container.php';

void Config_Container::setName ( string $name )

Description

Set this item's name.

Parameter

string $name

Item name

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::setDirective | PEAR Manual | Config_Container::setType


Config_Container::setType

Config_Container::setType

Config_Container::setType() – Set item type

Synopsis

require_once 'Config/Container.php';

void Config_Container::setType ( string $type )

Description

Set this item's type.

Parameter

string $type

item type

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::setName | PEAR Manual | Config_Container::toArray


Config_Container::toArray

Config_Container::toArray

Config_Container::toArray() – Return key/value pair array of container and its children

Synopsis

require_once 'Config/Container.php';

array Config_Container::toArray ( ( void )

Description

This method returns an array representation of the Config tree. The format is

<?php
$section[directive][index] = value
?>

If the container has attributes, it will use '@' as key for attributes and '#' for values. index is here because multiple directives and sections can have the same name, the toArray() method takes care of that.

Return value

array - an array representation of the Config_Container tree

Note

This function can not be called statically.

Example

Using toArray()()

<?php
$attributes = array('id' => 'db', 'language' => 'en');
     $section =& new Config_Container('section', 'main', null, $attributes);
     $section->createDirective('authentication', 'one', array('type' => 'mysql'));
     $section->createDirective('authentication', 'two', array('type' => 'oracle'));
     $section->createDirective('permission', 'group');
     var_dump($section->toArray());
?>

Resulting array with attributes and directives with same name or not

array(1) {
["main"]=>
array(3) {
["@"]=>
array(2) {
["id"]=>
string(2) "db"
["language"]=>
string(2) "en"
}
["authentication"]=>
array(2) {
[0]=>
array(2) {
["#"]=>
string(3) "one"
["@"]=>
array(1) {
["type"]=>
string(5) "mysql"
}
}
[1]=>
array(2) {
["#"]=>
string(3) "two"
["@"]=>
array(1) {
["type"]=>
string(6) "oracle"
}
}
}
["permission"]=>
string(5) "group"
}
}
Prev | Config | Next
Config_Container::setType | PEAR Manual | Config_Container::toString


Config_Container::toString

Config_Container::toString

Config_Container::toString() – Return string representation

Synopsis

require_once 'Config/Container.php';

string Config_Container::toString ( string $configType , array $options = array() )

Description

This method will call the toString() method in the choosen config type. It will return a string representation of the Config_Container and its children.

Parameter

string $configType

Type of configuration used to generate the string

array $options

Specify special options used by the parser

Return value

string - the generated string

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::toArray | PEAR Manual | Config_Container::updateAttributes


Config_Container::updateAttributes

Config_Container::updateAttributes

Config_Container::updateAttributes() – Update item attributes

Synopsis

require_once 'Config/Container.php';

void Config_Container::updateAttributes ( array $attributes )

Description

If the specified attributes are already set, they are overwritten. New attributes are set. The ones that are not set in the given parameter array are left untouched.

Parameter

array $attributes

Array of attributes

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::toString | PEAR Manual | Config_Container::writeDatasrc


Config_Container::writeDatasrc

Config_Container::writeDatasrc

Config_Container::writeDatasrc() – Write item to file

Synopsis

require_once 'Config/Container.php';

boolean Config_Container::writeDatasrc ( mixed $datasrc , string $configType , array $options = array() )

Description

By default, this method will write a new string generated with the toString() method to a file. If a writeDatasrc() method exists in the chosen config type, this method will be called instead. This allows for more flexibility and makes it possible to add your own save handlers.

Parameter

mixed $datasrc

Info on datasource such as path to the configuraton file or dsn...

string $configType

Type of configuration

array $options

Options for writer

Return value

boolean - TRUE on success

Throws

Possible PEAR_Error values
Error code | Error value | Meaning | Solution
 | " |  |

Note

This function can not be called statically.

Prev | Config | Next
Config_Container::updateAttributes | PEAR Manual | Console


Console

Console

Provides Packages for PHP-based command-line applications like the pear installer.

Table of Contents
  • Comparison of option parsers
  • Console_Color
  • Console_CommandLine
  • Console_Getopt
  • Console_ProgressBar
  • Console_Table
Prev | PEAR Packages | Next
Config_Container::writeDatasrc | PEAR Manual | Comparison of option parsers


Comparison of option parsers

Comparison of option parsers

This section gives an overview about the different command line option parser packages in PEAR.

  • Console_GetOpt: standard getopt implementation

  • Console_GetOptPlus: php5 rewrite of getopt with added features

  • Console_GetArgs: object oriented full featured parser

  • Console_CommandLine: similar to GetArgs with php5 and added features

Comparison of command line parsers in PEAR
Feature | Console_GetOpt | Console_GetOptPlus | Console_GetArgs | Console_CommandLine
PHP4 | yes |  | yes |
PHP5 |  | yes | yes | yes
PHP5 with E_STRICT |  | yes |  | yes
Has end user doc | yes |  |  | yes
Stability | stable | beta | stable | stable
POSIX/GNU compliance | yes | yes |  | yes
Generate help |  | yes | yes | yes
Generate version |  |  |  | yes
Argument validation |  |  | yes | yes
Handle password options |  |  |  | yes
Option validation |  |  |  | yes
Subcommands |  |  |  | yes
Optional callback actions |  |  |  | yes
L10n/I18n |  |  |  | yes
Package homepage | Link | Link | Link | Link
Prev | Console | Next
Console | PEAR Manual | Console_Color


Console_Color

Console_Color

Console_Color allows you to easily use ANSI console colors in your application to colorize the output.

Table of Contents
  • Introduction -- How to use Console_Color
  • Color codes -- Tabular reference
Prev | Console | Next
Comparison of option parsers | PEAR Manual | Introduction


Introduction

Introduction

Introduction – How to use Console_Color

Basics

Console_Color provides methods to convert complete strings tagged with special markers into ANSI-compatible color code representations, and methods that directly return those codes for certain colors.

The method used most often is convert(). It takes a string, e.g.

%bHello World!%n\n

or

3 out of 4 people make up about %r75%% %n

and returns the ANSI representation. The characters following a percentage sign (%) do have special meanings. See color codes to get an overview.

To reset the colors to normal, use %n.

Further, there is an escape() method that prevents special chars from being treated as markers.

Methods bgcolor(), color(), fgcolor() and style() directly return ANSI control codes for the given color or style value.

Using strip(), you can remove color and style codes from a string.

Example

<?php
require 'Console/Color.php';
//make it blue
print Console_Color::convert("%bHello World!%n\n");
//more colors
print Console_Color::convert("%rred%n, %ggreen%n, %yyellow%n\n");
?>
Prev | Console_Color | Next
Console_Color | PEAR Manual | Color codes


Color codes

Color codes

Color codes – Tabular reference

Description

Color codes
Color | Text normal | Text bold | Background
Black | %k | %K | %0
Red | %r | %R | %1
Green | %g | %G | %2
Yellow | %y | %Y | %3
Blue | %b | %B | %4
Magenta | %m | %M | %5
Purple | %p | %P |
Cyan | %c | %C | %6
White | %w | %W | %7
Style codes
Style | Code
Blinking, flashing | %F
Underline | %U
Invert, reverse | %8
Bold | %_, %9
Reset color | %n
Single % | %%
Prev | Console_Color | Next
Introduction | PEAR Manual | Console_CommandLine


Console_CommandLine

Console_CommandLine

Console_CommandLine is a full featured package for managing command line options and arguments highly inspired from the python optparse module, it allows the developer to easily build complex command line interfaces.

Table of Contents
  • Introduction -- introduction to the Console_CommandLine package
  • Creating the parser -- how to create a parser using PHP code or an XML definition file
  • Managing command line options -- how to add options to the parser and use them.
  • Managing command line arguments -- how to add arguments to the parser and use them
  • Managing command line sub-commands -- how to add sub-commands to the parser and use them
  • Extending Console_CommandLine -- how to customize this package to achieve specific tasks
  • Using Console_CommandLine in web environments -- How to use the same script from your browser
  • Examples -- various code examples
Prev | Console | Next
Color codes | PEAR Manual | Introduction


Introduction

Introduction

Introduction – introduction to the Console_CommandLine package

Introduction

Console_CommandLine is a convenient, flexible, and powerful library for parsing command-line options and arguments.

It uses adeclarative style of command-line parsing: you create an instance of Console_CommandLine, populate it with options, arguments and even sub-commands and parse the command line. Console_CommandLine allows users to specify options in the conventional GNU/POSIX syntax, and additionally generates usage and help messages for you.

DISCLAIMER: since Console_CommandLine was highly inspired from the python optparse module and thus is very similar to it, some parts of this document were shamelessly copied from optparse manual.

A simple example:

<?php
require_once 'Console/CommandLine.php';

$parser = new Console_CommandLine();
$parser->description = 'A fantastic command line program that does nothing.';
$parser->version = '1.5.0';
$parser->addOption('filename', array(
    'short_name'  => '-f',
    'long_name'   => '--file',
    'description' => 'write report to FILE',
    'help_name'   => 'FILE',
    'action'      => 'StoreString'
));
$parser->addOption('quiet', array(
    'short_name'  => '-q',
    'long_name'   => '--quiet',
    'description' => "don't print status messages to stdout",
    'action'      => 'StoreTrue'
));
try {
    $result = $parser->parse();
    // do something with the result object
    print_r($result->options);
    print_r($result->args);
} catch (Exception $exc) {
    $parser->displayError($exc->getMessage());
}
?>

With the above lines of code, users of the script can now use the program like this:

$ <yourscript> --file=outfile -q

As it parses the command line, Console_CommandLine sets attributes of the result object returned by Console_CommandLine::parse() method based on user-supplied command-line values. When Console_CommandLine::parse() returns from parsing this command line, $result->options['filename'] will be "outfile" and $result->options['quiet'] will be TRUE.

Console_CommandLine supports both long and short options, allows short options to be merged together, and allows options to be associated with their arguments in a variety of ways.

The following lines are all equivalent for the above example:

$ <yourscript> -f outfile --quiet
$ <yourscript> --quiet --file outfile
$ <yourscript> -q -foutfile
$ <yourscript> -qfoutfile

Additionally, to get help, users can do this:

$ <yourscript> -h
$ <yourscript> --help

These commands will print:

A fantastic command line program that does nothing.

Usage:
  tmp.php [options]

Options:
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout
  -h, --help            show this help message and exit
  --version             show the program version and exit

Console_CommandLine also manage the program version automatically:

$ <yourscript> --version

The above command will print:

$ <yourscript> version 1.5.0.

where the value of yourscript is determined at runtime (normally from $argv[0], except if you specified explicitely a name for your parser).

Prev | Console_CommandLine | Next
Console_CommandLine | PEAR Manual | Creating the parser


Creating the parser

Creating the parser

Creating the parser – how to create a parser using PHP code or an XML definition file

Console_CommandLine constructor

Console_CommandLine::__construct() takes an optional array of parameters explained in the table below. Note that if you are using an XML definition file, you can pass these parameters in it (see XML example for details).

Available parameters
name | type | required | description
name | string | no, default to $argv[0] if not given | the name of your program
description | string | no, but recommended for the help message | the description of your program: this should explain what your program is supposed to do
version | mixed (string or numeric) | no, note that if not given, the --version option will not be available | the program version number
add_help_option | boolean | no, default to TRUE | if set to FALSE the parser will not generate automatically the "help" option
add_version_option | boolean | no, default to TRUE | if set to FALSE the parser will not generate automatically the "version" option
force_posix | boolean | no, default to FALSE | if set to TRUE, the parser will force POSIX compliance (please see the gettext manual for more information)

Using PHP code

The examples below demonstrate how to instanciate Console_CommandLine and build a parser using PHP code.

The simplest way

<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine(array(
    'description' => 'A useful description for your program.',
    'version'     => '0.0.1', // the version of your program
));
?>

Alternative method

<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();
$parser->description = 'A useful description for your program.';
$parser->version = '0.0.1'; // the version of your program
?>

Using an XML definition file

The examples below demonstrate how to instanciate Console_CommandLine and build a parser using an XML definition file, this can be very useful if you have a big program or if you need to reuse your user interface settings for a web frontend for example.

The XML file

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<command>
    <description>A useful description for your program.</description>
    <version>0.0.1</version>
</command>

The PHP file

<?php
require_once 'Console/CommandLine.php';
$parser = Console_CommandLine::fromXmlFile('example.xml');
?>
Note: Using an XML string you would have called Console_CommandLine::fromXmlString() instead of Console_CommandLine::fromXmlFile() of course.
Prev | Console_CommandLine | Next
Introduction | PEAR Manual | Managing command line options


Managing command line options

Managing command line options

Managing command line options – how to add options to the parser and use them.

Some background

Options are used to provide extra information to tune or customize the execution of a program. In case it wasn't clear, options are usually optional. A program should be able to run just fine with no options whatsoever. Pick a random program from the Unix or GNU toolsets. Can it run without any options at all and still make sense? The main exceptions are find, tar, and dd--all of which are mutant oddballs that have been rightly criticized for their non-standard syntax and confusing interfaces.

Lots of people want their programs to have "required options". Think about it. If it's required, then it's not optional! If there is a piece of information that your program absolutely requires in order to run successfully, that's what arguments are for.

As an example of good command-line interface design, consider the humble cp utility, for copying files. It doesn't make much sense to try to copy files without supplying a destination and at least one source. Hence, cp fails if you run it with no arguments. However, it has a flexible, useful syntax that does not require any options at all:

$ cp SOURCE DEST
$ cp SOURCE ... DEST-DIR

You can get pretty far with just that. Most cp implementations provide a bunch of options to tweak exactly how the files are copied: you can preserve mode and modification time, avoid following symlinks, ask before clobbering existing files, etc. But none of this distracts from the core mission of cp, which is to copy either one file to another, or several files to another directory.

Adding options with Console_CommandLine

To add options to your parser, just create the parser as explained in the previous section and use the Console_CommandLine::addOption() method.

The Console_CommandLine::addOption() method takes two arguments:

  • the option name: a string that will be used to access the option in the result object. For example if you name your option foo, you will access to the result object like this: $result->options['foo'];

  • the options parameters: an array of various informations, as explained below.

Available option parameters
name | type | required | description | example
short_name | string | yes, if no long_name given | the option short name | -o
long_name | string | yes, if no short_name given | the option long name | --orientation
description | string | no, but recommended for the help message | a description for the option | orientation of the page: ltr (default) or rtl
action | string | no, default to "StoreString" | the option action (see next section for details) | StoreString
default | mixed | no | the option default value | ltr
choices | array | no, only relevant for options that expect argument(s) | list of possible values for the option | array('ltr', 'rtl')
list | array | no, only relevant for options that use the "List" action | list of values to display | array('blue', 'green', 'yellow')
add_list_option | boolean | no, default to FALSE | this property is only relevant when the choices property is set, if set to TRUE the parser will generate an additional option to list the choices (eg. --list-foo). | TRUE
help_name | string | no, if not given it will default to the option name | the name to display in the option help line | page_orientation (the help ligne will be: --orientation=page_orientation)

Adding commandline options

<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine(array(
   'description' => 'A useful description for your program.',
   'version'     => '0.0.1', // the version of your program
));

// Adding a simple option that takes no argument and that tell our program to
// turn on verbose output:
$parser->addOption(
   'verbose',
   array(
      'short_name'  => '-v',
      'long_name'   => '--verbose',
      'description' => 'turn on verbose output',
      'action'      => 'StoreTrue'
  )
);

// Adding an option that will store a string
$parser->addOption(
   'orientation',
   array(
       'short_name'  => '-o',
       'long_name'   => '--orientation',
       'description' => 'orientation of the page, "ltr" (default) or "rtl"',
       'action'      => 'StoreString',
       'default'     => 'ltr',
       'help_name'   => 'page_orientation'
  )
);

try {
   $result = $parser->parse();
   print_r($result->options);
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}
?>

Now if the user type:

$ <yourprogram> -vo rtl

or (equivalent):

$ <yourprogram> --verbose --orientation=rtl

The output of the above script will be:

Array
(
   [verbose] => 1
   [orientation] => rtl
   [help] =>
   [version] =>
)

Options actions

Actions tell the parser how to handle option values, among other things they tell the parser if the option expects a value or not and how to store this value in the result object.

StoreTrue

This action tells the parser to store the value true in the result object if the option is present in the command line, for example:

$ <yourprogram> -v

will store TRUE in $result->options['verbose'], assuming the option was defined like this:

<?php
$parser->addOption('verbose', array('short_name'=>'-v', 'action'=>'StoreTrue'));
$result = $parser->parse();
?>

StoreFalse

This action tells the parser to store the value false in the result object if the option is present in the command line, for example:

$ <yourprogram> -q

will store FALSE in $result->options['verbose'], assuming the option was defined like this:

<?php
$parser->addOption('verbose', array('short_name'=>'-q', 'action'=>'StoreFalse'));
$result = $parser->parse();
?>

StoreString

This action tells the parser that the option expects a value and to store this value as an integer in the result object, for example:

$ <yourprogram> -o out.txt

will store the string "out.txt" in $result->options['outfile'], assuming the option was defined like this:

<?php
$parser->addOption('outfile', array('short_name'=>'-o', 'action'=>'StoreString'));
$result = $parser->parse();
?>

StoreInt

This action tells the parser that the option expects a value and to store this value as an integer in the result object, for example:

$ <yourprogram> --width=500

will store the integer 500 in $result->options['width'], assuming the option was defined like this:

<?php
$parser->addOption('width', array('long_name'=>'--width', 'action'=>'StoreInt'));
$result = $parser->parse();
?>

StoreFloat

This action tells the parser that the option expects a value and to store this value as a float in the result object, for example:

$ <yourprogram> -l=0.3

will store the float 0.3 in $result->options['level'], assuming the option was defined like this:

<?php
$parser->addOption('level', array('short_name'=>'-l', 'action'=>'StoreFloat'));
$result = $parser->parse();
?>

Counter

This action tells the parser to increment the value in the result object each time it encounters the option in the command line, for example:

$ <yourprogram> -vvvv

or the equivalent:

$ <yourprogram> -v -v -v --verbose

will store the integer 4 in $result->options['verbose_level'], assuming the option was defined like this:

<?php
$parser->addOption('verbose_level', array(
   'short_name' => '-v',
   'long_name'  => '--verbose',
   'action'     => 'Counter'
));
$result = $parser->parse();
?>

Help

This action tells the parser to display the help message if it encounters the option in the command line, most of the time you won't need this since it is handled by Console_CommandLine internally.

Version

This action tells the parser to display the program version if it encounters the option in the command line, as for Help action, chances are that you won't need this since it is handled by Console_CommandLine internally.

Password

This action allows the user to either type the password on the commandline or to be prompted for it (will not echo on unix systems), some examples:

<?php
$parser->addOption('password', array('short_name'=>'-p', 'action'=>'Password'));
$result = $parser->parse();
?>

$ <yourprogram> -ps3cret

will store the string "s3ecret" in $result->options['password']

whereas:

$ <yourprogram> -p

will "prompt" the user for entering his/her password without echoing it, and will store "s3ecret" in $result->options['password']

Callback

This action allows to specify a PHP callback to handle user input. The callback must be a php callable and must accept five arguments:

  • the value of the option;

  • the Console_CommandLine_Option_Callback instance

  • the Console_CommandLine_Result instance

  • the Console_CommandLine instance (the parser)

  • an array of additional parameters that you specify when building your option.

Your callback function must return the modified (or not modified) value (the first argument).

All these arguments should give you enough flexibility to build complex callback actions.

Here is a simple example:

<?php
/**
* A simple encryption callback.
*
*/
function encryptCallback($value, $option, $result, $parser, $params=array())
{
   if (!isset($params['salt'])) {
       $params['salt'] = '';
   }
   return sha1($params['salt'] . $value);
}

require_once 'Console/CommandLine.php';

$parser = new Console_CommandLine();
$parser->addOption('encrypt', array(
   'short_name'    => '-e',
   'long_name'     => '--encrypt',
   'action'        => 'Callback',
   'description'   => 'encrypt the given value using sha1 + salt',
   'callback'      => 'encryptCallback',
   'action_params' => array('salt' => 'x2897ZHKx7200j1__2')
));

try {
   $result = $parser->parse();
   echo $result->options['encrypt'] . "\n";
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}
?>

Now if the user type:

$ <yourprogram> -e foobar

The output of the above script will be:

7f12da3b1c126d7a47745b09dc0040c92cee1700

List

a special action that simply output an array as a list.

<?php
$parser->addOption('list_colors', array(
   'short_name' => '-l',
   'long_name'  => '--list-colors',
   'action'     => 'List',
   'list'       => array('blue', 'green', 'yellow')
));
$result = $parser->parse();
?>

$ <yourprogram> --list-colors

will display the list of colors separated by commas.

Prev | Console_CommandLine | Next
Creating the parser | PEAR Manual | Managing command line arguments


Managing command line arguments

Managing command line arguments

Managing command line arguments – how to add arguments to the parser and use them

Some background

Arguments are for those pieces of information that your program absolutely, positively requires to run.

A good user interface should have as few absolute requirements as possible. If your program requires 17 distinct pieces of information in order to run successfully, it doesn't much matter how you get that information from the user, most people will give up and walk away before they successfully run the program. This applies whether the user interface is a command-line, a configuration file, or a GUI: if you make that many demands on your users, most of them will simply give up.

In short, try to minimize the amount of information that users are absolutely required to supply and use sensible defaults whenever possible. Of course, you also want to make your programs reasonably flexible. That's what options are for.

Adding arguments with Console_CommandLine

To add arguments to your parser, just create the parser as explained in the previous section and use the Console_CommandLine::addArgument() method.

The Console_CommandLine::addArgument() method takes two arguments:

  • the argument name: a string that will be used to access the argument in the result object. For example if you name your argument foo, you will access to the result object like this: $result->args['foo'];

  • the arguments parameters: an array of various informations as explained below.

Available arguments parameters
name | type | required | description | example
description | string | no, but recommended for the help message | a description for the argument | entry list of input files separated by spaces
multiple | boolean | no, default to FALSE | tells the parser that the argument expects multiples values | TRUE
optional | boolean | no, default to FALSE | tells the parser that the argument is optional | TRUE
help_name | string | no, if not given it will default to the argument name | the name to display in the argument help line | files

Adding commandline arguments

<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();

// add an array argument
$parser->addArgument('input_files', array('multiple'=>true));

// add a simple argument
$parser->addArgument('output_file');

try {
   $result = $parser->parse();
   print_r($result->args);
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}
?>

If the user type:

$ <yourprogram> file1 file2 file3

The output of the above script will be:

Array
(
   [input_files] => Array
       (
           [0] => file1
           [1] => file2
       )

   [output_file] => file3
)
Prev | Console_CommandLine | Next
Managing command line options | PEAR Manual | Managing command line sub-commands


Managing command line sub-commands

Managing command line sub-commands

Managing command line sub-commands – how to add sub-commands to the parser and use them

What are sub-commands ?

Some programs are very complex, you can't do anything about that but you need to provide the best user interface possible in order to have happy users. In some cases, sub-commands can be very useful, take the PEAR installer for example, it is much more clearer to separate the installer functionalities than to mix all functionalities in the same interface, that's why you have an interface like:

$ pear install <options> <pkgname>
$ pear upgrade <options> <pkgname>
and so on...

Adding sub-commands with Console_CommandLine

Adding sub-commands is quite simple, basically you use the Console_CommandLine::addCommand() method that returns a Console_CommandLine_Command instance and then you build your command instance like you would do for the main parser (add options, arguments etc...). One thing to remember is that sub-commands are exactly the same as main parsers: they have the same properties and methods.

Let's take a simple example to demonstrate the use of sub-commands, in the following code we will build a simple command line program that will have two sub-commands: "foo" and "bar":

<?php
// Include the Console_CommandLine package.
require_once 'Console/CommandLine.php';

// create the parser
$parser = new Console_CommandLine(array(
   'description' => 'A great program that can foo and bar !',
   'version'     => '1.0.0'
));

// add a global option to make the program verbose
$parser->addOption('verbose', array(
   'short_name'  => '-v',
   'long_name'   => '--verbose',
   'action'      => 'StoreTrue',
   'description' => 'turn on verbose output'
));

// add the foo subcommand
$foo_cmd = $parser->addCommand('foo', array(
   'description' => 'output the given string with a foo prefix'
));
$foo_cmd->addOption('reverse', array(
   'short_name'  => '-r',
   'long_name'   => '--reverse',
   'action'      => 'StoreTrue',
   'description' => 'reverse the given string before echoing it'
));
$foo_cmd->addArgument('text', array(
   'description' => 'the text to output'
));

// add the bar subcommand
$bar_cmd = $parser->addCommand('bar', array(
   'description' => 'output the given string with a bar prefix'
));
$bar_cmd->addOption('reverse', array(
   'short_name'  => '-r',
   'long_name'   => '--reverse',
   'action'      => 'StoreTrue',
   'description' => 'reverse the given string before echoing it'
));
$bar_cmd->addArgument('text', array(
   'description' => 'the text to output'
));

?>

Of course, we could also build our parser with sub-commands using an xml file, the xml file would be:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<command>
   <description>A great program that can foo and bar !</description>
   <version>1.0.0</version>
   <option name="verbose">
       <short_name>-v</short_name>
       <long_name>--verbose</long_name>
       <description>turn on verbose output</description>
       <action>StoreTrue</action>
   </option>
   <command>
       <name>foo</name>
       <description>output the given string with a foo prefix</description>
       <option name="reverse">
           <short_name>-r</short_name>
           <long_name>--reverse</long_name>
           <description>reverse the string before echoing it</description>
           <action>StoreTrue</action>
       </option>
       <argument name="text">
           <description>the text to output</description>
       </argument>
   </command>
   <command>
       <name>bar</name>
       <description>output the given string with a bar prefix</description>
       <option name="reverse">
           <short_name>-r</short_name>
           <long_name>--reverse</long_name>
           <description>reverse the string before echoing it</description>
           <action>StoreTrue</action>
       </option>
       <argument name="text">
           <description>the text to output</description>
       </argument>
   </command>
</command>

Also note that sub-commands support aliases, for example it is possible to have an "update" command and specify "up" as an alias (shortcut) of the command:

<?php

$parser->addCommand('update', array(
    'description' => 'Update the given package',
    'aliases'     => array('up'), // we can have more than 1 alias
));

?>

So far, so good, now let's see how to use this parser. When a user type a sub-command in the command line, the result object will have two properties set: the Console_CommandLine_Result::$command_name that will contain the name (as a string) of the sub-command typed by the user, and the Console_CommandLine_Result::$command that will contain a Console_CommandLine_Result instance, specific to the provided sub-command. For example with the above parser, we would do:

<?php

try {
   $result = $parser->parse();
   // find which command was entered
   switch ($result->command_name) {
   case 'foo':
       // the user typed the foo command
       // options and arguments for this command are stored in the
       // $result->command instance:
       print_r($result->command);
       exit(0);
   case 'bar':
       // the user typed the bar command
       // options and arguments for this command are stored in the
       // $result->command instance:
       print_r($result->command);
       exit(0);
   default:
       // no command entered
       exit(0);
   }
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}

?>
Prev | Console_CommandLine | Next
Managing command line arguments | PEAR Manual | Extending Console_CommandLine


Extending Console_CommandLine

Extending Console_CommandLine

Extending Console_CommandLine – how to customize this package to achieve specific tasks

Adding custom actions

Console_CommandLine allows you to register custom actions when you need it. Basically, you just create a action class that inherits from Console_CommandLine_Action and you call the Console_CommandLine::registerAction() method to register it.

Let's take a simple example, suppose we want to create a "range" action that would allow the user to type:

$ <yourprogram> -r 1,5

And in our Console_CommandLine_Result instance we would have:

// $result->options['range']: array('min' => 1, 'max' => 5)

Here's how we would do:

<?php

require_once 'Console/CommandLine.php';
require_once 'Console/CommandLine/Action.php';

class ActionRange extends Console_CommandLine_Action
{
    public function execute($value=false, $params=array())
    {
        $range = explode(',', str_replace(' ', '', $value));
        if (count($range) != 2) {
            throw new Exception(sprintf(
                'Option "%s" must be 2 integers separated by a comma',
                $this->option->name
             ));
        }
        $this->setResult(array('min' => $range[0], 'max' => $range[1]));
    }
}

// then we can register our action
Console_CommandLine::registerAction('Range', 'ActionRange');

// and now our action is available !
$parser = new Console_CommandLine();
$parser->addOption('range', array(
    'short_name'  => '-r',
    'long_name'   => '--range',
    'action'      => 'Range', // note our custom action
    'description' => 'A range of two integers separated by a comma'
));
// etc...

?>

Using a custom renderer

TODO: write this section

Prev | Console_CommandLine | Next
Managing command line sub-commands | PEAR Manual | Using Console_CommandLine in web environments


Using Console_CommandLine in web environments

Using Console_CommandLine in web environments

Using Console_CommandLine in web environments – How to use the same script from your browser

Introduction

So there is a nice shell script that does everything it ever should do, and other people - without shell access - have to use it now. Or the script needs to be called regularly from outside the server it is running on. What now?

If your server runs a HTTP server with PHP, the problem is already solved because Console_Commandline supports reading HTTP $_GET and $_POST variables out of the box.

A simple example

The scripts task in this example is to print out the current time. The user may customize the output by specifying the format string.

Between shell and web access is only one difference: On the web, the text shall be printed out in large letters by wrapping it in a h1 tag.

Console_CommandLine by itself cares about reading HTTP GET and POST variables when it is run through PHP's CGI or web server (e.g. Apache with mod_php). Let's try it:

<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();
$parser->description = 'Print out the current time';
$parser->version     = '1.23';
$parser->addOption(
    'format',
    array(
        'short_name'  => '-f',
        'long_name'   => '--format',
        'action'      => 'StoreString',
        'default'     => 'Y-m-d H:i:s',
        'description' => 'date()-compatible format string',
    )
);

$result = $parser->parse();
echo date($result->options['format']) . "\n";
?>

Shell output

$ php web.php
2009-06-13 10:10:15
$ php web.php --help
Print out the current time

Usage:
  web.php [options]

Options:
  -f format, --format=format  date()-compatible format string
  -h, --help                  show this help message and exit
  -v, --version               show the program version and exit

$ php web.php --format=d.m.Y
13.06.2009

Web output without parameters

2009-06-13 10:10:15

Web output for web.php?--help

Print out the current time Usage: --help [options]
Options: -f format, --format=format date()-compatible format string -h,
--help show this help message and exit -v, --version show the program
version and exit

Web output for web.php?format=d.m.Y

13.06.2009

The functionality is there, but it does not look nice.

Note: When using GET and POST parameters, Console_CommandLine accepts three types of parameter names:

  • short_name as configured for the option

  • long_name as configured

  • option name as passed as first parameter to Console_CommandLine::addOption().

So in our example, one can call

  • web.php?-f=d.m.Y

  • web.php?--format=d.m.Y

  • web.php?format=d.m.Y

For arguments, the argument name has to be used as GET or POST key.

A prettier example

Building upon our previous example, we care about pretty output here:

  • Time wrapped in h1 tags.

  • Monospaced help text

  • Monospaced error text

While we did not catch any errors - as there are nearly none to produce in that example - the code contains it now for completeness.

First and foremost, we check if we are in an HTTP environment by checking the SAPI (Server API) name. If we are not in CLI, we echo out <h1> and </h1>.

To get the help text printed with monospaced text, a custom renderer is defined. For the sake of easiness, the default console renderer is extendet since it does nearly everything we need here.

<?php
require_once 'Console/CommandLine.php';
$parser = new Console_CommandLine();
$parser->description = 'Print out the current time';
$parser->version     = '1.23';
$parser->addOption(
    'format',
    array(
        'short_name'  => '-f',
        'long_name'   => '--format',
        'action'      => 'StoreString',
        'default'     => 'Y-m-d H:i:s',
        'description' => 'date()-compatible format string',
    )
);

class HtmlRenderer extends Console_CommandLine_Renderer_Default
{
    public function usage()
    {
        return '<pre>' . parent::usage() . '</pre>';
    }

    public function error($error)
    {
        return '<pre>' . parent::error($error) . '</pre>';
    }
}

$parser->accept(new HtmlRenderer());

$http = (php_sapi_name() != 'cli');
try {
   $result = $parser->parse();
   if ($http) {
       echo '<h1>';
   }
   echo date($result->options['format']) . "\n";
   if ($http) {
       echo '</h1>';
   }
} catch (Exception $exc) {
   $parser->displayError($exc->getMessage());
}
?>
Prev | Console_CommandLine | Next
Extending Console_CommandLine | PEAR Manual | Examples


Examples

Examples

Examples – various code examples

Basic example

Basic example

<?php
// Include the Console_CommandLine package.
require_once 'Console/CommandLine.php';

// create the parser
$parser = new Console_CommandLine(array(
    'description' => 'zip given files using the php zip module.',
    'version'     => '1.0.0'
));

// add an option to make the program verbose
$parser->addOption(
    'verbose',
    array(
        'short_name'  => '-v',
        'long_name'   => '--verbose',
        'action'      => 'StoreTrue',
        'description' => 'turn on verbose output'
    )
);

// add an option to delete original files after zipping
$parser->addOption(
    'delete',
    array(
        'short_name'  => '-d',
        'long_name'   => '--delete',
        'action'      => 'StoreTrue',
        'description' => 'delete original files after zip operation'
    )
);

// add the files argument, the user can specify one or several files
$parser->addArgument(
    'files',
    array(
        'multiple' => true,
        'description' => 'list of files to zip separated by spaces'
    )
);

// add the zip file name argument
$parser->addArgument('zipfile', array('description' => 'zip file name'));

// run the parser
try {
    $result = $parser->parse();
    // write your program here...
    print_r($result->options);
    print_r($result->args);
} catch (Exception $exc) {
    $parser->displayError($exc->getMessage());
}
?>

Basic example using an XML definition file

Basic example (XML file)

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<command>
    <description>zip given files using the php zip module.</description>
    <version>1.0.0</version>
    <option name="verbose">
        <short_name>-v</short_name>
        <long_name>--verbose</long_name>
        <description>turn on verbose output</description>
        <action>StoreTrue</action>
    </option>
    <option name="delete">
        <short_name>-d</short_name>
        <long_name>--delete</long_name>
        <description>delete original files after zip operation</description>
        <action>StoreTrue</action>
    </option>
    <argument name="files">
        <description>a list of files to zip together</description>
        <multiple>true</multiple>
    </argument>
    <argument name="zipfile">
        <description>path to the zip file to generate</description>
    </argument>
</command>

Basic example (PHP file)

<?php
// Include the Console_CommandLine package.
require_once 'Console/CommandLine.php';

// create the parser from xml file
$xmlfile = dirname(__FILE__) . DIRECTORY_SEPARATOR . 'ex2.xml';
$parser = Console_CommandLine::fromXmlFile($xmlfile);

// run the parser
try {
    $result = $parser->parse();
    // todo: your program here ;)
    print_r($result->options);
    print_r($result->args);
} catch (Exception $exc) {
    $parser->displayError($exc->getMessage());
}
?>

Sub-commands example

Sub-commands example

<?php
// Include the Console_CommandLine package.
require_once 'Console/CommandLine.php';

// create the parser
$parser = new Console_CommandLine(array(
    'description' => 'A great program that can foo and bar !',
    'version'     => '1.0.0'
));

// add a global option to make the program verbose
$parser->addOption('verbose', array(
    'short_name'  => '-v',
    'long_name'   => '--verbose',
    'action'      => 'StoreTrue',
    'description' => 'turn on verbose output'
));

// add the foo subcommand
$foo_cmd = $parser->addCommand('foo', array(
    'description' => 'output the given string with a foo prefix'
));
$foo_cmd->addOption('reverse', array(
    'short_name'  => '-r',
    'long_name'   => '--reverse',
    'action'      => 'StoreTrue',
    'description' => 'reverse the given string before echoing it'
));
$foo_cmd->addArgument('text', array(
    'description' => 'the text to output'
));

// add the bar subcommand
$bar_cmd = $parser->addCommand('bar', array(
    'description' => 'output the given string with a bar prefix'
));
$bar_cmd->addOption('reverse', array(
    'short_name'  => '-r',
    'long_name'   => '--reverse',
    'action'      => 'StoreTrue',
    'description' => 'reverse the given string before echoing it'
));
$bar_cmd->addArgument('text', array(
    'description' => 'the text to output'
));

// run the parser
try {
    $result = $parser->parse();
    if ($result->command_name) {
        $st = $result->command->options['reverse']
            ? strrev($result->command->args['text'])
            : $result->command->args['text'];
        if ($result->command_name == 'foo') {
            echo "Foo says: $st\n";
        } else if ($result->command_name == 'bar') {
            echo "Bar says: $st\n";
        }
    }
} catch (Exception $exc) {
    $parser->displayError($exc->getMessage());
}

?>

Sub-commands example using an XML definition file

Sub-commands example (XML file)

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<command>
    <description>A great program that can foo and bar !</description>
    <version>1.0.0</version>
    <option name="verbose">
        <short_name>-v</short_name>
        <long_name>--verbose</long_name>
        <description>turn on verbose output</description>
        <action>StoreTrue</action>
    </option>
    <command>
        <name>foo</name>
        <description>output the given string with a foo prefix</description>
        <option name="reverse">
            <short_name>-r</short_name>
            <long_name>--reverse</long_name>
            <description>reverse the string before echoing it</description>
            <action>StoreTrue</action>
        </option>
        <argument name="text">
            <description>the text to output</description>
        </argument>
    </command>
    <command>
        <name>bar</name>
        <description>output the given string with a bar prefix</description>
        <option name="reverse">
            <short_name>-r</short_name>
            <long_name>--reverse</long_name>
            <description>reverse the string before echoing it</description>
            <action>StoreTrue</action>
        </option>
        <argument name="text">
            <description>the text to output</description>
        </argument>
    </command>
</command>

Sub-commands example (PHP file)

<?php
// Include the Console_CommandLine package.
require_once 'Console/CommandLine.php';

// create the parser
$xmlfile = dirname(__FILE__) . DIRECTORY_SEPARATOR . 'ex4.xml';
$parser  = Console_CommandLine::fromXmlFile($xmlfile);

// run the parser
try {
    $result = $parser->parse();
    if ($result->command_name) {
        $st = $result->command->options['reverse']
            ? strrev($result->command->args['text'])
            : $result->command->args['text'];
        if ($result->command_name == 'foo') {
            echo "Foo says: $st\n";
        } else if ($result->command_name == 'bar') {
            echo "Bar says: $st\n";
        }
    }
} catch (Exception $exc) {
    $parser->displayError($exc->getMessage());
}

?>
Prev | Console_CommandLine | Next
Using Console_CommandLine in web environments | PEAR Manual | Console_Getopt


Console_Getopt

Console_Getopt

Console_Getopt provides functions for easily fetching and processing command-line arguments.

Table of Contents
  • Introduction - Options -- Defining and processing options
  • Console_Getopt::getopt -- fetch the command-line options
  • Console_Getopt::readPHPArgv -- read the predefined $argv array
Prev | Console | Next
Examples | PEAR Manual | Introduction - Options


Introduction - Options

Introduction - Options

Introduction - Options – Defining and processing options

Defining options

Getopt() supports two types of options: short options and long options

Calling a script with short and long options

# Using short options
myphpscript -q -l en -o
# Using long options instead
myphpscript --quite --lang=en --option
# Mixing both
myphpscript -q --lang=en -o

You have to define which options you want to support. The second argument of getopt() requires a string containing all supported chars. For the example above this would be at least:

<?php
$shortoptions = "qlo";
?>

The order of the characters is not important. Often you have to define options with (optional) parameters. To express that a option requires a parameter, you have to add a colon. If the parameter is optional, add a double colon, ie:

<?php
$shortoptions = "ql:o::";
?>

this means the following script calls are permitted, ie.

myphpscript myphpscript -q myphpscript -q -l en myphpscript -o text myphpscript -o

whilst

myphpscript -l

is not permitted. The -l option requires a parameter, if the option is used.

The long options work equally, but they have to be defined in an array:

<?php
$longoptions = array("quite", "lang", "option");
?>

For defining optional parameters, use '=' and '==' like the colon in short options.

<?php
$longoptions = array("quite", "lang=", "option==");
?>

The returned options array

The return value is an array of two elements: the list of parsed options and the list of non-option command-line arguments. Each entry in the list of parsed options is a pair of elements - the first one specifies the option, and the second one specifies the option argument, if there was one, else the value is NULL.

Prev | Console_Getopt | Next
Console_Getopt | PEAR Manual | Console_Getopt::getopt


Console_Getopt::getopt

Console_Getopt::getopt

Console_Getopt::getopt – fetch the command-line options

Synopsis

require_once 'Console/Getopt.php';

array getopt ( array $args , string $shortoptions , array $longoptions = null )

Description

Parses the command-line options and returns them.

Parameter

  • array $args - an array of command-line arguments

  • string $shortoptions - specifies the list of allowed short options. See the "Options" section for more information.

  • array $longoptions - specifies the list of allowed long options. Default is NULL . See the "Options" section for more information.

Return value

array - two-element array containing the list of parsed options and the non-option arguments or a PEAR_Error.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Console_Getopt: option --$opt is ambiguous" | Two or more long options starts with the same character. | Change the naming of the options. It is also possible that the error is caused by a typing mistake.
NULL | "Console_Getopt: option --$opt requires an argument" | No parameter for a option was given. | Normally this is a user mistake. If the parameter is optional, you have to markup the parameter as optional in the option definitions.
NULL | "Console_Getopt: option --$opt doesn't allow an argument" | A parameter for a option was given. | Normally this is a user mistake. If the option requires a (optional) parameter, you have to markup it in the options definition.
NULL | "Console_Getopt: unrecognized option --$opt " | Unknown option. | Normally this is a user mistake. If the option exists, you have to define them in the options definition.

Note

This function can not be called statically.

Prev | Console_Getopt | Next
Introduction - Options | PEAR Manual | Console_Getopt::readPHPArgv


Console_Getopt::readPHPArgv

Console_Getopt::readPHPArgv

Console_Getopt::readPHPArgv – read the predefined $argv array

Synopsis

require_once 'Console/Getopt.php';

array readPHPArgv ( )

Description

Reads the $argv PHP array across different PHP configurations. Will take care of the register_globals and register_argc_argv ini directives.

Return value

array - array containing the options and parameters or PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Console_Getopt: Could not read cmd args (register_argc_argv=Off?)" | PHP does not provide the command-line arguments for the script. | Check "register_argc_argv" in your php.ini

Note

This function can not be called statically.

Example

Using readPHPArgv()

<?php
$con  = new Console_Getopt;
$args = $con->readPHPArgv();
array_shift($args);
$options = $con->getopt2($args, $shortopt);
?>
Prev | Console_Getopt | Next
Console_Getopt::getopt | PEAR Manual | Console_ProgressBar


Console_ProgressBar

Console_ProgressBar

Console_ProgressBar displays a customizable progress bar in the console/terminal.

Some progress bar examples

This will display a very simple bar:
=====================================================

A more complicated bar, showing current status in numbers as well:
* 3/7 [==========================>-------------------------------------]  42.86%

Showing elapsed time, and using ANSI codes:
   - 109/345 [========>------------------]  31.59% Elapsed Time: 00:03.94

Showing an estimate for the remaining time:
- 105/345 [============>-------------------------------]  30.43% ETA: 00:11.52

  1. require_once "Console/ProgressBar.php"

  2. Create a new instance of Console_ProgressBar.

  3. Call update() whenever some progress has been made.

  4. (optional) erase(). after you're finished.

Simple progressbar example

<?php
require_once 'Console/ProgressBar.php';
$bar = new Console_ProgressBar('[%bar%] %percent%', '=>', ' ', 80, 7);

//do some processing here
for ($i = 0; $i <= 7; $i++) {
    $bar->update($i);
    sleep(1);
}
echo "\n";
?>

[=======================================>                              ]  57.14%

Creating the bar

In the example we create the progress bar instance with five parameters: The format string , bar string , empty string , console width and the target number .

The first parameter, format string , defines the layout of the whole progress bar. It may contain any character and has some variables that get replaced:

  • %bar% is the actual progress bar.

  • %current% is the current value set via update().

  • %max% is replaced with the maximum value set by the constructor (target number).

  • %fraction% - the same as %current%/%max%.

  • %percent% - status in percent.

  • %elapsed% - elapsed time.

  • %estimate% - an estimation of how long the progress will take.

The second argument is the string that is going to fill the progress bar. In the above example, the string "=>" was used. If the string you pass is too short (like "=>" in this example), the leftmost character is used to pad it to the needed size. If the string you pass is too long, excessive characters are stripped from the left.

The third argument is the string that fills the "empty" space in the progress bar. In the above example, that would be "-". If the string you pass is too short (like "-" in this example), the rightmost character is used to pad it to the needed size. If the string you pass is too long, excessive characters are stripped from the right.

The fourth argument specifies the width of the display. A normal console/terminal is 80 chars, so pass 80 here. Currently there is no method to determine the current width of a terminal.

The fifth argument is the target number of the progress bar. For example, if you wanted to display a progress bar for a download of a file that is 115 KB big, you would pass 115 here.

Updating and finishing

After setting up the progress bar, you can start doing the real work - up- or downloading files, calculating something etc. Whenever you did a step forward, call update() with the current step number.

When you're finished, you may want to remove the progress bar from screen - use erase() for this.

Prev | Console | Next
Console_Getopt::readPHPArgv | PEAR Manual | Console_Table


Console_Table

Console_Table

Console_Table provides methods to display tabular data in an ASCII terminal/shell.

Table of Contents
  • Introduction -- Introduction to Console_Table
  • Examples -- Console_Table examples
  • Console_Table::Console_Table -- Console_Table constructor
  • Console_Table::addCol -- Adds a column to the table
  • Console_Table::addData -- Adds data to the table.
  • Console_Table::addRow -- Adds a row to the table
  • Console_Table::getTable -- Returns the table in wonderful ASCII art
  • Console_Table::insertRow -- Inserts a row after a given row number in the table.
  • Console_Table::setHeaders -- Sets the headers for the columns
Prev | Console | Next
Console_ProgressBar | PEAR Manual | Introduction


Introduction

Introduction to Console_Table

Console_Table helps you to display tabular data on a terminal/shell/console. It provides features similar to those of HTML tables: Header and body (data) parts, alignment of columns, cell padding, multi line cells, border "styles" and column filters.

The class be filled with data by adding rows, adding cols or even importing whole arrays.

When adding whole arrays, e.g. a database result, you might want to format the data of certain columns before displaying them. Attaching a formatting callback to a column using Console_Table::addFilter() helps you with that task.

There might be times when you have an array and just want to get it out to the user, without caring about all the small details. Console_Table::fromArray() is the single-line-of-code tool in such cases.

Tip

In combination with PEAR's Console_Color package you can format cells by using e.g. different colors for different cell values - very convenient in combination with column filters.

Prev | Console_Table | Next
Console_Table | PEAR Manual | Examples


Examples

Console_Table examples

Table of Contents
  • Using addFilter -- Using column filtering with Console_Color

To get the feeling how Console_Table is used, try out the following examples.

A very simple example

Here we are following the basic steps to get some data out on the shell:

  • Creating a Console_Table object

  • Adding the header row

  • Adding some data rows

  • Rendering the table to the shell

<?php
require_once 'Console/Table.php';

$tbl = new Console_Table();
$tbl->setHeaders(
    array('Language', 'Year')
);
$tbl->addRow(array('PHP', 1994));
$tbl->addRow(array('C',   1970));
$tbl->addRow(array('C++', 1983));

echo $tbl->getTable();
?>

This examples would display as following:

+----------+------+
| Language | Year |
+----------+------+
| PHP      | 1994 |
| C        | 1970 |
| C++      | 1983 |
+----------+------+
Prev | Console_Table | Next
Introduction | PEAR Manual | Using addFilter


Using addFilter

Using column filtering with Console_Color

In this example we use Console_Table::addFilter() to colorize our table cells according to their value. Colorization is very easy using PEAR's Console_Color package. Just make sure you set the "color" parameter of Console_Color's constructor - otherwise you will see weird column widths.

After filling our table object with headers and data, we add an output filter by specifying a callback function. The first parameter to addFilter is the column number that shall be formatted, beginning with 0. Due to backwards compatibility with PHP4, addFilter requires a variable as second parameter, even if you just want to specfiy a simple function name.

We also have Console_Table align the "Profit" column right so that the commas are aligned equally.

<?php
require_once 'Console/Table.php';
require_once 'Console/Color.php';

//those could come e.g. from database
$data = array(
    array(2001, 128.23),
    array(2002, 256.42),
    array(2003, 10.21),
    array(2004, -25.79),
    array(2005, 0),
    array(2006, 982.12),
);

//prepare table
$tbl = new Console_Table(
    CONSOLE_TABLE_ALIGN_LEFT, CONSOLE_TABLE_BORDER_ASCII,
    1, null,
    true//this is important when using Console_Color
);
$tbl->setHeaders(
    array('Year', 'Profit')
);
$tbl->addData($data);

//add filter callback to colorize our profit column values
$callback = 'colorize';
$tbl->addFilter(1, $callback);

//Values should be aligned right
$tbl->setAlign(1, CONSOLE_TABLE_ALIGN_RIGHT);

echo $tbl->getTable();

/**
* Wraps Console color codes around $value,
* depending if its larger or smaller 0.
*
* @param float $value Value (column 1)
*
* @return string Colorful value
*/
function colorize($value)
{
    $str = number_format($value, 2, ',', '');
    if ($value < 0) {
        return Console_Color::convert('%r' . $str . '%n');
    } else if ($value == 0) {
        return $str;
    } else {
        return Console_Color::convert('%g' . $str . '%n');
    }
}
?>

The code above creates the following output, except that "Profit" values larger than 0 are colored in green, while the ones smaller zero are in red.

+------+--------+
| Year | Profit |
+------+--------+
| 2001 | 128,23 |
| 2002 | 256,42 |
| 2003 |  10,21 |
| 2004 | -25,79 |
| 2005 |   0,00 |
| 2006 | 982,12 |
+------+--------+
Prev | Examples | Next
Examples | PEAR Manual | Console_Table::Console_Table


Console_Table::Console_Table

Console_Table::Console_Table

Console_Table::Console_Table – Console_Table constructor

Synopsis

require_once 'Console/Table.php';

Console_Table Console_Table::Console_Table ( string $align = CONSOLE_TABLE_ALIGN_LEFT , string $border = CONSOLE_TABLE_BORDER_ASCII , integer $padding = 1 , string $charset = null , boolean $color = false )

Description

Constructor

Prev | Console_Table | Next
Using addFilter | PEAR Manual | Console_Table::addCol


Console_Table::addCol

Console_Table::addCol

Console_Table::addCol() – Adds a column to the table

Synopsis

require_once 'Console/Table.php';

void Console_Table::addCol ( array $col_data , integer $col_id , integer $row_id )

Description

Adds a column to the table

Parameter

array $col_data

The data of the column. Can be numeric or associative array

integer $col_id

The column index to populate

integer $row_id

If starting row is not zero, specify it here

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Console_Table | Next
Console_Table::Console_Table | PEAR Manual | Console_Table::addData


Console_Table::addData

Console_Table::addData

Console_Table::addData() – Adds data to the table.

Synopsis

require_once 'Console/Table.php';

void Console_Table::addData ( array $data , integer $col_id , integer $row_id )

Description

Adds data to the table. Argument should be a two dimensional array containing the data to be added.

Parameter

array $data

The data to add to the table

integer $col_id

Optional starting column ID

integer $row_id

Optional starting row ID

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Console_Table | Next
Console_Table::addCol | PEAR Manual | Console_Table::addRow


Console_Table::addRow

Console_Table::addRow

Console_Table::addRow() – Adds a row to the table

Synopsis

require_once 'Console/Table.php';

void Console_Table::addRow ( array $row , array $append = true )

Description

Adds a row to the table

Parameter

array $row

The row data to add

array $append

Whether to append or prepend the row

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Console_Table | Next
Console_Table::addData | PEAR Manual | Console_Table::getTable


Console_Table::getTable

Console_Table::getTable

Console_Table::getTable() – Returns the table in wonderful ASCII art

Synopsis

require_once 'Console/Table.php';

void Console_Table::getTable ( )

Description

Returns the table in wonderful ASCII art

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Console_Table | Next
Console_Table::addRow | PEAR Manual | Console_Table::insertRow


Console_Table::insertRow

Console_Table::insertRow

Console_Table::insertRow() – Inserts a row after a given row number in the table.

Synopsis

require_once 'Console/Table.php';

void Console_Table::insertRow ( array $row , integer $row_id )

Description

Inserts a row after a given row number in the table. If $row_id is not given it will prepend the row.

Parameter

array $row

The data to insert

integer $row_id

Row number to insert before

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Console_Table | Next
Console_Table::getTable | PEAR Manual | Console_Table::setHeaders


Console_Table::setHeaders

Console_Table::setHeaders

Console_Table::setHeaders() – Sets the headers for the columns

Synopsis

require_once 'Console/Table.php';

void Console_Table::setHeaders ( array $headers )

Description

Sets the headers for the columns

Parameter

array $headers

The column headers

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Console_Table | Next
Console_Table::insertRow | PEAR Manual | Database


Database

Database

Provides database-related Packages

Table of Contents
  • DB
  • DB_DataObject
  • DB_DataObject_FormBuilder
  • DB_NestedSet
  • DB_Pager
  • DB_QueryTool
  • DB_Table
  • MDB
  • MDB2
  • MDB_QueryTool
  • MDB2_Schema
  • MDB2_TableBrowser
Prev | PEAR Packages | Next
Console_Table::setHeaders | PEAR Manual | DB


DB

DB

A unified API for accessing SQL databases

This package has been superseded. Please use MDB2 for new projects.

Table of Contents
  • Introduction - DSN -- The Data Source Name
  • Introduction - Connect -- Connecting and disconnecting a database
  • Introduction - Query -- Performing queries
  • Introduction - Results -- Obtaining data from query results
  • Introduction - Prepare & Execute -- Prepare and execute SQL statements
  • Introduction - autoPrepare & autoExecute -- Automatically prepare and execute SQL statements
  • Introduction - Portability -- Database portability features
  • Introduction - Sequences -- Sequences and auto-incrementing
  • Overview - get* methods -- Comparison of get* methods
  • DB -- Main class
  • DB::connect() -- Connects to a database
  • DB::isError() -- Determines if a variable is a DB_Error object
  • DB_common -- Interface for database access
  • DB_common::affectedRows() -- Finds number of rows affected by a data changing query
  • DB_common::autoCommit() -- Turns auto-commit on or off
  • DB_common::autoExecute() -- Prepares and runs an INSERT or UPDATE query based on variables you supply
  • DB_common::autoPrepare() -- Prepares an INSERT or UPDATE statement based on variables you supply
  • DB_common::commit() -- Commits the current transaction
  • DB_common::createSequence() -- Creates a new sequence
  • DB_common::disconnect() -- Disconnects from a database
  • DB_common::dropSequence() -- Deletes a sequence
  • DB_common::escapeSimple() -- Escapes a string according to the current DBMS's standards
  • DB_common::execute() -- Executes a prepared SQL statement
  • DB_common::executeMultiple() -- Runs a prepared SQL statement for each element of an array
  • DB_common::freePrepared() -- Releases resources associated with a prepared SQL statement
  • DB_common::getAll() -- Runs a query and returns all the data as an array
  • DB_common::getAssoc() -- Runs a query and returns the data as an array
  • DB_common::getCol() -- Runs a query and returns the data from a single column
  • DB_common::getListOf() -- Views database system information
  • DB_common::getOne() -- Runs a query and returns the first column of the first row
  • DB_common::getOption() -- Determines current state of a PEAR DB configuration option
  • DB_common::getRow() -- Runs a query and returns the first row
  • DB_common::limitQuery() -- Sends a LIMIT query to the database
  • DB_common::nextId() -- Returns the next number from a sequence
  • DB_common::nextQueryIsManip() -- Informs the DB driver that the next query is a manipulation query
  • DB_common::prepare() -- Prepares a SQL statement for later execution
  • DB_common::provides() -- Checks if the DBMS supports a particular feature
  • DB_common::query() -- Sends a query to the database
  • DB_common::quote() -- DEPRECATED: Quotes a string
  • DB_common::quoteIdentifier() -- Formats a string so it can be safely used as an identifier
  • DB_common::quoteSmart() -- Formats input so it can be safely used as a literal
  • DB_common::rollback() -- Rolls back the current transaction
  • DB_common::setFetchMode() -- Sets the default fetch mode
  • DB_common::setOption() -- Sets run-time configuration options for PEAR DB
  • DB_common::tableInfo() -- Gets info about columns in a table or a query result
  • DB_result -- DB result set
  • DB_result::fetchInto() -- Fetches a row of a result set into a variable
  • DB_result::fetchRow() -- Fetches a row from a result set
  • DB_result::free() -- Releases a result set
  • DB_result::nextResult() -- Gets result sets from multiple queries
  • DB_result::numCols() -- Gets number of columns in a result set
  • DB_result::numRows() -- Gets number of rows in a result set
  • DB_Error -- DB Error object
Prev | Database | Next
Database | PEAR Manual | Introduction - DSN


Introduction - DSN

Introduction - DSN

Introduction - DSN – The Data Source Name

Description

To connect to a database through PEAR::DB, you have to create a valid DSN - data source name. This DSN consists in the following parts:

  • phptype: Database backend used in PHP (i.e. mysql , odbc etc.)
  • dbsyntax: Database used with regards to SQL syntax etc. When using ODBC as the phptype, set this to the DBMS type the ODBC driver is connecting to. Examples: access, db2, mssql, navision, solid, etc.
  • protocol: Communication protocol to use ( i.e. tcp, unix etc.)
  • hostspec: Host specification (hostname[:port])
  • database: Database to use on the DBMS server
  • username: User name for login
  • password: Password for login
  • proto_opts: Maybe used with protocol
  • option: Additional connection options in URI query string format. options get separated by &

The format of the supplied DSN is in its fullest form:

phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value

Most variations are allowed:

phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype:///database
phptype:///database?option=value&anotheroption=anothervalue
phptype(dbsyntax)
phptype

The currently supported database backends are:

dbase  -> dBase
fbsql  -> FrontBase (functional since DB 1.7.0)
ibase  -> InterBase (functional since DB 1.7.0)
ifx    -> Informix
msql   -> Mini SQL (functional since DB 1.7.0)
mssql  -> Microsoft SQL Server (NOT for Sybase. Compile PHP --with-mssql)
mysql  -> MySQL (for MySQL <= 4.0)
mysqli -> MySQL (for MySQL >= 4.1) (requires PHP 5) (since DB 1.6.3)
oci8   -> Oracle 7/8/9
odbc   -> ODBC (Open Database Connectivity)
pgsql  -> PostgreSQL
sqlite -> SQLite
sybase -> Sybase

With an up-to-date version of DB, you can use a second DSN format

phptype(syntax)://user:pass@protocol(proto_opts)/database

If your database, option values, username or password contain characters used to delineate DSN parts, you can escape them via URI hex encodings:

: = %3a   / = %2f   @ = %40
+ = %2b   ( = %28   ) = %29
? = %3f   = = %3d   & = %26

Please note, that some features may be not supported by all database backends. Please refer to the PEAR DB extensions status document located at: /pear/base/dir/DB/doc/STATUS to get a detailed list about what features are supported by which backend.

Example

Connect to database through a socket

mysql://user@unix(/path/to/socket)/pear

Connect to database on a non standard port

pgsql://user:pass@tcp(localhost:5555)/pear

Connect to SQLite on a Unix machine using options

sqlite:////full/unix/path/to/file.db?mode=0666

Connect to SQLite on a Windows machine using options

sqlite:///c:/full/windows/path/to/file.db?mode=0666

Connect to MySQLi using SSL

mysqli://user:pass@localhost/pear?key=client-key.pem&cert=client-cert.pem

Connecting to MS Access sometimes requires admin as the user name

odbc(access)://admin@/datasourcename

Connecting to ODBC with a specific cursor

odbc(access)://admin@/datasourcename?cursor=SQL_CUR_USE_ODBC
Prev | DB | Next
DB | PEAR Manual | Introduction - Connect


Introduction - Connect

Introduction - Connect

Introduction - Connect – Connecting and disconnecting a database

Description

To connect to a database you have to use the function connect(), which requires a valid DSN as the first parameter. This parameter can either be a string or an array. If using an array, the array used gets merged with the default information:

$dsn = array(
    'phptype'  => false,
    'dbsyntax' => false,
    'username' => false,
    'password' => false,
    'protocol' => false,
    'hostspec' => false,
    'port'     => false,
    'socket'   => false,
    'database' => false,
);

Any elements you set override the defaults and the remainder stay at their defaults.

The second parameter is the optional $options array that can contain runtime configuration settings for this package. See setOption() for more information on the available settings.

In case of success you get a new instance of the database class. It is strongly recommended to check this return value with isError().

To disconnect use the method disconnect() from your database class instance.

Connect and disconnect

<?php
require_once 'DB.php';

$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
    'debug'       => 2,
    'portability' => DB_PORTABILITY_ALL,
);

$db =& DB::connect($dsn, $options);
if (PEAR::isError($db)) {
    die($db->getMessage());
}

// ...

$db->disconnect();
?>

Connect using an array for the DSN information

<?php
require_once 'DB.php';

$dsn = array(
    'phptype'  => 'pgsql',
    'username' => 'someuser',
    'password' => 'apasswd',
    'hostspec' => 'localhost',
    'database' => 'thedb',
);

$options = array(
    'debug'       => 2,
    'portability' => DB_PORTABILITY_ALL,
);

$db =& DB::connect($dsn, $options);
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>

When connecting to SQLite using a DSN array, the value of the mode element must be a string:

<?php
$dsn = array(
    'phptype'  => 'sqlite',
    'database' => 'thedb',
    'mode'     => '0644',
);
?>

Connect to MySQLi via SSL using an array for the DSN information

The ssl element of the $options array must be set to TRUE in order for SSL to work. Each of the extra elements in the $dsn array (key through cipher in the example below) are optional.

<?php
require_once 'DB.php';

$dsn = array(
    'phptype'  => 'mysqli',
    'username' => 'someuser',
    'password' => 'apasswd',
    'hostspec' => 'localhost',
    'database' => 'thedb',
    'key'      => 'client-key.pem',
    'cert'     => 'client-cert.pem',
    'ca'       => 'cacert.pem',
    'capath'   => '/path/to/ca/dir',
    'cipher'   => 'AES',
);

$options = array(
    'ssl' => true,
);

$db =& DB::connect($dsn, $options);
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>

Connect to a PostgreSQL database via a socket

<?php
require_once 'DB.php';

$dsn = 'pgsql://someuser:apasswd@unix(/tmp)/thedb';
$options = array(
    'debug'       => 2,
    'portability' => DB_PORTABILITY_ALL,
);

$db =& DB::connect($dsn, $options);
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>

See

DB_Error, setOption(), "Intro - Portability"

Prev | DB | Next
Introduction - DSN | PEAR Manual | Introduction - Query


Introduction - Query

Introduction - Query

Introduction - Query – Performing queries

Description

PEAR DB provides several methods for querying databases. The most direct method is query(). It takes a SQL query string as an argument. There are three possible returns: a new DB_result object for queries that return results (such as SELECT queries), DB_OK for queries that manipulate data (such as INSERT queries) or a DB_Error object on failure.

Doing a query

<?php
// Create a valid DB object named $db
// at the beginning of your program...
require_once 'DB.php';

$db =& DB::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($db)) {
    die($db->getMessage());
}

// Proceed with a query...
$res =& $db->query('SELECT * FROM clients');

// Always check that result is not an error
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

query() can be used instead of prepare() and execute(), if you set the $params parameter and your query uses placeholders.

Using query in prepare/execute mode with a scalar parameter

<?php
// Once you have a valid DB object named $db...
$sql  = 'select * from clients where clientid = ?';
$data = 53;

$res =& $db->query($sql, $data);

// Always check that result is not an error
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

Using query in prepare/execute mode with an array parameter

<?php
// Once you have a valid DB object named $db...
$sql  = 'select * from clients where clientid = ? and statusid = ?';
$data = array(53, 4);

$res =& $db->query($sql, $data);

// Always check that result is not an error
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>
Prev | DB | Next
Introduction - Connect | PEAR Manual | Introduction - Results


Introduction - Results

Introduction - Results

Introduction - Results – Obtaining data from query results

Description

Fetching Individual Rows From Query Results

The DB_result object provides two methods for fetching data from rows of a result set: fetchRow() and fetchInto().

fetchRow() returns the row's data. fetchInto() assigns the row's data to a variable you provide and returns DB_OK.

The result pointer gets moved to the next row each time these methods are called. NULL is returned when the end of the result set is reached.

DB_Error is returned if an error is encountered.

Fetching a result set

<?php
// Create a valid DB object named $db
// at the beginning of your program...
require_once 'DB.php';

$db =& DB::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($db)) {
    die($db->getMessage());
}

// Proceed with getting some data...
$res =& $db->query('SELECT * FROM mytable');

// Get each row of data on each iteration until
// there are no more rows
while ($res->fetchInto($row)) {
    // Assuming DB's default fetchmode is DB_FETCHMODE_ORDERED
    echo $row[0] . "\n";
}

// Or, you could have done the same thing using fetchRow()
// while ($row =& $res->fetchRow()) {
//     // Assuming DB's default fetchmode is DB_FETCHMODE_ORDERED
//     echo $row[0] . "\n";
// }
?>

Formats of Fetched Rows

The data from the row of a query result can be placed into one of three constructs: an ordered array (with column numbers as keys), an associative array (with column names as keys) or an object (with column names as properties).

DB_FETCHMODE_ORDERED (default)

Array
(
    [0] => 28
    [1] => hi
)

DB_FETCHMODE_ASSOC

Array
(
    [a] => 28
    [b] => hi
)

DB_FETCHMODE_OBJECT

stdClass Object
(
    [a] => 28
    [b] => hi
)

NOTE: When a query contains the same column name more than once (such as when joining tables which have duplicate column names) and the fetch mode is DB_FETCHMODE_ASSOC or DB_FETCHMODE_OBJECT, the data from the last column with a given name will be the one returned. There are two immediate options to work around this issue:

  • Use aliases in your query, for example People.Name AS PersonName
  • Change the fetch mode to DB_FETCHMODE_ORDERED

TIP: If you are running into this issue, it likely indicates poor planning of the database schema. Either data is needlessly being duplicated or the same names are being used for different kinds of data.

How to Set Formats

You can set the fetch mode each time you call a fetch method and/or you can set the default fetch mode for the whole DB instance by using the setFetchMode() method.

Determining fetch mode per call

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM users');

while ($res->fetchInto($row, DB_FETCHMODE_ASSOC)) {
    echo $row['id'] . "\n";
}
?>

Changing default fetch mode

<?php
// Once you have a valid DB object named $db...
$db->setFetchMode(DB_FETCHMODE_ASSOC);

$res =& $db->query('SELECT * FROM users');

while ($res->fetchInto($row)) {
    echo $row['id'] . "\n";
}
?>

Fetch Rows by Number

The PEAR DB fetch system also supports an extra parameter to the fetch statement. So you can fetch rows from a result by number. This is especially helpful if you only want to show sets of an entire result (for example in building paginated HTML lists), fetch rows in an special order, etc.

Fetching by number

<?php
// Once you have a valid DB object named $db...

// the row to start fetching
$from = 50;

// how many results per page
$resPage = 10;

// the last row to fetch for this page
$to = $from + $resPage;

foreach (range($from, $to) as $rowNum) {
    if (!$res->fetchInto($row, DB_FETCHMODE_ORDERED, $rowNum)) {
        break;
    }
    echo $row[0] . "\n";
}
?>

Getting Entire Result Sets

The DB_common object provides several methods that make data retrieval easy by combining the processes of running of the query string you provide, putting the returned information into a PHP data structure and freeing the results. These methods include getOne(), getRow(), getCol(), getAssoc() and getAll().

Freeing Result Sets

Once you finish using a result set, if your script continues for a while, it's a good idea to save memory by freeing the result set via Use free().

Freeing

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT name, address FROM clients');
while ($res->fetchInto($row)) {
    echo $row['name'] . ', ' . $row['address'] . "\n";
}
$res->free();
?>

Getting More Information From Query Results

With DB there are four ways to retrieve useful information about the query result sets themselves:

numRows() tells how many rows are in a SELECT query result

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
echo $res->numRows();
?>

numCols() tells how many columns are in a SELECT query result

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
echo $res->numCols();
?>

affectedRows() tells how many rows were altered by a data change query (INSERT, UPDATE or DELETE)

<?php
// remember that this statement won't return a result object
$db->query('DELETE * FROM clients');
echo 'I have deleted ' . $db->affectedRows() . ' clients';
?>

tableInfo() returns an associative array with information about the columns in a SELECT query result

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
print_r($db->tableInfo($res));

// That usage works for DB 1.6.0 or later.
// Below is the syntax for earlier versions:
print_r($res->tableInfo());
?>

Checking for Errors

Don't forget to use isError() to check if your actions return a DB_Error object.

Prev | DB | Next
Introduction - Query | PEAR Manual | Introduction - Prepare & Execute


Introduction - Prepare & Execute

Introduction - Prepare & Execute

Introduction - Prepare & Execute – Prepare and execute SQL statements

Description

Purpose

prepare() and execute*() give you more power and flexibilty for query execution. Prepare/execute mode is helpful when you have to run the same query several times but with different values in it, such as adding a list of addresses into a database.

Another place prepare/execute is useful is supporting databases which have different SQL syntaxes. Imagine you want to support two databases with different INSERT syntax:

db1: INSERT INTO tbl_name (col1, col2) VALUES (expr1, expr2)
db2: INSERT INTO tbl_name SET col1=expr1, col2=expr2

Correspondending to create multi-lingual scripts you can create a array with queries like this:

<?php
$statement['db1']['INSERT_PERSON'] = 'INSERT INTO person
    (surname, name, age) VALUES (?, ?, ?)';

$statement['db2']['INSERT_PERSON'] = 'INSERT INTO person
    SET surname=?, name=?, age=?';
?>

Prepare

To use the features above, you have to do two steps. Step one is to prepare the statement and the second is to execute it.

To start out, you need to prepare() a generic SQL statement. Create a generic statement by writing the SQL query as usual:

SELECT surname, name, age
    FROM person
    WHERE name = 'name_to_find' AND age < age_limit

Then substitute "placeholders" for the literal values which will be provided at run time:

SELECT surname, name, age
    FROM person
    WHERE name = ? AND age < ?

Then pass this SQL statement to prepare(), which returns a statement handle to be used when calling execute().

prepare() can handle different types of placeholders (a.k.a. wildcards).

  • ? - (recommended) stands for a scalar value like strings or numbers. The value will be automatically escaped and quoted according to the current DBMS's requirements.
  • ! - stands for a scalar value and will inserted into the statement "as is".
  • & - requires an existing filename, the content of this file will be included into the statement (i.e. for saving binary data of a graphic file in a database)

Use backslashes to escape placeholder characters if you don't want them to be interpreted as placeholders:

UPDATE foo SET col=? WHERE col='over \& under'

Execute

After preparing the statement, you can execute the query. This means to assign the variables to the prepared statement. To do this, execute() requires two arguments: the statement handle returned by prepare() and a scalar or array with the values to assign.

Passing scalars to execute()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers (number) VALUES (?)');
$db->execute($sth, 1);
$db->execute($sth, 8);
?>

When a prepared statement has multiple placeholders, you must use an array to pass the values to execute(). The first entry of the array represents the first placeholder, the second the second placeholder, etc. The order is independent of the type of placeholder used.

Passing an array to execute()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers VALUES (?, ?, ?)');

$data = array(1, 'one', 'en');
$db->execute($sth, $data);
?>

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement. Similarly, identifiers (i.e. table names and column names) can not be used because the names get validated during the prepare phase.

ExecuteMultiple

DB contains a process for executing several queries at once. So, rather than having to execute them manually, like this:

Passing arrays to execute()

<?php
// Once you have a valid DB object named $db...
$alldata = array(array(1, 'one', 'en'),
                 array(2, 'two', 'to'),
                 array(3, 'three', 'tre'),
                 array(4, 'four', 'fire'));
$sth = $db->prepare('INSERT INTO numbers VALUES (?, ?, ?)');
foreach ($alldata as $row) {
    $db->execute($sth, $row);
}
?>

which would issue four queries:

INSERT INTO numbers VALUES ('1', 'one', 'en')
INSERT INTO numbers VALUES ('2', 'two', 'to')
INSERT INTO numbers VALUES ('3', 'three', 'tre')
INSERT INTO numbers VALUES ('4', 'four', 'fire')

you can use executeMultiple() to avoid the explicit foreach in the eample above:

Using executeMultiple() instead of execute()

<?php
// Once you have a valid DB object named $db...
$alldata = array(array(1, 'one', 'en'),
                 array(2, 'two', 'to'),
                 array(3, 'three', 'tre'),
                 array(4, 'four', 'fire'));
$sth = $db->prepare('INSERT INTO numbers VALUES (?, ?, ?)');
$db->executeMultiple($sth, $alldata);
?>

The result is the same. If one of the records failed, the unfinished records will not be executed.

execute*() has three possible returns: a new DB_result object for queries that return results (such as SELECT queries), DB_OK for queries that manipulate data (such as INSERT queries) or a DB_Error object on failure

Prev | DB | Next
Introduction - Results | PEAR Manual | Introduction - autoPrepare & autoExecute


Introduction - autoPrepare & autoExecute

Introduction - autoPrepare & autoExecute

Introduction - autoPrepare & autoExecute – Automatically prepare and execute SQL statements

Description

Purpose

autoPrepare() and autoExecute() reduce the need to write boring INSERT or UPDATE SQL queries which are difficult to maintain when you add a field for instance.

Imagine you have a 'user' table with 3 fields (id, name and country). You have to write sql queries like:

INSERT INTO table (id, name, country) VALUES (?, ?, ?)
UPDATE table SET id=?, name=?, country=? WHERE ...

If you add a field ('birthYear' for example), you have to rewrite your queries which is boring and can lead to bugs (if you forget one query for instance).

autoPrepare

With autoPrepare(), you don't have to write your insert or update queries. For example:

<?php
// Once you have a valid DB object named $db...
$table_name   = 'user';
$table_fields = array('id', 'name', 'country');

$sth = $db->autoPrepare($table_name, $table_fields,
                        DB_AUTOQUERY_INSERT);

if (PEAR::isError($sth)) {
    die($sth->getMessage());
}
?>

In this example, autoPrepare() will build the following SQL query:

INSERT INTO user (id, name, country) VALUES (?, ?, ?)

And then, it will call prepare() with it.

To add records, you have to use execute() or executeMultiple() like:

<?php
// ... contining from the example above...
$table_values = array(1, 'Fabien', 'France');

$res =& $db->execute($sth, $table_values);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

So, you don't have to write any SQL INSERT queries! And it works with UPDATE queries too. For flexibility reasons, you have only to write the WHERE clause of the query. For instance:

<?php
// Once you have a valid DB object named $db...
$table_name   = 'user';
$table_fields = array('name', 'country');
$table_values = array('Bob', 'USA');

$sth = $db->autoPrepare($table_name, $table_fields,
                        DB_AUTOQUERY_UPDATE, 'id = 1');

if (PEAR::isError($sth)) {
    die($sth->getMessage());
}

$res =& $db->execute($sth, $table_values);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

autoPrepare() will build the following query:

UPDATE user SET name=?, country=? WHERE id=1

Then, it will call prepare() with it.

Be careful, if you don't specify any WHERE clause, all the records of the table will be updated.

autoExecute

Using autoExecute() is the easiest way to do insert or update queries. It is a mix of autoPrepare() and execute().

You only need an associative array (key => value) where keys are fields names and values are corresponding values of these fields. For instance:

<?php
// Once you have a valid DB object named $db...
$table_name = 'user';

$fields_values = array(
    'id'      => 1,
    'name'    => 'Fabien',
    'country' => 'France'
);

$res = $db->autoExecute($table_name, $fields_values,
                        DB_AUTOQUERY_INSERT);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

And that's all! The following query is built and executed:

INSERT INTO user (id, name, country)
  VALUES (1, 'Fabien', 'France')

And it's the same thing for UPDATE queries:

<?php
// Once you have a valid DB object named $db...
$table_name = 'user';

$fields_values = array(
    'name'    => 'Fabien',
    'country' => 'France'
);

$res = $db->autoExecute($table_name, $fields_values,
                        DB_AUTOQUERY_UPDATE, 'id = 1');

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

which prepares and executes the following query:

UPDATE user SET name='Fabien', country='France'
  WHERE id = 1

Be careful, if you don't specify any WHERE statement, all the records of the table will be updated.

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement.

Prev | DB | Next
Introduction - Prepare & Execute | PEAR Manual | Introduction - Portability


Introduction - Portability

Introduction - Portability

Introduction - Portability – Database portability features

Description

Each database management system (DBMS) has its own behaviors. For example, some databases capitalize field names in their output, some lowercase them, while others leave them alone. These quirks make it difficult to port your scripts over to another server type. PEAR DB strives to overcome these differences so your program can switch between DBMS's without any changes.

You control which portability modes are enabled by using the portability configuration option. Configuration options are set via connect() and setOption().

The portability modes are bitwised, so they can be combined using | and removed using ^. See the examples section below on how to do this.

Portability Mode Constants

  • DB_PORTABILITY_ALL

    turn on all portability features

  • DB_PORTABILITY_DELETE_COUNT

    force reporting the number of rows deleted. Some DBMS's don't count the number of rows deleted when performing simple DELETE FROM tablename queries. This mode tricks such DBMS's into telling the count by adding WHERE 1=1 to the end of DELETE queries.

  • DB_PORTABILITY_ERRORS

    makes certain error messages in certain drivers compatible with those from other DBMS's

    Error Code Re-mappings
    Driver | Description | Old Constant | New Constant
    mysql, mysqli | unique and primary key constraints | DB_ERROR_ALREADY_EXISTS | DB_ERROR_CONSTRAINT
    mysql, mysqli | not-null constraints | DB_ERROR_CONSTRAINT | DB_ERROR_CONSTRAINT_NOT_NULL
    odbc(access) | MS's ODBC driver mistakenly reports 'no such field' as code 07001, which means 'too few parameters.' When this option is on, that code gets remapped. | DB_ERROR_MISMATCH | DB_ERROR_NOSUCHFIELD

  • DB_PORTABILITY_LOWERCASE

    convert names of tables and fields to lower case when using get*(), fetch*() and tableInfo()

  • DB_PORTABILITY_NONE (default)

    turn off all portability features

  • DB_PORTABILITY_NULL_TO_EMPTY

    convert null values to empty strings in data output by get*() and fetch*(). Needed because Oracle considers empty strings to be null, while most other DBMS's know the difference between empty and null.

  • DB_PORTABILITY_NUMROWS

    enable hack that makes numRows() work in Oracle

  • DB_PORTABILITY_RTRIM

    right trim the data output by get*() and fetch*()

Backwards Compatibility

Some of this functionality used to be handled by the now deprecated optimize option. For backwards compatibility, when this option is set to portability, the following databases get these portability modes turned on:

  • oci8: DB_PORTABILITY_LOWERCASE and DB_PORTABILITY_DELETE_COUNT

  • fbsql, mysql, mysqli, sqlite: DB_PORTABILITY_DELETE_COUNT

When the optimize option gets set to performance the portability mode is switched to DB_PORTABILITY_NONE.

Example

Turning on all portability options while connecting

<?php
require_once 'DB.php';

$dsn = 'mysql://user:password@host/database'
$options = array(
    'debug'       => 2,
    'portability' => DB_PORTABILITY_ALL,
);

$db =& DB::connect($dsn, $options);
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>

Using setOption() to enable portability for lowercasing and trimming

<?php
// Once you have a valid DB object named $db...
$db->setOption('portability',
        DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
?>

Using setOption() to enable all portability options except trimming

<?php
// Once you have a valid DB object named $db...
$db->setOption('portability',
        DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
?>
Prev | DB | Next
Introduction - autoPrepare & autoExecute | PEAR Manual | Introduction - Sequences


Introduction - Sequences

Introduction - Sequences

Introduction - Sequences – Sequences and auto-incrementing

Description

Sequences are a way of offering unique IDs for data rows. If you do most of your work with e.g. MySQL, think of sequences as another way of doing AUTO_INCREMENT.

It's quite simple, first you request an ID, and then you insert that value in the ID field of the new row you're creating. You can have more than one sequence for all your tables, just be sure that you always use the same sequence for any particular table. To get the value of this unique ID use nextId(), if a sequence doesn't exists, it will be created automatically.

The sequence is automatically incremented each time nextId() is called.

Using a sequence

<?php
// Once you have a valid DB object named $db...
$id = $db->nextId('mySequence');
if (PEAR::isError($id)) {
    die($id->getMessage());
}

// Use the ID in your INSERT query
$res =& $db->query("INSERT INTO myTable (id, text) VALUES ($id, 'foo')");
?>

Note

When using PEAR DB's sequence methods, we strongly advise using these methods for all procedures, including the creation of the sequences. Do not use PEAR DB's methods to access sequences that were created directly in the DBMS.

If you have a compelling reason to ignore this advice, be aware that the $seq_name argument given to all of PEAR DB's sequence methods are modified before DB calls the underlying DBMS.

$seq_name is passed through PHP's sprintf() function using the value from the seqname_format option as sprintf()'s format argument. The default seqname_format is %s_seq. So, for example, if you use person_id_sequence as the $seq_name , PEAR DB will change that name to person_id_sequence_seq when querying the DBMS about creating/accessing/updating the sequence.

The seqname_format can be modified when connect()'ing or via setOption().

Please note that you may need to change the seqname_format option to represent a quoted form of the sequence name if the sequence names contain characters that cannot be used unquoted within queries. For example, PostgreSQL users with uppercase table names will probably need to use "%s_seq" (note the quotes) for queries to work as expected.

See

createSequence(),

nextId(),

dropSequence()

Prev | DB | Next
Introduction - Portability | PEAR Manual | Overview - get* methods


Overview - get* methods

Overview - get* methods

Overview - get* methods – Comparison of get* methods

Description

This page gives an overview about the methods that allow
you to fetch entire result sets without looping over single
result rows:

  getOne(),

  getRow(),

  getCol(),

  getAssoc() and

  getAll().

Our data source is the following table:

Data used in this example
id | nickname | email
1 | pinky | pinky@domination.org
2 | thebrain | brain@dominators.net

A simple var_dump() is used to make clear in which use cases the methods can be used:

<?php
require_once 'DB.php';
$db = DB::connect('mysql://user:pass@localhost/example');

var_dump(
    $db->getOne('SELECT nickname, id, email FROM users')
);
?>

getOne

getOne() fetches the first column of the first row.

string(5) "pinky"

getRow

getRow() fetches the first row.

array(3) {
  [0] => string(5)  "pinky"
  [1] => string(1)  "1"
  [2] => string(20) "pinky@domination.org"
}

getCol

getCol() fetches the first column of all rows.

array(2) {
  [0]=> string(5) "pinky"
  [1]=> string(8) "thebrain"
}

getAssoc

getAssoc() fetches all rows into an array, using the first colum of the rows as array key. This column is removed from the array itself.

array(2) {
  ["pinky"] => array(2) {
    [0] => string(1) "1"
    [1] => string(20) "pinky@domination.org"
  }
  ["thebrain"] => array(2) {
    [0] => string(1) "2"
    [1] => string(20) "brain@dominators.net"
  }
}

getAll

getAll() fetches all columns from all rows into an array.

array(2) {
  [0] => array(3) {
    [0] => string(5) "pinky"
    [1] => string(1) "1"
    [2] => string(20) "pinky@domination.org"
  }
  [1] => array(3) {
    [0] => string(8) "thebrain"
    [1] => string(1) "2"
    [2] => string(20) "brain@dominators.net"
  }
}
Prev | DB | Next
Introduction - Sequences | PEAR Manual | DB


DB

DB

DB – Main class

Description

The main DB class is simply a container class with some static methods for creating DB objects.

Prev | DB | Next
Overview - get* methods | PEAR Manual | DB::connect()


DB::connect()

DB::connect()

DB::connect() – Connects to a database

Synopsis

object connect ( mixed $dsn , array $options = array() )

Description

Creates a new DB connection object and connect to the specified database

Parameter

string or array $dsn

Data Source Name. String formats are described in the DSN section while array formats are covered in the "Intro - Connect" section.

array $options

An optional argument can contain runtime configuration settings for this package. See setOption() for more information on the available settings.

Return value

object - a new DB object or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NOT_FOUND | not found | The database specific class was not found. | Check the $dsn and make sure to have an complete installation of the DB-package and that you database is supported by DB.

Note

This function should be called statically.

See

disconnect(), "Intro - Connect"

Prev | DB | Next
DB | PEAR Manual | DB::isError()


DB::isError()

DB::isError()

DB::isError() – Determines if a variable is a DB_Error object

Synopsis

boolean isError ( mixed $value )

Description

Checks whether a result code from a DB method is a DB_Error object or not.

You're generally better off using PEAR::isError() instead of the DB specific isError().

Parameter

mixed $value

Variable to check

Return value

boolean - TRUE if $value is a DB_Error object

Note

This function should be called statically.

Example

Using isError()

<?php
require_once 'DB.php';

$db =& DB::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>
Prev | DB | Next
DB::connect() | PEAR Manual | DB_common


DB_common

DB_common

DB_common – Interface for database access

Description

DB_common is an interface class; that provides all methods to query a specific database. An instance of a database specific class will be returned by the connect() method.

Prev | DB | Next
DB::isError() | PEAR Manual | DB_common::affectedRows()


DB_common::affectedRows()

DB_common::affectedRows()

DB_common::affectedRows() – Finds number of rows affected by a data changing query

Synopsis

integer affectedRows ( )

Description

Number of rows affected by a data manipulation query (for example INSERT, UPDATE or DELETE). Returns 0 for SELECT queries.

Return value

integer - number of rows or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NOT_CAPABLE | DB backend not capable | Function is not supported by the database backend | Switch to another database system, if you really need this feature.

Note

This function can not be called statically.

Example

Using affectedRows()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('DELETE * FROM clients');

if (PEAR::isError($res)) {
    die($res->getMessage());
}

echo 'I have deleted ' . $db->affectedRows() . ' clients';
?>

See

numRows(),

numCols(),

query(),

execute(),

autoExecute(),

executeMultiple()

Prev | DB | Next
DB_common | PEAR Manual | DB_common::autoCommit()


DB_common::autoCommit()

DB_common::autoCommit()

DB_common::autoCommit() – Turns auto-commit on or off

Synopsis

mixed autoCommit ( boolean $onoff = false )

Description

Turns auto-commit on or off.

Parameter

boolean $onoff

TRUE to turn auto-commit on. FALSE to turn auto-commit off.

Return value

integer - DB_OK on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error.

Note

This function can not be called statically.

When using MySQL as your DBMS, transactions can only be used when the tables in question use the InnoDB format.

Example

Using autocommit()

<?php
$db =& DB::connect('ibase(firebird)://user:pw@localhost/path/file');

$db->autoCommit(false);

$db->query('CREATE TABLE blah (a integer)');
$db->query('CREATE TABLE blue (b integer)');
$db->commit();

$db->query('INSERT INTO blah (a) VALUES (11)');
$db->query('INSERT INTO blah (a) VALUES (12)');

$res1 =& $db->query('SELECT a FROM blah');
if (DB::isError($res1)) {
    echo $res1->getMessage() . "\n";
}
$i = 1;
while ($res1->fetchInto($row, DB_FETCHMODE_ORDERED)) {
    echo "fetch data $row[0]\n";
    echo "insert number $i...\n";
    $res2 =& $db->query("INSERT INTO blue (b) VALUES ($i)");
    if (DB::isError($res2)) {
        echo $res2->getMessage() . "\n";
    }
    $i++;
}
$res1->free();

$db->query('DROP TABLE blah');
$db->query('DROP TABLE blue');
$db->commit();
?>

See

commit(), rollback()

Prev | DB | Next
DB_common::affectedRows() | PEAR Manual | DB_common::autoExecute()


DB_common::autoExecute()

DB_common::autoExecute()

DB_common::autoExecute() – Prepares and runs an INSERT or UPDATE query based on variables you supply

Synopsis

integer autoExecute ( string $table , array $fields_values , integer $mode = DB_AUTOQUERY_INSERT , string $where = false )

Description

Automatically prepares and executes INSERT or UPDATE queries.

This method builds a SQL statement using autoPrepare() and then executes the statement using execute() with it.

Parameter

string $table

name of the table

array $fields_values

assoc (key => value), keys are fields names, values are values of these fields

Values are automatically escaped and quoted according to the current DBMS's requirements.

integer $mode

type of query to make (DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE)

string $where

a string to be used in the WHERE clause. This is only used when $mode is DB_AUTOQUERY_UPDATE. The string is put directly into the query, so you must escape and quote literals according to the DBMS's standards.

Return value

integer - DB_OK on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NEED_MORE_DATA | insufficient data supplied | Your associative array, which has to contain fields names and their values, is empty. | Check and correct your fields_values array.
DB_ERROR_SYNTAX | syntax error | You use an unknown mode. | Available modes are only DB_AUTOQUERY_INSERT for INSERT queries or DB_AUTOQUERY_UPDATE for UPDATE queries.
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error.

Note

This function can not be called statically.

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement.

Example

Using autoExecute() in insert mode

<?php
// Once you have a valid DB object named $db...
$table_name = 'user';

$fields_values = array(
    'id'      => 1,
    'name'    => 'Fabien',
    'country' => 'France'
);

$res = $db->autoExecute($table_name, $fields_values,
                        DB_AUTOQUERY_INSERT);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

Using autoExecute() in update mode

<?php
// Once you have a valid DB object named $db...
$table_name = 'user';

$fields_values = array(
    'country' => 'France',
);

$res = $db->autoExecute($table_name, $fields_values,
                        DB_AUTOQUERY_UPDATE, "country = 'Japan'");

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

See

"Intro - Prepare & Execute",

"Intro - autoPrepare & autoExecute",

prepare(),

execute(),

executeMultiple(),

autoPrepare()

Prev | DB | Next
DB_common::autoCommit() | PEAR Manual | DB_common::autoPrepare()


DB_common::autoPrepare()

DB_common::autoPrepare()

DB_common::autoPrepare() – Prepares an INSERT or UPDATE statement based on variables you supply

Synopsis

resource autoPrepare ( string $table , array $table_fields , integer $mode = DB_AUTOQUERY_INSERT , string $where = false )

Description

Automatically builds an INSERT or UPDATE SQL statement so it can later be used by execute() or executeMultiple().

Parameter

string $table

name of the table

array $table_fields

ordered array containing the fields names

Be aware that these fields are assigned ? placeholders, therefore the data you pass to them in the execute() will be automatically escaped and quoted according to the current DBMS's requirements.

integer $mode

type of query to make (DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE)

string $where

a string to be used in the WHERE clause. This is only used when $mode is DB_AUTOQUERY_UPDATE. The string is put directly into the query, so you must escape and quote literals according to the DBMS's standards.

Return value

resource - resource handle for the query or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NEED_MORE_DATA | insufficient data supplied | The ordered array, which has to contain fields names, is empty. | Check and correct your fields names array.
DB_ERROR_SYNTAX | syntax error | You use an unknown mode. | Available modes are only DB_AUTOQUERY_INSERT for INSERT queries or DB_AUTOQUERY_UPDATE for UPDATE queries.
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error.

Note

This function can not be called statically.

Example

Using autoPrepare() in insert mode

<?php

// Once you have a valid DB object named $db...

$table_name   = 'user';

$table_fields = array('name', 'country');

$table_values = array('Zoe', 'France');

$sth = $db->autoPrepare($table_name, $table_fields,

                        DB_AUTOQUERY_INSERT);

if (PEAR::isError($sth)) {

    die($sth->getMessage());

}

$res =& $db->execute($sth, $table_values);

if (PEAR::isError($res)) {

    die($res->getMessage());

}

?>

Using autoPrepare() in update mode

<?php

// Once you have a valid DB object named $db...

$table_name   = 'user';

$table_fields = array('name', 'country');

$table_values = array('Bob', 'USA');

$sth = $db->autoPrepare($table_name, $table_fields,

                        DB_AUTOQUERY_UPDATE, "country = 'Japan'");

if (PEAR::isError($sth)) {

    die($sth->getMessage());

}

$res =& $db->execute($sth, $table_values);

if (PEAR::isError($res)) {

    die($res->getMessage());

}

?>

See

"Intro - Prepare & Execute",

"Intro - autoPrepare & autoExecute",

prepare(),

execute(),

executeMultiple(),

autoExecute()

Prev | DB | Next
DB_common::autoExecute() | PEAR Manual | DB_common::commit()


DB_common::commit()

DB_common::commit()

DB_common::commit() – Commits the current transaction

Synopsis

mixed commit ( )

Description

Commits the current transaction.

Return value

integer - DB_OK on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error.

Note

This function can not be called statically.

When using MySQL as your DBMS, transactions can only be used when the tables in question use the InnoDB format.

Example

Using commit()

<?php
// Once you have a valid DB object named $db...

$db->autoCommit(false);

$db->query('CREATE TABLE blah (a integer)');
$db->commit();

$db->query('INSERT INTO blah (a) VALUES (11)');

$res =& $db->query('SELECT a FROM blah');
if (DB::isError($res)) {
    echo $res->getMessage() . "\n";
}
while ($res->fetchInto($row, DB_FETCHMODE_ORDERED)) {
    echo $row[0] . "\n";
}
$res->free();

$db->query('DROP TABLE blah');
$db->commit();
?>

See

rollback(), autoCommit()

Prev | DB | Next
DB_common::autoPrepare() | PEAR Manual | DB_common::createSequence()


DB_common::createSequence()

DB_common::createSequence()

DB_common::createSequence() – Creates a new sequence

Synopsis

integer createSequence ( string $seq_name )

Description

See "Intro - Sequences"

Parameter

string $seq_name

name of the new sequence to create

To avoid problems with various database systems, sequence names should start with a letter and only contain letters, numbers and the underscore character.

Return value

integer - DB_OK or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every error code |  | Database specific error | Check the name of the sequence. If correct, probably a bug in the sequence implementation

Note

This function can not be called statically.

When using PEAR DB's sequence methods, we strongly advise using these methods for all procedures, including the creation of the sequences. Do not use PEAR DB's methods to access sequences that were created directly in the DBMS. See the warning on the "Intro - Sequences" page complete information.

Example

Using createSequence()

<?php
// Once you have a valid DB object named $db...
$tmp = $db->createSequence('mySequence');

if (PEAR::isError($tmp)) {
    die($tmp->getMessage());
}
?>

See

"Intro - Sequences", nextId(), dropSequence()

Prev | DB | Next
DB_common::commit() | PEAR Manual | DB_common::disconnect()


DB_common::disconnect()

DB_common::disconnect()

DB_common::disconnect() – Disconnects from a database

Synopsis

boolean disconnect ( )

Description

Disconnects from a database

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Example

Using disconnect()

<?php
require_once 'DB.php';

$db =& DB::connect('pgsql://someuser:apasswd@localhost/thedb');
if (PEAR::isError($db)) {
    die($db->getMessage());
}

$db->disconnect();
?>

See

connect(), "Intro - Connect"

Prev | DB | Next
DB_common::createSequence() | PEAR Manual | DB_common::dropSequence()


DB_common::dropSequence()

DB_common::dropSequence()

DB_common::dropSequence() – Deletes a sequence

Synopsis

integer dropSequence ( string $seqName )

Description

See "Intro - Sequences"

Parameter

string $seqName

name of the sequence to delete

Return value

integer - DB_OK or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every error code |  | Database specific error | Check the name of the sequence. If correct, probably a bug in the sequence implementation.

Note

This function can not be called statically.

When using PEAR DB's sequence methods, we strongly advise using these methods for all procedures, including the creation of the sequences. Do not use PEAR DB's methods to access sequences that were created directly in the DBMS. See the warning on the "Intro - Sequences" page complete information.

Example

Using dropSequence()

<?php
// Once you have a valid DB object named $db...
$tmp = $db->dropSequence('mySequence');

if (PEAR::isError($tmp)) {
    die($tmp->getMessage());
}
?>

See

"Intro - Sequences", createSequence(), nextId()

Prev | DB | Next
DB_common::disconnect() | PEAR Manual | DB_common::escapeSimple()


DB_common::escapeSimple()

DB_common::escapeSimple()

DB_common::escapeSimple() – Escapes a string according to the current DBMS's standards

Synopsis

string escapeSimple ( string $str )

Description

Escape a string according to the current DBMS's standards.

Parameter

string $str

the input to be escaped

Return value

string - the escaped string

Note

This function can not be called statically.

Function available since: Release 1.6.0

Example

Using escapeSimple()

<?php
// Once you have a valid DB object named $db...
$name = "all's well";
$sql  = "SELECT * FROM clients WHERE name = '"
        . $db->escapeSimple($name) . "'";

$res =& $db->query($sql);
?>

See

quoteIdentifier(), quoteSmart()

Prev | DB | Next
DB_common::dropSequence() | PEAR Manual | DB_common::execute()


DB_common::execute()

DB_common::execute()

DB_common::execute() – Executes a prepared SQL statement

Synopsis

mixed &execute ( resource $stmt , mixed $data = array() )

Description

Merges the SQL statement you submitted to prepare() with the information in $data and then sends the query to the database.

Parameter

resource $stmt

query handle from prepare()

mixed $data

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

Return value

mixed - a new DB_result object for queries that return results (such as SELECT queries), DB_OK for queries that manipulate data (such as INSERT queries) or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement handle is not valid. | Check correct processing of the SQL statement with prepare(). Note that execute() requires a handle to the statement returned by prepare(), not the statement itself.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statment for an Oracle database.

Note

This function can not be called statically.

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement.

Example

Passing a scalar to execute()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers (number) VALUES (?)');
if (PEAR::isError($sth)) {
    die($sth->getMessage());
}

$res =& $db->execute($sth, 1);
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

Passing an array to execute()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers VALUES (?, ?, ?)');

$data = array(1, 'one', 'en');
$db->execute($sth, $data);
?>

See

"Intro - Prepare & Execute", "Intro - autoPrepare & autoExecute", prepare(), executeMultiple()

Prev | DB | Next
DB_common::escapeSimple() | PEAR Manual | DB_common::executeMultiple()


DB_common::executeMultiple()

DB_common::executeMultiple()

DB_common::executeMultiple() – Runs a prepared SQL statement for each element of an array

Synopsis

integer executeMultiple ( resource $stmt , array $data )

Description

Automatically passes the information in $data (a multi-dimensional array) to execute(), which then runs the SQL statement you submitted to prepare().

Parameter

resource $stmt

query handle from prepare()

array $data

a numeric array containing the data to insert into the query

Return value

integer - DB_OK on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement handle is not valid. | Check correct processing of the SQL statement with prepare(). Note that executeMultiple() requires a handle to the statement returned by prepare(), not the statement itself.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

If an error occurs during execution, the function will be stopped. Possible remaining data will be unprocessed.

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement.

Example

Using executeMultiple()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers VALUES (?, ?, ?)');

if (PEAR::isError($sth)) {
    die($sth->getMessage());
}

$alldata = array(array(1, 'one', 'en'),
                 array(2, 'two', 'to'),
                 array(3, 'three', 'tre'),
                 array(4, 'four', 'fire'));

$res =& $db->executeMultiple($sth, $alldata);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

See

"Intro - Prepare & Execute",

"Intro - autoPrepare & autoExecute",

prepare(),

execute(),

autoPrepare(),

autoExecute()

Prev | DB | Next
DB_common::execute() | PEAR Manual | DB_common::freePrepared()


DB_common::freePrepared()

DB_common::freePrepared()

DB_common::freePrepared() – Releases resources associated with a prepared SQL statement

Synopsis

boolean freePrepared ( resource $stmt , boolean $free_resource = true )

Description

Removes the memory occupied by the internal notations that keep track of prepared SQL statements. Does not delete the DB_result object itself.

Parameter

resource $stmt

statement resource identifier returned from prepare()

boolean $free_resource

should the PHP resource be freed too? Use false if you need to get data from the result set later.

Parameter available since Release 1.7.0.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Example

Using freePrepared()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers (number) VALUES (?)');
$db->execute($sth, 1);
$db->freePrepared($sth);
?>

See

prepare(),

autoPrepare(),

free()

Prev | DB | Next
DB_common::executeMultiple() | PEAR Manual | DB_common::getAll()


DB_common::getAll()

DB_common::getAll()

DB_common::getAll() – Runs a query and returns all the data as an array

Synopsis

array &getAll ( string $query , array $params = array() , integer $fetchmode = DB_FETCHMODE_DEFAULT )

Description

Runs the query provided and puts the entire result set into a nested array then frees the result set.

Parameter

string $query

the SQL query or the statement to prepare

array $params

array to be used in execution of the statement. Quantity of array elements must match quantity of placeholders in query.

If supplied, prepare()/ execute() is used.

This method does not allow scalars to be used for this argument.

integer $fetchmode

the fetch mode to use. The default is DB_FETCHMODE_DEFAULT, which tells this method to use DB's current fetch mode. The current fetch mode can be changed using setFetchMode(). Potential values include:

  • DB_FETCHMODE_ORDERED

  • DB_FETCHMODE_ASSOC

  • DB_FETCHMODE_OBJECT

  • DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED

  • DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED

Return value

array - a nested array or a DB_Error on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statemt using placeholders.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Example

Using getAll() to return an associative array by setting the default fetch mode first

<?php

// Once you have a valid DB object named $db...

$db->setFetchMode(DB_FETCHMODE_ASSOC);

$data =& $db->getAll('SELECT cf, nf, df FROM foo');

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => Array

        (

            [cf] => Juan

            [nf] => 5

            [df] => 1991-01-11 21:31:41

        )

    [1] => Array

        (

            [cf] => Kyu

            [nf] => 10

            [df] => 1992-02-12 22:32:42

        )

)

Using getAll() to return an ordered array

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAll('SELECT cf, nf, df FROM foo',

        array(), DB_FETCHMODE_ORDERED);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => Array

        (

            [0] => Juan

            [1] => 5

            [2] => 1991-01-11 21:31:41

        )

    [1] => Array

        (

            [0] => Kyu

            [1] => 10

            [2] => 1992-02-12 22:32:42

        )

)

Using getAll() to return a flipped ordered array

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAll('SELECT cf, nf, df FROM foo',

        array(), DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => Array

        (

            [0] => Juan

            [1] => Kyu

        )

    [1] => Array

        (

            [0] => 5

            [1] => 10

        )

    [2] => Array

        (

            [0] => 1991-01-11 21:31:41

            [1] => 1992-02-12 22:32:42

        )

)

Using getAll() to return an associative array

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAll('SELECT cf, nf, df FROM foo',

        array(), DB_FETCHMODE_ASSOC);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => Array

        (

            [cf] => Juan

            [nf] => 5

            [df] => 1991-01-11 21:31:41

        )

    [1] => Array

        (

            [cf] => Kyu

            [nf] => 10

            [df] => 1992-02-12 22:32:42

        )

)

Using getAll() to return a flipped associative array

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAll('SELECT cf, nf, df FROM foo',

        array(), DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [cf] => Array

        (

            [0] => Juan

            [1] => Kyu

        )

    [nf] => Array

        (

            [0] => 5

            [1] => 10

        )

    [df] => Array

        (

            [0] => 1991-01-11 21:31:41

            [1] => 1992-02-12 22:32:42

        )

)

Using getAll() to return an array of objects

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAll('SELECT cf, nf, df FROM foo',

        array(), DB_FETCHMODE_OBJECT);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => stdClass Object

        (

            [cf] => Juan

            [nf] => 5

            [df] => 1991-01-11 21:31:41

        )

    [1] => stdClass Object

        (

            [cf] => Kyu

            [nf] => 10

            [df] => 1992-02-12 22:32:42

        )

)

Using getAll() in prepare/execute mode to return an associative array

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAll('SELECT cf, nf, df FROM foo WHERE nf = ?',

        array(5), DB_FETCHMODE_ASSOC);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => Array

        (

            [cf] => Juan

            [nf] => 5

            [df] => 1991-01-11 21:31:41

        )

)

See

setFetchMode(),

getOne(),

getRow(),

getCol(),

getAssoc(),

query(),

"Intro - Prepare & Execute"

Prev | DB | Next
DB_common::freePrepared() | PEAR Manual | DB_common::getAssoc()


DB_common::getAssoc()

DB_common::getAssoc()

DB_common::getAssoc() – Runs a query and returns the data as an array

Synopsis

array &getAssoc ( string $query , boolean $force_array = false , mixed $params = array() , integer $fetchmode = DB_FETCHMODE_DEFAULT , boolean $group = false )

Description

Runs the query provided and puts the entire result set into an associative array then frees the result set.

If the result set contains more than two columns, the value will be an array of the values from column 2 to n. If the result set contains only two columns, the returned value will be a scalar with the value of the second column (unless forced to an array with the $force_array parameter).

Parameter

string $query

the SQL query or the statement to prepare

boolean $force_array

used only if the query returns exactly two columns. If TRUE, the values of the returned array will be one-element arrays instead of scalars.

mixed $params

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

If supplied, prepare()/ execute() is used.

integer $fetchmode

the fetch mode to use. The default is DB_FETCHMODE_DEFAULT, which tells this method to use DB's current fetch mode. DB's current default fetch mode can be changed using setFetchMode(). Potential values include:

  • DB_FETCHMODE_ORDERED

  • DB_FETCHMODE_ASSOC

  • DB_FETCHMODE_OBJECT

boolean $group

if TRUE, the values of the returned array is wrapped in another array. If the same key value (in the first column) repeats itself, the values will be appended to this array instead of overwriting the existing values.

Return value

array - associative array with the query results or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statemt using placeholders.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
DB_ERROR_TRUNCATED | truncated | The result set contains fewer then two columns | Check the SQL query or choose another get*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Example

All of the examples use the following data set:

INSERT INTO foo VALUES ('Juan', 5, '1991-01-11 21:31:41');

INSERT INTO foo VALUES ('Kyu', 10, '1992-02-12 22:32:42');

INSERT INTO foo VALUES ('Kyu', 15, '1993-03-13 23:33:43');

Result sets having two columns

When using getAssoc() for results which have two columns and $force_array = FALSE (the default) changing $fetchmode has no impact on the format of the resulting array.

Using getAssoc() in default mode

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo');

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => 1991-01-11 21:31:41

    [Kyu] => 1993-03-13 23:33:43

)

Using getAssoc() with $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        false, array(), DB_FETCHMODE_ORDERED, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => 1991-01-11 21:31:41

        )

    [Kyu] => Array

        (

            [0] => 1992-02-12 22:32:42

            [1] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $force_array = TRUE and $fetchmode = DB_FETCHMODE_ORDERED

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        true, array(), DB_FETCHMODE_ORDERED);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => 1991-01-11 21:31:41

        )

    [Kyu] => Array

        (

            [0] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $force_array = TRUE and $fetchmode = DB_FETCHMODE_ASSOC

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        true, array(), DB_FETCHMODE_ASSOC);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [df] => 1991-01-11 21:31:41

        )

    [Kyu] => Array

        (

            [df] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $force_array = TRUE and $fetchmode = DB_FETCHMODE_OBJECT

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        true, array(), DB_FETCHMODE_OBJECT);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => stdClass Object

        (

            [cf] => Juan

            [df] => 1991-01-11 21:31:41

        )

    [Kyu] => stdClass Object

        (

            [cf] => Kyu

            [df] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $force_array = TRUE, $fetchmode = DB_FETCHMODE_ORDERED and $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        true, array(), DB_FETCHMODE_ORDERED, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => Array

                (

                    [0] => 1991-01-11 21:31:41

                )

        )

    [Kyu] => Array

        (

            [0] => Array

                (

                    [0] => 1992-02-12 22:32:42

                )

            [1] => Array

                (

                    [0] => 1993-03-13 23:33:43

                )

        )

)

Using getAssoc() with $force_array = TRUE, $fetchmode = DB_FETCHMODE_ASSOC and $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        true, array(), DB_FETCHMODE_ASSOC, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => Array

                (

                    [df] => 1991-01-11 21:31:41

                )

        )

    [Kyu] => Array

        (

            [0] => Array

                (

                    [df] => 1992-02-12 22:32:42

                )

            [1] => Array

                (

                    [df] => 1993-03-13 23:33:43

                )

        )

)

Using getAssoc() with $force_array = TRUE, $fetchmode = DB_FETCHMODE_OBJECT and $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo',

        true, array(), DB_FETCHMODE_OBJECT, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => stdClass Object

                (

                    [cf] => Juan

                    [df] => 1991-01-11 21:31:41

                )

        )

    [Kyu] => Array

        (

            [0] => stdClass Object

                (

                    [cf] => Kyu

                    [df] => 1992-02-12 22:32:42

                )

            [1] => stdClass Object

                (

                    [cf] => Kyu

                    [df] => 1993-03-13 23:33:43

                )

        )

)

Result sets having more than two columns

Using getAssoc() with $fetchmode = DB_FETCHMODE_ORDERED

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',

        false, array(), DB_FETCHMODE_ORDERED);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => 5

            [1] => 1991-01-11 21:31:41

        )

    [Kyu] => Array

        (

            [0] => 15

            [1] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $fetchmode = DB_FETCHMODE_ASSOC

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',

        false, array(), DB_FETCHMODE_ASSOC);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [nf] => 5

            [df] => 1991-01-11 21:31:41

        )

    [Kyu] => Array

        (

            [nf] => 15

            [df] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $fetchmode = DB_FETCHMODE_OBJECT

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',

        false, array(), DB_FETCHMODE_OBJECT);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => stdClass Object

        (

            [cf] => Juan

            [nf] => 5

            [df] => 1991-01-11 21:31:41

        )

    [Kyu] => stdClass Object

        (

            [cf] => Kyu

            [nf] => 15

            [df] => 1993-03-13 23:33:43

        )

)

Using getAssoc() with $fetchmode = DB_FETCHMODE_ORDERED and $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',

        false, array(), DB_FETCHMODE_ORDERED, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => Array

                (

                    [0] => 5

                    [1] => 1991-01-11 21:31:41

                )

        )

    [Kyu] => Array

        (

            [0] => Array

                (

                    [0] => 10

                    [1] => 1992-02-12 22:32:42

                )

            [1] => Array

                (

                    [0] => 15

                    [1] => 1993-03-13 23:33:43

                )

        )

)

Using getAssoc() with $fetchmode = DB_FETCHMODE_ASSOC and $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',

        false, array(), DB_FETCHMODE_ASSOC, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => Array

                (

                    [nf] => 5

                    [df] => 1991-01-11 21:31:41

                )

        )

    [Kyu] => Array

        (

            [0] => Array

                (

                    [nf] => 10

                    [df] => 1992-02-12 22:32:42

                )

            [1] => Array

                (

                    [nf] => 15

                    [df] => 1993-03-13 23:33:43

                )

        )

)

Using getAssoc() with $fetchmode = DB_FETCHMODE_OBJECT and $group = TRUE

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, nf, df FROM foo',

        false, array(), DB_FETCHMODE_OBJECT, true);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [Juan] => Array

        (

            [0] => stdClass Object

                (

                    [cf] => Juan

                    [nf] => 5

                    [df] => 1991-01-11 21:31:41

                )

        )

    [Kyu] => Array

        (

            [0] => stdClass Object

                (

                    [cf] => Kyu

                    [nf] => 10

                    [df] => 1992-02-12 22:32:42

                )

            [1] => stdClass Object

                (

                    [cf] => Kyu

                    [nf] => 15

                    [df] => 1993-03-13 23:33:43

                )

        )

)

Prepare / Execute Mode

Using getAssoc() with one placeholder

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo WHERE nf = ?',

        false, 5);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

?>

Using getAssoc() with two placeholders

<?php

// Once you have a valid DB object named $db...

$data =& $db->getAssoc('SELECT cf, df FROM foo WHERE nf IN (?, ?)',

        false, array(5, 10));

if (PEAR::isError($data)) {

    die($data->getMessage());

}

?>

See

setFetchMode(),

getOne(),

getRow(),

getCol(),

getAll(),

query(),

"Intro - Prepare & Execute"

Prev | DB | Next
DB_common::getAll() | PEAR Manual | DB_common::getCol()


DB_common::getCol()

DB_common::getCol()

DB_common::getCol() – Runs a query and returns the data from a single column

Synopsis

array &getCol ( string $query , mixed $col = 0 , mixed $params = array() )

Description

Runs the query provided and puts the first column of data into an array then frees the result set.

Parameter

string $query

the SQL query or the statement to prepare

mixed $col

which column to return (integer [column number, starting at 0] or string [column name])

mixed $params

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

If supplied, prepare()/ execute() is used.

Return value

array - an ordered array containing data from a result set column or a DB_Error object on failure. The array's index starts at 0.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statemt using placeholders.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NOSUCHFIELD | no such field | Invalid column number/name passed to $col | Use a column number or name that exists in the query result.
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP Manual to detect the reason for this error. In most cases a malformed SQL statement is the cause of the error. (Ie. using LIMIT in a SQL-Statement for an Oracle database.)

Note

This function can not be called statically.

Example

Using getCol()

<?php
// Once you have a valid DB object named $db...
$data =& $db->getCol('SELECT cf, df FROM foo');

if (PEAR::isError($data)) {
    die($data->getMessage());
}

print_r($data);
?>

Output:

Array
(
    [0] => Juan
    [1] => Kyu
)

Using getCol() to retrieve a numerically specified column

<?php
// Once you have a valid DB object named $db...
$data =& $db->getCol('SELECT cf, df FROM foo', 1);

if (PEAR::isError($data)) {
    die($data->getMessage());
}

print_r($data);
?>

Output:

Array
(
    [0] => 1991-01-11 21:31:41
    [1] => 1992-02-12 22:32:42
)

Using getCol() to retrieve a named column

<?php
// Once you have a valid DB object named $db...
$data =& $db->getCol('SELECT cf, df FROM foo', 'df');

if (PEAR::isError($data)) {
    die($data->getMessage());
}

print_r($data);
?>

Output:

Array
(
    [0] => 1991-01-11 21:31:41
    [1] => 1992-02-12 22:32:42
)

Using getCol() in prepare/execute mode with one placeholder

<?php
// Once you have a valid DB object named $db...
$data =& $db->getCol('SELECT cf, df FROM foo WHERE nf = ?',
        'df', 5);

if (PEAR::isError($data)) {
    die($data->getMessage());
}

print_r($data);
?>

Output:

Array
(
    [0] => 1991-01-11 21:31:41
)

Using getCol() in prepare/execute mode with two placeholders

<?php
// Once you have a valid DB object named $db...
$data =& $db->getCol('SELECT cf, df FROM foo WHERE nf IN (?, ?)',
        'df', array(5, 10));

if (PEAR::isError($data)) {
    die($data->getMessage());
}

print_r($data);
?>

Output:

Array
(
    [0] => 1991-01-11 21:31:41
    [1] => 1992-02-12 22:32:42
)

See

getOne(),

getRow(),

getAssoc(),

getAll(),

query(),

"Intro - Prepare & Execute"

Prev | DB | Next
DB_common::getAssoc() | PEAR Manual | DB_common::getListOf()


DB_common::getListOf()

DB_common::getListOf()

DB_common::getListOf() – Views database system information

Synopsis

array getListOf ( string $type )

Description

Retrieves information about database users, avaible databases, views and functions.

Parameter

string $type

type of requested info, valid values for $type are database dependent, ie: tables, databases, users, view, functions

Return value

array - an ordered array containing the requested data or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_UNSUPPORTED | not supported | The requested information is not avaible. | Check your user permissions and the database system for support quering the requested information.

Note

This function can not be called statically.

Example

Using getListOf()

<?php
// Once you have a valid DB object named $db...
$data = $db->getListOf('tables');

if (PEAR::isError($data)) {
    die($data->getMessage());
}

echo implode("\n", $data);
?>
Prev | DB | Next
DB_common::getCol() | PEAR Manual | DB_common::getOne()


DB_common::getOne()

DB_common::getOne()

DB_common::getOne() – Runs a query and returns the first column of the first row

Synopsis

mixed &getOne ( string $query , mixed $params = array() )

Description

Runs the query provided and returns the data from the first column of the first row then frees the result set.

Parameter

string $query

the SQL query or the statement to prepare

mixed $params

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

If supplied, prepare()/ execute() is used.

Return value

mixed - the first column's data, NULL if there is no data, or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statemt using placeholders.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Example

Using getOne()

<?php
// Once you have a valid DB object named $db...
$data =& $db->getOne('SELECT cf FROM foo');

if (PEAR::isError($data)) {
    die($data->getMessage());
}

echo "$data\n";
?>

Using getOne() with one placeholder

<?php
// Once you have a valid DB object named $db...
$data =& $db->getOne('SELECT cf FROM foo WHERE nf = ?',
        5);

if (PEAR::isError($data)) {
    die($data->getMessage());
}

echo "$data\n";
?>

Using getOne() with two placeholders

<?php
// Once you have a valid DB object named $db...
$data =& $db->getOne('SELECT cf FROM foo WHERE nf IN (?, ?)',
        array(5, 10));

if (PEAR::isError($data)) {
    die($data->getMessage());
}

echo "$data\n";
?>

See

getRow(),

getCol(),

getAssoc(),

getAll(),

query(),

"Intro - Prepare & Execute"

Prev | DB | Next
DB_common::getListOf() | PEAR Manual | DB_common::getOption()


DB_common::getOption()

DB_common::getOption()

DB_common::getOption() – Determines current state of a PEAR DB configuration option

Synopsis

mixed getOption ( string $option )

Description

Determines current state of a PEAR DB configuration option

Parameter

string $option

name of the option to examine

Return value

mixed the option's value

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | unknown option | The given option does not exist | Check $option for typographical errors

Note

This function can not be called statically.

Example

Simple getOption() example

<?php
// Once you have a valid DB object named $db...
if ($db->getOption('autofree')) {
    // do something...
}
?>
Prev | DB | Next
DB_common::getOne() | PEAR Manual | DB_common::getRow()


DB_common::getRow()

DB_common::getRow()

DB_common::getRow() – Runs a query and returns the first row

Synopsis

array &getRow ( string $query , array $params = array() , integer $fetchmode = DB_FETCHMODE_DEFAULT )

Description

Runs the query provided and puts the first row of data into an array then frees the result set.

Parameter

string $query

the SQL query or the statement to prepare

array $params

array to be used in execution of the statement. Quantity of array elements must match quantity of placeholders in query.

If supplied, prepare()/ execute() is used.

This method does not allow scalars to be used for this argument.

integer $fetchmode

the fetch mode to use. The default is DB_FETCHMODE_DEFAULT, which tells this method to use DB's current fetch mode. DB's current default fetch mode can be changed using setFetchMode(). Potential values include:

  • DB_FETCHMODE_ORDERED

  • DB_FETCHMODE_ASSOC

  • DB_FETCHMODE_OBJECT

Return value

array - the first row's data in an array or a DB_Error object on failure. The array may be ordered or associative depending on $fetchmode . The column index starts at 0 for ordered arrays.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statemt using placeholders.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Example

Using getRow() with $fetchmode = DB_FETCHMODE_ORDERED

<?php

// Once you have a valid DB object named $db...

$data =& $db->getRow('SELECT cf, df FROM foo',

        array(), DB_FETCHMODE_ORDERED);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [0] => Juan

    [1] => 1991-01-11 21:31:41

)

Using getRow() with $fetchmode = DB_FETCHMODE_ASSOC

<?php

// Once you have a valid DB object named $db...

$data =& $db->getRow('SELECT cf, df FROM foo',

        array(), DB_FETCHMODE_ASSOC);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

Array

(

    [cf] => Juan

    [df] => 1991-01-11 21:31:41

)

Using getRow() with $fetchmode = DB_FETCHMODE_OBJECT

<?php

// Once you have a valid DB object named $db...

$data =& $db->getRow('SELECT cf, df FROM foo',

        array(), DB_FETCHMODE_OBJECT);

if (PEAR::isError($data)) {

    die($data->getMessage());

}

print_r($data);

?>

Output:

stdClass Object

(

    [cf] => Juan

    [df] => 1991-01-11 21:31:41

)

Using getRow() with one placeholder

<?php

// Once you have a valid DB object named $db...

$data =& $db->getRow('SELECT cf, df FROM foo WHERE nf = ?',

        array(5));

if (PEAR::isError($data)) {

    die($data->getMessage());

}

?>

Using getRow() with two placeholders

<?php

// Once you have a valid DB object named $db...

$data =& $db->getRow('SELECT cf, df FROM foo WHERE nf IN (?, ?)',

        array(5, 10));

if (PEAR::isError($data)) {

    die($data->getMessage());

}

?>

See

setFetchMode(),

getOne(),

getCol(),

getAssoc(),

getAll(),

query(),

"Intro - Prepare & Execute"

Prev | DB | Next
DB_common::getOption() | PEAR Manual | DB_common::limitQuery()


DB_common::limitQuery()

DB_common::limitQuery()

DB_common::limitQuery() – Sends a LIMIT query to the database

Synopsis

mixed &limitQuery ( string $query , integer $from , integer $count , mixed $params = array() )

Description

Executes a SQL query, but fetches only the specificed count of rows. It is an emulation of the MySQL LIMIT option.

Parameter

string $query

the SQL query

integer $from

the row to start to fetch. Note that 0 returns the first row, 1 returns the second row, etc.

integer $count

the numbers of rows to fetch

mixed $params

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

Return value

mixed - a new DB_result object for queries that return results (such as SELECT queries), DB_OK for queries that manipulate data (such as INSERT queries) or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Depending on the database you will not really get more speed compared to query(). The advantage of limitQuery() is the deleting of unneeded rows in the resultset, as early as possible. So this can decrease memory usage.

Also note that $from and $count are not being escaped. You should take care of sanitizing input yourself, or you are open to an SQL injection attack.

Example

Using limitQuery()

<?php
// Once you have a valid DB object named $db...
$res =& $db->limitQuery('SELECT * FROM foo', 49, 10);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

See

query()

Prev | DB | Next
DB_common::getRow() | PEAR Manual | DB_common::nextId()


DB_common::nextId()

DB_common::nextId()

DB_common::nextId() – Returns the next number from a sequence

Synopsis

integer nextId ( string $seq_name , boolean $onDemand = true )

Description

Returns the next available number from a sequence. The sequence is automatically incremented each time this method is called.

See "Intro - Sequences" for a more complete discussion.

Parameter

string $seq_name

name of the sequence

To avoid problems with various database systems, sequence names should start with a letter and only contain letters, numbers and the underscore character.

boolean $onDemand

When TRUE, the sequence is automatically created if it does not exist yet.

The on demand creation process necessitates the database user specified in the script having the database permissions needed to create a table or sequence. The exact privileges required depends on the DBMS being used.

Return value

integer - a free id number or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NOT_CAPABLE | DB backend not capable | Function is not supported by the database backend | Switch to another database system, if you really need this feature.
DB_ERROR_NOT_LOCKED | not locked | Locking of sequence table fails | Database specific, check documentation of your database,
DB_ERROR_NOSUCHTABLE | no such table | Sequence table was not found | Try to create a new sequence or if you are sure, a sequence was already create, check database integrity

Note

This function can not be called statically.

When using PEAR DB's sequence methods, we strongly advise using these methods for all procedures, including the creation of the sequences. Do not use PEAR DB's methods to access sequences that were created directly in the DBMS. See the warning on the "Intro - Sequences" page complete information.

Example

Using nextId()

<?php
// Once you have a valid DB object named $db...
$id = $db->nextId('mySequence');
if (PEAR::isError($id)) {
    die($id->getMessage());
}

// Use the ID in your INSERT query
$res =& $db->query("INSERT INTO myTable (id, text) VALUES ($id, 'foo')");
?>

See

"Intro - Sequences", createSequence(), dropSequence()

Prev | DB | Next
DB_common::limitQuery() | PEAR Manual | DB_common::nextQueryIsManip()


DB_common::nextQueryIsManip()

DB_common::nextQueryIsManip()

DB_common::nextQueryIsManip() – Informs the DB driver that the next query is a manipulation query

Synopsis

void nextQueryIsManip ( boolean $manip )

Description

Informs the DB driver that the next query that is called will manipulate data within the database and will not return a result set, irrespective of the usual detection performed within DB.

Parameter

boolean $manip

When TRUE, the next query will always be treated as not returning a result set. When FALSE, the normal behaviour will be used, which will result in DB attempting to automatically detect whether the query will return a result set or not.

Return value

void - nothing is returned

Note

This function can not be called statically.

Prev | DB | Next
DB_common::nextId() | PEAR Manual | DB_common::prepare()


DB_common::prepare()

DB_common::prepare()

DB_common::prepare() – Prepares a SQL statement for later execution

Synopsis

resource prepare ( string $query )

Description

Gets a SQL statement ready so it can be run by execute().

Parameter

string $query

the query to prepare

Return value

resource - the query handle or a DB_Error object on failure

Note

This function can not be called statically.

Example

Using prepare()

<?php
// Once you have a valid DB object named $db...
$sth = $db->prepare('INSERT INTO numbers (number) VALUES (?)');
if (PEAR::isError($sth)) {
    die($sth->getMessage());
}

$res =& $db->execute($sth, 1);
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

See

"Intro - Prepare & Execute", "Intro - autoPrepare & autoExecute", execute(), executeMultiple()

Prev | DB | Next
DB_common::nextQueryIsManip() | PEAR Manual | DB_common::provides()


DB_common::provides()

DB_common::provides()

DB_common::provides() – Checks if the DBMS supports a particular feature

Synopsis

boolean provides ( string $feature )

Description

Checks if a feature is available for the chosen database type.

Parameter

string $feature

the feature to check

Possible values are:
$feature value | Meaning
prepare | The database does a pre-check of the SQL statement
pconnect | The database supports persistent connections
transactions | The database supports transactions
limit | The database supports LIMITed SELECT statements

Return value

boolean - TRUE if the feature is supported

Note

This function can not be called statically.

The provided information are only hints. Check the documentation of your database system for the real supported features. I.e. MySQL supports transactions, but not for every table type.

Example

Using provides()

<?php
// Once you have a valid DB object named $db...
if ($db->provides('pconnect')) {
    echo "Persistent connections are allowed.\n";
}
?>
Prev | DB | Next
DB_common::prepare() | PEAR Manual | DB_common::query()


DB_common::query()

DB_common::query()

DB_common::query() – Sends a query to the database

Synopsis

mixed &query ( string $query , mixed $params = array() )

Description

Runs a query

Can be used instead of prepare() and execute(), if you set the $params parameter and your query uses placeholders. See "Intro - Prepare & Execute" for more information on this mode.

Parameter

string $query

the SQL query or the statement to prepare

mixed $params

array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

Return value

mixed - a new DB_result object for queries that return results (such as SELECT queries), DB_OK for queries that manipulate data (such as INSERT queries) or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_INVALID | invalid | SQL statement for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statement using placeholders.
DB_ERROR_MISMATCH | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statement. | Check that the number of placeholders in the prepare() statement passed to $query equals the count of entries passed to $params .
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of the PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. I.e. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

"Intro - Prepare & Execute", limitQuery()

Prev | DB | Next
DB_common::provides() | PEAR Manual | DB_common::quote()


DB_common::quote()

DB_common::quote()

DB_common::quote() – DEPRECATED: Quotes a string

Synopsis

string quote ( string $string )

Description

Quotes a string database-dependent, so it can be safely used in a query

This method has been deprecated. Use quoteSmart() or escapeSimple() instead.

Parameter

string $string

the input string to quote

Return value

string - the quoted string.

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 1.6.0.

See

quoteSmart(),

escapeSimple(),

quoteIdentifier()

Prev | DB | Next
DB_common::query() | PEAR Manual | DB_common::quoteIdentifier()


DB_common::quoteIdentifier()

DB_common::quoteIdentifier()

DB_common::quoteIdentifier() – Formats a string so it can be safely used as an identifier

Synopsis

string quoteIdentifier ( string $str )

Description

Format input so it can be safely used as a delimited identifier in a query. Identifiers are objects such as table or column names.

The format returned depends on the database type being used.

Delimited identifiers are known to generally work correctly under the following drivers:

  • mssql
  • mysql
  • mysqli
  • oci8
  • odbc(access)
  • odbc(db2)
  • pgsql
  • sqlite
  • sybase

InterBase doesn't seem to be able to use delimited identifiers via PHP 4. They work fine under PHP 5.

Parameter

string $str

the input to be quoted

Return value

string - the formatted string

Note

This function can not be called statically.

Function available since: Release 1.6.0

Just because you CAN use delimited identifiers doesn't mean you SHOULD use them. In general, they end up causing way more problems than they solve.

Portability is broken by using the following characters inside delimited identifiers:

  • backtick (`) -- due to MySQL
  • double quote (") -- due to Oracle
  • brackets ([ or ]) -- due to Access

Example

Using quoteIdentifier()

<?php
// Once you have a valid DB object named $db...
$sql = 'SELECT ' . $db->quoteIdentifier('company name')
       . ', address FROM clients';

$res =& $db->query($sql);
?>

See

quoteSmart(), escapeSimple()

Prev | DB | Next
DB_common::quote() | PEAR Manual | DB_common::quoteSmart()


DB_common::quoteSmart()

DB_common::quoteSmart()

DB_common::quoteSmart() – Formats input so it can be safely used as a literal

Synopsis

mixed quoteSmart ( mixed $in )

Description

Format input so it can be safely used as a literal in a query. Literals are values such as strings or numbers which get utilized in places like WHERE, SET and VALUES clauses of SQL statements.

The format returned depends on the PHP data type of input and the database type being used.

Parameter

mixed $in

the input to be quoted

Return value

mixed - the formatted data

The format of the results depends on the input's PHP type:

  • input -> returns

  • NULL -> the string NULL

  • integer or float -> the unquoted number

  • boolean -> output depends on the driver in use

    Most drivers return integers: 1 if true or 0 if false. Some return strings: TRUE if true or FALSE if false. Finally one returns strings: T if true or F if false. Here is a list of each DBMS, the values returned and the suggested column type:

    • dbase -> T/F (Logical)

    • fbase -> TRUE/FALSE (BOOLEAN)

    • ibase -> 1/0 (SMALLINT) [1]

    • ifx -> 1/0 (SMALLINT) [1]

    • msql -> 1/0 (INTEGER)

    • mssql -> 1/0 (TINYINT)

    • mysql -> 1/0 (TINYINT(1))

    • mysqli -> 1/0 (TINYINT(1))

    • oci8 -> 1/0 (NUMBER(1))

    • odbc -> 1/0 (SMALLINT) [1]

    • pgsql -> TRUE/FALSE (BOOLEAN)

    • sqlite -> 1/0 (INTEGER)

    • sybase -> 1/0 (TINYINT)

    [1] Accommodate the lowest common denominator because not all versions of have BOOLEAN.

  • other (including strings and numeric strings) -> a string which has been escaped in a DBMS specific way (using escapeSimple()) and then surrounded by single quotes

Note

This function can not be called statically.

Function available since: Release 1.6.0

Example

Using quoteSmart()

<?php
// Once you have a valid DB object named $db...
$name   = "all's well";
$active = true;
$sql    = 'SELECT * FROM clients WHERE name = '
          . $db->quoteSmart($name)
          . ' AND active = '
          . $db->quoteSmart($active);

$res =& $db->query($sql);
?>

See

quoteIdentifier(), escapeSimple()

Prev | DB | Next
DB_common::quoteIdentifier() | PEAR Manual | DB_common::rollback()


DB_common::rollback()

DB_common::rollback()

DB_common::rollback() – Rolls back the current transaction

Synopsis

mixed rollback ( )

Description

Rolls back the current transaction.

Return value

integer - DB_OK on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error.

Note

This function can not be called statically.

When using MySQL as your DBMS, transactions can only be used when the tables in question use the InnoDB format.

Example

Using rollback()

<?php
// Once you have a valid DB object named $db...

$db->autoCommit(false);

$db->query('INSERT INTO blah (a) VALUES (11)');

$res =& $db->query('SELECT b FROM blue');
if (DB::isError($res)) {
    echo $res->getMessage() . "\n";
}
while ($res->fetchInto($row, DB_FETCHMODE_ORDERED)) {
    if ($row[0] == 'problem') {
        $db->rollback();
    }
}
$res->free();

$db->query('DROP TABLE blah');
$db->commit();
?>

See

commit(), autoCommit()

Prev | DB | Next
DB_common::quoteSmart() | PEAR Manual | DB_common::setFetchMode()


DB_common::setFetchMode()

DB_common::setFetchMode()

DB_common::setFetchMode() – Sets the default fetch mode

Synopsis

void setFetchMode ( integer $fetchmode , string $object_class = stdClass )

Description

Sets the default fetch mode used by fetch*() and get*() methods.

Parameter

integer $fetchmode

DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC or DB_FETCHMODE_OBJECT.

See the Examples section, below, for more information.

string $object_class

This parameter is for use when $fetchmode is set to DB_FETCHMODE_OBJECT.

You can set this parameter to DB_row, which then causes the resulting data to populate a new instance of a DB_row object.

Return value

void - nothing is returned on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | invalid fetchmode mode | The given fetch mode does not exists or is not implement in your DB version. | Check writing of the argument and your used version of DB.

Note

This function can not be called statically.

Example

DB_FETCHMODE_ORDERED (default)

Causes ordered arrays to be returned. The order is taken from the select statement.

<?php
// Once you have a valid DB object named $db...
$db->setFetchMode(DB_FETCHMODE_ORDERED);

$res =& $db->query('SELECT a, b FROM phptest WHERE a = 28');
$row =& $res->fetchRow();

print_r($row);
echo 'Column a is ' . $row[0];
?>

Output:

Array
(
    [0] => 28
    [1] => hi
)
Column a is 28

DB_FETCHMODE_ASSOC

Makes associative arrays, with the column names as the array keys.

<?php
// Once you have a valid DB object named $db...
$db->setFetchMode(DB_FETCHMODE_ASSOC);

$res =& $db->query('SELECT a, b FROM phptest WHERE a = 28');
$row =& $res->fetchRow();

print_r($row);
echo 'Column a is ' . $row['a'];
?>

Output:

Array
(
    [a] => 28
    [b] => hi
)
Column a is 28

DB_FETCHMODE_OBJECT

Returns objects with column names as properties.

<?php
// Once you have a valid DB object named $db...
$db->setFetchMode(DB_FETCHMODE_OBJECT);

$res =& $db->query('SELECT a, b FROM phptest WHERE a = 28');
$row =& $res->fetchRow();

print_r($row);
echo 'Column a is ' . $row->a;
?>

Output:

stdClass Object
(
    [a] => 28
    [b] => hi
)
Column a is 28

DB_FETCHMODE_OBJECT and DB_row

If setFetchMode()'s optional $object_class parameter is set to DB_row, DB_row objects are returned.

<?php
// Once you have a valid DB object named $db...
$db->setFetchMode(DB_FETCHMODE_OBJECT, 'DB_row');

$res =& $db->query('SELECT a, b FROM phptest WHERE a = 28');
$row =& $res->fetchRow();

print_r($row);
echo 'Column a is ' . $row->a;
?>

Output:

db_row Object
(
    [a] => 28
    [b] => hi
)
Column a is 28

DB_FETCHMODE_OBJECT with your own object in PHP 4

<?php
// Once you have a valid DB object named $db...

class SomeResult {
    function SomeResult($data) {
        foreach ($data as $key => $value) {
            $this->$key = $data[$key];
        }
    }
}

$db->setFetchMode(DB_FETCHMODE_OBJECT, 'SomeResult');

$res =& $db->query('SELECT a, b FROM phptest WHERE a = 28');
$row =& $res->fetchRow();

print_r($row);
echo 'Column a is ' . $row->a;
?>

Output:

SomeResult Object
(
    [a] => 28
    [b] => hi
)
Column a is 28

DB_FETCHMODE_OBJECT with your own object in PHP 5

<?php
// Once you have a valid DB object named $db...

class SomeResult {
    public $row_data;
    function __construct($data) {
        $this->row_data = $data;
    }
    function __get($variable) {
        return $this->row_data[$variable];
    }
}

$db->setFetchMode(DB_FETCHMODE_OBJECT, 'SomeResult');

$res =& $db->query('SELECT a, b FROM phptest WHERE a = 28');
$row =& $res->fetchRow();

print_r($row);
echo 'Column a is ' . $row->a;
?>

Output:

SomeResult Object
(
    [a] => 28
    [b] => hi
)
Column a is 28

Prev | DB | Next
DB_common::rollback() | PEAR Manual | DB_common::setOption()


DB_common::setOption()

DB_common::setOption()

DB_common::setOption() – Sets run-time configuration options for PEAR DB

Synopsis

integer setOption ( string $option , mixed $value )

Description

Sets run-time configuration options for PEAR DB.

Parameter

string $option

name of the option to set

mixed $value

value to set the option to

Option | Data Type | Default Value | Description
autofree | boolean | FALSE | should results be freed automatically when there are no more rows?
debug | integer | 0 | debug level
persistent | boolean | FALSE | should the connection be persistent?
portability | integer | DB_PORTABILITY_NONE | portability mode constant. These constants are bitwised, so they can be combined using | and removed using ^. See the examples below and the "Intro - Portability" for more information.
seqname_format | string | %s_seq | the sprintf() format string used on sequence names. This format is applied to sequence names passed to createSequence(), nextID() and dropSequence().
ssl | boolean | FALSE | use ssl to connect?

Return value

integer - DB_OK on success or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | unknown option | The given option does not exist | Check $option for typographical errors

Note

This function can not be called statically.

Example

Simple setOption() example

<?php
// Once you have a valid DB object named $db...
$db->setOption('autofree', true);
?>

Portability for lowercasing and trimming

<?php
// Once you have a valid DB object named $db...
$db->setOption('portability',
    DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
?>

All portability options except trimming

<?php
// Once you have a valid DB object named $db...
$db->setOption('portability',
    DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
?>
Prev | DB | Next
DB_common::setFetchMode() | PEAR Manual | DB_common::tableInfo()


DB_common::tableInfo()

DB_common::tableInfo()

DB_common::tableInfo() – Gets info about columns in a table or a query result

Synopsis

array tableInfo ( mixed $result , integer $mode = null )

Description

Get information about columns in a table or a query result.

Parameter

mixed $result

DB_result object from a query or a string containing the name of a table

If the name of the table needs to be delimited (ie: the name is a reserved word or has spaces in it), use the quoteIdentifier() method on the table name when passing it.

This can also be a query result resource identifier, but doing so is deprecated.

integer $mode

one of the tableInfo mode constants

Return value

array - an associative array of the table's information or a DB_Error object on failure

The array's contents depends on the $mode parameter.

The names of tables and columns will be lowercased if the DB_PORTABILITY_LOWERCASE portability mode is enabled.

The flags element contains a space separated list of extra information about the column. If the DBMS is able to report a column's default value, the value is passed through rawurlencode() to avoid problems caused by potential spaces in the value.

Most DBMS's only provide the table and flags elements if $result is a table name. Only fbsql and mysql provide full information from queries.

The type element contains the type returned by the DBMS. It varies from DBMS to DBMS.

tableInfo Modes

This section describes the format of the returned array and how it varies depending on which $mode was used when the function was called.

The sample output below is based on this query:

SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
  FROM tblFoo
  JOIN tblBar ON tblFoo.fldId = tblBar.fldId;

NULL or 0

[0] => Array (
[table] => tblFoo
[name] => fldId
[type] => int
[len] => 11
[flags] => primary_key not_null
)
[1] => Array (
[table] => tblFoo
[name] => fldPhone
[type] => string
[len] => 20
[flags] =>
)
[2] => Array (
[table] => tblBar
[name] => fldId
[type] => int
[len] => 11
[flags] => primary_key not_null
)
DB_TABLEINFO_ORDER

In addition to the information found in the default output, a notation of the number of columns is provided by the num_fields element while the order element provides an array with the column names as the keys and their location index number (corresponding to the keys in the default output) as the values.

If a result set has identical field names, the last one is used.

[num_fields] => 3
[order] => Array (
[fldId] => 2
[fldTrans] => 1
)
DB_TABLEINFO_ORDERTABLE

Similar to DB_TABLEINFO_ORDER but adds more dimensions to the array in which the table names are keys and the field names are sub-keys. This is helpful for queries that join tables which have identical field names.

[num_fields] => 3
[ordertable] => Array (
[tblFoo] => Array (
[fldId] => 0
[fldPhone] => 1
)
[tblBar] => Array (
[fldId] => 2
)
)
DB_TABLEINFO_FULL

Contains the information from both DB_TABLEINFO_ORDER and DB_TABLEINFO_ORDERTABLE

The tableInfo mode constants are bitwised, so they can be combined using |.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NOT_CAPABLE | DB backend not capable | Driver doesn't support this feature. | Switch to another database system, if you really need this feature.
DB_ERROR_NEED_MORE_DATA | insufficient data supplied | The data passed in the $result parameter was not a valid table name or result identifier. | Check the table name for typographical errors or that the query ran correctly.
DB_ERROR_NODBSELECTED | no database selected | No database was chosen. | Check the DSN in connect().
can't distinguish duplicate field names |  | The query result has multiple columns with the same name. PHP's Informix extension deals with columns having the same names by overwriting the prior columns information. Therefore, tableInfo() is unable to properly represent these result sets. | Use aliases for columns that have the same names.

Note

This function can not be called statically.

tableInfo() is not portable because not all drivers have this method, many DBMS's are unable to determine table names from query results and the metadata returned by each database system varies dramatically.

Example

Finding information about a table

<?php
// Once you have a valid DB object named $db...
$info = $db->tableInfo('tablename');
print_r($info);
?>

Finding information about a query result

<?php
// Once you have a valid DB object named $db...
$res  =& $db->query('SELECT * FROM tablename');
$info =  $db->tableInfo($res);
print_r($info);
?>

Prior to version 1.6.0, tableInfo() was a part of the DB_result class, so had to be called like this:

<?php
// Once you have a valid DB object named $db...
$res  =& $db->query('SELECT * FROM tablename');
$info =  $res->tableInfo();  // <---- DEPRECATED
print_r($info);
?>
Prev | DB | Next
DB_common::setOption() | PEAR Manual | DB_result


DB_result

DB_result

DB_result – DB result set

Description

DB_result contains the result set of a SQL query. An instance of this class will be returned by a number of DB_common methods.

Prev | DB | Next
DB_common::tableInfo() | PEAR Manual | DB_result::fetchInto()


DB_result::fetchInto()

DB_result::fetchInto()

DB_result::fetchInto() – Fetches a row of a result set into a variable

Synopsis

integer fetchInto ( array &$arr , integer $fetchMode = DB_FETCHMODE_DEFAULT , integer $rowNum = null )

Description

Places a row of data from a result set into a variable you provide then moves the result pointer to the next row. The data can be formatted as an array or an object.

Parameter

mixed $arr

reference to a variable to contain the row

integer $fetchMode

the fetch mode to use. The default is DB_FETCHMODE_DEFAULT, which tells this method to use DB's current fetch mode. DB's current default fetch mode can be changed using setFetchMode(). Potential values include:

  • DB_FETCHMODE_ORDERED

  • DB_FETCHMODE_ASSOC

  • DB_FETCHMODE_OBJECT

integer $rowNum

the row number to fetch. Note that 0 returns the first row, 1 returns the second row, etc.

Return value

integer - DB_OK if a row is processed, NULL when the end of the result set is reached or a DB_Error object on failure

Note

This function can not be called statically.

Example

Using fetchInto()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM mytable');
while ($res->fetchInto($row)) {
    // Assuming DB's default fetchmode is
    // DB_FETCHMODE_ORDERED
    echo $row[0] . "\n";
}
?>

See

"Intro - Results", setFetchMode(), fetchRow()

Prev | DB | Next
DB_result | PEAR Manual | DB_result::fetchRow()


DB_result::fetchRow()

DB_result::fetchRow()

DB_result::fetchRow() – Fetches a row from a result set

Synopsis

mixed &fetchRow ( integer $fetchmode = DB_DEFAULT_MODE , integer $rownum = null )

Description

Returns a row of data from a result set then moves the result pointer to the next row. The data can be formatted as an array or an object.

Parameter

integer $fetchmode

the fetch mode to use. The default is DB_FETCHMODE_DEFAULT, which tells this method to use DB's current fetch mode. DB's current default fetch mode can be changed using setFetchMode(). Potential values include:

  • DB_FETCHMODE_ORDERED

  • DB_FETCHMODE_ASSOC

  • DB_FETCHMODE_OBJECT

integer $rownum

the row number to fetch

Return value

mixed - an array or object containing the row's data, NULL when the end of the result set is reached or a DB_Error object on failure

Note

This function can not be called statically.

Example

Using fetchRow()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM mytable');
while ($row =& $res->fetchRow()) {
    // Assuming DB's default fetchmode is
    // DB_FETCHMODE_ORDERED
    echo $row[0] . "\n";
}
?>

See

"Intro - Results", setFetchMode(), fetchInto()

Prev | DB | Next
DB_result::fetchInto() | PEAR Manual | DB_result::free()


DB_result::free()

DB_result::free()

DB_result::free() – Releases a result set

Synopsis

boolean free ( )

Description

Deletes the result set and frees the memory occupied by the result set. Does not delete the DB_result object itself.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Example

Using free()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT name, address FROM clients');
while ($row =& $res->fetchRow()) {
    echo $row['name'] . ', ' . $row['address'] . "\n";
}
$res->free();
?>

Note

This function can not be called statically.

Prev | DB | Next
DB_result::fetchRow() | PEAR Manual | DB_result::nextResult()


DB_result::nextResult()

DB_result::nextResult()

DB_result::nextResult() – Gets result sets from multiple queries

Synopsis

boolean nextResult ( )

Description

Some database backends supports executing more then one query at the same time. With nextResult() you can go through the result sets.

This function has nothing to do with with executeMultiple().

Return value

boolean - TRUE if DB_result contains the next result set, FALSE if there is no further result set to fetch

Note

This function can not be called statically.

Prev | DB | Next
DB_result::free() | PEAR Manual | DB_result::numCols()


DB_result::numCols()

DB_result::numCols()

DB_result::numCols() – Gets number of columns in a result set

Synopsis

integer numCols ( )

Description

Get the number of columns of the rows in a result set.

Return value

integer - number of columns or a DB_Error object on failure

Note

This function can not be called statically.

Example

Using numCols()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
echo $res->numCols();
?>

See

numRows(), affectedRows()

Prev | DB | Next
DB_result::nextResult() | PEAR Manual | DB_result::numRows()


DB_result::numRows()

DB_result::numRows()

DB_result::numRows() – Gets number of rows in a result set

Synopsis

integer numRows ( )

Description

Get the number of rows in a result set.

For ibase, ifx and oci8, this method only works if the DB_PORTABILITY_NUMROWS portability option is enabled. In addition, for ibase and ifx, PEAR DB must be at version 1.7.0 or greater.

Does not work for Microsoft Access.

Return value

integer - number of rows or a DB_Error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
DB_ERROR_NOT_CAPABLE | DB backend not capable | Driver doesn't support this feature. | Either switch to another database system or enable the DB_PORTABILITY_NUMROWS portability option.

Note

This function can not be called statically.

Example

Using numRows()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
echo $res->numRows();
?>

See

numCols(), affectedRows()

Prev | DB | Next
DB_result::numCols() | PEAR Manual | DB_Error


DB_Error

DB_Error

DB_Error – DB Error object

Description

In case of failure, most of the DB functions return a DB_Error object which contains information about the error. DB_Error offers the same functions as PEAR_Error.

The text messages returned by DB_Error::getMessage() are consistent between each DBMS.

The error code integers returned by DB_Error::getCode() are also consistent between each DBMS. The integers returned are based on the DB_ERROR_* constants defined in DB.php.

DB_Error::getDebugInfo() and DB_Error::getUserInfo() return complete native DBMS error reports.

Trapping errors and determining what happened

<?php
require_once 'DB.php';

$db =& DB::connect('pgsql://wronguser:badpw@localhost/thedb');
if (PEAR::isError($db)) {
    /*
     * This is not what you would really want to do in
     * your program.  It merely demonstrates what kinds
     * of data you can get back from error objects.
     */
    echo 'Standard Message: ' . $db->getMessage() . "\n";
    echo 'Standard Code: ' . $db->getCode() . "\n";
    echo 'DBMS/User Message: ' . $db->getUserInfo() . "\n";
    echo 'DBMS/Debug Message: ' . $db->getDebugInfo() . "\n";
    exit;
}
?>
Prev | DB | Next
DB_result::numRows() | PEAR Manual | DB_DataObject


DB_DataObject

DB_DataObject

SQL Builder and Data Modeling Layer

This chapter describes how to use the DB_DataObject SQL Builder and Data Modeling layer

Table of Contents
  • Introduction -- What DB_DataObject can do
  • Configuration Options -- Setting the defaults for database access
  • Auto Building and Database Schema -- creating the base Classes and Database schema
  • DB_DataObject::factory() -- Autoload and instantate class based on table name.
  • ->get() -- Simple Get (Select) request
  • DB_DataObject::staticGet() -- Simple Get (Select) request, abbreviated and Autoload.
  • {Child Class}::staticGet() -- Simple Get (Select) request, abbreviated (autogenerated)
  • ->find() -- find results
  • ->fetch() -- fetch next row
  • ->count() -- Perform a select count() request
  • ->insert() -- Insert current objects variables into database
  • ->update() -- Update objects variables into database
  • ->delete() -- Delete items from table
  • Selecting Specific data (SELECT) -- Advanced Filters - ::query(), ::SelectAdd(), ::whereAdd(), ::Limit(), ::OrderBy(), ::GroupBy(),
  • ->query() -- send a raw query
  • ->free() -- Free resources
  • ->selectAdd() -- Add selected columns
  • ->whereAdd() -- Add WHERE statement
  • ->escape() -- Escape a string for use with Like queries
  • ->limit() -- Set limit
  • ->orderBy() -- Add an order by condition
  • ->groupBy() -- Add group by condition
  • Automatic Table Linking and Joins -- Automatic Table Linking - ::getLink(), ::getLinks(), ::joinAdd(), ::selectAs()
  • ->getLink() -- fetch and return a related object
  • ->getLinks() -- load related objects
  • ->selectAs() -- Build the select component of a query (usually for joins)
  • ->joinAdd() -- add another dataobject to build a create join query
  • ->set*() and ->get*() -- Automatic Setters and Getters using overload
  • ->setFrom() -- Copy items from Array or Object (for form posting)
  • ->toArray() -- Get an array of the current result
  • ->validate() -- check object data, and call objects validation methods.
  • ->tableName() -- Get or set the table name of an object
  • ->database() -- Get or set the database the object uses
  • ->table() -- Get or set the table schema
  • ->keys() -- Get or set the table keys
  • ->getDatabaseConnection() -- Get the PEAR Database Object
  • ->getDatabaseResult() -- Get the PEAR Database Result Object
  • DB_DataObject::debugLevel -- set the amount of debugging output
  • ->debug() -- output debug information.
  • DB_DataObject::raiseError -- throw an error
  • Casting - Dates, Blobs and Null -- DB_DataObject_Cast ::date(), ::blob(), ::sql()
Prev | Database | Next
DB_Error | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What DB_DataObject can do

Introduction

Zend Optimizer: due to a bug in the optimizer, you will have to either reduce the optimization level, or define the constant DB_DATAOBJECT_NO_OVERLOAD = 0 otherwise PHP may segfault

Pass by Reference, due to a unfixable bug in PHP4, you can not use overload with pass-by-reference arguments (It works OK in PHP5), If you need pass-by-reference, define the constant DB_DATAOBJECT_NO_OVERLOAD = 0

DB_DataObject is a SQL Builder and Data Modeling Layer built on top of PEAR::DB. Its main purpose is to

  • Build SQL and execute statements based on the objects variables.

  • Group source code around the data that they relate to.

  • Provide a simple consistent API to access and manipulate that data.

So what does that mean in English? Well, if you look around at some of the better written PHP applications and frameworks out there, you will notice a common approach to using classes to wrap access to database tables or groups. The prime example of this is the person object, which would frequently look something like this.

A Classic Data Object or Container

<?php
require_once 'DB.php';
$db = DB::connect('mysql://someuser:somepass@localhost/pear_dbdo');
$db->setFetchMode(DB_FETCHMODE_ASSOC);

class MyPerson
{

    // gets an array of data about the seleted person
    function getPerson($id)
    {
        global $db;
        $result = $db->query('SELECT * FROM person WHERE id=' . $db->quote($id));
        return $result->fetchRow();
    }

    // example of checking a password.
    function checkPassword($username, $password)
    {
        global $db;

        $hashed = md5($password);
        $result = $db->query(
            'SELECT name FROM person WHERE name=' . $db->quote($username)
            . ' AND password = ' . $db->quote($hashed)
        );
        return $result->fetchRow();
    }

}

// get the persons details..
$array = MyPerson::getPerson(12);
echo $array['name'] . "\n";
?>

The examples operate on the following SQL database table:

CREATE TABLE IF NOT EXISTS `person` (
  `id` int(11) NOT NULL auto_increment,
  `name` varchar(64) NOT NULL,
  `password` varchar(32) NOT NULL,
  `birthDate` date NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 AUTO_INCREMENT=13 ;

INSERT INTO `person` (`id`, `name`, `password`, `birthDate`) VALUES
(12, 'John', '098f6bcd4621d373cade4e832627b4f6', '1984-02-23');

The key benefit of this approach is that you are grouping similar actions on a single table in one place, and are more likely to spot duplicated code (eg. two methods that do similar things). You will also notice the global $db variable used here - the fact is that most of the time you will use a common database connection for all your classes, so how should this be dealt with?

The next step on this road is to use the objects variables as a storage mechanism.

A Classic Data Object or Container

<?php
require_once 'DB.php';
$db = DB::connect('mysql://someuser:somepass@localhost/pear_dbdo');
$db->setFetchMode(DB_FETCHMODE_ASSOC);

class MyPerson
{
    var $id;
    var $name;
    var $birthDate;

    // gets an array of data about the seleted person
    function get($id) {
        global $db;
        $result = $db->query('SELECT * FROM person WHERE id=' . $db->quote($id));
        $array = $result->fetchRow();
        foreach ($array as $key => $value) {
            $this->$key = $value;
        }
    }

    function getAge() {
        return date('Y') - date('Y', strtotime($this->birthDate));
    }

}
// now get the person and display the age.
$person = new MyPerson();
$person->get(12);
echo "{$person->name} is ". $person->getAge() . " years old\n";
?>

As you can see, the current row of data is now stored in the Data Container, and additional methods can be added to manipulate the data in the object or even call other related objects (eg. tables relationships in databases)

As a next step, why not utilize the member variables to perform searches or gets on the database.

A Classic Data Object or Container

<?php
require_once 'DB.php';
$db = DB::connect('mysql://someuser:somepass@localhost/pear_dbdo');
$db->setFetchMode(DB_FETCHMODE_ASSOC);

class MyPerson
{
    var $id;
    var $name;
    var $birthDate;

    // does the query based on the value of $this->name
    function find() {
        global $db;
        $this->result = $db->query('SELECT * FROM person WHERE name=' . $db->quote($this->name));
    }

    // fetches a row of data and sets the object variables to match it.
    function fetch() {
        $array = $this->result->fetchRow();
        if (empty($array)) {
            return false;
        }
        foreach ($array as $key=>$value) {
            $this->$key = $value;
        }
        return true;
    }

}

// now get the person and display the age.
$person = new MyPerson();
$person->name = "John";
$person->find();
while ($person->fetch()) {
    echo "a {$person->name} has a birthday on {$person->birthDate}<br/>\n";
}
?>

As you can see, by assigning values to the object before the find method is called, you can set conditions for the query. DB_DataObjects behaves in a similar way to this, however, you can also add more conditions with the whereAdd() method, or restrict the selection using the selectAdd() method.

Obviously you can carry on down this road and create lots of little containers for each table in your database, and all the code will nicely relate to each table. However, you can see from the examples above that all classes are likely to end up with a common set of methods.

  • to fetch data, like get, find, fetch

  • to update, insert and delete from the data store

  • to automate fetching related objects

So to improve on this, DB_DataObject was born, it started life as a common answer to the issues above, however as most problems grow in complexity as the problem is examined in finer detail, so has DataObjects. It has grown to include

  • A common simple configuration method (for setting database connections)

  • A fast and simple store for database descriptions, so primary keys can be used to locate data quickly

  • a debugger that enables you to see what exactly it is doing.

  • basic data validation - so the strings and integers can be checked.

  • Posibility to build complex joins or get related data by secondary calls (links) .

  • Ability to create and update your Table specific classes with the current database table variables (see autobuilding)

  • Simple to integrate with other packages, with setFrom() and toArray() methods

So what do my classes look like?

At last some real DataObject Code..

<?php
// this is the common configuration code - place in a general site wide include file.

    // this  the code used to load and store DataObjects Configuration.
    $options = &PEAR::getStaticProperty('DB_DataObject','options');

    // the simple examples use parse_ini_file, which is fast and efficient.
    // however you could as easily use wddx, xml or your own configuration array.
    $config = parse_ini_file('example.ini',TRUE);

    // because PEAR::getstaticProperty was called with an & (get by reference)
    // this will actually set the variable inside that method (a quasi static variable)
    $options = $config['DB_DataObject'];

     // this is normally contained in your DataObjects file (autogenerated by the generator)

    require_once 'DB/DataObject.php';

    // by extending the base class DB_DataObject - you inherit all the common methods defined in it.

    class DataObjects_Person extends  DB_DataObject {

        var $id; // this is a primary id (it's specified in a config file - explained later)
        var $name;
        var $friend;

        // this is a simple function to get the persons friends..?

        function getFriends()
        {

            $personObject = $this->factory('person');

            // look for all people with their friend number matching this persons id.
            $personObject->friend = $this->id;

            // do the select query.
            $personObject->find();
            $array = array();

            // fetch the results into the object.
            while ($personObject->fetch()) {
                // use the clone to copy - not really needed but get used to it for PHP5

                $array[] = clone($personObject);
            }
            // return the results.
            return $array;

        }
    }

    // and this goes on your display code

    // create a new person class..
    $person = DB_DataObject::Factory('person');

    // get the person using the primary key.
    $person->get(12);
    // get the friends.
    $friends = $person->getFriends();

    //  DB_DataObjects is designed to make print_r useable to debug your applications.
    print_r($friends);
?>

The above example illustrates the components of the DB_DataObject, by setting the options, all the core objects will be able to auto load the data definitions from a generated ini file, and know how to access the database. (multiple databases are supported - see section on configuration)

The class definition illustrates how you only need to define the data specific code in your class, ignoring all the common methods, along with showing one of the methods for retrieveing multiple rows of data.

The later half illustrates how to query and get the result for a single row. The $person->get() would connect to the database, perform the query, fetch the result and assign the objects variables to the data returned from the query.

In the above example, this query would be performed.

SELECT * FROM person WHERE id=12;
SELECT * FROM person WHERE friend=12;

To make a change to the Database you would just change the value of the objects variables and call the update method.

<?php
$person = DB_DataObject::factory('person');
        $person->get(12);
        $person->name = 'Fred';
        $person->update();
?>

As a general rule of thumb method names are usually the same as the SQL statement they relate to.

Prev | DB_DataObject | Next
DB_DataObject | PEAR Manual | Configuration Options


Configuration Options

Configuration Options

Configuration Options – Setting the defaults for database access

Configuration

DB_DataObject needs to be configured before using it and auto generating classes and definitions. The easiest way to configure DB_DataObject is to use ini files (although you may also like to consider the PEAR::Config class, or your own configuration system)

This is a typical configuration file for DB_DataObject

[DB_DataObject]

database          = mysql://user:password@localhost/vending
schema_location   = /home/me/Projects/myapplication/DataObjects
class_location    = /home/me/Projects/myapplication/DataObjects
require_prefix    = DataObjects/
class_prefix      = DataObjects_
db_driver         = MDB2 #Use this if you wish to use MDB2 as the driver
quote_identifiers = 1

To use this ini file with DB_DataObject, (and possibly any other classes that use options like this)

Setting the default options

<?php
$config = parse_ini_file('example.ini',TRUE);
foreach($config as $class=>$values) {
    $options = &PEAR::getStaticProperty($class,'options');
    $options = $values;
}

// or you can do without an ini file, and configure it in PHP..

$options = &PEAR::getStaticProperty('DB_DataObject','options');
$options = array(
    'database'          => 'mysql://user:password@localhost/vending',
    'schema_location'   => '/home/me/Projects/myapplication/DataObjects',
    'class_location'    => '/home/me/Projects/myapplication/DataObjects',
    'require_prefix'    => 'DataObjects/',
    'class_prefix'      => 'DataObjects_',
    'db_driver'         => 'MDB2', //Use this if you wish to use MDB2 as the driver
    'quote_identifiers' => true
);
?>

Configuration Options - Required

database DSN

This is the default data source name (DSN) to connect to your database. See the DSN configuration page for DB or the DSN configuration page for MDB2 for more details.

schema_location directory

The directory where the DB_DataObject database schema file is store.

DB_DataObject stores the description of the database (Tables and Columns) in an .ini file, in this directory. This information is used to determine if the column is a string and needs quotes, or should be a number (and is checked) at SQL building time. It is quite common to store the schema in the same directory as your DataObject Classes.

require_prefix directory

The Path absolute, or relative to your default include path(s), where your extended classes can be found.

This is used by the staticGet() method and the getLinks() method to auto load classes,

class_prefix string

All the generated Classes are named {class_prefix}ucfirst($table_name) . Use this to alter the prefixed name, this is used by the staticGet() and getLinks() methods

Configuration Options - Optional

db_driver string

default = DB, Use this configuration option to set the database abstraction driver used by DB_DataObject.

using MDB2 as the driver

db_driver = MDB2
sequence_{table} string

To Hard code the key (autoincrement/nextval() for a table to a specific key, overriding anything in the keys definition of the file. Normally used on databases that are not able to be queried correctly for their structure

using login as the key for the person table

sequence_person = login
ignore_sequence_keys string

If you do not want to use pear's nextval(), for automatically filling in sequences, this can disable it for "ALL", or a list of tables "person,cart,group"

debug integer

The default debugging level (default 0=off), 1= basic sql logging,2=result logging, 3=everything

debug_ignore_updates boolean

default FALSE, if set, then updates on the database are disabled.

dont_die boolean

default FALSE, The standard behaviour of dataobjects is to issue a PEAR_ERROR_DIE (eg. exiting PHP), when a fatal error occurs, like database connection failure or sending an invalid object type to a method. However if you need to run it on a live server you will probably want to set this to TRUE and define a PEAR error handler to catch these errors and show a nice friendly 'sorry we are down for maintenence' message page.

quote_identifiers boolean

To force the quotation of identifiers in the SQL statements, set this to 1. This is useful if any table names use hyphens.

Statement Generated with and without quote_identifiers

quote_identifiers = 1;
SELECT 'somecol' FROM 'sometable' WHERE 'somevalue'=1;

quote_identifiers = 0;
SELECT somecol FROM sometable WHERE somevalue=1;

Note: This will not affect data sent to methods such as
whereAdd(),
orderBy(),
and groupBy(),
which expect raw data.

proxy string

This enables the building of classes and ini classes on the fly, rather than forcing you to generate the code forhand. (currently the only value supported is "full", which will generate both schema data and default classes when using factory)

Configuration Options - Multiple Databases (optional)

database_* string

When you have multiple databases you can use the database_* to specify the DSN for each database

using multiple databases - database passwords

database_authentication  = mysql://user:password@localhost/authentication
database_sales           = mysql://user:password@localhost/sales
table_* string

When you have multiple databases you can use the table_* configuration variables to map individual tables to different databases, for example

using multiple databases - table settings

table_users     = authentication
table_saleslog  = sales
table_stock     = sales

Configuration Options - Builder

class_location directory

The Directory where your DataObject extended Classes are.

Used by the Class Auto Builder when updating/writing to your class definitions.

extends string

The Name of your Base Class (usually DB_DataObject) is located.

If you wish to add a common layer of useful methods for all classes, you can set the extends_location and extends settings to a different class. the default is 'DB_DataObject'

extends_location directory

The Directory where your Base Class (usually DB_DataObject) is located.

If you wish to add a common layer of useful methods for all classes, you can set the extends_location and extends settings to a different class. the default is 'DB/DataObject.php'

generator_class_rewrite boolean

Normally when you recreate a class from the database, it will only alter the variables, and staticGet, - with this set, it will also update the extends field

build_views boolean

Postgres (and maybe some others), allow you to treat views just like normal tables (eg. insert/update/delete etc. work on them), you can use this option to generate files for all the views in the database.

Note: You will have to specify keys manually in the generated classes (eg. define the methods keys() and sequenceKey(), as the generator can not guess which ones are likely to be the key.

generator_include_regex string

If you only want to generate classes and ini entries for specific tables, you can use this to build a regex, only tables with names matching the regex will be generated, for example /mytables_.*/

generator_exclude_regex string

If you only want to explicitly prevent the generation of classes and ini entries for specific tables, you can use this to build a regex, any tables that match the regex, will not be generated, for example /private_tables_.*/

generator_strip_schema boolean

postgresql has a wierd concept of schemas which end up prefixed to the list of tables. - this makes a mess of class/schema generation setting this to 1, makes the generator strip the schema from the table name

generator_novars boolean

If True, the generator does not write a private or var's definition for the columns so you can overload get/set.

generator_add_validate_stubs boolean

If True, the generator will insert / (or add to existing files) stubs for validate methods.

Prev | DB_DataObject | Next
Introduction | PEAR Manual | Auto Building and Database Schema


Auto Building and Database Schema

Auto Building and Database Schema

Auto Building and Database Schema – creating the base Classes and Database schema

What the Auto Builder (createTables.php) does

One of the essential features of an SQL building tool is to to have some understanding of the database structure, So that Integers can be checked, and strings can be escaped. There a few ways that Querying the database for the table structure could be accomplished

  • on every SQL query

  • At the initialization of every web page.

  • Once, while setting up the application, and store it in a file

DB_DataObject uses the last of these normally (see the section below on Alternatives), it utilizes the parse_ini_file function to read the file, so it should be reasonably fast. However this does involve a stage of setting up DB_DataObject prior to use.

The other key concept of DB_DataObject is that you work with extended classes of DB_DataObject, which do all the 'table' related work. Setting up these classes for a large database can be time consuming, so the createTables.php file will automatically build the skeletons for all these class files.

To start the auto builder simply go to the pear/DB/DataObject/ directory, and type c:\php4\php.exe createTables.php myconfig.ini this will read your configuration file and generate all the base classes, along with the data definition file.

As of Version 1.5, you can use the option "proxy = full", which will cause DataObjects to create classes and schema on the fly, rather than using an ini file or prebuilt classes.

Default Class Definition

The default generated class looks like this.

an generated extended class

<?php
/*
* Table Definition for group
*/

class DataObjects_Grp extends DB_DataObject {

    ###START_AUTOCODE
    /* the code below is auto generated do not remove the above tag */

    var $__table='group';                             // table name
    var $id;                              // int primary_key
    var $name;                            // string
    var $grp_owner;                       // int
    var $official;                        // string
    var $street;                          // string
    var $postcode;                        // string
    var $city;                            // string
    var $homepage;                        // string
    var $email;                           // string
    var $extra;                           // blob

    /* Static get */
    function staticGet($k,$v=NULL) { return DB_DataObject::staticGet('DataObjects_Grp',$k,$v); }

    /* the code above is auto generated do not remove the tag below */
    ###END_AUTOCODE
}
?>

The class defines the table name, and comments some of table columns for your reference, It also adds the staticGet() method, which can be used to quickly get single rows as Objects. You should add your table related code after the ###END_AUTOCODE.

Prior to version 1.6 a method __clone was created, since PHP5 changed to use $x = clone($y);, this method has been removed. DataObjects now creates a dummy function clone (if necessary), to enable forward compatibility

Database Schema File

The default generated database definition file looks like this, it is located in the directory set by the "schema_location" configuration option, and is named the same as the database.

If you rename the database, you will either have to regenerate the file or copy it to match the same name.

If you change the database schema (eg. add a column or change the type), you will have to regenerate the schema file, using createTables.php, At present, this is not done automatically (although this may be added in the future..)

You should not edit this file by hand (as any changes will be lost when regenerating it). You can override the keys of a table by using a configuration option "sequence_{table} = key", or by defining the sequenceKey() method in your extended class.

Database configuration file

[group]
id = 129
name = 130
grp_owner = 129
official = 130
street = 130
postcode = 130
city = 130
homepage = 130
email = 130
extra = 130

[group__keys]
id = N

The blocks indicate either tables and the type of field with binary addition (1=integer,2=string,128=not null, so 129=integer and not null), or a list of keys for each table. You should not need to edit file.

Alternatives to using a Schema File

It is possible to use DataObjects without a schema file, this can be achieved in 2 ways

  • by defining the table() and keys() methods in an extended class

  • by passing an array to table() and keys() when you have an instance of dataobjects

The second of this is demonstrated on the keys() and table() page.

Below is a hand coded class which does not use a schema.ini file.

It was designed to be a return value from a method, rather than an object variable, so that the output of print_r(), would not include extra information (and would be smaller when dumping a large result set.

A Hand Coded extended class

<?php
/*
* Table Definition for group
*/

class DataObjects_Grp extends DB_DataObject {

    // you can define these yourself

    var $__table='group';                             // table name
    var $id;                              // int primary_key
    var $name;                            // string
    var $bday;                            // string
    var $last;                            // datetime
    var $active;                          // tinyint(1)
    var $desc;                            // text
    var $photo;                           // blob

    // these are usefull to be consistant with a autogenerated file.

    /* Static get */
    function staticGet($k,$v=NULL) { return DB_DataObject::staticGet('DataObjects_Grp',$k,$v); }

    // now define your table structure.
    // key is column name, value is type
    function table() {
        return array(
            'id'     => DB_DATAOBJECT_INT,
            'name'   => DB_DATAOBJECT_STR,
            'bday'   => DB_DATAOBJECT_STR + DB_DATAOBJECT_DATE,
            'last'   => DB_DATAOBJECT_STR + DB_DATAOBJECT_DATE + DB_DATAOBJECT_TIME,
            'active' => DB_DATAOBJECT_INT + DB_DATAOBJECT_BOOL,
            'desc'   => DB_DATAOBJECT_STR + DB_DATAOBJECT_TXT,
            'photo'  => DB_DATAOBJECT_STR + DB_DATAOBJECT_BLOB,
        );
    }

    // now define the keys.
    function keys() {
        return array('id');
    }

}
?>
Prev | DB_DataObject | Next
Configuration Options | PEAR Manual | DB_DataObject::factory()


DB_DataObject::factory()

DB_DataObject::factory()

DB_DataObject::factory() – Autoload and instantate class based on table name.

Synopsis

mixed DB_DataObject::factory ( string $table )

Description

This is the recommended way to autoload a class, and instantate it. The class is loaded based on the configuration settings (class_location and class_prefix) for table to class naming.

Parameter

  • string $table - the table you want to load ([From Version 1.7.2] if blank, and called on an an instance of a dataobject, it will create a new instance of that object)

Return value

object mixed - DB_DataObject_Error or the object

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_DATAOBJECT_ERROR_NOCLASS | "could not autoload $class" |  |

Note

This method can be called statically or dynamically.

Example

Simple fetch of data based on Primary Key

<?php
// set up our options
$opts = &PEAR::getStaticProperty('DB_DataObject','options');
$opts = array(
    'class_location'  => '/home/me/Projects/myapplication/DataObjects',
    'class_prefix'    => 'DataObjects_'
);

// loads the file: /home/me/Projects/myapplication/DataObjects/Person.php
// and checks that the class DataObjects_Person exists, and returns an
// instance of it.

$person = DB_DataObject::factory('person');

if ($person->get(12)) {
  print_r($person);
} else {
  echo "NO person 12 exists";
}

// it can also be used in a dynamically
class DataObjects_MyTable {

    function anExample() {
        $person = $this->factory('person');

        // supported in version 1.7.2
        $another_mytable = $this->factory();

        $another_person = $person->factory();

    }
}
?>
Prev | DB_DataObject | Next
Auto Building and Database Schema | PEAR Manual | ->get()


->get()

->get()

->get() – Simple Get (Select) request

Synopsis

int $DB_DataObject->get ( mixed Key or Value , mixed value )

Description

Get a result using key, value. Returns Number of rows located (usually 1) for success, and puts all the table columns into this classes variables. If only one parameter is used, it is assumed that first parameter is a value and get() will use the primary key.

Parameter

  • mixed $key or $value - column (or value if only one parameter)

  • mixed $value - value

Return value

int - Number of rows

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_DATAOBJECT_ERROR_INVALIDCONFIG | "No Keys available for $table" |  |
DB_DATAOBJECT_ERROR_INVALIDARGS | "No Value specified for get" |  |

Note

This function can not be called statically.

You should avoid calling get on the same object instance twice, as this will result in unexpected results.

Example

Simple fetch of data based on Primary Key

<?php
$person = new DataObjects_Person;
$person->get(12);
print_r($person);
?>

Resulting SQL

SELECT * FROM person WHERE id=12

Simple fetch of data based on Key and Value

<?php
$person = new DataObjects_Person;
$person->get('email','test@example.com');
print_r($person);
?>

Resulting SQL

SELECT * FROM person WHERE email='test@example.com'

Results of example code

<?php
Object (DataObjects_Person) =>
    [N] => 1
    [id] => 12
    [group] => 5
    [has_glasses] => 1
    [name] => 'fred blogs'
    [password] => '**testing'
    [email] => 'test@example.com'
?>
Prev | DB_DataObject | Next
DB_DataObject::factory() | PEAR Manual | DB_DataObject::staticGet()


DB_DataObject::staticGet()

DB_DataObject::staticGet()

DB_DataObject::staticGet() – Simple Get (Select) request, abbreviated and Autoload.

Synopsis

mixed DB_DataObject::staticGet ( string $class , mixed $key or $value , mixed $value )

Description

This method is depreciated, it is recommended to use ::factory() and ->get()

The static method is a combination of factory and get(). staticGet() will cache the returned data in a global variable for quick access within the same request (any data modification query will clear the cache).

Parameter

  • string $class - class name

  • string $key - column (or value if only 2 parameters are given)

  • mixed $value - value

Return value

object mixed - FALSE or the object

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_DATAOBJECT_ERROR_NOCLASS | "could not autoload $class" |  |
DB_DATAOBJECT_ERROR_NOCLASS | "Error creating $newclass" |  |
DB_DATAOBJECT_ERROR_NODATA | "No Data return from get $key $value" |  |

Note

This method must be called statically.

Example

Simple fetch of data based on Primary Key or column and value

<?php
$person = DB_DataObject::staticGet('DataObjects_Person', 12);
print_r($person);

$person = DB_DataObject::staticGet('DataObjects_Person', 'name', 'fred');
print_r($person);
?>
Prev | DB_DataObject | Next
->get() | PEAR Manual | {Child Class}::staticGet()


{Child Class}::staticGet()

{Child Class}::staticGet()

{Child Class}::staticGet() – Simple Get (Select) request, abbreviated (autogenerated)

Synopsis

object {Child Class}::staticGet ( mixed $key or $value , mixed $value )

Description

The static method is similar to the get request, however it does not require the initial instantiation of the class. staticGet() can optionally cache the results. (see the configuration section)

Note: This can only be used for tables with a single column primary key.

Parameter

  • string $key - column or value if only one parameter is given

  • mixed $value - value

Return value

object mixed - FALSE or the object

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_DATAOBJECT_ERROR_NOCLASS | "could not autoload $class" |  |
DB_DATAOBJECT_ERROR_NOCLASS | "Error creating $newclass" |  |
DB_DATAOBJECT_ERROR_NODATA | "No Data return from get $key $value" |  |

Note

This method must be called statically.

Example

Simple fetch of data based on Primary Key or column and value

<?php
$person = DataObjects_Person::staticGet(12);
print_r($person);

$person = DataObjects_Person::staticGet('name', 'fred');
print_r($person);
?>
Prev | DB_DataObject | Next
DB_DataObject::staticGet() | PEAR Manual | ->find()


->find()

->find()

->find() – find results

Synopsis

int $DB_DataObject->find ( boolean $autoFetch )

Description

The find method builds and executes the current Query, based on the object variables and any WhereAdd() conditions , If the AutoFetch is TRUE, then it will also call the fetch method automatically.

Parameter

  • boolean $autoFetch - fetch first result

Return value

int - number of rows found, only if the database backend supports the numRows() method. Otherwise 1 (or in versions after 1.7.13, true will returned)

Note

This function can not be called statically.

Example

Simple find() of data based on Object Vars

<?php
$person = new DataObjects_Person;
$person->hair = 'red';
$person->has_glasses = 1;
$number_of_rows = $person->find();
?>

Resulting SQL

<?php
SELECT * FROM person WHERE hair='red' and has_glasses = 1
?>
Prev | DB_DataObject | Next
{Child Class}::staticGet() | PEAR Manual | ->fetch()


->fetch()

->fetch()

->fetch() – fetch next row

Synopsis

boolean $DB_DataObject->fetch ( )

Description

The fetch method gets the next row and sets the objects variables to the rows data. It returns TRUE if data has been collected, and FALSE when there is no more data.

Return value

boolean - TRUE on success and FALSE on failure.

Note

This function can not be called statically.

Fetch is called by staticGet and get calls, so you can override this method in your classes, to add extra data to your object (like formated dates etc)

Example

Simple find and fetch of data based on object Vars

<?php
$person = new DataObjects_Person;

$person->hair = 'red';
$person->has_glasses = 1;

$number_of_rows = $person->find();

$people = array();
while ($person->fetch()) {
    /* store the results in an array */
    $people[] = clone($person);
    echo "GOT {$person->name}<BR>";
}
?>

Overriding fetch to add extra data.

<?php
function fetch() {

  $ret = parent::fetch();
  if ($ret === false) {
      return false;
  }
  $this->dateFormated = date('d/M/Y', $this->date);
  return true;
}
?>
Prev | DB_DataObject | Next
->find() | PEAR Manual | ->count()


->count()

->count()

->count() – Perform a select count() request

Synopsis

int $DB_DataObject->count ( string|boolean $countWhat|$whereAddOnly , boolean $whereAddOnly )

Description

It performs a select count() request on the tables key column and returns the number of resulting rows. The default condition applied to the count() is a combination of the object variables and whereAdd settings. If the constant DB_DATAOBJECT_WHEREADD_ONLY is passed in as the first parameter then only the whereAdd settings will be used.

Parameter

  • string $countWhat - by default count will count on the primary key, if you need to count something else, if you just say DISTINCT, it will count the primiary key prefixed with distinct, or put your own value in (don't forget to escape it if necessary)

  • boolean $useWhereAddOnly - use only the whereAdd conditions (by default, count will only use both the object settings and the whereAdd conditions)

Return value

int|false - number of results or false on an error

Note

This function can not be called statically.

Example

Various examples of using count()

<?php

/* using property values */
$person = new DataObjects_Person;
$person->name  = "test"
$total = $person->count();
echo "There are {$total} people with a name like test";

/* using countWhat */
$person = new DataObjects_Person;
$total = $person->count('DISTINCT name');
echo "There are {$total} names in the database";

/* using countWhat value = DISTINCT */
$person = new DataObjects_Person;
$total = $person->count('DISTINCT');
echo "There are {$total} names in the database";

/* using whereOnly */
$person = new DataObjects_Person;
$person->name = "test";
$person->whereAdd("name like '%test%'");
$total = $person->count(DB_DATAOBJECT_WHEREADD_ONLY);
echo "There are {$total} names in the database";

?>

Resulting SQL

SELECT count(person.id) AS DATAOBJECT_NUM
FROM person
WHERE person.name = 'test';

SELECT count(DISTINCT name) AS DATAOBJECT_NUM
FROM person;

SELECT count(DISTINCT person.id) AS DATAOBJECT_NUM
FROM person;

SELECT count(person.id) AS DATAOBJECT_NUM
FROM person
WHERE name like '%test%';
Prev | DB_DataObject | Next
->fetch() | PEAR Manual | ->insert()


->insert()

->insert()

->insert() – Insert current objects variables into database

Synopsis

mixed $DB_DataObject->insert ( )

Description

Insert the data into the database, based on the variable values of the current object and returns the ID of the inserted element if sequences or primary keys are being used. The values are correctly quoted, and some limited type checking is done.

With mysql, the mysql_next_id() method is used, on other databases, PEAR DB sequence method is used.

Note, insert() may not return the ID correctly in quite a few situations:

  • If the database backend does not support it.

  • The generator did not correctly flag the correct column as autoincrement/nextval

  • An error occured (turn on debugging to see it)

  • The insert failed or '0' rows where affected.

Return value

mixed - Id or key

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_DATAOBJECT_ERROR_INVALIDCONFIG | "insert:No table definition for $table" |  |
DB_DATAOBJECT_ERROR_NODATA | "insert: No Data specifed for query" |  |
DB_* | * | see PEAR::DB | see PEAR::DB

Note

This function can not be called statically.

Example

Simple insert

<?php
$person = new DataObjects_Person;
$person->name='fred';
$id = $person->insert();
?>

Resulting SQL

<?php
INSERT INTO person (name) VALUES ('fred');
?>
Prev | DB_DataObject | Next
->count() | PEAR Manual | ->update()


->update()

->update()

->update() – Update objects variables into database

Synopsis

int $DB_DataObject->update ( dataobject|boolean $original|$useWhere )

Description

Updates current objects variables into the database. if you supply it with a dataObject, as an argument, it will only update the differences between the new and old.

if called with DB_DATAOBJECT_WHEREADD_ONLY as the argument, the update request is built based on the whereAdd values, rather than the primary key. This enables global updates to be performed, rather than single row ones.

Parameter

  • DataObject $original - if provided the update query will be built from the difference between the current and original dataobject.

Return value

int number of rows affected or FALSE on failure

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_DATAOBJECT_ERROR_INVALIDCONFIG | "update:No table definition for $table" |  |
DB_DATAOBJECT_ERROR_NODATA | "update: No Data specifed for query $settings" |  |

Note

This function can not be called statically.

Example

Simple fetch and update

<?php
$person = new DataObjects_Person;
$person->get(12);
$person->name='fred';
$person->update();

$person = new DataObjects_Person;
$person->get(12);
$original = clone($person); // clone is emulated in php4 for compatibility reasons.
$person->name='fred';
$person->update($original);
?>

Resulting SQL

SELECT * FROM person WHERE id = 12
UPDATE person SET name='fred', age='21', eyes='blue' WHERE id = 12

SELECT * FROM person WHERE id = 12
UPDATE person SET name='fred' WHERE id = 12

Simple fetch and update

<?php
$person = new DataObjects_Person;
$person->removed=1;
$person->whereAdd('age > 21');
$person->update();
?>

Resulting SQL

SELECT * FROM person WHERE id = 12;
UPDATE person SET removed=1 WHERE age > 21
Prev | DB_DataObject | Next
->insert() | PEAR Manual | ->delete()


->delete()

->delete()

->delete() – Delete items from table

Synopsis

int $DB_DataObject->delete ( boolean $useWhere )

Description

Deletes data from the database, either using primary key or based on a whereAdd() method call. By default the delete will base its query on the set variables, however if you wish to use the whereAdd() method you should set the $useWhere parameter to DB_DATAOBJECT_WHEREADD_ONLY.

Parameter

  • boolean $use_where - use the whereAdd() conditions (by default, delete will only use primary keys)

Return value

int number of rows affected or FALSE on failure

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
DB_* | "*" | see PEAR::DB | see PEAR::DB
DB_DATAOBJECT_ERROR_NODATA | "delete: No Data specifed for query $condition " |  |

Note

This function can not be called statically.

Example

Simple Delete

<?php
$person = new DataObjects_Person;
$person->get(12);
$person->delete();

$person       = new DataObjects_Person;
$person->name = 'test';
$person->age  = 21;
$person->delete();

$person = new DataObjects_Person;
$person->whereAdd('age < 21');
$person->delete(DB_DATAOBJECT_WHEREADD_ONLY);
?>

Resulting SQL

<?php
SELECT * FROM person WHERE person.id = 12
DELETE FROM person WHERE ( person.id = 12 )

DELETE FROM person WHERE ( person.name = 'test' ) AND ( person.age = 21 )

DELETE FROM person WHERE ( age < 21 )
?>
Prev | DB_DataObject | Next
->update() | PEAR Manual | Selecting Specific data (SELECT)


Selecting Specific data (SELECT)

Selecting Specific data (SELECT)

Selecting Specific data (SELECT) – Advanced Filters - ::query(), ::SelectAdd(), ::whereAdd(), ::Limit(), ::OrderBy(), ::GroupBy(),

More advanced Querying

The basic features allow most simple queries to be done very quickly, however building more complex queries can be done using the methods listed below, which append or set conditions that build the query. You will find that there is a fine balance between using these builder methods and just using raw SQL.

The DB_DataObject can now handle JOIN queries, however please read the introduction to linking and Joining before jumping in and using the Join feature, as you may be trading the use of a cool feature, against the readibility of your code.

Prev | DB_DataObject | Next
->delete() | PEAR Manual | ->query()


->query()

->query()

->query() – send a raw query

Synopsis

void $DB_DataObject->query ( string $string )

Description

Sends a raw query to database. Often you may consider that using a large number of whereAdd's and orderBy method calls are not necessary, and it would be simpler to just write the query, to make the code clearer and shorter.

Parameter

  • string $string - SQL Query

Note

This function can not be called statically.

Example

raw queries on the database

<?php
$person = new DataObjects_Person;
$person->query("SELECT * FROM {$person->__table} WHERE id > 12 ORDER BY id");
while ($person->fetch()) {
  echo $person->name;
}
?>
Prev | DB_DataObject | Next
Selecting Specific data (SELECT) | PEAR Manual | ->free()


->free()

->free()

->free() – Free resources

Synopsis

object $DB_DataObject->free ( )

Description

DataObjects stores result set's as a private global variable, normally this is free'ed after you have run through the results, or at the end of the request. However in some situations, like running queries directly, inserting data, some data is unnecessarly cached.

Using this method will Free All results sets! (so be carefull) it may break running fetch() loops..

You normally only need to use this if you are doing a large number of inserts or queries.

Note

This function can not be called statically.

Example

Freeing resources in a loop

<?php

for ($i = 0; i< 10000; $i++) {
    $person = new DataObjects_Person;
    $person->query(' ... do something ... ');
    $person->free();
}

?>
Prev | DB_DataObject | Next
->query() | PEAR Manual | ->selectAdd()


->selectAdd()

->selectAdd()

->selectAdd() – Add selected columns

Synopsis

void $DB_DataObject->selectAdd ( string $condition )

Description

Adds a selected columns. By default a select query will request all items (eg. SELECT * FROM table), to change this behavior you can first call selectAdd() without any arguments to clear the current request and then add the specific items you require.

You can also set up a default selection query by adding SelectAdd() method calls in the object constructor method (the one with the same name as the class)

Parameter

  • resource $key - table column name

Note

This function can not be called statically.

Example

Using selectAdd()

<?php
$person = new DataObjects_Person;
$person->selectAdd();
$person->selectAdd('id,name');

while ($person->fetch()) {
  echo "{$person->id} {$person->name}<BR>";
}

$person = new DataObjects_Person;
$person->selectAdd("DATE_FORMAT(birthday,'%d %m %Y') as birthday_formated ");
$person->id = 12;
$person->find(TRUE);

echo "{$person->name} {$person->birthday_formated}<BR>";
?>

Resulting SQL

SELECT id,name FROM person

SELECT *, DATE_FORMAT(birthday,'%d %m %Y') as birthday_formated FROM person WHERE id=12
Prev | DB_DataObject | Next
->free() | PEAR Manual | ->whereAdd()


->whereAdd()

->whereAdd()

->whereAdd() – Add WHERE statement

Synopsis

void $DB_DataObject->whereAdd ( string $where , string $logic )

Description

Adds items to the where part of a SQL query. Calling this without any arguments clears the where condition. The default behavior is to add 'AND' to the existing conditions, use the $logic parameter to append OR conditions.

Parameter

  • string $cond - condition to add, or blank to reset the conditions

  • string $logic - optional logic "OR" (defaults to "AND")

Note

This function can not be called statically.

The quote_identifiers configuration option will not affect data sent to whereAdd.

See

Example

Using whereAdd()

<?php
$person = new DataObjects_Person;
$person->whereAdd('age > 12');
$person->whereAdd('age < 30');
$person->find();

while ($person->fetch()) {
    echo "{$person->id} {$person->name}<br />";
}
$person = new DataObjects_Person;
$person->whereAdd('age < 12');
$person->whereAdd('age > 30', 'OR');
$person->find();

while ($person->fetch()) {
    echo "{$person->id} {$person->name}<br />";
}
?>

Resulting SQL

SELECT * FROM person WHERE age > 12 AND age < 30

SELECT * FROM person WHERE age < 12 OR age > 30
Prev | DB_DataObject | Next
->selectAdd() | PEAR Manual | ->escape()


->escape()

->escape()

->escape() – Escape a string for use with Like queries

Synopsis

void $DB_DataObject->escape ( string $value )

Description

Similar to Pear DB's quote it will escape a value, without the quotes, so it can be used with a LIKE query.

Parameter

  • string $value - the string you want to escape

Note

This function can not be called statically.

Example

Escaping a LIKE string

<?php
$person = new DataObjects_Person;
$person->whereAdd("name LIKE '%" . $person->escape("o'brian") . "%'");
$person->find();
?>

Sample SQL

SELECT * FROM PERSON WHERE name LIKE '%o\'brian%'
Prev | DB_DataObject | Next
->whereAdd() | PEAR Manual | ->limit()


->limit()

->limit()

->limit() – Set limit

Synopsis

void $DB_DataObject->limit ( int $from , int $number )

Description

Sets the limit for a query. (this only works on databases that support the LIMIT clause), without parameters, it will clear the current limit.

Parameter

  • int $from - limit start (or number), or blank to reset

  • int $number - limit results to number

Note

This function can not be called statically.

Since postgres and mysql only really support limit directly - calling this on an unsupported database will emit a PEAR::Error and die.

Example

Setting the Limit

<?php
$person = new DataObjects_Person;
$person->limit(2);
$person->find();
while ($person->fetch()) {
    echo "{$person->id} {$person->name}<BR>";
}

$person = new DataObjects_Person;
$person->limit(2,4);
$person->find();

while ($person->fetch()) {
    echo "{$person->id} {$person->name}<BR>";
}
?>

Resulting SQL

SELECT * FROM person LIMIT 2

SELECT * FROM person LIMIT 2,4
Prev | DB_DataObject | Next
->escape() | PEAR Manual | ->orderBy()


->orderBy()

->orderBy()

->orderBy() – Add an order by condition

Synopsis

void $DB_DataObject->orderBy ( string $order )

Description

Adds a order by condition. Calling this without any arguments clears the current order condition.

Parameter

  • string $order - Order

Note

This function can not be called statically.

The quote_identifiers configuration option will not affect data sent to orderBy.

Example

Setting the order by

<?php
$person = new DataObjects_Person;
$person->orderBy('name');
$person->orderBy('age, eye');
$person->find();

// or with direction:
$person = new DataObjects_Person;
$person->orderBy('name ASC');
$person->orderBy('age DESC, eye');
$person->find();

?>

Resulting SQL

SELECT * FROM person ORDER BY name, age, eye
Prev | DB_DataObject | Next
->limit() | PEAR Manual | ->groupBy()


->groupBy()

->groupBy()

->groupBy() – Add group by condition

Synopsis

void $DB_DataObject->groupBy ( string $group )

Description

Adds a group by condition. Calling this without any arguments clears the Group Condition

Parameter

  • string $group - Grouping condition

Note

This function can not be called statically.

The quote_identifiers configuration option will not affect data sent to groupBy.

Example

Setting the Group by

<?php
$person = new DataObjects_Person;
$person->groupBy('name');
$person->groupBy('age, eye');
$person->find();
?>

Resulting SQL

SELECT * FROM person GROUP BY name, age, eye
Prev | DB_DataObject | Next
->orderBy() | PEAR Manual | Automatic Table Linking and Joins


Automatic Table Linking and Joins

Automatic Table Linking and Joins

Automatic Table Linking and Joins – Automatic Table Linking - ::getLink(), ::getLinks(), ::joinAdd(), ::selectAs()

Automating the collection of related data

When designing a database, often some tables are related to others - a membership table would contain a reference to a person's id and the group id that they are a member of. Using the Link methods, you can automatically fetch objects into the parents variables.

Automated links are supported by a databasename.links.ini file. which stores the relations ship between tables, maping one tables column to anothers. This databasename.links.ini file is used by the getLinks() and joinAdd() Method, to either retrieve related information of a primary object, or quickly build complex multitable queries.

The other way of using linking is via the getLink() method, which you can manually use without a database.links.ini file to specify a column, and how it relates to another table and column.

The goal of getlinks and joinAdd is to make connecting two tables as simple and fast as possible, while still ensuring that the code is reasonably comprehensable. In the example below, It is demostrated how getlinks() can be used to fetch more data about an object after the initial fetch, and it can also be used to test the links file prior to building a full blown join Query.

A simple introduction to links and joins

<?php
// just loop and fetch more information

$person = new DataObjects_Person;
$person->eyeColour = 'red';
$person->find();
while ($person->fetch()) {
    // this will look up in the cars table for the id matching the person->car value.

    $car = $person->getLink('car','cars','id');

    echo "{$person->name} has red eyes and owns a {$car->type}\n";
}

// now if you create a database.links.ini file with the car example
// the example would look like this.

$person = new DataObjects_Person;
$person->eyeColour = 'red';
$person->find();
while ($person->fetch()) {

    // use the links.ini file to automatically load
    // the car object into $person->_car
    $person->getLinks();

    echo "{$person->name} has red eyes and owns a {$person->_car->type}\n";
}

// and finally the most complex, using SQL joins and select as.
// the example would look like this.

$person = new DataObjects_Person;
$person->eyeColour = 'red';

// first, use selectAs as to make the select clauses match the column names.
$person->selectAs();

// now lets create the related element
$car = new DataObjects_Car;

// and for fun.. lets look for red eys and red cars..
$car->colour = 'red';

// add them together.
$person->joinAdd($car);

// since both tables have the column id in them, we need to reformat the query so
// that the car columns have a different name.

$person->selectAs($car,'car_%s');

$person->find();
while ($person->fetch()) {

    echo "{$person->name} has red eyes and owns a {$person->car_type}\n";
}
?>

Using link ini files for table links

DB_DataObject Version 0.3 introduced the ability to create link ini files so you can map column to other database columns using an ini file this ini file should have the name 'databasename.links.ini', and be placed in the same folder as the database schema ini file 'databasename.ini' file that is created automatically by createTables.php

The databasename.links.ini file contains a section for each table, then the column that is linked equal to the table and column that it should locate the column from. It assumes the relationships are non-primary id to primary id, as the example below shows, the person.owner is linked to grp.id. This indicates that running getLinks() on the person object, will fetch a single bit of data from 3 tables - colurs,grp,attachments.

If you use a 'full stop' in the key (link from column), getLinks() will look up in the table with the column name matching the string to the left of the 'full stop', and replace the 'full stop' with and underscore and assign the object variable to that name. Or you may wish to use the selectAs() method to decide how you want columns from different objects to be returned (when using joinAdd())

An example databasename.links.ini file

;                       for table person
[person]
;                       link value of eycolor to table colors, match name column
eyecolor = colors:name
;                       link value of owner to table grp, match id column
owner = grp:id
;                       link value of picture to table attachments, match id column
picture = attachments:id

;                       for a sales example with multiple links of a single column
[sales]
;                       for autoloading the car object into $sales->_car_id
car_id = car:id
;                       for autoloading the part number object into $sales->_car_id_partnum
car_id.partnum = part_numbers:car_id

It is also possible to create joins on keys consisting of more than one column. Use the following syntax:

Linking tables on composite keys

[table_b]
field1,field2 = table_a:field1,field2

This will lead to the following select statement (here using the INNER JOIN syntax):

Resulting SQL

<?php
SELECT * FROM table_b INNER JOIN table_a ON table_b.field1 = table_a.field1 AND table_b.field2 = table_a.field2
?>
Prev | DB_DataObject | Next
->groupBy() | PEAR Manual | ->getLink()


->getLink()

->getLink()

->getLink() – fetch and return a related object

Synopsis

mixed $DB_DataObject->getLink ( string $column , string $table , string $key )

Description

Fetch a related object. This should be used in conjunction with a <dbname>.links.ini file configuration (see the introduction on linking for details on this).

You may also use this with all parameters to specify, the column, and related table and column.

Parameter

  • string $column - either column or column.xxxxx

  • string $table - name of table to look up value in

  • string $link - name of column in other table to match

Return value

mixed - object on success or FALSE on failure.

Note

This function can not be called statically.

Example

Getting the related object

<?php
$person = new DataObjects_Person;
$person->get(12);
$group = $person->getLink('group_owner');
echo $group->name;
$group = $person->getLink('colourid','hair');
?>

Resulting SQL

SELECT * FROM person WHERE id=12
SELECT * FROM group WHERE id=3
SELECT * FROM hair WHERE id=4
Prev | DB_DataObject | Next
Automatic Table Linking and Joins | PEAR Manual | ->getLinks()


->getLinks()

->getLinks()

->getLinks() – load related objects

Synopsis

boolean $DB_DataObject->getLinks ( string $variableFormat )

Description

Loads the all the related objects into the main object, by using the links.ini relationships, and sets the calling objects variables with the row name prefixed with an underscode (_ ) to the resulting objects.

Using this with the earlier column naming convention is depreciated, and links.ini files should be used.

Parameter

  • string $variableFormat - the default behavior is to assign the resulting objects to variables with the row name prefixed with an underscode (_ ), however, you can use this value to format the variable differently

    examples of formaters

if room.occupied_by is linked to a person.id

without a modifier - eg _%s

results in the equivilant of
$object->_occupied_by =  $object->getLink('occupied_by');

with a modifier - eg link_%s

results in the equivilant of
$object->link_occupied_by = $object->getLink('occupied_by');

Return value

boolean - TRUE on success and FALSE on failure

Note

This function can not be called statically.

See

DB_DataObject::getLink()

Example

Two Example Tables

Person
+---------------+---------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+---------------+---------------+------+-----+---------+----------------+
| id | mediumint(9) | | PRI | 0 | auto_increment |
| first_name | varchar(80) | YES | | NULL | |
| last_name | varchar(80) | | MUL | | |
| middle_name | varchar(80) | YES | | NULL | |
| badge_number | smallint(6) | YES | | NULL | |
| street | varchar(80) | YES | | NULL | |
| city | varchar(80) | YES | | NULL | |
| state | varchar(80) | YES | | NULL | |
| zip | varchar(15) | YES | | NULL | |
| phone | varchar(15) | YES | | NULL | |
| reg_type | varchar(80) | YES | | NULL | |
| judge | varchar(10) | YES | | NULL | |
| staff | varchar(10) | YES | | NULL | |
| volunteer | varchar(10) | YES | | NULL | |
| rpga_number | mediumint(9) | YES | | NULL | |
| total_fee | float(10,2) | YES | | NULL | |
| email_address | varchar(80) | YES | | NULL | |
| country | varchar(30) | YES | | NULL | |
| convention_id | int(11) | | | 0 | |
| last_modified | timestamp(14) | YES | | NULL | |
+---------------+---------------+------+-----+---------+----------------+

Convention
+----------------------+---------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+----------------------+---------------+------+-----+---------+----------------+
| id | int(11) | | PRI | 0 | auto_increment |
| name | varchar(50) | | | | |
| sponsor_organization | varchar(50) | | | | |
| rpga_convention_code | varchar(20) | | | | |
| web_site_url | varchar(200) | | | | |
| last_modified | timestamp(14) | YES | | NULL | |
| room_id | int(11) | | | | |
+----------------------+---------------+------+-----+---------+----------------+

Room
+----------------------+---------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+----------------------+---------------+------+-----+---------+----------------+
| room_id | int(11) | | PRI | 0 | auto_increment |
| name | varchar(50) | | | | |
+----------------------+---------------+------+-----+---------+----------------+

Loading all the related objects

<?php
$person = new DataObjects_Person;
$person->get(1079);
$person->getLinks();
print_r($person);
?>

Resulting SQL

SELECT * FROM person WHERE id=1079
SELECT * FROM convention WHERE id=1

Resulting Output

Object:dataobjects_person Object
(
[_DB_DataObject_version] => 1.0
[__table] => person
[_database_dsn] =>
[_database_dsn_md5] => 3974043abbccdd6412fb156a1d10b98377
[_database] => testing
[_condition] =>
[_group_by] =>
[_order_by] =>
[_limit] =>
[_data_select] => *
[_link_loaded] => 1
[_lastError] => pear_error Object
(
[error_message_prefix] =>
[mode] => 1
[level] => 1024
[code] => -3
[message] => getLink:Could not find class for row last_modified, table last
[userinfo] =>
[callback] =>
)

[id] => 1079
[N] => 1
[_DB_resultid] => 2
[first_name] => Tim
[last_name] => White
[middle_name] =>
[badge_number] => 123
[street] => 334411 N Washington
[city] => Texas
[state] => CO
[zip] => 12345
[phone] => 343412323232
[reg_type] => Staff
[judge] =>
[staff] => CHECKED
[volunteer] =>
[rpga_number] => 1232323
[total_fee] => 0.00
[email_address] => tim@example.com
[country] => USA
[convention_id] => 1
[last_modified] => 20020711084539
[_first_name] =>
[_last_name] =>
[_middle_name] =>
[_badge_number] =>
[_reg_type] =>
[_rpga_number] =>
[_total_fee] =>
[_email_address] =>
[_convention_id] => dataobjects_convention Object
(
[_DB_DataObject_version] => 1.0
[__table] => convention
[_database_dsn] =>
[_database_dsn_md5] => 3974043abbcc86412fb156a1d10b98377
[_database] => testing
[_condition] =>
[_group_by] =>
[_order_by] =>
[_limit] =>
[_data_select] => *
[_link_loaded] =>
[_lastError] =>
[id] => 1
[N] => 1
[_DB_resultid] => 3
[name] => ABCD XYZ
[sponsor_organization] => some sponser
[rpga_convention_code] => ABCD_XYZ
[web_site_url] => http://example.com
[last_modified] => 20020703143828
[room_id] => 1
)

[_last_modified] =>
)

** Note, This error: [message] => getLink:Could not find class for row last_modified, table last

is caused by the original link code using {tablename}_{colname} for guessing links, this automated
linking should be ignored, and not used, as it is depreciated.

Example with three tables join

<?php
/**
 * The following example show a three tables join.
 *
 * More joins can be nested as you see fit.
 */
$person = new DataObjects_Person;

$data = array();
if ($person->find()) {
    while ($person->fetch()) {
        $person->getLinks();
        // Following is another call to getLinks for the second join
        $person->_convention_id->getLinks();
        $data[] = $person->_convention_id->_room_id->ToArray();
    }
}

print_r($data);
?>

databasename.links.ini

; this ini file is for the three tables join example above.
[person]
person_id = convention:person_id

[room]
room_id = convention:room_id
Prev | DB_DataObject | Next
->getLink() | PEAR Manual | ->selectAs()


->selectAs()

->selectAs()

->selectAs() – Build the select component of a query (usually for joins)

Synopsis

void $DB_DataObject->selectAs ( object | array $columns_or_object , string $format , string $table_name )

Description

Auto creates select items based on either the current objects column names, the supplied object, or an array.

This is primarily used in conjunciton with joinAdd, to enable the renaming of columns into a fixed format when they are likely to have naming conflicts (like both tables have an 'id' column).

Sending no arguments to selectAs, will reset the current select (usually removing the default *), and build a select list based on the current objects column names.

Parameter

  • object | array $column_or_object - a dataobject or array of column names

  • string $format - the format the columns will appear, using sprintf format, the %s is replaced with the column name so car_%s would result in the SQL 'car.name as car_name' being generated.

  • string $tableName - this is used either when use send an array as the first argument, or when you are joining a table 'as' another name,

Note

This function can not be called statically.

Example

Using selectAs()

<?php
// ok lets see what is going on..
DB_DataObject::debugLevel(1);

$person = new DataObjects_Person;

// to generate "person.id as id , person.name as name ......."
$person->selectAs();

// to generate a restricted list.. "person.age as age , person.name as name"
$person->selectAs(array('age','name'));

// using another object.
$car = new DataObjects_Car;

// this is the first car (
$car->use = 'first';

// using the joinadd add the car..
$person->joinAdd($car);

// now add all the select columns for the car eg. "car.id as car_id, car.name as car_name ...."
$person->selectAs($car, 'car_%s');

// select only a few columns from the car table.
// note you have to use the table name at the end..
$person->selectAs(array('color','topspeed'), 'car_%s','car');

// now the user can have a second car....
$secondcar = new DataObjects_Car;
$secondcar->use = 'second';

// now since we alreay have one car, the sql statement would get messy
// so we are joining this as the second car "FROM person INNER JOIN car ..... , car as secondcar WHERE .....
$person->joinAdd($secondcar,'','secondcar');

// and we can now add all the columns
// "secondcar.id as secondcar_id, secondcar.name as secondcar_name ........
// note that you must use the last field as the SECONDCAR.ID format uses the 'AS' name, rather than the
// objects real table name 'car'
$person->selectAs($secondcar, 'secondcar_%s','secondcar');

// ok fire of a query...
$person->find();
while ($person->fetch()) {
  ......
}

?>
Prev | DB_DataObject | Next
->getLinks() | PEAR Manual | ->joinAdd()


->joinAdd()

->joinAdd()

->joinAdd() – add another dataobject to build a create join query

Synopsis

void $DB_DataObject->joinAdd ( object $dataobject , string $joinType , string $joinAs , string $joinCol )

Description

Builds a Join Query, by adding another dataobject to this one. Be careful when using this, raw queries may be clearer than using joinAdd.

Thanks to Stijn de Reede for the implementation of this.

Parameter

  • object $obj - joining object (no value resets the join)

  • string $joinType - "LEFT" | "INNER " | "RIGHT" | ""

    INNER is default, "" indicates just select ... from a,b,c with no join and links are added as where items.

    Note: 'LEFT' is the same as LEFT OUTER.

  • string $joinAs - if you want to select the table as anther name useful when you want to select multiple columns from a secondary table.

  • string $joinCol - The column on This objects table to match,needed if this table links to the child object in multiple places eg.

    using specific join Columns

user->friend (is a id of a person)
user->mother (is a id of another person)

Note

This function can not be called statically.

The Examples below are not tested, use DB_DataObject::debugLevel(1), to see what exactly is going on when you use this, and send the author some better examples..

Example

Simple simple Join

<?php
// (requires links.ini to be set up correctly)
// get all the images for product 24

$i = new DataObject_Image();
$pi = new DataObjects_Product_image();
$pi->product_id = 24; // set the product id to 24
$i->joinAdd($pi); // add the product_image connectoin
$i->find();
while ($i->fetch()) {
// do stuff
}
?>

Resulting SQL

SELECT * FROM image
LEFT JOIN product_image
ON (image.id = product_image.image_id)
WHERE product_image.id = 24

More Complex Join query

<?php
// an example with 2 joins
// get all the images linked with products or productgroups
$i = new DataObject_Image();
$pi = new DataObject_Product_image();
$pgi = new DataObject_Productgroup_image();
$i->joinAdd($pi);
$i->joinAdd($pgi);
$i->find();
while ($i->fetch()) {
// do stuff
}
?>

Resulting SQL

SELECT * FROM image
LEFT JOIN product_image
ON (image.id = product_image.image_id)
LEFT JOIN productgroup
ON (image.id = productgroup_image.image_id);
Prev | DB_DataObject | Next
->selectAs() | PEAR Manual | ->set*() and ->get*()


->set*() and ->get*()

->set*() and ->get*()

->set*() and ->get*() – Automatic Setters and Getters using overload

Synopsis

true | string $DB_DataObject->set* ( mixed $value )

mixed $DB_DataObject->get* ( )

Description

From version PHP 4.3.2RC2 onwards, DB_DataObject is automatically overloaded, providing access to all variables using $object->set{ColumnName}() and $object->set{ColumnName}($value) even if you have not defined the method.

It is assumed that set methods return strings as errors or TRUE, so that it can interact with setFrom and return array's of error strings.

The get Methods are used by toArray(), if defined they can be used to alter the appearance of columns ,like making dates human readable

The logic is very simple, if you call $object->setXXX() and it is not defined, it will just set the value, if you define a method setXXXX, that will be called instead of the default handler, same applies to getXXX().

Due to the naming conflict possiblity of a column named from, the associated method for column 'from' is set_from, rather than setFrom()

Parameter

  • mixed $value - on setters only (the value to assign to the column), on getters you may like to implement date formating or sprintf formating as the argument.

Return value

mixed - setters will return TRUE from the default method, in your implementations of setters. It is expected that setXXX($value) will return a string (the error) if it is invalid or TRUE on success. getXXX may return the value or a formated value, remember though it affects $object->toArray().

Note

This function can not be called statically.

Warning: This is experimental, its behavour may change slightly in the future.

Example

Simple find and fetch of data based on Object Vars

<?php
class DataObjects_Person extends DB_DataObject {

    var $id;
    var $name;
    var $date_of_birth;

    // you can define this method after you implement a call to it!
    // as it is automatically implemented to return $this->date_of_birth by
    // the overload __call() method.

    function getDate_of_Birth() {
        return date('d M Y', strtotime($this->date_of_birth));
    }
}

$person = new DataObjects_Person;

$person->get(12);

// now lets use the getters and setters even though some are not defined.
echo $person->getName() . ' was born on  ' . $person->getDate_of_Birth();
?>

Resulting Output

Fred Blogs was born on 1 April 1970
Prev | DB_DataObject | Next
->joinAdd() | PEAR Manual | ->setFrom()


->setFrom()

->setFrom()

->setFrom() – Copy items from Array or Object (for form posting)

Synopsis

boolean $DB_DataObject->setFrom ( array or object $from , string $format = '%s' , bool $skipEmpty = false )

Description

Copies items that are in the table definitions from an array or object into the current object (It will not override key values). This can be used to process form posts (if the field names match the database), or cloning similar objects.

You can not set the value of a key column using setFrom, It is silently ignored for security reasons. (you can still assign it manually)

setFrom will attempt to call the setters set{columnname} methods if they exist, It will also call fromValue(), which formats dates correctly.

You may realize that this method overlaps the overloaded method for the column name from, due to this, the associated methods for the column name 'from' are set_from and getFrom.

Parameter

  • array or Object $from - what to copy from

  • string $format - the format of the array or object variables and how they relate to this object. For example if your input array is in the format prefix_COLNAME, then you can use 'prefix_%s'.

  • bool $skipEmpty - If set to true, DB_DataObject will not assign empty values if a column is empty (eg. '' / 0 etc)

Return value

array or boolean - TRUE on success or an array of set*() return values in PHP4.3.2 upwards

Note

This function can not be called statically.

Example

Using setFrom()

<?php
// Person contains name,age
// $_POST contains 'name'=>'fred', 'age'=>'22'

$person = new DataObjects_Person;
$person->get(12);
$person->setFrom($_POST);
$person->update();

// or using the formating

// person contains name,age
// $_POST contains 'person_name'=>'fred', 'person_age'=>'22'

$person = new DataObjects_Person;
$person->get(12);
$ret = $person->setFrom($_POST,'person_%s');

// use the return value from setFrom to test for errors (PHP4.3.2)
if ($ret === true) {
  $person->update();
} else {
  // $ret is an array or strings..
  echo 'There were some errors: '  . implode(', ', $ret);
}

// or copying from another object
$personA = new DataObjects_Person;
$personA->get(12);

$personB = new DataObjects_Person;
$personB->get(14);

$personA->setFrom($personB);
$person->update();
?>
Prev | DB_DataObject | Next
->set*() and ->get*() | PEAR Manual | ->toArray()


->toArray()

->toArray()

->toArray() – Get an array of the current result

Synopsis

array $DB_DataObject->toArray ( string $format = '%s' , bool $hideEmpty = false )

Description

Allows the fetching of an associate array (with optional key formating) for use with other packages, like HTML_QuickForm.

From PHP4.2.3RC2 onwards, The values of each column are retrieved using getXXXX() methods so you can change the formating of a row by defining a getter method.

Parameter

  • string $format - a sprintf string eg. 'form[%s]'

  • bool $hideEmpty - If set to true, empty elements (no value/null) will not be returned

Note

This function can not be called statically.

Example

getting arrays

<?php
$person = new DataObjects_Person;
$person->get(2);
print_r($person->toArray());
print_r($person->toArray('user[%s]'));
print_r($person->toArray('user[%s]', true));
?>

Sample Output

Array
(
[id] => 2
[name] => test
[username] => username
[password] =>
[firstname] => jones
[lastname] =>
)

Array
(
[user[id]] => 2
[user[name]] => test
[user[username]] => username
[user[password]] =>
[user[firstname]] => jones
[user[lastname]] =>
)

Array
(
[user[id]] => 2
[user[name]] => test
[user[username]] => username
[user[firstname]] => jones
)
Prev | DB_DataObject | Next
->setFrom() | PEAR Manual | ->validate()


->validate()

->validate()

->validate() – check object data, and call objects validation methods.

Synopsis

array $DB_DataObject->validate ( )

Description

Check all the objects variables to see if they are valid, by default this means is a column an integer or string, if you define methods like validateEmail(), in your extended class then it will be called to validate the row called 'email'. This may be useful if called prior to an update or insert.., to generate error messages.

override this to set up your validation rules.

Return value

array - of validation results or TRUE

Note

This function can not be called statically.

the examples below utilize the PEAR validation package

Example

validate usage

<?php
$person = new DataObjects_Person;
$person->get(12);
$person->setFrom($_POST['input']);
$val = $person->validate();
if ($val === TRUE) {
  $person->update();
} else {
  foreach ($val as $k=>$v) {
    if ($v == false) {
      echo "There was something wrong with ($k)\n";
    } else {
      echo "($k) validated OK\n";
    }
  }
}
?>

validate methods

<?php
/* inside class DataObject_Person */
function validateEmail() {
  return Validate::email($this->email, true);
}

function validateHomepage() {
  return Validate::url($this->homepage, true);
}
function validateDate() {
  return Validate::date($this->date, "%d-%m-%Y", array(01,01,1970), array(01,01,2030));
?>
Prev | DB_DataObject | Next
->toArray() | PEAR Manual | ->tableName()


->tableName()

->tableName()

->tableName() – Get or set the table name of an object

Synopsis

object $DB_DataObject->tableName ( string $name )

Description

Without any argument, it returns the table name that the object deals with. With a string, it will set the table name for the instance of the object.

Note

This function can not be called statically.

Example

getting and setting the tablename

<?php
$person = new DataObjects_Person;
echo $person->tableName();
// echo's person

// now use the same object to query the extra_people table

$person->tableName('extra_people');
$person->id = 12;
$person->find(true);

// you can also use this in conjunction with table(), to create dataobjects for random tables..

$d = new DB_DataObject;
$d->tableName('person');
$d->table(array(
  'id'   => DB_DATAOBJECT_INT,
  'name' => DB_DATAOBJECT_STRING,
));
$d->keys(array('id'));

$d->id = 12;
$d->find(true);
// should do the same as above..!
?>
Prev | DB_DataObject | Next
->validate() | PEAR Manual | ->database()


->database()

->database()

->database() – Get or set the database the object uses

Synopsis

object $DB_DataObject->database ( string $name )

Description

Without any argument, it returns the database that the object deals with. With a string, it will set the database for the instance of the object.

Note

This function can not be called statically.

Example

Getting the database name

<?php
$person = new DataObjects_Person;
echo $person->database();
// echo's mydatabase

// now use the same object to check on a mirror..

$person->database('mirror1');
$person->id = 12;
$person->find(true);
?>
Prev | DB_DataObject | Next
->tableName() | PEAR Manual | ->table()


->table()

->table()

->table() – Get or set the table schema

Synopsis

object $DB_DataObject->table ( array $schema )

Description

Without any arguments, table() returns the table schema that the object deals with. With an array passed as the first argument, it will set the table schema for the current instance of the object.

The default schema is normally stored in the database.ini file described in the Autobuilding section.

Note

This function can not be called statically.

Example

getting the connection

<?php
$person = new DataObjects_Person;
print_r($person->table());
//
// array(
//     'id'     =>  1  // == DB_DATAOBJECT_INT
//     'name'   =>  2  // == DB_DATAOBJECT_STR
//     'bday'   =>  6  // == DB_DATAOBJECT_STR + DB_DATAOBJECT_DATE
//     'last'   =>  14 // == DB_DATAOBJECT_STR + DB_DATAOBJECT_DATE + DB_DATAOBJECT_TIME
//     'active' =>  17 // == DB_DATAOBJECT_INT + DB_DATAOBJECT_BOOL
//     'desc'   =>  34 // == DB_DATAOBJECT_STR + DB_DATAOBJECT_TXT
//     'photo'  =>  64 // == DB_DATAOBJECT_STR + DB_DATAOBJECT_BLOB
// )
//

// now use it to define a on the fly database table...

$d = new DB_DataObject;
$d->tableName('person');
$d->table(array(
  'id'   => DB_DATAOBJECT_INT,
  'name' => DB_DATAOBJECT_STRING,
));
$d->keys(array('id'));

$d->id = 12;
$d->find(true);
// should do the same as above..!
?>
Prev | DB_DataObject | Next
->database() | PEAR Manual | ->keys()


->keys()

->keys()

->keys() – Get or set the table keys

Synopsis

array $DB_DataObject->keys ( string $keys ... )

Description

Without any arguments, keys() returns an array of the keys used by the object (the generator builds these and guesses them based on finding things like primary key, unique, or nextval). Calling it with a value, or mulitple values, sets the keys for the current instance of the object.

The default keys are normally stored in the database.ini file described in the Autobuilding section.

Note

This function can not be called statically.

Example

getting the connection

<?php
$person = new DataObjects_Person;
print_r($person->keys());
//
// array(
//     0 => 'id',
// )
//

// now use it to define a on the fly database table...

$d = new DB_DataObject;
$d->tableName('person');
$d->table(array(
  'id'   => DB_DATAOBJECT_INT,
  'name' => DB_DATAOBJECT_STRING,
));
$d->keys('id');

// if you have multiple keys
// $d->keys('id','key2','key2');

$d->id = 12;
$d->find(true);
// should do the same as above..!
?>
Prev | DB_DataObject | Next
->table() | PEAR Manual | ->getDatabaseConnection()


->getDatabaseConnection()

->getDatabaseConnection()

->getDatabaseConnection() – Get the PEAR Database Object

Synopsis

object $DB_DataObject->getDatabaseConnection ( )

Description

Fetch the pear database connection that the object uses - so you can find information or send queries directly to it.

Note

This function can not be called statically.

Example

getting the connection

<?php
$person = new DataObjects_Person;
$db=  &$person->getDatabaseConnection();
echo $db->phptype;
?>

Sample Output

1000_monkeys
Prev | DB_DataObject | Next
->keys() | PEAR Manual | ->getDatabaseResult()


->getDatabaseResult()

->getDatabaseResult()

->getDatabaseResult() – Get the PEAR Database Result Object

Synopsis

object $DB_DataObject->getDatabaseResult ( )

Description

Fetch the pear database result object - so you can use it with things like the Pager or HTML_Select classes

Note

This function can not be called statically.

Example

getting the result object

<?php
$person = new DataObjects_Person;
$person->hair = 'green';
$person->selectAdd();
$person->selectAdd('id,name');
$person->find();

$res=  $person->getDatabaseResult();
$quickFormSelect->loadDbResult($res,'id','name');
?>
Prev | DB_DataObject | Next
->getDatabaseConnection() | PEAR Manual | DB_DataObject::debugLevel


DB_DataObject::debugLevel

DB_DataObject::debugLevel

DB_DataObject::debugLevel – set the amount of debugging output

Synopsis

void DB_DataObject::debugLevel ( integer $level )

Description

Sets and returns debug level. So you can see the queries and connections being built and executed.

Parameter

  • integer $level - level, without any parameters it will disable the debugging output. 1 give a general output, 5 includes things like passwords for connections.

Note

This function can not be called statically.

See

->debug()()

Example

Using debugLevel()

<?php
// turn debugging high
DB_DataObject::debugLevel(5);
$person = new DataObjects_Person;
$person->get(12);
$person->setFrom($_POST['input']);
$person->update();
// turn debugging off
DB_DataObject::debugLevel();
?>
Prev | DB_DataObject | Next
->getDatabaseResult() | PEAR Manual | ->debug()


->debug()

->debug()

->debug() – output debug information.

Synopsis

void $DB_DataObject->debug ( string $message , string $logPrefix , integer $level=1 )

Description

Debugger - you can use this in your extended classes to output debugging information. Uses DB_DataObject::DebugLevel(x) to turn it on, and can be completly turned off by using the production setting in the configuration file

Parameter

  • string $message - message to output

  • string $logPrefix - A bold prefix string

  • integer $level - output level, 1 is general, 5 tends to reveal things like database connection passwords..

Note

This function can not be called statically.

In production mode, the debugger is disabled

See

DB_DataObject::debugLevel()

Example

Setting the debugging level

<?php
$person = new DataObjects_Person;
$person->get(12);

// always prints
$person->debug('just got the person, about to set stuff', 'my application',0);
$person->setFrom($_POST['input']);

// only prints if debuglevel is set
$person->debug('just set the variables, about to update', 'my application',1);
$person->update();
?>
Prev | DB_DataObject | Next
DB_DataObject::debugLevel | PEAR Manual | DB_DataObject::raiseError


DB_DataObject::raiseError

DB_DataObject::raiseError

DB_DataObject::raiseError – throw an error

Synopsis

object DB_DataObject::raiseError ( int $message , resource $type = null , resource $behaviour = null )

Description

Default error handling is to create a PEAR::Error, but never return it. If you need to handle errors you should look at setting the PEAR_Error callback this is due to the fact it would wreck havoc on the internal methods!

Parameter

  • int $message - message

  • resource $type - type

  • resource $behaviour - behaviour (die or continue!);

Return value

object [unknown] -

Note

This function can not be called statically.

Prev | DB_DataObject | Next
->debug() | PEAR Manual | Casting - Dates, Blobs and Null


Casting - Dates, Blobs and Null

Casting - Dates, Blobs and Null

Casting - Dates, Blobs and Null – DB_DataObject_Cast ::date(), ::blob(), ::sql()

Dealing with Casting, (everything except strings and numbers)

This is experimental!, although it is documented, it currently only supports a limited amount of databases (send me fixes if you want it to support your favorite database), and the internal operations/API may change in the future..

DataObjects is a very easy way to work with databases that are focused on numbers and strings. You can also use it on date fields (although you must format your strings correctly), and you can use it with other types by using raw SQL query(), and the string value "null" is automatically converted to NULL in the database.

In an effort to provide a cleaner way to code to the richer database types, the DB_DataObject_Cast object was created. It's purpose is to simply create an object to represent some of the more unusual types. Below is an example of using it to create a few simple types.

Cast Objects can be used in both building queries, and assigning values

Cast Objects for building and assigning values

<?php

// using Cast Objects for building a query.

$person = DB_DataObject::factory('person');

// assign the value of birthday to a Cast object with a date.
$person->birthday =  DB_DataObject_Cast::date(2000,12,30);

$person->find();
while ($person->fetch()) {
    echo "{$person->name} has a birthday on 30 december 2002<BR>";
}

// use Cast Objects for assigning values.

$person = DB_DataObject::factory('person');
$person->get(12);

// set the persons's birthday to 30 december 2000
$person->birthday = DB_DataObject_Cast::date(2000,12,30);

// now update the database.
$person->update();

?>

As you can see, This component is in it"s infancy, so if you have any feature requests, ideas, please do not hesitate to contact me at alan_k at php dot net.

The blob and string type

Blobs are fields which can store large amounts of binary data in the databases.

At present only blobs is only supported in postgres using the bytea type. (please email me with code for other databases.)

Inserting a photo and a big text file

<?php

$person = DB_DataObject::factory('person');
$person->name = 'fred'

// use blob for binary data.
$person->photo =  DB_DataObject_Cast::blob(file_get_contents('xxx.jpg'));

// use string for textural data into a blob type.
$person->xmldocs =  DB_DataObject_Cast::string(file_get_contents('xxx.xml'));

// now insert into the database.
$person->insert();

?>

The date type

Most dates are stored in a database in ISO standard format, this method, allows you to create date types, from either Year,month,day, Human readable day/month/year, or standard iso format year-month-day. It fills in the remaining values based on simple rules.

Inserting a date in various formats

<?php

$person = DB_DataObject::factory('person');
$person->name = 'fred'

// use a human readable date

// full format
$person->birthday = new DB_DataObject_Cast::date('21/12/2003');

// use only a month/year - actually sets to 1 december 2003
$person->expires =  DB_DataObject_Cast::date('12/2003');

// use only a year only - actually sets to 1 jan 2003
$person->expires = DB_DataObject_Cast::date(2003);

// use a iso formated

// full formated
$person->birthday =  DB_DataObject_Cast::date('2003-12-21');

// use only a year-month - actually sets to 1 december 2003
$person->expires =  DB_DataObject_Cast::date('2003-12');

// using array syntax

// full formated
$person->birthday =  DB_DataObject_Cast::date(2003,12,21);

// use only a year-month  - actually sets to 1 december 2003
$person->expires =  DB_DataObject_Cast::date(2003,12);

// the real values are stored in object variables

echo $person->birthday->year; // prints 2003
echo $person->birthday->month; // prints 12
echo $person->birthday->day; // prints 21

// you can do simple date addition (similar to mktime)

$d = DB_DataObject_Cast::date('01/12/2003');

$nextMonth = DB_DataObject_Cast::date($d->year,$d->month+1,1);

?>

The sql type

Some types are sql specific, or may even be database specific, you can use the sql type to put raw strings as part of the sql statement.

using raw sql

<?php
$person = DB_DataObject::factory('person');
$person->get(12);

// set the birthday to null.
$person->birthday =  DB_DataObject_Cast::sql('NULL');

// do a sql cast statement (postgres specific)
$data = DB_DataObject_Cast::sql('cast("123123",datetime)');

// now insert into the database.
$person->insert();

?>
Prev | DB_DataObject | Next
DB_DataObject::raiseError | PEAR Manual | DB_DataObject_FormBuilder


DB_DataObject_FormBuilder

DB_DataObject_FormBuilder

A package for building HTML forms from DataObject classes.

For now, detailed documentation is available here.

You can view a presentation about FormBuilder here.

Table of Contents
  • Introduction -- A package for building HTML forms from DataObject classes
Prev | Database | Next
Casting - Dates, Blobs and Null | PEAR Manual | Introduction


Introduction

Introduction

Introduction – A package for building HTML forms from DataObject classes

DB_DataObject_FormBuilder Description

DB_DataObject_FormBuilder will aid you in rapid application development using the packages DB_DataObject and HTML_QuickForm. For having a quick but working prototype of your application, simply model the database, run DataObject createTable script over it and write a script that passes one of the resulting objects to the FormBuilder class. The FormBuilder will automatically generate a simple but working HTML_QuickForm object that you can use to test your application. It also provides a processing method that will automatically detect if an insert() or update( )command has to be executed after the form has been submitted. If you have set up DataObject links.ini file correctly, it will also automatically detect if a table field is a foreign key and will populate a selectbox with the linked tables entries. There are many optional parameters that you can place in your DataObjects.ini or in the properties of your derived classes, that you can use to fine-tune the form-generation, gradually turning the prototypes into fully-featured forms, and you can take control at any stage of the process. Basic usage:

<?php
$do =& new MyDataObject();
// Insert "$do->get($some_id);" here to edit an
// existing object instead of making a new one
$fg =& DB_DataObject_FormBuilder::create($do);
$form =& $fg->getForm();
if ($form->validate()) {
    $form->process(array(&$fg,'processForm'), false);
$form->freeze();
}
$form->display();
?>
Prev | DB_DataObject_FormBuilder | Next
DB_DataObject_FormBuilder | PEAR Manual | DB_NestedSet


DB_NestedSet

DB_NestedSet

With this package, one can easily create trees with infinite depth inside a relational database.

Table of Contents
  • Introduction -- Introduction to DB_NestedSet
  • DB_NestedSet::addListener -- Add an event listener
  • DB_NestedSet::apiVersion -- apiVersion
  • DB_NestedSet::convertTreeModel -- Convert a <1.3 tree into a 1.3 tree format
  • DB_NestedSet::createLeftNode -- Creates a node before a given node
  • DB_NestedSet::createRightNode -- Creates a node after a given node
  • DB_NestedSet::createRootNode -- Creates a new root node. If no id is specified then it is either added to the beginning/end of the tree based on the $pos.
  • DB_NestedSet::createSubNode -- Creates a subnode
  • DB_NestedSet::deleteNode -- Deletes a node
  • DB_NestedSet::factory -- Handles the returning of a concrete instance of DB_NestedSet based on the driver.
  • DB_NestedSet::getAllNodes -- Fetch the whole NestedSet
  • DB_NestedSet::getBranch -- Fetch the whole branch where a given node id is in
  • DB_NestedSet::getChildren -- Fetch the children _one level_ after of a node given by id
  • DB_NestedSet::getParent -- Fetch the immediate parent of a node given by id
  • DB_NestedSet::getParents -- Fetch the parents of a node given by id
  • DB_NestedSet::getRootNodes -- Fetches the first level (the rootnodes) of the NestedSet
  • DB_NestedSet::getSiblings -- Fetch all siblings of the node given by id Important: The node given by ID will also be returned Do a unset($array[$id]) on the result if you don't want that
  • DB_NestedSet::getSubBranch -- Fetch all the children of a node given by id
  • DB_NestedSet::isParent -- See if a given node is a parent of another given node
  • DB_NestedSet::moveTree -- Wrapper for node moving and copying
  • DB_NestedSet::pickNode -- Fetch the data of a node with the given id
  • DB_NestedSet::removeListener -- Removes an event listener
  • DB_NestedSet::setAttr -- Sets an object attribute
  • DB_NestedSet::setDbOption -- Sets a db option. Example, setting the sequence table format
  • DB_NestedSet::setsortMode -- This enables you to set specific options for each output method
  • DB_NestedSet::testLock -- Tests if a database lock is set
  • DB_NestedSet::triggerEvent -- Triggers and event an calls the event listeners
  • DB_NestedSet::updateNode -- Changes the payload of a node
Prev | Database | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to DB_NestedSet

Overview

With this package, one can easily create trees with infinite depth inside a relational database. The package provides a way to

  • create/update/delete nodes

  • query nodes, trees and subtrees

  • copy (clone) nodes, trees and subtrees

  • move nodes, trees and subtrees

  • etc.

An example

Creates some root and subnodes

In this example, one rootnode and two subnodes are created, saved to the database and displayed.

<?php
require_once 'DB/NestedSet.php';
require_once 'DB/NestedSet/Output.php';
require_once 'HTML/Menu.php';
$DatabasePointer = mysql_connect("localhost", "user", "pwd");
mysql_select_db("database", $DatabasePointer);
$dsn = 'mysql://user:pwd@localhost/database';
// needed colums in table:
$params = array(
    'id'        => 'id',
    'parent_id' => 'rootid',
    'left_id'   => 'l',
    'right_id'  => 'r',
    'order_num' => 'norder',
    'level'     => 'level',
    'name'      => 'name',
);
$nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
$nestedSet->setAttr(array(
        'node_table' => 'nested_set',
        'lock_table' => 'nested_set_locks',
        'secondarySort' => 'name',
    )
);
$parent = $nestedSet->createRootNode(array('name' =>'root 1'), false, true);
$nestedSet->createSubNode($parent, array('name' => 'node 1.1'));
$nestedSet->createSubNode($parent, array('name' =>'node 1.2'));
$data = $nestedSet->getAllNodes(true);

foreach ($data as $id => $node) {
     $data[$id]['url'] = 'index.php?nodeID=' . $node['id'];
}

$params = array(
    'structure' => $data,
    'titleField' => 'name',
    'urlField' => 'url');
$output =& DB_NestedSet_Output::factory($params, 'Menu');
$structure = $output->returnStructure();
$menu = & new HTML_Menu($structure, 'sitemap');
$menu->forceCurrentUrl($currentUrl);
$menu->show();
?>
Prev | DB_NestedSet | Next
DB_NestedSet | PEAR Manual | DB_NestedSet::addListener


DB_NestedSet::addListener

DB_NestedSet::addListener

DB_NestedSet::addListener() – Add an event listener

Synopsis

require_once 'DB/NestedSet.php';

string DB_NestedSet::addListener ( string $event , &$listener , string $listener )

Description

Adds an event listener and returns an ID for it Known events are
nodeCreate
nodeDelete
nodeUpdate
nodeCopy
nodeLoad

Parameter

string $event

The event name

string $listener

The listener object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Add Listener

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->AddListener("nodeCreate", "listener");
?>
Prev | DB_NestedSet | Next
Introduction | PEAR Manual | DB_NestedSet::apiVersion


DB_NestedSet::apiVersion

DB_NestedSet::apiVersion

DB_NestedSet::apiVersion() – apiVersion

Synopsis

require_once 'DB/NestedSet.php';

void DB_NestedSet::apiVersion ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get API-version

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->apiVersion();
?>
Prev | DB_NestedSet | Next
DB_NestedSet::addListener | PEAR Manual | DB_NestedSet::convertTreeModel


DB_NestedSet::convertTreeModel

DB_NestedSet::convertTreeModel

DB_NestedSet::convertTreeModel() – Convert a <1.3 tree into a 1.3 tree format

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::convertTreeModel ( &$orig , &$copy , integer $_parent = false , object $ )

Description

This will convert the tree into a format needed for some new features in 1.3. Your <1.3 tree will still work without converting but some new features like preorder sorting won't work as expected.

Usage:
- Create a new node table (tb_nodes2) from the current node table (tb_nodes1) (only copy the structure).
- Create a nested set instance of the 'old' set (NeSe1) and one of the new set (NeSe2)
- Now you have 2 identical objects where only node_table differs
- Call DB_NestedSet::convertTreeModel(&$orig, &$copy);
- After that you have a cleaned up copy of tb_nodes1 inside tb_nodes2

Parameter

&$orig

&$copy

integer $_parent

ID of the parent node (private)

object $copy

Object where the new tree is copied to

Return value

returns True uns success

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | DB_NestedSet | Next
DB_NestedSet::apiVersion | PEAR Manual | DB_NestedSet::createLeftNode


DB_NestedSet::createLeftNode

DB_NestedSet::createLeftNode

DB_NestedSet::createLeftNode() – Creates a node before a given node

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::createLeftNode ( int $id , array $values , bool $returnID )

Description

+-- root1
|
+-\ root2
| |
| |-- subnode2 [new]
| |-- subnode1 [target]
| |-- subnode3
|
+-- root3

Parameter

integer $id

Target node ID

array $values

Hash with param => value pairs of the node (see $this->params)

boolean $returnID

Tell the method to return a node id instead of an object. ATTENTION: That the method defaults to return an object instead of the node id has been overseen and is basically a bug. We have to keep this to maintain BC. You will have to set $returnID to TRUE to make it behave like the other creation methods. This flaw will get fixed with the next major version.

Return value

returns The node id or false on error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Create left node

Firstly, we connect to NestedSet using Factory. Then we create some nodes and finally we create a LeftNode. The LeftNode will be placed leftsided to the first root-node.

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->createSubNode($parent, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent, array('name' => 'sub2'));
    $nestedSet->createLeftNode($parent, array('name' => 'left node'), true);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::convertTreeModel | PEAR Manual | DB_NestedSet::createRightNode


DB_NestedSet::createRightNode

DB_NestedSet::createRightNode

DB_NestedSet::createRightNode() – Creates a node after a given node

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::createRightNode ( int $id , array $values , bool $returnID )

Description

+-- root1
|
+-\ root2
| |
| |-- subnode1 [target]
| |-- subnode2 [new]
| |-- subnode3
|
+-- root3

Parameter

integer $id

Target node ID

array $values

Hash with param => value pairs of the node (see $this->params)

boolean $returnID

Tell the method to return a node id instead of an object. ATTENTION: That the method defaults to return an object instead of the node id has been overseen and is basically a bug. We have to keep this to maintain BC. You will have to set $returnID to TRUE to make it behave like the other creation methods. This flaw will get fixed with the next major version.

Return value

returns The node id or false on error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Create right node

Firstly, we connect to NestedSet using Factory. Then we create some nodes and finally we create a RightNode. The RightNode will be placed rightsided to the first root-node.

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->createSubNode($parent, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent, array('name' => 'sub2'));
    $nestedSet->createRightNode($parent, array('name' => 'right node'), true);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::createLeftNode | PEAR Manual | DB_NestedSet::createRootNode


DB_NestedSet::createRootNode

DB_NestedSet::createRootNode

DB_NestedSet::createRootNode() – Creates a new root node. If no id is specified then it is either added to the beginning/end of the tree based on the $pos.

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::createRootNode ( array $values , integer $id = false , bool $first = false , string $pos = NESE_MOVE_AFTER )

Description

Optionally it deletes the whole tree and creates one initial rootnode

+-- root1 [target]
|
+-- root2 [new]
|
+-- root3

Parameter

array $values

Hash with param => value pairs of the node (see $this->params)

integer $id

ID of target node (the rootnode after which the node should be inserted)

boolean $first

Danger: Deletes and (re)inits the whole tree - sequences are reset

string $pos

The position in which to insert the new node.

Return value

returns The node id or false on error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Create rootnodes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->createRootNode(array('name' => 'rootnode'), false, true);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::createRightNode | PEAR Manual | DB_NestedSet::createSubNode


DB_NestedSet::createSubNode

DB_NestedSet::createSubNode

DB_NestedSet::createSubNode() – Creates a subnode

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::createSubNode ( integer $id , array $values )

Description

+-- root1
|
+-\ root2 [target]
| |
| |-- subnode1 [new]
|
+-- root3

Parameter

integer $id

Parent node ID

array $values

Hash with param => value pairs of the node (see $this->params)

Return value

returns The node id or false on error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Create subnodes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'rootnode'), false, true);
    $nestedSet->createSubNode($parent, array('name' => "node"));
?>
Prev | DB_NestedSet | Next
DB_NestedSet::createRootNode | PEAR Manual | DB_NestedSet::deleteNode


DB_NestedSet::deleteNode

DB_NestedSet::deleteNode

DB_NestedSet::deleteNode() – Deletes a node

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::deleteNode ( int $id )

Description

This package is not documented yet.

Parameter

integer $id

ID of the node to be deleted

Return value

returns True if the delete succeeds

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Delete nodes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->deleteNode($id);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::createSubNode | PEAR Manual | DB_NestedSet::factory


DB_NestedSet::factory

DB_NestedSet::factory

DB_NestedSet::factory() – Handles the returning of a concrete instance of DB_NestedSet based on the driver.

Synopsis

require_once 'DB/NestedSet.php';

object The& DB_NestedSet::factory ( string $driver , string $dsn , array $params = array() )

Description

If the class given by $driver allready exists it will be used. If not the driver will be searched inside the default path ./NestedSet/

Parameter

string $driver

The driver, such as DB or MDB

string $dsn

The dsn for connecting to the database

array $params

The field name params for the node table

Return value

returns DB_NestedSet object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Factory

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::deleteNode | PEAR Manual | DB_NestedSet::getAllNodes


DB_NestedSet::getAllNodes

DB_NestedSet::getAllNodes

DB_NestedSet::getAllNodes() – Fetch the whole NestedSet

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getAllNodes ( bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get all nodes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->createSubNode($parent, array('name' => 'sub1');
    $nestedSet->createSubNode($parent, array('name' => 'sub2');
    $data = $nestedSet->getAllNodes(true);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::factory | PEAR Manual | DB_NestedSet::getBranch


DB_NestedSet::getBranch

DB_NestedSet::getBranch

DB_NestedSet::getBranch() – Fetch the whole branch where a given node id is in

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getBranch ( int $id , bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

integer $id

The node ID

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get Branch

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $parent2 = $nestedSet->createSubNode($parent, array('name' => 'sub-node));
    $nestedSet->createSubNode($parent2, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent2, array('name' => 'sub2));
    $data = getBranch($parent2);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getAllNodes | PEAR Manual | DB_NestedSet::getChildren


DB_NestedSet::getChildren

DB_NestedSet::getChildren

DB_NestedSet::getChildren() – Fetch the children _one level_ after of a node given by id

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getChildren ( int $id , bool $keepAsArray = false , bool $aliasFields = true , bool $forceNorder = false , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

integer $id

The node ID

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

boolean $forceNorder

(optional) Force the result to be ordered by the norder param (as opposed to the value of secondary sort). Used by the move and add methods.

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get Children

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $parent2 = $nestedSet->createSubNode($parent, array('name' => 'sub-node));
    $nestedSet->createSubNode($parent2, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent2, array('name' => 'sub2));
    $data = $nestedSet->getChildren($parent2);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getBranch | PEAR Manual | DB_NestedSet::getParent


DB_NestedSet::getParent

DB_NestedSet::getParent

DB_NestedSet::getParent() – Fetch the immediate parent of a node given by id

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getParent ( int $id , bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() , $useDB = true )

Description

This package is not documented yet.

Parameter

integer $id

The node ID

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

$useDB

Return value

returns False on error, or the parent node

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get Parent

Fetch the immediate parent of a node given by id. GetParent will return $parent2 as $data.

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $parent2 = $nestedSet->createSubNode($parent, array('name' => 'sub-node));
    $nestedSet->createSubNode($parent2, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent2, array('name' => 'sub2));
    $data = $nestedSet->getParent($parent2);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getChildren | PEAR Manual | DB_NestedSet::getParents


DB_NestedSet::getParents

DB_NestedSet::getParents

DB_NestedSet::getParents() – Fetch the parents of a node given by id

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getParents ( int $id , bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

integer $id

The node ID

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get Parents

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $parent2 = $nestedSet->createSubNode($parent, array('name' => 'sub-node));
    $parent3 = $nestedSet->createSubNode($parent2, array('name' => 'sub-node'));
    $nestedSet->createSubNode($parent3, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent3, array('name' => 'sub2));
    $data = $nestedSet->getParents($parent3);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getParent | PEAR Manual | DB_NestedSet::getRootNodes


DB_NestedSet::getRootNodes

DB_NestedSet::getRootNodes

DB_NestedSet::getRootNodes() – Fetches the first level (the rootnodes) of the NestedSet

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getRootNodes ( bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get Rootnodes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->createSubNode($parent, array('name' => 'sub1'));
    $parent2 = $nestedSet->createRootNode($parent, array('name' => 'sub-node), '1', false);
    $nestedSet->createSubNode($parent2, array('name' => 'sub2));
    $data = $nestedSet->getRootNodes();
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getParents | PEAR Manual | DB_NestedSet::getSiblings


DB_NestedSet::getSiblings

DB_NestedSet::getSiblings

DB_NestedSet::getSiblings() – Fetch all siblings of the node given by id Important: The node given by ID will also be returned Do a unset($array[$id]) on the result if you don't want that

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getSiblings ( int $id , bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

integer $id

The node ID

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or the parent node

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get Siblings

<?php
require_once 'DB/NestedSet.php';
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $node = $nestedSet->createSubNode($parent, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent, array('name' => 'sub2'));
    $nestedSet->createSubNode($parent, array('name' => 'sub3'));
    $data = $nestedSet->getSiblings($node);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getRootNodes | PEAR Manual | DB_NestedSet::getSubBranch


DB_NestedSet::getSubBranch

DB_NestedSet::getSubBranch

DB_NestedSet::getSubBranch() – Fetch all the children of a node given by id

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::getSubBranch ( string $id , bool $keepAsArray = false , bool $aliasFields = true , array $addSQL = array() )

Description

getChildren only queries the immediate children getSubBranch returns all nodes below the given node

Parameter

string $id

The node ID

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get SubBranch

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $parent2 = $nestedSet->createSubNode($parent, array('name' => 'sub-node));
    $parent3 = $nestedSet->createSubNode($parent2, array('name' => 'sub-node));
    $nestedSet->createSubNode($parent3, array('name' => 'sub1'));
    $nestedSet->createSubNode($parent3, array('name' => 'sub2'));
    $data = $nestedSet->getSubBranch($parent2);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getSiblings | PEAR Manual | DB_NestedSet::isParent


DB_NestedSet::isParent

DB_NestedSet::isParent

DB_NestedSet::isParent() – See if a given node is a parent of another given node

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::isParent ( mixed $parent , mixed $child )

Description

A node is considered to be a parent if it resides above the child So it doesn't mean that the node has to be an immediate parent. To get this information simply compare the levels of the two nodes after you know that you have a parent relation.

Parameter

mixed $parent

The parent node as array or object

mixed $child

The child node as array or object

Return value

returns True if it's a parent

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

IsParent

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'));
    $node = $nestedSet->createSubNode($parent, array('name' => 'sub1'));
    $boolparent = $nestedSet->isParent($parent, $node);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::getSubBranch | PEAR Manual | DB_NestedSet::moveTree


DB_NestedSet::moveTree

DB_NestedSet::moveTree

DB_NestedSet::moveTree() – Wrapper for node moving and copying

Synopsis

require_once 'DB/NestedSet.php';

int DB_NestedSet::moveTree ( int $id , $targetid , constant $pos , bool $copy = false , int $target )

Description

This package is not documented yet.

Parameter

integer $id

Source ID

$targetid

Target ID

constant $pos

Position (use one of the NESE_MOVE_* constants)

boolean $copy

Shall we create a copy

integer $target

Target ID

Return value

returns ID of the moved node or false on error

See

see _moveInsideLevel

see _moveRoot2Root

see _moveAcross

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Get SubBranch

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $parent2 = $nestedSet->createSubNode($parent, array('name' => 'sub-node));
    $parent3 = $nestedSet->createSubNode($parent2, array('name' => 'sub-node));
    $nestedSet->createSubNode($parent3, array('name' => 'sub1'));
    $node = $nestedSet->createSubNode($parent3, array('name' => 'sub2'));
    $nestedSet->moveTree($node, $parent, NESE_MOVE_AFTER);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::isParent | PEAR Manual | DB_NestedSet::pickNode


DB_NestedSet::pickNode

DB_NestedSet::pickNode

DB_NestedSet::pickNode() – Fetch the data of a node with the given id

Synopsis

require_once 'DB/NestedSet.php';

mixed DB_NestedSet::pickNode ( int $id , bool $keepAsArray = false , bool $aliasFields = true , string $idfield = 'id' , array $addSQL = array() )

Description

This package is not documented yet.

Parameter

integer $id

The node id of the node to fetch

boolean $keepAsArray

(optional) Keep the result as an array or transform it into a set of DB_NestedSet_Node objects?

boolean $aliasFields

(optional) Should we alias the fields so they are the names of the parameter keys, or leave them as is?

string $idfield

(optional) Which field has to be compared with $id? This is can be used to pick a node by other values (e.g. its name).

array $addSQL

(optional) Array of additional params to pass to the query.

Return value

returns False on error, or an array of nodes

See

see _addSQL

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Pick Node

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $parent = $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->createSubNode($parent, array('name' => 'sub1'));
    $data = $nestedSet->getBranch($id);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::moveTree | PEAR Manual | DB_NestedSet::removeListener


DB_NestedSet::removeListener

DB_NestedSet::removeListener

DB_NestedSet::removeListener() – Removes an event listener

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::removeListener ( string $event , string $listenerID )

Description

Removes the event listener with the given ID

Parameter

string $event

The ivent name

string $listenerID

The listener's ID

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Remove Listener

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->AddListener("nodeCreate", "listener");
    $nestedSet->RemoveListener("nodeCreate", "listener");
?>
Prev | DB_NestedSet | Next
DB_NestedSet::pickNode | PEAR Manual | DB_NestedSet::setAttr


DB_NestedSet::setAttr

DB_NestedSet::setAttr

DB_NestedSet::setAttr() – Sets an object attribute

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::setAttr ( array $attr )

Description

This package is not documented yet.

Parameter

array $attr

An associative array with attributes

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Set attributes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->setAttr(array(
        'node_table' => 'nested_set',
        'lock_table' => 'nested_set_locks',
       'secondarySort' => 'name'
        )
    );
?>
Prev | DB_NestedSet | Next
DB_NestedSet::removeListener | PEAR Manual | DB_NestedSet::setDbOption


DB_NestedSet::setDbOption

DB_NestedSet::setDbOption

DB_NestedSet::setDbOption() – Sets a db option. Example, setting the sequence table format

Synopsis

require_once 'DB/NestedSet.php';

void DB_NestedSet::setDbOption ( $option , $val )

Description

This package is not documented yet.

Parameter

$option

$val

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | DB_NestedSet | Next
DB_NestedSet::setAttr | PEAR Manual | DB_NestedSet::setsortMode


DB_NestedSet::setsortMode

DB_NestedSet::setsortMode

DB_NestedSet::setsortMode() – This enables you to set specific options for each output method

Synopsis

require_once 'DB/NestedSet.php';

Current DB_NestedSet::setsortMode ( constant $sortMode = false )

Description

This package is not documented yet.

Parameter

constant $sortMode

Return value

returns sortMode

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | DB_NestedSet | Next
DB_NestedSet::setDbOption | PEAR Manual | DB_NestedSet::testLock


DB_NestedSet::testLock

DB_NestedSet::testLock

DB_NestedSet::testLock() – Tests if a database lock is set

Synopsis

require_once 'DB/NestedSet.php';

void DB_NestedSet::testLock ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Test lock

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->testLock();
?>
Prev | DB_NestedSet | Next
DB_NestedSet::setsortMode | PEAR Manual | DB_NestedSet::triggerEvent


DB_NestedSet::triggerEvent

DB_NestedSet::triggerEvent

DB_NestedSet::triggerEvent() – Triggers and event an calls the event listeners

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::triggerEvent ( string $event , &$node , array $eparams = false , object $ )

Description

This package is not documented yet.

Parameter

string $event

The Event that occured

&$node

Node

array $eparams

A associative array of params which may be needed by the handler

object $node

A Reference to the node object which was subject to changes

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Trigger Event

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->AddListener("nodeCreate", "listener");
    $parent = $nestedSet->createRootNode(array('name' => 'rootnode'), false, true);
    $node = $nestedSet->createSubNode($parent, array('name' => "node"));
    $nestedSet->TriggerEvent("nodeDelete", $node);
?>
Prev | DB_NestedSet | Next
DB_NestedSet::testLock | PEAR Manual | DB_NestedSet::updateNode


DB_NestedSet::updateNode

DB_NestedSet::updateNode

DB_NestedSet::updateNode() – Changes the payload of a node

Synopsis

require_once 'DB/NestedSet.php';

bool DB_NestedSet::updateNode ( int $id , array $values , $_internal = false , bool $_intermal )

Description

This package is not documented yet.

Parameter

integer $id

Node ID

array $values

Hash with param => value pairs of the node (see $this->params)

$_internal

Internal use only.

boolean $_intermal

Internal use only. Used to skip value validation. Leave this as it is.

Return value

returns True if the update is successful

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Update nodes

<?php
require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->createSubNode($id, array('name' => "rootnode"));
    $nestedSet->updateNode($id, array('name' => "new name"));
?>
Prev | DB_NestedSet | Next
DB_NestedSet::triggerEvent | PEAR Manual | DB_Pager


DB_Pager

DB_Pager

DB_Pager handles all the stuff needed for displaying paginated results from a db query of PEAR::DB, including fetching only the needed rows and giving extensive information for helping build an HTML or GTK query result display.

NB: This package is deprecated in favour of the Pager package. In particular, have a look at the Pager_Wrapper example included with Pager, and read this paragraph or this tutorial.

Prev | Database | Next
DB_NestedSet::updateNode | PEAR Manual | DB_QueryTool


DB_QueryTool

DB_QueryTool

This package is an OO-abstraction to the SQL-Query language, it provides methods such as setWhere, setOrder, setGroup, setJoin, etc. to easily build queries.

This package has been superseded. Please use MDB_QueryTool for new projects.

Table of Contents
  • Introduction -- An OO-interface for easily retrieving and modifying data in a database
Prev | Database | Next
DB_Pager | PEAR Manual | Introduction


Introduction

Introduction

Introduction – An OO-interface for easily retrieving and modifying data in a database

DB_QueryTool Description

This package is an OO-abstraction to the SQL-Query language, it provides methods such as setWhere, setOrder, setGroup, setJoin, etc. to easily build queries. It also provides an easy to learn interface that interacts nicely with HTML-forms using arrays that contain the column data, that shall be updated/added in a database. This package bases on an SQL-Builder which lets you easily build SQL-Statements and execute them.

You can find some useful usage examples and docs in the MDB_QueryTool documentation. Everything there holds true for DB_QueryTool too, except for the class name, of course.

Prev | DB_QueryTool | Next
DB_QueryTool | PEAR Manual | DB_Table


DB_Table

DB_Table

An object-oriented interface to a database

Table of Contents
  • Introduction -- Overview of the DB_Table package.
  • DB_Table Class Tutorial -- Interface to a single table
  • DB_Table Forms Tutorial -- Creating HTML_QuickForm forms
  • DB_Table_Database Class Tutorial -- Interface to a relational database
  • DB_Table_Generator Class Tutorial -- Code generation for an existing database
  • DB_Table Data Types -- Abstract data types used in DB_Table column definitions
Prev | Database | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Overview of the DB_Table package.

Description

The DB_Table package provides an object oriented interface to a database. It contains three main classes:

  • DB_Table - interface to and model of a single database table.

  • DB_Table_Database - interface to and model of a relational database.

  • DB_Table_Generator - code generation for an existing database.

The package grew around the DB_Table class, which was written by Paul M. Jones. The Database and Generator class were added in releases 1.5.0RC1 and 1.5.0RC2, respectively. These manual pages document release 1.5.0.

The properties of the core DB_Table class contain the schema for a table, defined using portable data types. The class methods provides a convenient API for constructing and submitting INSERT, UPDATE, DELETE, and SELECT SQL commands, and for creation of a RDBMS database table from the defined schema. Simple data type validation is provided for data to be inserted or updated. The class provides methods to automatically generate HTML_QuickForm input forms that match the column definitions.

Each instance of DB_Table_Database contains a model of relationships between tables in a database, in which each table is represented by an instance of DB_Table. The autoJoin() method can automatically construct join conditions for queries that join any number of tables. The class also provides optional PHP validation of foreign key validity, and optional PHP emulation of actions triggered on delete or update of referenced rows, such as cascading deletes.

The DB_Table_Generator class may be used to automatically generate the PHP code necessary to use the DB_Table package as an interface to an existing database. It is used (if at all) only during set-up of the interface for a database.

Each of these three classes is discussed in a separate tutorial in the following manual pages.

Prev | DB_Table | Next
DB_Table | PEAR Manual | DB_Table Class Tutorial


DB_Table Class Tutorial

DB_Table Class Tutorial

DB_Table Class Tutorial – Interface to a single table

Description

This tutorial uses an extended example to introduce the use of the DB_Table class as an interface to a single database table. This class provides:

  • Column and index definitions embedded in the object properties, using portable data types.

  • Creation or verification of the table from the declared schema.

  • Simplified API for SELECT, INSERT, UPDATE, and DELETE commands.

  • Array syntax for SELECT commands, and stored baseline queries.

  • Data type validation for inserted/updated column values

  • Auto-increment emulation

  • Automated creation of HTML_QuickForm elements from the column definitions.

This class tutorial contains two manual pages: This page documents all of the features of DB_Table except those involving HTML_Quick form generation, which are discussed in the next page. The tutorial is based closely upon the original external documentation for DB_Table, by Paul M. Jones, which is still available here. The original documentation includes some examples of how to customize a DB_Table subclass definition that are not included here.

The DB_Table and DB_Table_Database classes both extend an abstract base class named DB_Table_Base. Methods and properties that are inherited from DB_Table_Base are thus available via either a DB_Table or a DB_Table_Database object, with the same interface. These shared methods and properties will be identified as such in these manual pages.

  • Extending DB_Table

    • Defining columns

    • Defining indices

    • Declaring an auto-increment column

  • DB_Table Constructor

  • Modifying Data: insert, update and delete

    • insert() - Inserting rows of data

    • Auto-increment and sequences

    • update() - Updating rows of data

    • delete() - Deleting rows of data

  • Selecting Data

    • Query Arrays

    • Storing Queries: $this->sql

    • Submitting Queries: select*() methods

  • Data Type Validation

  • Miscellaneous Utility Methods

    • quote()

    • recast()

    • getBlankRow()

Extending DB_Table

You generally do not usually create instances of DB_Table directly. Instead, for each table in a database, you define a a subclass of DB_Table, and instantiate one object of that subclass. The table schema is embedded in the properties of that object: column definitions are declared in the $col property array and indices in the $idx property array. Normally, the values of these property arrays are defined as part of the subclass definition, which thus serves as a record of the table schema.

One advantage of any database gateway that associates a class with each RDBMS table is that the subclass definition provides a natural place to specify properties and behaviors that are specific to that table. Custom behaviors and validations may be implemented by overriding the class methods, or by defining new methods. DB_Table also allows commonly used or baseline SELECT queries to be stored in the $sql property array.

The package provides two ways to create both a RDBMS table and a corresponding DB_Table subclass, without writing redundant specifications:

  • Programmatic table creation: Write a DB_Table subclass definition for each table, and use an instance of that subclass to create the actual database table.

  • Reflection and code generation: Use the DB_Table_Generator class to automatically generate skeleton DB_Table subclass definitions, and related glue code, for an existing database.

In this tutorial, we demonstrate the former method, which requires us to write subclass definitions manually. A discussion of the latter method is given in the DB_Table_Generator class tutorial.

Defining Columns

The $col property is an associative array in which each key is a column name, and each value is an associative array containing a column definition. The value of the required 'type' element of a column definition must be the name of one of the DB_Table data types, e.g., 'integer', 'decimal', 'boolean', etc. The 'char' and 'varchar' string types, and the 'decimal' numerical type, all require a 'size' element, for which the value is an integer number of characters or digits. The 'decimal' type also requires a 'scope' element, which is the number of digits after the decimal point. A 'require' element with a boolean true value is equivalent to NOT NULL in SQL, and indicates that NULL values are not allowed in that column.

As an example, let's say we're going to create a GuestBook table. This table will store the first and last name of visitors, their email address, and the date and time they signed the guestbook. In addition, we're going to want a unique ID for each row. The columns in our table will be:

  • id -- a sequential integer that is unique for every row (required; i.e., no nulls allowed)

  • fname -- a string of up to 32 characters, the first name of the visitor

  • lname -- a string of up to 64 characters, the last name of the visitor

  • email -- a string of up to 255 characters, the visitor's email address (required; i.e., no nulls allowed)

  • signdate -- a date for when the visitor signed the guestbook (required; i.e., no nulls allowed)

These column definitions must be declared in the $col property array. Shown below is the required declaration of $col for a subclass of DB_Table, named GuestBook_Table, that is associated with a database table named GuestBook:

GuestBook column definitions

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(

        // unique row ID
        'id' => array(
            'type'    => 'integer',
            'require' => true
        ),

        // first name
        'fname' => array(
            'type' => 'varchar',
            'size' => 32
        ),

        // last name
        'lname' => array(
            'type' => 'varchar',
            'size' => 64
        ),

        // email address
        'email' => array(
            'type' => 'varchar',
            'size' => 128,
            'require' => true
        ),

        // date signed
        'signdate' => array(
            'type' => 'date',
            'require' => true)
     );
?>

Defining Indices

The $idx property array is used to declare indices. Each index can be declared to be of type 'primary', 'unique', or 'normal'. Primary and unique indices both define constraints that require that each key value be unique within the table. Normal indices are introduced purely for efficiency. Both single- and multi-column indices may be defined.

In our GuestBook example, we want two single column indices: First, we will define a primary index for the "id" identifier column. Second, for purposes of the example, we'll define a normal index on the "signdate" column, because we expect to search for visitors by date and time. The required $idx property declaration is given below:

Index Definitions for GuestBook

<?php

class GuestBook_Table extends DB_Table
{

    // Column definitions - see above
    // var $col = array(...);

    // Index definitions
    var $idx = array(

        'id' => array(
            'type' => 'primary',
            'cols' => 'id'
        ),

        'signdate' => array(
            'type' => 'normal',
            'cols' => 'signdate'
        )
    );
}
?>

The key of each element in the $idx array is an index name, and the value is generally an array containing a definition for the index. An index definition array must contain a 'type' element, for which the value must be 'primary', 'unique' or 'normal', and 'cols' element. The value of 'cols' element must be either the name of a single column, for a single-column array, or a sequential array of column names, for a multi-column index. There is also an alternative shorthand syntax for single-column indices, which is discussed below.

As an example of a multi-column index, here is the definition for a multi-column index named "namefl" on the fname and lname columns.

Defining A Multi-Column Index

<?php

class GuestBook_Table extends DB_Table
{
    // Column definitions
    // var $col = array( ... )

    // Index definitions
    var $idx = array(

            // above single-column indices, plus

            'namefl' = array(
                'type' => 'normal',
                'cols' => array('fname', 'lname')
            )
        );
}
?>

There is also a shorthand way to declare a single-column index: If you want single-column index for which the index name is the same as the column name, use the column name as the key of $idx, and the index type string (rather than an index definition array) as the value.

Shorthand for Single-Column Indices:

<?php

class GuestBook_Table extends DB_Table
{

    // Column definitions
    // var $col = array(...);

    // Index definitions
    var $idx = array(

        // primary index called 'id' based on the 'id' column
        'id' => 'primary',

        // normal index called 'signdate' based on the 'signdate' column
        'signdate' => 'normal'

    );
}
?>

Declaring an Auto-Increment Column

One integer column of each table may be declared to be an auto-increment column. This column is normally a primary key identifier. The only effect of this declaration is to change the behavior of the insert() method: If the insert() method is used to insert a row in which the value of an auto-increment column is not set or NULL, then an auto-incremented integer will be inserted automatically.

A column is declared to be auto-increment by setting the value of the $auto_inc_col property to the column name. In the following example, we declare the "id" primary key column of the GuestBook table to be auto-increment:

An Auto-Incrementing Identifier

<?php

class GuestBook_Table extends DB_Table
{

    // Column definitions
    // var $col = array(...);

    // Index definitions
    var $idx = array(...);

    // Auto-increment declaration
    var $auto_inc_col = 'id';

}

?>

DB_Table Constructor

Each DB_Table object wraps a DB or MDB2 database connection object. This object is passed to the DB_Table constructor as its first parameter. A single DB/MDB2 object may be shared by any number of DB_Table objects. The second parameter of the constructor is the name of the associated RDBMS table. The optional third parameter is a string $create that can be used to specify whether the table should be created by the constructor if it does not already exist, or whether its structure should be verified if it does (as discussed in more detail below).

In the example shown below, an instance of the GuestBook subclass is created, which binds to the GuestBook table. The use of a value $auto_create = 'safe' specifies that the GuestBook table should be created if a table of that name does not already exist, but not otherwise.

Constructing the GuestBook_Table Object

<?php

// Include basic classes
require_once 'MDB2.php';
require_once 'DB/Table.php';
require_once 'Guestboook_Table.php';

// create a PEAR MDB2 (or DB) object
$dsn = "phptype://username:password@localhost/database";
$conn = MDB2::connect($dsn);

// set up for the GuestBook and create it
$table  = 'GuestBook';
$create = 'safe';
$GuestBook =& new GuestBook_Table($conn, $table, $create);

// print out results
if ($GuestBook->error) {
     echo "Failure!  Try again.";
     print_r($GuestBook->error);
} else {
     echo "Success!";
     print_r($GuestBook);
}

?>

The $conn connection object may be either a DB or MDB2 object, and is passed by reference.

The allowed values of the $create argument are:

  • boolean false to not attempt creation (default)

  • 'drop' to drop any existing table with the same name and re-create it

  • 'safe' to create the table if no such table exist, and do nothing if it does.

  • 'verify' to check whether the table exists, verify the schema. It checks whether all the columns exist, whether the columns have the right type, and whether the indexes exist and have the right type

  • 'alter' does the same as 'safe' if the table does not exist; if it does exist, the schema is verified, and the table is altered if needed.

Modifying Data: Insert, Update, and Delete

The DB_Table insert(), update(), and delete() methods provide a convenient interface for inserting, updating, and deleting rows of data. A row of data to be inserted or updated is passed to the insert or update method as an associative array in which the keys are column names.

Inserting Rows

To insert a row into the GuestBook table, you use the insert() method. The only parameter is an associative array in which the keys are column names, and the values are column values to be inserted.

Inserting a Row

<?php

// [snip] create the $GuestBook object

// assign fields and values
$row = array(
    'fname'    => 'Thomas',
    'lname'    => 'Anderson',
    'signdate' => '2003-10-12',
    'email'    => 'neo@matrix.net'
);

// insert into the table and print results
$result = $GuestBook->insert($row);
if (PEAR::isError($result)) {
    // Error handling code
}

?>

By default, the insert method will automatically validate that the data you are inserting is of the expected type, and that values have been provided for all required columns other than auto-increment columns. If either of these validations fails, the method returns a PEAR Error, and does not attempt to insert a row. In the above example, no value has been provided for the required 'id' column because this is an auto-increment column, as discussed below.

Auto-Increment Columns and Sequences

DB_Table can use sequences created by the underlying DB or MDB2 layer to generate auto-increment integer identifiers. If the value of a column that has been declared to be auto-increment is not set or set to PHP NULL in the array of values that is passed to the insert method, then an auto-incremented sequence value will be generated and inserted for that column. In the above example, a sequence value is generated and inserted for the 'id' column. If an integer value is set for such a column, however, the provided value will instead be inserted.

The sequence generation features of DB or MDB2 may also be accessed explictly via the DB_Table::nextID() method. This method is simply a wrapper that calls the corresponding DB or MDB2 method internally. The following example shows how to use nextID() to explicitly generate and insert an auto-incremented value for an identifier.

Using nextID() to access a sequence

<?php

// [snip] create the $GuestBook object

// get the next ID in a sequence associated with the table
$id = $GuestBook->nextID();

// assign fields and values
$row = array(
    'id'       => $id,
    'fname'    => 'Thomas',
    'lname'    => 'Anderson',
    'signdate' => '2003-10-12',
    'email'    => 'neo@matrix.net'
);

// insert into the table and print results
$result = $GuestBook->insert($row);
if (PEAR::isError($result)) {
    // ... error handling code ...
}

?>

Because the 'id' column has been declared to be auto-increment, this code snippet is functionally equivalent to that given in the preceding example.

Updating Rows

The update() method is used to update the data in a row or a set of rows. The method takes two parameters. Its first parameter is an associative array in which keys are names of columns to be updated, and values are new data values. The second is the text of the WHERE clause of the corresponding SQL UPDATE statement, excluding the WHERE keyword.

For example to change all the rows with the last name "Smith" to "Jones":

Updating a Set of Rows

<?php

// [snip] create the $GuestBook object

$values = array(
    'lname' => 'Jones'
    );

// assign the WHERE clause
$where = "lname = 'Smith'";

// attempt the update
$result = $GuestBook->update($values, $where);
if (PEAR::isError($result)) {
    // ... error handling code ...
}

?>

As for insertion, if you attempt to update with values that do not validate against the declared column types, then the update will fail, and the method will return a PEAR Error.

Deleting Rows

The delete() method is used to delete a row or set of rows specified by a logical condition. Its only parameter is a string containing the logical condition of the WHERE clause needed to identify which rows to delete, excluding the WHERE keyword.

For example, to delete all rows that were entered before today:

Deleting a Set of Rows

<?php

// [snip] create the $GuestBook object

// a WHERE clause
$today = date('Y-m-d'); // formatted as yyyy-mm-dd
$where = "signdate < '$today'";

// attempt the update and print the results
$result = $GuestBook->delete($where);
if (PEAR::isError($result)) {
    // ... error handling code ...
}

?>

Selecting Data

DB_Table uses an array syntax for constructing SQL SELECT statements, in which each clause of an SQL SELECT statement (e.g., SELECT, FROM, WHERE clauses) is stored in a different element. This representation makes it relatively easy to modify a query by, e.g., adding additional conditions to the WHERE clause to further limit the returned set of rows. Query arrays may be stored in the $sql property array.

Queries may be submitted to the database using either the select() method, which generally returns the result set as an array, or the selectResult() method, which returns a DB_Result or MDB2_Result_Common result set object. These three methods are all inherited from the DB_Table_Base base class, and thus are also available as methods of a DB_Table_Database object.

Query Arrays

Each SQL select statement is defined by a "query array". For most of the allowed elements of a query array, the key is a lower case version of the keyword that begins a clause in the SELECT statement (e.g., 'select', 'from', 'where', etc.), and the value is the text of the remainder of that clause, excluding the keyword. The allowed keys of a query array that define clauses of the SELECT command are:

  • 'select' - the SELECT clause (defaults to '*')

  • 'from' - the table(s) to select from. (Defaults to the name of this table, $this->table)

  • 'join' - any join clauses that should be added to the FROM clause.

  • 'where' - the WHERE clause

  • 'group' - the GROUP BY clause

  • 'having' - the HAVING clause

  • 'order' - the ORDER BY clause

The values of the 'select', 'from', 'where', 'group', 'having', and 'order' elements are strings that contain the text of corresponding clause of the desired SQL statement, excluding the keywords SELECT, FROM, WHERE, GROUP BY, HAVING, or ORDER, respectively. The value of the 'join' element, if present, is simply concatenated onto the end of the 'FROM' element, and should include the keywords, e.g., 'JOIN', 'INNER JOIN', or 'LEFT JOIN'.

The other allowed keys of a query array may be used to specify how the results of query should be returned by the select() method. These are:

  • 'get' - determines how the select() method will return results. See below for a list of allowed values. (Defaults to 'all').

  • 'fetchmode' - determines how rows of a result set will be returned by select() if 'get' is 'all' or not set.

  • 'fetchmode_object_class' - The name of the class of the objects that should be used to encapsulate rows if rows are returned as objects.

These three elements effect only the behavior of the select() method, and have no effect upon the behavior of the selectResult() method. The allowed values of the 'get' element are:

  • 'all' - return all rows of a return set as a sequential array of rows (this is the default). Each row can be returned as either an associative array in which keys are column names (the default) or a sequential array.

  • 'assoc' - returns an associative array in which the key is the first column of the return set and the value is the second column.

  • 'col' - return only the first column as a sequential array

  • 'row' - return only the first row as an associative array in which the keys are column names and the values are the column values.

  • 'one' - return only the value of the first column in the first row.

Each allowed value of the 'get' element corresponds to the name of the get* method of DB and MDB2 that is actually called internally by DB_Table::select(): If the value of the 'get' element is 'all', the query is submitted by calling the DB/MDB2::getAll() method, using an SQL query constructed from the query array, and DB_Table::select() simply returns the return value of getAll(). Similarly, a 'get' element value of 'assoc' causes a call to getAssoc(), 'col' calls getCol(), 'one' calls getOne(), and 'row' calls getRow().

When the 'get' element is set to 'all', explicitly or by default, each row in the array returned by the DB_Table::select() method returned as an associative array in which keys are column names, as a sequential array, or as an object in which column names map to property names. The choice of data structure for each row may be controlled by the 'fetchmode' element of the query or, if this is not is set, by the $fetchmode property of the DB_Table object. Similarly, when rows are returned as objects, the name of the object class may be specified by the 'fetchmode_object_class' element of the query or, if this is not set, by the $fetchmode_object_class property of the DB_Table object.

The values of the 'fetchmode' and 'fetchmode_object_class' elements of the query or the $fetchmode and $fetchmode_object_class properties of DB_Table are used to temporarily reset the values of the 'fetchmode' and 'fetchmode_object_class' properties (for DB) or options (for MDB2) of the underlying DB or MDB2 object. These values should be set equal to the desired DB_FETCHMODE_* or MDB2_FETCHMODE_* constant appropriate for the underlying backend. The original values of the DB/MDB2 object properties or options are restored before the select() method returns.

Storing Queries: $sql property array

Commonly used queries, and "baseline" queries that are useful as a starting point for construction of more complicated ones, may be stored in the $sql public property array. The $sql property is an associative array in which keys are query names, and values are query arrays. Stored queries can be submitted by passing the name key for the query as an argument to any of the select*() methods.

The $sql property is inherited from the DB_Table_Base class. Queries may thus be stored either the $sql property of a DB_Table that provides an interface to a specific table, or in the $sql property of a DB_Table_Database object that provides an interface to the entire database. For applications that involve only one table, or queries that involve only one table, it may be convenient to use the $sql property of the DB_Table object, as in the above example, and to then use the select*() methods of that object to access these queries by name. For more complicated queries and applications, however, it may be more convenient to store all queries in the $sql property of a DB_Table_Database object, and submit them by name via the select*() methods of that object.

Defining Baseline Queries in a DB_Table Subclass Definition

For our GuestBook table, let's say we define three stored SELECT statements, which may be used as a basis of more specific queries:

  • One that returns a list of guestbook rows ordered from most-recent to least-recent, showing the full name (first+last) and the date signed.

  • One that returns a single guestbook row, showing all fields.

  • One that returns a list of all unique email + fullname rows, ordered by last name and first name.

In the following program snippet, we declare these queries as elements of the $sql property within the GuestBook_Table class definition.

<?php

class GuestBook_Table extends DB_Table
{

    // [snip] var $col = array( ... );
    // [snip] var $idx = array( ... );

    var $sql = array(

        // multiple rows for a list
        'list' => array(
            'select' => "id, signdate, CONCAT(fname, ' ', lname) AS fullname",
            'order'  => 'signdate DESC'
        ),

        // one row for an item detail
        'item' => array(
            'select' => 'id, fname, lname, email, signdate',
            'get' => 'row'
        ),

        // email => fullname (unique rows only)
        'emails' => array(
            'select' => "DISTINCT email, CONCAT(fname, ' ', lname) AS fullname",
            'order' => 'lname, fname',
            'get' => 'assoc'
        )
    );

}

?>

Submitting Queries: select*() Methods

The select() method submits a query and returns the result set as an array. The selectResult() method returns the result as a DB_Result/MDB2_Result_Common object. The selectCount() method returns an integer equal to the number of rows that would be returned by a query, without returning the actual result set.

The interface is the same for all three of these methods. In each, the first parameter, which is required, can be either a query array or a key of the $sql property array, for which the corresponding value is a stored query array. The remaining parameters, which are all optional, may be used to modify the query before submission to the database. The second parameter, $filter, is a string that contains an SQL logical expression that will be ANDed with the WHERE clause of the query before the SELECT command is submitted. The third parameter, $order, if present, is used to construct the 'ORDER BY' clause, and may be used to override the 'order' element of the query. The fourth and fifth parameters, $start and $count, are integers that may be used to specify the first row of the result set that should be returned, and the maximum number of rows to be returned.

Submitting a Stored Query

<?php

// [snip] create a DB/MDB2 object and connect to the database
// [snip] create the GuestBook_Table object $GuestBook

// Submit the stored 'list' query, which returns an array of rows
$rows = $GuestBook->select('list');

// Print the result set
print_r($rows);

?>

The next example shows how to modify a stored query with the filter, order, start and count parameters:

Using Filter, Order, and Limit Parameters

<?php

$filter = "signdate = '2003-08-14'";
$order = 'lname, fname';
$start = 7;
$count = 12;

// Return results as an array of rows
$rows = $GuestBook->select($view, $filter, $order, $start, $count);
print_r($rows);

// Return results as a DB_Result/MDB2_Result_Common object
$result = $GuestBook->selectResult($view, $filter, $order, $start, $count);
print_r($result);

?>

To have select() return rows as associative arrays, we must set either the 'fetchmode' element of a specific query array or the $fetchmode property of the DB_Table object to the DB_FETCHMODE_ASSOC or MDB2_FETCHMODE_ASSOC constant values, as appropriate:

Setting Fetchmode to Return Rows as Associative Arrays

<?php

// [snip] create the $GuestBook GuestBook_Table object

// set the fetch mode to "associative"
$GuestBook->fetchmode = DB_FETCHMODE_ASSOC;

// now all rows arrays will be returned by DB_Table::select() as associative
// arrays with the column names as the array keys
?>

To have select() return rows as objects, with properties that correspond to column names, we must set either the 'fetchmode' element of the query array or the $fetchmode property of the DB_Table object to the DB_FETCHMODE_OBJECT or MDB2_FETCHMODE_OBJECT constant. If no user-defined class is specified, all rows are returned as instances of stdClass, as in the following example:

Returning Rows as stdClass Objects

<?php

// [snip] create the $GuestBook GuestBook_Table object

// set the fetch mode to the "object" constant for DB or MDB2
$GuestBook->fetchmode = DB_FETCHMODE_OBJECT;

// now each row in the results array will be a stdClass object,
// and the object properties will be named for the columns

// now all column arrays will come with the column names as the array keys
?>

To specify a class to be used to encapsulate rows of a return set, set the value of the 'fetchmode_object_class' element of the query array or the $fetchmode_object_class property to the name of the desired class.

Returning Rows as Objects of a User-Defined Class

<?php

// [snip] create the $GuestBook GuestBook_Table object

// set the fetch mode to "object"
$GuestBook->fetchmode = DB_FETCHMODE_OBJECT;

// set the fetched row class to "myRowClass" ...
// of course, you will need to include the "myRowClass" file
// before this.
$GuestBook->fetchmode_object_class = 'myRowClass';

// now each row in the results array will be a myRowClass object,
// and the object properties will be named for the columns

?>

Data Type Validation

DB_Table can automatically validate that the format of data to be inserted or updated is consistent with the declared types for the corresponding columns. Validation of the data type of both inserted and updated data is on by default. Validation upon insertion and updating can be turned on or off with the autoValidInsert() and autoValidUpdate() methods, respectively. Each of these methods takes a single boolean parameter, and turns validation on if its parameter is true and off if it is false.

Data type validation for a row of data to be inserted or updated is actually carried out by the validInsert() or validUpdate() method, respectively. Each of these methods takes one parameter, which is an associative array of data in which keys are column names. Each returns boolean true on success or a PEAR_Error object on failure. These methods are called internally by the insert() and update() methods, respectively, when auto-validation is enabled. Customized automatic validations may thus be implemented by overriding one or both of these methods.

Validation of the type of a single column value is carried out by the isValid() method. This method takes the value to be validated as its first parameter, and the name of the required DB_Table data type as its second parameter. This method is called internally by the two row validation methods.

Miscellaneous Utility Methods

Miscellaneous Methods
Method | Description
quote() | Enquotes and escapes a value in a form appropriate for inclusion in an SQL query. A simple wrapper for the DB::smartQuote() or MDB2::quote() method, which it calls internally.
recast() | Takes an associative array of data (keys are column names and values are column values) and re-casts each value to the proper format for its column.
getBlankRow() | Returns an associative array with column name keys and a blank value for each column. Each value will be in the proper format for the associated column type.
Prev | DB_Table | Next
Introduction | PEAR Manual | DB_Table Forms Tutorial


DB_Table Forms Tutorial

DB_Table Forms Tutorial

DB_Table Forms Tutorial – Creating HTML_QuickForm forms

Description

This page documents the use of the DB_Table class to create HTML_QuickForm form elements appropriate for the columns of a table, and to create entire data entry forms. DB_Table can use the column definitions to automatically create default form elements for you. Although your plain column definitions will do fine at first, you will want to customize the labels and options for your form elements. You can do so by adding 'qf_*' keys to your column definitions

Note: The underlying HTML_QuickForm package is a very powerful library with many options. While DB_Table automates away much of the complexity for simple forms, the full power of HTML_QuickForm can only be realized by combining the automatic element creation from DB_Table with custom-created HTML_QuickForm objects. DB_Table makes it easy to get started with HTML_QuickForm, but does not replace it.

Simple Form with Default Elements

Once you have defined your columns and instantiated an object, you can generate a complete HTML_QuickForm object using the getForm() method. If getForm() is called with no parameters, it will return a form with all of the $GuestBook object columns as input fields.

A default form with all columns

<?php
// [snip] create the GuestBook_Table object ($GuestBook)

// create the <classname>HTML_QuickForm</classname> object
$form =& $GuestBook->getForm(); // note the "=&" -- very important

// display the form
$form->display();
?>

Specifying Columns

To limit the fields you want to display, or to change the order, pass a sequential array of column names as the first parameter to getForm()

Specifying column names in getForm()

<?php

// [snip] create the Guesbook object ($GuestBook)

// only show the first name, last name, and email in the form
$cols = array('fname', 'lname', 'email');

// create the <classname>HTML_QuickForm</classname> object
$form =& $GuestBook->getForm($cols);

// display the form
$form->display();

?>

Add Buttons

Unfortunately, the form only has the input fields; it does not yet have "Submit" or "Reset" buttons, which are not automatically generated.

Adding "Submit" and "Reset" buttons with getForm()

<?php

// [snip] create the $GuestBook GuestBook_Table object

// create the HMTL_QuickForm object
$form =& $GuestBook->getForm($cols);

// add a "submit" button named "op" that says "Go!"
$form->addElement('submit', 'op', 'Go!');

// add a reset button
$form->addElement('reset');

// display the form
$form->display();

?>

Simple Form with Custom Elements

The basic form is nice, but it's very generic. It doesn't have descriptive labels for the input fields, all the fields are text boxes, and so on. This section shows you how to include form element properties along with your column definitions so that your forms are customized in a somewhat consistent fashion.

In every case you will modify the $col property by adding 'qf_*' keys and values.

  • 'qf_label' (string) Adds a text label to the field

  • 'qf_type' (string) Sets the input type (text, hidden, select, checkbox, etc.)

  • 'qf_vals' (array) Sets list of values for select, radio, and checkbox elements

  • 'qf_attrs' (array) Sets additional HTML attributes for the input element

  • 'qf_opts' (array) Sets options for date elements (date, time, timestamp, jscalendar)

Element Label

When a column appears in a form, you can make sure the same label is always applied to it. Let's say we have a column called "other" defined as a 32-character string. We always want it to be labelled as "Other Information" in our forms; use 'qf_label' key like this:

Setting 'qf_label'

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(
        // ...
        'example' => array(
            // table column definition
            'type' => 'varchar',
            'size' => 32,

            // form element definition
            'qf_label' => 'Other Information'
        )
    );
}
?>

Element Type

By default, DB_Table will try to figure out what kind of form field input type to use for your column. Most column types translate into text fields, but there are some exceptions.

  • Boolean columns become HTML_QuickForm 'advcheckbox' fields with values of 0 for not-checked and 1 for checked.

  • CLOB columns become HTML_QuickForm 'textarea' fields

  • Date columns become HTML_QuickForm 'date' select fields in 'Y-m-d' format.

  • Time columns become HTML_QuickForm 'date' select fields in 'H:i:s' format.

  • Timestamp columns become HTML_QuickForm 'date' select fields in 'Y-m-d H:i:s' format

To explicitly set the HTML_QuickForm element type for a column, rather than relying on the above defaults, you add a 'qf_type' element to your column definition. You can tell DB_Table to create any of several supported HTML_QuickForm element types by setting the 'qf_type' element to one of these string values:

  • 'checkbox' for a single checkbox; maps to the 'advcheckbox' HTML_QuickForm type

  • 'hidden' for a hidden element

  • 'password' for a password text box

  • 'radio' for a set of radio buttons

  • 'select' for a select menu

  • 'text' for a text box

  • 'textarea' for a text area

  • 'date' for a date selector; formats as 'Y-m-d'

  • 'time' for a time selector; maps to 'date', formats as 'H:i:s'

  • 'timestamp' for a timestamp selector; maps to 'date', formats as 'Y-m-d H:i:s'

If you use any other element name, DB_Table will attempt to map to the proper HTML_QuickForm element (thanks to Moritz Heidkamp for the patch), but it's not guaranteed to work.

In this example, we'll make the 'example' column a text field:

Setting an element type

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(
        // ...
        'example' => array(
            // table column definition
            'type' => 'varchar',
            'size' => 32,
            // form element definition
            'qf_label' => 'Other Information',
            'qf_type'  => 'text'
        )
    );
}
?>

Element Values

If your column form element is 'checkbox', 'radio', or 'select', you can set the values of the available choices for the form element. You do so via an 'sq_vals' element in the corresponding column definition.

Setting CheckBox Values

For a checkbox, use a sequential array of two elements: the first is the value if the box is not checked, and the second is the value if it is checked.

In this example, the checkbox values are 0 if not checked,and 1 if checked; these are the values that will be stored in the column.

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(
        // ...
        'example' => array(
            // table column definition
            'type' => 'varchar',
            'size' => 32,
            // form element definition
            'qf_label' => 'Other Information',
            'qf_type'  => 'text',
            'qf_vals'  => array(0, 1)
        )
    );
}
?>

Radio and Select Values

For radio buttons and select menus, use an associative array. Each array key is the value that will be stored in the column, and each array value is the text that will be displayed to the user.

This example creates a select menu with three possible values ('a', 'b', and 'c') and the corresponding labels:

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(
        // ...
        'example' => array(
            // table column definition
            'type' => 'varchar',
            'size' => 32,
            // form element definition
            'qf_label' => 'Other Information',
            'qf_type'  => 'text',
            'qf_vals'  => array(
                'a' => 'This is the letter "a"',
                'b' => 'I choose "b"',
                'c' => 'No, "c" is always the right answer'
            )
        )
    );
}
?>

Element HTML Attributes

If you like, you can add HTML attributes to the form element using the 'qf_attrs' keys. Attributes are assigned as key-value pairs in an associative array; the keys is the attribute name, and the value is the attribute value. For example, to set the number of rows and columns for a textarea element:

Setting rows and column number for a textarea

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(

        // ...

        'example' => array(
            // table column definition
            'type' => 'varchar',
            'size' => 32,

            // form element definition
            'qf_label' => 'Other Information',
            'qf_type'  => 'textarea',
            'qf_attrs' => array(
                'rows' => 24,
                'cols' => 80
            )
        )
    );
}
?>

DB_Table automatically adds a "maxlength" attribute to text and password elements based on the column size, so that users cannot type in values longer than the column allows.

Element Rules

HTML_QuickForm allows you to add validation rules to the input form. These rules are not the same as the DB_Table automated validations; the HTML_QuickForm rules apply only to the values as they relate to the form itself, not the values related to the table proper. This is an important distinction that will become apparent as you use HTML_QuickForm.

The available rules are:

  • email - the form input must be an email address

  • lettersonly -- the form nput must consist only of letters

  • maxlength -- the form input cannot have more than this many characters

  • maxlength -- the form input cannot have fewer than this many characters

  • nonzero -- the form input must be greater than or less than zero

  • nopunctuation -- the form input may not contain punctuation

  • numeric -- the form input must be a number of some sort (no letters)

  • regex -- the form input must match a regular expression

  • required -- the form input is required to be filled (even with a single space)

DB_Table will automatically add HTML_QuickForm rules for you in most cases.

  • If the column is required ('require' => true), then DB_Table will add a 'required' HTML_QuickForm rule.

  • If the column is numeric ('smallint', 'integer', 'bigint', 'single', 'double', or 'timestep') then DB_Table will a 'numeric' HTML_QuickForm rule.

  • If the column has a specific size ('size'), then DB_Table will add a 'maxlength' rule.

If you want to use a specific HTML_QuickForm rule for a column when that column appears in a form, set 'qf_rules' key to the name of the rule and set the value for that rule; in most cases, the value is an error message, but in some cases the value is a sequential array. You can add as many different rules as you like, but you can add only one of each type.

QuickForm Rules

<?php

class GuestBook_Table extends DB_Table
{

    var $col = array(

        // ...

        'example1' => array(
            // table column definition
            'type' => 'integer',

            // form element definition
            'qf_label' => 'Information',
            'qf_type' => 'text',

            // a set of QuickForm rules
            'qf_rules' => array(
                'required' => 'This field is required.',
                'numeric' => 'Please use only numbers, no letters.'
            )
        ),

        'example2' => array(

            // table column definition
            'type' => 'varchar',
            'size' => 10,

            // form element definition
            'qf_label' => 'Something:',
            'qf_type' => 'text',

            // a set of QuickForm rules
            'qf_rules' => array(
                'minlength' => array('Minimum length is 6 characters.', 6),
                'maxlength' => array('Maximum length is 10 characters.', 10),
                'regex' => array(
                    'Must be only upper-case letters and underscores.',
                    '/^[A-Z_]+$/'
                )
            );
        )
    )
}
?>

HTML_QuickForm supports rules for groups and entire forms, but DB_Table does not automate these; you will need to add them to the form object yourself.

Setting Default Values

Sometimes you will want to populate your input form with default values, such as the current values from the database. Doing so is easy.

When you call getForm(), instead of passing a sequential array of column names, pass an associative array in which the key is the column name and the value is the column value.

Setting Default Values for Form Fields

<?php

// [snip] create the GuestBook_Table object ($GuestBook)

// Show only the first name, last name, and email in the form
// Provide default values for the form elements
$cols = array(
    'fname' => 'Thomas',
    'lname' => 'Anderson',
    'email' => 'neo@matrix.net'
);

// create the HTML_QuickForm object
$form =& $GuestBook->getForm($cols);

// display the form
$form->display();
?>

Element Names as Array Keys

By default, when you call getForm(), the form elements are named for their columns. For example, the column 'fname' is called 'fname' in the form.

<!-- [snip] the beginning of the form -->

<input type="text" name="fname" ... />

<!-- [snip] the end of the form -->

However, often you will want the form elements to be keys in any array instead of their own separate variables. This is particularly useful when you are going to use the values in a DB_Table insert() or update() call.

To do so, pass the name of an array as the second argument to getForm() (after the list of columns to use in the form). For example, if you want the column names to be keys in an array called 'new_row', do this:

Returning form values in an array

<?php

// [snip] create the $GuestBook object of class GuestBook_Table

// choose which columns to display in the form
$cols = array('fname', 'lname', 'email');

// create the HTML_QuickForm object, with elements
// named as part of an array called 'new_row'
$form = $GuestBook->getForm($cols, 'new_row');

// display the form
$form->display()

?>

Custom HTML_QuickForm Objects

Although the getForm() method supports all HTML_QuickForm parameters (such as the name of the form, the method, the action, and so on), you don't need to use DB_Table to create the entire form. If you like, you can create your own HTML_QuickForm object, and add DB_Table columns to it one-by-one or in groups.

DB_Table provides these methods to add automatically-defined elements to pre-existing HTML_QuickForm objects:

  • addFormElements() to add one or more automatically-defined form element objects to a pre-existing HTML_QuickForm object, along with their associated DB_Table defined rules.

  • getFormGroup() to get an HTML_QuickForm group array of automatically-defined element objects

  • getFormElement() to get a single automatically defined element object.

Here are example uses of each:

Custom HTML Element

<?php

// [snip] Create the GuestBook_Table object $GuestBook

// load the class file and create a QuickForm object
require_once 'HTML/QuickForm.php';
$form =& new HTML_QuickForm();

// add one or more elements from the GuestBook
// object to the QuickForm object, along with
// the rules for those elements
$cols = array('email', 'signdate');
$GuestBook->addFormElements($form, $cols);

// add an element group of GuestBook columns
// to the QuickForm object (does not add rules)
$cols = array('fname', 'lname');
$group =& $GuestBook->getFormGroup($cols);
$form->addGroup($group);

// get back a single form element object with a
// custom name, then add it to the form
$col = 'id';
$name = 'new_row[id]';
$element =& $GuestBook->getFormElement($col, $name);
$form->addElement($element);

?>
Prev | DB_Table | Next
DB_Table Class Tutorial | PEAR Manual | DB_Table_Database Class Tutorial


DB_Table_Database Class Tutorial

DB_Table_Database Class Tutorial

DB_Table_Database Class Tutorial – Interface to a relational database

Description

DB_Table_Database is an database abstraction class for a relational database. It is a layer built on top of the DB_Table class: Each table in a DB_Table_Database object is represented by a DB_Table object. The most important difference between a DB_Table_Database object and a collection of DB_Table objects is that the properties of a parent DB_Table_Database object contain a model of the entire database, including relationships between tables.

DB_Table_Database provides:

  • An object-oriented representation of a relations between tables in a relational database, including linking/association tables that create many-to-many relationships.

  • A simplified API for INSERT, UPDATE, DELETE, and SELECT commands, with an interface very similar to that of the DB_Table class.

  • Automated construction of join conditions for inner joins of any number of tables, based on a list of table names and/or a list of desired column names.

  • Optional checking of the validity of foreign key values by the PHP layer upon insertion or updating.

  • Optional PHP emulation of SQL ON DELETE and ON UPDATE referentially triggered actions.

  • PHP serialization to (and unserialization from) a string that contains the entire database schema.

  • Serialization to (and unserialization) from XML, using an extension of the MDB2 XML schema. (Unserialization from XML requires PHP 5).

  • Methods to set various properties of all the child DB_Table objects to a common value.

  • Various utility methods that aid the construction of SQL queries.

Like DB_Table, DB_Table_Database wraps a DB or MDB2 database connection object. The class is compatible with both PHP 4 and PHP 5, with the exception of one non-essential method: The fromXML() method, which creates a DB_Table_Database object from an XML database schema, requires PHP 5.

Class DB_Table_Database extends abstract base class DB_Table_Base. Methods or properties that are inherited from DB_Table_Base are noted as such, and are indicated in the table of contents of this page with the notation "(from DB_Table_Base)".

This tutorial uses an extended example to introduce the use of the DB_Table_Database class to create a model of an interface to a relational database.

  • Example Database

  • Constructor

  • Building a Model

    • addTable() - Adding tables

    • addRef() - Adding references

    • addLink() - Declaring linking tables

    • Deleting Tables, References, or Links

  • Referentially Triggered Actions

    • Declaring actions with addRef()

    • setOnDelete() and setOnUpdate()

    • setActOnDelete() and setActOnUpdate()

  • Foreign Key Validation

  • Data Selection

    • Query Arrays

    • select(), selectResult(), and selectCount() (from DB_Table_Base)

    • autoJoin()

  • SQL Utilities

    • quote()

    • buildFilter() (from DB_Table_Base)

    • buildSQL() (from DB_Table_Base)

    • validCol()

  • Data Modification: insert(), update(), and delete()

  • PHP Serialization

    • setTableSubclassPath()

  • XML Serialization

  • Setting DB_Table Properties

  • Get* Methods

Example Database

Throughout this tutorial, our examples will refer to a DB_Table_Database object for an example database named TestDB, which is described below. The child DB_Table objects that are associated with RDBMS tables must all be instantiated first, and then added to (i.e., linked with) a parent DB_Table_Database object.

The example database TestDB stores names, numbers, and addresses for a set of people, and contains 4 tables. Peoples names, phone numbers, and addresses are stored in three tables named Person, Phone, and Address, respectively. To allow for the fact that several people may share a phone number, and that a person may have more than one phone number, the database allows the creation of a many-to-many relationship between Person and Phone. This relationships are established by an additional linking table, named PersonPhone, which contains foreign key references to Person and Phone.

DB_Table objects must be instantiated before they can be added to a parent DB_Table_Database instance. The usual way of creating a DB_Table object (as discussed in the tutorial for that class) is to create one subclass of DB_Table for each table, and create one instance of each such subclass. In this tutorial, we use a convention in which the subclass of DB_Table associated with a database table named "Entity" is Entity_Table, and in which the single object of this class is $Entity. This is also the convention used in code generated by the DB_Table_Generator class.

The following code defines a subclass Person_Table that represents a database table Person:

<?php
require_once 'DB/Table.php'

class Person_Table extends DB_Table
{
    // Define columns
    $col = array (
        'PersonID' => array('type' => 'integer', 'require' => true),
        'FirstName' => array('type' => 'char', 'size' => 32, 'require' => true),
        'MiddleName' => array('type' => 'char', 'size' => 32),
        'LastName' => array('type' => 'char', 'size' => 64, 'require' => true),
        'NameSuffix' => array('type' => 'char', 'size' => 16),
        'AddressID' => array('type' => 'integer')
    );

    // Define indices. PersonID is declared to be the primary index
    $idx = array(
        'PersonID' => array('cols' => 'PersonID',  'type' => 'primary'),
        'AddressID' => array('cols' => 'AddressID', 'type' => 'normal')
    );

    // Declare 'PersonID' to be an auto-increment column
    $auto_inc_col = 'PersonID';

}
?>

Here, 'PersonID' is the primary index of the Person table. Column AddressID is a foreign key that references the primary key of the Address table (defined below).

Note the assignment of a value for the $auto_inc_col property, which is a recent addition to DB_Table: The value of $auto_inc_col is the name of a column that is declared to be 'auto increment'. Auto incrementing of this column is now implemented in the insert method of DB_Table using DB or MDB2 sequences.

The following code uses the same method to create subclasses of DB_Table associated with the remaining Phone, Address, and PersonPhone tables of database TestDB:

<?php
class Address_Table extends DB_Table
{
    $col = array(
        'AddressID' => array('type' => 'integer', 'require' => true),
        'Building' => array('type' => 'char', 'size' =>16),
        'Street' => array('type' => 'char', 'size' => 64),
        'UnitType' => array('type' => 'char', 'size' => 16),
        'Unit' => array('type' => 'char', 'size' => 16),
        'City' => array('type' => 'char', 'size' => 64),
        'StateAbb' => array('type' => 'char', 'size' => 2),
        'ZipCode' => array('type' => 'char', 'size' => 16)
    );
    $idx = array(
        'AddressID' => array('cols' => 'AddressID', 'type' => 'primary'),
    );
    $auto_inc_col = 'AddressID';
}
?>

<?php
class Phone_Table extends DB_Table
{
    $col = array(
        'PhoneID' => array('type' => 'integer', 'require' => true),
        'PhoneNumber' => array('type' => 'char', 'size' => 16, 'require' => true),
        'PhoneType'   => array('type' => 'char', 'size' => 4)
    );
    $idx = array(
        'PhoneID' => array('cols' => 'PhoneID', 'type' => 'primary')
    );
    $auto_inc_col = 'PhoneID';
}
?>

<?php
class PersonPhone_Table extends DB_Table
{
    $col = array(
        'PersonID' => array('type' => 'integer', 'require' => true),
        'PhoneID'  => array('type' => 'integer', 'require' => true)
    );

    $idx = array(
        'PersonID' => array('cols' => 'PersonID', 'type' => 'normal'),
        'PhoneID' => array('cols' => 'PhoneID', 'type' => 'normal')
    );
}
?>

In ths example, the PhoneType column of table Phone is used to distinguish home, work, and cell phones, and so must have one of the 4 character values 'HOME', 'WORK' or 'CELL'.

The following code instantiates one object of each DB_Table subclass, which is associated with the corresponding table:

<?php
$Person = new Person_Table($conn, 'Person', 'safe');
$Address = new Address_Table($conn, 'Address', 'safe');
$Phone = new Phone_Table($conn, 'Phone', 'safe');
$PersonPhone = new PersonPhone_Table($conn, 'PersonPhone', 'safe');
?>

Here, because we have used the value 'safe' for the optional third parameter of the DB_Table constructor in each statement, each table will be created in the RDBMS only if and only if a table of that name does not already exist in the database.

It is recommended that constructor statements be placed in a separate file from any of the DB_Table subclass definitions. Doing so makes it easier to serialize and unserialize the DB_Table and DB_Table_Database objects, because a php file in which an instance of a DB_Table subclass is unserialized must have access to the subclass definition, but should not include the constructor statements. Putting each DB_Table subclass definition in a separate file, with a name that is the subclass name with a .php extension, also allows the subclass definitions to be autoloaded when an object is serialized, as discussed below.

An alternative way to create a DB_Table object is to create an instance of DB_Table itself, rather than of a subclass of DB_Table. In this method, one first instantiates a generic DB_Table object, which initially contains no information about the table schema, and then sets the values of the public $col and $idx properties needed to define a table schema. As an example, the following code constructs an instance of DB_Table that represents the Person table:

<?php
$Person = new DB_Table($conn, 'Person');

$Person->col['PersonID'] = array('type' => 'integer', 'require' => true);
$Person->col['FirstName'] = array('type' => 'char', 'size' => 32, 'require' => true);
$Person->col['MiddleName'] = array('type' => 'char', 'size' => 32);
$Person->col['LastName'] = array('type' => 'char', 'size' => 64, 'require' => true);
$Person->col['NameSuffix'] = array('type' => 'char', 'size' => 16);
$Person->col['AddressID'] = array('type' => 'integer');

$Person->idx['PersonID'] = array('cols' => 'PersonID', 'type' => 'primary');
$Person->idx['PersonID'] = array('cols' => 'PersonID', 'type' => 'normal');

$Person->auto_inc_col = 'PersonID';
?>

This method is valid only in recent versions of the DB_Table package (1.5.0RC1 and greater) that contain the DB_Table_Database class. Earlier versions of DB_Table required that DB_Table always be extended. The only real disadvantage of using such generic DB_Table objects is that it makes it impossible to override the methods of DB_Table to, for example, customize the insert or update method so as to implement business rules for a table. Generic DB_Table objects are used by the fromXML() method, which takes an XML description of a database schema as a parameter, and returns a DB_Table_Database object in which each of the child tables is represented by an instance of DB_Table.

Constructor

A DB_Table_Database object is instantiated as an empty shell, to which tables, foreign key references, and links are then added. The constructor interface is

void DB_Table_Database(DB/MDB2 object $conn, string $name)

The parameter $conn must be either a DB or MDB2 object, which establishes a connection to a RDBMS. The $name parameter is the name of the database. To instantiate an object that represents a database named TestDB with a DB connection to a MySQL database, we might thus use (with no error checking):

<?php
require_once 'DB/Table/Database.php'

$conn = DB::connect("mysqli://$user:$password@$host");
$db = new DB_Table_Database($conn, 'TestDB');
?>

where the values of $user, $password, and $host are the user name, database password, and host machine, respectively.

Building a Model

To construct a model of a relational database, after instantiating a set of DB_Table objects and a DB_Table_Database object, we must add the table objects to the database object, add declarations of foreign key references, and declare many-to-many relationships that involve linking tables, in that order.

Adding Tables

After a DB_Table object is instantiated, it can be added to the parent database with the DB_Table_Database::addTable() method. The interface for this method is

true|PEAR_Error addTable(object &$Table)

where $Table is a DB_Table object that is passed by reference. The method returns boolean true on normal completion, and a PEAR_Error object on failure.

The following code adds the four tables of our example database to the $db DB_Table_Database object:

<?php
$db->addTable($Person);
$db->addTable($Address);
$db->addTable($Phone);
$db->addTable($PersonPhone);
?>

In this and all subseqent examples, we omit the error handling code that should be added to production code.

Adding Foreign Key References

After tables have been added to a database, we can use the addRef() method to add references between pairs of tables.

Synopsis (simplified):

true|PEAR_Error addRef(string $ftable, string|array $fkey,
string $rtable, [string|array $rkey] )

Here $ftable is the name of a referencing (or foreign key) table, $fkey is the foreign key, $rtable is the name of the referenced table, and $rkey is the (optional) referenced key. If the optional $rkey parameter is absent or null, the referenced key is taken by default to be the primary key of the referenced table. The foreign and referenced key values are specified using the same syntax as that used to define indices in DB_Table: Each key may be either a column name string, for a single-column key, or a sequential array of column names, for a multi-column key. The method returns true on normal completion, and a PEAR_Error on failure. The simplified synopsis shown here does not include two more optional parameters (parameters 5 and 6) that can be used to specify 'on delete' and 'on update' actions. The full interface is presented below. For example, the command:

<?php
$db->addRef('Person', 'AddressID', 'Address', 'AddressID');
?>

adds a reference from foreign key Person.AddressID of referencing table Person to the primary key Address.AddressID of referenced table Address. Because the referenced key 'AddressID' is also the primary key of table 'Address' this could also be written as:

<?php
$db->addRef('Person', 'AddressID', 'Address');
?>

When the referenced key is explicitly specified, as in the first example, it should always be either a primary key or a key for which a unique index is defined, as required by standard SQL.

A reference between two tables can only be added after both the referencing and referenced DB_Table objects have been instantiated and added to the parent DB_Table_Datbase instance.

Adding Links

A table may be declared to be a "linking" table that establishes a many-to-may relationship between two others. The only effect of such a declaration is to change the action of the autoJoin method: If a table named $link is declared to be a linking table that creates a many-to-many relationship between tables named $table1 and $table2, then the autoJoin method may use the linking table to join $table1 and $table2, if necessary.

Method addLink() declares a table to be a linking or association table for two others.

Synopsis:

true|PEAR_Error addLink(string $table1, string $table2, string $link)

Here, $link is the name of a linking table that links tables named $table1 and $table2. All three parameters are required, and all must be valid table name strings. It does not matter which of the two linked tables, $table1 and $table2, is listed first and which second in the function call. A table that links $table1 and $table2 must have foreign keys that references to both of the linked tables. A link can only be added to the model after the references from the linking table to both of the linked tables have been added. The method returns true on normal completion and a PEAR_Error() if an error is detected.

For example, the command:

<?php
$db->addLink('Person', 'Phone, 'PersonPhone)
?>

declares PersonPhone to be a linking table that links tables Person and Phone.

The addLink() method will not prevent one from declarating more than one linking table for the same two linked tables. Doing so would make the link declaration useless, however, because the autoJoin() method will fail if it needs to use a linking table to join a pair of tables, but finds that more than one of linking table is declared for those two tables.

The command

<?php
$db->addAllLinks()
?>

adds all possible linking tables to the database. In this method, any table that has foreign keys that reference tables $table1 and $table2 is declared to be a link between $table1 and $table2. In some databases, the easiest way to declare links may be by using the addAllLinks method to create all possible links and then using the deleteLink() method to delete those that are not desired.

The database model is complete when all of the tables have been added, all of the references have been added, and all the links have been added.

Example - Putting it Together

For our example, let us create a directory in which to put all of the code required as an interface to a database. We will put each DB_Table subclass definition in a separate file in this directory, in which each file name is simply the class name with a '.php' extension. In addition, it is convenient to create a single file, which we will call 'Database.php', in which we create a DB or MDB2 connection, create one object per table, and construct a parent DB_Table_Database object. This file structure is used by the DB_Table_Generator class for code that is auto-generated for an existing database. Below is a listing of the minimal 'Database.php' file required for our example database:

Database.php File

<?php
require_once 'MDB2.php';
require_once 'DB/Table/Database.php';
require_once 'Person_Table.php';
require_once 'Address_Table.php';
require_once 'Phone_Table.php';
require_once 'PersonPhoneAssoc_Table.php';

// NOTE: User must uncomment & edit code to create $dsn
$phptype  = 'mysqli';
$username = 'root';
$password = 'password';
$hostname = 'localhost';
$dsn = "$phptype://$username:$password@$hostname";

// Instantiate DB/MDB2 connection object $conn
$conn =& MDB2::connect($dsn);
if (PEAR::isError($conn)) {
    print "Error connecting to database server\n";
    print $conn->getMessage();
    die;
}

// Create one instance of each DB_Table subclass
$Person = new Person_Table($conn, 'Person');
$Address = new Address_Table($conn, 'Address');
$Phone = new Phone_Table($conn, 'Phone');
$PersonPhoneAssoc = new PersonPhoneAssoc_Table($conn, 'PersonPhoneAssoc');

// Instantiate a parent DB_Table_Database object $db
$db = new DB_Table_Database($conn, '42A');

// Add DB_Table objects to parent DB_Table_Database object
$db->addTable($Person);
$db->addTable($Address);
$db->addTable($Phone);
$db->addTable($PersonPhoneAssoc);

// Add foreign references
$db->addRef('PersonPhoneAssoc', 'PersonID', 'Person');
$db->addRef('PersonPhoneAssoc', 'PhoneID', 'Phone');
$db->addRef('Person', 'AddressID', 'Address');

// Add all possible linking tables
$db->addAllLinks();

?>

This example file is very similar to the skeleton file that would be created by DB_Table_Generator for an existing database with this structure. The main differences are that some lines in the auto-generated file would have to be uncommented or edited to produce the above (e.g., the lines that define the database DSN). In this example, the call to addAllLinks() method would correctly identify 'PersonPhoneAssoc' as a table that links 'Person' and 'Phone'. This example does not include any referentially triggered 'ON DELETE' or 'ON UPDATE' actions, discussed below, which could be added to the end of the same file.

Deleting Tables, References, and Links

The deleteTable(), deleteRef(), and deleteLinks() methods can be used to delete tables, and foreign key references, and linking table declarations, respectively, from the DB_Table_Database model.

deleteTable() - deletes a table from the database model

Synopsis:

void deleteTable(string $table)

Parameter $table is the name of the table to be deleted. Deletion of a table causes deletion of the table and all other entities of the model that depend on the existence of that table, including foreign key references to or from that table, and linking relationships that depend upon the existence of those foreign key references.

deleteRef() - deletes a reference from the database model

Synopsis:

void deleteRef(string $ftable, string $rtable)

where $ftable and $rtable are the names of the referencing and referenced tables, respectively. Deletion of a foreign key reference causes deletion of any links that rely on the existence of that reference, i.e., links in which $ftable is the linking table and $rtable is one of the linked tables.

deleteLink() - deletes a linking table declaration

Synopsis:

void deleteLink(string $table1, string $table2, [string $link])

Here $table1 and $table2 are names of the linked tables, and the optional parameter $link is the name of the linking table. If $link is null or absent, all declarations of linking tables between $table1 and $table2 are deleted. If $link is present, only the declaration of $link as a linking table between $table1 and $table2 is deleted (if one exists). The deleteLinks() method may be used after the addAllLinks() to prune the resulting set of linking table declarations.

On Delete and On Update Actions

DB_Table_Database optionally provides actions designed to enforce referential integrity that are provided by ANSI SQL, but that are not provided by some popular databases (e.g., SQLite and the default MySQL engine). DB_Table_Database offers optional PHP emulation of referentially triggered ON DELETE and ON UPDATE actions, such as cascading deletes (discussed here), and also optionally checks the validity of foreign key values before insertion or updating (discussed below)

The ON DELETE and ON UPDATE actions associated with a reference (if any) may be declared either as additional parameters to addRef(), or by using setOnDelete() and setOnUpdate().

Declaring actions in addRef()

Actions to be taken on deletion or updating of a referenced row may may be declared when a reference is added to the model using two optional parameters of the addRef() method. The following example shows the extended form of addRef() needed to add a reference from PersonPhone to Person (as above), while also declaring a cascade action on delete of a referenced row of Person, and a restrict action on update of such a row:

<?php
$db->addRef('PersonPhone', 'PersonID', 'Person', null, 'cascade', 'restrict');
?>

Here, a null value of the fourth parameter is used to indicate that the referenced key should be taken, by default, to be primary key of referenced table Person. The values of the fifth and sixth parameters represent actions to be taken upon delete ('cascade') and upon update ('restrict'), respectively. A null or absent value for either of these parameters indicates that no referentially triggered action should be taken on delete or on update.

The effect of the 'cascade' values of the fifth parameter in the above example is to declare that that all referencing rows of PersonPhone should be deleted upon deletion of a corresponding referenced row of Person (a cascading delete). The 'restrict' value of the sixth parameter declares that updating of the primary key PersonID of Person should be prevented (the 'restrict' on update action), and an error should be thrown by the update method, in rows of Person that are referenced by rows of PersonPhone.

The full interface of the addRef() method is:

true|PEAR_Error addRef(string $ftable, mixed $fkey, string $rtable, [mixed $rkey],
[string|null $on_delete], [string|null $on_update])

Here, $ftable is the referencing table, $fkey is the foreign key, $rtable is referenced table, and $rkey is the referenced key. The $fkey and $rkey parameters may be column name strings or arrays of column names, or $rkey may be null. An absent or null value of $rkey indicates a reference to the primary key of the referenced table. The $on_delete and $on_update parameters indicate actions to be taken on deletion or updating of a referenced row. The only allowed values of $on_delete and $on_update are the string literals

'cascade' | 'restrict' | 'set null' | 'set default'

or PHP null, which is the default value for both parameters. Each of the allowed action strings is the lower case form of a standard SQL action, and turns on PHP emulation of the corresponding action. An absent or null value for either action indicates that no action should be taken at the PHP layer upon delete or update of a referenced row. (Note that a PHP null value is different from the 'set null' action string.)

The following example declares all of the foreign key references needed in our example database, with appropriate referentially triggered actions:

<?php
$db->addRef('Person', 'AddressID', 'Address', null, 'set null', 'cascade');
$db->addRef('PersonPhone', 'PersonID', 'Person', null, 'cascade', 'cascade');
$db->addRef('PersonPhone', 'PhoneID', 'Phone', null, 'cascade', 'cascade');
?>

As a result of these declarations, rows in the linking table PersonPhone will be deleted when corresponding rows of either Person or Phone are deleted, and updated if the primary keys of reference rows Person or Phone are modified. The foreign key AddressID of a row in table Person will be set to null if the corresponding referenced row of Address is deleted (to indicate that no address is known), and updated if the primary key of that row in Address is modified.

setOnDelete() and setOnUpdate()

The referentially triggered actions associated with a foreign key reference may also be changed, or turned off, with the setOnDelete() and setOnUpdate() methods.

Synopses:

void setOnDelete(string $ftable, string $rtable, string|null $action)
void setOnUpdate(string $ftable, string $rtable, string|null $action)

Here, $ftable and $rtable are the names of referencing (foreign key) and referenced table, respectively, for an existing reference. The $action parameter is the value for the on_delete or on_update action for that reference, i.e., either an action strings or null. A null parameter is used to indicate that no action on delete or update of rows of table $rtable.

For example, the following code would change the 'on_update' action associated with the reference from 'PersonPhone' to 'Person' to a 'restrict' action:

<?php
$db->setOnUpdate('PersonPhone', 'Person', 'restrict');
?>

The effect this is to prohibit updates of the primary key value in rows of Person that are referenced by rows of PersonPhone.

setActOnDelete() and setActOnUpdate()

PHP emulation of referentially triggered actions may be turned on or off for the entire database by the setActOnDelete() and setActOnUpdate() methods.

Synopses:

void setActOnDelete(bool $flag)
void setActOnUpdate(bool $flag)

Passing a true value to either method activates PHP emulation of all of the declared ON DELETE or ON UPDATE actions, respectively, while a false value turns off PHP emulation of the corresponding action. By default, PHP emulation of both ON DELETE and ON UPDATE actions is on. Calling either of these methods with a false value does not modify the values of the instance property (the $_ref property) that records the on delete or on update actions associated with each reference: It merely prevents PHP emulation of these actions by the DB_Table_Database::delete() and DB_Table_Database::update() methods.

Foreign Key Validation

By default, DB_Table_Database checks the validity of foreign key values before inserting or updating data in a table with foreign keys. That is, before inserting a row, or updating any foreign key column values, the insert() and update() methods of DB_Table_Database actually submit a query to confirm that the inserted or updated foreign key column values correspond to values of the referenced columns of an existing row in the referenced table. By default, both methods throw an error, and do not modify the data, if this check fails.

This checking of foreign key validity by the PHP layer may be turned on or off, for insertion or updating of any table in database, with the setCheckFKey() method. The interface of this method is:

void setCheckFKey(bool $flag)

Passing a true value of $flag turns on checking of foreign keys (the default), while a false value turns checking off.

Data Selection

DB_Table_Database provides an object-oriented interface for SQL select statements that is almost identical to that of DB_Table.

Query Arrays

As in DB_Table, queries are represented in DB_Table_Database as arrays, in which array elements represents clauses of a corresponding SQL select statement. For example, a query for names of all people that live on Oak Street in Anytown in our example database might be

<?php
$oak = array(
'select' => 'Person.FirstName, Person.LastName, Address.Building',
'from' => 'Person, Address',
'where' => "Person.AddressID = Address.AddressID\n"
. " AND Address.Street = 'Oak Street'\n"
. " AND Address.City = 'AnyTown'",
'order' => 'Address.Building' );
?>

The buildSQL() method accepts such a query array as a parameter and returns the corresponding SQL command string. For example

<?php
echo $db->buildSQL($oak);
?>

yields the output

SELECT Person.FirstName, Person.LastName, Address.Building
FROM Person, Address
WHERE Person.AddressID = Address.AddressID
  AND Address.Street = 'Oak Street'
  AND Address.City = 'AnyTown'
ORDER BY Address.Building

The string values of most values in this array are passed to the RDBMS unmodified, prefixed by the keywords 'SELECT', 'FROM', etc. Column names that appear in only one table often do not need to be qualified by table names, as they are in the above example.

As in DB_Table, such query arrays can be stored in the public $sql property array:

<?php
$db->sql['oak'] = $oak
?>

Representing queries as arrays, rather than strings, makes it easier for baseline queries to be modified by, for example, adding additional limitations to the end of the 'where' clause string.

Select* Methods: select(), selectResult(), and selectCount()

The select*() methods are inherited by both the DB_Table_Database and DB_Table classes from the DB_Table_Base class, and thus share the same interface and behavior. The interface is also the same for all three methods. The required first parameter can be either the key for a previously stored query array, as in

<?php
$result = $db->select('oak')
?>

or the corresponding array value as a parameter, as in

<?php
$result = $db->select($oak)
?>

The select method returns a result set as a numerically indexed array of rows. Each row can represented as be either an associative or numerical array, or an object, depending on the value of the $fetchmode property of the DB_Table_Database object or (if this is null) the fetchmode of the underlying DB or MDB2 object.

The common interface of three select* methods
select(),
selectCount(), and
selectResult() is:

mixed select*( array|string $sql_key, [string $filter], [string $order],
[int $start], [int $count], [array $params])

As discussed above, $sql_key is either a query array, or the key of a baseline query array that has been stored in the $sql property. The $filter parameter is an SQL logical expression string that limits the result set. This condition is added (i.e., ANDed) to the end of the 'where' element of the $sql_key query array. The $order parameter is an ORDER BY clause (without the ORDER BY prefix) that can be used to override any 'order' element of the $sql_key array. Integer parameters $start is which the position within the full result set of the first row that should be included in the return value, while $count is the maximum number of rows desired within the return value. If present, $params is an array in which the values are parameters for placeholder substitution in a prepared query.

autoJoin()

autoJoin() - accepts an array parameter containing the names of desired columns and/or an array of tables names, and returns a query array containing a WHERE clause with automatically generated join conditions.

Synopsis:

<?php
array|PEAR_Error autoJoin([array $cols], [array $tables], [string $filter])
?>

Here, $cols is a sequential array of the names of the desired columns, $tables is a sequential array of names of tables to be joined, and $filter is an SQL logical statement that may be used to limit the results. The $filter clause is added (i.e., ANDed) to the end of the the 'where' element, after the automatically generated join conditions. Both the $col and $tables parameter are optional, but at least one of them must be supplied. The query returned by autoJoin is an inner join of a set of tables containing all of those listed in the $tables parameter, all of the tables containing the columns listed in the $cols parameter, and any linking tables required to join these tables.

The following example generates and submits query that selects a result set in which each row contains a person's name, home phone number and address, based on knowledge of the names of the desired columns. In our example database, this requires that all four tables be joined.

<?php
$cols = array('FirstName', 'LastName', 'PhoneNumber', 'Building', 'Street', 'City')
$report = $db->autoJoin($cols, "Phone.PhoneType = 'HOME'");
$result = $db->select($report);
?>

Note that the column names in the $cols parameter do not need to be qualified by table names if they are unambiguous -- the autoJoin method internally uses the validCol() method to validate and disambiguate all qualified and unqualified column names.

The SQL command corresponding to such a query array may be obtained using buildSQL(). In this example,the command

<?php
echo $db->buildSQL($report);
?>

yields

SELECT Person.FirstName, Person.LastName, Phone.PhoneNumber, Address.Building, Address.Street, Address.City
FROM Person, Phone, Address, PersonPhone
WHERE PersonPhone.PhoneID = Phone.PhoneID
  AND PersonPhone.PersonID = Person.PersonID
  AND Person.AddressID = Address.AddressID

If autoJoin() is passed only a set of column names, as in the above example, it identifies the set of tables that contain those columns, and joins those tables, plus any linking tables needed to create many-to-many relationships.

In the following example, the $cols parameter is null, but the names of the tables to be joined are specified in the $tables parameter:

<?php
$tables = array('Person', 'Address', 'Phone');
$report = $db->autoJoin(null,$tables);
$result = $db->select($report);
?>

The corresponding SQL command is

SELECT *
FROM Person, Phone, Address, PersonPhone
WHERE PersonPhone.PhoneID = Phone.PhoneID
  AND PersonPhone.PersonID = Person.PersonID
  AND Person.AddressID = Address.AddressID

When the first argument of autoJoin is null, as in this example, the SELECT clause is taken to be 'SELECT * by default. Note that the FROM and WHERE clauses join a linking table PersonPhone that was not explicitly specified, because this table was necessary to join two of the tables containing the desired data.

Algorithm: The algorithm used by autoJoin() is designed to find appropriate join conditions if these exist and are unambiguous, and to return a PEAR Error if the structure of references and linking tables either yields a multiply connected network of joins, or if it cannot construct an appropriate set of join conditions. The method first examines the $col and $table property to identify the list of tables that must be joined. It then creates a network of joined tables (the joined set) by starting with one table and sequentially adding tables to the joined set from the set of tables have not yet been joined (the unjoined set). The process starts by taking the first required table as a nucleus of the joined set, and then iterating through the unjoined set in search of a table that can be joined to the first. During this and each subsequent stage of addition, the method iterates through the unjoined set in search of a table that can be joined to any table in the joined set (i.e., that either references or is referenced by one of the tables in the joined set.) If it finds an unjoined table that can be joined to exactly one table in the joined set, that table is added to the joined set, and the search for another table to join begins. If the search encounters a table in the unjoined set that can be joined to two or more tables in the joined set, the method returns an error indicating that the join conditions are ambiguous -- the method will only return a set of joins that correspond to a tree graph (where tables are nodes and joins are bonds) and will reject any multiply connected set of joins. If it is found that none of the tables in the unjoined set can be directly joined to any table in the joined set, the method then cycles through the unjoined set again in search of a table that can be joined to exactly one table in the joined set through a linking tables. If it finds a table that is connected via linking tables to two or more tables in the joined set, it will also return an error. If the search does not identify any unjoined table that can be joined to a table in the joined set either through a direct reference or a linking table, the method returns an error indicating that the required set of tables can not be joined.

SQL Utilities

quote()

The quote method returns an SQL literal string representation of the parameter $value.

Synposis:

string quote(mixed $value)

The DB_Table_Database::quote() method calls either the DB::quoteSmart() or MDB2::quote() method internally. The return value is always a string, with a return value whose format depends upon the PHP type of $value: If $value is a string, the method returns a string that is properly quoted and escaped for the underlying RDBMS. If $value is an integer or float, it returns an unquoted string representation of the number. If $value is boolean, it returns '1' for true, or '0' for false (consistent with the representation of booleans as integers used by the DB_Table abstract data type). If $value is null, it returns the unquoted string NULL.

buildFilter()

buildFilter() returns a SQL logical expression that is true if the values of a specified set of database columns are equal to a corresponding set of SQL literal values. It must be passed an array parameter in which the array keys are column names and the array values are the required values.

The following example uses the buildFilter method to construct a filter for addresses on Pine St. in Peoria:

<?php
$data = array('Street' => 'Pine St', 'City' => 'Peoria');
$filter = $db->buildFilter($data);
?>

Printing $filter then yields the SQL snippet:

Street = 'Pine St' AND City = 'Peoria'

In this example, the resulting SQL string is admittedly longer than the code required to create it. The function becomes more useful when the column names and/or values are variables representing data of various types, rather than string literals, or strings that may require escaping. The buildFilter method uses the quote method internally to construct SQL literal string representations of values.

buildSQL()

buildSQL() - takes a query array of the form used by the select* methods, and returns a corresponding SQL command string. It is called internally by the select*() methods. Both buildSQL() and the select*() methods are inherited from DB_Table_Base.

Synopsis: The interface is similar to that of the select*() methods:

string|PEAR_Error buildSQL(array|string $query, [string $filter], [string $order],
[int $start], [int $count])

As in the select*() methods, $query is a query array or a key for a query array stored in the $sql property, $filter is an SQL logical condition that is added to the 'where' element of the query array, $order is an ORDER BY clause that overrides the 'order' element of the query array when it is present, and $start and $count are the first row in the result set that should be returned, and the maximum number of rows that should be returned. Only the $query argument is required.

validCol()

validCol() - validates and (if necessary) disambiguates column names.

Synopsis:

array|PEAR_Error validCol(string $col, [array $from])

The required parameter $col is a column name. The optional $from parameter is a sequential array of table names.

The $col parameter may either be a column name qualified by a table name, using the SQL syntax table.column, or a column name that is not qualified by a table name, if the identification of the column with a table is unambiguous. The return value of validCol, upon success, is a sequential array in which the second element is the unqualified column name string, and the first element is either a table name (if $col is qualified by a table name or a unique table can be identified) or a sequential array of possible column names (if $col is an unqualified column name that could refer to columns in two or more different tables). If no column with the specified name exists in the database, a PEAR error is returned.

The optional $from parameter is used only when $col is not explicitly qualified by a table name. When it is present, $from is a sequential list of tables that should be searched for a column of the specified name (as in the from clause of an SQL select statement). In this case, validCol first searches the tables in $from, and returns a table name if this yields a unique result. If a set of or more tables in $from are found to contain a column with the specified name, the return value is that set, or a subset thereof. If none of the table in $from contain a columns with the specified name, the search is instead broadened to all tables in the database. If two or more choices still remain at this point (either more than one tables in from, or more than one tables in the rest of the database) the method tries excluding tables in which the specified column is a foreign key column, if this still leaves one or more tables in which the column is not a foreign key column.

Data Modification: insert(), update(), and delete()

The insert(), delete(), and update() methods of DB_Table_Database have interfaces and behaviors similiar to those of the corresponding methods of DB_Table. The only differences in the interfaces are that each of these DB_Table_Database method requires an additional first parameter whose value is the name of the table to which the SQL insert, update, or delete command should be applied.

Synopses:

true|PEAR_Error insert(string $table, array $data)
true|PEAR_Error delete(string $table, [string $where])
true|PEAR_Error update(string $table, array $data, [string $where])

In all three functions $table_name is the name of the table to which the operation should be applied. In the insert and update methods, $data is an associative array of data to be inserted or updated, in which the keys are column name strings and the values are the value to be inserted or updated in the database. In the delete and update methods, the optional $where parameter is a string containing an SQL logical condition that is used to select the rows that should be deleted or updated, respectively. That is, the $where parameter should contain the contents of the WHERE clause of the corresponding SQL command, without the 'WHERE ' prefix. Each method returns true on normal completion, and a PEAR Error if an error is encountered.

These DB_Table_Database methods are simple wrappers that call the corresponding methods DB_Table methods internally. As one result, overriding any of these methods in a subclass of DB_Table in order to customize the behavior of a specific table will automatically modify the behavior of the DB_Table_Database method.

The DB_Table_Database data insert() and update() methods can validate foreign key values before actually modifying data in the database, and can emulate referentially triggered actions such cascading deletes, if foreign key validation and these referentially triggered actions are enabled. The corresponding methods of DB_Table will take identical actions if the DB_Table has been added to a parent DB_Table_Database object (i.e., if it contains a reference to a parent object), and if these actions are enabled in the parent DB_Table_Database object. Foreign key validation is disabled by default. Referentially triggered actions are enabled by default, for any such action that is declared in the database model.

The insert() and update() methods return a PEAR_Error object if foreign key validation fails, or if an error occurs during any database command. A PEAR_Error is also returned if a 'restrict' ON DELETE or ON UPDATE action is declared, when such actions are enabled, if an attempt is made to delete or update any row that is referenced by a foreign key of one or more rows of another table.

PHP Serialization

One way to maintain the state of DB_Table_Database between web pages is to serialize the entire database as one string, and save it in a session variable, a file, or a database. A serialized DB_Table_Database object contains serialized versions of all of its tables, and thus contains the information necessary to reconstruct the database. Serialization is accomplished by the PHP serialize function:

<?php
$db_serial = serialize($db);
?>

The following two commands are necessary to unserialize and restore the state of a DB_Table_Database object:

<?php
$db = unserialize($db_serial);
$db->setDBconnection($DB_object);
?>

where $DB_object is a DB or MDB2 connection object. The setDBconnection method sets the same database connection for the parent DB_Table_Database object and all of the child DB_Table objects.

When a DB_Table_Database object is unserialized, each child DB_Table object is unserialized in turn by the DB_Table_Database::__wakeup() method. If the DB_Table objects are instances of subclasses of DB_Table, this requires that the definitions of these subclasses exist in memory prior to unserialization of the table. This can be accomplished by explicitly including the file or files containing the required class definitions in the file containing the unserialize command, or by taking advantage of an auto-load mechanism that is built into the wake-up method.

In order for autoloading of subclass definitions to work, each of the subclasses must be defined in a separate file in a default directory, with a filename that is given by the class name with an added '.php' extension. If the definition of a required subclass of DB_Table named "classname" is found to not exist in memory when needed during unserialization, the __wakeup() method tries to include a file named "classname.php" in this directory.

For autoloading to work, the base of each such filename must be the class name obtained by applying the built-in get_class function to the object. This yields a lower case class name PHP 4 and preserves the capitalization used in the class definition in PHP 5.

setTableSubclassPath()

setTableSubclassPath() - sets the path to the default directory for DB_Table subclass definitions.

Synopsis:

void setTableSubclassPath(string $path)

Parameter $path is the path to the desired directory, without a trailing directory separator. The path must be specified in the form required by a 'require_once" statement, with the current PHP settings.

XML Serialization

The toXML() and fromXML() methods may be used to serialize a database schema to, and unserialize it from, an XML string, respectively. The fromXML() method uses simpleXML to parse the XML string, and so requires PHP 5. (This is the only method in the class that is not compatible with PHP 4).

The XML schema used by these methods is an extension of the current MDB2_Schema DTD, extended so as to allow specification of foreign key references. This extension for foreign keys has been agreed upon for adoption in a future release of MDB2_Schema.

The toXML() method returns an XML string for the entire database, including all of its tables and foreign key references, like so:

<?php
$xml_string = $db->toXML();
?>

The DB_Table_Database::fromXML() method is a static method that takes an MDB2 XML database schema string as its only parameter and returns a DB_Table_Database object containing all the tables and references in the database. The following pair of commands is necessary to create a DB_Table_Database object and connect it to a RDBMS

<?php
$db = DB_Table_Database::fromXML($xml_string);
$db->setDBconnection($DB_object);
?>

Here, as for unserialization, the setDBconnection() method is used to establish a connection be the new object and a database server, where $DB_object is a DB or MDB2 connection object. The tables of the DB_Table_Database object that is returned by fromXML() are all instances of DB_Table itself, rather than of custom subclasses of DB_Table. fromXML() returns a PEAR_Error if the XML string cannot be parsed, if an error is thrown during instantiation of either the DB_Table_Database object or any of the child DB_Table objects, or if called with a PHP 4 interpreter (it requires PHP 5).

Setting DB_Table properties

Several methods of DB_Table_Database are used to set a common value of a DB_Table property for every child table in the database. These methods, which have the same names and interfaces as the corresponding DB_Table methods, are:

void autoValidInsert(bool $flag);
void autoValidUpdate(bool $flag);
void autoRecast(bool $flag);
void autoInc(bool $flag);

Each has a boolean argument that turns on (true) or off (false) one of the features of DB_Table. All of the relevant features affect data insertion and updating, and are implemented within the DB_Table insert() and update() methods. The DB_Table_Database insert() and update() methods simply call the corresponding DB_Table methods, so changes in these properties also change the behavior of the DB_Table_Database methods.

The autoValidInsert and autoValidUpdate methods turn on or off the automatic validation that data is of the expected type prior to insertion or updating of the data. The autoRecast method turns on or off the attempted recasting of data to the expected data type, if necessary, prior to insertion or updating. autoInc turns on or off the PHP implementation of auto-incrementation of the value of the $auto_inc_col column (if any) upon insertion. Note that, when the feature is on, this column is still auto-incremented only if its value is left null in the data to be inserted.

Get* Methods

Most of the properties of DB_Table_Database are private. A get* method is defined for each private property. Please see the API documentation for a discussion of all of properties and associated get* methods.

Prev | DB_Table | Next
DB_Table Forms Tutorial | PEAR Manual | DB_Table_Generator Class Tutorial


DB_Table_Generator Class Tutorial

DB_Table_Generator Class Tutorial

DB_Table_Generator Class Tutorial – Code generation for an existing database

Description

The DB_Table_Generator class can generate the PHP code necessary to use the DB_Table package to interact with an existing database. It generates skeleton DB_Table subclass definitions for every table in the database, using table schemas that are obtained by querying the database. It can also generate a file containing the code required to connect to the database, and to create a parent DB_Table_Database object.

Name Conventions and File Structure

All code generated by a DB_Table_Generator object is written to a directory whose path is given by the $class_write_path property of that object. By default, this is the current directory. By default, the name of the class constructed for a table named 'thing' is Thing_Table. That is, the class name is the table name, with the first letter upper case, with an added suffix '_Table'. This suffix can be changed by setting the $class_suffix property. The name of the file containing a subclass definition is the subclass name with a PHP extension, e.g., 'Thing_Table.php'. The name of the object instantiated from that subclass is the same as the table name, with no suffix, e.g., 'thing'.

Code Generation Instructions

To generate the code for all of the tables in a database named $database, instantiate a DB or MDB2 object named $conn that connects to the database of interest, and execute the following code:

Code Generation for an Entire Database

<?php
require_once 'DB/Table/Generator.php';

// [snip] Instantiate DB or MDB2 object $conn

// Instantiate a Generator object
$generator = new DB_Table_Generator($conn, $database);

// Choose a directory for the generated code
$generator->class_write_path = '/var/www/html/app1/db_table' ;

// Generate DB_Table subclass definition files
$generator->generateTableClassFiles();

// Generate the 'Database.php' file
$generator->generateDatabaseFile();

?>

In the above example, '/var/www/html/app1/db_table' is the path (without a trailing directory separator) to a directory in which all of the code should be written. If this directory does not exist, it will be created (if possible). If the directory does already exist, existing files will not be overwritten. If $class_write_path is not set (i.e., if this line from the example is ommitted) all the code will be written to the current directory.

The generateTableClassFiles() method generates skeleton subclass definitions for a set of tables, with different subclass definitions in different files. If it is called with no argument, as above, it generates subclass definitions for all of the tables in the current database.

The generateDatabaseFile() method generates a file, named 'Database.php' by default, that contains all of the additional code necessary to connect to a database and to create a parent DB_Table_Database object. If the generateDatabaseFile() method is called, as in the above example, it must be called after the generateTableClassFiles(). The code in the 'Database.php' file includes (using the "require_once" command) each of the table subclass definition files, instantiates one object of each DB_Table subclass (creating one object per table), instantiates a parent DB_Table_Database object, adds all the tables to that parent, and attempts to guess foreign key relationships between tables based on the column names. This file will generally need to be edited so as to include information about the data source name (DSN), and any foreign key relationships that could not be guessed by the generator.

By default, generateTableClassFiles() and generateDatabaseFiles() generate code for all of the tables in the current database. To generate code for a specified list of tables, set the value of the public $tables property to a sequential list of table names before calling either of these methods. For example, code can be generated for three tables named 'table1', 'table2', and 'table3' as follows:

Code Generation for a Specified Set of Tables

<?php
require_once 'DB/Table/Generator.php'

// [snip] Instantiate DB or MDB2 object $conn

// Instantiate a Generator object
$generator = new DB_Table_Generator($conn, $database);

// Choose a directory for the generated code
$generator->class_write_path = '/var/www/html/app1/db_table' ;

// Define the set of tables
$generator->tables = array('table1', 'table2', 'table3');

// Generate DB_Table subclass definition files
$generator->generateTableClassFiles();

// Generate the 'Database.php' file
$generator->generateDatabaseFile();

?>

If the $tables property of the DB_Table_Generator object is not set to an array value before generateTableClassFiles() is called, then, by default, the generateTableClassFiles() method queries the database for an array of all table names (by calling the getTableNames() method internally), and the $table property is set equal to the resulting array of table names.

Prev | DB_Table | Next
DB_Table_Database Class Tutorial | PEAR Manual | DB_Table Data Types


DB_Table Data Types

DB_Table Data Types

DB_Table Data Types – Abstract data types used in DB_Table column definitions

Description

These are the supported data types in DB_Table:

  • Integers of 2-, 4-, and 8-bytes ('smallint', 'integer', and 'bigint')

  • Fixed-point decimals ('decimal')

  • Floating-point decimals of single or double precision ('float' and 'double')

  • Booleans for true/false values ('boolean')

  • Character strings of fixed or variable length ('char' and 'varchar')

  • Dates in ISO "yyyy-mm-dd" format ('date')

  • Times in ISO "hh:ii:ss" format ('time')

  • Timestamps in ISO "yyyy-mm-dd hh:ii:ss" format ('timestamp')

  • Character large objects (CLOB) for text or ascii data ('clob')

DB_Table abstracts data types for you, so your data is always stored the same way, regardless of the database backend. In some cases, particularly with date, time, and timestamp, the native database format is ignored completely and data is stored as a fixed-length character string.

DB_Table does no support binary large objects (BLOBs), but character large objects (CLOBS) are available.

Integers

There are three sizes of integer columns:

  • 'smallint' can store values from (-2^15) to +(2^15); that is, from -32778 to 32767

  • 'integer' can store values from (-2^31) to +(2^31); that is, from -2,147,483,648 to +2,147,483,647

  • 'bigint' can store values from (-2^63) to +(2^63); that is, from -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807

The $col definition, you need only specify the column type; no size or scope is needed.

Integer column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'    => 'integer'
    )
);
?>

Fixed-Point Decimal Numbers

To define a fixed-point column in DB_Table, use the 'decimal' datatype, and indicate both the 'size' (width) and 'scope' (number of decimal places). For example, to define a 5-digit number that has 2 decimal places:

Decimal column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'decimal',
        'size'  => 5,
        'scope' => 2
    ),
);
?>

For the above example, standard SQL requires that the column be able to store any value with 5 digits and 2 decimals. In this case, therefore, the range of values that can be stored in the column is from -999.99 to 999.99. DB_Table attempts to enforce this behavior regardless of the RDBMS backend behavior.

Floating-Point Numbers

To define a floating-point column in DB_Table, use the 'single' or 'double' datatype.

  • 'single' is a single-precision floating point number

  • 'double' is a double-precision floating point number

You need only specify the column type; no size or scope is needed.

Floating-point column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'double'
    ),
);
?>

Boolean

A boolean value is a true/false (1 or 0) value. You need only specify the column type; no size or scope is needed.

Boolean column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'boolean'
    )
);
?>

Boolean values are stored as fixed-point decimals of size 1, scope 0.

If the column is not required, a NULL value stored therein may be treated as a third value, which allows the boolean column to be treated as a ternary value instead of a binary value (i.e., NULL|0|1 instead of 0|1).

Strings

To define a fixed-length character string column, use the 'char' datatype, and indicate the exact size of the string.

To define a variable-length character string column, use the 'varchar' datatype, and indicate the maximum size of the string.

For example, to define a 64-character variable-length string:

Variable length string column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'varchar',
        'size'  => 64
    )
);
?>

You must specify a 'size' element, but no scope is needed. The maximum size is 255 characters.

Date

To define an ISO-standard date column, use the 'date' datatype.

Date column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'date'
    )
);
?>

You need only specify the column type; no size or scope is needed.

Values for 'date' are always stored as 10-character strings, in the format "yyyy-mm-dd".

Time

To define an ISO standard time with hour, minutes, and seconds, use the 'time' data type.

Time column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'time'
    )
);
?>

You need only specify the column type; no size or scope is needed.

A 'time' value is always stored as an 8-character string, in the format "hh:ii:ss".

Timestamp

To define an ISO standard date-and-time column, use the 'timestamp' data type.

Timestamp column declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'timestamp'
    )
);
?>

You need only specify the column type; no size or scope is needed.

Values for 'timestamp' are always stored as an 19-character strings, in the format "yyyy-mm-dd hh:ii:ss" (24-hour clock).

Note: If you want to store a Unix timestamp, use the 'integer' datatype; Unix timestampes are 4-byte integers, which maps perfectly to the DB_Table 'integer' datatype.

Character Large Object (CLOB)

CLOB Column Declaration

<?php
var $col = array(
    // unique row ID
    'fieldname' => array(
        'type'  => 'clob'
    )
);
?>

You need only specify the column type; no size or scope is needed.

Values for 'clob' are always stored as the large possible native text type (e.g., LONGTEXT) or native CLOB type.

Prev | DB_Table | Next
DB_Table_Generator Class Tutorial | PEAR Manual | MDB


MDB

MDB

A unified API for accessing databases, based on user provided meta data.

Table of Contents
  • Introduction - DSN -- The Data Source Name
  • Introduction - Connect -- Connecting and disconnecting a database
  • Introduction - Query -- Performing a query against a database.
  • Introduction - Fetch -- Fetching rows from the query
  • Introduction - Sequences -- Database sequences
  • Introduction - Execute -- Prepare & Execute/ExecuteMultiple
  • MDB -- Main class
  • MDB::connect() -- connects to database
  • MDB::isError() -- checks for an error
  • MDB_Common -- Interface for database access
  • MDB_Common::affectedRows() -- Number of affected rows
  • MDB_Common::createSequence() -- create a new sequence
  • MDB_Common::currId() -- returns the current free id of a sequence
  • MDB_Common::disconnect() -- disconnect from a database
  • MDB_Common::dropSequence() -- deletes a sequence
  • MDB_Common::execute() -- executes a prepared SQL statement
  • MDB_Common::executeQuery() -- executes a prepared SQL statement
  • MDB_Common::executeMultiple() -- repeated execution of a prepared SQL statement
  • MDB_Common::fetchAll() -- fetch result set as a nested array
  • MDB_Common::fetchCol() -- Fetch a single column
  • MDB_Common::fetchOne() -- fetch the first column of the first row
  • MDB_Common::fetchRow() -- fetch the first row
  • MDB_Common::fetchInto() -- fetch a row into a variable
  • MDB_Common::freeResult() -- delete the result set
  • MDB_Common::getAll() -- Fetch all rows
  • MDB_Common::getAssoc() -- fetch result set as associative array
  • MDB_Common::getCol() -- Fetch a single column
  • MDB_Common::getOne() -- fetch the first column of the first row
  • MDB_Common::getRow() -- fetch the first row
  • MDB_Common::getTextValue() -- quotes a string
  • MDB_Common::limitQuery() -- send a limited query to the database
  • MDB_Common::nextId() -- returns the next free id of a sequence
  • MDB_Common::numCols() -- get number of columns
  • MDB_Common::numRows() -- get number of rows
  • MDB_Common::prepareQuery() -- prepares a SQL statement
  • MDB_Common::query() -- send a query to the database
  • MDB_Common::queryAll() -- fetch result set as a nested array
  • MDB_Common::queryCol() -- Fetch a single column
  • MDB_Common::queryOne() -- fetch the first column of the first row
  • MDB_Common::queryRow() -- fetch the first row
  • MDB_Common::setFetchMode() -- sets the default fetch mode
  • MDB_Common::tableInfo() -- get table info from a query
  • MDB_Error -- MDB Error object
Prev | Database | Next
DB_Table Data Types | PEAR Manual | Introduction - DSN


Introduction - DSN

Introduction - DSN

Introduction - DSN – The Data Source Name

Description

To connect to a database through PEAR::MDB, you have to create a valid DSN - data source name. This DSN consists in the following parts:

  • phptype : Database backend used in PHP (i.e. mysql , odbc etc.)
  • dbsyntax : Database used with regards to SQL syntax etc.
  • protocol : Communication protocol to use ( i.e. tcp , unix etc.)
  • hostspec : Host specification (hostname[:port] )
  • database : Database to use on the DBMS server
  • username : User name for login
  • password : Password for login
  • proto_opts : Maybe used with protocol

The format of the supplied DSN is in its fullest form:

phptype(dbsyntax)://username:password@protocol+hostspec/database

Most variations are allowed:

phptype://username:password@protocol+hostspec:110//usr/db_file.mdb
phptype://username:password@hostspec/database_name
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype(dbsyntax)
phptype

The currently supported database backends are:

mysql  -> MySQL
pgsql  -> PostgreSQL
ibase  -> InterBase
mssql  -> Microsoft SQL Server
oci8   -> Oracle 7/8/8i
fbsql  -> FrontBase

With an up-to-date version of MDB, you can use a second DSN format

phptype(syntax)://user:pass@protocol(proto_opts)/database

Connect to database through a socket

mysql://user@unix(/path/to/socket)/pear

Connect to database on a non standard port

pgsql://user:pass@word@tcp(localhost:5555)/pear

Please note, that some features may be not supported by all database backends. Please refer to the PEAR MDB extensions status document located at: <pear base dir>/MDB/STATUS to get a detailed list about what features are supported by which backend.

Prev | MDB | Next
MDB | PEAR Manual | Introduction - Connect


Introduction - Connect

Introduction - Connect

Introduction - Connect – Connecting and disconnecting a database

Description

To connect to a database you have to use the function MDB::connect() , which requires a valid DSN as parameter and optional a boolean value, which determines wether to use a persistent connection or not. In case of success you get a new instance of the database class. It is strongly recommended to check this return value with MDB::isError() . To disconnect use the method disconnect() from your database class instance.

Connect and disconnect

<?php
require_once 'MDB.php';

$user = 'foo';
$pass = 'bar';
$host = 'localhost';
$db_name = 'clients_db';

// Data Source Name: This is the universal connection string
$dsn = "mysql://$user:$pass@$host/$db_name";

// MDB::connect will return a PEAR MDB object on success
// or an PEAR MDB Error object on error

$db = MDB::connect($dsn);

// With MDB::isError you can differentiate between an error or
// a valid connection.
if (MDB::isError($db)) {
    die ($db->getMessage());
}

....
// close conection
$db->disconnect();
?>
Prev | MDB | Next
Introduction - DSN | PEAR Manual | Introduction - Query


Introduction - Query

Introduction - Query

Introduction - Query – Performing a query against a database.

Description

To perform a query against a database, you have to use the function query(), that takes the query string as an argument. On failure you get a MDB_Error object. Be sure to check it with MDB::isError(). On success, you get MDB_OK or when you set a SELECT -statement a result resource handle

A simple MDB query

<?php
// Once you have a valid MDB object...
$sql = "select * from clients";

$result = $db->query($sql);

// Always check that $result is not an error
if (MDB::isError($result)) {
    die ($result->getMessage());
}

// Continue on with your script
?>
Prev | MDB | Next
Introduction - Connect | PEAR Manual | Introduction - Fetch


Introduction - Fetch

Introduction - Fetch

Introduction - Fetch – Fetching rows from the query

Description

Fetch functions

In order to fetch data from a result resource you can use one if the following methods: fetchInto() , fetchOne() . , fetchRow() . , fetchCol() . and fetchAll() . All above mentioned methods except fetchOne() return the requested data encapsuled into a (multi-dimensional-)array, NULL on no more data or a MDB_Error , when an error occurs. All method prefixed with fetch() automatically free the result set.

Fetching a result set

<?php
...
$db = MDB::connect($dsn);
$res = $db->query("SELECT * FROM mytable");

// Get each row of data on each iteration until
// there are no more rows
while ($row = $db->fetchInto($res)) {
    $id = $row[0];
}

// If we are just interested in the first column of the first row
$id = $db->fetchOne($res);

// Since the fetch methods always free the result set
// we cannot loop across the result set but instead
// need to choose the proper fetch method
$data = $db->getAll($res);
foreach($data as $row)
{
    $id = $row[0];
}
?>

Select the format of the fetched row

The fetch modes supported are:

  • MDB_FETCHMODE_ORDERED (default)

    The fetch*() returns an ordered array. The order is taken from the select statement.

    Fetch a ordered array

    <?php
    $res     = $db->query('SELECT id, name, email FROM users');
    $row = $db->fetchRow($res, MDB_FETCHMODE_ORDERED);
    /*
    $row will contain:
    array (
        0 => <column "id" data>,
        1 => <column "name" data>,
        2 => <column "email" data>
    )
    */
    // Access the data with:
    $id    = $row[0];
    $name  = $row[1];
    $email = $row[2];
    ?>

  • MDB_FETCHMODE_ASSOC

    Returns an associative array with the column names as the array keys

    Fetch a assoc. array

    <?php
    $res     = $db->query('SELECT id, name, email FROM users');
    $row = $db->fetchRow($res, MDB_FETCHMODE_ASSOC);
    /*
    $row will contain:
    array (
        'id'    => <column "id" data>,
        'name'  => <column "name" data>,
        'email' => <column "email" data>
    )
    */
    // Access the data with:
    $id    = $row['id'];
    $name  = $row['name'];
    $email = $row['email'];
    ?>

Set the format of the fetched row

You can set the fetch mode per result call or for your whole MDB instance.

Per call

<?php
while ($row = $db->fetchInto($res, MDB_FETCHMODE_ASSOC)) {
    $id = $row['id'];
}
?>

Once per instance

<?php
$db = MDB::connect($dsn);
// this will set a default fetchmode for this Pear MDB instance
// (for all queries)
$db->setFetchMode(MDB_FETCHMODE_ASSOC);

$result = $db->query(...);

while ($row = $db->fetchRow($res)) {
    $id = $row['id'];
}
?>

Fetch rows by number

The PEAR MDB fetch system also supports an extra parameter to the fetch statement. So you can fetch rows from a result by number. This is especially helpful if you only want to show sets of an entire result (for example in building paginated HTML lists), fetch rows in an special order, etc.

Fetching by number

<?php
...
// the row to start fetching
$from = 50;

// how many results per page
$resPage = 10;

// the last row to fetch for this page
$to = $from + $resPage;

foreach (range($from, $to) as $rowNum) {
if (!$row = $db->fetchInto($res, $fetchmode, $rowNum)) {
        break;
    }
    $id = $row[0];
    ....
}
?>

Freeing the result set

It is recommended to finish the result set after processing in order to to save memory. Use freeResult() to do this.

Freeing

<?php
...
$res = $db->query('SELECT * FROM clients');
while ($row = $res->fetchInto($res)) {
...
}
$db->freeResult($res);
?>

Quick data retrieving

MDB provides some special ways to retrieve information from a query without the need of using fetch*() and loop throw results.

queryOne() retrieves the first result of the first column from a query

<?php
$numrows = $db->queryOne('select count(id) from clients');
?>

queryRow() returns the first row and returns it as an array.

<?php
$sql = 'select name, address, phone from clients where id=1';
if (is_array($row = $db->queryRow($sql))) {
    list($name, $address, $phone) = $row;
}
?>

queryCol() returns an array with the data of the selected column. It accepts the column number to retrieve as the second parameter.

<?php
$all_client_names = $db->queryCol('SELECT name FROM clients');
?>

The above sentence could return for example:

<?php
$all_client_names = array('Stig', 'Jon', 'Colin');
?>

getAll() fetches all the rows returned from a query. This method also has some advanced parameters still will also enable you to return the data as an associative array using the first column as the key.

<?php
$data = getAll('SELECT id, text, date FROM mytable');
/*
Will return:
array(
   1 => array('4', 'four', '2004'),
   2 => array('5', 'five', '2005'),
   3 => array('6', 'six', '2006')
)
*/
?>

The query*() family methods will do all the dirty job for you, this is: launch the query, fetch the data and free the result. Please note that as all PEAR MDB functions they will return a MDB_Error object on errors.

Getting more information from query results

With MDB you have many ways to retrieve useful information from query results. These are:

  • numRows() : Returns the total number of rows returned from a "SELECT" query.

    <?php
    // Number of rows
    echo $db->numRows($res);
    ?>

  • numCols() : Returns the total number of columns returned from a "SELECT" query.

    <?php
    // Number of cols
    echo $db->numCols($res);
    ?>

  • affectedRows() : Returns the number of rows affected by a data manipulation query ("INSERT", "UPDATE" or "DELETE").

    <?php
    // remember that this statement won't return a result object
    $db->query('DELETE * FROM clients');
    echo     'I have deleted ' . $db->affectedRows() . ' clients';
    ?>

  • tableInfo() : Returns an associative array with information about the returned fields from a "SELECT" query.

    <?php
    // Table Info
    print_r($db->tableInfo($res));
    ?>

Don't forget to check if the returned result from your action is a MDB_Error object. If you get a error message like "MDB_Error: database not capable", means that your database backend doesn't support this action.

Prev | MDB | Next
Introduction - Query | PEAR Manual | Introduction - Sequences


Introduction - Sequences

Introduction - Sequences

Introduction - Sequences – Database sequences

Description

Sequences are a way of offering unique IDs for data rows. If you do most of your work with e.g. MySQL, think of sequences as another way of doing AUTO_INCREMENT. It's quite simple, first you request an ID, and then you insert that value in the ID field of the new row you're creating. You can have more than one sequence for all your tables, just be sure that you always use the same sequence for any particular table. To get the value of this unique ID use nextId() , if a sequence doesn't exists, it will be created automaticlly.

Using a sequence

<?php
...
$id = $db->nextId('mySequence');
// Use the ID in your INSERT query
$res = $db->query("INSERT INTO myTable (id,text) VALUES ($id,'foo')");
...
?>
Prev | MDB | Next
Introduction - Fetch | PEAR Manual | Introduction - Execute


Introduction - Execute

Introduction - Execute

Introduction - Execute – Prepare & Execute/ExecuteMultiple

Description

Purpose

prepareQuery() and executeQuery*() give you more power and flexibilty for query execution. You can use them, if you have to do more than one equal query (i.e. adding a list of adresses to a database) or if you want to support different databases, which have different implementations of the SQL standard.

Imagine you want to support two databases with different INSERT syntax:

db1 : INSERT INTO tbl_name ( col1, col2 ... ) VALUES ( expr1, expr2 ... )
db2 : INSERT INTO tbl_name SET col1=expr1, col2=expr2 ...

Corresponding to create multi-lingual scripts you can create a array with queries like this:

<?php
$statement['db1']['INSERT_PERSON'] = "INSERT INTO person ( surname, name, age ) VALUES ( ?, ?, ? )" ;
$statement['db2']['INSERT_PERSON'] = "INSERT INTO person SET surname=?, name=?, age=?" ;
?>

Prepare

To use the features above, you have to do two steps. Step one is to prepareQuery the statement and the second is to executeQuery it.

Prepare() has to be called with the generic statement at least once. It returns a handle for the statement.

To create a generic statement is simple. Write the SQL query as usual, i.e.

SELECT surname, name, age FROM person
WHERE name = 'name_to_find' AND age < 'age_limit'

Now check which parameters should be replaced while script runtime. Substitute this parameters with a placeholder.

SELECT surname, name, age FROM person WHERE name = ? AND age < ?

So, thats all! Now you have a generic statement, required by prepareQuery() .

prepareQuery() can handle different types of placeholders or wildcards.

  • ? - (recommended) stands for a scalar value like strings or numbers, the value will be quoted depending of the database
  • ! - stands for a scalar value and will inserted into the statement "as is".
  • & - requires an existing filename, the content of this file will be included into the statement (i.e. for saving binary data of a graphic file in a database)

Execute/ ExecuteMultiple

After preparing the statement, you can execute the query. This means to assign the variables to the prepared statement. To do this, executeQuery() requires two arguments, the statement handle of prepareQuery() and an array with the values to assign. The array has to be numerically ordered. The first entry of the array represents the first wildcard, the second the second wildcard etc. The order is independent from the used wildcard char.

Inserting data into a datebase

<?php
$alldata = array(  array(1, 'one', 'en'),
                   array(2, 'two', 'to'),
                   array(3, 'three', 'tre'),
                   array(4, 'four', 'fire'));
$sth = $dbh->prepareQuery("INSERT INTO numbers VALUES(?,?,?)");
foreach ($alldata as $row) {
    $dbh->executeQuery($sth, $row);
}
?>

In the example the query is done four times:

INSERT INTO numbers VALUES( '1', 'one', 'en')
INSERT INTO numbers VALUES( '2', 'two', 'to')
INSERT INTO numbers VALUES( '3', 'three', 'tre')
INSERT INTO numbers VALUES( '4', 'four', 'fire')

executeMultiple() works in the same way, but requires a two dimensional array. So you can avoid the explicit foreach in the eample above.

Using executeMultiple() instead of executeQuery()

<?php
...
$alldata = array(  array(1, 'one', 'en'),
                   array(2, 'two', 'to'),
                   array(3, 'three', 'tre'),
                   array(4, 'four', 'fire'));
$sth = $dbh->prepareQuery("INSERT INTO numbers VALUES(?,?,?)");
$dbh->executeMultiple($sth, $alldata);
}
?>

The result is the same. If one of the records failed, the unfinished records will not be executed.

If executeQuery*() fails a MDB_Error, else MDB_OK will returned.

Prev | MDB | Next
Introduction - Sequences | PEAR Manual | MDB


MDB

MDB

MDB – Main class

Description

The main MDB class is simply a container class with some static methods for creating MDB objects.

Prev | MDB | Next
Introduction - Execute | PEAR Manual | MDB::connect()


MDB::connect()

MDB::connect()

MDB::connect() – connects to database

Synopsis

require_once 'MDB.php';

object MDB::connect ( string $dsn , boolean $options = false )

Description

Creates a new MDB connection object and connect to the specified database

Parameter

string $dsn

Data Source Name. See the "DSN" section for further information.

boolean $options

If $options is TRUE the connection will be persistent (requires support by database driver). Default is FALSE. In future releases, this parameter will be an array and take different options depending on the database.

Return value

object - the created MDB connection object, or a MDB_Error object on error.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NOT_FOUND | NULL | The database specific class was not found. | Check the $dsn and make sure to have an complete installation of the MDB-package and that you database is supported by MDB.

Note

This function should be called statically.

See

MDB::disconnect() , Tutorial - Connect()

Prev | MDB | Next
MDB | PEAR Manual | MDB::isError()


MDB::isError()

MDB::isError()

MDB::isError() – checks for an error

Synopsis

require_once 'MDB.php';

boolean MDB::isError ( mixed $value )

Description

Checks whether a result code from a MDB method is a MDB_Error object or not.

Parameter

mixed $value

Variable to check

Return value

boolean - TRUE, if $value is a MDB_Error object

Note

This function should be called statically.

Prev | MDB | Next
MDB::connect() | PEAR Manual | MDB_Common


MDB_Common

MDB_Common

MDB_Common – Interface for database access

Description

MDB_Common is an interface class; that provides all methods to query a specific database. An instance of a database specific class will be returned by the MDB::connect() method.

Prev | MDB | Next
MDB::isError() | PEAR Manual | MDB_Common::affectedRows()


MDB_Common::affectedRows()

MDB_Common::affectedRows()

MDB_Common::affectedRows() – Number of affected rows

Synopsis

require_once 'MDB.php';

integer affectedRows ( )

Description

Number of affected rows by a query

Return value

integer - number of rows or MDB_Error when fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NOT_CAPABLE | NULL | Function is not supported by the database backend | Switch to another database system, if you really need this feature.

Note

This function can not be called statically.

See

query()

Prev | MDB | Next
MDB_Common | PEAR Manual | MDB_Common::createSequence()


MDB_Common::createSequence()

MDB_Common::createSequence()

MDB_Common::createSequence() – create a new sequence

Synopsis

require_once 'MDB.php';

integer createSequence ( string $seq_name , integer $start )

Description

See "Introduction - Sequences"

Parameter

string $seq_name

name of the new sequence to create

integer $start

starting value of the sequence

Return value

integer - MDB_OK or MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every error code |  | Database specific error | Check the name of the sequence. If correct, probably a bug in the sequence implementation

Note

This function can not be called statically.

See

MDB::nextId() , MDB::dropSequence()

Prev | MDB | Next
MDB_Common::affectedRows() | PEAR Manual | MDB_Common::currId()


MDB_Common::currId()

MDB_Common::currId()

MDB_Common::currId() – returns the current free id of a sequence

Synopsis

require_once 'MDB.php';

resource currId ( string $seq_name )

Description

See "Introduction - Sequences"

Parameter

string $seq_name

name of the sequence

Return value

resource - a free id or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NOT_CAPABLE | NULL | Function is not supported by the database backend | Switch to another database system, if you really need this feature.
MDB_ERROR_NOT_LOCKED | NULL | Locking of sequence table fails | Database specific, check documention of your database,
MDB_ERROR_NOSUCHTABLE | NULL | Sequence table was not found | Try to create a new sequence or if you are sure, a sequence was already create, check database integrity

Note

This function can not be called statically.

See

createSequence() , dropSequence()

Prev | MDB | Next
MDB_Common::createSequence() | PEAR Manual | MDB_Common::disconnect()


MDB_Common::disconnect()

MDB_Common::disconnect()

MDB_Common::disconnect() – disconnect from a database

Synopsis

require_once 'MDB.php';

boolean MDB::disconnect ( )

Description

Disconnects from a database

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

See

MDB::connect() , Tutorial - Connect()

Prev | MDB | Next
MDB_Common::currId() | PEAR Manual | MDB_Common::dropSequence()


MDB_Common::dropSequence()

MDB_Common::dropSequence()

MDB_Common::dropSequence() – deletes a sequence

Synopsis

require_once 'MDB.php';

integer dropSequence ( string $seqName )

Description

See "Introduction - Sequences"

Parameter

string $seqName

name of the sequence to delete

Return value

  • integer - MDB_OK or MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every error code |  | Database specific error | Check the name of the sequence. If correct, probably a bug in the sequence implementation.

Note

This function can not be called statically.

See

MDB_Common::createSequence() , MDB_Common::nextId()

Prev | MDB | Next
MDB_Common::disconnect() | PEAR Manual | MDB_Common::execute()


MDB_Common::execute()

MDB_Common::execute()

MDB_Common::execute() – executes a prepared SQL statement

Synopsis

require_once 'MDB.php';

mixed execute ( resource $stmt , array $types = null , array $params = array() , array $param_types = null )

Description

execute() joins the prepared SQL statement from prepareQuery() with the given data and executes the SQL query.

Parameter

resource $stmt

query handle from prepareQuery()

array $types

if supplied, the types of the columns in the result set will be set for fetching

array $params

a numeric array containing the data to insert into the query

array $param_types

if supplied, the values in $param will automatically be set to the passed datatypes

Return value

mixed - a resource id/MDB_OK or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement handle is not valid. | Check correct processing of the SQL statement with prepareQuery() . Note that execute() requires a handle to the statement returned by prepareQuery() , not the statement itself.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement for prepareQuery() . Check the count of entries in the array for $data . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

prepareQuery() , executeMultiple()

Prev | MDB | Next
MDB_Common::dropSequence() | PEAR Manual | MDB_Common::executeQuery()


MDB_Common::executeQuery()

MDB_Common::executeQuery()

MDB_Common::executeQuery() – executes a prepared SQL statement

Synopsis

require_once 'MDB.php';

mixed executeQuery ( resource $stmt , array $types = null )

Description

executeQuery() joins the prepared SQL statement from prepareQuery() with the data that was set using one of the setParam() methods and executes the SQL query.

Parameter

resource $stmt

query handle from prepareQuery()

array $types

if supplied, the types of the columns in the result set will be set for fetching

Return value

mixed - a resource id/MDB_OK or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement handle is not valid. | Check correct processing of the SQL statement with prepareQuery() . Note that executeQuery() requires a handle to the statement returned by prepareQuery() , not the statement itself.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement for prepareQuery() . Check the count of entries in the array for $data . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See Introduction - Execute for general using and an example.

See

prepareQuery() , executeMultiple()

Prev | MDB | Next
MDB_Common::execute() | PEAR Manual | MDB_Common::executeMultiple()


MDB_Common::executeMultiple()

MDB_Common::executeMultiple()

MDB_Common::executeMultiple() – repeated execution of a prepared SQL statement

Synopsis

require_once 'MDB.php';

mixed executeMultiple ( resource $stmt , array $types = null , array $params = array() , array $param_types = null , array $data )

Description

executeMultiple() joins the prepared SQL statement from prepareQuery() with the given data and does the SQL query for every "row" in the $data array.

Parameter

resource $stmt

query handle from prepareQuery()

array $types

if supplied, the types of the columns in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

array array $data

a numeric array containing the data to insert into the query

Return value

mixed - a resource id/MDB_OK or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement handle is not valid. | Check correct processing of the SQL statement with prepareQuery() . Note that executeMultiple() requires a handle to the statement returned by prepareQuery() , not the statement itself.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement for prepareQuery() . Check the count of entries in the array for $data . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

If an error occurs during execution, the function will be stopped. Possible remaining data will be unprocessed.

See Introduction - Execute for general using and an example.

See

prepareQuery() , executeQuery()

Prev | MDB | Next
MDB_Common::executeQuery() | PEAR Manual | MDB_Common::fetchAll()


MDB_Common::fetchAll()

MDB_Common::fetchAll()

MDB_Common::fetchAll() – fetch result set as a nested array

Synopsis

require_once 'MDB.php';

array &fetchAll ( resource $result , integer $fetchmode = MDB_FETCHMODE_DEFAULT , boolean $rekey = false , boolean $force_array = false , boolean $group = false )

Description

Fetch the entire result set of a result set and return it into a nested array and free the result set.

Parameter

resource $result

a valid resource returned by query() or executeQuery()

integer $fetchmode

the fetch mode to use

boolean $rekey

if set to TRUE the array result be modified as follows: If the result set contains more than two columns, the value will be an array of the values from column 2 to n. If the result set contains only two columns, the returned value will be a scalar with the value of the second column (unless forced to an array with the $force_array parameter).

boolean $force_array

used only if the query returns exactly two columns. If TRUE, the values of the returned array will be one-element arrays instead of scalars.

boolean boolean $group

if TRUE, the values of the returned array is wrapped in another array. If the same key value (in the first column) repeats itself, the values will be appended to this array instead of overwriting the existing values.

Return value

array - an nested array or a MDB_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_TRUNCATED | NULL | The result set contains fewer then two columns | Check the SQL fetch or choose another fetch*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , fetchRow() , fetchOne() , fetchCol()

Prev | MDB | Next
MDB_Common::executeMultiple() | PEAR Manual | MDB_Common::fetchCol()


MDB_Common::fetchCol()

MDB_Common::fetchCol()

MDB_Common::fetchCol() – Fetch a single column

Synopsis

require_once 'MDB.php';

array &fetchCol ( resource $result , mixed $colnum = 0 )

Description

Fetch a single column from a result set of a result set and free the result set.

Parameter

resource $result

a valid resource returned by query() or executeQuery()

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

mixed $colnum

which column to return (integer [column number, starting at 0] or string [column name])

Return value

array - the first row of results as an array indexed from 0 or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_TRUNCATED | NULL | The result set contains fewer then two columns | Check the SQL query or choose another query*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , fetchRow() , fetchOne() , fetchAll()

Prev | MDB | Next
MDB_Common::fetchAll() | PEAR Manual | MDB_Common::fetchOne()


MDB_Common::fetchOne()

MDB_Common::fetchOne()

MDB_Common::fetchOne() – fetch the first column of the first row

Synopsis

require_once 'MDB.php';

mixed &fetchOne ( resource $result )

Description

Fetch the first column of the first row of data returned from a result set and free the result set.

Parameter

resource $result

a valid resource returned by query() or executeQuery()

Return value

mixed - the returned value or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , fetchRow() , fetchCol() , fetchCol()

Prev | MDB | Next
MDB_Common::fetchCol() | PEAR Manual | MDB_Common::fetchRow()


MDB_Common::fetchRow()

MDB_Common::fetchRow()

MDB_Common::fetchRow() – fetch the first row

Synopsis

require_once 'MDB.php';

array &fetchRow ( resource $result , integer $fetchmode = MDB_FETCHMODE_DEFAULT , integer $rownum = null )

Description

Fetch the first row of data returned from a result set and free the result set.

Parameter

resource $result

a valid resource returned by query() or executeQuery()

integer $fetchmode

the fetch mode to use, default is MDB_FETCHMODE_DEFAULT

integer $rownum

the row number to fetch

Return value

array - the first row of results as an array indexed from 0 or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() executeQuery() , fetchCol() , fetchRow()

Prev | MDB | Next
MDB_Common::fetchOne() | PEAR Manual | MDB_Common::fetchInto()


MDB_Common::fetchInto()

MDB_Common::fetchInto()

MDB_Common::fetchInto() – fetch a row into a variable

Synopsis

require_once 'MDB.php';

mixed fetchInto ( resource $result , integer $fetchMode = MDB_FETCHMODE_DEFAULT , integer $rownum = null )

Description

Fetch a row and return data in an array.

Parameter

resource $result

result identifier

integer $fetchMode

format of fetched row

integer $rownum

the row number to fetch

Return value

mixed - an array or NULL, if no more rows

Prev | MDB | Next
MDB_Common::fetchRow() | PEAR Manual | MDB_Common::freeResult()


MDB_Common::freeResult()

MDB_Common::freeResult()

MDB_Common::freeResult() – delete the result set

Synopsis

require_once 'MDB.php';

boolean freeResult ( resource $result )

Description

Deletes the result set and frees the memory occupied by the result set.

Parameter

resource $result

A valid resource returned by query() or executeQuery()

Return value

  • boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | MDB | Next
MDB_Common::fetchInto() | PEAR Manual | MDB_Common::getAll()


MDB_Common::getAll()

MDB_Common::getAll()

MDB_Common::getAll() – Fetch all rows

Synopsis

require_once 'MDB.php';

array &getAll ( string $query , array $types = null , array $params = array() , array $param_types = null , integer $fetchmode = MDB_FETCHMODE_DEFAULT )

Description

Fetch the entire result set of a query and return it into a nested array. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

integer $fetchmode

the fetch mode to use, default is MDB_FETCHMODE_DEFAULT

Return value

  • array - an nested array or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement for preparing is not valid. | See the prepareQuery() documentation, if you want to use a SQL statemt using wildcards.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement prepareQuery() . Check the count of entries in the array for $params . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() executeQuery() , getCol() , getRow() , getAssoc() , getOne()

Prev | MDB | Next
MDB_Common::freeResult() | PEAR Manual | MDB_Common::getAssoc()


MDB_Common::getAssoc()

MDB_Common::getAssoc()

MDB_Common::getAssoc() – fetch result set as associative array

Synopsis

require_once 'MDB.php';

array &getAssoc ( string $query , array $types = null , array $params = array() , array $param_types = null , integer $fetchmode = MDB_FETCHMODE_DEFAULT , boolean $force_array = false , boolean $group = false )

Description

Fetch the entire result set of a query and return it as an associative array using the first column as the key. The function takes care of doing the query and freeing the results when finished. If the result set contains more than two columns, the value will be an array of the values from column 2 to n. If the result set contains only two columns, the returned value will be a scalar with the value of the second column (unless forced to an array with the $force_array parameter).

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

integer $fetchmode

the fetch mode to use

boolean $force_array

used only if the query returns exactly two columns. If TRUE, the values of the returned array will be one-element arrays instead of scalars.

boolean boolean $group

if TRUE, the values of the returned array is wrapped in another array. If the same key value (in the first column) repeats itself, the values will be appended to this array instead of overwriting the existing values.

Return value

array - associative array with results from the query.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement for preparing is not valid. | See the prepareQuery() documentation, if you want to use a SQL statemt using wildcards.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement prepareQuery() . Check the count of entries in the array for $params . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
MDB_ERROR_TRUNCATED | NULL | The result set contains fewer then two columns | Check the SQL query or choose another get*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , getRow() , getOne() , getCol()

Prev | MDB | Next
MDB_Common::getAll() | PEAR Manual | MDB_Common::getCol()


MDB_Common::getCol()

MDB_Common::getCol()

MDB_Common::getCol() – Fetch a single column

Synopsis

require_once 'MDB.php';

array &getCol ( string $query , string $type = null , array $params = array() , array $param_types = null , mixed $colnum = 0 )

Description

Fetch a single column from a result set of a query. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query

string $type

if supplied, the type of the column in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

mixed $colnum

which column to return (integer [column number, starting at 0] or string [column name])

Return value

array - the first row of results as an array indexed from 0 or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement for preparing is not valid. | See the prepareQuery() documentation, if you want to use a SQL statemt using wildcards.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement prepareQuery() . Check the count of entries in the array for $params . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
MDB_ERROR_TRUNCATED | NULL | The result set contains fewer then two columns | Check the SQL query or choose another get*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , getRow() , getOne() , getAssoc()

Prev | MDB | Next
MDB_Common::getAssoc() | PEAR Manual | MDB_Common::getOne()


MDB_Common::getOne()

MDB_Common::getOne()

MDB_Common::getOne() – fetch the first column of the first row

Synopsis

require_once 'MDB.php';

mixed &getOne ( string $query , string $type = null , array $params = array() , array $param_types = null )

Description

Fetch the first column of the first row of data returned from a query. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query or the statement to prepare

string $type

if supplied, the type of the column in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

Return value

mixed - the returned value or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement for preparing is not valid. | See the prepareQuery() documentation, if you want to use a SQL statemt using wildcards.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement prepareQuery() . Check the count of entries in the array for $params . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , getRow() , getCol() , getCol() , getCol()

Prev | MDB | Next
MDB_Common::getCol() | PEAR Manual | MDB_Common::getRow()


MDB_Common::getRow()

MDB_Common::getRow()

MDB_Common::getRow() – fetch the first row

Synopsis

require_once 'MDB.php';

array &getRow ( string $query , array $types = null , array $params = array() , array $param_types = null , integer $fetchmode = MDB_FETCHMODE_DEFAULT )

Description

Fetch the first row of data returned from a query. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

integer $fetchmode

the fetch mode to use, default is MDB_FETCHMODE_DEFAULT

Return value

array - the first row of results as an array indexed from 0 or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_INVALID | NULL | SQL statement for preparing is not valid. | See the prepareQuery() documentation, if you want to use a SQL statemt using wildcards.
MDB_ERROR_NEED_MORE_DATA | NULL | To less data for filling the prepared SQL statement. | Check the number of wild cards given in the SQL statement prepareQuery() . Check the count of entries in the array for $params . The count of entries have to be equal to the number of wild cards.
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() executeQuery() , getCol() , getRow() , getAssoc()

Prev | MDB | Next
MDB_Common::getOne() | PEAR Manual | MDB_Common::getTextValue()


MDB_Common::getTextValue()

MDB_Common::getTextValue()

MDB_Common::getTextValue() – quotes a string

Synopsis

require_once 'MDB.php';

string MDB::getTextValue ( string $string )

Description

Quotes a string database-dependent, so it can be safely used in a query

Parameter

string $string

the input string to quote

Return value

string - the quoted string.

Note

This function can not be called statically.

Prev | MDB | Next
MDB_Common::getRow() | PEAR Manual | MDB_Common::limitQuery()


MDB_Common::limitQuery()

MDB_Common::limitQuery()

MDB_Common::limitQuery() – send a limited query to the database

Synopsis

require_once 'MDB.php';

mixed &limitQuery ( string $query , array $types , integer $from , integer $count )

Description

Executes a SQL query, but fetches only the specificed count of rows. It is an emulation of the MySQL LIMIT option.

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

integer $from

the row to start to fetch

integer $count

the numbers of rows to fetch

Return value

mixed - a new a resource id/MDB_OK or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

This module is EXPERIMENTAL. That means that the behaviour of these functions, these function names, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this module at your own risk.

Depending on the database you will not really get more speed compared to query() . The advantage of limitQuery() is the deleting of unneeded rows in the resultset, as early as possible. So this can decrease memory usage.

See

query()

Prev | MDB | Next
MDB_Common::getTextValue() | PEAR Manual | MDB_Common::nextId()


MDB_Common::nextId()

MDB_Common::nextId()

MDB_Common::nextId() – returns the next free id of a sequence

Synopsis

require_once 'MDB.php';

resource nextId ( string $seq_name , boolean $onDemand = true )

Description

See "Introduction - Sequences"

Parameter

string $seq_name

name of the sequence

boolean $onDemand

when TRUE the sequence is automatic created, if it not exists.

Return value

resource - a free id or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NOT_CAPABLE | NULL | Function is not supported by the database backend | Switch to another database system, if you really need this feature.
MDB_ERROR_NOT_LOCKED | NULL | Locking of sequence table fails | Database specific, check documention of your database,
MDB_ERROR_NOSUCHTABLE | NULL | Sequence table was not found | Try to create a new sequence or if you are sure, a sequence was already create, check database integrity

Note

This function can not be called statically.

See

createSequence() , dropSequence()

Prev | MDB | Next
MDB_Common::limitQuery() | PEAR Manual | MDB_Common::numCols()


MDB_Common::numCols()

MDB_Common::numCols()

MDB_Common::numCols() – get number of columns

Synopsis

require_once 'MDB.php';

integer numCols ( resource $result )

Description

Get the number of columns of the rows in a result set.

Parameter

resource $result

a valid resource returned by query() or executeQuery()

Return value

integer - number of columns

Note

This function can not be called statically.

See

MDB_Common::numRows()

Prev | MDB | Next
MDB_Common::nextId() | PEAR Manual | MDB_Common::numRows()


MDB_Common::numRows()

MDB_Common::numRows()

MDB_Common::numRows() – get number of rows

Synopsis

require_once 'MDB.php';

integer numRows ( resource $result )

Description

Get the number of rows in a result set.

Parameter

resource $result

a valid resource returned by query() or executeQuery()

Return value

integer - number of rows

Note

This function can not be called statically.

See

MDB_Common::numCols()

Prev | MDB | Next
MDB_Common::numCols() | PEAR Manual | MDB_Common::prepareQuery()


MDB_Common::prepareQuery()

MDB_Common::prepareQuery()

MDB_Common::prepareQuery() – prepares a SQL statement

Synopsis

require_once 'MDB.php';

resource prepareQuery ( string $query )

Description

Prepares a query for execution with executeQuery() .

Parameter

string $query

the query to prepareQuery

Return value

resource - the query handle

Note

This function can not be called statically.

See Introduction - Execute for general using and an example.

See

executeQuery() , executeQuery()

Prev | MDB | Next
MDB_Common::numRows() | PEAR Manual | MDB_Common::query()


MDB_Common::query()

MDB_Common::query()

MDB_Common::query() – send a query to the database

Synopsis

require_once 'MDB.php';

mixed &query ( string $query , array $types )

Description

Executes a SQL query

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

Return value

mixed - a new a resource id/MDB_OK or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

Prev | MDB | Next
MDB_Common::prepareQuery() | PEAR Manual | MDB_Common::queryAll()


MDB_Common::queryAll()

MDB_Common::queryAll()

MDB_Common::queryAll() – fetch result set as a nested array

Synopsis

require_once 'MDB.php';

array &queryAll ( string $query , array $types = null , integer $fetchmode = MDB_FETCHMODE_DEFAULT , boolean $rekey = false , boolean $force_array = false , boolean $group = false )

Description

Fetch the entire result set of a query and return it into a nested array. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

integer $fetchmode

the fetch mode to use

boolean $rekey

if set to TRUE the array result be modified as follows: If the result set contains more than two columns, the value will be an array of the values from column 2 to n. If the result set contains only two columns, the returned value will be a scalar with the value of the second column (unless forced to an array with the $force_array parameter).

boolean $force_array

used only if the query returns exactly two columns. If TRUE, the values of the returned array will be one-element arrays instead of scalars.

boolean boolean $group

if TRUE, the values of the returned array is wrapped in another array. If the same key value (in the first column) repeats itself, the values will be appended to this array instead of overwriting the existing values.

Return value

array - an nested array or a MDB_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
MDB_ERROR_TRUNCATED | NULL | The result set contains fewer then two columns | Check the SQL query or choose another query*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , queryRow() , queryOne() , queryCol()

Prev | MDB | Next
MDB_Common::query() | PEAR Manual | MDB_Common::queryCol()


MDB_Common::queryCol()

MDB_Common::queryCol()

MDB_Common::queryCol() – Fetch a single column

Synopsis

require_once 'MDB.php';

array &queryCol ( string $query , string $type = null , mixed $colnum = 0 )

Description

Fetch a single column from a result set of a query. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query

string $type

if supplied, the type of the column in the result set will be set for fetching

array $params

if supplied, prepareQuery()/ executeQuery() will be used with this array as execute parameters

array $param_types

if supplied, the values in $param will automatically set to the passed datatypes

mixed $colnum

which column to return (integer [column number, starting at 0] or string [column name])

Return value

array - the first row of results as an array indexed from 0 or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
MDB_ERROR_TRUNCATED | NULL | The result set contains fewer then two columns | Check the SQL query or choose another query*() function
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , queryRow() , queryOne() , queryAll()

Prev | MDB | Next
MDB_Common::queryAll() | PEAR Manual | MDB_Common::queryOne()


MDB_Common::queryOne()

MDB_Common::queryOne()

MDB_Common::queryOne() – fetch the first column of the first row

Synopsis

require_once 'MDB.php';

mixed &queryOne ( string $query , string $type = null )

Description

Fetch the first column of the first row of data returned from a query. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query or the statement to prepare

string $type

if supplied, the type of the cell in the result set will be set for fetching

Return value

mixed - the returned value or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() , executeQuery() , queryRow() , queryCol() , queryCol()

Prev | MDB | Next
MDB_Common::queryCol() | PEAR Manual | MDB_Common::queryRow()


MDB_Common::queryRow()

MDB_Common::queryRow()

MDB_Common::queryRow() – fetch the first row

Synopsis

require_once 'MDB.php';

array &queryRow ( string $query , array $types = null , integer $fetchmode = MDB_FETCHMODE_DEFAULT , integer $rownum = null )

Description

Fetch the first row of data returned from a query. The function takes care of doing the query and freeing the results when finished.

Parameter

string $query

the SQL query

array $types

if supplied, the types of the columns in the result set will be set for fetching

integer $fetchmode

the fetch mode to use, default is MDB_FETCHMODE_DEFAULT

integer $rownum

the row number to fetch

Return value

array - the first row of results as an array indexed from 0 or a MDB_Error, if fail

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
MDB_ERROR_NO_DB_SELECTED | NULL | No database was chosen. | Check the DSN in connect() .
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statement. Ie. using LIMIT in a SQL-Statement for an Oracle database.

Note

This function can not be called statically.

See

query() , limitQuery() , prepareQuery() executeQuery() , queryCol() , queryRow()

Prev | MDB | Next
MDB_Common::queryOne() | PEAR Manual | MDB_Common::setFetchMode()


MDB_Common::setFetchMode()

MDB_Common::setFetchMode()

MDB_Common::setFetchMode() – sets the default fetch mode

Synopsis

require_once 'MDB.php';

void setFetchMode ( integer $fetchmode , string $object_class = null )

Description

Sets the fetch mode used by default on queries for the connection.

Parameter

integer $fetchmode

MDB_FETCHMODE_ORDEREDor MDB_FETCHMODE_ASSOC, all possibly bit-wise OR'ed with MDB_FETCHMODE_FLIPPED. See "Introduction - Fetch" for further information.

Return value

void - NULL, if ok(!)

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | invalid fetchmode mode | The given fetch mode does not exists or is not implement in your MDB_Error version. | Check writing of the argument and your used version of MDB.

Note

This function can not be called statically.

Prev | MDB | Next
MDB_Common::queryRow() | PEAR Manual | MDB_Common::tableInfo()


MDB_Common::tableInfo()

MDB_Common::tableInfo()

MDB_Common::tableInfo() – get table info from a query

Synopsis

require_once 'MDB.php';

boolean tableInfo ( resource $result , int $mode = null )

Description

Fetch table information from result query.

Return value

Returns an associative array of table and field information.

This function is currently not documented.

Note

This function can not be called statically.

Prev | MDB | Next
MDB_Common::setFetchMode() | PEAR Manual | MDB_Error


MDB_Error

MDB_Error

MDB_Error – MDB Error object

Description

In case of failure, most of the MDB functions return a MDB_Error object which contains information about the error. MDB_Error offers the same functions as PEAR_Error.

Prev | MDB | Next
MDB_Common::tableInfo() | PEAR Manual | MDB2


MDB2

MDB2

A unified API for accessing databases and constructing SQL in a portable way.

Table of Contents
  • Introduction -- A feature overview
  • DSN -- The Data Source Name
  • Connecting -- Connecting and disconnecting a database
  • Querying -- Performing queries
  • Quoting and escaping -- Quote values in a suitable format to compose a query.
  • Datatypes -- An overview of datatype handling
  • Results -- Obtaining data from query results
  • Prepare & Execute -- Prepare and execute SQL statements
  • Transactions -- Performing transactions
  • Modules -- Loading and calling modules
  • Function Module -- Module to handle SQL function abstraction
  • Manager Module -- Module for managing database structure
  • Reverse Module -- Module for managing database structure
  • autoPrepare & autoExecute -- Automatically prepare and execute SQL statements
  • Portability -- Database portability features
  • Sequences -- Sequences and auto-incrementing
  • FAQ -- Frequently asked questions
Prev | Database | Next
MDB_Error | PEAR Manual | Introduction


Introduction

Introduction

Introduction – A feature overview

MDB2 Description

PEAR MDB2 is a merge of the PEAR DB and Metabase php database abstraction layers.

It provides a common API for all support RDBMS. The main difference to most other database abstraction packages is that MDB2 goes much further to ensure portability. Among other things MDB2 features:

  • An OO-style query API

  • A DSN (data source name) or array format for specifying database servers

  • Datatype abstraction and on demand datatype conversion

  • Portable error codes

  • Sequential and non sequential row fetching as well as bulk fetching

  • Ability to make buffered and unbuffered queries

  • Ordered array and associative array for the fetched rows

  • Prepare/execute (bind) emulation

  • Sequence emulation

  • Replace emulation

  • Limited Subselect emulation

  • Row limit support

  • Transactions support

  • Large Object support

  • Index/Unique support

  • Module Framework to load advanced functionality on demand

  • Table information interface

  • RDBMS management methods (creating, dropping, altering)

  • Full integration into the PEAR Framework

  • PHPDoc API documentation

Currently supported RDBMS:

  • MySQL

  • MySQLi (PHP5 only)

  • PostgreSQL

  • Oracle

  • Frontbase (unmaintained)

  • Querysim

  • Interbase/Firebird (PHP5 only)

  • MSSQL

  • SQLite

Installation

When you install PEAR MDB2, you only get the base classes, but you also need to install the driver of the appropriate DBMS to have a working installation. For instance, to install the MySQL and the PostgreSQL drivers, you have to run these commands:

$ pear install MDB2

$ pear install MDB2#mysql

$ pear install MDB2#pgsql

Still having problems? Check the F.A.Q.

External support resources

  • external documentation

  • Porting apps from DB to MDB2

Prev | MDB2 | Next
MDB2 | PEAR Manual | DSN


DSN

DSN

DSN – The Data Source Name

Description

To connect to a database through PEAR::MDB2, you have to create a valid DSN - data source name. This DSN consists in the following parts:

  • phptype: Database backend used in PHP (i.e. mysql , pgsql etc.)
  • dbsyntax: Database used with regards to SQL syntax etc.
  • protocol: Communication protocol to use ( i.e. tcp, unix etc.)
  • hostspec: Host specification (hostname[:port])
  • database: Database to use on the DBMS server
  • username: User name for login
  • password: Password for login
  • proto_opts: Maybe used with protocol
  • option: Additional connection options in URI query string format. options get separated by &. The Following table shows a non complete list of options:

List of options
Name | Description | Type
charset | Some backends support setting the client charset. (Invokes setCharset(string $charset, [resource $connection = null]) | string
new_link [boolean] | Some RDBMS do not create new connections when connecting to the same host multiple times. If this option is set to TRUE it will attempt to force a new connection. | boolean

The DSN can either be provided as an associative array or as a string. The array format is preferred, since it doesn't require a further parsing step (see the Connecting chapter for an example). The string format of the supplied DSN is in its fullest form:

phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value

Most variations are allowed:

phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype:///database
phptype:///database?option=value&anotheroption=anothervalue
phptype(dbsyntax)
phptype

The currently supported database backends are:

fbsql  -> FrontBase
ibase  -> InterBase / Firebird (requires PHP 5)
mssql  -> Microsoft SQL Server (NOT for Sybase. Compile PHP --with-mssql)
mysql  -> MySQL
mysqli -> MySQL (supports new authentication protocol) (requires PHP 5)
oci8   -> Oracle 7/8/9/10
pgsql  -> PostgreSQL
querysim -> QuerySim
sqlite -> SQLite 2

A second DSN format is supported

phptype(syntax)://user:pass@protocol(proto_opts)/database

If your database, option values, username or password contain characters used to delineate DSN parts, you can escape them via URI hex encodings:

: = %3a   / = %2f   @ = %40
+ = %2b   ( = %28   ) = %29
? = %3f   = = %3d   & = %26

Please note, that some features may be not supported by all database backends.

Example

Connect to database through a socket

mysql://user@unix(/path/to/socket)/pear

Connect to database on a non standard port

pgsql://user:pass@tcp(localhost:5555)/pear

Connect to SQLite on a Unix machine using options

sqlite:////full/unix/path/to/file.db?mode=0666

Connect to SQLite on a Windows machine using options

sqlite:///c:/full/windows/path/to/file.db?mode=0666

Connect to MySQLi using SSL

mysqli://user:pass@localhost/pear?key=client-key.pem&cert=client-cert.pem

Connect to Oracle using Service name

oci8://username:password@foo.example.com[:port]/?service=service

Connect to Oracle using "Easy Connect" syntax

username/password@[//]host[:port][/service_name]
Prev | MDB2 | Next
Introduction | PEAR Manual | Connecting


Connecting

Connecting

Connecting – Connecting and disconnecting a database

Description

To instantiate a database object you have several methods available using MDB2.

Connection functions
Function | Summary | Description
factory() | Efficient | Will instantiate a new MDB2_Driver_Common instance, but will not connect to the database until required. This will delay making the actual connection. This is called lazy connecting. Using this makes sense if it is possible that due to caching inside the application no connection will ever need to be established.
connect() | Eager | Will instantiate a new MDB2_Driver_Common instance, and will establish a database connection immediately. This way any connection issues will immediately raise an error.
singleton() | Available | Returns a MDB2_Driver_Common instance. A new MDB2_Driver_Common object is only created once using factory(), subsequent calls to singleton will return a reference to the existing object. This method is preferred over declaring your database object as a global.

To connect to a database you have to use the function factory(), connect() or singleton(), which require a valid DSN as the first parameter. This parameter can either be a string or an array. If using an array, the array used gets merged with the default information:

$dsn = array(
    'phptype'  => false,
    'dbsyntax' => false,
    'username' => false,
    'password' => false,
    'protocol' => false,
    'hostspec' => false,
    'port'     => false,
    'socket'   => false,
    'database' => false,
    'new_link' => false,
    'service'  => false, // only in oci8
);

Any elements you set override the defaults and the remainder stay at their defaults.

The second parameter is the optional $options array that can contain runtime configuration settings for this package.

List of options
Name | Type | Description
ssl | boolean | determines if ssl should be used for connections
field_case | integer | CASE_LOWER|CASE_UPPER: determines what case to force on field/table names
disable_query | boolean | determines if queries should be executed
result_class | string | class used for result sets
buffered_result_class | string | class used for buffered result sets, default is MDB2_Result_Common
result_wrap_class | string | class used to wrap result sets into, default is MDB2_Result_Common
result_buffering | boolean | should results be buffered or not?
fetch_class | string | class to use when fetch mode object is used
persistent | boolean | persistent connection?
debug | integer | numeric debug level
debug_handler | string | function/method that captures debug messages
debug_expanded_output | boolean | BC option to determine if more context information should be send to the debug handler
default_text_field_length | integer | default text field length to use
lob_buffer_length | integer | LOB buffer length
log_line_break | string | line-break format
idxname_format | string | pattern with '%s' for index name
seqname_format | string | pattern with '%s' for sequence name
savepoint_format | string | pattern with '%s' for auto generated savepoint names
seqcol_name | string | sequence column name
quote_identifier | boolean | if identifier quoting should be done when check_option is used
use_transactions | boolean | if transaction use should be enabled
decimal_places | integer | number of decimal places to handle
portability | integer | portability constant
modules | array | short to long module name mapping for __call()
emulate_prepared | boolean | force prepared statements to be emulated
datatype_map | array | map user defined datatypes to other primitive datatypes
datatype_map_callback | array | callback function/method that should be called

In case of success you get a new instance of the database class. It is strongly recommended to check this return value with PEAR::isError() (will detect PEAR_Error or any subclass) or the MDB2_Driver_Common specific isError().

To disconnect use the method disconnect() from your database class instance.

Connect and disconnect

<?php
require_once 'MDB2.php';

$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
    'debug' => 2,
    'result_buffering' => false,
);

$mdb2 =& MDB2::factory($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// ...

$mdb2->disconnect();
?>

Connect using an array for the DSN information

<?php
require_once 'MDB2.php';

$dsn = array(
    'phptype'  => 'pgsql',
    'username' => 'someuser',
    'password' => 'apasswd',
    'hostspec' => 'localhost',
    'database' => 'thedb',
);

$options = array(
    'debug'       => 2,
    'portability' => MDB2_PORTABILITY_ALL,
);

// uses MDB2::factory() to create the instance
// and also attempts to connect to the host
$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}
?>

When connecting to SQLite using a DSN array, the value of the mode element must be a string:

<?php
$dsn = array(
    'phptype'  => 'sqlite',
    'database' => 'thedb',
    'mode'     => '0644',
);
?>

Connect to MySQLi via SSL using an array for the DSN information

The ssl element of the $options array must be set to TRUE in order for SSL to work. Each of the extra elements in the $dsn array (key through cipher in the example below) are optional.

<?php
require_once 'MDB2.php';

$dsn = array(
    'phptype'  => 'mysqli',
    'username' => 'someuser',
    'password' => 'apasswd',
    'hostspec' => 'localhost',
    'database' => 'thedb',
    'key'      => 'client-key.pem',
    'cert'     => 'client-cert.pem',
    'ca'       => 'cacert.pem',
    'capath'   => '/path/to/ca/dir',
    'cipher'   => 'AES',
);

$options = array(
    'ssl' => true,
);

// gets an existing instance with the same DSN
// otherwise create a new instance using MDB2::factory()
$mdb2 =& MDB2::singleton($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}
?>

Connect to a PostgreSQL database via a socket

<?php
require_once 'MDB2.php';

$dsn = 'pgsql://someuser:apasswd@unix(/tmp)/thedb';
$options = array(
    'debug'       => 2,
    'portability' => MDB2_PORTABILITY_ALL,
);

$mdb2 =& MDB2::factory($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}
?>

Connect using singleton

<?php
require_once 'MDB2.php';

$dsn = 'pgsql://someuser:apasswd@localhost/thedb';

$mdb2 =& MDB2::singleton($dsn);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

$blah =& new blah();
// is able to use the existing database connection
$blah->foo();

$mdb2->disconnect();

class blah
{
    function foo() {
        // get a reference to the existing database object
        $mdb2 =& MDB2::singleton();
        // ...
    }
}
?>

See

"Intro - Portability", options, setOption(), getOption().

Prev | MDB2 | Next
DSN | PEAR Manual | Querying


Querying

Querying

Querying – Performing queries

Description

PEAR MDB2 provides several methods for querying databases. The most direct method is query(). It takes a SQL query string as an argument. There are two possible returns: A new MDB2_Result object for queries that return results (such as SELECT queries), or a MDB2_Error object on failure. It should not be used with statements that manipulate data (such as INSERT queries)

Doing a query

<?php
// Create a valid MDB2 object named $mdb2
// at the beginning of your program...
require_once 'MDB2.php';

$mdb2 =& MDB2::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// Proceed with a query...
$res =& $mdb2->query('SELECT * FROM clients');

// Always check that result is not an error
if (PEAR::isError($res)) {
    die($res->getMessage());
}

// Disconnect
$mdb2->disconnect();
?>

exec() should be used for manipulation queries. There are two possible returns: An integer denoting the number of affected rows for statements that manipulate data (such as INSERT queries), or a MDB2_Error object on failure. It should not be used with statements that return results (such as SELECT queries)

Using exec to manipulate data

<?php
// Once you have a valid MDB2 object named $mdb2...
$sql  = "INSERT INTO clients (name, address) VALUES ($name, $address)";

$affected =& $mdb2->exec($sql);

// Always check that result is not an error
if (PEAR::isError($affected)) {
    die($affected->getMessage());
}
?>

Data types

MDB2 supports a number of data types across all drivers. These can be set for result sets at query or prepare time or using the setResultTypes() method. You can find an overview of the supported data types and their format here.

Limiting rows and reading from an offset

In order to read/write to only a limited number of rows from a result set and/or to start reading from a specific offset the setLimit() can be called prior to issueing the query. The limit and offset will only affected the next method call that will issue a query or prepare a statement and will automatically be reset after issueing the query. This also applies to any internal queries issues inside MDB2. Note that limit may not work with DML statements on RDBMS that emulate limit support and no error will be raised.

Using setLimit with query and exec

<?php
// Once you have a valid MDB2 object named $mdb2...

$sql = "SELECT * FROM clients";
// read 20 rows with an offset of 10
$mdb2->setLimit(20, 10);
$affected =& $mdb2->exec($sql);

$sql = "DELETE FROM clients";
if ($mdb2->supports('limit_queries') === 'emulated') {
    echo 'offset will likely be ignored'
}
// only delete 10 rows
$mdb2->setLimit(10);
$affected =& $mdb2->exec($sql);

?>
Prev | MDB2 | Next
Connecting | PEAR Manual | Quoting and escaping


Quoting and escaping

Quoting and escaping

Quoting and escaping – Quote values in a suitable format to compose a query.

Description

MDB2 provides a quote() method to quote a value into a DBMS specific format that is suitable to compose query statements. It has four parameters (only the first one is required): the value to be quoted, its datatype, whether or not to quote the value, and whether or not to escape the wildcards in the value. If you don't provide the datatype, it will be guessed from the value.

Doing a query with quoted values

<?php
// Create a valid MDB2 object named $mdb2
// at the beginning of your program...
require_once 'MDB2.php';

$mdb2 =& MDB2::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// some sample values to be inserted
$id = 1;
$name = 'sample item';
$time = date('Y-m-d H:i:s');

// Proceed with a query...
$query = 'INSERT INTO tablename (id, itemname, saved_time) VALUES ('
    . $mdb2->quote($id,   'integer')   .', '
    . $mdb2->quote($name, 'text')      .', '
    . $mdb2->quote($time, 'timestamp') .')';
$res =& $mdb2->exec($query);
?>

With the third parameter of the quote() you can specify whether or not the above fields should be individually quoted:

Individually choose the values to be quoted

<?php
$query = 'INSERT INTO sometable (textfield1, boolfield2, datefield3) VALUES ('
    .$mdb2->quote($val1, "text", true).', '
    .$mdb2->quote($val2, "boolean", false).', '
    .$mdb2->quote($val3, "date", true).')';
?>

The above example will quote the fields and the resulting SQL will look as such:

INSERT INTO sometable FIELDS (textfield1, boolfield2, datefield3) VALUES ('blah', 1, '2006-02-21')

where the values defined were the values inserted accordingly. You will notice that the "boolfield2" is unquoted as we specified FALSE in the quote() method.

NB: If you use prepared statements, then quoting will be done automatically, you don't need to do it yourself.

Identifiers

You can quote the db identifiers (table and field names) with quoteIdentifier(). The delimiting style depends on which database driver is being used. NOTE: just because you CAN use delimited identifiers, it doesn't mean you SHOULD use them. In general, they end up causing way more problems than they solve. Anyway, it may be necessary when you have a reserved word as a field name (in this case, we suggest you to change it, if you can). Also, don't use quoteIdentifier() if you have a period in the table name itself (which, BTW, is a really bad idea), since it will consider it as a schema.table pair.

Some of the internal MDB2 methods generate queries. Enabling the quote_identifier option of MDB2 you can tell MDB2 to quote the identifiers in these generated queries. For all user supplied queries this option is irrelevant.

Portability is broken by using the following characters inside delimited identifiers:

  • backtick (`) -- due to MySQL

  • double quote (") -- due to Oracle

  • brackets ([ or ]) -- due to Access

Delimited identifiers are known to generally work correctly under the following drivers:

  • mssql

  • mysql

  • mysqli

  • oci8

  • pgsql

  • sqlite

Firebird/InterBase doesn't seem to be able to use delimited identifiers via PHP 4. They work fine under PHP 5.

Quoting options

Within the MDB2 API there are a number of options to set the quoting options, one of which simply quotes the identifiers within the abstraction, the other quotes the field values on insert/update etc. when using the prepared statements methods.

When using the quote_identifier option, all of the field identifiers will be automatically quoted in the resulting SQL statements:

<?php
$mdb2->setOption('quote_identifier', true);
?>

will result in a SQL statement that all the field names are quoted with the backtick '`' operator (in MySQL).

SELECT * FROM `sometable` WHERE `id` = '123';

as opposed to:

SELECT * FROM sometable WHERE id='123';

Escape

If you want to escape a value, without surrounding it with quotes, you can use the escape() method. If you also want to escape the wildcards (_ and %), set the second parameter to TRUE

If you just want to escape the wildcards in a value, you can use the escapePattern() method.

Prev | MDB2 | Next
Querying | PEAR Manual | Datatypes


Datatypes

Datatypes

Datatypes – An overview of datatype handling

Introduction

All DBMS provide multiple choice of data types for the information that can be stored in their database table fields. However, the set of data types made available varies from DBMS to DBMS.

To simplify the interface with the DBMS supported by MDB2, it was defined a base set of data types that applications may access independently of the underlying DBMS.

The MDB2 applications programming interface takes care of mapping data types when managing database options. It is also able to convert that is sent to and received from the underlying DBMS using the respective driver.

The following data type examples should be used with MDB2's createTable() method. The example array at the end of the data types section may be used with createTable() to create a portable table on the DBMS of choice (please refer to the main MDB2 documentation to find out what DBMS back ends are properly supported). It should also be noted that the following examples do not cover the creation and maintenance of indices, this chapter is only concerned with data types and the proper usage thereof.

"Global" table type modifiers

Within the MDB2 API there are a few modifiers that have been designed to aid in optimal table design. These are:

  • The notnull modifiers

  • The length modifiers

  • The default modifiers

  • unsigned modifiers for some field definitions, although not all DBMS's support this modifier for integer field types.

  • fixed length modifiers for some field definitions.

Building upon the above, we can say that the modifiers alter the field definition to create more specific field types for specific usage scenarios. The notnull modifier will be used in the following way to set the default DBMS NOT NULL Flag on the field to true or false, depending on the DBMS's definition of the field value: In PostgreSQL the "NOT NULL" definition will be set to "NOT NULL", whilst in MySQL (for example) the "NULL" option will be set to "NO". In order to define a "NOT NULL" field type, we simply add an extra parameter to our definition array (See the examples in the following section)

<?php
'sometime' = array(
    'type'    = 'time',
    'default' = '12:34:05',
    'notnull' = true,
),
?>

Using the above example, we can also explore the default field operator. Default is set in the same way as the notnull operator to set a default value for the field. This value may be set in any character set that the DBMS supports for text fields, and any other valid data for the field's data type. In the above example, we have specified a valid time for the "Time" data type, '12:34:05'. Remember that when setting default dates and times, as well as datetimes, you should research and stay within the epoch of your chosen DBMS, otherwise you will encounter difficult to diagnose errors!

Example of the length modifier

<?php
'sometext' = array(
    'type'   = 'text',
    'length' = 12,
),
?>

The above example will create a character varying field of length 12 characters in the database table. If the length definition is left out, MDB2 will create a length of the maximum allowable length for the data type specified, which may create a problem with some field types and indexing. Best practice is to define lengths for all or most of your fields.

Text data type

The text data type is available with two options for the length: one that is explicitly length limited and another of undefined length that should be as large as the database allows.

The length limited option is the most recommended for efficiency reasons. The undefined length option allows very large fields but may prevent the use of indexes, nullability and may not allow sorting on fields of its type.

The fields of this type should be able to handle 8 bit characters. Drivers take care of DBMS specific escaping of characters of special meaning with the values of the strings to be converted to this type.

By default MDB2 will use variable length character types. If fixed length types should be used can be controlled via the fixed modifier.

Example of text data type with length and fixed option

<?php
'sometext' = array(
    'type'   => 'text',
    'length' => 12,
    'fixed'  => 'fixed',
),
?>

Boolean data type

The boolean data type represents only two values that can be either 1 or 0. Do not assume that these data types are stored as integers because some DBMS drivers may implement this type with single character text fields for a matter of efficiency. Ternary logic is possible by using null as the third possible value that may be assigned to fields of this type.

Example of boolean data type

<?php
'someboolean' = array(
    'type' => 'boolean',
),
?>

Integer data type

The integer data type may store integer values as large as each DBMS may handle. Fields of this type may be created optionally as unsigned integers but not all DBMS support it. Therefore, such option may be ignored. Truly portable applications should not rely on the availability of this option.

Example of integer data type

<?php
'someint' = array(
    'type'     => 'integer',
    'length'   => 10,
    'unsigned' => true,
),
?>

Decimal data type

The decimal data type may store decimal numbers accurately with a fixed number of decimal places. This data type is suitable for representing accurate values like currency amounts.

Some DBMS drivers may emulate the decimal data type using integers. Such drivers need to know in advance how many decimal places that should be used to perform eventual scale conversion when storing and retrieving values from a database. Despite this, applications may use arithmetic expressions and functions with the values stored on decimal type fields as long as any constant values that are used in the expressions are also converted with the respective MDB2 conversion functions.

The number of places that are used to the left and the right of the decimal point is pre-determined and fixed for all decimal values stored in the same database. By default, MDB2 uses 2 places to the right of the decimal point, but this may be changed when setting the database connection. The number of places available to the right of the decimal point depend on the DBMS.

It is not recommended to change the number places used to represent decimal values in database after it is installed. MDB2 does not keep track of changes in the number of decimal places. The number of decimal places can be set using the setOption() method.

Example of decimal data type

<?php
'somedecimal' = array(
    'type' => 'decimal',
),
?>

Float data type

The float data type may store floating point decimal numbers. This data type is suitable for representing numbers within a large scale range that do not require high accuracy. The scale and the precision limits of the values that may be stored in a database depends on the DBMS that it is used.

Example of float data type

<?php
'somefloat' = array(
    'type' => 'float',
),
?>

Date data type

The date data type may represent dates with year, month and day. DBMS independent representation of dates is accomplished by using text strings formatted according to the IS0-8601 standard.

The format defined by the ISO-8601 standard for dates is YYYY-MM-DD where YYYY is the number of the year (Gregorian calendar), MM is the number of the month from 01 to 12 and DD is the number of the day from 01 to 31. Months or days numbered below 10 should be padded on the left with 0.

Some DBMS have native support for date formats, but for others the DBMS driver may have to represent them as integers or text values. In any case, it is always possible to make comparisons between date values as well sort query results by fields of this type.

Example of date data type

<?php
'somedate' = array(
    'type' => 'date',
),
?>

Time data type

The time data type may represent the time of a given moment of the day. DBMS independent representation of the time of the day is also accomplished by using text strings formatted according to the ISO-8601 standard.

The format defined by the ISO-8601 standard for the time of the day is HH:MI:SS where HH is the number of hour the day from 00 to 23 and MI and SS are respectively the number of the minute and of the second from 00 to 59. Hours, minutes and seconds numbered below 10 should be padded on the left with 0.

Some DBMS have native support for time of the day formats, but for others the DBMS driver may have to represent them as integers or text values. In any case, it is always possible to make comparisons between time values as well sort query results by fields of this type.

Example of time data type

<?php
'sometime' = array(
    'type'    => 'time',
    'default' => '12:34:05',
    'notnull' => true,
),
?>

Timestamp data type

The timestamp data type is a mere combination of the date and the time of the day data types. The representation of values of the time stamp type is accomplished by joining the date and time string values in a single string joined by a space. Therefore, the format template is YYYY-MM-DD HH:MI:SS. The represented values obey the same rules and ranges described for the date and time data types

Example of timestamp data type

<?php
'sometimestamp' = array(
    'type' => 'timestamp',
),
?>

Large object (file) data types

The large object data types are meant to store data of undefined length that may be too large to store in text fields, like data that is usually stored in files.

MDB2 supports two types of large object fields: Character Large OBjects (CLOBs) and Binary Large OBjects (BLOBs). CLOB fields are meant to store only data made of printable ASCII characters. BLOB fields are meant to store all types of data.

Large object fields are usually not meant to be used as parameters of query search clause (WHERE) unless the underlying DBMS supports a feature usually known as "full text search"

Example of large object data types

<?php
'someblob' = array(
    'type' => 'blob',
),
// or
'someclob' = array(
    'type' => 'clob',
),
?>

Putting it all together

Example of field definition

<?php
$fields = array(
    'id' => array(
        'type'     => 'text',
        'length'   => 32,
        'fixed' => true,
    ),
    'someint' => array(
        'type'     => 'integer',
        'length'   => 10,
        'unsigned' => true,
    ),
    'sometext' => array(
        'type'   => 'text',
        'length' => 12,
    ),
    'somedate' => array(
        'type' => 'date',
    ),
    'sometimestamp' => array(
        'type' => 'timestamp',
    ),
    'someboolean' => array(
        'type' => 'boolean',
    ),
    'somedecimal' => array(
        'type' => 'decimal',
    ),
    'somefloat' => array(
        'type' => 'float',
    ),
    'sometime' => array(
        'type'    => 'time',
        'default' => '12:34:05',
        'notnull' => true,
    ),
    'somedate' => array(
        'type' => 'date',
    ),
    'someclob' => array(
        'type' => 'clob',
    ),
    'someblob' => array(
        'type' => 'blob',
    ),
);
?>

The above example will create a database table as such:

PostgreSQL
Column | Type | Not Null | Default | comment
id | character(32) |  |  |
somename | character varying(12) |  |  |
somedate | date |  |  |
sometimestamp | timestamp without time zone |  |  |
someboolean | boolean |  |  |
somedecimal | numeric(18,2) |  |  |
somefloat | double precision |  |  |
sometime | time without time zone | NOT NULL | '12:34:05'::time without time zone |
someclob | text |  |  |
someblob | bytea |  |  |

MySQL
Field | Type | Collation | Attributes | Null | Default | comment
id | char(32) |  |  | YES |  |
somename | varchar(12) | latin1_swedish_ci |  | YES |  |
somedate | date |  |  | YES |  |
sometimestamp | timestamp without time zone |  |  | YES |  |
someboolean | tinyint(1) |  |  | YES |  |
somedecimal | decimal(18,2) |  |  | YES |  |
somefloat | double |  |  | YES |  |
sometime | time |  |  | NO | 12:34:05 |
someclob | longtext | latin1_swedish_ci |  | YES |  |
someblob | longblob |  | binary | YES |  |

Custom Data Types and Further reading

Custom data types can be defined. This will be explored soon. For now you can refer to these blog posts:

  • To serialize or to not serialize?

  • Custom Types in PEAR::MDB2

Further reading should be done at the following URL's: getTypeDeclaration, getDeclaration.

Prev | MDB2 | Next
Quoting and escaping | PEAR Manual | Results


Results

Results

Results – Obtaining data from query results

Description

Fetching Individual Rows From Query Results

The MDB2_Result_Common object provides two
methods for fetching data from rows of a result set:

 fetchOne(),

 fetchRow(),

 fetchCol() and

 fetchAll().

fetchRow() and fetchOne() read an entire row or a single field from a column respectively. The result pointer gets moved to the next row each time these methods are called. NULL is returned when the end of the result set is reached.

fetchAll() and fetchCol() read all rows in the result set and therefore move the result pointer to the end. While fetchAll() reads the entire row data, fetchCol() only reads a single column.

MDB2_Error is returned if an error is encountered.

Fetching a result set

<?php
// Create a valid MDB2 object named $mdb2
// at the beginning of your program...
require_once 'MDB2.php';

$mdb2 =& MDB2::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// Proceed with getting some data...
$res =& $mdb2->query('SELECT * FROM mytable');

// Get each row of data on each iteration until
// there are no more rows
while (($row = $res->fetchRow())) {
    // Assuming MDB2's default fetchmode is MDB2_FETCHMODE_ORDERED
    echo $row[0] . "\n";
}

// while (($one = $res->fetchOne())) {
//     echo $one . "\n";
// }

?>

Formats of Fetched Rows

The data from the row of a query result can be placed into one of three constructs: an ordered array (with column numbers as keys), an associative array (with column names as keys) or an object (with column names as properties).

MDB2_FETCHMODE_ORDERED (default)

Array
(
    [0] => 28
    [1] => hi
)

MDB2_FETCHMODE_ASSOC

Array
(
    [a] => 28
    [b] => hi
)

MDB2_FETCHMODE_OBJECT

stdClass Object
(
    [a] => 28
    [b] => hi
)

NOTE: When a query contains the same column name more than once (such as when joining tables which have duplicate column names) and the fetch mode is MDB2_FETCHMODE_ASSOC or MDB2_FETCHMODE_OBJECT, the data from the last column with a given name will be the one returned. There are two immediate options to work around this issue:

  • Use aliases in your query, for example People.Name AS PersonName
  • Change the fetch mode to MDB2_FETCHMODE_ORDERED

TIP: If you are running into this issue, it likely indicates poor planning of the database schema. Either data is needlessly being duplicated or the same names are being used for different kinds of data.

How to Set Formats

You can set the fetch mode each time you call a fetch method and/or you can set the default fetch mode for the whole MDB2 instance by using the setFetchMode() method.

Determining fetch mode per call

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT * FROM users');

while ($row = $res->fetchRow(MDB2_FETCHMODE_ASSOC)) {
    echo $row['id'] . "\n";
}
?>

Changing default fetch mode

<?php
// Once you have a valid MDB2 object named $mdb2...
$mdb2->setFetchMode(MDB2_FETCHMODE_ASSOC);

$res =& $mdb2->query('SELECT * FROM users');

while ($row = $res->fetchRow()) {
    echo $row['id'] . "\n";
}
?>

Fetch Rows by Number

The PEAR MDB2 fetch system also supports an extra parameter to the fetch statement. So you can fetch rows from a result by number. This is especially helpful if you only want to show sets of an entire result (for example in building paginated HTML lists), fetch rows in an special order, etc.

Fetching by number

<?php
// Once you have a valid MDB2_Result object named $res...

// the row to start fetching
$from = 50;

// how many results per page
$resPage = 10;

// the last row to fetch for this page
$to = $from + $resPage;

foreach (range($from, $to) as $rowNum) {
    if (!($row = $res->fetchRow(MDB2_FETCHMODE_ORDERED, $rowNum))) {
        break;
    }
    echo $row[0] . "\n";
}
?>

Getting Entire Result Sets

The MDB2_Result_Common object provides several methods to read entire results sets: fetchCol() and fetchAll().

Freeing Result Sets

Once you finish using a result set, if your script continues for a while, it's a good idea to save memory by freeing the result set via Use free().

Freeing

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT name, address FROM clients');
while ($row = $res->fetchRow(MDB2_FETCHMODE_ASSOC)) {
    echo $row['name'] . ', ' . $row['address'] . "\n";
}
$res->free();
?>

Getting the native result resource

If whatever data you need to read from a result set is not yet implemented in MDB2 you can get the native result resource using the getResource() method and then call the underlying PHP extension directly (though this would of course require that it is now up to you to make this sufficiently portable).

Native result resource

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT name, address FROM clients');
$native_result = $res->getResource();
?>

Getting More Information From Query Results

With MDB2 there are four ways to retrieve useful information about the query result sets themselves:

numRows() tells how many rows are in a SELECT query result

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT * FROM phptest');
if ($mdb2->getOption('result_buffering')) {
    echo $res->numRows();
} else {
    echo 'cannot get number of rows in the result set when "result_buffering" is disabled';
}
?>

numCols() tells how many columns are in a SELECT query result

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT * FROM phptest');
echo $res->numCols();
?>

rowCount() tells which row number the internal result row pointer currently points to

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT * FROM phptest');
$res->fetchRow();
// returns 2 if the result set contains at least 2 rows
echo $res->rowCount();

?>

getColumnNames() returns an associative array with the names of the column of the result set as keys and the position inside the result set as the values

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT * FROM phptest');
print_r($res->getColumnNames());

?>

seek() allows to seek to a specific row inside a result set. Note that seeking to previously read rows is only possible if the 'result_buffering' option is left enabled, otherwise only forward seeking is supported.

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query('SELECT * FROM phptest');
// Seek to the 10th row in the result set
$res->seek(10);

?>

nextResult() allows iterate over multiple results returned by a multi query.

<?php
// Once you have a valid MDB2 object named $mdb2...
$multi_query = $this->db->setOption('multi_query', true);
// check if multi_query can be enabled
if (!PEAR::isError($multi_query)) {
    $res =& $mdb2->query('SELECT * FROM phptest; SELECT * FROM phptest2;');
    $data1 = $res->fetchAll();
    // move result pointer to the next result
    $res->nextResult();
    $data2 = $res->fetchAll();
} else {
    echo 'multi_query option is not supported';
}

?>

bindColumn() allows to bind a reference to a user variable to a specific field inside the result set. This means that when fetching the next row, this variable is automatically updated.

<?php
// Once you have a valid MDB2 object named $mdb2...
$name = $address = null;
$res =& $mdb2->query('SELECT id, name, address FROM clients', array('id' => 'integer'));
$res->bindColumn('id', $id);
// provide a type for the column not included in the query() call
$res->bindColumn('name', $name, 'text');
// but specifying a type is as always optional in MDB2
$res->bindColumn('address', $address);
while ($res->fetchRow()) {
    echo "The address of '$name' (user id '$id') is '$address'\n";
}
?>

Querying and fetching in one call

All of the fetch methods are also available in a variant that executes a
query directly:

 queryOne(),

 queryRow(),

 queryCol() and

 queryAll().

<?php
// Once you have a valid MDB2 object named $mdb2...
$data = $mdb2->queryAll('SELECT * FROM phptest');
print_r($data);

?>

Users that prefer to use prepared statements can make use of the
following methods from the
Extended module:

 getOne(),

 getRow(),

 getCol(),

 getAll() and

 getAssoc().

<?php
// Once you have a valid MDB2 object named $mdb2...
$mdb2->loadModule('Extended');
$query = 'SELECT * FROM phptest WHERE id = ?';
$data = $mdb2->extended->getRow($query, null, array(1), array('integer'));
print_r($data);

?>

Data types

MDB2 supports a number of data types across all drivers. These can be set for result sets at query or prepare time or using the setResultTypes() method. You can find an overview of the supported data types and their format here.

Fetching LOBs

To retrieve a Large Object (BLOB or CLOB), you can use streams, as you were reading a file

Fetching LOBs with streams.

<?php
$result =& $mdb2->query('SELECT document, picture FROM files WHERE id = 1', array('clob', 'blob'));
if (PEAR::isError($result) || !$result->valid()) {
    //uh-oh
}
$row = $result->fetchRow();

//fetch the Character LOB into the $clob_value variable
$clob = $row[0];
if (!PEAR::isError($clob) && is_resource($clob)) {
    $clob_value = '';
    //use streams
    while (!feof($clob)) {
        $clob_value .= fread($clob, 8192);
    }
    $mdb2->datatype->destroyLOB($clob);
}

//fetch the Binary LOB into the $blob_value variable
$blob = $row[1];
if (!PEAR::isError($blob) && is_resource($blob)) {
    $blob_value = '';
    while (!feof($blob)) {
        $blob_value.= fread($blob, 8192);
    }
    $mdb2->datatype->destroyLOB($blob);
}

//free the result
$result->free();
?>

Checking for Errors

Don't forget to use isError() to check if your actions return a MDB2_Error object.

Prev | MDB2 | Next
Datatypes | PEAR Manual | Prepare & Execute


Prepare & Execute

Prepare & Execute

Prepare & Execute – Prepare and execute SQL statements

Description

Purpose

prepare() and execute() give you more power and flexibilty for query execution. Prepare/execute mode is helpful when you have to run the same query several times but with different values in it, such as adding a list of addresses into a database.

Another place prepare/execute is useful is supporting databases which have different SQL syntaxes. Imagine you want to support two databases with different INSERT syntax:

db1: INSERT INTO tbl_name (col1, col2) VALUES (expr1, expr2)
db2: INSERT INTO tbl_name SET col1=expr1, col2=expr2

Corresponding to create multi-lingual scripts you can create a array with queries like this:

<?php
$statement['db1']['INSERT_PERSON'] = 'INSERT INTO person
    (surname, name, age) VALUES (?, ?, ?)';

$statement['db2']['INSERT_PERSON'] = 'INSERT INTO person
    SET surname=?, name=?, age=?';
?>

Furthermore it is also possible to use named placeholders as inspired by Oracle. Using named placeholders also allows using the same placeholder name multiple times inside a single statement:

<?php
$statement['db1']['INSERT_PERSON'] = 'INSERT INTO person
    (surname, name, age) VALUES (:surname, :lastname, :age)';

$statement['db2']['INSERT_PERSON'] = 'INSERT INTO person
    SET surname=:surname, name=:lastname, age=:age';
?>

NB: we don't recommend using non-standard SQL syntax. The example above is just meant to show what you can do with prepared statements, but if you use MDB2 because you heart portability, then be sure you're using a standard SQL syntax (hint: the db1 INSERT is correct).

Prepare

To use the features above, you have to do two steps. Step one is to prepare the statement which returns an instance of the MDB2_Statement_Common class. The second step is to execute it.

To start out, you need to prepare() a generic SQL statement. Create a generic statement by writing the SQL query as usual:

SELECT surname, name, age
    FROM person
    WHERE name = 'name_to_find' AND age < age_limit

Then substitute "placeholders" for the literal values which will be provided at run time:

SELECT surname, name, age
    FROM person
    WHERE name = ? AND age < ?

Then pass this SQL statement to prepare(), which returns a statement class instance to be used when calling execute().

prepare() can handle different types of placeholders (a.k.a. wildcards). By default all placeholders are handled as strings. However passing an array of data types as the second parameter makes it possible to set a specific type for each placeholder.

Since DML (data manipulation language - INSERT, UPDATE, DELETE) statements have different return values than data fetches the prepare() accepts a third parameter. This parameter should be set to MDB2_PREPARE_MANIP for DML statements (this way the number of affected rows will be returned). For data reads it should either be set to MDB2_PREPARE_RESULT, an array of data types for each of the columns in the result set or TRUE in order to automatically detect the data types in the result set.

Execute

After preparing the statement, you can execute the query. This means to assign the variables to the prepared statement. To do this, execute() requires one argument a scalar or array with the values to assign.

Passing scalars to execute()

<?php
// Once you have a valid MDB2 object named $mdb2...
$sth = $mdb2->prepare('INSERT INTO numbers (number) VALUES (?)', array('integer'), MDB2_PREPARE_MANIP);
$sth->execute(1);
$sth->execute(8);
?>

When a prepared statement has multiple placeholders, you must use an array to pass the values to execute(). The first entry of the array represents the first placeholder, the second the second placeholder, etc. The order is independent of the type of placeholder used.

Passing an array to execute()

<?php
// Once you have a valid MDB2 object named $mdb2...
$types = array('integer', 'text', 'text');
$sth = $mdb2->prepare('INSERT INTO numbers VALUES (?, ?, ?)', $types, MDB2_PREPARE_MANIP);

$data = array(1, 'one', 'en');
$affectedRows = $sth->execute($data);
?>

When using named placeholders the data array needs to be an associative array with the keys matching the placeholder names.

Passing an array to execute()

<?php
// Once you have a valid MDB2 object named $mdb2...
$types = array('integer', 'text', 'text');
$sth = $mdb2->prepare('INSERT INTO numbers VALUES (:id, :name, :lang)', $types);

$data = array('id' => 1, 'name' => 'one', 'lang' => 'en');
$affectedRows = $sth->execute($data);
?>

When using named placeholders the data array needs to be an associative array with the keys matching the placeholder names.

Passing an array to execute()

<?php
// Once you have a valid MDB2 object named $mdb2...
$sth = $mdb2->prepare('SELECT name, lang FROM numbers WHERE id = ?', array('integer'), array('text', 'text'));

$result = $sth->execute(1);
?>

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement. Similarly, identifiers (i.e. table names and column names) can not be used because the names get validated during the prepare phase.

ExecuteMultiple

MDB2 contains a process for executing several queries at once. So, rather than having to execute them manually, like this:

Passing arrays to execute()

<?php
// Once you have a valid MDB2 object named $mdb2...
$alldata = array(array(1, 'one', 'en'),
                 array(2, 'two', 'to'),
                 array(3, 'three', 'tre'),
                 array(4, 'four', 'fire'));
$sth = $mdb2->prepare('INSERT INTO numbers VALUES (?, ?, ?)');
foreach ($alldata as $row) {
    $sth->execute($row);
}
?>

which would issue four queries:

INSERT INTO numbers VALUES ('1', 'one', 'en')
INSERT INTO numbers VALUES ('2', 'two', 'to')
INSERT INTO numbers VALUES ('3', 'three', 'tre')
INSERT INTO numbers VALUES ('4', 'four', 'fire')

you can use executeMultiple() to avoid the explicit foreach in the example above:

Using executeMultiple() from the Extended Module instead of execute()

<?php
// Once you have a valid MDB2 object named $mdb2...
$mdb2->loadModule('Extended', null, false);
$alldata = array(array(1, 'one', 'en'),
                 array(2, 'two', 'to'),
                 array(3, 'three', 'tre'),
                 array(4, 'four', 'fire'));
$sth = $mdb2->prepare('INSERT INTO numbers VALUES (?, ?, ?)');
$mdb2->extended->executeMultiple($sth, $alldata);
?>

The result is the same. If one of the records failed, the unfinished records will not be executed.

execute() has three possible returns: a new MDB2_Result_Common object for queries that return results (such as SELECT queries), integer for queries that manipulate data (such as INSERT queries) or a MDB2_Error object on failure

Data types

MDB2 supports a number of data types across all drivers. These can be set for result sets at query or prepare time or using the setResultTypes() method. You can find an overview of the supported data types and their format here.

Freeing Prepared Statements

Once you finish using prepared statements, if your script continues for a while, it's a good idea to save memory by freeing the prepared statement set via Use free().

Freeing

<?php
// Once you have a valid MDB2 object named $mdb2...
$sth = $mdb2->prepare('SELECT name, lang FROM numbers WHERE id = ?', array('integer'), array('text', 'text'));

$result = $sth->execute(1);

$sth->free();
?>

Limiting rows and reading from an offset

In order to read/write to only a limited number of rows from a result set and/or to start reading from a specific offset, the setLimit() can be called prior to calling prepare(). The limit and offset will only affect the next method call that will issue a query or prepare a statement and will automatically be reset after issuing the query. This also applies to any internal queries issued inside MDB2. Note that limit may not work with DML statements on RDBMS that emulate limit support and no error will be raised.

Using setLimit with prepare

<?php
// Once you have a valid MDB2 object named $mdb2...
// read 20 rows with an offset of 10
$mdb2->setLimit(20, 10);
$sth = $mdb2->prepare('SELECT name, lang FROM numbers WHERE group_id = ?', array('integer'), array('text', 'text'));

?>
Prev | MDB2 | Next
Results | PEAR Manual | Transactions


Transactions

Transactions

Transactions – Performing transactions

Description

PEAR MDB2 defaults to auto-committing all queries. However using the beginTransaction() method one can open a new transaction and with the commit() and rollback() methods, a transaction is finished. These three methods optionally accept a string name of a savepoint to set, release or rollback to respectively. The method inTransaction() may be used to check if a transaction is currently open.

Doing a transaction

<?php
// Create a valid MDB2 object named $mdb2
// at the beginning of your program...
require_once 'MDB2.php';

$mdb2 =& MDB2::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// check if transaction are supported by this driver
if (!$mdb2->supports('transactions')) {
    exit();
}

// Open a transaction
$res = $mdb2->beginTransaction();

..

// check if we are inside a transaction and if savepoints are supported
if ($mdb2->inTransaction() && $mdb2->supports('savepoints')) {
    // Set a savepoint
    $savepoint = 'MYSAVEPOINT';
    $res = $mdb2->beginTransaction($savepoint);

    ..

    // determine if the savepoint should be released or to rollback to the savepoint
    if ($error_condition) {
        $res = $mdb2->rollback($savepoint);
    } else {
        $res = $mdb2->commit($savepoint);
    }
}

..

// determine if the commit or rollback
if ($error_condition) {
    $res = $mdb2->rollback();
} else {
    $res = $mdb2->commit();
}

?>

PEAR MDB2 does not emulate transactions or savepoints. This means that it depends on the underlying RDBMS (and in the case of MySQL the storage engines used) if transactions will be available in MDB2. Also note that some RDBMS implicitly commit transactions when executing DDL statements - notable exceptions are Oracle and PostgreSQL.

MDB2 also supports "nested" transactions using the beginNestedTransaction() method. Actually these are not true nested transactions as they are natively supported in Interbase for example. MDB2 maintains a counter of opened nested transactions. The transaction is finished once that counter is decremented back to 1 with completeNestedTransaction() calls. If the RDBMS supports savepoints then MDB2 will automatically set a savepoint on every call of the beginNestedTransaction() method after the initial call and will return the name. These savepoints are automatically released by the completeNestedTransaction() method. The name of these automatic savepoints are determined by the "savepoint_format" option and the nested transaction counter. The "savepoint_format" defaults to 'MDB2_SAVEPOINT_%s'.

If, after initially opening a nested transaction, an unexpected PEAR error is raised on the MDB2 instance the transaction is rolled back, otherwise it is commited at this point. Using the getNestedTransactionError() method it is possible to check if there has been an error inside the transaction. Alternatively a rollback can be forced using the failNestedTransaction(). This method optionally accepts a mixed parameter which will set the error to return if the getNestedTransactionError() method is called, as well as a second boolean parameter that optionally forces an immidiate rollback.

Using emulated nested transactions

<?php

$mdb2->beginNestedTransaction(); # open transaction

$query = "INSERT INTO autoinc (id) VALUES (?)";
$stmt = $mdb2->prepare($query);

$stmt->execute(array(1));

$savepoint = $mdb2->beginNestedTransaction(); # ignored / sets savepoint

..

// never true for this example
if (false) {
    // raise an error
    $error = $mdb2->raiseError(MDB2_ERROR, null, null, 'kaboom');
    $mdb2->failNestedTransaction();
}

if(($error = $mdb2->getNestedTransactionError())) {
    die($error->getUserinfo());
}

$mdb2->completeNestedTransaction(); # ignored / releases savepoint

$stmt->execute(array(2));

$mdb2->completeNestedTransaction(); # commit

?>

Finally MDB2 supports setting the transaction isolation level as per the SQL 92 standard using the setTransactionIsolation() method. If a given RDBMS does not support a given isolation level but supports a higher more strict isolation level, then MDB2 silently uses that higher transaction level. Some RDBMS systems support additional options which are silently ignored if they are not supported.

Setting the transaction isolation level

<?php

$options = array('wait' => 'WAIT', 'rw' => 'READ WRITE');
$options = array('wait' => 'NO WAIT', 'rw' => 'READ ONLY');

$isolation_level = READ UNCOMMITTED # (allows dirty reads)
$isolation_level = READ COMMITTED # (prevents dirty reads)
$isolation_level = REPEATABLE READ # (prevents nonrepeatable reads)
$isolation_level = SERIALIZABLE # (prevents phantom reads)
$mdb2->setTransactionIsolation($isolation_level, $options);

?>
Prev | MDB2 | Next
Prepare & Execute | PEAR Manual | Modules


Modules

Modules

Modules – Loading and calling modules

Description

MDB2 follows a modular concept to provide functionality beyond the basic ability to send queries to the database and fetch result sets. Currently the following modules are available:

  • Datatype module (API) - handles datatype abstraction via the MDB2_Datatype_Common class

  • Extended module (API) - provides numerous high-level methods via the MDB2_Extended class

  • Function module (API) - handles SQL function abstraction via the MDB2_Function_Common class

  • Manager module (API) - handles data definition language (DDL) abstraction and schema listing via the MDB2_Manager_Common class

  • Native module (API) - handles RDBMS specific functions via the MDB2_Native_Common class

  • Reverse module (API) - handles schema reverse engineering abstraction via the MDB2_Reverse_Common class

A module is loaded using the loadModule() method. This method returns the module instance, but also stores the instance in a property. The name of the property is either the lowercased name of the module passed in as the first parameter, or optionally the non null value of the second parameter. The optional third parameter is used to differentiate modules that depend on a specific RDBMS (like the Datatype module) and those that do not (like the Extended module). The method can also be used to load custom modules that are installed.

The third parameter is automatically detected if it is not set. On hosts that have 'safe_mode' enabled automatic detection does however require silenced falls to fopen(). Error handling and error handlers should be configured accordingly.

Loading a module

<?php
require_once 'MDB2.php';

$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
    'debug' => 2,
    'result_buffering' => false,
);

$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// ...

$mdb2->loadModule('Manager');
// specifically stating that the module that is being loaded is RDBMS independent
// this works around some needless internal calls
$mdb2->loadModule('Extended', null, false);
?>

Loading a custom module that is RDBMS independent

<?php
// ...

// file must reside in [peardir]/MDB2/MyModule.php
class MDB2_MyModule extends MDB2_Module_Common
{
  function myMethod()
  {
    $db =& $this->getDBInstance();
    if (PEAR::isError($db)) {
        return $db;
    }
    ...
  }
}
?>

<?php
// ...

// file must reside in [peardir]/MDB2/MyModule.php
$mdb2->loadModule('MyModule');

?>

Loading a custom module that is RDBMS dependent

<?php
// ...

// file must reside in [peardir]/MDB2/Driver/MyRDBMSModule/pgsql.php
// this is the class that would get loaded for an MDB2 PostgreSQL instance
// equivalent classes for other backends would need to implemented,
// potentially making use of a common base class
class MDB2_Driver_MyRDBMSModule_pgsql extends MDB2_Module_Common
{
  function myRDBMSMethod()
  {
    $db =& $this->getDBInstance();
    if (PEAR::isError($db)) {
        return $db;
    }
    ...
  }
}
?>

<?php
// ...

// file must reside in [peardir]/MDB2/Driver/MyRDBMSModule/[phptype].php
$mdb2->loadModule('MyRDBMSModule');

?>

Using a loaded module

<?php
// ...

// loading into default name
$mdb2->loadModule('Manager');
$tables = $mdb2->manager->listTables();

// loading into non standard property $foo
$mdb2->loadModule('Function', 'foo');
$tables = $mdb2->foo->concat($str1, $str2);

?>

On PHP5 users can also rely on overloading to load and call modules.

Using the 'modules' option with PHP5 overloading

<?php
require_once 'MDB2.php';

$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
    'debug' => 2,
    'result_buffering' => false,
);

$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// ...

$module_shorthands = $mdb2->getOptions('modules');

// use the shorthand key for the given module as a prefix for the method name
// where the first letter of the original method name is uppercased
$tables = $mdb2->mgListTables();
?>

Calling a method on a loaded module with PHP5 overloading

<?php
require_once 'MDB2.php';

$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
    'debug' => 2,
    'result_buffering' => false,
);

$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// ...

$mdb2->loadModule('Manager');

// since the manager module is already loaded we can call the listTable() method
$tables = $mdb2->manager->listTables();

// NB: on PHP5, where __autoload() is available,
// the above line can be rewritten as:
$tables = $mdb2->listTables();
?>
Prev | MDB2 | Next
Transactions | PEAR Manual | Function Module


Function Module

Function Module

Function Module – Module to handle SQL function abstraction

Description

The Function module provides methods for executing non-standard SQL database functions in a consistent way. The following document lists the available methods, providing examples of their use. To include the Function module functionality, you need to load it first.

Loading the Function module

<?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@somehost';
$mdb2 =& MDB2::factory($dsn);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// loading the Function module
$mdb2->loadModule('Function');
?>

After including the module, you can access its methods like this:

Get the length of a string expression

<?php
// PHP5
$mdb2->length('expression');
// PHP4 and PHP5
$mdb2->function->length('expression');
?>

Further in the document the PHP5-compatible way will be used.

Concatenate strings

<?php
$mdb2->concat('string1', 'string2');
?>

Execute a Stored Procedure

Supposing we have the following Stored Procedure (MySQL syntax):

DELIMITER //
CREATE PROCEDURE procedure1 (IN parameter1 INTEGER)
BEGIN
  DECLARE variable1 CHAR(10);
  IF parameter1 = 17 THEN
    SET variable1 = 'birds';
  ELSE
    SET variable1 = 'beasts';
  END IF;
  INSERT INTO table1 VALUES (variable1);
END
//
DELIMITER ;

we can call it this way:

Execute a Stored Procedure

<?php
$params = array(17);
$mdb2->executeStoredProc('procedure1', $params);
?>
Prev | MDB2 | Next
Modules | PEAR Manual | Manager Module


Manager Module

Manager Module

Manager Module – Module for managing database structure

Description

The Manager module provides methods for managing database structure. The methods can be grouped based on their responsibility: create, edit (alter or update), list or delete (drop) database elements. The following document lists the available methods, providing examples of their use. The following tables will be created, altered and finally dropped, in a database named "events_db":

events(id, name, datetime);
people(id, name);
event_participants(event_id, person_id);

To include the Manager module functionality, you need to load it first.

Loading the Manager module

<?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@somehost';
$mdb2 =& MDB2::factory($dsn);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}

// loading the Manager module
$mdb2->loadModule('Manager');
?>

After including the module, you can access its methods like this:

Creating a database

<?php
// PHP5
$mdb2->createDatabase('events_db');
// PHP4 and PHP5
$mdb2->manager->createDatabase('events_db');
?>

Further in the document the PHP5-compatible way will be used.

Creating database elements

These are methods to create new databases, tables, indices, constraints and sequences.

Creating a database

Creating and setting an events_db database

<?php
// MDB2 setup
require_once 'MDB2.php';
$dsn = 'mysql://root:test@localhost'; // note that DB name is omitted
$mdb2 =& MDB2::factory($dsn);

// loading the Manager module
$mdb2->loadModule('Manager');

// create the database
$mdb2->createDatabase('events_db');

// set the new database to work with it
$mdb2->setDatabase('events_db');

// the next time the DSN could be like
// mysql://root:test@localhost/events_db
?>

Creating tables

Now that the database is created, we can proceed with adding some tables. The method createTable() takes three parameters: the table name, an array of field definition and some extra options (optional and RDBMS-specific).

Creating the events table

<?php
$definition = array (
    'id' => array (
        'type' => 'integer',
        'unsigned' => 1,
        'notnull' => 1,
        'default' => 0,
    ),
    'name' => array (
        'type' => 'text',
        'length' => 255
    ),
    'datetime' => array (
        'type' => 'timestamp'
    )
);

$mdb2->createTable('events', $definition);
?>

The keys of the definition array are the names of the fields in the table. The values are arrays containing the required key 'type' as well as other keys, depending on the value of 'type'. The values for the 'type' key are the same as the possible MDB2 datatypes. Depending on the datatype, the other options may vary.

Options for the definition array based on datatype
Datatype | length | default | not null | unsigned
text | x | x | x |
boolean |  | x | x |
integer |  | x | x | x
decimal |  | x | x |
float |  | x | x |
timestamp |  | x | x |
time |  | x | x |
date |  | x | x |
clob | x |  | x |
blob | x |  | x |

The third parameter to createTable() contains extra options for the table, such as the charset, collation, and other DBMS-specific properties, like MySQL's table engine. Here's an example for MySQL.

Creating the people table

<?php
$table_options = array(
    'comment' => 'Repository of people',
    'charset' => 'utf8',
    'collate' => 'utf8_unicode_ci',
    'type'    => 'innodb',
);
$definition = array (
    'id' => array (
        'type' => 'integer',
        'unsigned' => 1,
        'notnull' => 1,
        'default' => 0,
    ),
    'name' => array (
        'type' => 'text',
        'length' => 255
    )
);
$mdb2->createTable('people', $definition, $table_options);
?>

To round up the example database, here's the event_participants table creation code.

Creating the event_participants table

<?php
$definition = array (
    'event_id' => array (
        'type' => 'integer',
        'unsigned' => 1,
        'notnull' => 1,
        'default' => 0,
    ),
    'person_id' => array (
        'type' => 'integer',
        'unsigned' => 1,
        'notnull' => 1,
        'default' => 0,
    ),
);
$mdb2->createTable('event_participants', $definition, $table_options);
?>

Creating constraints

In the example events table, the id should be a primary key. Creating a primary key is a task done by the createConstraint() method. It takes three parameters: the table name, the constraint name and the definition array.

The full structure of the definition array looks like this (in this case, it's representing a FOREIGN KEY constraint):

<?php
$definition = array (
    'primary' => false,
    'unique'  => false,
    'foreign' => true,
    'check'   => false,
    'fields' => array (
        'field1name' => array(), // one entry per each field covered
        'field2name' => array(), // by the index
        'field3name' => array(
            'sorting'  => ascending|descending,
            'position' => 3,
        ),
    )
    'references' => array(
        'table' => name,
        'fields' => array(
            'field1name' => array( //one entry per each referenced field
                'position' => 1,
        ),
    )
    'deferrable' => false,
    'initiallydeferred' => false,
    'onupdate' => CASCADE|RESTRICT|SET NULL|SET DEFAULT|NO ACTION,
    'ondelete' => CASCADE|RESTRICT|SET NULL|SET DEFAULT|NO ACTION,
    'match' => SIMPLE|PARTIAL|FULL,
);
?>

Creating primary keys in the events and people tables

<?php
$definition = array (
    'primary' => true,
    'fields' => array (
        'id' => array()
    )
);
$mdb2->createConstraint('events', 'keyname', $definition);
$mdb2->createConstraint('people', 'keyname', $definition);
?>

Note: Some RDBMS may choose to ignore the name of the constraint, for example MySQL will not use the value keyname provided in the method call, but will use PRIMARY when a primary key is created, or [tablename]_ibfk_[n] when a foreign key is created.

In the definition array, you specify which fields will be included in the constraint, using the fields key. The other possible keys in the definition array are primary and unique , which have boolean values.

Let's create another key in the event_participants, where each row has to be unique, meaning that one person can appear only once for a specific event. The definitions array will have both fields in the fields key and the unique key will be set to true.

Creating a unique constraint

<?php
$definition = array (
    'unique' => true,
    'fields' => array (
        'event_id' => array(),
        'person_id' => array(),
    )
);
$mdb2->createConstraint('event_participants', 'unique_participant', $definition);
?>

Creating indices

To create an index, the method createIndex() is used, which has similar signature as createConstraint(), so it takes table name, index name and a definition array. The definition array has one key fields with a value which is another associative array containing fields that will be a part of the index. The fields are defined as arrays with possible keys:

  • sorting , with values ascending and descending

  • length , integer value

Not all RDBMS will support index sorting or length, in these cases the drivers will ignore them. In the test events database, we can assume that our application will show events occuring in a specific timeframe, so the selects will use the datetime field in WHERE conditions. It will help if there is an index on this field.

Creating an index

<?php
$definition = array(
    'fields' => array(
        'datetime' => array()
    )
);
$mdb2->createIndex('events', 'event_timestamp', $definition);
?>

Creating sequences

The way MDB2 handles sequences is described here. For the events table in our example database, we'll need to have the 'id' auto-incrementing. For this purpose the method nextId() is used to give the next value. nextId() will create the sequence table if it doesn't exist, but we can create if beforehand with createSequence(). It takes a sequence name and an optional start value for the sequence.

Creating sequences

<?php
$mdb2->createSequence('events');
$mdb2->createSequence('people', 1);
?>

In the default MDB2 setup the example above will create two tables: events_seq and people_seq, each with one field called 'sequence', but the field name and the '_seq' postfix are configurable via the MDB2 options seqname_format and seqcol_name .

Altering database tables

Once a database table is created you can rename it or add, remove, rename and alter fields, using the alterTable() method. alterTable() takes three parameters: the table name, the definition of changes and a boolean "check-only" flag. If true, no changes will be made, but only a check if the proposed changes are feasible for the specific table and RDBMS. The second parameter (definition of changes) is an array with these keys:

  • name : new name for the table. This is the only key related to the table itself, the other keys contain field definitions

  • add : fields to be added

  • remove : fields to be removed

  • change : fields to be changed

  • rename : fields to be renamed

The values for add/remove/change/rename keys have slightly different structures, but they all contain field definitions. You can check the API docs for more information and an examples.

Listing database elements

To see what's in the database, you can use the list*() family of functions, namely:

  • listDatabases()

  • listFunctions()

  • listSequences(): takes optional database name as a parameter. If not supplied, the currently selected database is assumed.

  • listTableConstraints(): takes a table name

  • listTableFields(): takes a table name

  • listTableIndexes(): takes a table name

  • listTables(): takes an optional database name

  • listTableTriggers(): takes a table name

  • listTableViews(): takes a table name

  • listUsers()

  • listViews(): takes an optional database name

Listing database elements

<?php
$dbs = $mdb2->listDatabases();
print_r($dbs);
/*
prints:
Array
(
    [0] => information_schema
    [1] => events_db
    [2] => mysql
    [3] => test
    [4] => test_db
    [5] => test_db_explain
    [6] => test_mdb2
)
*/

$seqs = $mdb2->listSequences('events_db');
print_r($seqs);
/*
prints:
Array
(
    [0] => events
    [1] => people
)
*/

$cons = $mdb2->listTableConstraints('event_participants');
print_r($cons);
/*
prints:
Array
(
    [0] => unique_participant
)
*/

$fields = $mdb2->listTableFields('events');
print_r($fields);
/*
prints:
Array
(
    [0] => id
    [1] => name
    [2] => datetime
)
*/

$idx = $mdb2->listTableIndexes('events');
print_r($idx);
/*
prints:
Array
(
    [0] => event_timestamp
)
*/

$tables = $mdb2->listTables();
print_r($tables);
/*
prints:
Array
(
    [0] => event_participants
    [1] => events
    [2] => people
)
*/

// currently there is no method to create a view,
// so let's do it "manually"
$sql = "CREATE VIEW names_only AS SELECT name FROM people";
$mdb2->exec($sql);
$sql = "CREATE VIEW last_ten_events AS SELECT * FROM events ORDER BY id DESC LIMIT 0,10";
$mdb2->exec($sql);
// list views
$views = $mdb2->listViews();
print_r($views);
/*
prints:
Array
(
    [0] => last_ten_events
    [1] => names_only
)
*/

/*
Not implemented in the MySQL driver
listTableTriggers()
listTableViews()
listFunctions()
*/
?>

Deleting database elements

For every create*() method as shown above, there is a corresponding drop*() method to delete a database, a table, field, index or constraint. The drop*() methods do not check if the item to be deleted exists, so it's the developer's responsibility to check for PEAR errors.

Drop database elements

<?php
// let's say our normal setup is to die on PEAR errors
PEAR::setErrorHandling(PEAR_ERROR_DIE);

// for the next statements we'll temporarily
// change the error handling
PEAR::pushErrorHandling(PEAR_ERROR_RETURN);

// drop a sequence
$result = $mdb2->dropSequence('nonexisting');
if (PEAR::isError($result)) {
    echo 'The sequence does not exist';
} else {
    echo 'Sequence dropped';
}
// another sequence
$result = $mdb2->dropSequence('people');

// drop a constraint
$mdb2->dropConstraint('events', 'PRIMARY', true);
// note: the third parameter gives a hint
//       that this is a primary key constraint
$mdb2->dropConstraint('event_participants', 'unique_participant');

// drop an index
$mdb2->dropIndex('events', 'event_timestamp');

// drop a table
$mdb2->dropTable('events');

// drop the database already!
$mdb2->dropDatabase('events_db');

// revert to the usual error handling
PEAR::popErrorHandling();
?>
Prev | MDB2 | Next
Function Module | PEAR Manual | Reverse Module


Reverse Module

Reverse Module

Reverse Module – Module for managing database structure

Description

The Reverse module is an extension of the Common Module driver, and is made up in the following structure:

  • Common driver file that encapsulates an API that can be used to execute the reverse driver queries.

  • A set of DBMS specific drivers that are specifically written against the supported database back end (e.g. mysql.php for MySQL, and pgsql.php for PostgreSQL)

Usage

In order to use the MDB2 Reverse drivers, it is necessary to first load the Reverse driver into your MDB2 instance. Let's start a MDB2 instance and set up our connection:

Loading the Reverse module

<?php
// Load up the MDB2 Base class
require 'MDB2.php';

// define a DSN to connect to our database
$dsn = array(
    'phptype' => 'mysql',
    'username' => 'someuser',
    'password' => 'somepass',
    'hostspec' => 'somehost',
    'database' => 'somedb',
);

// create MDB2 instance
// MDB2 has a number of connection options - singleton(), factory() and connect()
$mdb2 = &MDB2::connect($dsn);
if(PEAR::isError($mdb2)) {
    // Die with the user info message on failure for any reason
    die($mdb2->getuserinfo());
}
// We have a valid connection, so let's do some magic!
// Load the Reverse Module using MDB2's loadModule method
$mdb2->loadModule('Reverse', null, true);
?>

In the above example, we have created a valid connection to a database that does exist, using a valid user and password for our database server. We now have access to all of the MDB2 Reverse functionality within our example application. For the purposes of this document, we will set up an example table as such:

Create a table

<?php
// Define a table name that we will be working with
$fields = array(
    'id' => array(
        'type' => 'integer',
        'unsigned' => true,
        'autoincrement' => true,
    ),
    'somename' => array(
        'type' => 'text',
        'length' => 12,
    ),
    'somedate' => array(
        'type' => 'date',
    ),
);
$table = 'sometable';
// Create the table
//Load the Manager Module
$mdb2->loadModule('Manager', null, true);
//create the table with the manager module
$mdb2->manager->createTable($table, $fields);
?>

getTableFieldDefinition() Method

The getTableFieldDefinition() Method exists primarily to get an array that defines a table field. This array can then be used to re-create the table elsewhere, or for any other purpose that may be necessary. Using the MDB2 instance defined above, we will connect to a database, define a table that we want to work with, and reverse engineer a specific field that we are interested in. First, we need to define the table and field that we want to work with; then, it is as easy as a single line of code to get the table definition back as an array of mixed values, then using var_dump to view the results:

Get the table definition

<?php
// Set the field that we would like to reverse engineer (get definition of)
$field = 'somedate';

// Here we get the definition of the table field and return it to a variable
// The return will either be a mixed array on success, or an MDB2 error on failure,
//so we don't need additional checks
$def = $mdb2->getTableFieldDefinition($table, $field);
// finally dumping the variable to screen
var_dump($def);
?>

The return will look something like the following, depending on your field definition:

<?php
array(1) {
  [0] => array(5) {
    ['notnull'] => bool(false)
    ['nativetype'] => string(4) "date"
    ['default'] => NULL
    ['type'] => string(4) "date"
    ['mdb2type'] => string(4) "date"
  }
}
?>

Additional table information

A number of other methods exist to gain information about a selected table. You may use any of the following methods according to the information needed:

  • getTableIndexDefinition(): - requires a table name and an index name to return information about the table index as an array

  • getTableConstraintDefinition(): requires a table name and a constraint to query against. This will return any constraint definitions that exist on the table. A constraint as is defined here is usually a Primary Key, an Unique Key or a Foreign Key. The returned array has the same structure as the one used in the Manager module with createConstraint().

  • getSequenceDefinition(): requires a sequence name. It will return information about the existing table sequence. The method will return an array on success or an MDB2 error on failure.

  • getTriggerDefinition(): takes a trigger name as an argument, and will return information as an array on the trigger queried.

tableInfo() Method

This method will return a lot of information regarding a table, and can be used in a number of different ways. The information that it returns will differ slightly across different RDBM's and may give some variance in results. This method can be used to query either a table definition, or a resultset, which makes it great for creating optimized tables. The tableInfo() method allows you to pass a parameter for the mode that you would like to see the results presented as. In order to demonstrate the results more effectively, we will use a series of examples to do some queries and return the results in different modes. NOTE: Either a table OR a resultset can be passed as the first parameter to get information on the table. In these examples, we will be using the table that we defined above.

tableinfo() usage 1

<?php
// Default Mode - NULL
$tableInfo = $mdb2->tableInfo($table, NULL);
var_dump($tableInfo);

//will produce:
array(3) {
  [0] => array(11) {
    ['notnull'] => bool(true)
    ['nativetype'] => string(3) "int"
    ['length'] => int(4)
    ['unsigned'] => int(1)
    ['default'] => string(0) ""
    ['autoincrement'] => bool(true)
    ['type'] => string(3) "int"
    ['mdb2type'] => string(7) "integer"
    ['name'] => string(2) "id"
    ['table'] => string(9) "sometable"
    ['flags'] => string(29) "primary_key not_null unsigned"
  }
  [1] => array(10) {
    ['notnull'] => bool(false)
    ['nativetype'] => string(7) "varchar"
    ['length'] => string(2) "12"
    ['fixed'] => bool(false)
    ['default'] => NULL
    ['type'] => string(7) "varchar"
    ['mdb2type'] => string(4) "text"
    ['name'] => string(8) "somename"
    ['table'] => string(9) "sometable"
    ['flags'] => string(0) ""
  }
  [2] => array(8) {
    ['notnull'] => bool(false)
    ['nativetype'] => string(4) "date"
    ['default'] => NULL
    ['type'] => string(4) "date"
    ['mdb2type'] => string(4) "date"
    ['name'] => string(8) "somedate"
    ['table'] => string(9) "sometable"
    ['flags'] => string(0) ""
  }
}
?>

In the subsequent examples, we will only include the first table field definition, as it effectively illustrates the differences in modes. Now, let's change the mode to MDB2_TABLEINFO_ORDER . In addition to the information found in the default output, a notation of the number of columns is provided by the num_fields element while the order element provides an array with the column names as the keys and their location index number (corresponding to the keys in the default output) as the values.

tableinfo() usage 2

<?php
$tableInfo = $mdb2->tableInfo($table, MDB2_TABLEINFO_ORDER);
var_dump($tableInfo);

array(5) {
  ['num_fields'] => int(3)
  [0] => array(11) {
    ['notnull'] => bool(true)
    ['nativetype'] => string(3) "int"
    ['length'] => int(4)
    ['unsigned'] => int(1)
    ['default'] => string(0) ""
    ['autoincrement'] => bool(true)
    ['type'] => string(3) "int"
    ['mdb2type'] => string(7) "integer"
    ['name'] => string(2) "id"
    ['table'] => string(9) "sometable"
    ['flags'] => string(29) "primary_key not_null unsigned"
  }
  [1] => array(10) {
    ['notnull'] => bool(false)
    ['nativetype'] => string(7) "varchar"
    ['length'] => string(2) "12"
    ['fixed'] => bool(false)
    ['default'] => NULL
    ['type'] => string(7) "varchar"
    ['mdb2type'] => string(4) "text"
    ['name'] => string(8) "somename"
    ['table'] => string(9) "sometable"
    ['flags'] => string(0) ""
  }
  [2] => array(8) {
    ['notnull'] => bool(false)
    ['nativetype'] => string(4) "date"
    ['default'] => NULL
    ['type'] => string(4) "date"
    ['mdb2type'] => string(4) "date"
    ['name'] => string(8) "somedate"
    ['table'] => string(9) "sometable"
    ['flags'] => string(0) ""
  }
  ['order'] => array(3) {
    ['id'] => int(0)
    ['somename'] => int(1)
    ['somedate'] => int(2)
  }
}
?>

Changing the mode to MDB2_TABLEINFO_ORDERTABLE will give us some additional information by adding additional dimensions to the array in which the table names are keys, and the field names are sub keys. This type of query can be useful when querying complex joins, where some field names may be the same.

NOTE: The flags element will contain a space-separated list of additional information about the field. This data is inconsistent between RDBMS's due to the way each RDBMS works:

  • primary_key

  • unique_key

  • multiple_key

  • not_null

  • unsigned

Most RDBMS's only provide the table and flags elements if the result is a table name. If the portability option is set to MDB2_PORTABILITY_FIX_CASE , the names of tables and fields will be lower- or upper-cased. If the case is set to CASE_UPPER all tables and fields will be uppercased, as is seen in Oracle and Firebird/Interbase, while CASE_LOWER will lower case all field and table names; this is the default setting.

Prev | MDB2 | Next
Manager Module | PEAR Manual | autoPrepare & autoExecute


autoPrepare & autoExecute

autoPrepare & autoExecute

autoPrepare & autoExecute – Automatically prepare and execute SQL statements

Description

Purpose

autoPrepare() and autoExecute() reduce the need to write boring INSERT, UPDATE, DELETE or SELECT SQL queries which are difficult to maintain when you add a field for instance. It requires the use of the Extended module

Imagine you have a 'user' table with 3 fields (id, name and country). You have to write sql queries like:

INSERT INTO table (id, name, country) VALUES (?, ?, ?)
UPDATE table SET id=?, name=?, country=? WHERE ...

If you add a field ('birthYear' for example), you have to rewrite your queries which is boring and can lead to bugs (if you forget one query for instance).

autoPrepare

With autoPrepare(), you don't have to write your insert, update, delete or select queries. For example:

<?php
// Once you have a valid MDB2 object named $mdb2...
$table_name   = 'user';
$table_fields = array('id', 'name', 'country');
$types = array('integer', 'text', 'text');

$mdb2->loadModule('Extended');
$sth = $mdb2->extended->autoPrepare($table_name, $table_fields,
                        MDB2_AUTOQUERY_INSERT, null, $types);

if (PEAR::isError($sth)) {
    die($sth->getMessage());
}
?>

In this example, autoPrepare() will build the following SQL query:

INSERT INTO user (id, name, country) VALUES (?, ?, ?)

And then, it will call prepare() with it.

To add records, you have to use execute() or executeMultiple() like:

<?php
// ... continuing from the example above...
$table_values = array(1, 'Fabien', 'France');

$res =& $sth->execute($table_values);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

So, you don't have to write any SQL INSERT queries! And it works with UPDATE and DELETE queries too. For flexibility reasons, you have only to write the WHERE clause of the query. For instance:

<?php
// Once you have a valid MDB2 object named $mdb2...
$table_name   = 'user';

$mdb2->loadModule('Extended');
$sth = $mdb2->extended->autoPrepare($table_name, null,
                        MDB2_AUTOQUERY_DELETE, 'id = '.$mdb2->quote(1, 'integer'));

if (PEAR::isError($sth)) {
    die($sth->getMessage());
}

$res =& $sth->execute($table_values);

if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

autoPrepare() will build the following query:

UPDATE user SET name=?, country=? WHERE id=1

Then, it will call prepare() with it.

Be careful, if you don't specify any WHERE clause, all the records of the table will be updated.

autoExecute

Using autoExecute() is the easiest way to do insert, update, delete or select queries. It is a mix of autoPrepare() and execute().

You only need an associative array (key => value) where keys are fields names and values are corresponding values of these fields. This is only relevant for insert and update queries. For instance:

<?php
// Once you have a valid MDB2 object named $mdb2...
$table_name = 'user';

$fields_values = array(
    'id'      => 1,
    'name'    => 'Fabien',
    'country' => 'France'
);
$types = array('integer', 'text', 'text');

$mdb2->loadModule('Extended');
$affectedRows = $mdb2->extended->autoExecute($table_name, $fields_values,
                        MDB2_AUTOQUERY_INSERT, null, $types);

if (PEAR::isError($affectedRows)) {
    die($affectedRows->getMessage());
}
?>

And that's all! The following query is built and executed:

INSERT INTO user (id, name, country)
  VALUES (1, 'Fabien', 'France')

And it's the same thing for UPDATE queries:

<?php
// Once you have a valid MDB2 object named $mdb2...
$table_name = 'user';

$fields_values = array(
    'name'    => 'Fabien',
    'country' => 'France'
);
$types = array('text', 'text');

$mdb2->loadModule('Extended');
$affectedRows = $mdb2->extended->autoExecute($table_name, $fields_values,
                        MDB2_AUTOQUERY_UPDATE, 'id = '.$mdb2->quote(1, 'integer'), $types);

if (PEAR::isError($affectedRows)) {
    die($affectedRows->getMessage());
}
?>

which prepares and executes the following query:

UPDATE user SET name='Fabien', country='France'
  WHERE id = 1

Be careful, if you don't specify any WHERE statement, all the records of the table will be updated.

Here is an example for a DELETE queries:

<?php
// Once you have a valid MDB2 object named $mdb2...
$table_name = 'user';

$mdb2->loadModule('Extended');
$affectedRows = $mdb2->extended->autoExecute($table_name, null,
                        MDB2_AUTOQUERY_DELETE, 'id = '.$mdb2->quote(1, 'integer'));

if (PEAR::isError($affectedRows)) {
    die($affectedRows->getMessage());
}

?>

which prepares and executes the following query:

DELETE FROM user WHERE id = 1

Finally an example for a SELECT queries:

<?php
// Once you have a valid MDB2 object named $mdb2...
$table_name = 'user';

// if left as a non array all fields of the table will be fetched using '*'
// in that case this variable can be set to true, to autodiscover the types
$result_types = array(
    'name'    => 'text',
    'country' => 'text'
);

$mdb2->loadModule('Extended');
$res = $mdb2->extended->autoExecute($table_name, null,
                        MDB2_AUTOQUERY_SELECT, 'id = '.$mdb2->quote(1, 'integer'),
                        null, true, $result_types);

if (PEAR::isError($res)) {
    die($res->getMessage());
}

$row = $res->fetchRow();

?>

which prepares and executes the following query:

SELECT name, country FROM user WHERE id = 1

You can also use placeholders in the WHERE clause and pass the values like this:

<?php
$id = 1;
$mdb2->autoExecute('table_name', array($id), MDB2_AUTOQUERY_DELETE, 'id = ?');
?>

which prepares the following query and passes the $id parameter on execute:

DELETE FROM table_name WHERE id = ?

The values passed in $data must be literals. Do not submit SQL functions (for example CURDATE()). SQL functions that should be performed at execution time need to be put in the prepared statement.

See

"Intro - Modules"

Prev | MDB2 | Next
Reverse Module | PEAR Manual | Portability


Portability

Portability

Portability – Database portability features

Description

Each database management system (DBMS) has its own behaviour. For example, some databases capitalize field names in their output, some lowercase them, while others leave them alone. These quirks make it difficult to port your scripts over to another server type. PEAR MDB2 strives to overcome these differences so your program can switch between DBMSs without any changes.

You control which portability modes are enabled by using the portability configuration option. Configuration options are set via factory() and setOption().

The portability modes are bitwised, so they can be combined using | and removed using ^. See the examples section below on how to do this.

NB: MDB2 portability modes are meant to change the behaviour of the returned values only, not that of the query itself. For instance, if you created your tables quoting the identifiers, remember to use the quoteIdentifier() method in all your queries or you'll get "not found" or "not exists" errors. Also check for the quote_identifier option, if it's false then quoting won't be applied if the check_option is used.

Portability Mode Constants

  • MDB2_PORTABILITY_ALL (default)

    turn on all portability features. this is the default setting.

  • MDB2_PORTABILITY_DELETE_COUNT

    Force reporting the number of rows deleted. Some DBMSs don't count the number of rows deleted when performing simple DELETE FROM tablename queries. This mode tricks such DBMSs into telling the count by adding WHERE 1=1 to the end of DELETE queries.

  • MDB2_PORTABILITY_EMPTY_TO_NULL

    Convert empty strings values to null in data in and output. Needed because Oracle considers empty strings to be null, while most other DBMSs know the difference between empty and null.

  • MDB2_PORTABILITY_ERRORS

    Makes certain error messages in certain drivers compatible with those from other DBMSs

    Error Code Re-mappings
    Driver | Description | Old Constant | New Constant
    mysql, mysqli | unique and primary key constraints | MDB2_ERROR_ALREADY_EXISTS | MDB2_ERROR_CONSTRAINT
    mysql, mysqli | not-null constraints | MDB2_ERROR_CONSTRAINT | MDB2_ERROR_CONSTRAINT_NOT_NULL

  • MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES

    This removes any qualifiers from keys in associative fetches. Some RDBMS, for example SQLite, will default to use the fully qualified name for a column in assoc fetches if it is qualified in a query.

  • MDB2_PORTABILITY_FIX_CASE

    Convert names of tables and fields to lower or upper case in all methods. The case depends on the field_case option that may be set to either CASE_LOWER (default) or CASE_UPPER. NB: the case change is applied to the returned values only, not to the field and table names in the query.

  • MDB2_PORTABILITY_NONE

    Turn off all portability features

  • MDB2_PORTABILITY_NUMROWS

    Enable hack that makes numRows() work in Oracle

  • MDB2_PORTABILITY_RTRIM

    Right trim the data output for all data fetches. This does not apply to drivers for RDBMS that automatically right trim values of fixed length character values, even if they do not right trim value of variable length character values.

Example

Disabling all portability options while connecting

<?php
require_once 'MDB2.php';

$dsn = 'mysql://user:password@host/database'
$options = array(
    'debug'       => 2,
    'portability' => MDB2_PORTABILITY_NONE,
);

$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
    die($mdb2->getMessage());
}
?>

Using setOption() to enable portability for lowercasing and trimming

<?php
// Once you have a valid MDB2 object named $mdb2...
$mdb2->setOption('field_case', CASE_LOWER);
$mdb2->setOption('portability',
        MDB2_PORTABILITY_FIX_CASE | MDB2_PORTABILITY_RTRIM);
?>

Using setOption() to enable all portability options except trimming

<?php
// Once you have a valid MDB2 object named $mdb2...
$mdb2->setOption('portability',
        MDB2_PORTABILITY_ALL ^ MDB2_PORTABILITY_RTRIM);
?>
Prev | MDB2 | Next
autoPrepare & autoExecute | PEAR Manual | Sequences


Sequences

Sequences

Sequences – Sequences and auto-incrementing

Description

Sequences are a way of offering unique IDs for data rows. If you do most of your work with e.g. MySQL, think of sequences as another way of doing AUTO_INCREMENT.

It's quite simple, first you request an ID, and then you insert that value in the ID field of the new row you're creating. You can have more than one sequence for all your tables, just be sure that you always use the same sequence for any particular table. To get the value of this unique ID use nextID(), if a sequence doesn't exists, it will be created automatically.

The sequence is automatically incremented each time nextID() is called.

Using a sequence

<?php
// Once you have a valid MDB2 object named $mdb2...
$id = $mdb2->nextID('mySequence');
if (PEAR::isError($id)) {
    die($id->getMessage());
}

// Use the ID in your INSERT query
$res =& $mdb2->query("INSERT INTO myTable (id, text) VALUES ($id, 'foo')");
?>

Note

When using PEAR MDB2's sequence methods, we strongly advise using these methods for all procedures, including the creation of the sequences. Do not use PEAR MDB2's methods to access sequences that were created directly in the DBMS.

If you have a compelling reason to ignore this advice, be aware that the $seq_name argument given to all of PEAR MDB2's sequence methods are modified before MDB2 calls the underlying DBMS.

$seq_name is passed through PHP's sprintf() function using the value from the seqname_format option as sprintf()'s format argument. The default seqname_format is %s_seq. So, for example, if you use person_id_sequence as the $seq_name , PEAR MDB2 will change that name to person_id_sequence_seq when querying the DBMS about creating/accessing/updating the sequence.

Also note that the default table layout for sequences emulated in PEAR DB is slightly different in PEAR MDB2. Where PEAR DB calls the column "id" PEAR MDB2 instead calls it "sequence" to make its purpose more clear. For backward compatibility this can be controlled via the seqcol_name option.

The seqname_format and seqcol_name can be modified when connecting or via setOption().

Getting the last inserted ID

If you prefer using AUTO_INCREMENT you can alternatively use the lastInsertID() method to retrieve the last generated value. This method alternatively also supports getting the current ID from a sequence using the format defined in PostgreSQL's SERIAL data type. MDB2 can emulate this behaviour for RDBMS that do not support autoincrement at table creation time when using the createTable() method.

Using lastInsertID()

<?php
// Once you have a valid MDB2 object named $mdb2...
$res =& $mdb2->query("INSERT INTO myTable (id, text) VALUES (NULL, 'foo')");

// optionally pass in a table and fieldname in order to call nextID()
// when autoincrement is not supported
$id = $mdb2->lastInsertID('myTable', 'id');
if (PEAR::isError($id)) {
    die($id->getMessage());
}

?>

Getting the current ID

If you can get the current global value of a sequence using the currID() method.

Using currID()

<?php

// getting the current value of a sequence
$id = $mdb2->currID('myseq');
if (PEAR::isError($id)) {
    die($id->getMessage());
}

?>

Getting around emulation

Finally if you prefer using whatever native feature the RDBMS supports you can use the getBeforeID() and getAfterID() methods from the Extended module. This way MDB2 will automatically use AUTO_INCREMENT if it is natively supported. If not MDB2 will instead use a sequence to get the next id value.

Using getBeforeID()/getAfterID()

<?php
// Once you have a valid MDB2 object named $mdb2...
// $id may either be a quoted integer or php null
$id = $mdb2->getBeforeID('myTable', 'id', true, true);
if (PEAR::isError($id)) {
    die($id->getMessage());
}

$res =& $mdb2->query("INSERT INTO myTable (id, text) VALUES ($id, 'foo')");

// $id is now equivalent to the value in the id field that was inserted
$id = $mdb2->getAfterID($id, 'myTable', 'id');
if (PEAR::isError($id)) {
    die($id->getMessage());
}

?>

See

createSequence(),

dropSequence(),

listSequences()

Prev | MDB2 | Next
Portability | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Frequently asked questions

I get an error!

If you get a PEAR_Error (or a MDB2_Error object), try using getMessage() and getUserInfo(). They do often give you more information about the cause of the error.

"MDB2 Error: not found"

If you get this error after creating the MDB2 instance it means that you don't have any MDB2 database driver installed. Since most people use only one database system, it is unnecessary to install 15 driver files.

If SQLite is the database of your choice, do a pear install MDB2_Driver_sqlite or simply pear install MDB2#sqlite and it should work.

Also search for MDB2 drivers in the PEAR package list.

"pear/MDB2_Driver_XXX requires php extension XXX"

If you get this error when trying to install a driver it means that the php.ini loaded in the given installer does not see the "XXX" extension. Either you forgot to install the extension all together or you need to make sure that the extension is actived in all relevant php.ini files. Note that there are usually separate php.ini files for the CLI and your other SAPIs.

If all else failes do pear install -nodeps MDB2_Driver_XXX and it should work.

Two instances fail to keep different databases selected

If you work with more than one database at the same time, you may notice that as soon you connect to the second db the connection to the first one is lost, since the DBMS reuses the last open connection link. To solve the problem, just set the new_link DSN option to TRUE.

Prev | MDB2 | Next
Sequences | PEAR Manual | MDB_QueryTool


MDB_QueryTool

MDB_QueryTool

This package is an OO-abstraction to the SQL-Query language, it provides methods such as setWhere, setOrder, setGroup, setJoin, etc. to easily build queries.

Table of Contents
  • Introduction -- An OO-interface for easily retrieving and modifying data in a database
  • Object -- An introduction to the usage of Objects with MDB_QueryTool
  • Quick API reference -- A quick overview of the available methods. Please refer to the full API docs for a detailed documentation.
Prev | Database | Next
FAQ | PEAR Manual | Introduction


Introduction

Introduction

Introduction – An OO-interface for easily retrieving and modifying data in a database

MDB_QueryTool Description

This package is an OO-abstraction to the SQL-Query language, it provides methods such as setWhere(), setOrder(), setGroup(), setJoin(), etc. to easily build queries. It also provides an easy to learn interface that interacts nicely with HTML-forms using arrays that contain the column data, that shall be updated/added in a database. This package bases on an SQL-Builder which lets you easily build SQL-Statements and execute them. It supports all the db engines supported by MDB and MDB2.

Since it's a 1:1 port of DB_QueryTool, it has the same API, the only difference being the class name (and the constructor name, of course). Unfortunately, complete documentation is not available at the moment.

Example 1 - Arrays

The best way to use MDB_QueryTool is creating a class that extends it. Here's a sample usage:

<?php
require_once 'MDB/QueryTool.php';
define('TABLE_CARS', 'cars');
$dsn = 'mysql://user:pass@host/dbname';

/**
 * Let's suppose the "car" table has the following fields:
 * (id, model, hp, color, clima, price)
 */
class Car extends MDB_QueryTool
{
    var $table        = TABLE_CARS;
    var $sequenceName = TABLE_CARS;

    // this is default, but to demonstrate it here ...
    var $primaryCol =   'id';

    /**
     * This table spec assigns a short name to a table name
     * this short name is needed in case the table name changes
     * i.e. when u put the application on a provider's db, where you have to
     * prefix each table, and you dont need to change the entire application to
     * where you refer to joined table columns, for that joined results the
     * short name is used instead of the table name
     */
    var $tableSpec = array(
        array('name'  => TABLE_CARS, 'shortName' =>  'cars'),
        //array('name'  => TABLE_TIME, 'shortName' =>  'time'),
    );
}

//instanciate an object of the Car class
$car = new Car($dsn);

//get the car #3
$car->reset();     // reset the query-builder, so no where, order, etc. are set
$res = $car->get(3);
var_dump($res);

//get all the cars
$car->reset();     // reset the query-builder, so no where, order, etc. are set
$res = $car->getAll();
var_dump($res);

// get the first 10 cars
$car->reset();     // reset the query-builder, so no where, order, etc. are set
$res = $car->getAll(0, 10);
var_dump($res);

//get all the red cars with clima, sorted by price
$car->reset();
$car->setWhere('color="red"');
$car->addWhere('clima=1');
$car->setOrder('price');
$res = $car->getAll();
var_dump($res);

//add a new car to the database
$data = array(
    'model' => 'Super Trooper',
    'hp'    => 140,
    'color' => 'black',
    'clima' => 0,
    'price' => 19000
);
$newCarId = $car->save($data);
var_dump($newCarId);

//update an existing car
$data = array(
    'id'    => $newCarId,
    'clima' => 1,
    'price' => 20000,
);
$res = $car->save($data);   //equivalent to $car->update($data);
var_dump($res);

//remove the car from the database
$res = $car->remove($newCarId);
var_dump($res);
?>

Example 2 - Classes

MDB_QueryTool also offers working with classes. Here's a sample usage:

<?php
require_once 'MDB/QueryTool.php';
define('TABLE_CARS', 'cars');
$dsn = 'mysql://user:pass@host/dbname';

/**
 * Let's suppose the "car" table has the following fields:
 * (id, model, hp, color, clima, price)
 */
class Car extends MDB_QueryTool
{
    var $table        = TABLE_CARS;
    var $sequenceName = TABLE_CARS;

    // this is default, but to demonstrate it here ...
    var $primaryCol =   'id';

    /**
     * This table spec assigns a short name to a table name
     * this short name is needed in case the table name changes
     * i.e. when u put the application on a provider's db, where you have to
     * prefix each table, and you dont need to change the entire application to
     * where you refer to joined table columns, for that joined results the
     * short name is used instead of the table name
     */
    var $tableSpec = array(
        array('name'  => TABLE_CARS, 'shortName' =>  'cars'),
        //array('name'  => TABLE_TIME, 'shortName' =>  'time'),
    );
}

//instanciate an object of the Car class
$car = new Car($dsn);
$car->useResult('object');

//get the car #3
$car->reset();     // reset the query-builder, so no where, order, etc. are set
$res = $car->get(3)->fetchRow();
var_dump($res);

//get all the cars
$car->reset();     // reset the query-builder, so no where, order, etc. are set
$cars = $car->getAll();
while ($res = $cars->getNext()) {
    var_dump($res);
}

// get the first 10 cars
$car->reset();     // reset the query-builder, so no where, order, etc. are set
$cars = $car->getAll(0, 10);
while ($res = $cars->getNext()) {
    var_dump($res);
}

//get all the red cars with clima, sorted by price
$car->reset();
$car->setWhere('color="red"');
$car->addWhere('clima=1');
$car->setOrder('price');
$cars = $car->getAll();
while ($res = $cars->getNext()) {
    var_dump($res);
}

//add a new car to the database
$newCar = $car->newEntity();
$newCar->model = 'Super Trooper';
$newCar->hp    = 140;
$newCar->color = 'black';
$newCar->clima = 0;
$newCar->price = 19000;

$newCarId = $newCar->save();
var_dump($newCarId);

//update an existing car
$car->reset();
$res        = $car->get($newCarId)->fetchRow();
$res->clima = 1;
$res->price = 20000;
$res->save();
var_dump($res);

//remove the car from the database
$car->reset();
$res = $car->get($newCarId)->fetchRow();
var_dump($res->remove());
unset($res);
?>
Prev | MDB_QueryTool | Next
MDB_QueryTool | PEAR Manual | Object


Object

Object

Object – An introduction to the usage of Objects with MDB_QueryTool

MDB_QueryTool Object Description

It is possible to use objects as result. A comprehensive example may be seen in the intro.

But using objects is not a simple alternative to using arrays as result. It is also possible to register a custom Class to be returned instead of the default MDB_QueryTool_Result_Row. The new resulting class has to be child of the MDB_QueryTool_Result_Row class.

Example 1 - Change the default result class

To change the resulting class the method setReturnClass is used.

<?php
require_once 'MDB/QueryTool.php';
require_once 'MDB/QueryTool/Result/Object.php';
define('TABLE_CARS', 'cars');
$dsn = 'mysql://user:pass@host/dbname';

/**
 * Let's suppose the "cars" table has the following fields:
 * (id, model, hp, color, clima, price)
 */
class Car extends MDB_QueryTool
{
    public $table = TABLE_CARS;
}

class CarEntity extends MDB_QueryTool_Result_Row
{
}

//instanciate an object of the Car class
$car = new Car($dsn);
$car->useResult('object');
$car->setReturnClass('CarEntity');
?>

Controlling class variable access

This can now be used to implement getter and setter and thus regulate the accessability to the values. In order to block the access to the class variables from outside they have to be declared as protected. Declaring them as private would result in also blocking the parent class, which gets the data, of accessing them. Of course when doing so corresponding methods have to be implemented to access the variables again.

Example 2 - Restricting class variable access

To keep the example short only methods for dealing with model, hp and clima have been implemented.

<?php
require_once 'MDB/QueryTool.php';
require_once 'MDB/QueryTool/Result/Object.php';
define('TABLE_CARS', 'cars');
$dsn = 'mysql://user:pass@host/dbname';

/**
 * Let's suppose the "cars" table has the following fields:
 * (id, model, hp, color, clima, price)
 */
class Car extends MDB_QueryTool
{
    public $table = TABLE_CARS;
}

class CarEntity extends MDB_QueryTool_Result_Row
{
    protected $id;
    protected $model;
    protected $hp;
    protected $color;
    protected $clima;
    protected $price;
    public function getModel() {
        return $this->model;
    }
    public function setModel($model) {
        $this->model = $model;
    }
    public function getHp() {
        return $this->hp;
    }
    public function setHp($hp) {
        $this->hp = $hp;
    }
        public function getClima() {
        if ($this->clima) {
            return true;
        } else {
            return false;
        }
    }
    public function setClima($clima) {
        if ($clima) {
            $this->clima = 1;
        } else {
            $this->clima = 0;
        }
    }
}

//instantiate an object of the Car class
$car = new Car($dsn);
$car->useResult('object');
$car->setReturnClass('CarEntity');
?>

Outlook

This example only demonstrates a very basic feature. But it enables for example the implementation of Decorators. Every feature of modern OOP is now possible to implement.

Prev | MDB_QueryTool | Next
Introduction | PEAR Manual | Quick API reference


Quick API reference

Quick API reference

Quick API reference – A quick overview of the available methods. Please refer to the full API docs for a detailed documentation.

MDB_QueryTool available methods

MDB_QueryTool provides the following methods:

  • autoJoin()

    Join the given tables, using the column names, to find out how to join the tables; i.e., if table1 has a column named "table2_id", this method will join "WHERE table1.table2_id=table2.id". All joins made here are only concatenated via AND.

  • getDbInstance()

    Return a PEAR::DB object

  • setDbInstance()

    Pass an existing PEAR::DB object to MDB_QueryTool

  • get($id, $column)

    Get the data of a single entry. If the second parameter is only one column, the result will be returned directly, not as an array!

  • getMultiple($ids, $column)

    Same as get(), but for all the elements in the $ids array.

  • getAll()

    Get all the entries from the db.

  • getCol($column)

    This method only returns one column, so the result will be a one dimensional array. This does also mean that using setSelect() should be set to *one* column, the one you want to have returned. A common use case for this could be:

    <?php
    $table    ->setSelect('id');
    $ids = $table->getCol();
    //OR
    $ids = $table->getCol('id');
    ?>

    so ids will be an array with all the id's.

  • getCount()

    Get the number of entries.

  • getDefaultValues()

    return an empty element where all the array elements do already exist corresponding to the columns in the DB

  • getQueryString()

    Render the current query and return it as a string.

  • save($data)

    Save data, calls either update() or add(). If the primaryCol is given in the data this method knows that the data passed to it are meant to be updated (call update()), otherwise it will call the method add(). If you don't like this behaviour simply stick with the methods add() and update() and ignore this one here. This method is very useful when you have validation checks that have to be done for both adding and updating, then you can simply overwrite this method and do the checks in here, and both cases will be validated first.

  • update($data)

    Update the member data of a data set.

  • add($data)

    Add a new member in the db.

  • addMultiple($data)

    Adds multiple new members in the db.

  • remove($data, $whereCol)

    Removes a member from the db. data is the value of the column that shall be removed (integer/string); if an array is used, it must contain multiple columns that shall be matched (in this case, the second parameter will be ignored); $whereCol : the column to match the data against, only if data is not an array

  • removeAll()

    Empty a table.

  • removeMultiple($ids, $colName)

    Remove the datasets with the given ids. If colName is set, it is used as the primary key column name.

  • removePrimary($ids, $colName, $atLeastOneObject)

    Removes a member from the db and calls the remove() methods of the given objects so all rows in another table that refer to this table are erased too.

  • setLimit($from=0, $count=0)

    Set the limits for the following query.

  • getLimit()

    Get the limits for the following query.

  • setWhere($whereCondition)

    Sets the where condition which is used for the current instance.

  • getWhere()

    Gets the where condition which is used for the current instance.

  • addWhere($whereCondition, $condition)

    Adds a string to the where clause. The default condition is AND.

  • addWhereSearch($column, $stringToSearch, $condition)

    Add a where-like clause which works like a search for the given string; i.e. calling it like this:

    <?php
    $this    ->addWhereSearch('name', 'otto hans')
    ?>

    produces a where clause like this one

    UPPER(name) LIKE "%OTTO%HANS%"

    so the search finds the given string.

  • setOrder($orderCondition, $desc=FALSE)

    Sets the order condition which is used for the current instance.

  • getOrder()

    Gets the order condition which is used for the current instance.

  • addOrder($orderCondition, $desc=FALSE)

    Adds an order parameter to the query.

  • setHaving($havingCondition)

    Sets the having condition which is used for the current instance.

  • getHaving()

    Gets the having condition which is used for the current instance.

  • addHaving($what, $connectString)

    Adds an having parameter to the query.

  • setJoin($table, $where, $joinType)

    Sets the join condition which is used for the current instance.

  • setLeftJoin($table, $where)

    Sets a left join on $this->table.

  • addLeftJoin($table, $where, $type)

    Adds a left join to the query.

  • setRightJoin($table, $where)

    Sets a right join on $this->table.

  • getJoin($what)

    Gets the join-condition.

  • addJoin($table, $where, $type)

    adds a table and a where clause that shall be used for the join instead of calling

    <?php
    setJoin    (array(table1, table2), '<where clause1> AND <where clause2>');
    ?>

    you can also call

    <?php
    setJoin    (table1,'<where clause1>');
    addJoin(table2,'<where clause2>');
    ?>

  • setTable($table)

    Sets the table this class is currently working on.

  • getTable()

    Gets the table this class is currently working on.

  • setGroup($group)

    Sets the group-by condition.

  • getGroup()

    Gets the group-by condition.

  • setSelect($what)

    Limit the result to return only the columns given in what .

  • addSelect($what, $connectString)

    Add a string to the select-part of the query and connects it to an existing string using the connectString , which by default is a comma. ("SELECT xxx FROM..." xxx is the select-part of a query)

  • getSelect()

    Gets the select-part of the query.

  • setDontSelect($what)

    Exclude some columns from the resultset.

  • getDontSelect()

    Gets the columns excluded from the resultset.

  • reset($what)

    Reset all the set* settings, with no parameter given it resets them all.

  • setOption($option, $value)

    Set mode the class shall work in. The 'raw' mode does not quote the data before building the query

  • getOption($option)

    Get the given option.

  • debug($string)

    override this method and i.e. print the queryString to see the final query.

  • getTableShortName($table)

    Gets the short name for a table.

  • execute($query, $method)

    Execute a query (the current query is executed when query is null.

  • writeLog($text)

    Write events to the logfile. It does some additional work, like time measuring etc. to see some additional info.

  • returnResult($result)

    Return the chosen result type

  • setIndex($key)

    Format the result to be indexed by key . NOTE: be careful, when using this you should be aware, that if you use an index which's value appears multiple times you may loose data since a key can't exist multiple times! The result for a result to be indexed by a key(=columnName) (i.e. 'relationtoMe') which's values are 'brother' and 'sister' or alike normally returns this:

    <?php
    $res    ['brother'] = array('name' => 'xxx');
    $res['sister']  = array('name' => 'xxx');
    ?>

    but if the column 'relationtoMe' contains multiple entries for 'brother' then the returned dataset will only contain one brother, since the value from the column 'relationtoMe' is used and which 'brother' you get depends on a lot of things, like the sort order, how the db saves the data, and whatever else. You can also set indexes which depend on 2 columns, simply pass the parameters like 'table1.id,table2.id' it will be used as a string for indexing the result and the index will be built using the 2 values given, so a possible index might be '1,2' or '2108,29389' this way you can access data which have 2 primary keys. Be sure to remember that the index is a string!

  • getIndex()

    Gets the index.

  • useResult($type)

    Choose the type of the returned result ('array', 'object', 'none')

  • setErrorCallback($param)

    Set both callbacks.

  • setErrorLogCallback($param)

    Set the error log callback.

  • setErrorSetCallback($param)

    Set the error set callback.

Prev | MDB_QueryTool | Next
Object | PEAR Manual | MDB2_Schema


MDB2_Schema

MDB2_Schema

PEAR::MDB2_Schema enables users to maintain RDBMS independent schema files in XML that can be used to create, alter and drop database entities and insert data into a database. Reverse engineering database schemas from existing databases is also supported. The format is compatible with both PEAR::MDB and Metabase.

Table of Contents
  • Introduction -- Introduction to MDB2_Schema
  • Installation and Usage Example -- Installation and example for the usage of MDB2_Schema
  • Get Database Definition -- Generating the definition array of a physical database or MDB2 XML
  • Dump Database -- Dumping a database to MDB2 XML
  • Create Database -- Restoring a database from MDB2 XML
  • Update Database -- Updating a database against a new schema
Prev | Database | Next
Quick API reference | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to MDB2_Schema

Introduction to MDB2_Schema

MDB2_Schema builds upon MDB2 to provide tools to manage your database schema using XML which is both platform- and database-independent.

The XML format is inherited from the Metabase package and was improved to be able to represent new entities such as Data Manipulation Instructions and Foreign Keys.

It enables users to maintain RDBMS independent schema files in XML that can be used to create, alter and drop database entities (also called as DDL: Data Definition Language) and insert data (also called as DML: Data Manipulation Language) into a database. Reverse engineering database schemas from existing databases is also supported. It also features the hability to parse database schemas and database data in separated files. However, in this document the term "schema file" will be used to designate any XML supported by MDB2_Schema, no matter its nature.

Reading of schema files is handled by MDB2_Schema_Parser and writing to them by MDB2_Schema_Writer. There is also the MDB2_Schema_Validate class which is called after something is parsed. It is supposed to check the logical integrity of the schema file, for instance whether you are trying to declare a index field that does not exist or even when you are trying to insert a float in a date field.

Currently two parsers are available, one based on the package XML_Parser (default) and another based on XML_Unserializer. As MDB2_Schema is still beta, both parsers have its own limitation. The default one can't parse more than 2 nested expressions. The later doesn't respect DML instructions in the order they are specified in the schema file.

Although MDB2_Schema API supports input from physical databases and schema files, internally it always operates using a database schema array that will be described later in the documentation.

Prev | MDB2_Schema | Next
MDB2_Schema | PEAR Manual | Installation and Usage Example


Installation and Usage Example

Installation and Usage Example

Installation and Usage Example – Installation and example for the usage of MDB2_Schema

Installation

First you need MDB2 installed:

$ pear install --alldeps MDB2

You should install a driver for each database you are working with. For MySQL it would be:

$ pear install MDB2_Driver_Mysql

For some hints refers to MDB2 documentation or try in a UNIX-like system:

$ pear remote-list | grep MDB2

MDB2_Schema is a separate package, and can also be installed using the PEAR installer:

$ pear install --alldeps MDB2_Schema-beta

now you should be ready :)

Usage Example

To create an instance of the MDB2_Schema class you can use the factory(), which accepts a $dsn or an array. The factory method also accepts an existing MDB2 object. In the example below, we will just use a $dsn.

<?php
require_once 'MDB2/Schema.php';

$options = array(
    'log_line_break' => '<br>',
    'idxname_format' => '%s',
    'debug' => true,
    'quote_identifier' => true,
    'force_defaults' => false,
    'portability' => false
);
$dsn = 'mysql://root:@localhost/MDB2Example';

$schema =& MDB2_Schema::factory($dsn, $options);

if (PEAR::isError($schema)) {
    $error = $schema->getMessage();
}

if (isset($error)) {
    var_dump($error);
}

$schema->disconnect();
?>
Prev | MDB2_Schema | Next
Introduction | PEAR Manual | Get Database Definition


Get Database Definition

Get Database Definition

Get Database Definition – Generating the definition array of a physical database or MDB2 XML

Introduction

All the internal work of MDB2_Schema is done over array structures, which we will call "definition array". Many methods, such as createDatabase, requires a definition array as input parameter, instead of a filename. Others take care of the conversion automatically, accepting both inputs.

For the cases when you need a definition array, there are two avaliable methods to manually generate the definition array, one for each schema source - either a database or a schema file. Obviously you can also write it by hand, it is not intended to be done this way though.

Get Database Definition

You can use getDefinitionFromDatabase() to get the definition array from an existing database.

<?php
require_once 'MDB2/Schema.php';

$options = array(
    'log_line_break' => '<br>',
    'idxname_format' => '%s',
    'debug' => true,
    'quote_identifier' => true,
    'force_defaults' => false,
    'portability' => false
);
$dsn = 'mysql://root:@localhost/MDB2Example';

$schema =& MDB2_Schema::factory($dsn, $options);

if (PEAR::isError($schema)) {
    $error = $schema->getMessage();
} else {
    // this method _attempts_ to get the defintition from the database
    // make sure you have tested it with your database to see if it
    // returns what you expect
    $definition = $schema->getDefinitionFromDatabase();

    if (PEAR::isError($definition)) {
      $error = $definition->getMessage();
    }
}

if (isset($error)) {
  var_dump($error);
}

$schema->disconnect();
?>

Though you have to use the method with caution, if you use the method on a database created by hand. Some of the fields might be slightly different, but once you create your database using MDB2_Schema it is reliable and will return the same $definition every time.

Parse Database Definition

You can use parseDatabaseDefinitionFile() to get the definition array from a schema file.

<?php
require_once 'MDB2/Schema.php';

$options = array(
    'log_line_break' => '<br>',
    'idxname_format' => '%s',
    'debug' => true,
    'quote_identifier' => true,
    'force_defaults' => false,
    'portability' => false
);
$dsn = 'mysql://root:@localhost/MDB2Example';

$schema =& MDB2_Schema::factory($dsn, $options);

if (PEAR::isError($schema)) {
    $error = $schema->getMessage();
} else {
    $definition = $schema->parseDatabaseDefinitionFile('schema.xml');

    if (PEAR::isError($definition)) {
      $error = $definition->getMessage();
    }
}

if (isset($error)) {
  var_dump($error);
}

$schema->disconnect();
?>

Although the method accepts more parameters, only the first one is required.

Prev | MDB2_Schema | Next
Installation and Usage Example | PEAR Manual | Dump Database


Dump Database

Dump Database

Dump Database – Dumping a database to MDB2 XML

Dump Database

You can use dumpDatabase() to copy your database to a schema file. dumpDatabase() accepts a database definition array, for instance:

<?php
require_once 'MDB2/Schema.php';

$options = array(
    'log_line_break' => '<br>',
    'idxname_format' => '%s',
    'debug' => true,
    'quote_identifier' => true,
    'force_defaults' => false,
    'portability' => false
);
$dsn = 'mysql://root:@localhost/MDB2Example';

$schema =& MDB2_Schema::factory($dsn, $options);

if (PEAR::isError($schema)) {
    $error = $schema->getMessage();
} else {
    $dump_options = array(
      'output_mode' => 'file',
      'output' => 'schema.xml',
      'end_of_line' => "\n"
    );

    $definition = $schema->getDefinitionFromDatabase();
    if (PEAR::isError($definition)) {
      $error = $definition->getMessage();
    } else {
      $op = $schema->dumpDatabase($definition, $dump_options, MDB2_SCHEMA_DUMP_ALL);

      if (PEAR::isError($op)) {
          $error = $op->getMessage();
      }
  }
}

if (isset($error)) {
    var_dump($error);
}

$schema->disconnect();
?>

The first parameter is just the database definition array. The second parameter is the options where we choose to output to a file. The third option tells dumpDatabase() what to be dumped - either the structure, the data in the tables, or both. This is defined using the constants MDB2_SCHEMA_DUMP_STRUCTURE, MDB2_SCHEMA_DUMP_CONTENT and MDB2_SCHEMA_DUMP_ALL.

Some databases don't accept a text field with a default value. Given that, notice that $options['force_defaults'] has to be set to false when you want to create a field with the type text, as it is true by default.

Prev | MDB2_Schema | Next
Get Database Definition | PEAR Manual | Create Database


Create Database

Create Database

Create Database – Restoring a database from MDB2 XML

Create Database

When having a schema file, it is a breeze to create a database. Simply do the following:

<?php
require_once 'MDB2/Schema.php';

$options = array(
    'log_line_break' => '<br>',
    'idxname_format' => '%s',
    'debug' => true,
    'quote_identifier' => true,
    'force_defaults' => false,
    'portability' => false
);
$dsn = 'mysql://root:@localhost/MDB2Example';

$schema =& MDB2_Schema::factory($dsn, $options);

if (PEAR::isError($schema)) {
    $error = $schema->getMessage();
} else {
    // first run with queries disabled to make sure everything is allright
    $disable_query = true;

    $definition = $schema->parseDatabaseDefinitionFile('example.xml');
    if (PEAR::isError($definition)) {
      $error = $definition->getMessage();
    } else {
      $op = $schema->createDatabase($definition, array(), $disable_query);

      if (PEAR::isError($op)) {
        $error = $op->getMessage();
      }
    }
}

if (isset($error)) {
    var_dump($error);
}

$schema->disconnect();
?>
Prev | MDB2_Schema | Next
Dump Database | PEAR Manual | Update Database


Update Database

Update Database

Update Database – Updating a database against a new schema

Update Database

Having MDB2_Schema to update your database, when its schema changes is also really easy. You can use the getDefinitionFromDatabase() method to determine the current database schema, and then just use updateDatabase() to do the actual update. However, you have to make sure, that getDefinitionFromDatabase() returns what you expect before you rely on it. See the respective chapter for more info.

<?php
require_once 'MDB2/Schema.php';

$options = array(
    'log_line_break' => '<br>',
    'idxname_format' => '%s',
    'debug' => true,
    'quote_identifier' => true,
    'force_defaults' => false,
    'portability' => false
);
$dsn = 'mysql://root:@localhost/MDB2Example';

$schema =& MDB2_Schema::factory($dsn, $options);

if (PEAR::isError($schema)) {
    $error = $schema->getMessage();
} else {
    // first run with queries disabled to make sure everything is allright
    $disable_query = true;

    $previous_schema = $schema->getDefinitionFromDatabase();
    $op = $schema->updateDatabase('schema.xml', $previous_schema, array(), $disable_query);

    if (PEAR::isError($op)) {
        $error = $op->getMessage();
    }
}

if (isset($error)) {
    var_dump($error);
}

$schema->disconnect();
?>

The method accepts both, a filename or a definition array, as the first two parameters. Note how we mixed them in the example above. You may want to backup the current schema using dumpDatabase() for the case something goes wrong.

When updating database schemas we can run into data persistence issues. This can be addressed with data manipulation ability, that will be documented later in this manual.

Prev | MDB2_Schema | Next
Create Database | PEAR Manual | MDB2_TableBrowser


MDB2_TableBrowser

MDB2_TableBrowser

PEAR::MDB2_TableBrowser is a lightweight ORM(object relation mapping) library. Turn any database table(or table view) into an easy to use php object.

Table of Contents
  • Introduction -- Introduction to MDB2_TableBrowser
  • Installation -- Installating MDB2_TableBrowser
  • Basic Usage -- Example of how to use MDB2_TableBrowser
  • Advanced Usage -- Advance usage of MDB2_TableBrowser
Prev | Database | Next
Update Database | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to MDB2_TableBrowser

Introduction to MDB2_TableBrowser

MDB2_TableBrowser is a lightweight ORM(object relation mapping) library. Turn any database table(or table view) into an easy to use php object.

Table browsing objects allow your code to handle any database table in an abstract way. By freeing your code from the database details it is possible for you to build generic data reporting or manipulation functions.

Put another way, if you really hate using sql in your code, having to piece together bits of sql to make queries...this library gives you an alternative.

Currently only the single table browser is implemented. If you need to work with data that spans multiple tables, you can build a table view as this library works with them as well.

Prev | MDB2_TableBrowser | Next
MDB2_TableBrowser | PEAR Manual | Installation


Installation

Installation

Installation – Installating MDB2_TableBrowser

Installation

First you need MDB2 installed:

$ pear install --alldeps MDB2

You should install a driver for each database you are working with. For MySQL it would be:

$ pear install MDB2_Driver_Mysql

Finally you install MDB2_TableBrowser using the PEAR installer. Since the package is in alpha you have to add the -d option as below:

$ pear -d preferred_state=alpha install --alldeps MDB2_TableBrowser
Prev | MDB2_TableBrowser | Next
Introduction | PEAR Manual | Basic Usage


Basic Usage

Basic Usage

Basic Usage – Example of how to use MDB2_TableBrowser

Creating a Table Object

Steps to creating a table object out of your database table or view. This example connects to a mysql database animal_db and constructs a table object from the tbl_animals table.

Create an MDB2 object:

<?php
require_once "MDB2.php";

$dsn     = 'mysql://username:pass@localhost/animal_db';
$mdb2 = MDB2::singleton($dsn);
?>

Load the TableBrowser extention:

<?php
$mdb2->loadModule('TableBrowser');
?>

Create the table object Create a table browser for the tbl_animals table, and specify id as the primary key:

<?php
$browser = $mdb2->tableBrowserFactory('tbl_animals', 'id');
?>

Retreiving Data

A table object allows you several ways of retrieving data from the underlying table. The examples below continue from the animals_db database.

Retrieving a single row is done via the getRows method. This call returns the row data as a hash array:

<?php
$browser->getRow(1);
?>

Retrieving multiple rows is done via the getRows method. This call returns an MDB2_Results object. From the animals db example... Get data the 3 animals in the table sorted by name starting with the 5th animal

<?php
$browser->getRows('name', 3, 5);
?>

Retrieving the different values in a column has is done via the getColumnValues method. In our example, we can get the different kinds of animals in tbl_animals eg: mammal, reptile,...

<?php
$browser->getColumnValues('type');
?>

Inserting

Inserting a single row is done via insertRow method. It takes a single hash array as input.

<?php
$rowData = array('id'=>13, 'name' => 'duck','type' => 'bird','lifespan' => 5);
$browser->insertRow($rowData);
?>

Inserting multiple rows at once is done via insertRows method.

<?php
$data = array(
    array(1,'dog','mammal',12),
    array(2,'cat','mammal',30),
    array(3,'parrot','bird',60),
    array(4,'shark','fish',30),
    array(5,'dolphin','mammal',50),
    array(6,'crocodile','reptile',50),
    array(7,'snake','reptile',20),
    array(8,'spider','arachnid',1),
    array(9,'housefly','insect',1),
    array(10,'ostrich','bird',35),
    array(11,'bat','mammal',6),
    array(12,'human','mammal',100)
        );
$browser->insertRows(array('id', 'name','type','lifespan'), $data);
?>

Updating

Updating a single row is done via updateRow method.

<?php
//Get the row data
$rowData = $browser->getRow(3);

//Modify the data
$rowData['lifespan'] = 65;

//Update the row
$browser->updateRow(3, $rowData);
?>
Prev | MDB2_TableBrowser | Next
Installation | PEAR Manual | Advanced Usage


Advanced Usage

Advanced Usage

Advanced Usage – Advance usage of MDB2_TableBrowser

Full example use the MDB2_TableBrowser API

The example source below contains all the different methods available to tableBrowser object beyond the features explained in the basic usage documentation.

<?php
require_once "MDB2.php";

define('DSN', 'mysql://username:pass@localhost/animal_db');

/**
 * The example below relies on the following data from the table tbl_animals
 * ID       NAME        TYPE        LIFESPAN
 * 1        dog         mammal      12
 * 2        cat         mammal      30
 * 3        parrot      bird        60
 * 4        shark       fish        30
 * 5        dolphin     mammal      50
 * 6        crocodile   reptile     50
 * 7        snake       reptile     20
 * 8        spider      arachnid    1
 * 9        housefly    insect      1
 * 10       ostrich     bird        35
 * 11       bat         mammal      6
 * 12       human       mammal      100
 */

$dsn     = 'mysql://username:pass@localhost/animal_db';
$options = array(
    'debug' => 2,
    'result_buffering' => false,
);

$mdb2 = MDB2::singleton($dsn, $options);

//Create the table
setupDb($mdb2);

$mdb2->loadModule('TableBrowser');

//Create a table browser for the tbl_animals table, and specify id as the primary key
$browser = $mdb2->tableBrowserFactory('tbl_animals', 'id');

//The data browsing object is now ready
//First insert the needed data
$data = array(
            array(1,'dog','mammal',12),
            array(2,'cat','mammal',30),
            array(3,'parrot','bird',60),
            array(4,'shark','fish',30),
            array(5,'dolphin','mammal',50),
            array(6,'crocodile','reptile',50),
            array(7,'snake','reptile',20),
            array(8,'spider','arachnid',1),
            array(9,'housefly','insect',1),
            array(10,'ostrich','bird',35),
            array(11,'bat','mammal',6),
            array(12,'human','mammal',100)
            );
$browser->insertRows(array('id', 'name','type','lifespan'), $data);

//Get info on a single animal, getRow returns a hash array and getRows returns
//an MDB2_Result object
$browser->getRow(1);
print "\n" . $browser->getLastSQL();
//Prints: SELECT `ID`,`NAME`,`TYPE`,`LIFESPAN` FROM tbl_animals WHERE (`id` = 1)

//Get info on 3 animals in the table sorted by name starting with the 5th animal
$browser->getRows('name', 3, 5);
print "\n" . $browser->getLastSQL();
//The limits/offsets are not shown below as they are set by mdb2 library
//Prints: SELECT `ID`,`NAME`,`TYPE`,`LIFESPAN` FROM tbl_animals

//Hide the ID column and rename the column "TYPE" to "Animal Type"
$browser->selectColumns(array('name','type','lifespan'));
$browser->setColumnAlias('TYPE', 'ANIMAL TYPE');
$browser->getRows('name', 3, 5);
print "\n" . $browser->getLastSQL();
//Prints:SELECT `NAME`,`TYPE` AS `ANIMAL TYPE`,`LIFESPAN` FROM tbl_animals

//Get the different kinds of animal types in the table eg: mammal, reptile,...
$browser->getColumnValues('type');
print "\n" . $browser->getLastSQL();
//Prints:SELECT DISTINCT `TYPE` FROM tbl_animals

//This also works with aliases you have set up
$browser->getColumnValues('ANIMAL TYPE');
print "\n" . $browser->getLastSQL();
//Prints:SELECT DISTINCT `TYPE` FROM tbl_animals

/*
 * Example using filters, look for mammals with a lifespan <60 years Multiple
 * filters can be added and removed. This functionality can be used to quickly
 * build a browsing application that gives the user the freedom to traverse the
 * table data in different ways.
 */
$browser->addFilter('MaxAge', 'lifespan', '<=', 60);
$browser->addFilter('AnimalType', 'type', '=', 'mammal');
//Once a filter has been set, it affects the browser's output
$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `NAME`,`TYPE` AS `ANIMAL TYPE`,`LIFESPAN` FROM tbl_animals WHERE (`lifespan` <= 60 AND `type` = 'mammal')

//A single filter can be removed by specifying the filter name
$browser->removeFilter('MaxAge');
$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `NAME`,`TYPE` AS `ANIMAL TYPE`,`LIFESPAN` FROM tbl_animals WHERE (`type` = 'mammal')

//All Filters set can be cleared using this method
$browser->resetFilters();
$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `NAME`,`TYPE` AS `ANIMAL TYPE`,`LIFESPAN` FROM tbl_animals

//Insert a new row
$rowData = array('id'=>13, 'name' => 'duck','type' => 'bird','lifespan' => 5);
$browser->insertRow($rowData);
print "\n" . $browser->getLastSQL();
//The whole statement is not shown as this sql is prepared and excectues by mdb2 library
//Prints: INSERT INTO tbl_animals VALUES (?,?,?,?)

//Update the parrot's data
$rowData             = $browser->getRow(3);
$rowData['lifespan'] = 65;
$browser->updateRow(3, $rowData);

print "\n" . $browser->getLastSQL();
//Prints: UPDATE tbl_animals SET `id`= NULL,`name`= 'parrot',`type`= NULL,`lifespan`= 65 WHERE (`id` = 3)

$browser->addFilter('AnimalType', 'type', '=', 'bird');
//Clear all colum selections and aliases
$browser->resetSelectColumns();
$browser->resetColumAliases();
$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `ID`,`NAME`,`TYPE`,`LIFESPAN` FROM tbl_animals WHERE (`type` = 'bird')

/**
 * You can also create multiple filter chains to query for different conditions
 * in parallel. Say you were interested in mammals with a lifespan > 30 or birds
 * with a lifespan < 10. This can be accomplished using 2 filter chains as
 * follows.
 */
$browser->resetFilters();
//Call the first chain 'Mammal Group' and the second "Bird Group'. You can use any identifier that makes sense to you
$browser->createFilterChain('Mammal Group');
$browser->createFilterChain('Bird Group');

//Define the mammals filter chain
$browser->selectFilterChain('Mammal Group');
$browser->addFilter('AnimalType', 'type', '=', 'mammal', 'Mammal Group');
$browser->addFilter('Lifespan', 'lifespan', '>', 30, 'Mammal Group');

//Define the birds filter chain
$browser->selectFilterChain('Bird Group');
$browser->addFilter('AnimalType', 'type', '=', 'bird', 'Bird Group');
$browser->addFilter('Lifespan', 'lifespan', '<', 10, 'Bird Group');

$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `ID`,`NAME`,`TYPE`,`LIFESPAN` FROM tbl_animals WHERE ((`type` = 'mammal' AND `lifespan` > 30)) OR ((`type` = 'bird' AND `lifespan` < 10))

//This resets all the filters chains
$browser->resetAllFilters();

//Switch back to the default filter chain
$browser->selectFilterChain();

//You can delete a filterChain like this. Any user defined filter chain can be removed
//But the default filter chain is always there
$browser->deleteFilterChain('Mammal Group');
$browser->deleteFilterChain('Bird Group');

//You can add custom columns as well for columns like 'md5()' or your own custom functions
$browser->addCustomColumn('md5(TYPE)', 'Special Column');
$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `id`,`name`,`type`,`lifespan`,md5(TYPE) AS `Special Column` FROM tbl_animals

$browser->removeCustomColumn('md5(TYPE)');

//You can also add grouping and sorting methods
$browser->setOrderBy('lifespan');
$browser->setGroupBy('type');
$browser->selectColumns(array('type','lifespan'));
$browser->addCustomColumn('count(*)', 'Number of Species');
$browser->getRows();
print "\n" . $browser->getLastSQL();
//Prints: SELECT `type`,`lifespan`,count(*) AS `Number of Species` FROM tbl_animals GROUP BY `type` ORDER BY `lifespan`

//Delete sharks (id 4)
$browser->deleteRow(4);
print "\n" . $browser->getLastSQL() . "\n\n";
//Prints: DELETE  FROM tbl_animals WHERE (`id` = 4)

/**
 * Creates the tbl_animals table
 *
 * @param ref &$mdb2 An mdb2 object reference
 *
 * @return void
 */
function setupDb(&$mdb2)
{
    // loading the Manager module
    $mdb2->loadModule('Manager');
    $tableDefinition = array (
        'id' => array (
            'type' => 'integer',
            'unsigned' => 1,
            'notnull' => 1,
            'default' => 0,
        ),
        'name' => array (
            'type' => 'text',
            'length' => 300,
            'notnull' => 1
        ),
        'type' => array (
            'type' => 'text',
            'length' => 300,
            'notnull' => 1
        ),
        'lifespan' => array (
            'type' => 'integer',
            'unsigned' => 1,
            'notnull' => 1,
            'default' => 0,
        ),
    );

    $tableConstraints = array (
        'primary' => true,
        'fields' => array (
            'id' => array()
        )
    );
    $mdb2->dropTable('tbl_animals');
    $mdb2->createTable('tbl_animals', $tableDefinition);
    $mdb2->createConstraint('tbl_animals', 'primary_key', $tableConstraints);
    $mdb2->createSequence('primary_key');

}
?>
Prev | MDB2_TableBrowser | Next
Basic Usage | PEAR Manual | Date and Time


Date and Time

Date and Time

Provides Packages for working with date and time data

Table of Contents
  • Calendar
  • Date
  • Date_Holidays
Prev | PEAR Packages | Next
Advanced Usage | PEAR Manual | Calendar


Calendar

Calendar

Calendar Data Structures

This chapter describes how to use PEAR::Calendar

Table of Contents
  • Introduction -- What Calendar can do
  • Installing -- How to install PEAR::Calendar
  • In A Hurry -- Just add hot water...
  • Package Overview -- Summary of Calendar Classes
  • Method Overview -- Summary of Calendar API
  • Calendar Decorators -- What Calendar_Decorator is for
  • FAQ -- Frequently Asked Questions
  • Calendar -- Calendar base class
  • constructor Calendar::Calendar -- Constructs the Calendar
  • Calendar::adjust -- Adjusts the date (helper method)
  • Calendar::build -- Abstract method for building the children of a calendar object.
  • Calendar::fetch -- Iterator method for fetching child Calendar subclass objects (e.g. a minute from an hour object). On reaching the end of the collection, returns false and resets the collection for further iteratations.
  • Calendar::fetchAll -- Fetches all child from the current collection of children
  • Calendar::getTimestamp -- Returns a timestamp from the current date / time values
  • Calendar::getValidator -- Returns an instance of Calendar_Validator
  • Calendar::isSelected -- True if the calendar subclass object is selected (e.g. today)
  • Calendar::isValid -- Determine whether this date is valid
  • Calendar::nextDay -- Returns the value for the next day
  • Calendar::nextHour -- Returns the value for the next hour
  • Calendar::nextMinute -- Returns the value for the next minute
  • Calendar::nextMonth -- Returns the value for next month
  • Calendar::nextSecond -- Returns the value for the next second
  • Calendar::nextYear -- Returns the value for next year
  • Calendar::prevDay -- Returns the value for the previous day
  • Calendar::prevHour -- Returns the value for the previous hour
  • Calendar::prevMinute -- Returns the value for the previous minute
  • Calendar::prevMonth -- Returns the value for the previous month
  • Calendar::prevSecond -- Returns the value for the previous second
  • Calendar::prevYear -- Returns the value for the previous year
  • Calendar::setSelected -- Defines calendar object as selected (e.g. for today)
  • Calendar::setSelection -- Abstract method for selected data objects called from build
  • Calendar::setTimestamp -- Defines the calendar by a Unix timestamp
  • Calendar::size -- Get the number Calendar subclass objects stored in the internal collection.
  • Calendar::thisDay -- Returns the value for this day
  • Calendar::thisHour -- Returns the value for this hour
  • Calendar::thisMinute -- Returns the value for this minute
  • Calendar::thisMonth -- Returns the value for this month
  • Calendar::thisSecond -- Returns the value for this second
  • Calendar::thisYear -- Returns the value for this year
  • Calendar_Year -- Calendar_Year API
  • constructor Calendar_Year::Calendar_Year -- Constructs Calendar_Year
  • Calendar_Year::build -- Builds the Months of the Year.
  • Calendar_Month -- Calendar_Month API
  • constructor Calendar_Month::Calendar_Month -- Constructs Calendar_Month
  • Calendar_Month::build -- Builds Day objects for this Month. Creates as many Calendar_Day objects
  • Calendar_Month_Weekdays -- Calendar_Month_Weekdays API
  • constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays -- Constructs Calendar_Month_Weekdays
  • Calendar_Month_Weekdays::build -- Builds Day objects in tabular form, to allow display of calendar month with empty cells if the first day of the week does not fall on the first day of the month.
  • Calendar_Month_Weeks -- Calendar_Month_Weeks API
  • constructor Calendar_Month_Weeks::Calendar_Month_Weeks -- Constructs Calendar_Month_Weeks
  • Calendar_Month_Weeks::build -- Builds Calendar_Week objects for the Month. Note that Calendar_Week
  • Calendar_Week -- Calendar_Week API
  • constructor Calendar_Week::Calendar_Week -- Constructs Week
  • Calendar_Week::build -- Builds Calendar_Day objects for this Week
  • Calendar_Week::nextWeek -- Gets the value of the following week, according to the requested format
  • Calendar_Week::prevWeek -- Gets the value of the previous week, according to the requested format
  • Calendar_Week::thisWeek -- Gets the value of the current week, according to the requested format
  • Calendar_Day -- Calendar_Day API
  • constructor Calendar_Day::Calendar_Day -- Constructs Calendar_Day
  • Calendar_Day::build -- Builds the Hours of the Day
  • Calendar_Day::isEmpty
  • Calendar_Day::isFirst -- Returns true if Day object is first in a Week
  • Calendar_Day::isLast -- Returns true if Day object is last in a Week
  • Calendar_Hour -- Calendar_Hour API
  • constructor Calendar_Hour::Calendar_Hour -- Constructs Calendar_Hour
  • Calendar_Hour::build -- Builds the Minutes in the Hour
  • Calendar_Minute -- Calendar_Minute API
  • constructor Calendar_Minute::Calendar_Minute -- Constructs Minute
  • Calendar_Minute::build -- Builds the Calendar_Second objects
  • Calendar_Second -- Calendar_Second API
  • constructor Calendar_Second::Calendar_Second -- Constructs Second
  • Calendar_Second::build -- Overwrite build
  • Calendar_Second::fetch -- Overwrite fetch
  • Calendar_Second::fetchAll -- Overwrite fetchAll
  • Calendar_Second::size -- Overwrite size
  • Calendar_Validation_Error -- Calendar_Validation_Error API
  • constructor Calendar_Validation_Error::Calendar_Validation_Error -- Constructs Calendar_Validation_Error
  • Calendar_Validation_Error::getMessage -- Returns the validation error message
  • Calendar_Validation_Error::getUnit -- Returns the Date unit
  • Calendar_Validation_Error::getValue -- Returns the value of the unit
  • Calendar_Validation_Error::toString -- Returns a string containing the unit, value and error message
  • Calendar_Validator -- Calendar_Validator API
  • constructor Calendar_Validator::Calendar_Validator -- Constructs Calendar_Validator
  • Calendar_Validator::fetch -- Iterates over any validation errors
  • Calendar_Validator::isValid -- Calls all the other isValidXXX() methods in the validator
  • Calendar_Validator::isValidDay -- Check whether this is a valid day
  • Calendar_Validator::isValidHour -- Check whether this is a valid hour
  • Calendar_Validator::isValidMinute -- Check whether this is a valid minute
  • Calendar_Validator::isValidMonth -- Check whether this is a valid month
  • Calendar_Validator::isValidSecond -- Check whether this is a valid second
  • Calendar_Validator::isValidYear -- Check whether this is a valid year
  • Package Calendar Constants -- Constants defined in and used by Calendar
Prev | Date and Time | Next
Date and Time | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What Calendar can do

Introduction

Some classes in PEAR::Calendar require PEAR::Date be installed. The PEAR::Date 1.3.1beta is missing a file and will not work. Make sure you have PEAR::Date version 1.4 or newer installed.

PEAR::Calendar is a package for generating Calendars as data structures. It does not render content or rely on any underlying data store, allowing it to be applied to many problem domains. At the same time it provides an easy to use API that makes rendering, for example, an HTML calendar very easy, while making it possible to "connect" the calendar with your data store.

PEAR::Calendar was developed as a result of finding no alternatives out there in PHP. There are numerous public domain calendar utilities / classes out there but all are tied to a specific output format (typically HTML with limited ability to customize without re-writing code) and often dependent on pre-built data structures stored in a database (read MySQL). This poses significant restrictions on the problem domains they can be applied to. By contrast PEAR::Calendar focuses on eliminating the math from the task of generating a calendar, allowing the end user to simply iterate over a prepared data structure.

Some of the benefits / features of PEAR::Calendar include:

  • You can render whatever output you like (e.g. (X)HTML, WML, SOAP, XML-RPC, command line ASCII or whatever).

  • Generating a calendar is much like looping through the results of a database query.

  • Representations of all "date objects" from a Year down to a Second (e.g. you can equally render a complete yearly calendar with months and days or a "Weekly / Daily Diary")

  • Allows "tabular" calendars to be generated easily.

  • Any date can be easily validated (is 29th Feb 2003 valid?).

  • Performs well despite number crunching and object oriented API.

  • Calendars can be easily navigated (e.g. providing a link from 1st Jan 2004 to 31st Dec 2003 is no problem).

  • It returns numeric values for all operations, meaning you are not tied to using, say, English names for months. Typically you would generate these yourself with PHP functions like strftime() and setlocale().

  • Representations of a date can be obtained as a human readable number or in the form of a timestamp (e.g. Unix Timestamp), depending on the calendar engine you are using.

  • You can attach your own functionality to the calendar by creating Decorators.

  • Allows you to write layered, N-Tier applications.

  • The calendar "calculation engine" is abstracted meaning you are not tied to a Gregorian calendar - you could write a Tolkien calendar should you wish. Currently "engines" based on Unixtimestamps (the default) and PEAR::Date have been implemented.

A Simple Example

<?php
require_once 'Calendar/Month.php';

$Month = new Calendar_Month(2003, 10); // October 2003

$Month->build(); // Build the days in the month

// Loop through the days...
while ($Day = $Month->fetch()) {
    echo $Day->thisDay().'<br />';
}
?>

Note: there are numerous and extensive examples provided with the PEAR::Calendar package file.

Prev | Calendar | Next
Calendar | PEAR Manual | Installing


Installing

Installing

Installing – How to install PEAR::Calendar

Installing

  • If not already installed, setup the PEAR package manager.

  • Type pear install Calendar-beta (using the command line manager)

  • PEAR::Calendar is now installed.

Prev | Calendar | Next
Introduction | PEAR Manual | In A Hurry


In A Hurry

In A Hurry

In A Hurry – Just add hot water...

In A Hurry

<?php
require_once 'Calendar/Month/Weekdays.php';

$Month = new Calendar_Month_Weekdays(date('Y'), date('n'));

$Month->build();

echo "<table>\n";

while ($Day = $Month->fetch()) {
    if ($Day->isFirst()) {
        echo "<tr>\n";
    }

    if ($Day->isEmpty()) {
        echo "<td>&nbsp;</td>\n";
    } else {
        echo '<td>'.$Day->thisDay()."</td>\n";
    }

    if ($Day->isLast()) {
        echo "</tr>\n";
    }
}

echo "</table>\n";
?>
Prev | Calendar | Next
Installing | PEAR Manual | Package Overview


Package Overview

Package Overview

Package Overview – Summary of Calendar Classes

Package Overview

When working with PEAR::Calendar, there are a total of 12 (public) classes available for you to use, depending on the particular problem you are trying to solve. They can be grouped in date classes, tabular date classes, validation classes and decorators.

Date Classes

Providing representations of all basic human date units. All are subclasses of Calendar so provide the methods defined there.

  • Calendar_Year - represents a year and can build Calendar_Month, Calendar_Month_Weekdays and Calendar_Month_Weeks objects.

    Include with

    <?php
    require_once 'Calendar/Year.php';
    ?>

    .

  • Calendar_Month - represents a month and can build Calendar_Day objects.

    Include with

    <?php
    require_once 'Calendar/Month.php';
    ?>

    .

  • Calendar_Day - represents a day and can build Calendar_Hour objects.

    Include with

    <?php
    require_once 'Calendar/Day.php';
    ?>

    .

  • Calendar_Hour - represents a hour and can build Calendar_Minute objects.

    Include with

    <?php
    require_once 'Calendar/Hour.php';
    ?>

    .

  • Calendar_Minute - represents a minute and can build Calendar_Second objects.

    Include with

    <?php
    require_once 'Calendar/Minute.php';
    ?>

    .

  • Calendar_Second - represents a second but cannot build anything.

    Include with

    <?php
    require_once 'Calendar/Second.php';
    ?>

    .

Tabular Date Classes

Designed for building calendars in tabular format. All are subclasses of Calendar so provide the methods defined there.

  • Calendar_Month_Weekdays - builds Calendar_Day objects setting the isFirst(), isLast() and isEmpty() states, to display a month in tabular form.

    Include with

    <?php
    require_once 'Calendar/Month/Weekdays.php';
    ?>

    .

  • Calendar_Month_Weeks - builds Calendar_Week objects, representing a month in terms of the tabular weeks it contains (see FAQ for what a week represents).

    Include with

    <?php
    require_once 'Calendar/Month/Weeks.php';
    ?>

    .

  • Calendar_Week - builds a collection of seven Calendar_Day objects. If extended by a Calendar_Month_Weeks object, it represents a tabular week in a month and it sets the isEmpty() state for the appropriate days, if necessary.

    Include with

    <?php
    require_once 'Calendar/Week.php';
    ?>

    .

Validation Classes

Used to validate dates. Calendar provides the methods isValid() to perform a simple check on any date and getValidator() to return an instance of Calendar_Validator for fine grained validation.

  • Calendar_Validator - is not instantiated by your code directly (you need need specifically include / create it) but instead returned from the Calendar::getValidator() method you can call on any subclass of Calendar. It is used to provide fine grained validation of a date to find out exactly what's wrong with it (for simple validation just call isValid() on any Date object or Tabular Date object, to know if it was created with valid values.

  • Calendar_Validation_Error - represents a validation error, providing methods to determine what went wrong. Available methods are getUnit() (e.g. returns Year or Month), getValue() (the value it failed with), getMessage() (the validation error message) and toString() which returns a combination of all the three preceding methods. The default validation error messages are in English but stored in the constants CALENDAR_VALUE_TOOSMALL and CALENDAR_VALUE_TOOLARGE which you can redefine in your code.

Decorators

Provide a mechanism to add functionality to the main calendar objects (the subclasses of Calendar) without needing to directly extend them (and risk overwriting fields accidentally). When you create a decorator, you pass its constructor an instance of an existing calendar object. You can then make calls to the decorator in exactly the same way as you make calls to the original calendar object. This allows you to "overwrite" calendar methods, add new methods or even apply multiple decorators to the same calendar object. Decorators a typically either "injected" (via selection or the Calendar_Decorator_Wrapper decorator) into the loop where the calendar is rendered and / or to alter the output content (e.g. convert a numeric month into a textual month: 1 => January).

PEAR::Calendar provides some decorator implementations for you, to help with common tasks. These are not designed to suit everyone and hence are provided as optional code for you to use as needed (avoiding the performance cost associated with parsing code you're not using).

  • Calendar_Decorator - this is the base decorator class which you should extend with your own. It provides the same API as the calendar object it is decorating, and simply routes calls through to it. Example;

    <?php
    require_once 'Calendar/Decorator.php';

    class     ChristmasDecorator extends Calendar_Decorator
    {
        function     ChristmasDecorator(&$Calendar)
        {
                parent::Calendar_Decorator($Calendar);
        }
            // Some method I've added
            function getDaysToChristmas()
        {
                $today = parent::thisDay(true);
                $Christmas = new Calendar_Day(date('Y'), 12, 25);
                $xmasday = $Christmas->thisDay(TRUE);
                $diff = $xmasday - $today;
            if (    $diff < 0) {
                    $NextChristmas = new Calendar_Day($Christmas->nextYear(), 12, 25);
                    $nextxmasday = $NextChristmas->thisDay(true);
                    $diff = $today - $nextxmasday;
            }
            return (    $diff / 86400);
        }
    }
    ?>

  • Calendar_Decorator_Uri - provides a decorator to help with generating URLs (for example next / prev URLs).

    Include with

    <?php
    require_once 'Calendar/Decorator/Uri.php';
    ?>

    .

  • Calendar_Decorator_Textual - helps with obtaining textual month names and weekday names from a calendar object.

    Include with

    <?php
    require_once 'Calendar/Decorator/Textual.php';
    ?>

    .

  • Calendar_Decorator_Wrapper - is intended to help you add decorators to the children of the calendar object you are working with. It will wrap the children in the decorator you specify at the point fetch() or fetchAll() is called, after a build build() call.

    Include with

    <?php
    require_once 'Calendar/Decorator/Wrapper.php';
    ?>

    .

Prev | Calendar | Next
In A Hurry | PEAR Manual | Method Overview


Method Overview

Method Overview

Method Overview – Summary of Calendar API

Method Overview

For the main Calendar classes (the subclasses of Calendar) all share a common API (a common set of class methods). Although there are some minor variations in specific cases, you should find it intuitive and easy to remember, once you are familiar with what's available. This section summarizes the common methods and highlights the variations. For further information, consult the API documentation.

Constructors

The constructors of the Date classes accept integer date values as their arguments, beginning with the year (on the left) across to the second (on the right), depending on what class you're using, for example;

<?php
// Natural Calendar Classes
$Year = new Calendar_Year(2003);                         // 2003
$Month = new Calendar_Month(2003, 10);                   // October 2003
$Day = new Calendar_Day(2003, 10, 25);                   // 25th October 2003
$Hour = new Calendar_Hour(2003, 10, 25, 13);             // 25th October 2003 13:00:00
$Minute = new Calendar_Minute(2003, 10, 25, 13, 31);     // 25th October 2003 13:31:00
$Second = new Calendar_Second(2003, 10, 25, 13, 31, 45); // 25th October 2003 13:31:45

// Tabular Calendar Classes
$Month = new Calendar_Month_Weekdays(2003, 10);          // October 2003
$Month = new Calendar_Month_Weeks(2003, 10);             // October 2003
$Week = new Calendar_Week(2003, 10, 25);                 // week containing 25th October 2003
?>

Note that the tabular classes, Calendar_Month_Weekdays and Calendar_Month_Weeks both take an optional third argument (integer) which specifies the first day of the week and adjust tabular display (normally it defaults to Monday (1) - pass the integer value 0 to switch to Sunday as the first day, for example). Calendar_Week accepts the first day argument as the fourth to its constructor.

Location Methods

All date and tabular date classes share the methods defined in the abstract base class Calendar. Among these are methods for an object of any of these classes to identify itself (what's its date is) and the previous and next dates. For example;

<?php
// Create a day
$Day = new Calendar_Day(2003, 10, 1); // 1st October 2003

echo $Day->thisDay(); // Displays 1
echo $Day->prevDay(); // Displays 30 (the 30th of September)
echo $Day->nextDay(); // Displays 2

echo $Day->thisMonth(); // Displays 10
echo $Day->prevMonth(); // Displays 9
echo $Day->nextMonth(); // Displays 11
?>

Notice that from the $Day I can find out not just about the day itself but also the month (or year/hour/minute/second). Notice also how prevDay() returned 30, taking care of working out that the previous day is in September for you. There are this***(), prev***() and next***() methods for years, months, days, hours, minutes and seconds.

Calling any of these methods and passing the value TRUE will result in a timestamp being returned (the type of timestamp depends on the Calendar Engine you are using - see the FAQ), for example;

<?php
// Create a second
$Second = new Calendar_Second(2003, 10, 25, 13, 32, 44);

echo $Second->thisYear(TRUE);     // Displays 1041375600
echo $Second->thisMonth(TRUE);    // Displays 1064959200
echo $Second->thisDay(TRUE);      // Displays 1067032800
echo $Second->thisHour(TRUE);     // Displays 1067079600
echo $Second->thisMinute(TRUE);   // Displays 1067081520
echo $Second->thisSecond(TRUE);   // Displays 1067081564
?>

Notice how the timestamp return increases, depending on the method that was called to obtain it. The first, obtained from thisYear(TRUE)() is a timestamp for the beginning of the year 2003 (1st January 2003 in fact) while the third from thisDay(TRUE)() is a timestamp for 25th October 2003.

The prev***() and next***() methods return values calculated relative to the current Calendar object you are working with. In the above example, if you wanted the day and month of the next day (which should be 2nd October 2003), calling nextDay() then nextMonth() would give you the 2nd of November not October. Instead you should call nextDay() passing it the argument TRUE, to get back a timestamp from which the next day can be obtained. Be aware of the Calendar_Decorator_Uri which is designed to help build URLs for next / prev links.

There are also the methods thisWeek(), prevWeek() and nextWeek() which only become available if you're using an instance of Calendar_Week. The returned value format can be chosen among 'timestamp', 'n_in_month', 'n_in_year' or 'array'. Be careful - if you select 'n_in_month', it will return NULL if it reaches the beginning or end of a month.

Finally all Calendar objects provide the methods getTimeStamp() and setTimeStamp(). The former returns a timestamp in the format used by the calendar engine you are working with (i.e. Unix Timestamp if it's the default UnixTs engine or of format YYYY-MM-DD HH:MM:SS). The later excepts a timestamp which is used to replace the values the Calendar object was constructed with.

Building and Fetching

Every date and tabular date class has a build() method which is used to generate the children of that date object. For example Calendar_Month builds Calendar_Day objects, the days being "children" of the month.

Once build() is called, the children can be fetched from the date object using the simple fetch() iterator, for example;

<?php
$Month = new Calendar_Month(2003, 10);

$Month->build();

while ($Day = $Month->fetch()) {
    echo $Day->thisDay()."<br />\n";
}
?>

The fetch() method returns one child at a time, in ascending date order, and returns FALSE when there are no more children. It also automatically resets the internal collection of children, meaning you can loop over them as many times as you like.

If you don't like the iterator, and wish to use your own, you can simply extract the children with the fetchAll() method (returns an indexed array of child date objects) and check the number you got back with size(). Be careful the index of the array you get back from fetchAll(). For Calendar_Year, Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks and Calendar_Week, the first index of the array is 1 while for Calendar_Day, Calendar_Hour, Calendar_Minute and Calendar_Second the index begins with 0. Why? Consider 2003-1-1 00:00:00 ...

Note: Calendar_Second::build() doesn't do anything - it has no children.

Selecting Children

To help with rendering the calendar, the build() methods accept an index array of date objects which is compares with the children it is building. If it finds that an object that was passed to it matches a child, it set's the childs state to selected, meaning the isSelected() method (available on any date or tabular date objects) returns TRUE. For example;

<?php
$Month = new Calendar_Month(2003, 10);

$DayX = new Calendar_Day(2003, 10, 15);
$DayY = new Calendar_Day(2003, 10, 23);
$selection = array($DayX, $DayY);

$Month->build($selection);

while ($Day = $Month->fetch()) {
    if ($Day->isSelected()) {
        echo $Day->thisDay()."<br />\n"; // Displays 15 or 23
    }
}
?>

In the above example, only 15th October 2003 and 23rd October 2003 are displayed.

The objects you pass to build() which match children that are being built replace the child (i.e. if there was a match, you get your object back). This allows you to "inject" your own objects into the loop, best accomplished by extending Calendar_Decorator.

Note: the Calendar_Year::build() method takes a second argument to specify the first day of the week (see above discussion on Constructors).

Tabular Days

The Calendar_Day class has three unique methods, which don't appear elsewhere, and are used purely for building tabular calendars. The isEmpty() is used to determine whether the day is an empty day or not (see FAQ for explaination of empty days). The methods isFirst() and isLast() are used to mark the beginning and and of a week.

Whether you need to use these methods depends on which class was used to build the day objects. If the day was built with Calendar_Month_Weekdays, all three of these methods are applicable (you may have empty days and Calendar_Month_Weekdays builts a complete month but delimits the beginning and end of each week so you can find it with isFirst() and isLast()). If the day was built with Calendar_Week, only the isEmpty() method is applicable (the first or last week in a month may contain empty days). For day objects built in any other manner, isEmpty(), isFirst() and isLast() are meaningless.

Validation

All date objects and tabular objects (except weeks) are capable of validating themselves. By default they accept whatever arguments they are given on construction but you can validate the date with the isValid() method, for example;

<?php
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    die ('Invalid date');
}
?>

For more fine grained validation, you can first call the getValidator() method, to return an instance of Calendar_Validator then list the validation errors;

<?php
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    $Validator = & $Day->getValidator();
    while ($Error = $Validator->fetch()) {
        echo $Error->getUnit().' is invalid<br>';
    }
}
?>

or...

<?php
$Day = new Calendar_Day(2003, 10, 32);

$Validator = & $Day->getValidator();
if (!$Validator->isValid()) {
    while ($Error = $Validator->fetch()) {
        echo $Error->toString().'<br>';
    }
}
?>

Note that rather than validating dates, you may prefer to automatically adjust them with the adjust() method, for example;

<?php
$Day = new Calendar_Day(2003, 10, 32);

$Day->adjust();

echo $Day->thisYear();      // 2003
echo $Day->thisMonth();     // 11 (moved forward a month)
echo $Day->thisDay();       // 1 (the first of the month)
?>

That summarizes all the methods available within PEAR::Calendar, apart from the those provided in the Decorator classes.

Prev | Calendar | Next
Package Overview | PEAR Manual | Calendar Decorators


Calendar Decorators

Calendar Decorators

Calendar Decorators – What Calendar_Decorator is for

Calendar Decorators

The Calendar_Decorator is provided to allow you to attach functionality to existing Calendar objects without needing to subclass them. This helps in a number of situations, such as allowing results from, say, a database query to be rendered in the calendar or to modify the values returned from Calendar methods (perhaps converting a numeric month into its textual name).

Some concrete decorators are provided with PEAR::Calendar, to address what may be common problems you encounter in using the library. These are not designed to suit everyone but instead focus on solving a more narrow problem domain. They will only be parsed by the PHP engine should you explicitly include them in your code. An example of why decorators can be useful:

<?php
require_once 'Calendar/Day.php';
require_once 'Calendar/Decorator.php';

class WorkingDay extends Calendar_Decorator {
    function WorkingDay(& $Calendar) {
        parent::Calendar_Decorator($Calendar);
    }

    // Overides the default fetch method of the calendar object
    function fetch() {
        if ($Hour = parent::fetch()) {

            // Recursive fetch, return only hours between 8am and 6pm
            if ($Hour->thisHour() < 8 || $Hour->thisHour() > 18) {
                return $this->fetch();
            } else {
                return $Hour;
            }
        } else {
            // Make sure to return FALSE when the real fetch returned nothing
            // or you will get an infinite loop
            return FALSE;
        }
    }
}

// Create a normal day and build the hours
$Day = new Calendar_Day(date('Y'), date('n'), date('d'));
$Day->build();

// Create the decorator, passing it the normal day
$WorkingDay = new WorkingDay($Day);

// Only hours in a working day are displayed...
while ($Hour = $WorkingDay->fetch()) {
    echo $Hour->thisHour().'<br />';
}
?>

The base Calendar_Decorator

The base class Calendar_Decorator "mirrors" the combined API of all the subclasses of Calendar. It accepts a Calendar object to its constructor then "takes over" the API allowing you to make calls through it rather than directly to the original calendar object. The Calendar_Decorator simply routes calls through to the calendar object it is decorating and returns values where appropriate.

Decorators and Date Selection

One important use of decorators is to help "inject" data into the loop which renders the calendar. This helps with fetching data from some sort of "event" table in a database. When passing a selection array to any build() method, the selected date objects will replace the default built objects, allowing you to get them back as inside the fetch() loop, using the isSelected() method. You'll find an example of this in the PEAR::Calendar download. It should always be possible to fetch the event data you need with a single database query...

The bundled Decorators

PEAR::Calendar already provides a few decorators:

  • Calendar_Decorator_Textual

    Decorator to help with fetching textual representations of months and days of the week. It has

  • Calendar_Decorator_Uri

    Decorator to help with building HTML links for navigating the calendar.

  • Calendar_Decorator_Weekday

    Decorator for fetching the day of the week.

  • Calendar_Decorator_Wrapper

    Decorator to help with wrapping built children in another decorator.

Calendar_Decorator_Textual example

This decorator defines a few methods that can be useful to handle month and day names:

  • monthNames($format ='long')

    Returns an array with month names; the format of returned months depends on the format parameter (one, two, short or long)

  • weekdayNames($format ='long')

    Returns an array with day names; the format of returned days depends on the format parameter (one, two, short or long)

  • prevMonthName($format ='long')

    Returns textual representation of the previous month of the decorated calendar object

  • thisMonthName($format ='long')

    Returns textual representation of the month of the decorated calendar object

  • nextMonthName($format ='long')

    Returns textual representation of the next month of the decorated calendar object

  • prevDayName($format ='long')

    Returns textual representation of the previous day of the decorated calendar object

  • thisDayName($format ='long')

    Returns textual representation of the day of the decorated calendar object

  • nextDayName($format ='long')

    Returns textual representation of the next day of the decorated calendar object

  • orderedWeekdays($format ='long')

    Returns the days of the week using the order defined in the decorated calendar object. Only useful for Calendar_Month_Weekdays, Calendar_Month_Weeks and Calendar_Week. Otherwise the returned array will begin on Sunday.

Calendar_Decorator_Uri example

Methods defined by this decorator:

  • setFragments($y, $m=null, $d=null, $h=null, $i=null, $s=null)

    Set the names of the URI vars for each date element

  • setSeparator($separator )

    Set the fragments separator, for instance '/' (default: &).

  • setScalar(boolean $state =TRUE)

    Puts Uri decorator into "scalar mode" - URI variable names are not returned

  • prev($method )

    Gets the URI string for the previous calendar unit (year, month, week or day etc)

  • this($method )

    Gets the URI string for the current calendar unit (year, month, week or day etc)

  • next($method )

    Gets the URI string for the next calendar unit (year, month, week or day etc)

A simple usage example:

<?php
$Day = new Calendar_Day(2003, 10, 23);
$Uri = & new Calendar_Decorator_Uri($Day);
$Uri->setFragments('year', 'month', 'day');
echo $Uri->prev('day');
// Displays year=2003&month=10&day=22
?>

Calendar_Decorator_Weekday example

Methods defined by this decorator:

  • setFirstDay($firstDay)

    Sets the first day of the week (0 = Sunday, 1 = Monday [default] etc)

  • prevWeekDay($format='int')

    Returns the previous weekday, formatted according the $format parameter (int, array, object, timestamp)

  • thisWeekDay($format='int')

    Returns the current weekday, formatted according the $format parameter (int, array, object, timestamp)

  • nextWeekDay($format='int')

    Returns the next weekday, formatted according the $format parameter (int, array, object, timestamp)

Example:

<?php
$Day = new Calendar_Day(2003, 10, 23);
$Weekday = & new Calendar_Decorator_Weekday($Day);
$Weekday->setFirstDay(0); // Set first day of week to Sunday (default Mon)
echo $Weekday->thisWeekDay(); // Displays 5 - fifth day of week relative to Sun
?>

Calendar_Decorator_Wrapper example

<?php
require_once 'Calendar/Month.php';
require_once 'Calendar/Decorator.php'; // Not really needed but added to help this make sense
require_once 'Calendar/Decorator/Wrapper.php';

class MyBoldDecorator extends Calendar_Decorator
{
    function MyBoldDecorator(&$Calendar)
    {
        parent::Calendar_Decorator($Calendar);
    }

    function thisDay()
    {
        return '<b>'.parent::thisDay().'</b>';
    }
}

$Month = new Calendar_Month(date('Y'), date('n'));

$Wrapper = & new Calendar_Decorator_Wrapper($Month);
$Wrapper->build();

echo '<h2>The Wrapper decorator</h2>';
echo '<i>Day numbers are rendered in bold</i><br /> <br />';
while ($DecoratedDay = $Wrapper->fetch('MyBoldDecorator')) {
    echo $DecoratedDay->thisDay().'<br />';
}
?>
Prev | Calendar | Next
Method Overview | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Frequently Asked Questions

Why doesn't it generate HTML?

What if you want WML, SOAP, PDF, GIF, command line, etc. etc.? PEAR::Calendar can be used to generate any output format you like (see the examples for SOAP and WML). Tying it to a particular output content type will limit its use (a problem that every public domain PHP Calendar library I've looked at suffers from). A PEAR::HTML_Calendar is likely to be developed using PEAR::Calendar.

There are too many objects, classes and files. It's bloated!

Running the examples on Sourceforge's servers (which are always overloaded), example 3.php renders in under 0.1 seconds (usually half that). The code is highly optimized and every "trick in the book" has been applied to make sure PHP only parses / executes the subset of logic you need for your specific problem. If in doubt, use Cache_Lite to cache the output HTML.

You use Unix timestamps to calculate the Calendar, which limits the range of years it can generate. Can this be changed?

All calculations are handled by a class implementing the Calendar_Engine interface. The default implemention is based on PHP's date() and mktime() functions (so Unix timestamps are required for that engine). A second engine exists which uses PEAR::Date. It's a bit slower but overcomes the limit on the range of Unixstamps. To switch between engines use the constant CALENDAR_ENGINE e.g.

<?php
// The default Unix timestamp engine (this definition is not required)
// define('CALENDAR_ENGINE', 'UnixTs');

// Switch to PEAR::Date engine
define('CALENDAR_ENGINE', 'PearDate');
?>

Note that the PearDate engine is based on PEAR::Date version 1.4 or newer.

This examples use the English language for days and months. Can this be changed?

PEAR::Calendar only uses base 10 numbers for calculations - the names of months and days of the week and generated as the calendar is being rendered (by you). You should only need to change PHP's locale with setlocale() and use the strftime() function e.g.:

<?php
$Day = & new Calendar_Day(2003, 10, 23);

setlocale (LC_TIME, 'de_DE'); // German

echo strftime('%A %d %B %Y', $Day->getTimeStamp());
?>

Note that Calendar_Decorator_Textual provides help in generating month and day of week names in a manner which is independent of the Calendar Engine you are using and can be modified with setlocale().

What are empty days?

PEAR::Calendar makes it easy to render calendars in tabular format (like humans are used to) such as:

October 2003
M T W T F S S
1 2 3 4 5
6 7 8 9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30 31

Notice the top left and botton right of this example - these are "empty days". Empty days are generated only by two calendar classes: Calendar_Month_Weekdays and Calendar_Week. For example using Calendar_Month_Weekdays;

<?php
require_once 'Calendar/Month/Weekdays.php';

$Month = & new Calendar_Month_Weekdays(2003, 10);
$Month->build();

while ($Day = & $Month->fetch()) {
    if ($Day->isFirst()) // Check for the start of a week
        echo "\n";

    if ($Day->isEmpty()) // Check to see if day is empty
        echo "\t";
    else
        echo $Day->thisDay()."\t";

    if ($Day->isLast()) // Check for the end of a week
        echo "\n";
}
?>

An empty day can still return values, the date it represents being from the previous or next month in the calendar. You may get empty days for Calendar_Month_Weekdays and Calendar_Week. Using Calendar_Week, you will only build 7 days (use Calendar_Month_Weeks to build Calendar_Week objects), so the isFirst() and isLast() methods are not applicable.

How do I select some dates?

All calendar objects (except Calendar_Second, which has no "children") have the method build() to build the "children" of that object. For example Calendar_Year::build() builds Calendar_Month objects while Calendar_Hour::build() builds Calendar_Minute objects. You have the option of passing this method an indexed array of Calendar objects which will be used to "select" the matching built children. For example:

<?php
$Month = & new Calendar_Month(2003, 10); // Oct 2003

$SelectedDay1 = & new Calendar_Day(2003, 10, 5);  // Oct  5th 2003
$SelectedDay2 = & new Calendar_Day(2003, 10, 21); // Oct 21st 2003

// Place in an array...
$selection = array($SelectedDay1, $SelectedDay2);

$Month->build($selection);

while ($Day = & $Month->fetch()) {
    if ($Day->isSelected())
        echo  $Day->thisYear().' '.$Day->thisMonth().' '.$Day->thisDay().' is selected'."\n";
}
?>

Note: the date objects you pass to a build() method replace the corresponding built date objects, allowing you to do things like attach your own subclass of Calendar_Decorator to them, then access the decorating functionality inside the loop which renders the calendar. You might display the contents from an "events database table" using this approach.

Why do I have to call build() explicitly. Why can't children be built automatically?

First and foremost, for performance. Building the children has a performance cost and you won't always need to have the children, so it should be called explicitly, otherwise you might have $Year->build(), expecting to get just months but behind the scenes, months built days, which built hours, which build minutes etc. Also calling build() yourself give you a chance to "select" some of the children.

How do I validate a date?

Validity is determined by the Calendar_Engine being used as well as the time the date object you're working with represents (e.g. $Month = & new Month(2003, 2, 29); is invalid, because Feb 2003 was not a leap year). For quick validation, you can call the method isValid() on any date object, which will return FALSE if there's a problem. For more information of more detailed validation, you can call the method getValidator() on any date object, which returns an instance of the class Calendar_Validator. For example;

<?php
$Month = & new Month(2003, 2, 29); // 29th Feb 2003 (?!?)
if (!$Month->isValid()) {
    $Validator = & $Month->getValidator();
    while ($Error = $Validator->fetch()) {
        echo $Error->toString();
    }
}
?>

You can also begin validation by calling getValidator()
then either isValidYear(), isValidMonth(),
isValidDay(), isValidHour(),
isValidMinute() and isValidSecond()
(or just isValid() which calls all of the isValidxxx methods).

Can I adjust invalid dates?

If you're allowing end users to navigate your calendar via the URL, were they to modify the URL to something like calendar.php?year=2003&month=13, instead of throwing a validation error at them, you could call the Calendar::adjust() method on the calendar object you create with that URL. You should then end up with January 2004 (in this example). This behaviour is possible thanks to mktime() for the Unix Timestamp engine, while being built into the PearDate engine for you.

After calling build(), I just want to get a single child date object without looping through the lot. How?

The method fetchAll() can be called on any date object to get an indexed array of all the children which have been built, allowing you to reference them directly. Be careful with the first index of this array - in some cases it will be [1] not [0], depending on the type of date object built. For example;

<?php
$Month = & new Calendar_Month(2003, 10);
$Month->build();

$days = & $Month->fetchAll(); // Now all in array
echo $days[1]->thisDay(); // The first day has index 1

$Hour = & new Calendar_Hour(2003, 10, 25, 15); // Oct 25th 2003, 3pm
$Hour->build();

$hours = & $Hour->fetchAll(); // Now all in array
echo $hours[0]->thisHour(); // The first hour has index 0
?>

The following classes are always built to have the first index as 1: Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks, Calendar_Week and Calendar_Day The following classes are always built to have the first index as 0: Calendar_Hour, Calendar_Minute and Calendar_Second Note also the method size() can be called on any date object, after build() has been called, to get the number of children.

What does a week actually represent in PEAR::Calendar?

Weeks are "pseudo" dates. They're useful for formatting the user interface for end users. Weeks are instantiated with a year, a month and a day of the month. You can then have the week tell you its timestamp (which will be the same as the timestamp for the first day in the week), its numeric position within the tabular month (see empty days above), its numeric position within the year (this is an ISO-8601 week number of year, weeks starting on Monday) or an array containing the numeric year, month and the first day of the week (as a number within the month). For example:

<?php
$Week = & new Calendar_Week(2003, 10, 15);

$Week = new Calendar_Week(2003, 10, 15);

echo $Week->thisWeek(); // Displays 2 (week num in month)
echo $Week->thisWeek('n_in_month'); // Display 2 - same as above

echo $Week->thisWeek('n_in_year');  // Displays 41 (week in year)

echo $Week->thisWeek('timestamp');  // Displays unix timestamp or an ISO-8601 datetime
                                    // (YYYY-MM-DD HH:MM:SS), depending on the engine.

print_r $Week->thisWeek('array');   // [year] => 2003 [month] => 10 [day] => 12
?>

How do I get a Calendar_Year to build Calendar_Month_Weekdays or Calendar_Month_Weeks, instead of the default Calendar_Month objects?

When working with a Calendar_Year, the constants CALENDAR_MONTH_STATE controls what type of month object is built. You can define CALENDAR_MONTH_STATE to CALENDAR_USE_MONTH_WEEKDAYS or CALENDAR_USE_MONTH_WEEKS for the Calendar_Month_Weekdays and Calendar_Month_Week classes, respectively.

You use Monday as the start of the week. Can I change that?

Yes. For the classes which are concerned with the notion of a "week", you can can pass a value which defines the first day of the week. For the default timestamp based Calendar engine, this is a number from 0 to 6, 0 being Sunday through to 6 being Saturday. This value can be passed to the following:

<?php
$Year = new Calendar_Year(2003);
$selection = array();
$Year->build($selection, 0); // the second argument is the first day of the week (Sunday)

$MonthWeekdays = new Calendar_Month_Weekdays(2003, 10, 6); // Third argument - Saturday

$MonthWeeks = new Calendar_Month_Weekdays(2003, 10, 2); // Third argument - Tuesday

$Week = new Calendar_Week(2003, 10, 15, 5) // Fourth argument - Friday
?>
Prev | Calendar | Next
Calendar Decorators | PEAR Manual | Calendar


Calendar

Calendar

Calendar – Calendar base class

Description

Calendar API.

Prev | Calendar | Next
FAQ | PEAR Manual | constructor Calendar::Calendar


constructor Calendar::Calendar

constructor Calendar::Calendar

constructor Calendar::Calendar() – Constructs the Calendar

Synopsis

require_once 'Calendar.php';

void constructor Calendar::Calendar ( int $y = 2000 , int $m = 1 , int $d = 1 , int $h = 0 , int $i = 0 , int $s = 0 )

Description

This package is not documented yet.

Parameter

integer $y

year

integer $m

month

integer $d

day

integer $h

hour

integer $i

minute

integer $s

second

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar | PEAR Manual | Calendar::adjust


Calendar::adjust

Calendar::adjust

Calendar::adjust() – Adjusts the date (helper method)

Synopsis

require_once 'Calendar.php';

void Calendar::adjust ( )

Description

Helper method. You can adjust calling object's date just like mktime does. For instance, (2003, 11, -1) will be translated to (2003, 10, 31). This method allows math operations on dates.

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar::Calendar | PEAR Manual | Calendar::build


Calendar::build

Calendar::build

Calendar::build() – Abstract method for building the children of a calendar object.

Synopsis

require_once 'Calendar.php';

boolean Calendar::build ( array $sDates = array() )

Description

Implemented by Calendar subclasses

Parameter

array $sDates

containing Calendar objects to select (optional)

abstract

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::adjust | PEAR Manual | Calendar::fetch


Calendar::fetch

Calendar::fetch

Calendar::fetch() – Iterator method for fetching child Calendar subclass objects (e.g. a minute from an hour object). On reaching the end of the collection, returns false and resets the collection for further iteratations.

Synopsis

require_once 'Calendar.php';

mixed Calendar::fetch ( )

Description

This package is not documented yet.

Return value

returns either an object subclass of Calendar or false

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::build | PEAR Manual | Calendar::fetchAll


Calendar::fetchAll

Calendar::fetchAll

Calendar::fetchAll() – Fetches all child from the current collection of children

Synopsis

require_once 'Calendar.php';

array Calendar::fetchAll ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::fetch | PEAR Manual | Calendar::getTimestamp


Calendar::getTimestamp

Calendar::getTimestamp

Calendar::getTimestamp() – Returns a timestamp from the current date / time values

Synopsis

require_once 'Calendar.php';

int Calendar::getTimestamp ( )

Description

Format of timestamp depends on Calendar_Engine implementation being used

Return value

returns timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::fetchAll | PEAR Manual | Calendar::getValidator


Calendar::getValidator

Calendar::getValidator

Calendar::getValidator() – Returns an instance of Calendar_Validator

Synopsis

require_once 'Calendar.php';

Calendar_Validator& Calendar::getValidator ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::getTimestamp | PEAR Manual | Calendar::isSelected


Calendar::isSelected

Calendar::isSelected

Calendar::isSelected() – True if the calendar subclass object is selected (e.g. today)

Synopsis

require_once 'Calendar.php';

boolean Calendar::isSelected ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::getValidator | PEAR Manual | Calendar::isValid


Calendar::isValid

Calendar::isValid

Calendar::isValid() – Determine whether this date is valid

Synopsis

require_once 'Calendar.php';

boolean Calendar::isValid ( )

Description

Determine whether this date is valid with the bounds determined by the Calendar_Engine. The call is passed on to Calendar_Validator::isValid

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::isSelected | PEAR Manual | Calendar::nextDay


Calendar::nextDay

Calendar::nextDay

Calendar::nextDay() – Returns the value for the next day

Synopsis

require_once 'Calendar.php';

int Calendar::nextDay ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 12 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::isValid | PEAR Manual | Calendar::nextHour


Calendar::nextHour

Calendar::nextHour

Calendar::nextHour() – Returns the value for the next hour

Synopsis

require_once 'Calendar.php';

int Calendar::nextHour ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 14 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::nextDay | PEAR Manual | Calendar::nextMinute


Calendar::nextMinute

Calendar::nextMinute

Calendar::nextMinute() – Returns the value for the next minute

Synopsis

require_once 'Calendar.php';

int Calendar::nextMinute ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 25 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::nextHour | PEAR Manual | Calendar::nextMonth


Calendar::nextMonth

Calendar::nextMonth

Calendar::nextMonth() – Returns the value for next month

Synopsis

require_once 'Calendar.php';

int Calendar::nextMonth ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 6 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::nextMinute | PEAR Manual | Calendar::nextSecond


Calendar::nextSecond

Calendar::nextSecond

Calendar::nextSecond() – Returns the value for the next second

Synopsis

require_once 'Calendar.php';

int Calendar::nextSecond ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 45 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::nextMonth | PEAR Manual | Calendar::nextYear


Calendar::nextYear

Calendar::nextYear

Calendar::nextYear() – Returns the value for next year

Synopsis

require_once 'Calendar.php';

int Calendar::nextYear ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 2004 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::nextSecond | PEAR Manual | Calendar::prevDay


Calendar::prevDay

Calendar::prevDay

Calendar::prevDay() – Returns the value for the previous day

Synopsis

require_once 'Calendar.php';

int Calendar::prevDay ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 10 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::nextYear | PEAR Manual | Calendar::prevHour


Calendar::prevHour

Calendar::prevHour

Calendar::prevHour() – Returns the value for the previous hour

Synopsis

require_once 'Calendar.php';

int Calendar::prevHour ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 13 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::prevDay | PEAR Manual | Calendar::prevMinute


Calendar::prevMinute

Calendar::prevMinute

Calendar::prevMinute() – Returns the value for the previous minute

Synopsis

require_once 'Calendar.php';

int Calendar::prevMinute ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 23 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::prevHour | PEAR Manual | Calendar::prevMonth


Calendar::prevMonth

Calendar::prevMonth

Calendar::prevMonth() – Returns the value for the previous month

Synopsis

require_once 'Calendar.php';

int Calendar::prevMonth ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 4 or Unix timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::prevMinute | PEAR Manual | Calendar::prevSecond


Calendar::prevSecond

Calendar::prevSecond

Calendar::prevSecond() – Returns the value for the previous second

Synopsis

require_once 'Calendar.php';

int Calendar::prevSecond ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 43 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::prevMonth | PEAR Manual | Calendar::prevYear


Calendar::prevYear

Calendar::prevYear

Calendar::prevYear() – Returns the value for the previous year

Synopsis

require_once 'Calendar.php';

int Calendar::prevYear ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 2002 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::prevSecond | PEAR Manual | Calendar::setSelected


Calendar::setSelected

Calendar::setSelected

Calendar::setSelected() – Defines calendar object as selected (e.g. for today)

Synopsis

require_once 'Calendar.php';

void Calendar::setSelected ( boolean $state = true )

Description

This package is not documented yet.

Parameter

boolean $state

state whether Calendar subclass

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::prevYear | PEAR Manual | Calendar::setSelection


Calendar::setSelection

Calendar::setSelection

Calendar::setSelection() – Abstract method for selected data objects called from build

Synopsis

require_once 'Calendar.php';

boolean Calendar::setSelection ( array $sDates )

Description

This package is not documented yet.

Parameter

array $sDates

abstract

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::setSelected | PEAR Manual | Calendar::setTimestamp


Calendar::setTimestamp

Calendar::setTimestamp

Calendar::setTimestamp() – Defines the calendar by a Unix timestamp

Synopsis

require_once 'Calendar.php';

void Calendar::setTimestamp ( int $ts )

Description

Defines the calendar by a Unix timestamp, replacing values passed to the constructor

Parameter

integer $ts

Unix timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::setSelection | PEAR Manual | Calendar::size


Calendar::size

Calendar::size

Calendar::size() – Get the number Calendar subclass objects stored in the internal collection.

Synopsis

require_once 'Calendar.php';

int Calendar::size ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::setTimestamp | PEAR Manual | Calendar::thisDay


Calendar::thisDay

Calendar::thisDay

Calendar::thisDay() – Returns the value for this day

Synopsis

require_once 'Calendar.php';

int Calendar::thisDay ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 11 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::size | PEAR Manual | Calendar::thisHour


Calendar::thisHour

Calendar::thisHour

Calendar::thisHour() – Returns the value for this hour

Synopsis

require_once 'Calendar.php';

int Calendar::thisHour ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 14 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::thisDay | PEAR Manual | Calendar::thisMinute


Calendar::thisMinute

Calendar::thisMinute

Calendar::thisMinute() – Returns the value for this minute

Synopsis

require_once 'Calendar.php';

int Calendar::thisMinute ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 24 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::thisHour | PEAR Manual | Calendar::thisMonth


Calendar::thisMonth

Calendar::thisMonth

Calendar::thisMonth() – Returns the value for this month

Synopsis

require_once 'Calendar.php';

int Calendar::thisMonth ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 5 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::thisMinute | PEAR Manual | Calendar::thisSecond


Calendar::thisSecond

Calendar::thisSecond

Calendar::thisSecond() – Returns the value for this second

Synopsis

require_once 'Calendar.php';

int Calendar::thisSecond ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 44 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::thisMonth | PEAR Manual | Calendar::thisYear


Calendar::thisYear

Calendar::thisYear

Calendar::thisYear() – Returns the value for this year

Synopsis

require_once 'Calendar.php';

int Calendar::thisYear ( string $format = 'int' )

Description

This package is not documented yet.

Parameter

string $format

'int', 'timestamp' , 'array' or 'object'

Return value

returns e.g. 2003 or timestamp

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar::thisSecond | PEAR Manual | Calendar_Year


Calendar_Year

Calendar_Year

Calendar_Year – Calendar_Year API

Description

Calendar_Year API.

Prev | Calendar | Next
Calendar::thisYear | PEAR Manual | constructor Calendar_Year::Calendar_Year


constructor Calendar_Year::Calendar_Year

constructor Calendar_Year::Calendar_Year

constructor Calendar_Year::Calendar_Year() – Constructs Calendar_Year

Synopsis

require_once 'Year.php';

void constructor Calendar_Year::Calendar_Year ( int $y )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Year | PEAR Manual | Calendar_Year::build


Calendar_Year::build

Calendar_Year::build

Calendar_Year::build() – Builds the Months of the Year.

Synopsis

require_once 'Year.php';

boolean Calendar_Year::build ( array$sDates = array() , int$firstDay = null )

Description

Note: by defining the constant CALENDAR_MONTH_STATE you can control what class of Calendar_Month is built e.g.;

1  require_once 'Calendar/Calendar_Year.php';
    2
define
('CALENDAR_MONTH_STATE',CALENDAR_USE_MONTH_WEEKDAYS); // Use Calendar_Month_Weekdays
    3  // define ('CALENDAR_MONTH_STATE',CALENDAR_USE_MONTH_WEEKS); // Use Calendar_Month_Weeks
    4

It defaults to building Calendar_Month objects.

Parameter

array $sDates

(optional) array of Calendar_Month objects representing selected months

integer $firstDay

(optional) first day of week (e.g. 0 for Sunday, 2 for Tuesday etc.)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Year::Calendar_Year | PEAR Manual | Calendar_Month


Calendar_Month

Calendar_Month

Calendar_Month – Calendar_Month API

Description

Calendar_Month API.

Prev | Calendar | Next
Calendar_Year::build | PEAR Manual | constructor Calendar_Month::Calendar_Month


constructor Calendar_Month::Calendar_Month

constructor Calendar_Month::Calendar_Month

constructor Calendar_Month::Calendar_Month() – Constructs Calendar_Month

Synopsis

require_once 'Month.php';

void constructor Calendar_Month::Calendar_Month ( int $y , int $m , int $firstDay = null )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $firstDay

(optional) unused in this class

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Month | PEAR Manual | Calendar_Month::build


Calendar_Month::build

Calendar_Month::build

Calendar_Month::build() – Builds Day objects for this Month. Creates as many Calendar_Day objects

Synopsis

require_once 'Month.php';

boolean Calendar_Month::build ( array $sDates = array() )

Description

as there are days in the month

Parameter

array $sDates

(optional) Calendar_Day objects representing selected dates

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Month::Calendar_Month | PEAR Manual | Calendar_Month_Weekdays


Calendar_Month_Weekdays

Calendar_Month_Weekdays

Calendar_Month_Weekdays – Calendar_Month_Weekdays API

Description

Calendar_Month_Weekdays API.

Prev | Calendar | Next
Calendar_Month::build | PEAR Manual | constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays


constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays

constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays

constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays() – Constructs Calendar_Month_Weekdays

Synopsis

require_once 'MonthWeekdays.php';

void constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays ( int $y , int $m , int $firstDay = false )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $firstDay

(optional) first day of week (e.g. 0 for Sunday, 2 for Tuesday etc.)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Month_Weekdays | PEAR Manual | Calendar_Month_Weekdays::build


Calendar_Month_Weekdays::build

Calendar_Month_Weekdays::build

Calendar_Month_Weekdays::build() – Builds Day objects in tabular form, to allow display of calendar month with empty cells if the first day of the week does not fall on the first day of the month.

Synopsis

require_once 'MonthWeekdays.php';

boolean Calendar_Month_Weekdays::build ( array $sDates = array() )

Description

This package is not documented yet.

Parameter

array $sDates

(optional) Calendar_Day objects representing selected dates

Throws

throws no exceptions thrown

See

see Calendar_Day_Base::isLast()

see Calendar_Day_Base::isFirst()

see Calendar_Day::isEmpty()

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays | PEAR Manual | Calendar_Month_Weeks


Calendar_Month_Weeks

Calendar_Month_Weeks

Calendar_Month_Weeks – Calendar_Month_Weeks API

Description

Calendar API.

Prev | Calendar | Next
Calendar_Month_Weekdays::build | PEAR Manual | constructor Calendar_Month_Weeks::Calendar_Month_Weeks


constructor Calendar_Month_Weeks::Calendar_Month_Weeks

constructor Calendar_Month_Weeks::Calendar_Month_Weeks

constructor Calendar_Month_Weeks::Calendar_Month_Weeks() – Constructs Calendar_Month_Weeks

Synopsis

require_once 'MonthWeeks.php';

void constructor Calendar_Month_Weeks::Calendar_Month_Weeks ( int $y , int $m , int $firstDay = false )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $firstDay

(optional) first day of week (e.g. 0 for Sunday, 2 for Tuesday etc.)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Month_Weeks | PEAR Manual | Calendar_Month_Weeks::build


Calendar_Month_Weeks::build

Calendar_Month_Weeks::build

Calendar_Month_Weeks::build() – Builds Calendar_Week objects for the Month. Note that Calendar_Week

Synopsis

require_once 'MonthWeeks.php';

boolean Calendar_Month_Weeks::build ( array $sDates = array() )

Description

builds Calendar_Day object in tabular form (with Calendar_Day->empty)

Parameter

array $sDates

(optional) Calendar_Week objects representing selected dates

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Month_Weeks::Calendar_Month_Weeks | PEAR Manual | Calendar_Week


Calendar_Week

Calendar_Week

Calendar_Week – Calendar_Week API

Description

Calendar_Week API.

Prev | Calendar | Next
Calendar_Month_Weeks::build | PEAR Manual | constructor Calendar_Week::Calendar_Week


constructor Calendar_Week::Calendar_Week

constructor Calendar_Week::Calendar_Week

constructor Calendar_Week::Calendar_Week() – Constructs Week

Synopsis

require_once 'Week.php';

void constructor Calendar_Week::Calendar_Week ( int $y , int $m , int $d , int $firstDay = false )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $d

a day of the desired week

integer $firstDay

(optional) first day of week (e.g. 0 for Sunday, 2 for Tuesday etc.)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Week | PEAR Manual | Calendar_Week::build


Calendar_Week::build

Calendar_Week::build

Calendar_Week::build() – Builds Calendar_Day objects for this Week

Synopsis

require_once 'Week.php';

boolean Calendar_Week::build ( array $sDates = array() )

Description

This package is not documented yet.

Parameter

array $sDates

(optional) Calendar_Day objects representing selected dates

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Week::Calendar_Week | PEAR Manual | Calendar_Week::nextWeek


Calendar_Week::nextWeek

Calendar_Week::nextWeek

Calendar_Week::nextWeek() – Gets the value of the following week, according to the requested format

Synopsis

require_once 'Week.php';

mixed Calendar_Week::nextWeek ( string $format )

Description

This package is not documented yet.

Parameter

string $format

['timestamp' | 'n_in_month' | 'n_in_year' | 'array']

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Week::build | PEAR Manual | Calendar_Week::prevWeek


Calendar_Week::prevWeek

Calendar_Week::prevWeek

Calendar_Week::prevWeek() – Gets the value of the previous week, according to the requested format

Synopsis

require_once 'Week.php';

mixed Calendar_Week::prevWeek ( string $format )

Description

This package is not documented yet.

Parameter

string $format

['timestamp' | 'n_in_month' | 'n_in_year' | 'array']

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Week::nextWeek | PEAR Manual | Calendar_Week::thisWeek


Calendar_Week::thisWeek

Calendar_Week::thisWeek

Calendar_Week::thisWeek() – Gets the value of the current week, according to the requested format

Synopsis

require_once 'Week.php';

mixed Calendar_Week::thisWeek ( string $format = 'n_in_month' )

Description

This package is not documented yet.

Parameter

string $format

['timestamp' | 'n_in_month' | 'n_in_year' | 'array']

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Week::prevWeek | PEAR Manual | Calendar_Day


Calendar_Day

Calendar_Day

Calendar_Day – Calendar_Day API

Description

Calendar_Day API.

Prev | Calendar | Next
Calendar_Week::thisWeek | PEAR Manual | constructor Calendar_Day::Calendar_Day


constructor Calendar_Day::Calendar_Day

constructor Calendar_Day::Calendar_Day

constructor Calendar_Day::Calendar_Day() – Constructs Calendar_Day

Synopsis

require_once 'Day.php';

void constructor Calendar_Day::Calendar_Day ( int $y , int $m , int $d )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 8

integer $d

day e.g. 15

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Day | PEAR Manual | Calendar_Day::build


Calendar_Day::build

Calendar_Day::build

Calendar_Day::build() – Builds the Hours of the Day

Synopsis

require_once 'Day.php';

boolean Calendar_Day::build ( array $sDates = array() )

Description

This package is not documented yet.

Parameter

array $sDates

(optional) Calendar_Hour objects representing selected dates

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Day::Calendar_Day | PEAR Manual | Calendar_Day::isEmpty


Calendar_Day::isEmpty

Calendar_Day::isEmpty

Calendar_Day::isEmpty() –

Synopsis

require_once 'Day.php';

boolean Calendar_Day::isEmpty ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Day::build | PEAR Manual | Calendar_Day::isFirst


Calendar_Day::isFirst

Calendar_Day::isFirst

Calendar_Day::isFirst() – Returns true if Day object is first in a Week

Synopsis

require_once 'Day.php';

boolean Calendar_Day::isFirst ( )

Description

Only relevant when Day is created by Calendar_Month_Weekdays::build()

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Day::isEmpty | PEAR Manual | Calendar_Day::isLast


Calendar_Day::isLast

Calendar_Day::isLast

Calendar_Day::isLast() – Returns true if Day object is last in a Week

Synopsis

require_once 'Day.php';

boolean Calendar_Day::isLast ( )

Description

Only relevant when Day is created by Calendar_Month_Weekdays::build()

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Day::isFirst | PEAR Manual | Calendar_Hour


Calendar_Hour

Calendar_Hour

Calendar_Hour – Calendar_Hour API

Description

Calendar_Hour API.

Prev | Calendar | Next
Calendar_Day::isLast | PEAR Manual | constructor Calendar_Hour::Calendar_Hour


constructor Calendar_Hour::Calendar_Hour

constructor Calendar_Hour::Calendar_Hour

constructor Calendar_Hour::Calendar_Hour() – Constructs Calendar_Hour

Synopsis

require_once 'Hour.php';

void constructor Calendar_Hour::Calendar_Hour ( int $y , int $m , int $d , int $h )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $d

day e.g. 11

integer $h

hour e.g. 13

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Hour | PEAR Manual | Calendar_Hour::build


Calendar_Hour::build

Calendar_Hour::build

Calendar_Hour::build() – Builds the Minutes in the Hour

Synopsis

require_once 'Hour.php';

boolean Calendar_Hour::build ( array $sDates = array() )

Description

This package is not documented yet.

Parameter

array $sDates

(optional) Calendar_Minute objects representing selected minutes

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Hour::Calendar_Hour | PEAR Manual | Calendar_Minute


Calendar_Minute

Calendar_Minute

Calendar_Minute – Calendar_Minute API

Description

Calendar_Minute API.

Prev | Calendar | Next
Calendar_Hour::build | PEAR Manual | constructor Calendar_Minute::Calendar_Minute


constructor Calendar_Minute::Calendar_Minute

constructor Calendar_Minute::Calendar_Minute

constructor Calendar_Minute::Calendar_Minute() – Constructs Minute

Synopsis

require_once 'Minute.php';

void constructor Calendar_Minute::Calendar_Minute ( int $y , int $m , int $d , int $h , int $i )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $d

day e.g. 11

integer $h

hour e.g. 13

integer $i

minute e.g. 31

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Minute | PEAR Manual | Calendar_Minute::build


Calendar_Minute::build

Calendar_Minute::build

Calendar_Minute::build() – Builds the Calendar_Second objects

Synopsis

require_once 'Minute.php';

boolean Calendar_Minute::build ( array $sDates = array() )

Description

This package is not documented yet.

Parameter

array $sDates

(optional) Calendar_Second objects representing selected seconds

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Minute::Calendar_Minute | PEAR Manual | Calendar_Second


Calendar_Second

Calendar_Second

Calendar_Second – Calendar_Second API

Description

Calendar_Second API.

Prev | Calendar | Next
Calendar_Minute::build | PEAR Manual | constructor Calendar_Second::Calendar_Second


constructor Calendar_Second::Calendar_Second

constructor Calendar_Second::Calendar_Second

constructor Calendar_Second::Calendar_Second() – Constructs Second

Synopsis

require_once 'Second.php';

void constructor Calendar_Second::Calendar_Second ( int $y , int $m , int $d , int $h , int $i , int $s )

Description

This package is not documented yet.

Parameter

integer $y

year e.g. 2003

integer $m

month e.g. 5

integer $d

day e.g. 11

integer $h

hour e.g. 13

integer $i

minute e.g. 31

integer $s

second e.g. 45

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Second | PEAR Manual | Calendar_Second::build


Calendar_Second::build

Calendar_Second::build

Calendar_Second::build() – Overwrite build

Synopsis

require_once 'Second.php';

NULL Calendar_Second::build ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Second::Calendar_Second | PEAR Manual | Calendar_Second::fetch


Calendar_Second::fetch

Calendar_Second::fetch

Calendar_Second::fetch() – Overwrite fetch

Synopsis

require_once 'Second.php';

NULL Calendar_Second::fetch ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Second::build | PEAR Manual | Calendar_Second::fetchAll


Calendar_Second::fetchAll

Calendar_Second::fetchAll

Calendar_Second::fetchAll() – Overwrite fetchAll

Synopsis

require_once 'Second.php';

NULL Calendar_Second::fetchAll ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Second::fetch | PEAR Manual | Calendar_Second::size


Calendar_Second::size

Calendar_Second::size

Calendar_Second::size() – Overwrite size

Synopsis

require_once 'Second.php';

NULL Calendar_Second::size ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Second::fetchAll | PEAR Manual | Calendar_Validation_Error


Calendar_Validation_Error

Calendar_Validation_Error

Calendar_Validation_Error – Calendar_Validation_Error API

Description

Calendar_Validation_Error API.

Prev | Calendar | Next
Calendar_Second::size | PEAR Manual | constructor Calendar_Validation_Error::Calendar_Validation_Error


constructor Calendar_Validation_Error::Calendar_Validation_Error

constructor Calendar_Validation_Error::Calendar_Validation_Error

constructor Calendar_Validation_Error::Calendar_Validation_Error() – Constructs Calendar_Validation_Error

Synopsis

require_once 'Validator.php';

void constructor Calendar_Validation_Error::Calendar_Validation_Error ( string $unit , int $value , string $message )

Description

This package is not documented yet.

Parameter

string $unit

Date unit (e.g. month,hour,second)

integer $value

Value of unit which failed test

string $message

Validation error message

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validation_Error | PEAR Manual | Calendar_Validation_Error::getMessage


Calendar_Validation_Error::getMessage

Calendar_Validation_Error::getMessage

Calendar_Validation_Error::getMessage() – Returns the validation error message

Synopsis

require_once 'Validator.php';

string Calendar_Validation_Error::getMessage ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Validation_Error::Calendar_Validation_Error | PEAR Manual | Calendar_Validation_Error::getUnit


Calendar_Validation_Error::getUnit

Calendar_Validation_Error::getUnit

Calendar_Validation_Error::getUnit() – Returns the Date unit

Synopsis

require_once 'Validator.php';

string Calendar_Validation_Error::getUnit ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validation_Error::getMessage | PEAR Manual | Calendar_Validation_Error::getValue


Calendar_Validation_Error::getValue

Calendar_Validation_Error::getValue

Calendar_Validation_Error::getValue() – Returns the value of the unit

Synopsis

require_once 'Validator.php';

int Calendar_Validation_Error::getValue ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validation_Error::getUnit | PEAR Manual | Calendar_Validation_Error::toString


Calendar_Validation_Error::toString

Calendar_Validation_Error::toString

Calendar_Validation_Error::toString() – Returns a string containing the unit, value and error message

Synopsis

require_once 'Validator.php';

string Calendar_Validation_Error::toString ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validation_Error::getValue | PEAR Manual | Calendar_Validator


Calendar_Validator

Calendar_Validator

Calendar_Validator – Calendar_Validator API

Description

Calendar_Validator API.

Prev | Calendar | Next
Calendar_Validation_Error::toString | PEAR Manual | constructor Calendar_Validator::Calendar_Validator


constructor Calendar_Validator::Calendar_Validator

constructor Calendar_Validator::Calendar_Validator

constructor Calendar_Validator::Calendar_Validator() – Constructs Calendar_Validator

Synopsis

require_once 'Validator.php';

void constructor Calendar_Validator::Calendar_Validator ( object subclass &$calendar )

Description

This package is not documented yet.

Parameter

object subclass; &$calendar

of Calendar

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator | PEAR Manual | Calendar_Validator::fetch


Calendar_Validator::fetch

Calendar_Validator::fetch

Calendar_Validator::fetch() – Iterates over any validation errors

Synopsis

require_once 'Validator.php';

mixed Calendar_Validator::fetch ( )

Description

This package is not documented yet.

Return value

returns either Calendar_Validation_Error or false

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
constructor Calendar_Validator::Calendar_Validator | PEAR Manual | Calendar_Validator::isValid


Calendar_Validator::isValid

Calendar_Validator::isValid

Calendar_Validator::isValid() – Calls all the other isValidXXX() methods in the validator

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValid ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::fetch | PEAR Manual | Calendar_Validator::isValidDay


Calendar_Validator::isValidDay

Calendar_Validator::isValidDay

Calendar_Validator::isValidDay() – Check whether this is a valid day

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValidDay ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::isValid | PEAR Manual | Calendar_Validator::isValidHour


Calendar_Validator::isValidHour

Calendar_Validator::isValidHour

Calendar_Validator::isValidHour() – Check whether this is a valid hour

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValidHour ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::isValidDay | PEAR Manual | Calendar_Validator::isValidMinute


Calendar_Validator::isValidMinute

Calendar_Validator::isValidMinute

Calendar_Validator::isValidMinute() – Check whether this is a valid minute

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValidMinute ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::isValidHour | PEAR Manual | Calendar_Validator::isValidMonth


Calendar_Validator::isValidMonth

Calendar_Validator::isValidMonth

Calendar_Validator::isValidMonth() – Check whether this is a valid month

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValidMonth ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::isValidMinute | PEAR Manual | Calendar_Validator::isValidSecond


Calendar_Validator::isValidSecond

Calendar_Validator::isValidSecond

Calendar_Validator::isValidSecond() – Check whether this is a valid second

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValidSecond ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::isValidMonth | PEAR Manual | Calendar_Validator::isValidYear


Calendar_Validator::isValidYear

Calendar_Validator::isValidYear

Calendar_Validator::isValidYear() – Check whether this is a valid year

Synopsis

require_once 'Validator.php';

boolean Calendar_Validator::isValidYear ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Calendar | Next
Calendar_Validator::isValidSecond | PEAR Manual | Package Calendar Constants


Package Calendar Constants

Package Calendar Constants

Package Calendar Constants – Constants defined in and used by Calendar

All Constants

Constants defined in Calendar.php

Constants defined in Calendar.php
Name | Value | Line Number
CALENDAR_ENGINE | 'UnixTS' | 39
CALENDAR_ROOT | 'Calendar'.DIRECTORY_SEPARATOR | 32

Constants defined in Validator.php

Constants defined in Validator.php
Name | Value | Line Number
CALENDAR_VALUE_TOOLARGE | 'Too large: max = ' | 34
CALENDAR_VALUE_TOOSMALL | 'Too small: min = ' | 31

Constants defined in Year.php

Constants defined in Year.php
Name | Value | Line Number
CALENDAR_USE_MONTH | 1 | 43
CALENDAR_USE_MONTH_WEEKDAYS | 2 | 44
CALENDAR_USE_MONTH_WEEKS | 3 | 45
Prev | Calendar | Next
Calendar_Validator::isValidYear | PEAR Manual | Date


Date

Date

PEAR Date is a generic class to represent and work with dates. It does not use timestamps which means it can be used for dates before 1970 and after 2038. The class provides methods to convert a date in different formats, calculate differences, weekdays and more.

Table of Contents
  • Examples -- Learning by doing
  • Basics -- How to get information
Prev | Date and Time | Next
Package Calendar Constants | PEAR Manual | Examples


Examples

Examples

Examples – Learning by doing

Introduction

Following the saying "learning by doing", we start with some examples.

The first step to work with the class is to instantiate a Date object.

Creating a Date object

<?php
require_once 'Date.php';

//without parameter == now
$now = new Date();

//pass a string in ISO format
$longAgo = new Date('1813-02-23T05:34:23');

//create a Date object from a PHP unix timestamp
$timestamp = time();
$nearlyNow = new Date($timestamp);

//make a copy of an existing Date object
$copyDate = new Date($longAgo);
?>

After finishing your work with the date object, you probably want to have it back. This can be done in different ways, for example by using getTime or getDate.

Getting the date in different formats

<?php
require_once 'Date.php';
$now = new Date();

//UNIX timestamp:     1183054688
echo $now->getTime();

//ISO formatted date: 2007-06-28 20:18:08
echo $now->getDate();
?>

Date has a lot more methods to output your date, but that is subject of a later chapter.

Now that we know how to create a Date instance, we'll do some easy tasks.

Calculating a time difference

You often have the task to know which time span lies between two dates. With Date, this is easy to accomplish. First we use setFromDateDiff on a fresh Date_Span object and then toDays to get the exact number of days between the two dates.

Calculating a time span

<?php
require_once 'Date.php';

$someDate  = new Date('1813-02-23T05:34:23');
$otherDate = new Date('1789-12-21T18:23:42');

$span = new Date_Span();
$span->setFromDateDiff($someDate, $otherDate);

//time span in days: 8463,46575231
echo $span->toDays();

//time span in full years: 23
echo (int)($span->toDays() / 365);
?>
Note: Date_Span works, unlike Date, internally with integers, which means that you have a precision of 32 bit or 68 years.

Converting timezones

Date can help you working with time zones. An array with all supported timezones can be retrieved by using getAvailableIDs statically as in $list = Date_TimeZone::getAvailableIDs();.

convertTZ converts the Date object's internal settings to the given time zone. Using format you can display the timezone setting. With Date_TimeZone's getDefault method the default time zone for this computer can be obtained.

Converting timezones

<?php
require_once 'Date.php';

//assume it's 2007-06-28 18:42:12
$now      = new Date();
$timezone = new Date_TimeZone('Australia/Adelaide');

//convert the date object to the timezone
$now->convertTZ($timezone);

//will give you:     2007-06-29 02:12:12
echo $now->getDate();
//now with timezone: 2007-06-29 02:12:12+09:30
echo $now->format('%Y-%m-%d %H:%M:%S%O');

//switch back
$defaultZone = Date_TimeZone::getDefault();
$now->convertTZ($defaultZone);

//we have our normal zone now: 2007-06-28 18:42:12+02:00
echo $now->format('%Y-%m-%d %H:%M:%S%O');
?>

Sorting an array of dates

Once you have an array of Date objects, you might want to sort it. The class provides a static method compare that helps with this.

Sorting dates

<?php
require_once 'Date.php';

$dates = array(
    new Date('1813-02-23T05:34:23'),
    new Date(),
    new Date('1714-12-21T18:23:42'),
);

usort($dates, array('Date', 'compare'));

/*
* prints the dates correctly sorted:
*  1714-12-21 18:23:42
*  1813-02-23 05:34:23
*  2007-06-28 20:59:39
*/
foreach ($dates as $date) {
    echo $date->getDate() . "\n";
}
?>
Prev | Date | Next
Date | PEAR Manual | Basics


Basics

Basics

Basics – How to get information

Introduction

The auto-generated API documentation is very valuable to get information about this packages' methods and which parameters they require. But of course you first need to have an overview about the abilities of the class.

Getting data

There are a number of simple getter methods that let you retrieve single pieces of a date currently set.

  • getYear

  • getMonth

  • getDay

  • getHour

  • getMinute

  • getSecond

Date does also have some advanced methods to obtain data from it.

  • getDayName returns the name of the day in short (Mon) or long form (Monday)

  • getMonthName returns the name of the month in short (Jan) or long form (January)

  • getDayOfWeek calculates the number of the day in the week (0-6, Sunday being 0)

  • getWeekOfYear returns the week number of this date

  • getQuarterOfYear

Navigating between dates

The following method all return a new date object.

  • getNextDay

  • getPrevDay

  • getNextWeekday

  • getPrevWeekday

You can also do excact calculations by adding and subtracting intervals. The *Span methods require a Date_Span object to be passed as only parameter while the others take a number representing seconds.

  • addSeconds

  • subtractSeconds

  • addSpan

  • subtractSpan

Prev | Date | Next
Examples | PEAR Manual | Date_Holidays


Date_Holidays

Date_Holidays

Holiday calculation package.

This chapter describes how to use PEAR::Date_Holidays

Table of Contents
  • Introduction -- What Date_Holidays can do
  • Example -- Example for the usage of Date_Holidays
Prev | Date and Time | Next
Basics | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What Date_Holidays can do

Introduction

Date_Holidays is a driver-based holiday calculation package. It helps you check whether a specific date is a holiday in a specific country or religion. Furthermore you can calculate the date of any holiday supported in the driver for the country, region or religion.

Currently the following drivers are supported:

  • Austria

  • Christian, calculates Christian holidays (used as base driver for other drivers)

  • Denmark

  • England & Wales

  • Germany, calculates German holidays

  • Ireland, calculates Irish holidays

  • Jewish, calculates Jewish holidays

  • The Netherlands

  • Norway

  • Slovenia

  • Sweden, calculates Swedish holidays

  • USA, calculates holidays in the United States of America

  • UNO, calculates UNO (United Nations Organization) holidays

  • Composite, a driver that is used to combine any number of the other drivers so they can be queried at once.

If you have written a custom driver for Date_Holidays that could be included in the distribution, please contact the package maintainers or open a feature request and attach a patch in the bug tracking tool.

Date_Holidays supports I18N by storing the names of the different holidays in INI files for each language. These files will be stored in the data directory of your PEAR installation.

Prev | Date_Holidays | Next
Date_Holidays | PEAR Manual | Example


Example

Example

Example – Example for the usage of Date_Holidays

Basic example

This example shows you, how to calculate the Easter date of 2005.

<?php
require_once "Date/Holidays.php";
$germany = &Date_Holidays::factory('Germany', 2004, 'en_EN');
if (Date_Holidays::isError($germany)) {
    die('Factory was unable to produce driver-object');
}
$easter = &$germany->getHoliday('easter', 'de_DE');
if (!Date_Holidays::isError($easter)) {
    print_r($easter->toArray());
}
?>

This will return an array in the following format:

Array
(
    [internalName] => easter
    [title] => Easter Sunday
    [date] => date Object
        (
            [year] => 2004
            [month] => 04
            [day] => 11
            [hour] => 0
            [minute] => 0
            [second] => 0
            [tz] => date_timezone Object
                (
                    [id] => UTC
                    [longname] => Coordinated Universal Time
                    [shortname] => UTC
                    [hasdst] =>
                    [dstlongname] => Coordinated Universal Time
                    [dstshortname] => UTC
                    [offset] => 0
                    [default] =>
                )

        )

)
Prev | Date_Holidays | Next
Introduction | PEAR Manual | Encryption


Encryption

Encryption

Provides packages for encryption, decryption, signing, verifying and key management.

Table of Contents
  • Crypt_CHAP
  • Crypt_GPG
Prev | PEAR Packages | Next
Example | PEAR Manual | Crypt_CHAP


Crypt_CHAP

Crypt_CHAP

Classes for generating packets for various CHAP Protocols

Table of Contents
  • Introduction -- encryption
  • Crypt_CHAP::generateChallenge() -- Generates a new random challenge.
  • Crypt_CHAP_MD5::Crypt_CHAP_MD5() -- constructor
  • Crypt_CHAP_MD5::challengeResponse() -- Generates the challenge-response paket.
  • Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1() -- constructor
  • Crypt_CHAP_MSCHAPv1::challengeResponse() -- Generates the Challenge-Response paket.
  • Crypt_CHAP_MSCHAPv1::lmChallengeResponse() -- Generates the Challenge-Response paket using the LAN-Manager Hash.
  • Crypt_CHAP_MSCHAPv1::ntChallengeResponse() -- Generates the Challenge-Response paket using the NT-Hash.
  • Crypt_CHAP_MSCHAPv1::ntPasswordHash() -- Generates the NT-Hash from the given plaintext-password.
  • Crypt_CHAP_MSCHAPv1::lmPasswordHash() -- Generates the LAN-Manager-Hash from the given plaintext-password.
  • Crypt_CHAP_MSCHAPv1::str2unicode() -- Converts a string to unicode.
  • Crypt_CHAP_MSCHAPv1::response() -- Generates the response-packet.
  • Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2() -- constructor
  • Crypt_CHAP_MSCHAPv2::challengeHash() -- Generates the Challenge-Hash.
  • Crypt_CHAP_MSCHAPv2::ntPasswordHashHash() -- Generates an MD4 Hash from the NT-Hash.
Prev | Encryption | Next
Encryption | PEAR Manual | Introduction


Introduction

Introduction

Introduction – encryption

CHAP - Challenge Handshake Authentication Protocol

CHAP is a part usualy of PPP (Point-to-Point Protocol) software, implemented in the authentication subsystem. CHAP avoid's sending plaintext passwords over an insecure link. The traditional CHAP-MD5 needs the plaintext password stored on the server. MS-CHAP doesen't need this, but also needs the password either as NT-Hash and/or as LAN-Manager-Hash. LAN-Manager-Hashes are weak and shouldn't be used anymore.

This package provides 3 classes:

  • Crypt_CHAP::Crypt_CHAP_MD5() - for generating CHAP-MD5 (RFC 1994) compliant pakets
  • Crypt_CHAP::Crypt_MSCHAPv1() - for generating MS-CHAPv1 (RFC 2433) compliant pakets
  • Crypt_CHAP::Crypt_MSCHAPv2() - for generating MS-CHAPv2 (RFC 2759) compliant pakets

Crypt_CHAP::Crypt_CHAP is an abstract base class.

In order to get the MS-CHAP* to work you need the mhash extension.

Prev | Crypt_CHAP | Next
Crypt_CHAP | PEAR Manual | Crypt_CHAP::generateChallenge()


Crypt_CHAP::generateChallenge()

Crypt_CHAP::generateChallenge()

Crypt_CHAP::generateChallenge() – Generates a new random challenge.

Synopsis

string Crypt_CHAP::generateChallenge ( string $varname = 'challenge' , int $size = 8 )

Description

This method generates a new random challenge and stores it in the given property, the default size of the challenge is 8 bytes.

Parameter

  • string $varname - name of the property for storing the challenge

  • int $size - the size of the challenge

Return value

string - a String containing the challenge

Note

This function can not be called statically.

Example

Using Crypt_CHAP::generateChallenge()

<?php
require_once 'File/SMBPasswd.php';

$cr = new Crypt_CHAP_MD5();
echo bin2hex($cr->challenge);
// or generate a new challenge
echo bin2hex(echo $cr->generateChallenge());

?>
Prev | Crypt_CHAP | Next
Introduction | PEAR Manual | Crypt_CHAP_MD5::Crypt_CHAP_MD5()


Crypt_CHAP_MD5::Crypt_CHAP_MD5()

Crypt_CHAP_MD5::Crypt_CHAP_MD5()

Crypt_CHAP_MD5::Crypt_CHAP_MD5() – constructor

Synopsis

require_once 'Crypt/CHAP.php';

void Crypt_CHAP_MD5::Crypt_CHAP_MD5 ( )

Description

Generates a new Object for generating CHAP-MD5 compliant pakets.

Prev | Crypt_CHAP | Next
Crypt_CHAP::generateChallenge() | PEAR Manual | Crypt_CHAP_MD5::challengeResponse()


Crypt_CHAP_MD5::challengeResponse()

Crypt_CHAP_MD5::challengeResponse()

Crypt_CHAP_MD5::challengeResponse() – Generates the challenge-response paket.

Synopsis

string Crypt_CHAP_MD5::challengeResponse ( )

Description

This method generates the challenge-response paket, by doing: md5(ID + Password + Challenge).

Return value

string - a String containing the challenge-response paket

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MD5::challengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MD5();
$cr->password = 'MyPw';
echo bin2hex($cr->challengeResponse());

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MD5::Crypt_CHAP_MD5() | PEAR Manual | Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()


Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()

Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()

Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1() – constructor

Synopsis

require_once 'Crypt/CHAP.php';

void Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1 ( )

Description

Generates a new Object for generating MS-CHAPv1 compliant pakets.

Note

You need the mhash extension in order to get this class to work.

Prev | Crypt_CHAP | Next
Crypt_CHAP_MD5::challengeResponse() | PEAR Manual | Crypt_CHAP_MSCHAPv1::challengeResponse()


Crypt_CHAP_MSCHAPv1::challengeResponse()

Crypt_CHAP_MSCHAPv1::challengeResponse()

Crypt_CHAP_MSCHAPv1::challengeResponse() – Generates the Challenge-Response paket.

Synopsis

string Crypt_CHAP_MSCHAPv1::challengeResponse ( )

Description

This method generates the Challenge-Response paket.

Return value

string - a String containing the challenge-response paket

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv1::challengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->chapid = 1;
$cr->password = 'MyPw';
echo bin2hex($cr->challengeResponse());

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1() | PEAR Manual | Crypt_CHAP_MSCHAPv1::lmChallengeResponse()


Crypt_CHAP_MSCHAPv1::lmChallengeResponse()

Crypt_CHAP_MSCHAPv1::lmChallengeResponse()

Crypt_CHAP_MSCHAPv1::lmChallengeResponse() – Generates the Challenge-Response paket using the LAN-Manager Hash.

Synopsis

string Crypt_CHAP_MSCHAPv1::lmChallengeResponse ( )

Description

This method generates the Challenge-Response using the LAN-Manager Hash.

Return value

string - a String containing the challenge-response

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv1::lmChallengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password = 'MyPw';
echo bin2hex($cr->lmChallengeResponse());

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::challengeResponse() | PEAR Manual | Crypt_CHAP_MSCHAPv1::ntChallengeResponse()


Crypt_CHAP_MSCHAPv1::ntChallengeResponse()

Crypt_CHAP_MSCHAPv1::ntChallengeResponse()

Crypt_CHAP_MSCHAPv1::ntChallengeResponse() – Generates the Challenge-Response paket using the NT-Hash.

Synopsis

string Crypt_CHAP_MSCHAPv1::ntChallengeResponse ( )

Description

This method generates the Challenge-Response using the NT-Hash.

Return value

string - a String containing the challenge-response

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv1::ntChallengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password = 'MyPw';
echo bin2hex($cr->ntChallengeResponse());

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::lmChallengeResponse() | PEAR Manual | Crypt_CHAP_MSCHAPv1::ntPasswordHash()


Crypt_CHAP_MSCHAPv1::ntPasswordHash()

Crypt_CHAP_MSCHAPv1::ntPasswordHash()

Crypt_CHAP_MSCHAPv1::ntPasswordHash() – Generates the NT-Hash from the given plaintext-password.

Synopsis

string Crypt_CHAP_MSCHAPv1::ntPasswordHash ( string $password = '' )

Description

This method generates NT-Hash from the given plaintext-password or from the password property. The NT-Hash is computed like this: md4(str2unicode(plaintext))

Parameter

  • string $password - the password to be hashed

Return value

string - a String containing the NT-Hash

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv1::ntPasswordHash()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password = 'MyPw';
echo bin2hex($cr->ntPasswordHash());

// or
echo bin2hex($cr->ntPasswordHash('MySecret'));

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::ntChallengeResponse() | PEAR Manual | Crypt_CHAP_MSCHAPv1::lmPasswordHash()


Crypt_CHAP_MSCHAPv1::lmPasswordHash()

Crypt_CHAP_MSCHAPv1::lmPasswordHash()

Crypt_CHAP_MSCHAPv1::lmPasswordHash() – Generates the LAN-Manager-Hash from the given plaintext-password.

Synopsis

string Crypt_CHAP_MSCHAPv1::lmPasswordHash ( string $password = '' )

Description

This method generates LAN-Manager-Hash from the given plaintext-password or from the password property.

Parameter

  • string $password - the password to be hashed

Return value

string - a String containing the LAN-Manager-Hash

Note

This function can not be called statically.

LAN-Manager Hash are weak and should not be used anymore.

Example

Using Crypt_CHAP_MSCHAPv1::lmPasswordHash()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password = 'MyPw';
echo bin2hex($cr->lmPasswordHash());

// or
echo bin2hex($cr->lmPasswordHash('MySecret'));

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::ntPasswordHash() | PEAR Manual | Crypt_CHAP_MSCHAPv1::str2unicode()


Crypt_CHAP_MSCHAPv1::str2unicode()

Crypt_CHAP_MSCHAPv1::str2unicode()

Crypt_CHAP_MSCHAPv1::str2unicode() – Converts a string to unicode.

Synopsis

string Crypt_CHAP_MSCHAPv1::str2unicode ( string $str )

Description

This method generates converts the given string to unicode.

Parameter

  • string $str - the string to be unicoded

Return value

string - a String containing unicode representation of the given string

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv1::str2unicode()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
echo bin2hex($cr->str2unicode('MyPw'));

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::lmPasswordHash() | PEAR Manual | Crypt_CHAP_MSCHAPv1::response()


Crypt_CHAP_MSCHAPv1::response()

Crypt_CHAP_MSCHAPv1::response()

Crypt_CHAP_MSCHAPv1::response() – Generates the response-packet.

Synopsis

string Crypt_CHAP_MSCHAPv1::response ( bool $lm = false )

Description

This method generates the response paket, containing the NT-Challenge-Response and/or the LM-Challenge-Response. By default the LM-Challenge-Response is not included.

Parameter

  • bool $lm - wether including the LM-Challenge-Response

Return value

string - a String containing the paket

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv1::response()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password  = 'MyPw';
echo bin2hex($cr->response());

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::str2unicode() | PEAR Manual | Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()


Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()

Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()

Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2() – constructor

Synopsis

require_once 'Crypt/CHAP.php';

void Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2 ( )

Description

Generates a new Object for generating MS-CHAPv2 compliant pakets. This version of CHAP uses also a Peer-Challenge, LM-Hashes are not used anymore. The Constructor generates automatically a Peer-Challenge and the Authenticator-Challenge.

Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv1::response() | PEAR Manual | Crypt_CHAP_MSCHAPv2::challengeHash()


Crypt_CHAP_MSCHAPv2::challengeHash()

Crypt_CHAP_MSCHAPv2::challengeHash()

Crypt_CHAP_MSCHAPv2::challengeHash() – Generates the Challenge-Hash.

Synopsis

string Crypt_CHAP_MSCHAPv2::challengeHash ( )

Description

This method generates the (SHA1) Challenge-Hash containing the authenticator and the peer challenge and the username.

Return value

string - a String containing the Challenge-Hash

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv2::challengeHash()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv2();
$cr->username = 'billy';
$cr->peerChallenge = $peerChallenge;
$cr->authChallenge = $authChallenge;
echo bin2hex($cr->challengeHash());

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2() | PEAR Manual | Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()


Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()

Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()

Crypt_CHAP_MSCHAPv2::ntPasswordHashHash() – Generates an MD4 Hash from the NT-Hash.

Synopsis

string Crypt_CHAP_MSCHAPv2::ntPasswordHashHash ( string $nthash )

Description

This method generates an MD4 Hash from the given NT-Hash.

Parameter

  • string $nthash - the NT-Hash to be hashed

Return value

string - a String containing the NT-Hash

Note

This function can not be called statically.

Example

Using Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv2();
$nthash = $cr->ntPasswordHash('MyPw');
echo bin2hex($cr->ntPasswordHashHash($nthash));

?>
Prev | Crypt_CHAP | Next
Crypt_CHAP_MSCHAPv2::challengeHash() | PEAR Manual | Crypt_GPG


Crypt_GPG

Crypt_GPG

Table of Contents
  • Introduction and Overview
  • Generating a GnuPG Key
  • Usage
  • Referring to Keys
  • Examples
Prev | Encryption | Next
Crypt_CHAP_MSCHAPv2::ntPasswordHashHash() | PEAR Manual | Introduction and Overview


Introduction and Overview

Introduction and Overview

Introduction

Crypt_GPG is a PHP package to interact with the GNU Privacy Guard (GnuPG). GnuPG is a free and open-source implementation of the OpenPGP protocol, providing key management, data encryption and data signing. Crypt_GPG provides an object-oriented API for performing OpenPGP actions using GnuPG.

GnuPG is distributed as an executable program with a command-line argument syntax for performing actions. Crypt_GPG uses PHP's program execution functions to run GnuPG as a subprocess, performing the desired action. Crypt_GPG automatically handles process control, stream handling and error checking of the GnuPG subprocess. Crypt_GPG uses PHP streams internally for most actions, allowing (among other things) any streamable resource to be used with the Crypt_GPG file commands.

Note: Though GnuPG can support symmetric-key cryptography, this package is intended only to facilitate public-key cryptography.

Overview

The basic internal overview of a GnuPG command executed in Crypt_GPG is as follows:

  1. build the required command line,

  2. open the GnuPG subprocess with the command line,

  3. stream data to and from the GnuPG subprocess on various IPC pipes until the command is finished,

  4. close the GnuPG subprocess and,

  5. check for errors.

Crypt_GPG handles all these details internally so GnuPG can be used with minimal effort from the developer.

Prev | Crypt_GPG | Next
Crypt_GPG | PEAR Manual | Generating a GnuPG Key


Generating a GnuPG Key

Generating a GnuPG Key

Outlines how to generate a GnuPG key for use with Crypt_GPG.

Crypt_GPG does not yet support generating GnuPG keys. Generating a GnuPG key for use with Crypt_GPG is much the same as generating any other GnuPG key on a system.

Important: Though Crypt_GPG supports specifying the keyring to use, Crypt_GPG, by default, uses the keyring of the current user. If using Crypt_GPG with a webserver such as Apache, the current user is the Apache user and the key will need to be generated as the Apache user. To do this, run the gen-key command as:
$ sudo -u apache gpg --gen-key

The following example walks through the process of generating a key that supports both encrypting and signing. First, run the command:

$ gpg --gen-key

This will display the following copyright information and a list of available key types:

gpg (GnuPG) 1.4.6; Copyright (C) 2006 Free Software Foundation, Inc. This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. See the file COPYING for details. Please select what kind of key you want: (1) DSA and Elgamal (default) (2) DSA (sign only) (5) RSA (sign only) Your selection? 1 DSA keypair will have 1024 bits.

Select (1) DSA and Elgamal (default) to allow the generated key to both encrypt and sign data. This will generate a public-private key pair in the GPG keyring and prompt for the size of the encryption key:

ELG-E keys may be between 1024 and 4096 bits long. What keysize do you want? (2048)

Select the default value of 2048. Enter greater or fewer bits depending on how secure the encryption must be. The default value is considered safe for most applications. GnuPG then prompts for the time period over which the generated key will be valid:

Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) Key does not expire at all Is this correct? (y/N) y

Unless the key needs to expire after a certain time period (preventing subsequent decryption), a key that does not expire should be used. Next, enter the three parts of the key's user id. The first part of the user id is the real name of the person or organization that will use the key to sign or encrypt data. The second part is an email address and the third is a comment about the key. Both the email address and comment are optional:

You need a user ID to identify your key; the software constructs the user ID from the Real Name, Comment and Email Address in this form: "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>" Real name: Test User Email address: test@example.com Comment: test key Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o

After entering the primary user id of the new key, the passphrase must be selected. A secret passphrase is essential to securing encrypted data. Guessable passphrases will render encryption useless. For critical data such as credit card numbers, a non-dictionary word that is at least 8 characters long is recommended.

You need a Passphrase to protect your secret key. Enter passphrase: Repeat passphrase:

Following the passphrase, GnuPG will gather entropy for a period to ensure the generated key uses sutitably random numbers. When enough entropy is collected the key is generated and added to the keyring:

We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy. ... snip ... gpg: key DB15A2C9 marked as ultimately trusted public and secret key created and signed. gpg: checking the trustdb gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u pub 1024D/DB15A2C9 2008-08-05 Key fingerprint = F94A F628 5725 7147 0569 F9FF E995 8292 DB15 A2C9 uid Test User (test key) <test@example.com> sub 2048g/6AD96F48 2008-08-05

At this point the key is in the GnuPG keyring and ready to be used by Crypt_GPG.

Prev | Crypt_GPG | Next
Introduction and Overview | PEAR Manual | Usage


Usage

Usage

Creating The Crypt_GPG Object

The Crypt_GPG class is the main entry point for using Crypt_GPG. To use GnuPG in your project, create an instance of Crypt_GPG and then call methods on the object to perform GPG actions.

The Crypt_GPG class supports several options, which may be specified in the constructor. Options may be used for the following:

Specifying Keyring Location

Sometimes, specifying the location of the keyring is required. One such case case is when using Crypt_GPG from the context of a Web page when the Web-server's user does not have a home directory, or does not have write access to its home directory. This is often the case on shared hosts. In this case, you should specify the GnuPG keyring location as an existing writeable directory. This is done using the homedir option. For example:

<?php

require_once 'Crypt/GPG.php';

// Specify homedir as an existing writeable directory if the web user
// does not have a home directory, or if the web user's home directory
// is not writeable.
$gpg = new Crypt_GPG(array('homedir' => '/my/writeable/directory'));

?>

Showing Debug Information

If, for some reason, Crypt_GPG does not seem to work correctly, detailed debugging information may be turned on. This is done using the debug option. When providing bug reports for the Crypt_GPG package, you may be asked to turn on deubg mode. Example:

<?php

require_once 'Crypt/GPG.php';

// Enable debug mode. This will dump a lot of output when Crypt_GPG
// actions are performed.
$gpg = new Crypt_GPG(array('debug' => true));

?>

Specifying the GnuPG Binary Location

Crypt_GPG works by talking to the GnuPG subprocess. As a result, it needs to know the location of the GnuPG binary to work properly. In most cases, Crypt_GPG will detect the location of the GnuPG binary automatically. If the location is detected incorrectly, or if the GnuPG binary is installed in a custom location, the binary option may be used. For example:

<?php

require_once 'Crypt/GPG.php';

// Specify custom location of GnuPG binary.
$gpg = new Crypt_GPG(array('binary' => '/home/joe/bin/gpg'));

?>

If an invalid binary location is specified, Crypt_GPG will throw an exception.

Prev | Crypt_GPG | Next
Generating a GnuPG Key | PEAR Manual | Referring to Keys


Referring to Keys

Referring to Keys

Outlines how to refer to GnuPG keys in code using Crypt_GPG.

Fingerprint

Crypt_GPG supports referring to a key in several ways. The most definitive way to refer to a specific key is to use the key's fingerprint. Key fingerprints are generated by performing a checksum on the actual content of a key. A fingerprint appears as a string of hexadecimal characters, sometimes separated by spaces or colons. For example: F94A F628 5725 7147 0569 F9FF E995 8292 DB15 A2C9. The fingerprint of a key can be retrieved using the Crypt_GPG::getKeys() and Crypt_GPG::getFingerprint() methods. Alternatively, the following command may be used to list keys on a console:

$ gpg --list-keys --with-fingerprint --with-fingerprint

Note: --with-fingerprint is doubled intentionally.

Key ID

Keys may also be referenced by the key id. The key id is an eight-octal long hexadecimal number. The key id can be obtained using Crypt_GPG::getKeys(). Though rare, it is possible to have two keys with the same key id. The key id may also be obtained using the following command:

$ gpg --list-keys --with-colons

The key id is the fifth colon-separated field. A partial key id may also be used to reference a key. The partial key id is the lower four octals of a full key id and may be obtained using the following command:

$ gpg --list-keys

User ID

Lastly, keys may be referenced by all or part of the key's user id. For example, Test User (test key) <test@example.com>, Test User <test@example.com> and test@example.com may all be used to refer to the same key. When there is more than on key in the keyring with the same user id (or partial user id), the first key is used. In these cases, it is important to use a more specific identifier to ensure the correct key is used. In general, unless the keyring contains many keys, the less specific but more convenient form of test@example.com is fine to use.

Prev | Crypt_GPG | Next
Usage | PEAR Manual | Examples


Examples

Examples

Note: The following examples assume you have created a key following the instructions for generating a key that can both encrypt and sign data. The example key has a user id of test@example.com and a passphrase of test. All signature data is fictitious, but is formatted like real signature data.

Signing a Package File

<?php
require_once 'Crypt/GPG.php';

$gpg = new Crypt_GPG();
$gpg->addSignKey('test@example.com', 'test');
$signature = $gpg->signFile($filename, Crypt_GPG::SIGN_MODE_DETACHED);

echo "Package signature is: ", $signature, "\n";
?>

Verifying a Signed File

<?php
require_once 'Crypt/GPG.php';

$signature = <<<DATA
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
iD8DBQBIl9Tf6ZWCktsVoskRAoAKAJ9VkbFDTSGY2ygaEGBcMOE8Or9puwCgppYm
0qq0bhtw5vsi0cJF5oC52RY=
=VfxI
-----END PGP SIGNATURE-----
DATA;

$gpg        = new Crypt_GPG();
$signatures = $gpg->verifyFile($filename, $signature);

if ($signatures[0]->isValid()) {
     echo "Package is valid.\n";
} else {
     echo "Package is invalid!\n";
}
?>

Encrypting a File From the Web

<?php

require_once 'Crypt/GPG.php';

$gpg = new Crypt_GPG();
$gpg->addEncryptKey('test@example.com');
// you can use any fopen-able stream
$gpg->encryptFile('http://example.com/file.html', '~/file.html.asc');
?>

Encrypting Credit Card Numbers

<?php
require_once 'Crypt/GPG.php';

// ... connect to database ...

$card_number = '411111111111';
$card_type   = 'visa';

$gpg = new Crypt_GPG();
$gpg->addEncryptKey('test@example.com');
$encrypted = $gpg->encrypt($card_number);

$sql = sprintf('insert into payments (card_type, card_number) ' .
               'values (%s, %s)',
               mysql_real_escape_string($card_type),
               mysql_real_escape_string($encrypted));

mysql_exec($sql);
?>

Decrypting Credit Card Numbers

<?php
require_once 'Crypt/GPG.php';

// ... connect to database ...

$gpg = new Crypt_GPG();
$gpg->addDecryptKey('test@example.com', 'test');

$sql = 'select card_type, card_number from payments';
$rs  = mysql_query($sql);
while ($row = mysql_fetch_object($rs)) {
    echo "Card type:   ", $row->card_type, "\n";
    echo "Card number: ", $gpg->decrypt($row->card_number), "\n";
}
?>

Publishing a Public Key

<?php
require_once 'Crypt/GPG.php';

$gpg = new Crypt_GPG();
echo "My public key is: ", $gpg->exportPublicKey('test@example.com'), "\n";
echo "My key fingerprint is: ",
     $gpg->getFingerprint('test@example.com', Crypt_GPG::FORMAT_CANONICAL), "\n";
?>

Clearsigning a Message

<?php
require_once 'Crypt/GPG.php';

$data = 'Hello, World!';

$gpg = new Crypt_GPG();
$gpg->addSignKey('test@example.com', 'test');
$signedData = $gpg->sign($data, Crypt_GPG::SIGN_MODE_CLEAR);

echo "Clearsigned message is: ", $signedData, "\n";
?>

Verifying a Clearsigned Message

<?php
require_once 'Crypt/GPG.php';

$signedData = <<<DATA
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hello, World!
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
iD8DBQFIl9Sb6ZWCktsVoskRArWDAJ9D5mq6p+4JnBy11OaAhnIA+uRSSACgoM5T
WcUHQ9pKf9PvNUn1Izy6c9E=
=k8+7
-----END PGP SIGNATURE-----
DATA;

$gpg        = new Crypt_GPG();
$signatures = $gpg->verify($signedData);

if ($signatures[0]->isValid()) {
     echo "Message is valid.\n";
} else {
     echo "Message is invalid!\n";
}
?>
Prev | Crypt_GPG | Next
Referring to Keys | PEAR Manual | Event


Event

Event

Provides packages for event based development.

Table of Contents
  • Event_Dispatcher
Prev | PEAR Packages | Next
Examples | PEAR Manual | Event_Dispatcher


Event_Dispatcher

Event_Dispatcher

Dispatch notifications using PHP callbacks

Table of Contents
  • Introduction -- Introduction to Event_Dispatcher
  • Examples -- Examples for the usage of Event_Dispatcher
  • Event_Dispatcher::getInstance -- Create a new Event_Dispatcher object
  • Event_Dispatcher::getName -- Get the name of the dispatcher.
  • Event_Dispatcher::addObserver -- Add a new observer.
  • Event_Dispatcher::removeObserver -- Remove an observer.
  • Event_Dispatcher::setNotificationClass -- Set the class that is used as notification.
  • Event_Dispatcher::post -- Post a notification.
  • Event_Dispatcher::addNestedDispatcher -- Add a nested dispatcher.
  • Event_Dispatcher::removeNestedDispatcher -- Remove a nested dispatcher.
  • Event_Notification -- Container class for notifications.
  • Event_Notification::Event_Notification -- Create a new notification object.
  • Event_Notification::getNotificationName -- Get the name of the notification.
  • Event_Notification::getNotificationObject -- Get the object that sent the notification.
  • Event_Notification::getNotificationInfo -- Get additional information from the notification.
  • Event_Notification::getNotificationCount -- Get number of observers notified.
  • Event_Notification::cancelNotification -- Cancel the notification.
  • Event_Notification::isNotificationCancelled -- Check, whether notification has been cancelled.
Prev | Event | Next
Event | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Event_Dispatcher

Introduction to Event_Dispatcher

Event_Dispatcher acts as a notification dispatch table. It is used to notify other objects of interesting things. This information is encapsulated in Event_Notification objects.

Client objects register themselves with the Event_Dispatcher as observers of specific notifications posted by other objects. When an event occurs, an object posts an appropriate notification to the Event_Dispatcher. The Event_Dispatcher dispatches a message to each registered observer, passing the notification as the sole argument.

Event_Dispatchers allows you to use event bubbling similar to JavaScript's event management. If an event is not handled by the dispatcher that triggered the event, it may bubble up to the next dispatcher.

Prev | Event_Dispatcher | Next
Event_Dispatcher | PEAR Manual | Examples


Examples

Examples

Examples – Examples for the usage of Event_Dispatcher

Examples usage of Event_Dispatcher

The following examples show you how to use Event_Dispatcher to create more flexible applications.

Basic example

<?php
require_once 'Event/Dispatcher.php';

/**
 * Dummy class that simulated authentication
 */
class Auth
{
    var $_dispatcher = null;
    var $_user;

    function Auth(&$dispatcher)
    {
         $this->_dispatcher = &$dispatcher;
    }

    function login($username, $password)
    {
        // Your code that authenticates goes here
        // ....
        // imagine $this->_user contains a User object

        $this->_dispatcher->post($this->_user, 'onLogin');
    }
}

function logAuth(&$notification)
{
    $user = &$notification->getNotificationObject();
    $username = $user->getUsername();

    // write logfile
    error_log("$username logged in.", 3, '/tmp/auth.log');
}

$dispatcher = &Event_Dispatcher::getInstance();

// catch all onLogin events to write a logfile
$dispatcher->addObserver('logAuth', 'onLogin');

$auth = &new Auth($dispatcher);

// simulate login
$auth->login($_GET['user'], $_GET['pass']);
?>

In this example, Event_Dispatcher is used to allow observers to hook into the authentication process. Whenever a user authenticates, a notification onLogin is sent.

This can be used to write logfiles or block the application for other users.

Cancelling notifications

<?php
require_once 'Event/Dispatcher.php';

/**
 * Dummy class that simulated authentication
 */
class Auth
{
    var $_dispatcher = null;
    var $_user;

    function Auth(&$dispatcher)
    {
         $this->_dispatcher = &$dispatcher;
    }

    function login($username, $password)
    {
        // Your code that authenticates goes here
        // ....
        // imagine $this->_user contains a User object

        $notification = $this->_dispatcher->post($this->_user, 'onLogin');

        if ($notification->isNotificationCancelled()) {
            echo "You are not allowed to login";
            $this->_user->logout();
        }
    }
}

function logAuth(&$notification)
{
    $user = &$notification->getNotificationObject();
    $username = $user->getUsername();

    // If a special user authenticated, cancel
    // the notification
    if ($username === 'foo') {
        $notification->cancelNotification();
    } else {
        // write logfile
        error_log("$username logged in.", 3, '/tmp/auth.log');
    }
}

$dispatcher = &Event_Dispatcher::getInstance();

// catch all onLogin events to write a logfile
$dispatcher->addObserver('logAuth', 'onLogin');

$auth = &new Auth($dispatcher);

// simulate login
$auth->login($_GET['user'], $_GET['pass']);
?>

In this case, the cancelNotification() method is used to cancel the notification if a certain user tries to authenticate.

The login method has been changed as well to check whether the notification has been cancelled and to take the necessary steps.

This allows you to add some flexible rules to your authentication system.

Prev | Event_Dispatcher | Next
Introduction | PEAR Manual | Event_Dispatcher::getInstance


Event_Dispatcher::getInstance

Event_Dispatcher::getInstance

Event_Dispatcher::getInstance() – Create a new Event_Dispatcher object

Synopsis

require_once 'Event/Dispatcher.php';

object Event_Dispatcher Event_Dispatcher::getInstance ( string $name = '__default' )

Description

Create a new Event_Dispatcher object.

As Event_Dispatcher uses the singleton pattern, you must not use the new operator to create a new instance of Event_Dispatcher, but use getInstance() instead.

If you need more than one instance of Event_Dispatcher, pass different names to the method.

Parameter

  • string $name = '__default'

Return value

object Event_Dispatcher Event_Dispatcher instance

Note

This function should be called statically.

Prev | Event_Dispatcher | Next
Examples | PEAR Manual | Event_Dispatcher::getName


Event_Dispatcher::getName

Event_Dispatcher::getName

Event_Dispatcher::getName() – Get the name of the dispatcher.

Synopsis

require_once 'Event/Dispatcher.php';

string Event_Dispatcher::getName ( )

Description

Get the name of the dispatcher.

The name of the dispatcher is used as a unique identifier. This is important for the methods getInstance() and removeNestedDispatcher().

Return value

string name of the dispatcher

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::getInstance | PEAR Manual | Event_Dispatcher::addObserver


Event_Dispatcher::addObserver

Event_Dispatcher::addObserver

Event_Dispatcher::addObserver() – Add a new observer.

Synopsis

require_once 'Event/Dispatcher.php';

void Event_Dispatcher::addObserver ( mixed $callback , string $nName = EVENT_DISPATCHER_GLOBAL , string $class = '' )

Description

Adds a new observer to the dispatcher.

Observers are PHP callbacks. That means you may either pass a function name as a string or an array containing an object or class and a method to call.

The callback is used as a signature for the observer, which allows you to remove it by passing the exact same parameters to removeObserver().

Parameter

  • mixed $callback

    Callback to notity, may either be a string containing the name of a global function or an array containing class or object and the name of the method to call.

  • string $nName = EVENT_DISPATCHER_GLOBAL

    Acts as a filter: notify the observer only if the notification name matches the name passed in this parameter. Use EVENT_DISPATCHER_GLOBAL if the observer should be notified regardles of the notification name.

  • string $class = ''

    Acts as a filter: notify the observer only if the sender of the notification matches the class passed in this parameter.

Return value

void

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::getName | PEAR Manual | Event_Dispatcher::removeObserver


Event_Dispatcher::removeObserver

Event_Dispatcher::removeObserver

Event_Dispatcher::removeObserver() – Remove an observer.

Synopsis

require_once 'Event/Dispatcher.php';

bool Event_Dispatcher::removeObserver ( mixed $callback , string $nName = EVENT_DISPATCHER_GLOBAL , string $class = '' )

Description

Remove an observer from dispatcher.

To remove an observer, specify the same parameters as used in the call to addObserver().

Parameter

  • mixed $callback

    Callback to notity, may either be a string containing the name of a global function or an array containing class or object and the name of the method to call.

  • string $nName = EVENT_DISPATCHER_GLOBAL

    Acts as a filter: notify the observer only if the notification name matches the name passed in this parameter. Use EVENT_DISPATCHER_GLOBAL if the observer should be notified regardles of the notification name.

  • string $class = ''

    Acts as a filter: notify the observer only if the sender of the notification matches the class passed in this parameter.

Return value

bool TRUE if the observer could be removed, FALSE otherwise

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::addObserver | PEAR Manual | Event_Dispatcher::setNotificationClass


Event_Dispatcher::setNotificationClass

Event_Dispatcher::setNotificationClass

Event_Dispatcher::setNotificationClass() – Set the class that is used as notification.

Synopsis

require_once 'Event/Dispatcher.php';

bool Event_Dispatcher::setNotificationClass ( string $class )

Description

Set the name of the class that will be used as a notification object when post() is called.

You may call this method on an object to change it for a single dispatcher or statically, to set the default for all dispatchers that will be created.

Parameter

  • string $class

    Name of the class that is used as a notification container when the post() method is called. Make sure the class is loaded before using it as notification class.

Return value

This method always returns true.

Note

This function can be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::removeObserver | PEAR Manual | Event_Dispatcher::post


Event_Dispatcher::post

Event_Dispatcher::post

Event_Dispatcher::post() – Post a notification.

Synopsis

require_once 'Event/Dispatcher.php';

object Event_Notification Event_Dispatcher::post ( object &$object , string $nName , mixed $info = array() , bool $pending = true , bool $bubble = true )

Description

Post a new notification to all observers.

Parameter

  • object &$object

    Reference to the object that posts the notification (the sender). May be used to filter notifications in the callbacks.

  • string $nName

    Name of the notification.

  • mixed $info = array()

    Additional information about the notification.

  • bool $pending = true

    Notifications are by default added to a pending notification list. This way, if an observer is not registered by the time they are posted, it will still be notified when it is added as an observer.

    This behaviour can be turned off in order to make sure that only the registered observers will be notified.

  • bool $bubble = true

    Notifications are by default added broadcasted to any nested dispatchers that have been added using addNestedDispatcher().

    This behaviour can be turned off in order to make sure that only the observers added the posting dispatcher will be notified. This allows you to differentiate between global and local notifications.

Return value

object Event_Notification The notification object.

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::setNotificationClass | PEAR Manual | Event_Dispatcher::addNestedDispatcher


Event_Dispatcher::addNestedDispatcher

Event_Dispatcher::addNestedDispatcher

Event_Dispatcher::addNestedDispatcher() – Add a nested dispatcher.

Synopsis

require_once 'Event/Dispatcher.php';

void Event_Dispatcher::addNestedDispatcher ( object Event_Dispatcher &$dispatcher )

Description

Adds a nested dispatcher to the dispatcher.

Nested dispatchers allow you to create event bubbling like it is implemented in Javascript. After an event has been posted to all observers of the dispatcher, it will be broadcasted to all nested dispatchers.

If you have one dispatcher that dispatches events of a component in your framework and one dispatcher that dispatches global events that are triggered by the framework itself it could make sense that you nest these dispatchers, so that events posted by the component dispatcher will also be broadcasted to the global dispatcher.

Parameter

  • object Event_Dispatcher &$dispatcher

    Dispatcher that should be added as a nested dispatcher to the current dispatcher.

Return value

void

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::post | PEAR Manual | Event_Dispatcher::removeNestedDispatcher


Event_Dispatcher::removeNestedDispatcher

Event_Dispatcher::removeNestedDispatcher

Event_Dispatcher::removeNestedDispatcher() – Remove a nested dispatcher.

Synopsis

require_once 'Event/Dispatcher.php';

boolean Event_Dispatcher::removeNestedDispatcher ( object Event_Dispatcher &$dispatcher )

Description

Removes a nested dispatcher from the dispatcher.

To remove a dispatcher from the list of nested dispatcher, just pass the same object to removeNestedDispatcher().

Parameter

  • object Event_Dispatcher &$dispatcher

    Dispatcher that should be removed from the list of nested dispatchers.

Return value

boolean TRUE if the dispatcher could be removed, FALSE otherwise.

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Dispatcher::addNestedDispatcher | PEAR Manual | Event_Notification


Event_Notification

Event_Notification

Event_Notification – Container class for notifications.

Description

The Event_Notification class acts as a container for event information. It provides some setters and getters to access the contained information.

If you need to store additional information about the events or provide additional features, you may change the class that is used by Event_Dispatcher, but it is recommended to extend Event_Notification.

Prev | Event_Dispatcher | Next
Event_Dispatcher::removeNestedDispatcher | PEAR Manual | Event_Notification::Event_Notification


Event_Notification::Event_Notification

Event_Notification::Event_Notification

Event_Notification::Event_Notification() – Create a new notification object.

Synopsis

require_once 'Event/Notification.php';

object Event_Notification Event_Notification::Event_Notifcation ( object &$object , string $nName , mixed $info = array() )

Description

Constructor of the Event_Notification class.

In most cases, you will not need to create the notification objects yourself, as this is done automatically by the Event_Dispatcher::post() method..

Parameter

  • object &$object

    Reference to the object that posts the notification (the sender). May be used to filter notifications in the callbacks.

  • string $nName

    Name of the notification.

  • mixed $info = array()

    Additional information about the notification.

Return value

string name of the notification

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification | PEAR Manual | Event_Notification::getNotificationName


Event_Notification::getNotificationName

Event_Notification::getNotificationName

Event_Notification::getNotificationName() – Get the name of the notification.

Synopsis

require_once 'Event/Notification.php';

string Event_Notification::getNotificationName ( )

Description

Get the name of the notification.

Return value

string name of the notification

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification::Event_Notification | PEAR Manual | Event_Notification::getNotificationObject


Event_Notification::getNotificationObject

Event_Notification::getNotificationObject

Event_Notification::getNotificationObject() – Get the object that sent the notification.

Synopsis

require_once 'Event/Notification.php';

object &Event_Notification::getNotificationObject ( )

Description

Get a reference to the object that sent the notification.

Return value

object sender of the notification

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification::getNotificationName | PEAR Manual | Event_Notification::getNotificationInfo


Event_Notification::getNotificationInfo

Event_Notification::getNotificationInfo

Event_Notification::getNotificationInfo() – Get additional information from the notification.

Synopsis

require_once 'Event/Notification.php';

mixed Event_Notification::getNotificationInfo ( )

Description

Get additional information that has been stored in the notification.

Return value

mixed additional information.

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification::getNotificationObject | PEAR Manual | Event_Notification::getNotificationCount


Event_Notification::getNotificationCount

Event_Notification::getNotificationCount

Event_Notification::getNotificationCount() – Get number of observers notified.

Synopsis

require_once 'Event/Notification.php';

int Event_Notification::getNotificationCount ( )

Description

Retrieves the amount of observers that have been notified by the notification.

Return value

int number of observers notified.

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification::getNotificationInfo | PEAR Manual | Event_Notification::cancelNotification


Event_Notification::cancelNotification

Event_Notification::cancelNotification

Event_Notification::cancelNotification() – Cancel the notification.

Synopsis

require_once 'Event/Notification.php';

void Event_Notification::cancelNotification ( )

Description

Cancels the notification.

If a notification is cancelled, no more observers will be notified by this notification.

Return value

void

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification::getNotificationCount | PEAR Manual | Event_Notification::isNotificationCancelled


Event_Notification::isNotificationCancelled

Event_Notification::isNotificationCancelled

Event_Notification::isNotificationCancelled() – Check, whether notification has been cancelled.

Synopsis

require_once 'Event/Notification.php';

bool Event_Notification::isNotificationCancelled ( )

Description

Checks, whether the notification has been cancelled.

Return value

bool TRUE if the notification has been cancelled, FALSE otherwise.

Note

This function can not be called statically.

Prev | Event_Dispatcher | Next
Event_Notification::cancelNotification | PEAR Manual | File Formats


File Formats

File Formats

Provides Packages for working with different file formats.

Table of Contents
  • Contact_Vcard
  • Contact_Vcard_Build
  • Contact_Vcard_Parse
  • File_Archive
  • File_Cabinet
  • File_DICOM
  • File_Fortune
  • File_Fstab
  • File_MARC
  • File_Passwd
  • MP3_Id
  • OpenDocument
  • Spreadsheet_Excel_Writer
Prev | PEAR Packages | Next
Event_Notification::isNotificationCancelled | PEAR Manual | Contact_Vcard


Contact_Vcard

Contact_Vcard

Parse and create vCards.

Table of Contents
  • Contact_VCard -- About the classes
  • Components -- Data stored in a vCard
  • Lines -- vCards internally
  • Projects -- Other vCard projects
Prev | File Formats | Next
File Formats | PEAR Manual | Contact_VCard


Contact_VCard

Contact_VCard

Contact_VCard – About the classes

Description

The Contact_Vcard classes for PHP allow you to parse and build vCards that match the IMC standards.

A vCard is a plain text file that contains an "electronic business card" of contact information suitable for including in an address book. The vCard format is a standardized way of trading personal and organizational contact information.

For a full overview of the vCard 3.0 specification, refer to Internet Engineering Task Force RFC 2426.

For a full overview of the vCard 2.1 specification (version 2.1), refer to the Internet Mail Consortium Product Developer Information web page.

Prev | Contact_Vcard | Next
Contact_Vcard | PEAR Manual | Components


Components

Components

Components – Data stored in a vCard

Description

These are some, but not all, of the components of a vCard file:

  • N: The name of the person or organization represented by the vCard, in a structured format: family name, given name, additional (middle) names, any honorific prefixes (Mr., Dr., Miss, etc), and any honorific suffixes (Jr., III, Ph.D., etc).

  • ADR: Physical address. There may be one or more addresses in a vCard; one for home, one for work, one for deliveries, and so on. The ADR element has structured components for p.o. box, extended information, street, city/locality, state/region, postal code, and country.

  • TEL: Telephone. There may be one or more telephone numbers in a vCard; one for home, one for work, one for fax, and so on. The TEL element has a single text value indicating the phone number.

  • EMAIL: Email address. There may be one or more email addresses in a vCard; one for home, one for work, and so on. The EMAIL element has a single text value indicating the email address.

  • URL: One URL associated with this vCard; e.g., a personal or organizational home page.

  • ORG: The organization in which this vCard is a part. There may be one or more suborgnizations as well.

  • TITLE: A single job title.

  • ROLE: A single, longer description of the job role. Whereas TITLE might be "Senior VP Of Custodial Enforcement" the ROLE might be "Sweep floors, empty trash, etc."

  • CATEGORIES: The category or categories of this vCard: Personal, Business, Family, and so on.

  • BDAY: Birthday in yyyy-mm-dd format. It might also have additional time and timezone information.

  • PHOTO, LOGO, KEY, SOUND: Respectively, a binary-encoded file for a personal photo, corporate logo, encryption key, or name-pronounciation sound associated with the vCard. The information may also be a URI link to a binary file.

  • NOTE: Any other arbitrary information you might want to keep with the vCard.

Prev | Contact_Vcard | Next
Contact_VCard | PEAR Manual | Lines


Lines

Lines

Lines – vCards internally

Description

Each line in a vCard is a separate component of the vCard. A component line consists of three things:

  • the component type-defnition (N, ADR, TEL, etc);

  • optionally, parameters for the component, such as whether or not the data is binary-encoded, or the type of data (home/work/preferred/etc), and so on; and

  • the component value (which may be a single text value, repeated text values, or a structured text value).

For example, consider the following component lines:

ADR;TYPE=WORK,PREF:;;123 Main;Beverly Hills;CA;90210;US
EMAIL;TYPE=HOME;TYPE=INTERNET:nobody@example.com
CATEGORIES:Personal,Business,Family
PHOTO;TYPE=JPEG;VALUE=URI:http://example.com/photo.jpg

Component line 1 has an ADR type-definition (meaning a delivery address). It has a TYPE parameter of WORK and PREF, indicating that this a work address and is the preferred address for deliveries. Finally, the value of the component is a structured text value. Structured text value parts are delimited by semicolons; in the case of ADR components, the structured value parts are p.o. box, extended address, street address, city/locality, state/region, zip/postal code, and country.

Component line 2 has an EMAIL type-definition (meaning an email address). It has a TYPE parameter of HOME and INTERNET (meaning an internet email address for home). The component value is a single text value indicating the email address.

Component line 3 has a CATEGORIES type-definition (meaning the general categories of of this vCard). There are no parameters for this component. The component value is a repeating-text value. Repeated text values a delimited by commas.

Component line 4 has a PHOTO type-definition (meaning a personal photograph). The parameters indicate that the photo TYPE is JPEG (giving a hint to vCard decoders how to handle the PHOTO value) and that the component VALUE will be a URI (that is, a link to an external photo file). Finally, the component value is a single text value, revealing in this case the URI of the photo.

Prev | Contact_Vcard | Next
Components | PEAR Manual | Projects


Projects

Projects

Projects – Other vCard projects

Description

Frank Hellwig has a 2.1/3.0 parser and address-book page generator. See his site at vcardphp.sf.net.

Kai Blankenhorn has a 2.1 card generator (not a parser). See his work at www.bitfolge.de/?s=phpvcard.

Flaimo has a vCard generator, too, at flaimo.com/php_scripts.php (scroll down past the iCalendar stuff).

HORDE has a vCard data element in their application framework, but I don't quite see how to use it outside that framework. The doc pages for it are at http://dev.horde.org/api/horde/dev-doxygen/html/classData__vcard.html .

Of course, you can always search for more vCard stuff under PHP, too: http://www.google.com/search?q=vcard+php.

Prev | Contact_Vcard | Next
Lines | PEAR Manual | Contact_Vcard_Build


Contact_Vcard_Build

Contact_Vcard_Build

Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Please read About Contact_Vcard first.

Table of Contents
  • Introduction -- Build (create) and fetch vCard 2.1 and 3.0 text blocks.
  • Usage -- How to use Contact_VCard_Build
Prev | File Formats | Next
Projects | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Contact_Vcard_Build Description

Allows you to programmatically create a vCard, version 2.1 or 3.0, and fetch the vCard text.

Quick Instructions

  • Download and un-compress Contact_Vcard_Build from the PEAR archive.

  • Include Contact_Vcard_Build.php in your PHP script.

  • Instantiate a new Contact_Vcard_Build object (by default, the vCard version is 3.0, but 2.1 vCards are also supported).

  • Set or add values and parameters that you want in the vCard.

  • Fetch the completed vCard, then use print_r() to view the results.

Example code:

<?php

    // include the class file
    require_once 'Contact/Vcard/Build.php';

    // instantiate a builder object
    // (defaults to version 3.0)
    $vcard = new Contact_Vcard_Build();

    // set a formatted name
    $vcard->setFormattedName('Bolivar Shagnasty');

    // set the structured name parts
    $vcard->setName('Shagnasty', 'Bolivar', 'Odysseus',
        'Mr.', 'III');

    // add a work email.  note that we add the value
    // first and the param after -- Contact_Vcard_Build
    // is smart enough to add the param in the correct
    // place.
    $vcard->addEmail('boshag@example.com');
    $vcard->addParam('TYPE', 'WORK');

    // add a home/preferred email
    $vcard->addEmail('bolivar@example.net');
    $vcard->addParam('TYPE', 'HOME');
    $vcard->addParam('TYPE', 'PREF');

    // add a work address
    $vcard->addAddress('POB 101', 'Suite 202', '123 Main',
        'Beverly Hills', 'CA', '90210', 'US');
    $vcard->addParam('TYPE', 'WORK');

    // get back the vCard and print it
    $text = $vcard->fetch();
    echo '<pre>';
    print_r($text);
    echo '</pre>';
?>

Differences Between vCard 2.1 and vCard 3.0

The 2.1 specification uses CRLF to terminate lines (\r\n). It allows the following components and parameters:

  • Parameters:

    • TYPE of DOM, INTL, POSTAL, PARCEL, HOME, WORK, PREF, VOICE, FAX, MSG, CELL, PAGER, BBS, MODEM, CAR, ISDN, VIDEO, AOL, APPLELINK, ATTMAIL, CIS, EWORLD, INTERNET, IBMMAIL, MCIMAIL, POWERSHARE, PRODIGY, TLX, X400, GIF, CGM, WMF, BMP, MET, PMB, DIB, PICT, TIFF, PDF, PS, JPEG, QTIME, MPEG, MPEG2, AVI, WAVE, AIFF, PCM, X509, or PGP.

    • ENCODING of 7BIT, 8BIT, BASE64, QUOTED-PRINTABLE

    • VALUE of INLINE, CONTENT-ID, CID, URL, VCARD

    • CHARSET of any ISO charset specification.

    • LANGUAGE is very lenient, basically anything so long as it uses only the characters a-z, A-Z, 0-9, and dash (-).

  • Components and methods

    • VERSION (setVersion())

    • FN (setFormattedName())

    • N (setName())

    • PHOTO (setPhoto())

    • BDAY (setBirthday())

    • ADR (addAddress())

    • LABEL (addLabel())

    • TEL (addTelephone())

    • EMAIL (addEmail())

    • MAILER (setMailer())

    • TZ (setTZ())

    • GEO (setGeo())

    • TITLE (setTitle())

    • ROLE (setRole())

    • LOGO (setLogo())

    • AGENT (setAgent())

    • ORG (addOrganization())

    • NOTE (setNote())

    • REV (setRevision())

    • SOUND (setSound())

    • URL (setURL())

    • KEY (setKey())

The 3.0 specification uses LF to terminate lines (\n). It allows the following components and parameters:

  • Parameters:

    • TYPE of any of the 2.1 TYPE values, or any other value so long as it uses only the characters a-z, A-Z, 0-9, and dash (-).

    • ENCODING of 8BIT and B ("binary").

    • VALUE of BINARY, PHONE-NUMBER, TEXT, URI, UTC-OFFSET, or VCARD.

  • Components and Methods:

    • VERSION (setVersion())

    • FN (setFormattedName())

    • N (setName())

    • NAME (setSourceName())

    • SOURCE (setSource())

    • NICKNAME (addNickname())

    • PHOTO (setPhoto())

    • BDAY (setBirthday())

    • ADR (addAddress())

    • LABEL (addLabel())

    • TEL (addTelephone())

    • EMAIL (addEmail())

    • MAILER (setMailer())

    • TZ (setTZ())

    • GEO (setGeo())

    • TITLE (setTitle())

    • ROLE (setRole())

    • LOGO (setLogo())

    • AGENT (setAgent())

    • ORG (addOrganization())

    • CATEGORIES (addCategories())

    • NOTE (setNote())

    • PRODID (setProductID())

    • REV (setRevision())

    • SORT-STRING (setSortString())

    • SOUND (setSound())

    • UID (setUniqueID())

    • URL (setURL())

    • CLASS (setClass())

    • KEY (setKey())

Prev | Contact_Vcard_Build | Next
Contact_Vcard_Build | PEAR Manual | Usage


Usage

Usage

Usage – How to use Contact_VCard_Build

Description

The basic use of Contact_Vcard_Build is straightforward: instantiate a builder object, add values and parameters, then fetch the resulting vCard.

Instantiation

To create an instance of a Contact_Vcard_Build ("builder") object, include the class file and issue a new directive:

<?php
    require_once 'Contact/Vcard/Build.php';
    $vcard = new Contact_Vcard_Build();
?>

By default, this creates a builder object that will allow you to fetch a version 3.0 vCard. If you want to build a version 2.1 vCard, pass '2.1' as the only constructor argument:

<?php
    $vcard = new Contact_Vcard_Build('2.1');
?>

How To Set A Component Value

There are two ways to set the value of a component: use the method specifically for the component you want to add, or use the generic setValue() and addValue() methods. While the generic methods allow you direct control over every individual component, iteration, structured part, and value repetition, the component-specific methods are often easier to use.

Note: You must set the FN (formatted name) and N (personal name) components; these are required by both 2.1 and 3.0 version vCards.

For example, if you want to add two ADR components to the vCard, you can do it with the ADR-specific method...

<?php
    // add first address iteration
    $vcard->addAddress($pobox0, $extend0, $street0, $city0,
        $state0, $zip0, $country0);

    // add second address iteration
    $vcard->addAddress($pobox1, $extend1, $street1, $city1,
        $state1, $zip1, $country1);
?>

...or you can use the generic methods:

<?php
    // add first address (iteration = 0)
    $vcard->addValue('ADR', 0, VCARD_ADR_POB,      $pobox0);
    $vcard->addValue('ADR', 0, VCARD_ADR_EXTEND,   $extend0);
    $vcard->addValue('ADR', 0, VCARD_ADR_STREET,   $street0);
    $vcard->addValue('ADR', 0, VCARD_ADR_LOCALITY, $city0);
    $vcard->addValue('ADR', 0, VCARD_ADR_REGION,   $state0);
    $vcard->addValue('ADR', 0, VCARD_ADR_POSTCODE, $zip0);
    $vcard->addValue('ADR', 0, VCARD_ADR_COUNTRY,  $country0);

    // add second address (iteration = 1)
    $vcard->addValue('ADR', 1, VCARD_ADR_POB,      $pobox1);
    $vcard->addValue('ADR', 1, VCARD_ADR_EXTEND,   $extend1);
    $vcard->addValue('ADR', 1, VCARD_ADR_STREET,   $street1);
    $vcard->addValue('ADR', 1, VCARD_ADR_LOCALITY, $city1);
    $vcard->addValue('ADR', 1, VCARD_ADR_REGION,   $state1);
    $vcard->addValue('ADR', 1, VCARD_ADR_POSTCODE, $zip1);
    $vcard->addValue('ADR', 1, VCARD_ADR_COUNTRY,  $country1);
?>

Please see the Contact_Vcard_Build.php inline comments for descriptions of how to use each component-specific method.

How To Set A Parameter Value

There is only one way to add a parameter: use the addParam() method. Unlike with adding values, there are no component-specifc methods to add parameters.

In general, you should add the parameters of a component immediately after you add the complete value of a component, because the builder object keeps track of what was the last component value added. (This is why there are no component-specific add-parameter methods.)

For example, we can set the params for the ADR components as in the above code:

<?php
    // add first address iteration
    $vcard->addAddress($pobox0, $extend0, $street0, $city0,
        $state0, $zip0, $country0);

    // add parameters to the first address
    $vcard->addParam('TYPE', 'HOME');
    $vcard->addParam('TYPE', 'PREF');

    // add second address iteration
    $vcard->addAddress($pobox1, $extend1, $street1, $city1,
        $state1, $zip1, $country1);

    // add parameters to the second address
    $vcard->addParam('TYPE', 'WORK');
?>

Thus, the first address will have TYPE=HOME,PREF and the second will have TYPE=WORK as their parameters.

Alternatively, you can add parameters directly using the same addParam() method, with some additional arguments:

<?php
    // add parameters to the first address iteration
    // (component = ADR, iteration = 0)
    $vcard->addParam('TYPE', 'HOME', 'ADR', 0);
    $vcard->addParam('TYPE', 'PREF', 'ADR', 0);

    // add parameters to the second address iteration
    // (component = ADR, iteration = 1)
    $vcard->addParam('TYPE', 'WORK', 'ADR', 1);
?>

This does the same thing as the earlier addParam() code.

Note: Although the version 2.1 specification optionally allows parameter values to be indicated without without specified types (i.e, "HOME" instead of "TYPE=HOME") the Contact_Vcard_Build class is not so lenient. With Contact_Vcard_Builder, you must set both the parameter kind and parameter value.

How To Fetch A vCard

After you have added all the values and parameters that you want, you get back the vCard using the fetch() method. This will return the components, parameters, and values (including BEGIN:VCARD and END:VCARD) in proper format for the vCard version.

<?php
    $text = $vcard->fetch();
?>
Note: If you set values and parameters for components that are not part of the selected vCard version, they will not be included in the fetched vCard text.
Note: You must have set the FN (formatted name) and N (personal name) components, or the fetch() method will return a PEAR_Error object. The FN and N components are required by both 2.1 and 3.0 version vCards.
Prev | Contact_Vcard_Build | Next
Introduction | PEAR Manual | Contact_Vcard_Parse


Contact_Vcard_Parse

Contact_Vcard_Parse

Parse vCard 2.1 and 3.0 files.

Please read About Contact_Vcard first.

Table of Contents
  • Introduction -- Build (create) and fetch vCard 2.1 and 3.0 text blocks.
  • How Data Is Returned -- Getting data from the file
  • Known issues -- Problems you might encounter
Prev | File Formats | Next
Usage | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Description

Here are some quick instructions for the impatient. :-)

  • Download and un-compress Contact_Vcard_Parse from the PEAR archive.

  • Include Contact_Vcard_Parse.php in your PHP script.

  • Instantiate a new Contact_Vcard_Parse object.

  • Use the fromFile() method to parse any file which may have one or more vCards in it; try the sample.vcf file for a start. Contact_Vcard_Parse should work with both 2.1 and 3.0 vCard files.

  • Use print_r() to view the resulting array of data from the parsed file.

  • Do what you want with the data, such as insert into a table.

Example code

<?php
    // include the class file
    require_once 'Contact_Vcard_Parse.php';

    // instantiate a parser object
    $parse = new Contact_Vcard_Parse();

    // parse a vCard file and store the data
    // in $cardinfo
    $cardinfo = $parse->fromFile('sample.vcf');

    // view the card info array
    echo '<pre>';
    print_r($cardinfo);
    echo '</pre>';

?>
Prev | Contact_Vcard_Parse | Next
Contact_Vcard_Parse | PEAR Manual | How Data Is Returned


How Data Is Returned

How Data Is Returned

How Data Is Returned – Getting data from the file

Description

Contact_Vcard_Parse reads a file or block of text for vCard data, then converts that data into a series of nested arrays. I used to present a detailed prose explanation of the array, but I think it's easier to just give a generic outline of the array:

$parse_result = array (
    [int_cardnumber] => array (
        [string_datatype] => array (
            ["param"] => array (
                [string_paramname] => array (
                    [int_repetitionnumber] => string_paramtext
                )
            )
            ["value"] => array (
                [int_partnumber] => array (
                    [int_repetitionnumber] => string_valuetext
                )
            )
        )
    )
)

By way of example, let's take a look at the vCard of my friend Bolivar Shagnasty.

BEGIN:VCARD
VERSION:3.0
N:Shagnasty;Bolivar;Odysseus;Mr.;III,B.S.
FN:Bolivar Shagnasty
ADR;TYPE=HOME,WORK:;;123 Main,Apartment 101;Beverly Hills;CA;90210
EMAIL;TYPE=HOME;TYPE=WORK:boshag@example.com
EMAIL;TYPE=PREF:boshag@ciaweb.net
END:VCARD

This is a pretty simple vCard: my buddy Bolivar's name, one address (looks like Bolivar works from home), two email addresses (one for work and home, and one as his "preferred" address). This simple vCard, when it gets parsed, looks like this:

(
    [0] => Array
        (
            [VERSION] => Array
                (
                    [0] => Array
                        (
                            [param] => Array
                                (
                                )

                            [value] => Array
                                (
                                    [0] => Array
                                        (
                                            [0] => 3.0
                                        )

                                )

                        )

                )

            [N] => Array
                (
                    [0] => Array
                        (
                            [param] => Array
                                (
                                )

                            [value] => Array
                                (
                                    [0] => Array // family
                                        (
                                            [0] => Shagnasty
                                        )

                                    [1] => Array // first
                                        (
                                            [0] => Bolivar
                                        )

                                    [2] => Array // additional or middle
                                        (
                                            [0] => Odysseus
                                        )

                                    [3] => Array // honorifix prefix
                                        (
                                            [0] => Mr.
                                        )

                                    [4] => Array // honorifix suffix
                                        (
                                            [0] => III
                                            [1] => B.S.
                                        )

                                )

                        )

                )

            [FN] => Array
                (
                    [0] => Array
                        (
                            [param] => Array
                                (
                                )

                            [value] => Array
                                (
                                    [0] => Array
                                        (
                                            [0] => Bolivar Shagnasty
                                        )

                                )

                        )

                )

            [ADR] => Array
                (
                    [0] => Array
                        (
                            [param] => Array
                                (
                                    [TYPE] => Array
                                        (
                                            [0] => HOME
                                            [1] => WORK
                                        )

                                )

                            [value] => Array
                                (
                                    [0] => Array // p.o. box
                                        (
                                            [0] =>
                                        )

                                    [1] => Array // extended
                                        (
                                            [0] =>
                                        )

                                    [2] => Array // street
                                        (
                                            [0] => 123 Main
                                            [1] => Apartment 101
                                        )

                                    [3] => Array // locality or city
                                        (
                                            [0] => Beverly Hills
                                        )

                                    [4] => Array // region, state, or province
                                        (
                                            [0] => CA
                                        )

                                    [5] => Array // postal code
                                        (
                                            [0] => 90210
                                        )

                                    [6] => Array // country
                                        (
                                            [0] =>
                                        )

                                )

                        )

                )

            [EMAIL] => Array
                (
                    [0] => Array
                        (
                            [param] => Array
                                (
                                    [TYPE] => Array
                                        (
                                            [0] => HOME
                                            [1] => WORK
                                        )

                                )

                            [value] => Array
                                (
                                    [0] => Array
                                        (
                                            [0] => boshag@example.com
                                        )

                                )

                        )

                    [1] => Array
                        (
                            [param] => Array
                                (
                                    [TYPE] => Array
                                        (
                                            [0] => PREF
                                        )

                                )

                            [value] => Array
                                (
                                    [0] => Array
                                        (
                                            [0] => boshag@ciaweb.net
                                        )

                                )

                        )

                )

        )

)

Sweet Jebus! That's an ugly mess. But it retains every bit of info about the vCard so you can do what you like with it. It keeps (separately) every element and component so you can see the underlying structure of the vCard.

Yes, I know it's a deeply-nested array set, and is ugly and probably inefficient. The problem (or genius?) of the vCard format is that just about every part of a vCard element can have multiple values. While this makes the vCard format very flexible, it makes it a little difficult to parse and interpret in a simple fashion. The easiest way I could think of was a series of nested arrays. An object-oriented approach might be better, but even then you're going to have nested objects or nested arrays within the vCard object to represent multiple values of a vCard data element.

Prev | Contact_Vcard_Parse | Next
Introduction | PEAR Manual | Known issues


Known issues

Known issues

Known issues – Problems you might encounter

Description

When I wrote this parser, my primary goal was to be able to read vCard files produced by the Mac OS X Address Book application. However, it looks like Address Book puts some weird character after every single text character in the output, in addition to some weird line endings. If you want to use .vcf files generated by the Mac OS X Address Book, you might need to massage the file in BBEdit or TextWrangler first; turn on "show invisibles" to see the offending characters, then do a search-and-replace to delete them all at once (or perhaps "Zap Gremlins").

UPDATE: David Weingart writes, "That's probably Unicode. In my extremely limited testing, it looks like in some cases you get plain vanilla ISO Latin 1, but if there are any high ascii characters in the entry, they export UTF 16 (double-byte) Unicode." Thanks, David. (Contact_Vcard_Parse does not do Unicode at this time.)

Contact_Vcard_Parse does not validate the information or formatting in the vCard (although it does decode quoted-printable text). In the spirit of "be lenient in what you accept and strict in what you produce", Contact_Vcard_Parse should be able to read just about anything from a vCard file, but it's up to you as the programmer to make sense of the data.

Contact_Vcard_Parse should work on file with any kind of line endings (Mac \r, Unix \n, and DOS \r\n) automatically. It also unfolds lines automatically, so data elements spread across multiple lines should come through OK.

If you discover a new bug or want to contribute code to Contact_Vcard_Parse, contact Paul M. Jones at pjones at ciaweb dot net; the subject line should start with [VCARD].

Prev | Contact_Vcard_Parse | Next
How Data Is Returned | PEAR Manual | File_Archive


File_Archive

File_Archive

This package will let you manipulate easily tar, gz, bz2, tgz, tbz, zip, ar and deb files.

Table of Contents
  • Examples -- Some simple usage examples
  • Dynamic generation of archive files for a gallery -- How to use File_Archive for a photo/video gallery
  • Readers -- Getting files into an archive
  • Writers -- Saving archives
  • Predicates -- Filters
  • Archive modification -- Remove and append files
  • Cache -- Caching compressed files
Prev | File Formats | Next
Known issues | PEAR Manual | Examples


Examples

Examples

Examples – Some simple usage examples

Extract a tar archive to a sub directory

Here we simply take a tar archive called archive.tar and extract its contents to the folder

<?php
require_once "File/Archive.php";

File_Archive::extract('archive.tar/', 'output');
?>

Send a zip archive containing the content of a tar file to the standard output

<?php
require_once "File/Archive.php";

File_Archive::extract(
    //The content of archive.tar appears in the root folder (default argument)
    'archive.tar/',

    //And is written to ...
    File_Archive::toArchive(       // ... a zip archive
        'archive.zip',             // called archive.zip
        File_Archive::toOutput()   // that will be sent to the standard output
    )
);
?>

Extracting a file from an archive

Use extract() to get files out of an archive. When specifying the file to extract, make sure to use the archive name as first folder.

<?php
require_once "File/Archive.php";

File_Archive::extract(
    'archive.tar/inner.tgz/file.txt',
    File_Archive::toOutput()
);
?>
Prev | File_Archive | Next
File_Archive | PEAR Manual | Dynamic generation of archive files for a gallery


Dynamic generation of archive files for a gallery

Dynamic generation of archive files for a gallery

Dynamic generation of archive files for a gallery – How to use File_Archive for a photo/video gallery

One possible use case of File_Archive is to dynamically generate archives that contain pictures or videos from a gallery.

The choice of the file format is important if you want an efficient generation. Let's see what are the possibilities:

  1. Tar
  2. Tgz, Tbz
  3. Zip
Tar

Pros: Generation very efficient, constant memory usage, no need to cache

Cons: No compression (but anyway images or video can hardly be compressed), not as widely used as Zip

Tgz, Tbz

Pros: Very high compression ratio, constant memory usage

Cons: Can't be cached, needs a lot of CPU at each generation

Zip

Pros: Intermediate result can be cached, compressed, you can choose the compression level, widely used

Cons: Compression ratio lower than for Tgz/Tbz

We will focus on Tar and Zip generation, Tgz and Tbz are too CPU expensive for an "on the fly" archive generation.

Tar generation

<?php
require_once "File/Archive.php";

// $files is an array of path to the files that must be added to the archive
File_Archive::extract(
    $files,
    File_Archive::toArchive(
        'myGallery.tar',
        File_Archive::toOutput()
    )
);
?>

Zip generation

The main advantages of the Zip generation is that it is not very expensive (due to the ability to cache the result), and widely used. I think 2 viable options are to generate uncompressed Zip archives (since you don't reduce a lot the size of picture and video files by compressing them) or to generate compressed Zip archive using a cache system.

On the fly creation of an uncompressed ZIP archive

<?php
require_once "File/Archive.php";

File_Archive::setOption('zipCompressionLevel', 0);

// $files is an array of path to the files that must be added to the archive
File_Archive::extract(
    $files,
    File_Archive::toArchive(
        'myGallery.zip',
        File_Archive::toOutput()
    )
);
?>

On the fly creation of a compressed ZIP archive with a cache

<?php
require_once "File/Archive.php";
require_once "Cache/Lite.php";

// See the documentation of cache lite for the meaning of the $options array
// fileNameProtection must be left to the default true value
// automaticSerialization is not required and should be left to false
$options = array('cacheDir' => 'tmp');

File_Archive::setOption('cache', new Cache_Lite($options));
File_Archive::setOption('zipCompressionLevel', 9);

// $files is an array of path to the files that must be added to the archive
File_Archive::extract(
    $files,
    File_Archive::toArchive(
        'myGallery.zip',
        File_Archive::toOutput()
    )
);
?>

Putting it all together

Since generating a zip or a tar archive is pretty much the same code, you can write a simple code that lets the user choose what format he wants. The following code is taken from a code I really use in my gallery.

Custom archive

<?php
$allowedFormats = array('tar', 'zip');

if (!in_array($_GET['type'], $allowedFormats)) {
    die('Type ' . htmlspecialchars($_GET['type']) . ' is either unknown or not allowed');
}

require_once "File/Archive.php";

File_Archive::setOption('zipCompressionLevel', 0);

/**
 * I skipped the generation of the $files array since it really
 * depends on you gallery and what files the user requires
 */

File_Archive::extract(
    $files,
    File_Archive::toArchive(
        'myGallery.' . $_GET['type'],
        File_Archive::toOutput()
    )
);
?>
Prev | File_Archive | Next
Examples | PEAR Manual | Readers


Readers

Readers

Readers – Getting files into an archive

Introduction

A reader is an object that represents a list of files and directories. Those files can be generated dynamically or exist physically. For example, there is a reader class for a directory, or for each archive format handled by File_Archive, and they all have the same interface.

To create a reader, you will have to use the File_Archive factory. The important function is the read() function:

read ( string $url , string $symbolic = null , integer $uncompression = 0 , integer $directoryDepth = -0 )

In this function the URL will represent what you want to read.

Generation of sources

<?php
require_once "File/Archive.php";

/*
To read a directory, just give the directory name
By default, the directory and all the subdirectories
will be parsed (see $directoryDepth to change this)
*/
$source = File_Archive::read("Path/to/dir");

/*
To read from one single file,
simply provide the name of the file
*/
$source = File_Archive::read("Path/to/dir/file.txt");

/*
An archive will be considered as a directory if a slash follows
This example reads the directory and all the subdirectories of inner/dir
contained in archive Path/to/dir/archive.tar
This reads all the .txt files in the inner directory of the archive.tar
*/
$source = File_Archive::read("Path/to/dir/archive.tar/inner/*.txt");

/*
If you want to uncompress the archive (read all its content)
Note: if you ommit the trailing /, the archive will be treated as a single file
*/
$source = File_Archive::read("Path/to/dir/archive.tar/");
?>

The symbolic attribute says how the files read will be displayed for future use. If $URL is a directory, $URL will be replaced by $symbolic (or '' if $symbolic is null). So, in our first example, the files will be displayed as if the current directory was 'Path/to/dir': Since by default $symbolic is empty, Path/to/dir will be simply removed from the file. You may want to put Path/to/dir as $symbolic to keep the full path Path/to/dir.

If $URL is a file, then only the filename will be kept, and $symbolic will be added to it. So, in our second example, the source contains a file with symbolic name file.txt. If a symbolic name foo had been specified, the source would contain foo/file.txt.

The $uncompression parameter indicate how many files will be uncompressed while parsing the tree to files. By default the files are not uncompressed. So, if you do File_Archive::read('archive.tar/inner/dir', 'inner/dir'), and if archive.tar contains a file called archive.tar/inner/dir/file.tgz, this second archive will appear as a file and not as a directory. It won't be uncompressed because $uncompression is 0. If $uncompression is set to 1, file.tgz would appear as a directory, but the files inside this archive would not be uncompressed. If $uncompression is set to -1, all the files would be uncompressed, regardless of the depth.

Note: The compressed files that may appear in $URL are not taken into account by $uncompression variable.

The $directoryDepth parameter gives a limit to the number of directory read by the reader.

Multi readers

Using a multi reader, you can make several sources appear as one. You can create a multi reader using the File_Archive::readMulti() function.

Multi reader

<?php
//This reader contains the content of directory and archive.tar
$source = File_Archive::readMulti(
    array(
        File_Archive::read('directory'),
        File_Archive::read('archive.tar/')
    )
);
?>

Reading the content of a data reader

Any reader provides the following interface:

  • function next()

    Go to the next file in the source. Returns false when the end of the archive is reached.

  • function getFilename()

    Returns the filename of the currently selected entry in the archive.

  • function getStat()

    Returns the stat as the stat() function does. This function may not return a complete array, it may even return array().

  • function getDataFilename()

    For optimisation purposes: if the source is a physical file, this function returns the name of the file; otherwise it returns null.

  • function getData($length = -1)

    Reads some data from the source. This function will return a string which size is determined by the smallest of

    • $length if $length >= 0

    • the end of the file.

    If the end of the file is reached, the function will return null.

  • function skip($length)

    Equivalent to getData($length), but does not return any data. Depending on the data reader, this function can be far more efficient than getData().

  • function close()

    Should be called after having used the data reader (closes the file handles...). This function moves the object in the same state as it was before the first call to next(). After this call, you can iterate again on the data reader.

Listing the content of a data reader

<?php
$source->close(); //Move back to the begining of the source

while($source->next()) {
    echo $source->getFilename() . "<br/>\n";
}
?>

Functions that use readers

All File_Archive functions that take a reader as an argument also accept strings and arrays. The strings will be automatically interpreted as a reader using File_Archive::read function. The arrays will be interpreted as a multi reader.

Since the readers are passed by reference, you will have to pass a variable and not the raw string or array.

It is thus possible to rewrite the previous example like that:

Multi reader

<?php
//This reader contains the content of directory and archive.tar
File_Archive::extract(
    array(
        'directory',
        'archive.tar/'
    ),
    File_Archive::toArchive('test.zip')
);
?>
Prev | File_Archive | Next
Dynamic generation of archive files for a gallery | PEAR Manual | Writers


Writers

Writers

Writers – Saving archives

Introduction

A writer is an object that deals with data. Some writers transform data (this is the case of the archive writers), some save them to disk (for files writers), or to memory (for the memory writer)... They all implement the same interface.

You can transfer data from a reader to a writer using the File_Archive::extract function.

All the writers can be created thanks to the File_Archive factory, and more particularly the File_Archive::to* functions.

Write archives

To create a writer that will generate an archive, use the toArchive() function:

toArchive ( string $filename , &$innerWriter , $type = null , $stat = array() , $autoClose = true )

  • $filename is the name of the generated archive

  • $innerWriter is another writer in which the archive file will be written

  • $type is one of Tar, Gzip or Zip and indicates the format of compression. If not specified, the type is determined thanks to the extension of the filename.

  • $stat is an optional array to indicate stats about the archive (see the PHP stat function for the possible indexes).

  • $autoClose indicates whether the inner writer will be closed once the data are sent. It may be useful not to close the writer if you want to append some more data after writing. In general, you won't need to keep the writer open, so you should just keep the default value.

Generation of archive writers

<?php
require_once "File/Archive.php";

/* Writer to a tar file */
File_Archive::toArchive("archive.tar", $innerWriter);

/* Writer to a tar.gz file */
File_Archive::toArchive("archive.tgz", $innerWriter);

/* Writer to a zip file */
File_Archive::toArchive("archive.zip", $innerWriter);
?>

Write to files

A writer can write the files to physical files. To create such a writer, call File_Archive::toFiles();. If a directory does not exist, it will be automatically created.

Use files writer

<?php
require_once "File/Archive.php";

/* Copy a whole directory to another location */
File_Archive::extract(
    File_Archive::read('Path/to/dir', 'new/directory');
    File_Archive::toFiles()
);

/* Convert an archive to another format: tgz to zip */
File_Archive::extract(
    File_Archive::read('archive.tgz/'),

    File_Archive::toArchive(
        'archive.zip',
        File_Archive::toFiles()
    )
);
?>

Send emails

You can send emails as attachment using a mail writer available thanks to File_Archive::toMail function.

toMail ( array $to , array $headers , string $message , &$mail = null )

This function relies on the PEAR Mail and Mail_Mime libraries, and the parameters are the same as the one of these classes:

  • $to an array or a string with comma separated recipients

  • $headers will be sent to Mail_Mime and to $mail: an associative array of headers. The header name is used as key and the header value as value.

  • $message is the text version of the body of the mail. You can provide an HTML version thanks to the setHTMLBody() and addHTMLImage() of the writer. The signatures of these functions are the same as the ones of Mail_Mime.

  • $mail the way to send mail. This is an object created with the Mail::factory() function. If null, Mail::factory('mail') will be used (and the email will be sent using the PHP mail function).

<?php
require_once "File/Archive.php";

/* Send the files in the current directory (no recursion) as attachment */
File_Archive::extract(
    File_Archive::read('Path/to/dir', '', 0, 0),
    File_Archive::toMail(
        $to, // recipients
        array(
            'Subject' => 'Path/to/dir directory',
            'From'    => 'address@of.expeditor'
        ),
        'Find all the files attached' // body
    )
);
?>

Send files to the user

To send files to the remote user (i.e. write data to the standard output), you need a special writer. You can build one calling function File_Archive::toOutput().

This writer will automatically send a header forcing the download of the file.

If you don't want that, call File_Archive::toOutput(false).

Multi writers

Using a multi writer, you can write the data to two or more different locations in parallel.

A typical use is to send the file to the user at the same time as you write it to a file.

It can also be used to generate archives in different formats.

You can create a multi writer using File_Archive::toMulti($dest1, $dest2).

Multi writer

<?php
//Send a directory to the user and to a file

File_Archive::extract(
    File_Archive::read('directory'),
    File_Archive::toArchive(
        'multi.zip',
        File_Archive::toMulti(
            File_Archive::toOutput(),
            File_Archive::toFiles()
        )
    )
);
?>

Writing to a writer

It is also possible to write data directly to a writer, without using a reader. To do so, you can use the following interface implemented by any writer:

  • function newFile($URL, $stat)

    Create a new file in the writer.

    $URL is the name of the file, $stat is an array of statistics about the data (see the PHP stat() function for more information).

    The stat array may not contain all the information. The only index that must be present is index 7 (size of the data).

  • function writeData($data)

    Append the specified data to the writer. A call to newFile() must have been done previously.

  • function close()

    Close the writer, eventually flush the data, write the footer... This function must be called before the end of the file, otherwise some data may not be treated by the writer.

Dynamic creation of a zip file

<?php
require_once "File/Archive.php";

$dest = File_Archive::toArchive("foo.zip", File_Archive::toFiles());
$dest->newFile("even.txt");
for($i=0; $i<100; $i++)
    $dest->writeData((2*$i)."\n");
$dest->newFile("odd.txt");
for($i=0; $i<100; $i++)
    $dest->writeData((2*$i+1)."\n");
$dest->close();

?>
Note: If you do not specify the stat array in the newFile() function, the majority of the archives will have to buffer the data until the end of the file is reached (this is because the size of the file is usually needed to be able to write the header).
This may be a memory problem if you want to generate really large files.

Functions that use writers

All File_Archive functions that take a writer as an argument also accept strings and arrays. The strings will be automatically interpreted as a writer using File_Archive::appender() function. The arrays will be interpreted as a multi writer.

Since the writers are passed by reference, you will have to pass a variable and not the raw string or array.

It is thus possible to rewrite the previous example like that:

Multi writer

<?php
//Send a directory to the user and to a file

File_Archive::extract(
    $src = 'directory',
    File_Archive::toArchive(
        'multi.zip',
        array(
            File_Archive::toOutput(),
            File_Archive::toFiles()
        )
    )
);
?>
Prev | File_Archive | Next
Readers | PEAR Manual | Predicates


Predicates

Predicates

Predicates – Filters

Introduction

File_Archive introduces the concept of filters to be able to select the files from a source. A filter is a particular reader that you can create with the File_Archive::filter() function. This function requires you to give a predicate. You can build this predicate using the File_Archive::pred* functions.

The standard logic predicates are:

  • predTrue(): always evaluates to true

  • predFalse(): always evaluates to false

  • predAnd($p1, $p2, ...): evaluates to $p1 && $p2 && ...

  • predOr($p1, $p2, ...): evaluates to $p1 || $p2 || ...

  • predNot($p): evaluates to !$p

Some other predicats will help you filtering the files:

  • predMinSize($size): keep only the files which size is >= $size (in bytes).

  • predMinTime($time): keep only the files that have been modified after $time (unix timestamp).

  • predMaxDepth($depth): keep only the files that have a public name with less than $depth directories.

  • predExtension($list): keep only the files with a given extension. $list is an array or a comma separated string of allowed extensions.

  • predEreg($ereg): keep only the files that have a public name that matches the given regular expression.

  • predEregi($ereg): same as predEreg(), but the test is case insensitive.

  • predMIME($mimes): Select files with a certain MIME type. You can pass an array of types or a string, and use wildcards.

Filter examples

<?php
//Extract all the files that contain an 'a' in their path
// or filename from a tar archive
File_Archive::extract(
    File_Archive::filter(
        File_Archive::predEreg('a'),
        File_Archive::read(
            'archive.tar/',
            'folder'
        )
    ),
    File_Archive::toFiles()
);

//Compress a directory to a zip file, including only the files
//smaller than 1MB that have changed since last hour
File_Archive::extract(
    File_Archive::filter(
        File_Archive::predAnd(
            File_Archive::predNot(
                File_Archive::predMinSize(1024 * 1024)
            ),
            File_Archive::predMinTime(time()-3600)
        ),
        File_Archive::read('directory')
    ),
    File_Archive::toArchive(
        'directory.zip',
        File_Archive::toFiles()
    )
);
?>
Prev | File_Archive | Next
Writers | PEAR Manual | Archive modification


Archive modification

Archive modification

Archive modification – Remove and append files

Introduction

File_Archive version 1.3 introduces some new functions to edit existing archives. These functions will allow you to remove or append files to an existing archive.

Since for File_Archive, the file system is just another reader / writer, those modifications can be done on "real" archives (real files), or on nested archives (an archive inside another archive).

Remove files from an existing archive

To remove files from an archive, you'll use one of the following functions from File_Archive class:

  • remove ( &$pred , $URL )

    Removes all the files that follow a given predicate from file $URL. Note that the URL is the same as in the File_Archive::read() function. You can use nested archives.

  • removeFromSource ( &$pred , &$source , $URL = null )

    Same as remove, but use $source instead of the default file system reader. If no URL is specified, $source must be an archive, and the files will be removed from here.

  • removeDuplicates ( $URL )

    This function will remove all the doublons from the archive at $URL; only the most recent file will be kept.

    If the modification date is not specified for a file, it will be considered infinitely old.

    If two files have the same modification date, the one that has highest position in the archive (usually the one that was added to the archive at last) will be kept.

  • removeDuplicatesFromSource ( &$source , $URL = null )

    Same as removeDuplicate(), but use $source instead of the default file system reader. If no URL is specified, the duplicates will be removed from $source itself.

Note that those functions will not recursively uncompress archives.

Remove Jpg, gif and Bmp from a zip archive

<?php
require_once "File/Archive.php";

File_Archive::remove(
    File_Archive::predExtension(
        array('jpg', 'jpeg', 'bmp', 'gif')
    ),
    'archive.zip'
);
?>

Remove image files from a nested archive

<?php
require_once 'File/Archive.php';

File_Archive::remove(
    File_Archive::predMIME(
        array('image/*')
    ),
    'archive.zip/data.tgz'
);
?>

Appending files to an archive

To append files to an archive, you'll use one of the following functions from File_Archive class:

  • appender ( $URL , $unique = null , $type = null , $stat = array() )

    Allows to append to the archive specified by the URL.

    If unique is set to true, the eventual duplicates created by the insertion of new files will be automatically removed. If set to null, the default value (that you can change using File_Archive::setOption('appendRemoveDuplicates', true/false)) is used (false by default).

    If the archive does not exist, it will be created using the type specified in parameter (or looking at the extension in the URL if the type is not specified), and the stat array.

  • appenderFromSource ( &$source , $URL = null , $unique = null , $type = null , $stat = array() )

    Same as appender, but using $source instead of the default file system reader.

Both of these functions return a writer that you can use as in the previous examples, using the extract function

Add a folder to an archive

<?php
require_once "File/Archive.php";

File_Archive::extract(
    File_Archive::read('folder'),
    File_Archive::appender('archive.zip')
);
?>

Note that if you use a string instead of a writer in a function, the string will be converted using File_Archive::appender(). Thus the previous example could be rewritten to:

Add a folder to an archive

<?php
require_once "File/Archive.php";

File_Archive::extract(
    $src = 'folder',
    $dest= 'archive.zip'
);
?>
Prev | File_Archive | Next
Predicates | PEAR Manual | Cache


Cache

Cache

Cache – Caching compressed files

Introduction

File_Archive 1.4 introduce the possibility to use a cache to store intermediate result of a zip compression. It uses the Cache_Lite PEAR package to do so.

A zip file is made of compressed files, one after the others. So if you generate an archive that contains files A, B and C and then another archive that contains A and C, you will compress twice the files A and C. The use of the cache will allow to save the compressed version of files A, B and C on the first compression, to use them again in the second compression.

Usage examples

The cache can be (and should be) used if you dynamically create some zip archive that contains frequently the same files. For example, you may want to allow the user to select some images, videos or other files from your gallery and allow them to download a compressed zip archive that contains these files.

If you do so without cache, your server will answer very slowly if a lot of users ask the files. With the cache, the files will be compressed only once.

On my machine (a thinkpad T42P with default factory equipment), generating a 200MB zip archive takes around 30s of CPU without the cache, 32s of CPU with an empty cache and 2s of CPU if all the files to compress are already in cache.

How to use the cache

The cache is a Cache_Lite object. So you must have installed the package. Then all you have to do is use the File_Archive::setOption() function with the cache parameter.

Set up the cache

<?php
require_once "File/Archive.php";
require_once "Cache/Lite.php";

//Create the cache object
$cache = new Cache_Lite(
    array(
        //See the doc of Cache_Lite for its constructor parameters
    )
);

//Ask File_Archive to use the cache object we just created
File_Archive::setOption('cache', $cache);

//And then create your archives as usual
//Generate a file called archive.zip in the working folder
File_Archive::extract(
    'folderToCompress',
    'archive.zip'
);

//Send an archive to the user
File_Archive::extract(
    'folderToCompress',
    File_Archive::toArchive(
        'archive.zip',
        File_Archive::toOutput()
    )
);
?>
Prev | File_Archive | Next
Archive modification | PEAR Manual | File_Cabinet


File_Cabinet

File_Cabinet

Microsoft Cabinet file extraction using either cabextract or expand

Table of Contents
  • Introduction -- Extraction of Microsoft Cabinet files
Prev | File Formats | Next
Cache | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Extraction of Microsoft Cabinet files

Synopsis

<?php
require_once 'File/Cabinet.php';

// optional step: specify the command static property
File_Cabinet::$command = '/usr/local/bin/cabextract';

$cabinet = new File_Cabinet('cabinet.cab');

// Extract the contents of 1 file
$file_contents = $cabinet->extract('a_file.txt');

// Extract the contents of multiple files (returns an array)
$file_contents = $cabinet->extract(array('a_file.txt', 'another_file.txt'));

// Extract using a glob (returns a concatenated string)
$file_contents = $cabinet->extract('*.txt');

// Extract to a directory
$cabinet->extract('a_file.txt', '/path/to/extraction/dir');
?>
Prev | File_Cabinet | Next
File_Cabinet | PEAR Manual | File_DICOM


File_DICOM

File_DICOM

Package for reading and modifying DICOM files

Table of Contents
  • Introduction -- using File_DICOM
  • constructor File_DICOM::File_DICOM -- Constructor.
  • File_DICOM::parse -- Parse a DICOM file.
  • File_DICOM::write -- Write current contents to a DICOM file.
  • File_DICOM::getValue -- Gets the value for a DICOM element.
  • File_DICOM::setValue -- Sets the value for a DICOM element.
  • File_DICOM::dumpImage -- Dumps the contents of the image inside the DICOM file (element 0x0010 from group 0x7FE0) to a PGM (Portable Gray Map) file.
Prev | File Formats | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – using File_DICOM

What is DICOM?

File_DICOM allows reading and modifying of DICOM files. DICOM stands for Digital Imaging and COmmunications in Medicine, and is a standard for creating, storing and transfering digital images (X-rays, tomography) and related information used in medicine. This package in particular does not support the exchange/transfer of DICOM data, nor any network related functionality. More information on the DICOM standard can be found at the NEMA site.

Please be aware that any use of the information produced by this package for diagnosing purposes is strongly discouraged by the author. See here for more information.

Using it

File_DICOM can be used to accomplish two things, to retrieve data from a file (including image data), and to set new values for that data (allowing to write the modified file).

Let's see how we could show some relevant data from a DICOM file and export its image data at the same time.

Showing data

<?php
require_once('File/DICOM.php');

$dicom = new File_DICOM();
$res = $dicom->parse("test.dcm");

// check for errors
if (PEAR::isError($res)) {
    die("Error: ".$res->getMessage()."\n");
}

// show a few attributes of the DICOM file using group and element index
echo 'StudyDate : '.$dicom->getValue(0x0008, 0x0020)."\n";
echo 'Image Date : '.$dicom->getValue(0x0008, 0x0023)."\n";
echo 'Image Type : '.$dicom->getValue(0x0008, 0x0008)."\n";
echo 'Study Time : '.$dicom->getValue(0x0008, 0x0030)."\n";
echo 'Institution Name : '.$dicom->getValue(0x0008, 0x0080)."\n";
echo 'Manufacturer : '.$dicom->getValue(0x0008, 0x0070)."\n";
echo 'Manufacturer Model Name : '.$dicom->getValue(0x0008, 0x1090)."\n";
// or using element name
echo 'Patient Name : '.$dicom->getValue('PatientName')."\n";
echo 'Patient Age : '.$dicom->getValue('PatientAge')."\n";

// dump a PGM image from the file data
$res = $dicom->dumpImage('test.pgm');
if (PEAR::isError($res)) {
    die("Error: ".$res->getMessage()."\n");
}
?>
Prev | File_DICOM | Next
File_DICOM | PEAR Manual | constructor File_DICOM::File_DICOM


constructor File_DICOM::File_DICOM

constructor File_DICOM::File_DICOM

constructor File_DICOM::File_DICOM() – Constructor.

Synopsis

require_once 'File/DICOM.php';

void constructor File_DICOM::File_DICOM ( )

Description

It creates a File_DICOM object.

Note

This function can not be called statically.

Prev | File_DICOM | Next
Introduction | PEAR Manual | File_DICOM::parse


File_DICOM::parse

File_DICOM::parse

File_DICOM::parse() – Parse a DICOM file.

Synopsis

require_once 'File/DICOM.php';

mixed File_DICOM::parse ( string $infile )

Description

Parse a DICOM file and get all of its header members.

Parameter

string $infile

The DICOM file to parse

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | File_DICOM | Next
constructor File_DICOM::File_DICOM | PEAR Manual | File_DICOM::write


File_DICOM::write

File_DICOM::write

File_DICOM::write() – Write current contents to a DICOM file.

Synopsis

require_once 'File/DICOM.php';

mixed File_DICOM::write ( string $outfile = '' )

Description

This package is not documented yet.

Parameter

string $outfile

The name of the file to write. If not given it assumes the name of the file parsed. If no file was parsed and no name is given returns a PEAR_Error

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | File_DICOM | Next
File_DICOM::parse | PEAR Manual | File_DICOM::getValue


File_DICOM::getValue

File_DICOM::getValue

File_DICOM::getValue() – Gets the value for a DICOM element.

Synopsis

require_once 'File/DICOM.php';

mixed File_DICOM::getValue ( mixed $group_or_name , integer $element = null )

Description

Gets the value for a DICOM element of a given group from the parsed DICOM file

Parameter

mixed $group_or_name

The group the DICOM element belongs to (integer), or its name (string)

integer $element

The identifier for the DICOM element (unique inside a group). Optional

Return value

returns The value for the DICOM element on success, PEAR_Error on failure

Note

This function can not be called statically.

Example

Using getValue()

<?php
require_once('File/DICOM.php');

$dicom_file = new File_DICOM();
$res = $dicom_file->parse('test.dcm');

// check for errors
if (PEAR::isError($res)) {
    die($res->getMessage());
}

echo 'this value: '.$dicom_file->getValue('PatientName')."\n";
echo 'Should be the same as this value: '.$dicom_file->getValue(0x0010, 0x0010)."\n";
?>
Prev | File_DICOM | Next
File_DICOM::write | PEAR Manual | File_DICOM::setValue


File_DICOM::setValue

File_DICOM::setValue

File_DICOM::setValue() – Sets the value for a DICOM element.

Synopsis

require_once 'File/DICOM.php';

void File_DICOM::setValue ( integer $gp , integer $el , mixed $value )

Description

Sets the value for a DICOM element. Only works with strings now.

Parameter

integer $gp

The group the DICOM element belongs to

integer $el

The identifier for the DICOM element (unique inside a group)

mixed $value

Note

This function can not be called statically.

Prev | File_DICOM | Next
File_DICOM::getValue | PEAR Manual | File_DICOM::dumpImage


File_DICOM::dumpImage

File_DICOM::dumpImage

File_DICOM::dumpImage() – Dumps the contents of the image inside the DICOM file (element 0x0010 from group 0x7FE0) to a PGM (Portable Gray Map) file.

Synopsis

require_once 'File/DICOM.php';

mixed File_DICOM::dumpImage ( string $filename )

Description

Use with Caution!!. For a 8.5MB DICOM file on a P4 it takes 28 seconds to dump it's image.

Parameter

string $filename

The file where to save the image

Return value

returns true on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | File_DICOM | Next
File_DICOM::setValue | PEAR Manual | File_Fortune


File_Fortune

File_Fortune

Table of Contents
  • Class Summary File_Fortune -- File_Fortune
  • Introduction -- File_Fortune aims to provide a simple OOP and array-like interface to fortune files. To this end, it implements the SPL interfaces Iterator, Countable, and ArrayAccess. With it, you may easily create and maintain fortune databases, as well as fulfill their primary use case: getting a random fortune.
  • Examples -- Common use cases.
  • File_Fortune::__construct -- Constructor
  • File_Fortune::add -- Add a new fortune
  • File_Fortune::create -- Create a new fortune file from an array of fortunes
  • File_Fortune::delete -- Delete an existing fortune
  • File_Fortune::getAll -- Retrieve all fortunes from the current file
  • File_Fortune::getDirectory -- Retrieve current directory of fortune files
  • File_Fortune::getFile -- Retrieve current fortune file name
  • File_Fortune::getFiles -- Retrieve list of currently set fortune files
  • File_Fortune::getHeaderFile -- Retrieve current header file name
  • File_Fortune::getRandom -- Retrieve random fortune
  • File_Fortune::save -- Save changes
  • File_Fortune::setDirectory -- Set directory from which to randomly select a fortune file
  • File_Fortune::setFile -- Set fortune file
  • File_Fortune::setFiles -- Set multiple fortune files
  • File_Fortune::setHeaderFile -- Set header file name
  • File_Fortune::update -- Update an existing fortune
Prev | File Formats | Next
File_DICOM::dumpImage | PEAR Manual | Class Summary File_Fortune


Class Summary File_Fortune

Class Summary File_Fortune

Class Summary File_Fortune – File_Fortune

File_Fortune

File_Fortune: Interface to fortune cookie databases

The fortune program is a small but important part of *nix culture, and this package aims to provide support for its "fortune cookie" databases to PHP programmers.

Class Trees for File_Fortune

  • File_Fortune

  • File_Fortune_Exception

Prev | File_Fortune | Next
File_Fortune | PEAR Manual | Introduction


Introduction

Introduction

Introduction – File_Fortune aims to provide a simple OOP and array-like interface to fortune files. To this end, it implements the SPL interfaces Iterator, Countable, and ArrayAccess. With it, you may easily create and maintain fortune databases, as well as fulfill their primary use case: getting a random fortune.

Authors

  • Greg Ward is the original author of the Perl "Fortune.pm", on which work this heavily derives.

  • Matthew Weier O'Phinney is the author of this implementation.

Prev | File_Fortune | Next
Class Summary File_Fortune | PEAR Manual | Examples


Examples

Examples

Examples – Common use cases.

Getting a random fortune

<?php
require_once 'File/Fortune.php';

// Grab from a single fortune file:
$fortunes = new File_Fortune('/path/to/fortune/file');
echo $fortunes->getRandom();

// Grab from a directory of fortune files:
$fortunes = new File_Fortune('/path/to/fortune/files/');
echo $fortunes->getRandom();
?>

Get all fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
$cached = $fortunes->getAll();

// or all fortunes in all files:
$fortunes->setDirectory('/path/to/fortunes/');
$cached = $fortunes->getAll();
?>

Counting fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
$count = count($fortunes);

// or all fortunes in all files:
$fortunes->setDirectory('/path/to/fortunes/');
$count = count($fortunes);
?>

Looping through fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
foreach ($fortunes as $fortune) {
    echo $fortune;
}
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Manipulating fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');

// Delete a fortune:
unset($fortunes[2]); // deletes fortune denoted at index 2

// Update a fortune:
$fortune[2] = "I never liked this fortune"; // update fortune at index 2
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Adding fortunes

<?php
require_once 'File/Fortune.php';

$fortunes = new File_Fortune('/path/to/fortune/file');
$fortunes->add('Shiny, new fortune!');
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Creating a new fortune file

<?php
require_once 'File/Fortune.php';

$newFortunes = array(
    'Fortune 1',
    'Fortune 2',
    'Fortune 3'
);

$fortunes = new File_Fortune('/path/to/fortune/file');
$fortunes->create($newFortunes);
?>

Note: this will raise exceptions if a directory or multiple files have been set.

Prev | File_Fortune | Next
Introduction | PEAR Manual | File_Fortune::__construct


File_Fortune::__construct

File_Fortune::__construct

File_Fortune::__construct() – Constructor

Synopsis

require_once 'File/Fortune.php';

File_Fortune File_Fortune::__construct ( string|array $file = null , string $headerFile = null )

Description

Optionally pass a filename or directory name to set the fortune file or directory, and, if passing a fortune file name, optionally pass the name of the header file.

Parameter

string|array $file

Fortune file name, or name of a directory containing fortune files.

If passing an array, array of fortune files names.

string $headerFile

Optional location of binary header file to associate with file passed to $file; see setHeader() for more information.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
Examples | PEAR Manual | File_Fortune::add


File_Fortune::add

File_Fortune::add

File_Fortune::add() – Add a new fortune

Synopsis

require_once 'File/Fortune.php';

File_Fortune File_Fortune::add ( string $fortune )

Description

This package is not documented yet.

Parameter

string $fortune

Fortune string to add to fortune file. Fortune will be appended to fortune file.

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::__construct | PEAR Manual | File_Fortune::create


File_Fortune::create

File_Fortune::create

File_Fortune::create() – Create a new fortune file from an array of fortunes

Synopsis

require_once 'File/Fortune.php';

void File_Fortune::create ( $fortunes , string $file = null )

Description

This package is not documented yet.

Parameter

$fortunes

Array of fortunes to use to seed the new fortune file.

string $file

Optional file name to use when creating new fortune file. If not provided, attempts to use the file set via setFile()

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::add | PEAR Manual | File_Fortune::delete


File_Fortune::delete

File_Fortune::delete

File_Fortune::delete() – Delete an existing fortune

Synopsis

require_once 'File/Fortune.php';

void File_Fortune::delete ( int $index )

Description

delete() may be used to delete a fortune at a given index. However, the easier usage is to simply use unset with array notation:

<?php
unset($fortunes[$index]);

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Parameter

integer $index

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::create | PEAR Manual | File_Fortune::getAll


File_Fortune::getAll

File_Fortune::getAll

File_Fortune::getAll() – Retrieve all fortunes from the current file

Synopsis

require_once 'File/Fortune.php';

array File_Fortune::getAll ( )

Description

getAll() can be used to pull the entire fortune database into an array. Typically this is a bad idea as fortune files are often very large. If you wish to do some processing with each fortune, use the File_Fortune object as an iterator:

<?php
foreach ($fortunes as $fortune) {
    // do something with the fortune
}
?>

Note: you can use getAll() when a directory or multiple files have been set; in such a context, it will return all fortunes in all files.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::delete | PEAR Manual | File_Fortune::getDirectory


File_Fortune::getDirectory

File_Fortune::getDirectory

File_Fortune::getDirectory() – Retrieve current directory of fortune files

Synopsis

require_once 'File/Fortune.php';

string File_Fortune::getDirectory ( )

Description

getDirectory() returns the currently registered fortune file directory, if any.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::getAll | PEAR Manual | File_Fortune::getFile


File_Fortune::getFile

File_Fortune::getFile

File_Fortune::getFile() – Retrieve current fortune file name

Synopsis

require_once 'File/Fortune.php';

string File_Fortune::getFile ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::getDirectory | PEAR Manual | File_Fortune::getFiles


File_Fortune::getFiles

File_Fortune::getFiles

File_Fortune::getFiles() – Retrieve list of currently set fortune files

Synopsis

require_once 'File/Fortune.php';

array File_Fortune::getFiles ( )

Description

Retrieves a list of all currently set fortune files, as set either explicitly by setFiles() or implicitly by setDirectory().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::getFile | PEAR Manual | File_Fortune::getHeaderFile


File_Fortune::getHeaderFile

File_Fortune::getHeaderFile

File_Fortune::getHeaderFile() – Retrieve current header file name

Synopsis

require_once 'File/Fortune.php';

string File_Fortune::getHeaderFile ( )

Description

Header files are explained in the setHeaderFile() documentation. This method returns the current header file name, if any.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::getFiles | PEAR Manual | File_Fortune::getRandom


File_Fortune::getRandom

File_Fortune::getRandom

File_Fortune::getRandom() – Retrieve random fortune

Synopsis

require_once 'File/Fortune.php';

string File_Fortune::getRandom ( )

Description

getRandom() pulls a random fortune. If a fortune file has been explicitly specified, the fortune will be pulled from that file; if a directory has been specified, a random fortune file will first be selected.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::getHeaderFile | PEAR Manual | File_Fortune::save


File_Fortune::save

File_Fortune::save

File_Fortune::save() – Save changes

Synopsis

require_once 'File/Fortune.php';

void File_Fortune::save ( )

Description

In most cases, it will not be necessary to save changes; __destruct() will save changes when the object goes out of scope. However, if you wish to manually ensure that changes are set, you may call save().

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::getRandom | PEAR Manual | File_Fortune::setDirectory


File_Fortune::setDirectory

File_Fortune::setDirectory

File_Fortune::setDirectory() – Set directory from which to randomly select a fortune file

Synopsis

require_once 'File/Fortune.php';

File_Fortune File_Fortune::setDirectory ( string $directory )

Description

This package is not documented yet.

Parameter

string $directory

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::save | PEAR Manual | File_Fortune::setFile


File_Fortune::setFile

File_Fortune::setFile

File_Fortune::setFile() – Set fortune file

Synopsis

require_once 'File/Fortune.php';

File_Fortune File_Fortune::setFile ( string $file , string $headerFile = null )

Description

setFile() may be used to explicitly set a fortune file to use or create.

Parameter

string $file

string $headerFile

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::setDirectory | PEAR Manual | File_Fortune::setFiles


File_Fortune::setFiles

File_Fortune::setFiles

File_Fortune::setFiles() – Set multiple fortune files

Synopsis

require_once 'File/Fortune.php';

File_Fortune File_Fortune::setFiles ( )

Description

setFiles() may be used to define a list of files from which to pull fortunes. You may pass either a string single argument, an array single argument, or multiple string arguments. As examples:

<?php
// single file:
$fortunes->setFiles('/path/to/fortunefile');

// array of files:
$fortunes->setFiles(array('/path/to/fortunefile', '/another/fortunefile', '/more/fortunes'));

// multiple individual files:
$fortunes->setFiles('/path/to/fortunefile', '/another/fortunefile', '/more/fortunes');
?>

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::setFile | PEAR Manual | File_Fortune::setHeaderFile


File_Fortune::setHeaderFile

File_Fortune::setHeaderFile

File_Fortune::setHeaderFile() – Set header file name

Synopsis

require_once 'File/Fortune.php';

File_Fortune File_Fortune::setHeaderFile ( string $headerFile )

Description

Fortune files consist of an ASCII file containing fortunes separated by a delimiter, and a binary header file that contains meta information such as the delimter used, number of fortunes, minimum and maximum length of fortunes contained in the file, and the offsets where each fortune exist in the file.

In most cases, this file is simply the name of the fortune file plus the extension 'dat', and File_Fortune will automatically detect this. If this is not the case, however, you may explicitly set the header file name using this method.

Parameter

string $headerFile

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::setFiles | PEAR Manual | File_Fortune::update


File_Fortune::update

File_Fortune::update

File_Fortune::update() – Update an existing fortune

Synopsis

require_once 'File/Fortune.php';

void File_Fortune::update ( int $index , string $fortune )

Description

update() may be used to update fortunes. However, the recommended practice is to use array access:

<?php
$fortunes[2] = 'Updated fortunes are fun!';

If multiple files or a directory have been set, you cannot manipulate the fortune list, and this method will raise an exception.

Parameter

integer $index

string $fortune

Throws

throws File_Fortune_Exception

Note

This function can not be called statically.

Prev | File_Fortune | Next
File_Fortune::setHeaderFile | PEAR Manual | File_Fstab


File_Fstab

File_Fstab

This package reads and writes fstab files, or other files sharing their format, such as /proc/mounts on Linux systems.

Table of Contents
  • Introduction -- Introduction to File_Fstab.
  • Entries -- Working with entries
  • Saving -- Saving your changes
Prev | File Formats | Next
File_Fortune::update | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to File_Fstab.

Overview

This package allows you to read, manipulate, and write fstab-format files, such as /etc/fstab, /etc/mtab, and /proc/mounts.

Examples

Getting the filesystem type of the root device.

<?php
require_once 'File/Fstab.php';

$fstab =& new File_Fstab();

$root =& $fstab->getEntryForPath('/');
echo "Root FS type: " . $root->fsType . "\n";
?>

Determine if a user may mount the CD-ROM

The user option in your fstab determines whether users may mount a given device or not.

<?php
require_once 'File/Fstab.php';

$fstab =& new File_Fstab();

$cd =& $fstab->getEntryForDevice('/dev/cdrom');
if ($cd->hasOption('user')) {
    echo "Users may mount the CD-ROM\n";
} else {
    echo "Users may not mount the CD-ROM\n";
}
?>
Prev | File_Fstab | Next
File_Fstab | PEAR Manual | Entries


Entries

Entries

Entries – Working with entries

Entry overview

The File_Fstab_Entry class represents all the information available about a particular entry in a Fstab file.

Entry properties

The entry has a number of properties which represent the information in the fstab file.

$device

This is the path to the block device for this entry. $device, $uuid, and $label are mutually exclusive; only one of the three may be set.

$uuid

The UUID of the device.

$label

The label for this device.

$mountPoint

The directory this device is mounted on.

$fsType

The type of filesystem on $device.

$mountOptions

Array of mount options for this device.

$dumpFrequency

How often / if this filesystem should be backed up by dump.

$fsckPassNo

Order of / if this device should be checked by fsck when the system boots.

You may want to read fstab(5) for more information about what these fields mean.

Finding entries

There are a number of ways of finding a specific entry from the fstab. You may find based on device, mountpoint, filesystem label, or UUID.

Finding by device

To find by device, you want to use the getEntryForDevice() function. The single argument this function accepts is the path to the block device for an entry.

Get entry by device

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$dev =& $fstab->getEntryForDevice('/dev/hda1');
if (PEAR::isError($dev)) {
    die($dev->getMessage());
}
?>

Finding by path (mountpoint)

You may want to find a device based on the path it is mounted on; for example, you may want to get the entry for /cdrom, without caring if the CD device is /dev/hdb, /dev/cdrom, or some other device. To do this, use the getEntryForPath() function.

Get entry by path

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$dev =& $fstab->getEntryForPath('/cdrom');
if (PEAR::isError($dev)) {
    die($dev->getMessage());
}
?>

Finding by UUID

Some systems use a filesystem UUID to specify the device to mount. A UUID may look like this: b46ad2ee-01f3-4041-96ca-91d35d059417. The getEntryForUUID() function handles this.

Get entry by UUID

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$dev =& $fstab->getEntryForUUID('b46ad2ee-01f3-4041-96ca-91d35d059417');
if (PEAR::isError($dev)) {
    die($dev->getMessage());
}
?>

Finding by label

Some filesystems allow you to specify a textual label to a filesystem. For example, you may label your root device rootdev, the device you mount on /home could be named homedirs and so forth. File_Fstab supports getting entries based on the device label. This is accomplished by using the getEntryForLabel() function.

Get entry by label

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$dev =& $fstab->getEntryForLabel('homedirs');
if (PEAR::isError($dev)) {
    die($dev->getMessage());
}
?>

Adding entries

In addition to reading fstab files, you may modify them as well.

Add an entry for a floppy disk

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$floppy =& new File_Fstab_Entry();
$floppy->fsType = 'vfat';
$floppy->device = '/dev/fd0';
$floppy->mountPoint = '/floppy';
$fstab->addEntry($floppy);
?>
Prev | File_Fstab | Next
Introduction | PEAR Manual | Saving


Saving

Saving

Saving – Saving your changes

Saving your changes

After modifying a fstab file, you will want to save your changes. The save() function does this.

Comments from the loaded file are not preserved when saving, and whitespace may change. This has no effect on the functionality of the fstab file, but you may lose helpful comments.

Save to the same file

This will save your changes back to the file you loaded, overwriting the old file.

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$floppy =& new File_Fstab_Entry();
$floppy->fsType = 'vfat';
$floppy->device = '/dev/fd0';
$floppy->mountPoint = '/floppy';
$fstab->addEntry($floppy);
$res = $fstab->save();
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>

Save to a different file

This will save your changes to a different file than the one you originally loaded.

<?php
require_once 'File/Fstab.php';
$fstab =& new File_Fstab();
$floppy =& new File_Fstab_Entry();
$floppy->fsType = 'vfat';
$floppy->device = '/dev/fd0';
$floppy->mountPoint = '/floppy';
$fstab->addEntry($floppy);
$res = $fstab->save('/tmp/fstab.new');
if (PEAR::isError($res)) {
    die($res->getMessage());
}
?>
Prev | File_Fstab | Next
Entries | PEAR Manual | File_MARC


File_MARC

File_MARC

This package creates, reads, and modifies Machine Readable Cataloging (MARC) formatted files.

Table of Contents
  • Reading MARC data -- Reading MARC data with File_MARC
  • Formatting MARC data -- Formatting MARC data with File_MARC
Prev | File Formats | Next
Saving | PEAR Manual | Reading MARC data


Reading MARC data

Reading MARC data

Reading MARC data – Reading MARC data with File_MARC

Overview

File_MARC allows you to read Machine Readable Cataloging (MARC) data in MARC 21 format. File_MARCXML, which is bundled with File_MARC, allows you to read MARCXML formatted data.

Reading MARC data from different sources

Your input source can be a PHP stream (File_MARC::SOURCE_FILE) or a string (File_MARC::SOURCE_STRING). The source location and source types are the first and second arguments to the File_MARC and File_MARCXML constructors.

Reading MARC 21 data from a file

In the following example, MARC21 data has been stored on disk in a file named journals.mrc. To read the MARCX21 data, we call the constructor for File_MARC. We do not need to tell File_MARC that journals.mrc is a filename or stream pointing to the MARC content, because the value of the second parameter of the constructor for File_MARC defaults to File_MARC::SOURCE_FILE.

<?php
require 'File/MARC.php';

// Retrieve a set of MARC records from a file
$journals = new File_MARC('journals.mrc');

// Iterate through the retrieved records
while ($record = $journals->next()) {
    // Pretty print each record
    print $record;
    print "\n";
}
?>

Reading MARCXML data from a string

In the following example, MARCXML data has been returned from a call to a Web service and has therefore been stored in a PHP variable, $xml_data, as a string. To read the MARCXML data, we call the constructor for File_MARCXML. To tell File_MARCXML that $xml_data is a string, we specify File_MARC::SOURCE_STRING as the second parameter of the constructor.

<?php
require 'File/MARCXML.php';

// Retrieve a set of MARCXML records from a string
$journals = new File_MARCXML($xml_data, File_MARC::SOURCE_STRING);

// Iterate through the retrieved records
while ($record = $journals->next()) {
    // Pretty print each record
    print $record;
    print "\n";
}
?>

Reading MARC data from different sources

A File_MARC object consists of a leader and an iterable set of File_MARC_Record objects representing MARC records. Each of these, in turn, consists of an iterable set of File_MARC_Data_Field or File_MARC_Control_Field objects representing MARC fields. A File_MARC_Data_Field consists of a set of iterable File_MARC_Subfield objects representing MARC subfields.

Printing the elements of a record

<?php
require 'File/MARC.php';

// Retrieve a set of MARC records
$bibrecords = new File_MARC('catdump.mrc', File_MARC::SOURCE_FILE);

// Iterate through the retrieved records
while ($record = $bibrecords->next()) {
    // Print the leader
    print $record->getLeader();
    $subjects = $record->getFields('650');
    if ($subjects) {
        // Retrieve just the first 24_ field
        print $record->getField('24.', true);
        print "\n";

        // Now print all of the retrieved subjects
        foreach ($subjects as $field) {
            print $field;
            print "\n";
        }
        print "\n";
    }
}
?>

All of this means that File_MARC makes it easy to read in a set of MARC records and iterate through the contents to retrieve specific fields and subfields. File_MARC offers convenience methods for retrieving specific fields without forcing you to iterate through the fields. getField returns the first field that matches the field name, while getFields returns an array of all of the fields that match the specified field name. Both of these methods accept an optional boolean parameter that specifies whether your match string should be treated as a Perl Compatible Regular Expression.

Retrieving all 650 fields from a record

<?php
require 'File/MARC.php';

// Retrieve a set of MARC records from a z39 result string
$bibrecords = new File_MARC($z39_result, File_MARC::SOURCE_STRING);

// Iterate through the retrieved records
while ($record = $bibrecords->next()) {
    // Retrieve an array of all of the 650 fields
    $subjects = $record->getFields('650');
    if ($subjects) {
        // Retrieve just the first 24_ field
        print $record->getField('24.', true);
        print "\n";

        // Now print all of the retrieved subjects
        foreach ($subjects as $field) {
            print $field;
            print "\n";
        }
        print "\n";
    }
}
?>

Iterating through fields and subfields

When you iterate over a File_MARC_Data_Field object using foreach(), the MARC tag for the given field is returned as the key for the element and the set of subfields is returned as the value of the element.

Similarly, when you iterate over a File_MARC_Subfield object using foreach(), the code for the given subfield is returned as the key of the element and the value of the given subfield is returned as the value of the element.

Iterating over fields and subfields in a MARC record

In the following example, we iterate through a set of 650 fields to print out the subject headings contained in the subfields for each field.

<?php
require 'File/MARC.php';

// Retrieve a set of MARC records from a z39 result string
$bibrecords = new File_MARC($z39_result, File_MARC::SOURCE_STRING);

// Go through each record
while ($record = $bibrecords->next()) {
    // Iterate through the fields
    foreach ($record->getFields() as $tag => $subfields) {
        // Skip everything except for 650 fields
        if ($tag == '650') {
            print "Subject:";
            foreach ($subfields->getSubfields() as $code => $value) {
                print " $value";
            }
            print "\n";
        }
    }
}
?>

Retrieving field indicators

Data fields, represented by the File_MARC_Data_Field class, offer a getIndicator() function to enable you to retrieve the value of an indicator.

Retrieving an indicator

In the following example, we retrieve the title (245) field of a MARC record and check the second indicator for the field to determine whether there are non-filing indicators that we should ignore when sorting the contents of the field.

<?php
require 'File/MARC.php';

$titleField = $record->getField('245');
$nonfiling = $titleField->getIndicator(2);

if ($nonfiling) {
  // Sort using the subset of the $a subfield
  $title = substr($titleField->getSubfield('a'), $nonfiling);
} else {
  // Sort using the entire contents of the $a subfield
  $title = $titleField->getSubfield('a');
}
?>
Prev | File_MARC | Next
File_MARC | PEAR Manual | Formatting MARC data


Formatting MARC data

Formatting MARC data

Formatting MARC data – Formatting MARC data with File_MARC

Overview

The File_MARC_Record class enables you to write Machine Readable Cataloging (MARC) data in MARC 21 format, in a human-readable string format, and (with some restrictions) in MARCXML format.

Formatting MARC 21 data

To return a record in MARC 21 format, call the toRaw() method on the File_MARC_Record object.

Writing MARC 21 data to a file

In the following example, we have created one or more MARC records represented by File_MARC_Record objects stored in the $records array. To write this data to a file in MARC 21 format, we simply open the file in binary mode and write the contents of the records in the array to the file by calling the toRaw() method on each record in turn.

<?php
require 'File/MARC.php';

// convert_metadata_to_marc() is a fictional method
// that returns an array of File_MARC_Record objects
$records = convert_metadata_to_marc();

// Open a file for binary write access
$marc21_file = fopen("records.mrc", "wb");

// Iterate through the records
while ($record = $records->next()) {
    // Write each record to the file in MARC 21 format
    fwrite($marc21_file, $record->toRaw());
}

// Close the file
fclose($marc21_file);
?>

Creating human-readable output from MARC data

To return a human-readable version of a MARC 21 or MARCXML record, call the __toString() method on the File_MARC_Record object. Note that you call the __toString() method implicitly when you call the print() function on a File_MARC_Record object.

Returning a human-readable representation of MARC

In the following example, we print the contents of each MARC record in a human-readable format and also explicitly call the __toString() method so that we can write the human-readable contents to a file. Notice that it does not matter whether the source format is MARC or MARCXML, the methods we call to format the data for output are the same.

<?php
require 'File/MARCXML.php';

// Retrieve a set of MARCXML records from a string
$journals = new File_MARCXML($xml_data, File_MARC::SOURCE_STRING);

// Open a file for binary write access
$marc21_file = fopen("records.mrc", "wb");

// Iterate through the retrieved records
while ($record = $journals->next()) {
    // Pretty print each record
    print $record;
    print "\n";

    // Write the pretty-printed record to file
    fwrite($marc21_file, $record->__toString() . "\n");
}

// Close the file
fclose($marc21_file);
?>

Formatting MARCXML data

To return a record in MARCXML format, call the toXML() method on the File_MARC_Record object.

Significant restrictions on the toXML() method

  • Most significantly, PHP offers no means of converting from the MARC8 encoding that most legacy MARC records have been encoded in to a valid XML encoding such as UTF-8. MARC libraries in other languages have worked around this basic lack of infrastructure by creating their own character encoding conversion libraries. At this time, the author of File_MARC does not have the capacity to build the same support as a PEAR package but would welcome any assistance. Better still would be the addition of ANSEL and MARC8 encoding support to the iconv and ICU toolkits that are used to supply encoding conversion by most open-source projects and languages.

  • The toXML() method currently produces a single, complete, valid XML MARCXML document for a single File_MARC_Record object. You cannot simply concatenate the results of calling toXML() on two File_MARC_Record objects, because that will produce invalid an invalid XML document. At this time, it is up to the developer to extract the record node from each MARCXML document and concatenate them inside a collection root element if they want to create a MARCXML document that contains more than a single record.

Writing MARCXML data to a file

In the following example, we have created a MARC record represented by a File_MARC_Record object stored in the $record variable. To write this data to a file in MARCXML format, we simply open the file in binary mode and write the record to the file by calling the toXML() method on the record object.

<?php
require 'File/MARC.php';

// Create a MARC record
$record = create_a_marc_record();

// Open a file for binary write access
$marcxml_file = fopen("records.mrc", "wb");

// Write the record to the file in MARCXML format
fwrite($marcxml_file, $record->toXML());

// Close the file
fclose($marcxml_file);
?>
Prev | File_MARC | Next
Reading MARC data | PEAR Manual | File_Passwd


File_Passwd

File_Passwd

Package to manage passwd-style files

Table of Contents
  • Introduction
  • File_Passwd
  • File_Passwd_Common
  • File_Passwd_Custom
  • File_Passwd_Unix
  • File_Passwd_Cvs
  • File_Passwd_Smb
  • File_Passwd_Authbasic
  • File_Passwd_Authdigest
Prev | File Formats | Next
Formatting MARC data | PEAR Manual | Introduction


Introduction

Introduction

Table of Contents
  • Introduction
Prev | File_Passwd | Next
File_Passwd | PEAR Manual | Introduction


Introduction

Introduction

Introduction –

New File_Passwd Facilities

The new File_Passwd package provides facilities to manage many different kinds of password files.

Currently supported password file formats:

Unix, CVS, SMB, AuthUserFile, AuthDigestFile and custom formatted passwd files.

Fileformat

passwd-style means, the file has a format like this:

user<delimiter>password

The delimiting character is usually the colon.

With the new File_Passwd_Custom class you can choose your delimiting character, but be aware that any column of your passwd file MUST NOT contain the delimiter!

Prev | Introduction | Next
Introduction | PEAR Manual | File_Passwd


File_Passwd

File_Passwd

Table of Contents
  • File_Passwd Constants -- Constants used by File_Passwd
  • File_Passwd::apiVersion -- Get API version
  • File_Passwd::factory -- Factory for extensions
  • File_Passwd::staticAuth -- Fast authentication

The File_Passwd class provides a factory for all special purpose classes, static authentication and common encryption methods.

Prev | File_Passwd | Next
Introduction | PEAR Manual | File_Passwd Constants


File_Passwd Constants

File_Passwd Constants

File_Passwd Constants – Constants used by File_Passwd

Constants

Encryption Constants
Name | Value | Description
FILE_PASSWD_DES | "des" | DES encryption
FILE_PASSWD_MD5 | "md5" | MD5 encryption
FILE_PASSWD_SHA | "sha" | SHA encryption
FILE_PASSWD_NT | "nt" | NT hash
FILE_PASSWD_LM | "lm" | LM hash
FILE_PASSWD_PLAIN | "plain" | no encryption
Error Constants
Name | Value | Description
FILE_PASSWD_E_UNDEFINED | 0 | undefined - some seldom occuring errors
FILE_PASSWD_E_INVALID_FORMAT | 1 | passwd file has invalid format
FILE_PASSWD_E_INVALID_PROPERTY | 2 | an invalid (additional) property was supplied
FILE_PASSWD_E_INVALID_CHARS | 3 | parameter contains illegal chracters (usually only alphanumerics, the dash and underline are allowed)
FILE_PASSWD_E_INVALID_ENC_MODE | 4 | an invalid encryption mode was supplied (depending on the class actually used)
FILE_PASSWD_E_EXISTS_ALREADY | 5 | an entry (user, group, etc) to add exists already
FILE_PASSWD_E_EXISTS_NOT | 6 | an entry (user, group, etc) to delete/change doesn't exist
FILE_PASSWD_E_USER_NOT_IN_GROUP | 7 | the specified user is not in this certain group
FILE_PASSWD_E_USER_NOT_IN_REALM | 8 | the specified user is not in this certain realm
FILE_PASSWD_E_PARAM_MUST_BE_ARRAY | 9 | the supplied param must be of type array
FILE_PASSWD_E_METHOD_NOT_IMPLEMENTED | 10 | requested method was not implemented yet
FILE_PASSWD_E_DIR_NOT_CREATED | 11 | a certain directory couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | 12 | passwd file couldn't be opened
FILE_PASSWD_E_FILE_NOT_LOCKED | 13 | passwd file couldn't be locked
FILE_PASSWD_E_FILE_NOT_UNLOCKED | 14 | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | 15 | passwd file couldn't be closed
Prev | File_Passwd | Next
File_Passwd | PEAR Manual | File_Passwd::apiVersion


File_Passwd::apiVersion

File_Passwd::apiVersion

File_Passwd::apiVersion() – Get API version

Synopsis

require_once 'File/Passwd.php';

string File_Passwd::apiVersion ( )

Description

Returns API version of the File_Passwd package.

Return value

Returns string API version (currently 1.0.0).

Note

This function can be called statically.

Prev | File_Passwd | Next
File_Passwd Constants | PEAR Manual | File_Passwd::factory


File_Passwd::factory

File_Passwd::factory

File_Passwd::factory() – Factory for extensions

Synopsis

require_once 'File/Passwd.php';

object &File_Passwd::factory ( string $class )

Description

Load the desired worker class (extension).

  • Unix - for standard Unix passwd files

  • CVS - for CVS pserver passwd files

  • SMB - for SMB server passwd files

  • Authbasic - for AuthUserFiles

  • Authdigest - for AuthDigestFiles

  • Custom - for custom formatted passwd files

Parameter

string $class

the desired extension of File_Passwd

Return value

Returns object File_Passwd extension or PEAR_Error on failure.

Note

This function should be called statically.

Prev | File_Passwd | Next
File_Passwd::apiVersion | PEAR Manual | File_Passwd::staticAuth


File_Passwd::staticAuth

File_Passwd::staticAuth

File_Passwd::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd.php';

mixed File_Passwd::staticAuth ( string $type , string $file , string $user , string $pass , mixed $opt = '' )

Description

Static user autentication.

Though this approach should be reasonable fast, it is NOT with APR compatible MD5 encryption used for htpasswd style password files encrypted in MD5.

Generating one MD5 password takes about 0.25 seconds!

Depending on $type, $opt should be:

  • Smb:

    • encryption method (NT or LM)

  • Unix:

    • encryption method (des or md5)

  • Authbasic:

    • encryption method (des, sha or md5)

  • Authdigest:

    • the realm the user is in

  • Cvs:

    • n/a (empty)

  • Custom:

    • array of 2 elements: encryption function and delimiter

Parameter

string $type

Unix, Cvs, Smb, Authbasic or Authdigest

string $file

path to passwd file

string $user

the user to authenticate

string $pass

the plaintext password

mixed $opt

  • Smb:

    • nt | lm

  • Unix:

    • des | md5

  • Authbasic:

    • des | sha | md5

  • Authdigest:

    • the realm the user is in

  • Cvs:

    • n/a (empty)

  • Custom:

    • array of 2 elements: encryption function and delimiter

Return value

Returns TRUE if authenticated, FALSE if not, or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed /only if auth fails)
FILE_PASSWD_E_UNDEFINED | if class/file couldn't be loaded
FILE_PASSWD_E_INVALID_ENC_MODE | supplied encryption mode is not supported
FILE_PASSWD_E_USER_NOT_IN_REALM | user doesn't exist in this realm (only File_Passwd_Authdigest)

Note

This function should be called statically.

Prev | File_Passwd | Next
File_Passwd::factory | PEAR Manual | File_Passwd_Common


File_Passwd_Common

File_Passwd_Common

Table of Contents
  • Childs -- Classes that extend File_Passwd_Common and their inherited methods
  • File_Passwd_Common::delUser -- Delete a certain user
  • File_Passwd_Common::listUser -- List user
  • File_Passwd_Common::userExists -- Check if user exists
  • File_Passwd_Common::getFile -- Get path of passwd file
  • File_Passwd_Common::setFile -- Set path to passwd file
  • File_Passwd_Common::load -- Loads the file
  • File_Passwd_Common::parse -- Parse the content of the file
  • File_Passwd_Common::save -- Apply changes and rewrite passwd file
  • File_Passwd_Common::_auth -- Base method for File_Passwd::staticAuth()
  • File_Passwd_Common::_open -- Open a file
  • File_Passwd_Common::_close -- Closes a prior opened and locked file handle
  • File_Passwd_Common::_save -- Save the modified content to the passwd file
  • File_Passwd_Common::__construct -- Constructor (ZE2)

Base class for worker class extensions.

Prev | File_Passwd | Next
File_Passwd::staticAuth | PEAR Manual | Childs


Childs

Childs

Childs – Classes that extend File_Passwd_Common and their inherited methods

Child Classes

Classes that extend File_Passwd_Common
Class | Summary
File_Passwd_Authbasic | Manipulate AuthUserFiles as used for HTTP Basic Authentication.
File_Passwd_Authdigest | Manipulate AuthDigestFiles as used for HTTP Digest Authentication.
File_Passwd_Cvs | Manipulate CVS pserver passwd files.
File_Passwd_Smb | Manipulate SMB server passwd files.
File_Passwd_Unix | Manipulate standard Unix passwd files.
File_Passwd_Custom | Manipulate custom formatted passwd files.

List of inherited Methods

Inherited methods from File_Passwd_Common
Method Name | Summary
File_Passwd_Common::delUser() | Delete a certain user
File_Passwd_Common::getFile() | Get path of passwd file
File_Passwd_Common::listUser() | List user
File_Passwd_Common::load() | Loads the file
File_Passwd_Common::parse() | Parse the content of the file
File_Passwd_Common::save() | Apply changes and rewrite passwd file
File_Passwd_Common::setFile() | Set path to passwd file
File_Passwd_Common::userExists() | Check if a certain user already exists
File_Passwd_Common::_auth() | Base method for File_Passwd::staticAuth()
File_Passwd_Common::_close() | Closes a prior opened and locked file handle
File_Passwd_Common::_open() | Opens a file, locks it exclusively and returns the filehandle
File_Passwd_Common::_save() | Save the modified content to the passwd file
Prev | File_Passwd_Common | Next
File_Passwd_Common | PEAR Manual | File_Passwd_Common::delUser


File_Passwd_Common::delUser

File_Passwd_Common::delUser

File_Passwd_Common::delUser() – Delete a certain user

Synopsis

mixed^File_Passwd_Common::delUser ( string $user )

Description

Delete a certain user.

Parameter

string $user

username

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
Childs | PEAR Manual | File_Passwd_Common::listUser


File_Passwd_Common::listUser

File_Passwd_Common::listUser

File_Passwd_Common::listUser() – List user

Synopsis

mixed File_Passwd_Common::listUser ( string $user = '' )

Description

List one user's properties or all users.

Parameter

string $user

the user to list or all users if empty

Return value

Returns array of user(s) or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | suer doesn't exist

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::delUser | PEAR Manual | File_Passwd_Common::userExists


File_Passwd_Common::userExists

File_Passwd_Common::userExists

File_Passwd_Common::userExists() – Check if user exists

Synopsis

bool File_Passwd_Common::userExists ( string $user )

Description

Check if a certain user already exists.

Parameter

string $user

the name of the user to check if already exists

Return value

Returns boolean whether user already exists.

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::listUser | PEAR Manual | File_Passwd_Common::getFile


File_Passwd_Common::getFile

File_Passwd_Common::getFile

File_Passwd_Common::getFile() – Get path of passwd file

Synopsis

string File_Passwd_Common::getFile ( )

Description

Get the path of the passwd file.

Return value

Returns string path of passwd file.

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::userExists | PEAR Manual | File_Passwd_Common::setFile


File_Passwd_Common::setFile

File_Passwd_Common::setFile

File_Passwd_Common::setFile() – Set path to passwd file

Synopsis

void File_Passwd_Common::setFile ( string $file )

Description

Set path to passwd file.

Parameter

string $file

path to passwd file

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::getFile | PEAR Manual | File_Passwd_Common::load


File_Passwd_Common::load

File_Passwd_Common::load

File_Passwd_Common::load() – Loads the file

Synopsis

mixed File_Passwd_Common::load ( )

Description

Loads the passwd file and calls the parse() method of the extending child class.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | the directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed
FILE_PASSWD_E_INVALID_FORMAT | passwd file has invalid format

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::setFile | PEAR Manual | File_Passwd_Common::parse


File_Passwd_Common::parse

File_Passwd_Common::parse

File_Passwd_Common::parse() – Parse the content of the file

Synopsis

object File_Passwd_Common::parse ( )

Description

This is kinda abstract method which only returns a PEAR_Error, so it is to be overwritten in the extending child class.

You must overwrite this method in your File_Passwd_* class.

(package developer related)

Return value

Returns object PEAR_Error FILE_PASSWD_E_METHOD_NOT_IMPLEMENTED.

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::load | PEAR Manual | File_Passwd_Common::save


File_Passwd_Common::save

File_Passwd_Common::save

File_Passwd_Common::save() – Apply changes and rewrite passwd file

Synopsis

object File_Passwd_Common::save ( )

Description

This is kinda abstract method which only returns a PEAR_Error, so it is to be overwritten in the extending child class.

You must overwrite this method in your File_Passwd_* class.

(package developer related)

Return value

Returns object PEAR_Error FILE_PASSWD_E_METHOD_NOT_IMPLEMENTED.

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::parse | PEAR Manual | File_Passwd_Common::_auth


File_Passwd_Common::_auth

File_Passwd_Common::_auth

File_Passwd_Common::_auth() – Base method for File_Passwd::staticAuth()

Synopsis

mixed File_Passwd_Common::_auth ( string $file , string $id )

Description

Base method for File_Passwd_*::staticAuth()

(package developer related)

Parameter

string $file

path to passwd file

string $id

user_id to search for

Return value

Returns string line of passwd file containing $id, FALSE if $id wasn't found, or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed (only if auth fails)

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::save | PEAR Manual | File_Passwd_Common::_open


File_Passwd_Common::_open

File_Passwd_Common::_open

File_Passwd_Common::_open() – Open a file

Synopsis

mixed &File_Passwd_Common::_open ( string $mode , mixed $file = null )

Description

Opens a file, locks it exclusively and returns the filehandle.

(package developer related)

Parameter

string $mode

the mode to open the file with

string $file

path to passwd file

Return value

Returns resource file handle or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | the directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in the desired mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::_auth | PEAR Manual | File_Passwd_Common::_close


File_Passwd_Common::_close

File_Passwd_Common::_close

File_Passwd_Common::_close() – Closes a prior opened and locked file handle

Synopsis

mixed File_Passwd_Common::_close ( resource &$file_handle )

Description

Closes a prior with File_Passwd_Common::_open() opened and locked file handle.

(package developer related)

Parameter

resource &$file_handle

the file handle to operate on

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::_open | PEAR Manual | File_Passwd_Common::_save


File_Passwd_Common::_save

File_Passwd_Common::_save

File_Passwd_Common::_save() – Save the modified content to the passwd file

Synopsis

mixed File_Passwd_Common::_save ( string $content )

Description

Save content to file.

(package developer related)

Parameter

string $content

file content

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | the directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::_close | PEAR Manual | File_Passwd_Common::__construct


File_Passwd_Common::__construct

File_Passwd_Common::__construct

File_Passwd_Common::__construct() – Constructor (ZE2)

Synopsis

object File_Passwd_Common::__construct ( string $file = 'passwd' )

Description

Implemented for Zend Engine 2 compatibility.

(package developer related)

Parameter

string $file

path to passwd file

Return value

Returns object File_Passwd_* - new instance of an File_Passwd_* object.

Note

This function can not be called statically.

Prev | File_Passwd_Common | Next
File_Passwd_Common::_save | PEAR Manual | File_Passwd_Custom


File_Passwd_Custom

File_Passwd_Custom

Table of Contents
  • File_Passwd_Custom::staticAuth -- Fast authentication
  • File_Passwd_Custom::File_Passwd_Custom -- Constructor
  • File_Passwd_Custom::parse -- Parse passwd file
  • File_Passwd_Custom::save -- Save changes
  • File_Passwd_Custom::addUser -- Add an user
  • File_Passwd_Custom::modUser -- Modify user
  • File_Passwd_Custom::changePasswd -- Change password
  • File_Passwd_Custom::verifyPasswd -- Verify password
  • File_Passwd_Custom::useMap -- Whether to use the 'name map'
  • File_Passwd_Custom::getMap -- Get 'name map'
  • File_Passwd_Custom::setMap -- Set 'name map'

Manipulate custom formatted passwd files. (inherited methods)

Prev | File_Passwd | Next
File_Passwd_Common::__construct | PEAR Manual | File_Passwd_Custom::staticAuth


File_Passwd_Custom::staticAuth

File_Passwd_Custom::staticAuth

File_Passwd_Custom::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd/Custom.php';

mixed File_Passwd_Custom::staticAuth ( string $file , string $user , string $pass , array $opts )

Description

Static user authentication.

Parameter

string $file

path to passwd file

string $user

user to authenticate

string $pass

plaintext password

array $opts

A two element array containing the encryption function to use and the delimiting character: e.g. array('md5', '|')

Return value

Returns TRUE if authenticated, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed (only if auth fails)

Note

This function should be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom | PEAR Manual | File_Passwd_Custom::File_Passwd_Custom


File_Passwd_Custom::File_Passwd_Custom

File_Passwd_Custom::File_Passwd_Custom

File_Passwd_Custom::File_Passwd_Custom() – Constructor

Synopsis

require_once 'File/Passwd/Custom.php';

object &new File_Passwd_custom ( string $file = 'passwd' )

Description

Initialize a new File_Passwd_Custom object with the specified path to passwd file.

Parameter

string $file

path to passwd file

Return value

Returns object File_Passwd_Custom.

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::staticAuth | PEAR Manual | File_Passwd_Custom::parse


File_Passwd_Custom::parse

File_Passwd_Custom::parse

File_Passwd_Custom::parse() – Parse passwd file

Synopsis

mixed File_Passwd_Custom::parse ( )

Description

Parse the custom passwd file. (package developer related)

This usually happens in File_Passwd_Custom::load() .

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_INVALID_FORMAT, if passwd file has illegal format.

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::File_Passwd_Custom | PEAR Manual | File_Passwd_Custom::save


File_Passwd_Custom::save

File_Passwd_Custom::save

File_Passwd_Custom::save() – Save changes

Synopsis

mixed File_Passwd_Custom::save ( )

Description

Apply changes and rewrite passwd file.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::parse | PEAR Manual | File_Passwd_Custom::addUser


File_Passwd_Custom::addUser

File_Passwd_Custom::addUser

File_Passwd_Custom::addUser() – Add an user

Synopsis

mixed File_Passwd_Custom::addUser ( string $user , string $pass , array $extra = array() )

Description

The username must start with an alphabetical character and must NOT contain any other characters than alphanumerics, the underline and dash.

The username MUST NOT contain the custom delimiter!

If you use the 'name map' you should also use these naming in the supplied extra array, because your values would get mixed up if they are in the wrong order, which is always true if you DON'T use the 'name map'!

So be warned and USE the 'name map'!

Parameter

string $user

the name of the user to add

string $pass

the password of the user to add

array $extra

extra properties of user to add

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_ALREADY_EXISTS | user already exists
FILE_PASSWD_E_INVALID_CHARS | username contains illegal characters
FILE_PASSWD_E_INVALID_CHARS | any of the extra proporties contains the delimiter
FILE_PASSWD_E_INVALID_ENC_MODE | actual encryption mode is not supported
FILE_PASSWD_E_UNDEFINED | if passwd file is shadowed

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::save | PEAR Manual | File_Passwd_Custom::modUser


File_Passwd_Custom::modUser

File_Passwd_Custom::modUser

File_Passwd_Custom::modUser() – Modify user

Synopsis

mixed File_Passwd_Custom::modUser ( string $user , array $properties = array() )

Description

You shouldn't modify the password of the user with this method, use File_Passwd_Custom::changePasswd() instead.

You should use this method only if the 'name map' is used, too.

Parameter

string $user

the user to modify

array $properties

an associative array of properties to modify

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exists
FILE_PASSWD_E_INVALID_CHARS | any of the extra properties contains the delimiter

See

See File_Passwd_Custom::useMap()

See File_Passwd_Custom::changePasswd()

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::addUser | PEAR Manual | File_Passwd_Custom::changePasswd


File_Passwd_Custom::changePasswd

File_Passwd_Custom::changePasswd

File_Passwd_Custom::changePasswd() – Change password

Synopsis

mixed File_Passwd_Custom::changePasswd ( string $user , string $pass )

Description

Change the password of a certain user.

Parameter

string $user

the user whose password should be changed

string $pass

the new plaintext password

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_INVALID_ENC_MODE | actual encryption mode is not supported

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::modUser | PEAR Manual | File_Passwd_Custom::verifyPasswd


File_Passwd_Custom::verifyPasswd

File_Passwd_Custom::verifyPasswd

File_Passwd_Custom::verifyPasswd() – Verify password

Synopsis

mixed File_Passwd_Custom::verifyPasswd ( string $user , string $pass )

Description

Verify the password of a certain user.

Parameter

string $user

the user whose password should be verified

string $pass

the password to verify

Return value

Returns TRUE if passwords equal, FALSE if they don't or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_E_INVALID_ENC_MODE | actual encryption mode isn't supported

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::changePasswd | PEAR Manual | File_Passwd_Custom::useMap


File_Passwd_Custom::useMap

File_Passwd_Custom::useMap

File_Passwd_Custom::useMap() – Whether to use the 'name map'

Synopsis

boolean File_Passwd_Custom::useMap ( boolean $bool = null )

Description

Whether to use the 'name map' of the extra properties or not.

You first must supply a 'name map' to use it.

Parameter

boolean $bool

whether to use the 'name map' or not

Return value

Returns boolean TRUE if you set a value, or the actual value if called without param.

See

See File_Passwd_Custom::getMap()

See File_Passwd_Custom::setMap()

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::verifyPasswd | PEAR Manual | File_Passwd_Custom::getMap


File_Passwd_Custom::getMap

File_Passwd_Custom::getMap

File_Passwd_Custom::getMap() – Get 'name map'

Synopsis

array File_Passwd_Custom::getMap ( )

Description

Get the 'name map' which is used for the extra properties of the user.

Return value

Returns array 'name map'.

See

See File_Passwd_Custom::setMap()

See File_Passwd_Custom::useMap()

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::useMap | PEAR Manual | File_Passwd_Custom::setMap


File_Passwd_Custom::setMap

File_Passwd_Custom::setMap

File_Passwd_Custom::setMap() – Set 'name map'

Synopsis

mixed File_Passwd_Custom::setMap ( mixed $map = array() )

Description

Set the 'name map' to use with the extra properties of the user.

This map is used for naming the associative array of the extra properties.

Parameter

array $map

the 'name map'

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_PARAM_MUST_BE_ARRAY, if the supplied 'name map' was not of type array.

See

See File_Passwd_Custom::useMap()

See File_Passwd_Custom::getMap()

Note

This function can not be called statically.

Prev | File_Passwd_Custom | Next
File_Passwd_Custom::getMap | PEAR Manual | File_Passwd_Unix


File_Passwd_Unix

File_Passwd_Unix

Table of Contents
  • File_Passwd_Unix::staticAuth -- Fast authentication
  • File_Passwd_Unix::File_Passwd_Unix -- Constructor
  • File_Passwd_Unix::parse -- Parse passwd file
  • File_Passwd_Unix::save -- Save changes
  • File_Passwd_Unix::addUser -- Add an user
  • File_Passwd_Unix::modUser -- Modify user
  • File_Passwd_Unix::changePasswd -- Change password
  • File_Passwd_Unix::verifyPasswd -- Verify password
  • File_Passwd_Unix::useMap -- Whether to use the 'name map'
  • File_Passwd_Unix::getMap -- Get 'name map'
  • File_Passwd_Unix::setMap -- Set 'name map'
  • File_Passwd_Unix::getMode -- Get actual encryption mode
  • File_Passwd_Unix::setMode -- Set encryption mode
  • File_Passwd_Unix::listModes -- Get supported encryption modes
  • File_Passwd_Unix::isShadowed -- Check if passwd file is shadowed
  • File_Passwd_Unix::generatePassword -- Generate password

Manipulate standard Unix passwd files. (inherited methods)

Prev | File_Passwd | Next
File_Passwd_Custom::setMap | PEAR Manual | File_Passwd_Unix::staticAuth


File_Passwd_Unix::staticAuth

File_Passwd_Unix::staticAuth

File_Passwd_Unix::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd/Unix.php';

mixed File_Passwd_Unix::staticAuth ( string $file , string $user , string $pass , string $mode )

Description

Static user authentication.

Parameter

string $file

path to passwd file

string $user

user to authenticate

string $pass

plaintext password

string $mode

des or md5

Return value

Returns TRUE if authenticated, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed (only if auth fails)

Note

This function should be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix | PEAR Manual | File_Passwd_Unix::File_Passwd_Unix


File_Passwd_Unix::File_Passwd_Unix

File_Passwd_Unix::File_Passwd_Unix

File_Passwd_Unix::File_Passwd_Unix() – Constructor

Synopsis

require_once 'File/Passwd/Unix.php';

object &new File_Passwd_Unix ( string $file = 'passwd' )

Description

Initialize a new File_Passwd_Unix object with the specified path to passwd file.

Parameter

string $file

path to passwd file

Return value

Returns object File_Passwd_Unix.

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::staticAuth | PEAR Manual | File_Passwd_Unix::parse


File_Passwd_Unix::parse

File_Passwd_Unix::parse

File_Passwd_Unix::parse() – Parse passwd file

Synopsis

mixed File_Passwd_Unix::parse ( )

Description

Parse the unix passwd file. (package developer related)

This usually happens in File_Passwd_Unix::load() .

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_INVALID_FORMAT, if passwd file has illegal format.

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::File_Passwd_Unix | PEAR Manual | File_Passwd_Unix::save


File_Passwd_Unix::save

File_Passwd_Unix::save

File_Passwd_Unix::save() – Save changes

Synopsis

mixed File_Passwd_Unix::save ( )

Description

Apply changes and rewrite passwd file.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::parse | PEAR Manual | File_Passwd_Unix::addUser


File_Passwd_Unix::addUser

File_Passwd_Unix::addUser

File_Passwd_Unix::addUser() – Add an user

Synopsis

mixed File_Passwd_Unix::addUser ( string $user , string $pass , array $extra = array() )

Description

The username must start with an alphabetical character and must NOT contain any other characters than alphanumerics, the underline and dash.

If you use the 'name map' you should also use these naming in the supplied extra array, because your values would get mixed up if they are in the wrong order, which is always true if you DON'T use the 'name map'!

So be warned and USE the 'name map'!

If the passwd file is shadowed, the user will be added though, but with an 'x' as password, and a PEAR_Error will be returned, too.

Parameter

string $user

the name of the user to add

string $pass

the password of the user to add

array $extra

extra properties of user to add

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_ALREADY_EXISTS | user already exists
FILE_PASSWD_E_INVALID_CHARS | username contains illegal characters
FILE_PASSWD_E_INVALID_CHARS | any of the extra proporties contains a colon
FILE_PASSWD_E_INVALID_ENC_MODE | actual encryption mode is not supported
FILE_PASSWD_E_UNDEFINED | if passwd file is shadowed

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::save | PEAR Manual | File_Passwd_Unix::modUser


File_Passwd_Unix::modUser

File_Passwd_Unix::modUser

File_Passwd_Unix::modUser() – Modify user

Synopsis

mixed File_Passwd_Unix::modUser ( string $user , array $properties = array() )

Description

You shouldn't modify the password of the user with this method, use File_Passwd_Unix::changePasswd() instead.

You should use this method only if the 'name map' is used, too.

Parameter

string $user

the user to modify

array $properties

an associative array of properties to modify

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exists
FILE_PASSWD_E_INVALID_CHARS | any of the extra properties contains a colon

See

See File_Passwd_Unix::useMap()

See File_Passwd_Unix::changePasswd()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::addUser | PEAR Manual | File_Passwd_Unix::changePasswd


File_Passwd_Unix::changePasswd

File_Passwd_Unix::changePasswd

File_Passwd_Unix::changePasswd() – Change password

Synopsis

mixed File_Passwd_Unix::changePasswd ( string $user , string $pass )

Description

Change the password of a certain user.

Parameter

string $user

the user whose password should be changed

string $pass

the new plaintext password

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_INVALID_ENC_MODE | actual encryption mode is not supported
FILE_PASSWD_UNDEFINED | if passwd file is shadowed

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::modUser | PEAR Manual | File_Passwd_Unix::verifyPasswd


File_Passwd_Unix::verifyPasswd

File_Passwd_Unix::verifyPasswd

File_Passwd_Unix::verifyPasswd() – Verify password

Synopsis

mixed File_Passwd_Unix::verifyPasswd ( string $user , string $pass )

Description

Verify the password of a certain user.

Parameter

string $user

the user whose password should be verified

string $pass

the password to verify

Return value

Returns TRUE if passwords equal, FALSE if they don't or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_E_INVALID_ENC_MODE | actual encryption mode isn't spported

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::changePasswd | PEAR Manual | File_Passwd_Unix::useMap


File_Passwd_Unix::useMap

File_Passwd_Unix::useMap

File_Passwd_Unix::useMap() – Whether to use the 'name map'

Synopsis

boolean File_Passwd_Unix::useMap ( boolean $bool = null )

Description

Whether to use the 'name map' of the extra properties or not.

Default Unix passwd files look like:
user:password:user_id:group_id:gecos:home_dir:shell

The default 'name map' for properties except user and password looks like:

  • uid

  • gid

  • gecos

  • home

  • shell

If you want to change the naming of the standard map use File_Passwd_Unix::setMap().

Parameter

boolean $bool

whether to use the 'name map' or not

Return value

Returns boolean TRUE if you set a value, or the actual value if called without param.

See

See File_Passwd_Unix::getMap()

See File_Passwd_Unix::setMap()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::verifyPasswd | PEAR Manual | File_Passwd_Unix::getMap


File_Passwd_Unix::getMap

File_Passwd_Unix::getMap

File_Passwd_Unix::getMap() – Get 'name map'

Synopsis

array File_Passwd_Unix::getMap ( )

Description

Get the 'name map' which is used for the extra properties of the user.

Return value

Returns array 'name map'.

See

See File_Passwd_Unix::setMap()

See File_Passwd_Unix::useMap()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::useMap | PEAR Manual | File_Passwd_Unix::setMap


File_Passwd_Unix::setMap

File_Passwd_Unix::setMap

File_Passwd_Unix::setMap() – Set 'name map'

Synopsis

mixed File_Passwd_Unix::setMap ( mixed $map = array() )

Description

Set the 'name map' to use with the extra properties of the user.

This map is used for naming the associative array of the extra properties.

Parameter

array $map

the 'name map'

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_PARAM_MUST_BE_ARRAY, if the supplied 'name map' was not of type array.

See

See File_Passwd_Unix::useMap()

See File_Passwd_Unix::getMap()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::getMap | PEAR Manual | File_Passwd_Unix::getMode


File_Passwd_Unix::getMode

File_Passwd_Unix::getMode

File_Passwd_Unix::getMode() – Get actual encryption mode

Synopsis

string File_Passwd_Unix::getMode ( )

Description

Get actual encryption mode (des|md5).

Return value

Returns string actual encryption mode.

See

See File_Passwd_Unix::setMode()

See File_Passwd_Unix::listModes()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::setMap | PEAR Manual | File_Passwd_Unix::setMode


File_Passwd_Unix::setMode

File_Passwd_Unix::setMode

File_Passwd_Unix::setMode() – Set encryption mode

Synopsis

mixed File_Passwd_Unix::setMode ( string $mode )

Description

Set encryption mode to use.

Supported encryption modes are 'des' and 'md5'.

You can use the constants FILE_PASSWD_MD5 and FILE_PASSWD_DES for this purpose.

Parameter

string $mode

encryption mode to use

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_INVALID_ENC_MODE, if supplied encryption mode is not supported.

See

See File_Passwd_Unix::listModes()

See File_Passwd_Unix::getMode()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::getMode | PEAR Manual | File_Passwd_Unix::listModes


File_Passwd_Unix::listModes

File_Passwd_Unix::listModes

File_Passwd_Unix::listModes() – Get supported encryption modes

Synopsis

array File_Passwd_Unix::listModes ( )

Description

List the supported encryption modes.

<pre>
array
+ md5
+ des
</pre>

Return value

Returns array supported encryption modes.

See

See File_Passwd_Unix::getMode()

See File_Passwd_Unix::setMode()

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::setMode | PEAR Manual | File_Passwd_Unix::isShadowed


File_Passwd_Unix::isShadowed

File_Passwd_Unix::isShadowed

File_Passwd_Unix::isShadowed() – Check if passwd file is shadowed

Synopsis

boolean File_Passwd_Unix::isShadowed ( )

Description

Check if the passwords of this passwd file are shadowed in another file.

Return value

Returns boolean whether passwords of this passwd file are shadowed in another file.

Note

This function can not be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::listModes | PEAR Manual | File_Passwd_Unix::generatePassword


File_Passwd_Unix::generatePassword

File_Passwd_Unix::generatePassword

File_Passwd_Unix::generatePassword() – Generate password

Synopsis

mixed File_Passwd_Unix::generatePassword ( string $pass , string $mode = 'md5' , string $salt = null )

Description

Generate a "Un*x" style password.

The encryption mode can be of any type File_Passwd provides, although FILE_PASSWD_MD5 and FILE_PASSWD_DES are the most common.

Parameter

string $pass

the plaintext password to encrypt

string $mode

the encryption mode to use

string $salt

the salt to use for encryption (usually empty)

Return value

Returns string encrypted password, or PEAR_Error FILE_PASSWD_E_INVALID_ENC_MODE if encryption mode is not supported.

Example

File_Passwd_Unix::generatePassword()

<?php
require_once 'File/Passwd/Unix.php';
$pass = File_Passwd_Unix::generatePassword('secret', FILE_PASSWD_MD5);
?>

Note

This function should be called statically.

Prev | File_Passwd_Unix | Next
File_Passwd_Unix::isShadowed | PEAR Manual | File_Passwd_Cvs


File_Passwd_Cvs

File_Passwd_Cvs

Table of Contents
  • File_Passwd_Cvs::staticAuth -- Fast authentication
  • File_Passwd_Cvs::File_Passwd_Cvs -- Constructor
  • File_Passwd_Cvs::parse -- Parse file
  • File_Passwd_Cvs::save -- Save changes
  • File_Passwd_Cvs::addUser -- Add an user
  • File_Passwd_Cvs::changeSysUser -- Change syste user
  • File_Passwd_Cvs::changePasswd -- Change password
  • File_Passwd_Cvs::verifyPasswd -- Verify password
  • File_Passwd_Cvs::generatePassword -- Generate password

Manipulate CVS pserver passwd files. (inherited methods)

Prev | File_Passwd | Next
File_Passwd_Unix::generatePassword | PEAR Manual | File_Passwd_Cvs::staticAuth


File_Passwd_Cvs::staticAuth

File_Passwd_Cvs::staticAuth

File_Passwd_Cvs::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd/Cvs.php';

mixed File_Passwd_Cvs::staticAuth ( string $file , string $user , string $pass )

Description

Static user authentication.

Parameter

string $file

path to passwd file

string $user

user to authenticate

string $pass

plaintext password

Return value

Returns TRUE if authenticated, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed /only if auth fails)

Note

This function should be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs | PEAR Manual | File_Passwd_Cvs::File_Passwd_Cvs


File_Passwd_Cvs::File_Passwd_Cvs

File_Passwd_Cvs::File_Passwd_Cvs

File_Passwd_Cvs::File_Passwd_Cvs() – Constructor

Synopsis

require_once 'File/Passwd/Cvs.php';

object &new File_Passwd_Cvs ( mixed $file = 'passwd' )

Description

Initialize a new File_Passwd_Cvs object with the given path to passwd file.

Parameter

string $file

path to passwd file

Return value

Returns object File_Passwd_Cvs.

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::staticAuth | PEAR Manual | File_Passwd_Cvs::parse


File_Passwd_Cvs::parse

File_Passwd_Cvs::parse

File_Passwd_Cvs::parse() – Parse file

Synopsis

mixed File_Passwd_Cvs::parse ( )

Description

Parse the CVS passwd file. (package developer related)

This usually happens in File_Passwd_Cvs::load() .

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_INVALID_FORMAT, if passwd file has invalid format.

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::File_Passwd_Cvs | PEAR Manual | File_Passwd_Cvs::save


File_Passwd_Cvs::save

File_Passwd_Cvs::save

File_Passwd_Cvs::save() – Save changes

Synopsis

mixed File_Passwd_Cvs::save ( )

Description

Apply changes and rewrite CVS passwd file.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::parse | PEAR Manual | File_Passwd_Cvs::addUser


File_Passwd_Cvs::addUser

File_Passwd_Cvs::addUser

File_Passwd_Cvs::addUser() – Add an user

Synopsis

mixed File_Passwd_Cvs::addUser ( string $user , string $pass , string $system_user = '' )

Description

The username must start with an alphabetical character and must NOT contain any other characters than alphanumerics, the underline and dash.

Parameter

string $user

the name of the user to add

string $pass

the password of the user tot add

string $system_user

the systemuser this user maps to

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_ALREADY | user already exists
FILE_PASSWD_E_INVALID_CHARS | user or system_user contain illegal characters

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::save | PEAR Manual | File_Passwd_Cvs::changeSysUser


File_Passwd_Cvs::changeSysUser

File_Passwd_Cvs::changeSysUser

File_Passwd_Cvs::changeSysUser() – Change syste user

Synopsis

mixed File_Passwd_Cvs::changeSysUser ( mixed $user , mixed $system )

Description

Change the corresponding system user of a certain cvs user.

Parameter

string $user

the user to change the system user for

string $system

the new system user name

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_E_INVALID_CHARS | system user contains illegal characters

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::addUser | PEAR Manual | File_Passwd_Cvs::changePasswd


File_Passwd_Cvs::changePasswd

File_Passwd_Cvs::changePasswd

File_Passwd_Cvs::changePasswd() – Change password

Synopsis

mixed File_Passwd_Cvs::changePasswd ( mixed $user , mixed $pass )

Description

Change the password of a certain user.

Parameter

string $user

the user whose password should be changed

string $pass

the new plaintext password

Return value

$return.success-pearerror;

Returns PEAR_Error FILE_PASSWD_E_EXISTS_ALREADY, if user already exists.

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::changeSysUser | PEAR Manual | File_Passwd_Cvs::verifyPasswd


File_Passwd_Cvs::verifyPasswd

File_Passwd_Cvs::verifyPasswd

File_Passwd_Cvs::verifyPasswd() – Verify password

Synopsis

mixed File_Passwd_Cvs::verifyPasswd ( string $user , string $pass )

Description

Verify the password of a certain user.

Parameter

string $user

user whose password should be verified

string $pass

the plaintext password that should be verified

Return value

Returns TRUE if passwords equal, FALSE if the don't or PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_EXISTS_NOT, if user doesn't exist.

Note

This function can not be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::changePasswd | PEAR Manual | File_Passwd_Cvs::generatePassword


File_Passwd_Cvs::generatePassword

File_Passwd_Cvs::generatePassword

File_Passwd_Cvs::generatePassword() – Generate password

Synopsis

string File_Passwd_Cvs::generatePassword ( string $pass , string $salt = null )

Description

Generate a "CVS" pserver style password.

Parameter

string $pass

the plaintext password to encrypt

string $salt

the salt to use for encryption (usually empty)

Return value

Returns string encrypted password.

Example

File_Passwd_Cvs::generatePassword()

<?php
require_once 'File/Passwd/Cvs.php';
$pass = File_Passwd_Cvs::generatePassword('secret');
?>

Note

This function should be called statically.

Prev | File_Passwd_Cvs | Next
File_Passwd_Cvs::verifyPasswd | PEAR Manual | File_Passwd_Smb


File_Passwd_Smb

File_Passwd_Smb

Table of Contents
  • File_Passwd_Smb::staticAuth -- Fast authentication
  • File_Passwd_Smb::File_Passwd_Smb -- Constructor
  • File_Passwd_Smb::parse -- Parse file
  • File_Passwd_Smb::save -- Save changes
  • File_Passwd_Smb::addUser -- Add an user
  • File_Passwd_Smb::modUser -- Modify a user
  • File_Passwd_Smb::changePasswd -- Change password
  • File_Passwd_Smb::verifyPasswd -- Verify password
  • File_Passwd_Smb::verifyEncryptedPasswd -- Verify encrypted password
  • File_Passwd_Smb::generatePassword -- Generate password

Manipulate SMB server passwd files. (inherited methods)

Prev | File_Passwd | Next
File_Passwd_Cvs::generatePassword | PEAR Manual | File_Passwd_Smb::staticAuth


File_Passwd_Smb::staticAuth

File_Passwd_Smb::staticAuth

File_Passwd_Smb::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd/Smb.php';

mixed File_Passwd_Smb::staticAuth ( string $file , string $user , string $pass , string $mode )

Description

Static user authentication.

Parameter

string $file

path to passwd file

string $user

user to authenticate

string $pass

plaintext password

string $mode

encryption mode ('nt'|'lm') NTHASH or LMHASH

Return value

Returns TRUE if authenticated, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed /only if auth fails)
FILE_PASSWD_E_INVALID_ENC_MODE | supplied encryption mode was invalid

Note

This function should be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb | PEAR Manual | File_Passwd_Smb::File_Passwd_Smb


File_Passwd_Smb::File_Passwd_Smb

File_Passwd_Smb::File_Passwd_Smb

File_Passwd_Smb::File_Passwd_Smb() – Constructor

Synopsis

require_once 'File/Passwd/Smb.php';

object &new File_Passwd_Smb ( string $file = 'smbpasswd' )

Description

Initialize a new File_Passwd_Smb object with the given path to passwd file.

Parameter

string $file

path to SMB passwd file

Return value

Returns object File_Passwd_Smb.

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::staticAuth | PEAR Manual | File_Passwd_Smb::parse


File_Passwd_Smb::parse

File_Passwd_Smb::parse

File_Passwd_Smb::parse() – Parse file

Synopsis

mixed File_Passwd_Smb::parse ( )

Description

Parse the SMB passwd file. (package developer related)

This usually happens in File_Passwd_Smb::load() .

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_INVALID_FORMAT, if passwd file has invalid format.

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::File_Passwd_Smb | PEAR Manual | File_Passwd_Smb::save


File_Passwd_Smb::save

File_Passwd_Smb::save

File_Passwd_Smb::save() – Save changes

Synopsis

mixed File_Passwd_Smb::save ( )

Description

Apply changes and rewrite SMB passwd file.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::parse | PEAR Manual | File_Passwd_Smb::addUser


File_Passwd_Smb::addUser

File_Passwd_Smb::addUser

File_Passwd_Smb::addUser() – Add an user

Synopsis

mixed File_Passwd_Smb::addUser ( string $user , string $pass , array $params , boolean $isMachine = false )

Description

Add an SMB user/machine account.

Parameter

string $user

the user/machine to add

string $pass

the new plaintext password

array $params

additional properties of account:

  • userid

  • flags

  • lct

  • comment

boolean $isMachine

whether to add an machine account

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_ALREADY | account already exists
FILE_PASSWD_E_INVALID_CHARS | user/machine name contains illegal characters

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::save | PEAR Manual | File_Passwd_Smb::modUser


File_Passwd_Smb::modUser

File_Passwd_Smb::modUser

File_Passwd_Smb::modUser() – Modify a user

Synopsis

mixed File_Passwd_Smb::modUser ( string $user , array $params )

Description

Modify a certain user.

You shouldn't modify the password with this method, use File_Passwd_Smb::changePasswd() instead.

Parameter

string $user

the user to modify

array $params

an associative array of properties to change

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | account doesn't exist
FILE_PASSWD_E_INVALID_PROPERTY | any supplied property was invalid

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::addUser | PEAR Manual | File_Passwd_Smb::changePasswd


File_Passwd_Smb::changePasswd

File_Passwd_Smb::changePasswd

File_Passwd_Smb::changePasswd() – Change password

Synopsis

mixed File_Passwd_Smb::changePasswd ( string $user , string $pass )

Description

Change the passwd of a certain user.

Parameter

string $user

the user whose passwd should be changed

string $pass

the new plaintext passwd

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error FILE_PASSWD_E_EXISTS_NOT, if user doesn't exist.

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::modUser | PEAR Manual | File_Passwd_Smb::verifyPasswd


File_Passwd_Smb::verifyPasswd

File_Passwd_Smb::verifyPasswd

File_Passwd_Smb::verifyPasswd() – Verify password

Synopsis

mixed File_Passwd_Smb::verifyPasswd ( string $user , string $pass )

Description

Verifies an account with the given plaintext password.

Parameter

string $user

username

string $pass

the plaintext password

Return value

Returns TRUE if passwds equal, FALSE if they don't or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_E_UNDEFINED | if account is disabled

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::changePasswd | PEAR Manual | File_Passwd_Smb::verifyEncryptedPasswd


File_Passwd_Smb::verifyEncryptedPasswd

File_Passwd_Smb::verifyEncryptedPasswd

File_Passwd_Smb::verifyEncryptedPasswd() – Verify encrypted password

Synopsis

mixed File_Passwd_Smb::verifyEncryptedPasswd ( string $user , string $nthash , string $lmhash = '' )

Description

Verify the encrypted password of an user/machine.

We prefer NT-Hash instead of weak LAN-Manager-Hash.

Parameter

string $user

username

string $nthash

NT-Hash in hex

string $lmhash

LAN-Manager-Hash in hex

Return value

Returns TRUE if passwds equal, FALSE if they don't or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_E_UNDEFINED | if account is disabled

Note

This function can not be called statically.

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::verifyPasswd | PEAR Manual | File_Passwd_Smb::generatePassword


File_Passwd_Smb::generatePassword

File_Passwd_Smb::generatePassword

File_Passwd_Smb::generatePassword() – Generate password

Synopsis

string File_Passwd_Smb::generatePassword ( string $pass , string $mode = 'nt' )

Description

Generate a "Samba" server style password.

The encryption mode can either be FILE_PASSWD_NT or FILE_PASSWD_LM.

Parameter

string $pass

the plaintext password to encrypt

string $mode

the encryption mode to use

Return value

Returns string encrypted password.

Example

File_Passwd_Smb::generatePassword()

<?php
require_once 'File/Passwd/Smb.php';
$pass = File_Passwd_Smb::generatePassword('secret', FILE_PASSWD_LM);
?>

Note

This function should be called statically.

See

See also Crypt_CHAP_MSv1::ntPasswordHash() , Crypt_CHAP_MSv1::lmPasswordHash() .

Prev | File_Passwd_Smb | Next
File_Passwd_Smb::verifyEncryptedPasswd | PEAR Manual | File_Passwd_Authbasic


File_Passwd_Authbasic

File_Passwd_Authbasic

Table of Contents
  • File_Passwd_Authbasic::staticAuth -- Fast authentication
  • File_Passwd_Authbasic::File_Passwd_Authbasic -- Constructor
  • File_Passwd_Authbasic::parse -- Parse the AuthUserFile
  • File_Passwd_Authbasic::save -- Save changes
  • File_Passwd_Authbasic::addUser -- Add an user
  • File_Passwd_Authbasic::changePasswd -- Change password
  • File_Passwd_Authbasic::verifyPasswd -- Verify password
  • File_Passwd_Authbasic::getMode -- Get actual encryption mode
  • File_Passwd_Authbasic::setMode -- Set the encryption mode
  • File_Passwd_Authbasic::listModes -- Get supported encryption modes
  • File_Passwd_Authbasic::generatePassword -- Generate password

Manipulate AuthUserFiles. (inherited methods)

Prev | File_Passwd | Next
File_Passwd_Smb::generatePassword | PEAR Manual | File_Passwd_Authbasic::staticAuth


File_Passwd_Authbasic::staticAuth

File_Passwd_Authbasic::staticAuth

File_Passwd_Authbasic::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd/Authbasic.php';

mixed File_Passwd_Authbasic::staticAuth ( string $file , string $user , string $pass , string $mode )

Description

Static user authentication.

Parameter

string $file

path to passwd file

string $user

user to authenticate

string $pass

plaintext password

string $mode

des, sha or md5

Return value

Returns TRUE if authenticated, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed /only if auth fails)

Note

This function should be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic | PEAR Manual | File_Passwd_Authbasic::File_Passwd_Authbasic


File_Passwd_Authbasic::File_Passwd_Authbasic

File_Passwd_Authbasic::File_Passwd_Authbasic

File_Passwd_Authbasic::File_Passwd_Authbasic() – Constructor

Synopsis

require_once 'File/Passwd/Authbasic.php';

object &new File_Passwd_Authbasic ( string $file = '.htpasswd' )

Description

Initialise a new File_Passwd_Authbasic object with the given path to the passwd file.

Parameter

string $file

path to AuthUserFile

Return value

Returns object File_Passwd_Authbasic.

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::staticAuth | PEAR Manual | File_Passwd_Authbasic::parse


File_Passwd_Authbasic::parse

File_Passwd_Authbasic::parse

File_Passwd_Authbasic::parse() – Parse the AuthUserFile

Synopsis

mixed File_Passwd_Authbasic::parse ( )

Description

Parse the AuthUserFile. (package developer related)

This usually happens in File_Passwd_Authbasic::load() .

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_INVALID_FORMAT | passwd file has invalid format

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::File_Passwd_Authbasic | PEAR Manual | File_Passwd_Authbasic::save


File_Passwd_Authbasic::save

File_Passwd_Authbasic::save

File_Passwd_Authbasic::save() – Save changes

Synopsis

mixed File_Passwd_Authbasic::save ( )

Description

Apply changes and rewrite AuthUserFile.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::parse | PEAR Manual | File_Passwd_Authbasic::addUser


File_Passwd_Authbasic::addUser

File_Passwd_Authbasic::addUser

File_Passwd_Authbasic::addUser() – Add an user

Synopsis

mixed File_Passwd_Authbasic::addUser ( string $user , string $pass )

Description

The username must start with an alphabetical character and must NOT contain any other characters than alphanumerics, the underline and dash.

Parameter

string $user

username

string $pass

plaintext password

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_ALREADY | the user to add already exists
FILE_PASSWD_E_INVALID_CHARS | the username to add contains illegal characters

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::save | PEAR Manual | File_Passwd_Authbasic::changePasswd


File_Passwd_Authbasic::changePasswd

File_Passwd_Authbasic::changePasswd

File_Passwd_Authbasic::changePasswd() – Change password

Synopsis

mixed File_Passwd_Authbasic::changePasswd ( string $user , string $pass )

Description

Change the password of a certain user.

Parameter

string $user

the user whose password should be changed

string $pass

the new plaintext password

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | the user to delete doesn't exist

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::addUser | PEAR Manual | File_Passwd_Authbasic::verifyPasswd


File_Passwd_Authbasic::verifyPasswd

File_Passwd_Authbasic::verifyPasswd

File_Passwd_Authbasic::verifyPasswd() – Verify password

Synopsis

mixed File_Passwd_Authbasic::verifyPasswd ( string $user , string $pass )

Description

Verify the password of a certain user.

Parameter

string $user

the user whose password should be verified

string $pass

the plaintext password to verify

Return value

Returns TRUE if passwords equal, FALSE if they don't, or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | user doesn't exist
FILE_PASSWD_E_INVALID_ENC_MODE | invalid encryption mode was supplied

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::changePasswd | PEAR Manual | File_Passwd_Authbasic::getMode


File_Passwd_Authbasic::getMode

File_Passwd_Authbasic::getMode

File_Passwd_Authbasic::getMode() – Get actual encryption mode

Synopsis

string File_Passwd_Authbasic::getMode ( )

Description

Get the actual encryption mode.

Return value

string - actual encryption mode

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::verifyPasswd | PEAR Manual | File_Passwd_Authbasic::setMode


File_Passwd_Authbasic::setMode

File_Passwd_Authbasic::setMode

File_Passwd_Authbasic::setMode() – Set the encryption mode

Synopsis

mixed File_Passwd_Authbasic::setMode ( string $mode )

Description

You can choose one of md5, sha or des.

ATTN: DES encryption not available on Win32!

Returns a PEAR_Error if a specific encryption mode is not supported.

Parameter

string $mode

the encryption mode to use

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::getMode | PEAR Manual | File_Passwd_Authbasic::listModes


File_Passwd_Authbasic::listModes

File_Passwd_Authbasic::listModes

File_Passwd_Authbasic::listModes() – Get supported encryption modes

Synopsis

array File_Passwd_Authbasic::listModes ( )

Description

Returns an array of supported encryption modes.

<pre>
array
+ md5
+ sha
+ des
</pre>

ATTN: DES encryption not available on Win32!

Return value

array - supported encryption modes.

Note

This function can not be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::setMode | PEAR Manual | File_Passwd_Authbasic::generatePassword


File_Passwd_Authbasic::generatePassword

File_Passwd_Authbasic::generatePassword

File_Passwd_Authbasic::generatePassword() – Generate password

Synopsis

mixed File_Passwd_Authbasic::generatePassword ( string $pass , string $mode = 'des' , string $salt = null )

Description

Generate a password usable for "AuthBasic" authentication.

The encryption mode can either be FILE_PASSWD_DES, FILE_PASSWD_SHA or FILE_PASSWD_MD5.

Parameter

string $pass

the plaintext password to encrypt

string $mode

the encryption mode to use

string $salt

the salt to use for encryption (usually empty)

Return value

Returns string encrypted password, or PEAR_Error FILE_PASSWD_E_INVALID_ENC_MODE if encryption mode is not supported.

Example

File_Passwd_Authbasic::generatePassword()

<?php
require_once 'File/Passwd/Authbasic.php';
$pass = File_Passwd_Authbasic::generatePassword('secret', FILE_PASSWD_MD5);
?>

Note

This function should be called statically.

Prev | File_Passwd_Authbasic | Next
File_Passwd_Authbasic::listModes | PEAR Manual | File_Passwd_Authdigest


File_Passwd_Authdigest

File_Passwd_Authdigest

Table of Contents
  • File_Passwd_Authdigest::staticAuth -- Fast authentication
  • File_Passwd_Authdigest::File_Passwd_Authdigest -- Constructor
  • File_Passwd_Authdigest::parse -- Parse the AuthDigestFile
  • File_Passwd_Authdigest::save -- Save changes
  • File_Passwd_Authdigest::addUser -- Add an user
  • File_Passwd_Authdigest::changePasswd -- Change password
  • File_Passwd_Authdigest::verifyPasswd -- Verifiy password
  • File_Passwd_Authdigest::delUserInRealm -- Delete a user
  • File_Passwd_Authdigest::listUserInRealm -- List user
  • File_Passwd_Authdigest::userInRealm -- Ckeck if a certain user is in a specific realm
  • File_Passwd_Authdigest::generatePassword -- Generate password

Manipulate AuthDigestFiles. (inherited methods)

Prev | File_Passwd | Next
File_Passwd_Authbasic::generatePassword | PEAR Manual | File_Passwd_Authdigest::staticAuth


File_Passwd_Authdigest::staticAuth

File_Passwd_Authdigest::staticAuth

File_Passwd_Authdigest::staticAuth() – Fast authentication

Synopsis

require_once 'File/Passwd/Authdigest.php';

mixed File_Passwd_Authdigest::staticAuth ( string $file , string $user , string $pass , string $realm )

Description

Static user authentication.

Parameter

string $file

path to passwd file

string $user

user to authenticate

string $pass

plaintext password

string $realm

the realm the user should be in

Return value

Returns TRUE if authenticated, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_NOT_EXISTS | passwd file doesn't exist
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in read mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked shared
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked (only if auth fails)
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed (only if auth fails)

Note

This function should be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest | PEAR Manual | File_Passwd_Authdigest::File_Passwd_Authdigest


File_Passwd_Authdigest::File_Passwd_Authdigest

File_Passwd_Authdigest::File_Passwd_Authdigest

File_Passwd_Authdigest::File_Passwd_Authdigest() – Constructor

Synopsis

require_once 'File/Passwd/Authdigest.php';

object &new File_Passwd_Authdigest ( string $file = '.htdigest' )

Description

Initialize a new object of File_Passwd_Authdigest with the specified path to the AuthDigestFile.

Parameter

string $file

path to AuthDigestFile

Return value

Returns object File_Passwd_Authdigest.

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::staticAuth | PEAR Manual | File_Passwd_Authdigest::parse


File_Passwd_Authdigest::parse

File_Passwd_Authdigest::parse

File_Passwd_Authdigest::parse() – Parse the AuthDigestFile

Synopsis

mixed File_Passwd_Authdigest::parse ( )

Description

Parse the AuthDigestFile. (package developer related)

This usually happens in File_Passwd_Authdigest::load() .

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_INVALID_FORMAT | AuthDigestFile has invalid format

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::File_Passwd_Authdigest | PEAR Manual | File_Passwd_Authdigest::save


File_Passwd_Authdigest::save

File_Passwd_Authdigest::save

File_Passwd_Authdigest::save() – Save changes

Synopsis

mixed File_Passwd_Authdigest::save ( )

Description

Apply changes and rewrite AuthDigestFile.

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_DIR_NOT_CREATED | directory in which the passwd file should reside couldn't be created
FILE_PASSWD_E_FILE_NOT_OPENED | passwd file couldn't be opened in write mode
FILE_PASSWD_E_FILE_NOT_LOCKED | passwd file couldn't be locked exclusively
FILE_PASSWD_E_FILE_NOT_UNLOCKED | passwd file couldn't be unlocked
FILE_PASSWD_E_FILE_NOT_CLOSED | passwd file couldn't be closed

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::parse | PEAR Manual | File_Passwd_Authdigest::addUser


File_Passwd_Authdigest::addUser

File_Passwd_Authdigest::addUser

File_Passwd_Authdigest::addUser() – Add an user

Synopsis

mixed File_Passwd_Authdigest::addUser ( string $user , string $realm , string $pass )

Description

Add an user to the AuthDigestFile.

$user and $realm must start with an alphabetical charachter and must NOT contain any other characters than alphanumerics, the underline and dash.

Parameter

string $user

the user to add

string $realm

the realm the user should be in

string $pass

the plaintext password

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_ALREADY | user already exists in the supplied realm
FILE_PASSWD_E_INVLAID_CHARS | user or realm contains illegal characters

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::save | PEAR Manual | File_Passwd_Authdigest::changePasswd


File_Passwd_Authdigest::changePasswd

File_Passwd_Authdigest::changePasswd

File_Passwd_Authdigest::changePasswd() – Change password

Synopsis

mixed File_Passwd_Authdigest::changePasswd ( string $user , string $realm , string $pass )

Description

Change the password of a certain user in a specific realm.

This method in fact adds the user whith the new password after deleting the user.

Parameter

string $user

the user whose password should be changed

string $realm

the realm the user is in

string $pass

the new plaintext password

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_USER_NOT_IN_REALM | user doesn't exist in the supplied realm
FILE_PASSWD_E_INVALID_CHARS | user or realm contains illegal characters

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::addUser | PEAR Manual | File_Passwd_Authdigest::verifyPasswd


File_Passwd_Authdigest::verifyPasswd

File_Passwd_Authdigest::verifyPasswd

File_Passwd_Authdigest::verifyPasswd() – Verifiy password

Synopsis

mixed File_Passwd_Authdigest::verifyPasswd ( string $user , string $realm , string $pass )

Description

Verify the password of an user in a certain realm.

Parameter

string $user

the user whose password should be verified

string $realm

the realm the user is in

string $pass

the plaintext password to verify

Return value

Retruns TRUE if passwords equal, FALSE if they don't, or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_USER_NOT_IN_REALM | the specified user doesn't exist in the supplied realm

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::changePasswd | PEAR Manual | File_Passwd_Authdigest::delUserInRealm


File_Passwd_Authdigest::delUserInRealm

File_Passwd_Authdigest::delUserInRealm

File_Passwd_Authdigest::delUserInRealm() – Delete a user

Synopsis

mixed File_Passwd_Authdigest::delUserInRealm ( string $user , string $inRealm )

Description

Delete a certain user in a specific realm.

Parameter

string $user

the user to remove

string $inRealm

the realm the user should be in

Return value

Returns TRUE on success, PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_USER_NOT_IN_REALM | user doesn't exist in the supplied realm

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::verifyPasswd | PEAR Manual | File_Passwd_Authdigest::listUserInRealm


File_Passwd_Authdigest::listUserInRealm

File_Passwd_Authdigest::listUserInRealm

File_Passwd_Authdigest::listUserInRealm() – List user

Synopsis

array File_Passwd_Authdigest::listUserInRealm ( string $inRealm = '' )

Description

List all user af either one specific or all realms.

Parameter

string $inRealm

the realm to list users of

Return value

Returns array:

  • associative array of users of ONE realm if $inRealm was supplied
    <pre>
    realm1
    + user1 =&gt; pass
    + user2 =&gt; pass
    + user3 =&gt; pass
    </pre>

  • associative array of all realms with all users
    <pre>
    array
    + realm1 =&gt; array
    + user1 =&amp;gt; pass
    + user2 =&amp;gt; pass
    + user3 =&amp;gt; pass
    + realm2 =&gt; array
    + user3 =&amp;gt; pass
    + realm3 =&gt; array
    + user1 =&amp;gt; pass
    + user2 =&amp;gt; pass
    </pre>

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::delUserInRealm | PEAR Manual | File_Passwd_Authdigest::userInRealm


File_Passwd_Authdigest::userInRealm

File_Passwd_Authdigest::userInRealm

File_Passwd_Authdigest::userInRealm() – Ckeck if a certain user is in a specific realm

Synopsis

require_once 'Passwd/Authdigest.php';

boolean File_Passwd_Authdigest::userInRealm ( string $user , string $realm )

Description

Ckeck if a certain user is in a specific realm.

Parameter

string $user

the user to check

string $realm

the realm the user shuold be in

Return value

Returns TRUE if user is in realm, FALSE if not or PEAR_Error on failure.

Possible PEAR_Error values
Error Code | Summary
FILE_PASSWD_E_EXISTS_NOT | specified realm doesn't exist

Note

This function can not be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::listUserInRealm | PEAR Manual | File_Passwd_Authdigest::generatePassword


File_Passwd_Authdigest::generatePassword

File_Passwd_Authdigest::generatePassword

File_Passwd_Authdigest::generatePassword() – Generate password

Synopsis

string File_Passwd_Authdigest::generatePassword ( string $user , string $realm , string $pass )

Description

Generate a password usable for "AuthDigest" authentication.

Parameter

string $user

the username

string $realm

the realm the user is in

string $pass

the plaintext password

Return value

Returns string encrypted password.

Example

File_Passwd_Authdigest::generatePassword()

<?php
require_once 'File/Passwd/Authdigest.php';
$pass = File_Passwd_Authdigest::generatePassword('mike', 'restricted', 'secret');
?>

Note

This function should be called statically.

Prev | File_Passwd_Authdigest | Next
File_Passwd_Authdigest::userInRealm | PEAR Manual | MP3_Id


MP3_Id

MP3_Id

This package offers methods for reading and writing IDv1-information tags of MP3 files.

Table of Contents
  • Constants -- Constants defined in and used by MP3_Id
  • MP3_Id::MP3_Id -- constructor
  • MP3_Id::copy -- copy the tags of another instance
  • MP3_Id::genres -- get Genre list
  • MP3_Id::getGenre -- return genre name by number
  • MP3_Id::getGenreNo -- get number of genre
  • MP3_Id::getTag -- get the value of a tag
  • MP3_Id::read -- reads and parses file
  • MP3_Id::remove -- remove tags
  • MP3_Id::setTag -- sets a tag content
  • MP3_Id::study -- does extra work to get the MPEG frame info
  • MP3_Id::write -- save changed tags
Prev | File Formats | Next
File_Passwd_Authdigest::generatePassword | PEAR Manual | Constants


Constants

Constants

Constants – Constants defined in and used by MP3_Id

All Constants

Constants defined in Id.php

Constants
Name | Value | Meaning
PEAR_MP3_ID_FNO | 1 | Error code: file not found
PEAR_MP3_ID_NOMP3 | 4 | Error code: file is not a MP3 file
PEAR_MP3_ID_RE | 2 | Error code: read error
PEAR_MP3_ID_TNF | 3 | Error code: Tag not found
Prev | MP3_Id | Next
MP3_Id | PEAR Manual | MP3_Id::MP3_Id


MP3_Id::MP3_Id

MP3_Id::MP3_Id

MP3_Id::MP3_Id() – constructor

Synopsis

require_once 'Id.php';

void MP3_Id::MP3_Id ( boolean $study = false )

Description

Constructor

Parameter

boolean $study

Enables an in-deep look in the file (increase execution time!)

Note

This function can not be called statically.

Prev | MP3_Id | Next
Constants | PEAR Manual | MP3_Id::copy


MP3_Id::copy

MP3_Id::copy

MP3_Id::copy() – copy the tags of another instance

Synopsis

require_once 'Id.php';

void MP3_Id::copy ( string $from )

Description

Sets the ID3 tags to the same as the tags in $from

Parameter

string $from

Name of the variable storing an other instance of MP3_Id

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::MP3_Id | PEAR Manual | MP3_Id::genres


MP3_Id::genres

MP3_Id::genres

MP3_Id::genres() – get Genre list

Synopsis

require_once 'Id.php';

array MP3_Id::genres ( )

Description

Returns a list of genre numbers and names

Return value

array - list of genres

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::copy | PEAR Manual | MP3_Id::getGenre


MP3_Id::getGenre

MP3_Id::getGenre

MP3_Id::getGenre() – return genre name by number

Synopsis

require_once 'Id.php';

mixed MP3_Id::getGenre ( integer $genreno )

Description

Return the name of a genre number, if no genre number is specified the genre number found in the file will be used.

Parameter

integer $genreno

Number of the genre

Return value

mixed FALSE, if no genre found, else string

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::genres | PEAR Manual | MP3_Id::getGenreNo


MP3_Id::getGenreNo

MP3_Id::getGenreNo

MP3_Id::getGenreNo() – get number of genre

Synopsis

require_once 'Id.php';

integer MP3_Id::getGenreNo ( string $genre , integer $default = 0xff )

Description

Get the number of a genre.

Parameter

string $genre

Name of the genre

integer $default

The value to return in case of genre not found

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::getGenre | PEAR Manual | MP3_Id::getTag


MP3_Id::getTag

MP3_Id::getTag

MP3_Id::getTag() – get the value of a tag

Synopsis

require_once 'Id.php';

mixed MP3_Id::getTag ( string $name , mixed $default )

Description

Get the value of a tag

Parameter

string $name

the name of the tag to get

mixed $default

returned, if the tag not exists

Return value

mixed The value of the field

See

MP3_Id::setTag()

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::getGenreNo | PEAR Manual | MP3_Id::read


MP3_Id::read

MP3_Id::read

MP3_Id::read() – reads and parses file

Synopsis

require_once 'Id.php';

void MP3_Id::read ( string $file )

Description

Reads the given file and parses it.

Parameter

string $file

the name of the file to parse

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
PEAR_MP3_ID_FNO | "Unable to open $file" | The provide file name could not be opened | The file is currently write protected or doesn't exists.
PEAR_MP3_ID_RE | "Unable to see to end - 128 of $file" or "Unable to see to end of $file" | A read error occured | The file is too short or empty - not a MP3 file or a corrupted one.

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::getTag | PEAR Manual | MP3_Id::remove


MP3_Id::remove

MP3_Id::remove

MP3_Id::remove() – remove tags

Synopsis

require_once 'Id.php';

void MP3_Id::remove ( boolean $id3v1 = true , boolean $id3v2 = true )

Description

Removes all tags from a file.

Parameter

boolean $id3v1

TRUE to remove tags

boolean $id3v2

unused

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
PEAR_MP3_ID_FNO | "Unable to open $file" | The provide file name could not be opened | The file is currently write protected or doesn't exists.
PEAR_MP3_ID_RE | "Unable to see to end - 128 of $file" or "Unable to see to end of $file" | A read error occured | The file is too short or empty - not a MP3 file or a corrupted one.

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::read | PEAR Manual | MP3_Id::setTag


MP3_Id::setTag

MP3_Id::setTag

MP3_Id::setTag() – sets a tag content

Synopsis

require_once 'Id.php';

void MP3_Id::setTag ( mixed $name , mixed $value )

Description

Sets a field

Possible names of tags are:
Tag | Meaning
name | Title of the content
artists | Name of band or artist
album | Name of the album
year | publishing year of the album or song
comment | song comment
track | the number of the track
genre | genre of the song
genreno | Number of the genre

Parameter

mixed $name

Name of the tag to set or hash with the key as fieldname

mixed $value

the value to set

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::remove | PEAR Manual | MP3_Id::study


MP3_Id::study

MP3_Id::study

MP3_Id::study() – does extra work to get the MPEG frame info

Synopsis

require_once 'Id.php';

void MP3_Id::study ( ( void )

Description

Does extra work to get the MPEG frame info.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
PEAR_MP3_ID_NOMP3 | "No mpeg frame found" | The file have no MP3 file structure. | The file is not a MP3 file.

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::setTag | PEAR Manual | MP3_Id::write


MP3_Id::write

MP3_Id::write

MP3_Id::write() – save changed tags

Synopsis

require_once 'Id.php';

void MP3_Id::write ( boolean $v1 = true )

Description

Updates the tags on the file.

Parameter

boolean $v1

if TRUE update/create an Version 1-tag on the file

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
PEAR_MP3_ID_FNO | "Unable to open $file" | The provide file name could not be opened | The file is currently write protected or doesn't exists.
PEAR_MP3_ID_RE | "Unable to see to end - 128 of $file" or "Unable to see to end of $file" | A read error occured | The file is too short or empty - not a MP3 file or a corrupted one.

Note

This function can not be called statically.

Prev | MP3_Id | Next
MP3_Id::study | PEAR Manual | OpenDocument


OpenDocument

OpenDocument

The OpenDocument package lets you create office files according to the OASIS OpenDocument specification. As of version 0.1.2, only text documents can be created.

Table of Contents
  • Creating a first text document
Prev | File Formats | Next
MP3_Id::write | PEAR Manual | Creating a first text document


Creating a first text document

Creating a first text document

Creating an OpenDocument text document is really simple.

<?php
/**
* This script demonstrates how to create a new text document by
* adding a headline and a paragraph containing a link.
*/
require_once 'OpenDocument.php';

$doc = new OpenDocument();
$doc->createHeading('Welcome to OpenDocument!', 1);
$p = $doc->createParagraph('This script serves as a demonstration of PEAR\'s
OpenDocument package. You are invited to explore the capabilities of this
package and to read the API documentation available at ');
$p->createHyperlink('pear.php.net', 'http://pear.php.net/package/OpenDocument');
$p->createTextElement('. Have fun!');

$doc->save('my-first-document.odt');
?>

After creating an OpenDocument instance, there are several methods available to create actual content; all of them are prefixed with create.

All of those methods return the created object. This object has already been inserted at the end of the document.

The newly created element may have some create*() methods of its own - a paragraph for example allows you to add links and additional text elements.

When you are done, call OpenDocument::save() with the filename as only parameter to store the document on disk.

Note: Until version 0.1.2, only relative filenames are allowed.
Prev | OpenDocument | Next
OpenDocument | PEAR Manual | Spreadsheet_Excel_Writer


Spreadsheet_Excel_Writer

Spreadsheet_Excel_Writer

Package for generating Excel spreadsheets

Table of Contents
  • Introduction -- how to generate Excel files
  • Formatting Tutorial -- how to format cells in a spreadsheet
  • Workbook::close -- Calls finalization methods for the workbook
  • Workbook::&addWorksheet -- Add a new worksheet to the Excel workbook.
  • Workbook::&addFormat -- Add a new format to the Excel workbook.
  • Workbook::setCountry -- Set the country identifier for the workbook
  • Workbook::&setTempDir -- Sets the temp dir used for storing the OLE file.
  • Workbook::setVersion -- Sets the BIFF version.
  • Workbook::setCustomColor -- Change the RGB components of the elements in the colour palette.
  • Workbook::worksheets -- An accessor for the _worksheets[] array.
  • Worksheet::getName -- Retrieve the worksheet name. This is usefull when creating worksheets
  • Worksheet::setInputEncoding -- Allow writing for different charsets.
  • Worksheet::select -- Set this worksheet as a selected worksheet, i.e. the worksheet has its tab
  • Worksheet::activate -- Set this worksheet as the active worksheet, i.e. the worksheet that is
  • Worksheet::setFirstSheet -- Set this worksheet as the first visible sheet. This is necessary
  • Worksheet::protect -- Set the worksheet protection flag
  • Worksheet::setColumn -- Set the width of a single column or a range of columns.
  • Worksheet::writeCol -- Write an array of values as a column
  • Worksheet::writeRow -- Write an array of values as a row
  • Worksheet::setSelection -- Set which cell or cells are selected in a worksheet
  • Worksheet::freezePanes -- Set panes and mark them as frozen.
  • Worksheet::thawPanes -- Set panes and mark them as unfrozen.
  • Worksheet::hideScreenGridlines -- Set the option to hide gridlines on the worksheet (as seen on the screen).
  • Worksheet::setPortrait -- Set the page orientation as portrait.
  • Worksheet::setLandscape -- Set the page orientation as landscape.
  • Worksheet::setPaper -- Set the paper type. Ex. 1 = US Letter, 9 = A4
  • Worksheet::setHeader -- Set the page header caption and optional margin.
  • Worksheet::setFooter -- Set the page footer caption and optional margin.
  • Worksheet::setMerge -- Sets a merged cell range
  • Worksheet::centerHorizontally -- Center the page horizontally.
  • Worksheet::centerVertically -- Center the page vertically.
  • Worksheet::setMargins -- Set all the page margins to the same value in inches.
  • Worksheet::setMargins_LR -- Set the left and right margins to the same value in inches.
  • Worksheet::setMargins_TB -- Set the top and bottom margins to the same value in inches.
  • Worksheet::setMarginLeft -- Set the left margin in inches.
  • Worksheet::setMarginRight -- Set the right margin in inches.
  • Worksheet::setMarginTop -- Set the top margin in inches.
  • Worksheet::setMarginBottom -- Set the bottom margin in inches.
  • Worksheet::repeatRows -- Set the rows to repeat at the top of each printed page.
  • Worksheet::repeatColumns -- Set the columns to repeat at the left hand side of each printed page.
  • Worksheet::printArea -- Set the area of each worksheet that will be printed.
  • Worksheet::hideGridlines -- Set the option to hide gridlines on the printed page.
  • Worksheet::printRowColHeaders -- Set the option to print the row and column headers on the printed page.
  • Worksheet::fitToPages -- Store the vertical and horizontal number of pages that will define the
  • Worksheet::setHPagebreaks -- Store the horizontal page breaks on a worksheet (for printing).
  • Worksheet::setVPagebreaks -- Store the vertical page breaks on a worksheet (for printing).
  • Worksheet::setZoom -- Set the worksheet zoom factor.
  • Worksheet::setPrintScale -- Set the scale factor for the printed page.
  • Worksheet::write -- Map to the appropriate write method acording to the token recieved.
  • Worksheet::writeNumber -- Write a double to the specified row and column (zero indexed).
  • Worksheet::writeString -- Write a string to the specified row and column (zero indexed).
  • Worksheet::writeNote -- Writes a note associated with the cell given by the row and column.
  • Worksheet::writeBlank -- Write a blank cell to the specified row and column (zero indexed).
  • Worksheet::writeFormula -- Write a formula to the specified row and column (zero indexed).
  • Worksheet::writeUrl -- Write a hyperlink. This is comprised of two elements: the visible label and
  • Worksheet::setRow -- This method is used to set the height and XF format for a row.
  • Worksheet::mergeCells -- This is an Excel97/2000 method. It is required to perform more complicated
  • Worksheet::insertBitmap -- Insert a 24bit bitmap image in a worksheet. The main record required is
  • Worksheet::setOutline -- This method sets the properties for outlining and grouping
  • Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer -- The constructor. It just creates a Workbook
  • Spreadsheet_Excel_Writer::send -- Send HTTP headers for the Excel file.
  • Spreadsheet_Excel_Writer::rowcolToCell -- Utility function for writing formulas.
  • Format::setAlign -- Set cell alignment.
  • Format::setVAlign -- Set cell alignment.
  • Format::setHAlign -- Set cell alignment.
  • Format::setMerge -- This is an alias for the unintuitive setAlign('merge')
  • Format::setLocked -- Locks a cell.
  • Format::setUnLocked -- Unlocks a cell. Useful for unprotecting particular cells of a protected sheet.
  • Format::setBold -- Sets the boldness of the text.
  • Format::setBottom -- Sets the width for the bottom border of the cell
  • Format::setTop -- Sets the width for the top border of the cell
  • Format::setLeft -- Sets the width for the left border of the cell
  • Format::setRight -- Sets the width for the right border of the cell
  • Format::setBorder -- Set cells borders to the same style
  • Format::setBorderColor -- Sets all the cell's borders to the same color
  • Format::setBottomColor -- Sets the cell's bottom border color
  • Format::setTopColor -- Sets the cell's top border color
  • Format::setLeftColor -- Sets the cell's left border color
  • Format::setRightColor -- Sets the cell's right border color
  • Format::setFgColor -- Sets the cell's foreground color
  • Format::setBgColor -- Sets the cell's background color
  • Format::setColor -- Sets the color of a cell's content
  • Format::setPattern -- Sets the fill pattern attribute of a cell
  • Format::setUnderline -- Sets the underline of the text
  • Format::setItalic -- Sets the font style as italic
  • Format::setSize -- Sets the font size
  • Format::setTextWrap -- Sets text wrapping
  • Format::setTextRotation -- Sets the orientation of the text
  • Format::setNumFormat -- Sets the numeric format.
  • Format::setStrikeOut -- Sets font as strikeout.
  • Format::setOutLine -- Sets outlining for a font.
  • Format::setShadow -- Sets font as shadow.
  • Format::setScript -- Sets the script type of the text
  • Format::setFontFamily -- Sets the font family.
Prev | File Formats | Next
Creating a first text document | PEAR Manual | Introduction


Introduction

Introduction

Introduction – how to generate Excel files

What is Spreadsheet_Excel_Writer?

Spreadsheet_Excel_Writer is a tool for creating Excel files without the need for COM components. The files generated by the current version of Spreadsheet_Excel_Writer correspond to the Excel 5 (BIFF5) format, so all functionality until that version of Excel (but not beyond) should be available.

Using it

The most common use for Spreadsheet_Excel_Writer will be spitting out large (or not so large) amounts of information in the form of a spreadsheet, which is easy to manipulate with a fairly ubiquitous spreadsheet program such as Excel (or OpenOffice).

So let's cut to the chase and see how this is done:

Typical usage

<?php
require_once 'Spreadsheet/Excel/Writer.php';

// Creating a workbook
$workbook = new Spreadsheet_Excel_Writer();

// sending HTTP headers
$workbook->send('test.xls');

// Creating a worksheet
$worksheet =& $workbook->addWorksheet('My first worksheet');

// The actual data
$worksheet->write(0, 0, 'Name');
$worksheet->write(0, 1, 'Age');
$worksheet->write(1, 0, 'John Smith');
$worksheet->write(1, 1, 30);
$worksheet->write(2, 0, 'Johann Schmidt');
$worksheet->write(2, 1, 31);
$worksheet->write(3, 0, 'Juan Herrera');
$worksheet->write(3, 1, 32);

// Let's send the file
$workbook->close();
?>

The first thing you should notice, is that we created a workbook before any worksheets. All worksheets are contained within a workbook, and a workbook may contain several worksheets.

Another important thing, which you should have in mind when programming with Spreadsheet_Excel_Writer, is that ampersand sign (&) that appears when we created our worksheet. That ampersand means we are referencing a Worksheet object instead of copying it. If you don't know what that means, don't worry, all you have to remember is to always use ampersands when calling addWorksheet() for creating a worksheet, or addFormat() for creating a format.

Saving to a regular file

You may have noticed also the following line:

// sending HTTP headers
$workbook->send('test.xls');

What that means is that we are sending our spreadsheet to a browser. But what if we just want to save the spreadsheet in our machine? Well, you just have to omit that line and give a valid file path to the workbook constructor.

For example, if we wanted to save the same spreadsheet we created in our first example to a file named 'test.xls', we would do it like so:

Saving to a regular file

<?php
require_once 'Spreadsheet/Excel/Writer.php';

// We give the path to our file here
$workbook = new Spreadsheet_Excel_Writer('test.xls');

$worksheet =& $workbook->addWorksheet('My first worksheet');

$worksheet->write(0, 0, 'Name');
$worksheet->write(0, 1, 'Age');
$worksheet->write(1, 0, 'John Smith');
$worksheet->write(1, 1, 30);
$worksheet->write(2, 0, 'Johann Schmidt');
$worksheet->write(2, 1, 31);
$worksheet->write(3, 0, 'Juan Herrera');
$worksheet->write(3, 1, 32);

// We still need to explicitly close the workbook
$workbook->close();
?>

More tutorials

If you would like to learn about formatting (fonts, cell color, text alignment, etc...) with Spreadsheet_Excel_Writer, you can check the formatting tutorial here.

Prev | Spreadsheet_Excel_Writer | Next
Spreadsheet_Excel_Writer | PEAR Manual | Formatting Tutorial


Formatting Tutorial

Formatting Tutorial

Formatting Tutorial – how to format cells in a spreadsheet

What is a format?

A format is an object of type Spreadsheet_Excel_Writer_Format. This format can be applied to cells inside a spreadsheet so that these cells inherit the properties of the format (text alignment, background color, border colors, etc...).

Using it

Formats can't be created directly by a new call. You have to create a format using the addFormat() method from a Workbook, which associates your Format with this Workbook (you can't use the Format with another Workbook).

Let's see how addFormat() is used:

addFormat usage

<?php
require_once 'Spreadsheet/Excel/Writer.php';

// Creating a workbook
$workbook = new Spreadsheet_Excel_Writer();

// Creating the format
$format_bold =& $workbook->addFormat();
$format_bold->setBold();

?>

There, we just created a bold format. Notice the ampersand sign (&) that appears when we created our format. If you don't create your format like that it will appear as if all the format's properties you set are ignored.

Making something useful

Well, we just created our first format, but we didn't use it. Not very smart. So let's do something useful with a format.

Let's say you want to make your regular data filled spreadsheet. Only this time, when you proudly present your beautiful creation to your boss, the thing you most dread happens:

Pointy haired boss - Mmmmhhh, seems OK.

You - Yes, I added those totals as you requested.

Pointy haired boss - Mmmmhhh, you know, there's going to be a lot of customers using this spreadsheet...

You - So...

Pointy haired boss - Mmmmhhh, what do you think of changing the style for those headers there?

You - ...

Of course it won't be just those headers: "why don't we center this title here?", "Could you merge those cells over there?", "what do you think of using the company's colors for those titles?".

There are a number of ways for dealing with this situation, but in this tutorial we will stick to the one which will keep your job.

So let's begin work on the spreadsheet for DotCom.com.

First example

<?php
require_once 'Spreadsheet/Excel/Writer.php';
$workbook = new Spreadsheet_Excel_Writer();

$format_bold =& $workbook->addFormat();
$format_bold->setBold();

// We need a worksheet in which to put our data
$worksheet =& $workbook->addWorksheet();
// This is our title
$worksheet->write(0, 0, "Profits for Dotcom.Com", $format_bold);
// And now the data
$worksheet->write(0, 0, 0);

?>

There. Now all of those VC's out there are going to be calling like crazy asking for an oportunity to invest on DotCom.com. Wait a minute. These are not regular VC's we are talking about. These are very selective guys who wouldn't trust their money to the first start-up they happen to see on the internet. I know! Let's put the company's colors in there!

Second example

<?php
require_once 'Spreadsheet/Excel/Writer.php';
$workbook = new Spreadsheet_Excel_Writer();

$format_bold =& $workbook->addFormat();
$format_bold->setBold();

$format_title =& $workbook->addFormat();
$format_title->setBold();
$format_title->setColor('yellow');
$format_title->setPattern(1);
$format_title->setFgColor('blue');

$worksheet =& $workbook->addWorksheet();
$worksheet->write(0, 0, "Quarterly Profits for Dotcom.Com", $format_title);
// While we are at it, why not throw some more numbers around
$worksheet->write(1, 0, "Quarter", $format_bold);
$worksheet->write(1, 1, "Profit", $format_bold);
$worksheet->write(2, 0, "Q1");
$worksheet->write(2, 1, 0);
$worksheet->write(3, 0, "Q2");
$worksheet->write(3, 1, 0);

$workbook->send('test.xls');
$workbook->close();
?>

Merging cells

If you just tested the previous example you might have noticed that the title would need several cells to be seen correctly, but the format we applied only works for the first cell. So our title does not look very nice.

What can we do to fix that? Well, you could tell your boss that the title looks ok to you, and that he really needs to visit an ophthalmologist. Or you could use cell merging in order to make the title spread over several cells.

For this you have to use the setAlign() method with 'merge' as argument, and create some empty cells so the title can 'use' them as a sort of background (there will be a better way to do this in a future version of Spreadsheet_Excel_Writer).

Applying merging to our example script, we would have this:

Merging cells

<?php
require_once 'Spreadsheet/Excel/Writer.php';
$workbook = new Spreadsheet_Excel_Writer();

$format_bold =& $workbook->addFormat();
$format_bold->setBold();

$format_title =& $workbook->addFormat();
$format_title->setBold();
$format_title->setColor('yellow');
$format_title->setPattern(1);
$format_title->setFgColor('blue');
// let's merge
$format_title->setAlign('merge');

$worksheet =& $workbook->addWorksheet();
$worksheet->write(0, 0, "Quarterly Profits for Dotcom.Com", $format_title);
// Couple of empty cells to make it look better
$worksheet->write(0, 1, "", $format_title);
$worksheet->write(0, 2, "", $format_title);
$worksheet->write(1, 0, "Quarter", $format_bold);
$worksheet->write(1, 1, "Profit", $format_bold);
$worksheet->write(2, 0, "Q1");
$worksheet->write(2, 1, 0);
$worksheet->write(3, 0, "Q2");
$worksheet->write(3, 1, 0);

$workbook->send('test.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Introduction | PEAR Manual | Workbook::close


Workbook::close

Workbook::close

Workbook::close – Calls finalization methods for the workbook

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

mixed Workbook::close ( )

Description

Calls finalization methods for the workbook. This method should always be the last one to be called on every workbook.

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Formatting Tutorial | PEAR Manual | Workbook::&addWorksheet


Workbook::&addWorksheet

Workbook::&addWorksheet

Workbook::&addWorksheet – Add a new worksheet to the Excel workbook.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

object reference Workbook::&addWorksheet ( string $name='' )

Description

Add a new worksheet to the Excel workbook. If no name is given the name of the worksheet will be Sheeti with i in [1..].

Parameter

  • string $name - the optional name of the worksheet. Can not be longer than 31 characters.

Return value

returns a reference to a worksheet object on success, PEAR_Error on failure

Note

This function can not be called statically.

Example

Using &addWorksheet()

<?php
require_once 'Spreadsheet/Excel/Writer.php';
$workbook = new Spreadsheet_Excel_Writer('test.xls');
$worksheet =& $workbook->addWorksheet('My first worksheet');
if (PEAR::isError($worksheet)) {
    die($worksheet->getMessage());
}
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Workbook::close | PEAR Manual | Workbook::&addFormat


Workbook::&addFormat

Workbook::&addFormat

Workbook::&addFormat – Add a new format to the Excel workbook.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

object reference Workbook::&addFormat ( array $properties=array() )

Description

Add a new format to the Excel workbook. Also, pass any properties to the Format constructor. Valid properties are:

  • Align

  • Bold

  • Bottom

  • Top

  • Left

  • Right

  • Border

  • BorderColor

  • BottomColor

  • TopColor

  • RightColor

  • LeftColor

  • FgColor

  • BgColor

  • Color

  • Pattern

  • Underline

  • TextRotation

  • Size

  • NumFormat

  • Script

Parameter

  • array $properties - array with properties for initializing the format.

Return value

object reference - to an Excel Format

Note

This function can not be called statically.

Example

Using &addFormat()

<?php
require_once "Spreadsheet/Excel/Writer.php";
$workbook = new Spreadsheet_Excel_Writer();
$format =& $workbook->addFormat(array('Size' => 10,
                                      'Align' => 'center',
                                      'Color' => 'white',
                                      'Pattern' => 1,
                                      'FgColor' => 'magenta'));
$worksheet =& $workbook->addWorksheet();
$worksheet->writeString(1, 0, "Magenta Hello", $format);
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Workbook::&addWorksheet | PEAR Manual | Workbook::setCountry


Workbook::setCountry

Workbook::setCountry

Workbook::setCountry – Set the country identifier for the workbook

Synopsis

require_once 'Spreadsheet/Excel/Writer/Workbook.php';

void Workbook::setCountry ( integer $code )

Description

This package is not documented yet.

Parameter

integer $code

Is the international calling country code for the chosen country.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Workbook::&addFormat | PEAR Manual | Workbook::&setTempDir


Workbook::&setTempDir

Workbook::&setTempDir

Workbook::&setTempDir – Sets the temp dir used for storing the OLE file.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

boolean Workbook::&setTempDir ( string $dir )

Description

Sets the temp dir used for storing the OLE file. Use this method if you don't have the right to write in the default temporary dir.

Parameter

  • string $dir - The dir to be used as temp dir

Return value

boolean - TRUE if given dir is valid, FALSE otherwise

Note

This function can not be called statically.

Example

Using &setTempDir()

<?php
require_once 'Spreadsheet/Excel/Writer.php';
$workbook = new Spreadsheet_Excel_Writer('test.xls');
$worksheet =& $workbook->addWorksheet('My first worksheet');
$workbook->setTempDir('/home/xnoguer/temp');
$worksheet->write(0, 0, "did this work?");
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Workbook::setCountry | PEAR Manual | Workbook::setVersion


Workbook::setVersion

Workbook::setVersion

Workbook::setVersion – Sets the BIFF version.

Synopsis

require_once 'Spreadsheet/Excel/Writer/Workbook.php';

void Workbook::setVersion ( integer $version )

Description

This method exists just to access experimental functionality from BIFF8. It will be deprecated ! Only possible value is 8 (Excel 97/2000). For any other value it fails silently.

Parameter

integer $version

The BIFF version

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Workbook::&setTempDir | PEAR Manual | Workbook::setCustomColor


Workbook::setCustomColor

Workbook::setCustomColor

Workbook::setCustomColor – Change the RGB components of the elements in the colour palette.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

integer Workbook::setCustomColor ( integer $index , integer $red , integer $green , integer $blue )

Description

Change the RGB components of the elements in the colour palette. The new color, defined by the given RGB components, will "overwrite" the color previously defined for the given index.

Parameter

  • integer $index - colour index

  • integer $red - red RGB value [0-255]

  • integer $green - green RGB value [0-255]

  • integer $blue - blue RGB value [0-255]

Return value

integer - The palette index for the custom color

Note

This function can not be called statically.

Example

Using setCustomColor()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

// "regular" green
$format_regular_green =& $workbook->addFormat();
$format_regular_green->setFgColor('green');

// "special" green
$format_special_green =& $workbook->addFormat();
$format_special_green->setFgColor(11);

// our green (overwriting color on index 12)
$workbook->setCustomColor(12, 10, 200, 10);
$format_our_green =& $workbook->addFormat();
$format_our_green->setFgColor(12);

$worksheet->setColumn(0, 0, 30);

$worksheet->write(0, 0, "Regular green", $format_regular_green);
$worksheet->write(1, 0, "Special green (index 11)", $format_special_green);
$worksheet->write(2, 0, "Our green", $format_our_green);

$workbook->send('greens.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Workbook::setVersion | PEAR Manual | Workbook::worksheets


Workbook::worksheets

Workbook::worksheets

Workbook::worksheets – An accessor for the _worksheets[] array.

Synopsis

require_once 'Spreadsheet/Excel/Writer/Workbook.php';

array Workbook::worksheets ( )

Description

Returns an array of the worksheet objects in a workbook

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Workbook::setCustomColor | PEAR Manual | Worksheet::getName


Worksheet::getName

Worksheet::getName

Worksheet::getName – Retrieve the worksheet name. This is usefull when creating worksheets

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

string Worksheet::getName ( )

Description

Retrieve the worksheet name. This is usefull when creating worksheets without a name.

Return value

string - The worksheet's name

Note

This function can not be called statically.

Example

Using getName()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Workbook::worksheets | PEAR Manual | Worksheet::setInputEncoding


Worksheet::setInputEncoding

Worksheet::setInputEncoding

Worksheet::setInputEncoding – Allow writing for different charsets.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setInputEncoding ( string $encoding )

Description

It allows writing for different charsets by setting the worksheet's "current" charset. It has been tested for UTF-8, ISO-8859-7. It requires iconv for any charset other than UTF-16LE.

Parameter

  • string $encoding - The encoding. It suports all encodings supported by php's iconv() function.

Note

This function can not be called statically.

Example

Using setInputEncoding()

<?php
require_once 'Spreadsheet/Excel/Writer.php';
$workbook = new Spreadsheet_Excel_Writer('test.xls');
$workbook->setVersion(8);
$worksheet =& $workbook->addWorksheet('International worksheet');

$russian = "\xD0\xBF\xD0\xBE\xD0\xBA\xD0\xB0";
$greek = "\342\345\353\355\341";

$worksheet->setInputEncoding('ISO-8859-7');
$worksheet->write(0, 0, $greek);
$worksheet->setInputEncoding('utf-8');
$worksheet->write(1, 0, $russian);
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::getName | PEAR Manual | Worksheet::select


Worksheet::select

Worksheet::select

Worksheet::select – Set this worksheet as a selected worksheet, i.e. the worksheet has its tab

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::select ( )

Description

Set this worksheet as a selected worksheet, i.e. the worksheet has its tab highlighted.

Note

This function can not be called statically.

Example

Using select()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setInputEncoding | PEAR Manual | Worksheet::activate


Worksheet::activate

Worksheet::activate

Worksheet::activate – Set this worksheet as the active worksheet, i.e. the worksheet that is

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::activate ( )

Description

Set this worksheet as the active worksheet, i.e. the worksheet that is displayed when the workbook is opened. Also set it as selected.

Note

This function can not be called statically.

Example

Using activate()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::select | PEAR Manual | Worksheet::setFirstSheet


Worksheet::setFirstSheet

Worksheet::setFirstSheet

Worksheet::setFirstSheet – Set this worksheet as the first visible sheet. This is necessary

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setFirstSheet ( )

Description

Set this worksheet as the first visible sheet. This is necessary when there are a large number of worksheets and the activated worksheet is not visible on the screen.

Note

This function can not be called statically.

Example

Using setFirstSheet()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::activate | PEAR Manual | Worksheet::protect


Worksheet::protect

Worksheet::protect

Worksheet::protect – Set the worksheet protection flag

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::protect ( string $password )

Description

Set the worksheet protection flag to prevent accidental modification and to hide formulas if the locked and hidden format properties have been set.

Parameter

  • string $password - The password to use for protecting the sheet.

Note

This function can not be called statically.

Example

Using protect()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setFirstSheet | PEAR Manual | Worksheet::setColumn


Worksheet::setColumn

Worksheet::setColumn

Worksheet::setColumn – Set the width of a single column or a range of columns.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setColumn ( integer $firstcol , integer $lastcol , float $width , mixed $format=0 , integer $hidden=0 )

Description

Set the width of a single column or a range of columns.

Parameter

  • integer $firstcol - first column on the range

  • integer $lastcol - last column on the range

  • float $width - width to set

  • mixed $format - The optional XF format to apply to the columns

  • integer $hidden - The optional hidden atribute

Note

This function can not be called statically.

Example

Using setColumn()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

$radius = 20;
$worksheet->setColumn(0,$radius*2,1);

// Face
for ($i = 0; $i < 360; $i++)
{
    $worksheet->write(floor(sin((2*pi()*$i)/360)*$radius) + $radius + 1, floor(cos((2*pi()*$i)/360)*$radius) + $radius + 1, "x");
}
// Eyes (maybe use a format instead?)
$worksheet->writeURL(floor($radius*0.8), floor($radius*0.8), "0");
$worksheet->writeURL(floor($radius*0.8), floor($radius*1.2), "0");

// Smile
for ($i = 65; $i < 115; $i++)
{
    $worksheet->write(floor(sin((2*pi()*$i)/360)*$radius*1.3) + floor($radius*0.2), floor(cos((2*pi()*$i)/360)*$radius*1.3) + $radius + 1, "x");
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('face.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::protect | PEAR Manual | Worksheet::writeCol


Worksheet::writeCol

Worksheet::writeCol

Worksheet::writeCol – Write an array of values as a column

Synopsis

require_once 'Spreadsheet/Excel/Writer/Worksheet.php';

mixed Worksheet::writeCol ( integer $row , integer $col , array $val , mixed $format = null )

Description

This package is not documented yet.

Parameter

integer $row

The first row (uppermost row) we are writing to

integer $col

The col we are writing to

array $val

The array of values to write

mixed $format

The optional format to apply to the cell

Return value

returns PEAR_Error on failure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setColumn | PEAR Manual | Worksheet::writeRow


Worksheet::writeRow

Worksheet::writeRow

Worksheet::writeRow – Write an array of values as a row

Synopsis

require_once 'Spreadsheet/Excel/Writer/Worksheet.php';

mixed Worksheet::writeRow ( integer $row , integer $col , array $val , mixed $format = null )

Description

This package is not documented yet.

Parameter

integer $row

The row we are writing to

integer $col

The first col (leftmost col) we are writing to

array $val

The array of values to write

mixed $format

The optional format to apply to the cell

Return value

returns PEAR_Error on failure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeCol | PEAR Manual | Worksheet::setSelection


Worksheet::setSelection

Worksheet::setSelection

Worksheet::setSelection – Set which cell or cells are selected in a worksheet

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setSelection ( integer $first_row , integer $first_column , integer $last_row , integer $last_column )

Description

Set which cell or cells are selected in a worksheet

Parameter

  • integer $first_row - first row in the selected quadrant

  • integer $first_column - first column in the selected quadrant

  • integer $last_row - last row in the selected quadrant

  • integer $last_column - last column in the selected quadrant

Note

This function can not be called statically.

Example

Using setSelection()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeRow | PEAR Manual | Worksheet::freezePanes


Worksheet::freezePanes

Worksheet::freezePanes

Worksheet::freezePanes – Set panes and mark them as frozen.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::freezePanes ( array $panes )

Description

Set panes and mark them as frozen. One can use this method to mark certain regions in the worksheet so that they are "frozen" in the sense that when scrolling through the worksheet these regions are not affected by the scrolling and remain where they are on the screen. This is the same functionality as provided by Microsoft Excel through the ->Window->Freeze Panes menu command.

Parameter

  •        array $panes
-
       This is the only parameter received and is composed of the following:
                    0 => Vertical split position,
                    1 => Horizontal split position
                    2 => Top row visible
                    3 => Leftmost column visible
                    4 => Active pane

Note

This function can not be called statically.

Example

Using freezePanes()

<?php
$worksheet =& $workbook->addWorksheet("Some Worksheet");

/* ... */

/* This freezes the first six rows of the worksheet: */
$worksheet->freezePanes(array(6, 0));

/* To freeze the first column, one must use the following syntax: */
$worksheet->freezePanes(array(0, 1));
?>

If one needs to further specify the scrolling region, the following syntax can be used:

<?php
/* Freeze the first six rows and start the scrollable region at row nine: */
$worksheet->freezePanes(array(6, 0, 9, 0));
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setSelection | PEAR Manual | Worksheet::thawPanes


Worksheet::thawPanes

Worksheet::thawPanes

Worksheet::thawPanes – Set panes and mark them as unfrozen.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::thawPanes ( array $panes )

Description

Set panes and mark them as unfrozen.

Parameter

  •        array $panes
-
       This is the only parameter received and is composed of the following:
                    0 => Vertical split position,
                    1 => Horizontal split position
                    2 => Top row visible
                    3 => Leftmost column visible
                    4 => Active pane

Note

This function can not be called statically.

Example

Using thawPanes()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::freezePanes | PEAR Manual | Worksheet::hideScreenGridlines


Worksheet::hideScreenGridlines

Worksheet::hideScreenGridlines

Worksheet::hideScreenGridlines – Set the option to hide gridlines on the worksheet (as seen on the screen).

Synopsis

require_once 'Spreadsheet/Excel/Writer/Worksheet.php';

void Worksheet::hideScreenGridlines ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Worksheet::thawPanes | PEAR Manual | Worksheet::setPortrait


Worksheet::setPortrait

Worksheet::setPortrait

Worksheet::setPortrait – Set the page orientation as portrait.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setPortrait ( )

Description

Set the page orientation as portrait.

Note

This function can not be called statically.

Example

Using setPortrait()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::hideScreenGridlines | PEAR Manual | Worksheet::setLandscape


Worksheet::setLandscape

Worksheet::setLandscape

Worksheet::setLandscape – Set the page orientation as landscape.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setLandscape ( )

Description

Set the page orientation as landscape.

Note

This function can not be called statically.

Example

Using setLandscape()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setPortrait | PEAR Manual | Worksheet::setPaper


Worksheet::setPaper

Worksheet::setPaper

Worksheet::setPaper – Set the paper type. Ex. 1 = US Letter, 9 = A4

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setPaper ( integer $size=0 )

Description

Set the paper type. Ex. 1 = US Letter, 9 = A4

Parameter

  • integer $size - The type of paper size to use

Note

This function can not be called statically.

Example

Using setPaper()

<?php

require_once 'Spreadsheet/Excel/Writer.php';

// Creating a workbook
$workbook = new Spreadsheet_Excel_Writer();

// sending HTTP headers
$workbook->send('test.xls');

// Creating a worksheet
$worksheet =& $workbook->addWorksheet('My first worksheet');

//set paper size
$worksheet->setPaper(9);

// The actual data
$worksheet->write(0, 0, 'Name');
$worksheet->write(0, 1, 'Age');
$worksheet->write(1, 0, 'John Smith');
$worksheet->write(1, 1, 30);
$worksheet->write(2, 0, 'Johann Schmidt');
$worksheet->write(2, 1, 31);
$worksheet->write(3, 0, 'Juan Herrera');
$worksheet->write(3, 1, 32);

// Let's send the file
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setLandscape | PEAR Manual | Worksheet::setHeader


Worksheet::setHeader

Worksheet::setHeader

Worksheet::setHeader – Set the page header caption and optional margin.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setHeader ( string $string , float $margin=0.5 )

Description

Set the page header caption and optional margin.

Parameter

  • string $string - The header text

  • float $margin - optional head margin in inches.

Note

This function can not be called statically.

Example

Using setHeader()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setPaper | PEAR Manual | Worksheet::setFooter


Worksheet::setFooter

Worksheet::setFooter

Worksheet::setFooter – Set the page footer caption and optional margin.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setFooter ( string $string , float $margin=0.5 )

Description

Set the page footer caption and optional margin.

Parameter

  • string $string - The footer text

  • float $margin - optional foot margin in inches.

Note

This function can not be called statically.

Example

Using setFooter()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setHeader | PEAR Manual | Worksheet::setMerge


Worksheet::setMerge

Worksheet::setMerge

Worksheet::setMerge – Sets a merged cell range

Synopsis

require_once 'Spreadsheet/Excel/Writer/Worksheet.php';

void Worksheet::setMerge ( integer $first_row , integer $first_col , integer $last_row , integer $last_col )

Description

This package is not documented yet.

Parameter

integer $first_row

First row of the area to merge

integer $first_col

First column of the area to merge

integer $last_row

Last row of the area to merge

integer $last_col

Last column of the area to merge

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setFooter | PEAR Manual | Worksheet::centerHorizontally


Worksheet::centerHorizontally

Worksheet::centerHorizontally

Worksheet::centerHorizontally – Center the page horizontally.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::centerHorizontally ( integer $center=1 )

Description

Center the page horizontally.

Parameter

  • integer $center - the optional value for centering. Defaults to 1 (center).

Note

This function can not be called statically.

Example

Using centerHorizontally()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMerge | PEAR Manual | Worksheet::centerVertically


Worksheet::centerVertically

Worksheet::centerVertically

Worksheet::centerVertically – Center the page vertically.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::centerVertically ( integer $center=1 )

Description

Center the page vertically.

Parameter

  • integer $center - the optional value for centering. Defaults to 1 (center).

Note

This function can not be called statically.

Example

Using centerVertically()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::centerHorizontally | PEAR Manual | Worksheet::setMargins


Worksheet::setMargins

Worksheet::setMargins

Worksheet::setMargins – Set all the page margins to the same value in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMargins ( float $margin )

Description

Set all the page margins to the same value in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMargins()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::centerVertically | PEAR Manual | Worksheet::setMargins_LR


Worksheet::setMargins_LR

Worksheet::setMargins_LR

Worksheet::setMargins_LR – Set the left and right margins to the same value in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMargins_LR ( float $margin )

Description

Set the left and right margins to the same value in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMargins_LR()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMargins | PEAR Manual | Worksheet::setMargins_TB


Worksheet::setMargins_TB

Worksheet::setMargins_TB

Worksheet::setMargins_TB – Set the top and bottom margins to the same value in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMargins_TB ( float $margin )

Description

Set the top and bottom margins to the same value in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMargins_TB()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMargins_LR | PEAR Manual | Worksheet::setMarginLeft


Worksheet::setMarginLeft

Worksheet::setMarginLeft

Worksheet::setMarginLeft – Set the left margin in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMarginLeft ( float $margin=0.75 )

Description

Set the left margin in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMarginLeft()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMargins_TB | PEAR Manual | Worksheet::setMarginRight


Worksheet::setMarginRight

Worksheet::setMarginRight

Worksheet::setMarginRight – Set the right margin in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMarginRight ( float $margin=0.75 )

Description

Set the right margin in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMarginRight()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMarginLeft | PEAR Manual | Worksheet::setMarginTop


Worksheet::setMarginTop

Worksheet::setMarginTop

Worksheet::setMarginTop – Set the top margin in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMarginTop ( float $margin=1 )

Description

Set the top margin in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMarginTop()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMarginRight | PEAR Manual | Worksheet::setMarginBottom


Worksheet::setMarginBottom

Worksheet::setMarginBottom

Worksheet::setMarginBottom – Set the bottom margin in inches.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setMarginBottom ( float $margin=1 )

Description

Set the bottom margin in inches.

Parameter

  • float $margin - The margin to set in inches

Note

This function can not be called statically.

Example

Using setMarginBottom()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMarginTop | PEAR Manual | Worksheet::repeatRows


Worksheet::repeatRows

Worksheet::repeatRows

Worksheet::repeatRows – Set the rows to repeat at the top of each printed page.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::repeatRows ( integer $first_row , integer $last_row=NULL )

Description

Set the rows to repeat at the top of each printed page.

Parameter

  • integer $first_row - First row to repeat

  • integer $last_row - Last row to repeat. Optional.

Note

This function can not be called statically.

Example

Using repeatRows()

<?php
  require_once 'Spreadsheet/Excel/Writer.php';

  $workbook = new Spreadsheet_Excel_Writer('test.xls');
  $worksheet =& $workbook->addWorkSheet();
  $worksheet->setColumn(0,0,100);
  $worksheet->write(0,0,"99 Bottles Of Beer On The Wall- The Complete Lyrics");
  // repeat only the first row
  $worksheet->repeatRows(0);
  for ($i = 99; $i > 0; $i--)
  {
      if ($i > 1) {
          $next = $i - 1;
      }
      else {
          $next = "no more";
      }
      $worksheet->write(100 - $i,0,"$i Bottles of beer on the wall, $i bottles of beer, ".
                                   "take one down, pass it around, ".
                                   "$next bottles of beer on the wall.");
  }
  $workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setMarginBottom | PEAR Manual | Worksheet::repeatColumns


Worksheet::repeatColumns

Worksheet::repeatColumns

Worksheet::repeatColumns – Set the columns to repeat at the left hand side of each printed page.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::repeatColumns ( integer $first_col , integer $last_col=NULL )

Description

Set the columns to repeat at the left hand side of each printed page.

Parameter

  • integer $first_col - First column to repeat

  • integer $last_col - Last column to repeat. Optional.

Note

This function can not be called statically.

Example

Using repeatColumns()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::repeatRows | PEAR Manual | Worksheet::printArea


Worksheet::printArea

Worksheet::printArea

Worksheet::printArea – Set the area of each worksheet that will be printed.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::printArea ( integer $first_row , integer $first_col , integer $last_row , integer $last_col )

Description

Set the area of each worksheet that will be printed.

Parameter

  • integer $first_row - First row of the area to print

  • integer $first_col - First column of the area to print

  • integer $last_row - Last row of the area to print

  • integer $last_col - Last column of the area to print

Note

This function can not be called statically.

Example

Using printArea()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::repeatColumns | PEAR Manual | Worksheet::hideGridlines


Worksheet::hideGridlines

Worksheet::hideGridlines

Worksheet::hideGridlines – Set the option to hide gridlines on the printed page.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::hideGridlines ( )

Description

Set the option to hide gridlines on the printed page.

Note

This function can not be called statically.

Example

Using hideGridlines()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

$radius = 20;
$worksheet->setColumn(0,$radius*2,1);

// Face
for ($i = 0; $i < 360; $i++)
{
    $worksheet->write(floor(sin((2*pi()*$i)/360)*$radius) + $radius + 1, floor(cos((2*pi()*$i)/360)*$radius) + $radius + 1, "x");
}
// Eyes (maybe use a format instead?)
$worksheet->writeURL(floor($radius*0.8), floor($radius*0.8), "0");
$worksheet->writeURL(floor($radius*0.8), floor($radius*1.2), "0");

// Smile
for ($i = 65; $i < 115; $i++)
{
    $worksheet->write(floor(sin((2*pi()*$i)/360)*$radius*1.3) + floor($radius*0.2), floor(cos((2*pi()*$i)/360)*$radius*1.3) + $radius + 1, "x");
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('face.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::printArea | PEAR Manual | Worksheet::printRowColHeaders


Worksheet::printRowColHeaders

Worksheet::printRowColHeaders

Worksheet::printRowColHeaders – Set the option to print the row and column headers on the printed page.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::printRowColHeaders ( integer $print=1 )

Description

Set the option to print the row and column headers on the printed page.

Parameter

  • integer $print - Whether to print the headers or not. Defaults to 1 (print).

Note

This function can not be called statically.

Example

Using printRowColHeaders()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::hideGridlines | PEAR Manual | Worksheet::fitToPages


Worksheet::fitToPages

Worksheet::fitToPages

Worksheet::fitToPages – Store the vertical and horizontal number of pages that will define the

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::fitToPages ( integer $width , integer $height )

Description

Store the vertical and horizontal number of pages that will define the maximum area printed. It doesn't seem to work with OpenOffice.

Parameter

  • integer $width - Maximun width of printed area in pages

  • integer $height - Maximun heigth of printed area in pages

Note

This function can not be called statically.

Example

Using fitToPages()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::printRowColHeaders | PEAR Manual | Worksheet::setHPagebreaks


Worksheet::setHPagebreaks

Worksheet::setHPagebreaks

Worksheet::setHPagebreaks – Store the horizontal page breaks on a worksheet (for printing).

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setHPagebreaks ( array $breaks )

Description

Store the horizontal page breaks on a worksheet (for printing). The breaks represent the row after which the break is inserted.

Parameter

  • array $breaks - Array containing the horizontal page breaks

Note

This function can not be called statically.

Example

Using setHPagebreaks()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::fitToPages | PEAR Manual | Worksheet::setVPagebreaks


Worksheet::setVPagebreaks

Worksheet::setVPagebreaks

Worksheet::setVPagebreaks – Store the vertical page breaks on a worksheet (for printing).

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setVPagebreaks ( array $breaks )

Description

Store the vertical page breaks on a worksheet (for printing). The breaks represent the column after which the break is inserted.

Parameter

  • array $breaks - Array containing the vertical page breaks

Note

This function can not be called statically.

Example

Using setVPagebreaks()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setHPagebreaks | PEAR Manual | Worksheet::setZoom


Worksheet::setZoom

Worksheet::setZoom

Worksheet::setZoom – Set the worksheet zoom factor.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setZoom ( integer $scale=100 )

Description

Set the worksheet zoom factor.

Parameter

  • integer $scale - The zoom factor

Note

This function can not be called statically.

Example

Using setZoom()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setVPagebreaks | PEAR Manual | Worksheet::setPrintScale


Worksheet::setPrintScale

Worksheet::setPrintScale

Worksheet::setPrintScale – Set the scale factor for the printed page.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setPrintScale ( integer $scale=100 )

Description

Set the scale factor for the printed page. It turns off the "fit to page" option

Parameter

  • integer $scale - The optional scale factor. Defaults to 100

Note

This function can not be called statically.

Example

Using setPrintScale()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setZoom | PEAR Manual | Worksheet::write


Worksheet::write

Worksheet::write

Worksheet::write – Map to the appropriate write method acording to the token recieved.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::write ( integer $row , integer $col , mixed $token , mixed $format=0 )

Description

Map to the appropriate write method acording to the token recieved.

Parameter

  • integer $row - The row of the cell we are writing to

  • integer $col - The column of the cell we are writing to

  • mixed $token - What we are writing

  • mixed $format - The optional format to apply to the cell

Note

This function can not be called statically.

Example

Using write()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setPrintScale | PEAR Manual | Worksheet::writeNumber


Worksheet::writeNumber

Worksheet::writeNumber

Worksheet::writeNumber – Write a double to the specified row and column (zero indexed).

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::writeNumber ( integer $row , integer $col , float $num , mixed $format=0 )

Description

Write a double to the specified row and column (zero indexed). An integer can be written as a double. Excel will display an integer. $format is optional. Returns 0 : normal termination -2 : row or column out of range

Parameter

  • integer $row - Zero indexed row

  • integer $col - Zero indexed column

  • float $num - The number to write

  • mixed $format - The optional XF format

Note

This function can not be called statically.

Example

Using writeNumber()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::write | PEAR Manual | Worksheet::writeString


Worksheet::writeString

Worksheet::writeString

Worksheet::writeString – Write a string to the specified row and column (zero indexed).

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::writeString ( integer $row , integer $col , string $str , mixed $format=0 )

Description

Write a string to the specified row and column (zero indexed). NOTE: there is an Excel 5 defined limit of 255 characters. $format is optional. Returns 0 : normal termination -1 : insufficient number of arguments -2 : row or column out of range -3 : long string truncated to 255 chars

Parameter

  • integer $row - Zero indexed row

  • integer $col - Zero indexed column

  • string $str - The string to write

  • mixed $format - The XF format for the cell

Note

This function can not be called statically.

Example

Using writeString()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeNumber | PEAR Manual | Worksheet::writeNote


Worksheet::writeNote

Worksheet::writeNote

Worksheet::writeNote – Writes a note associated with the cell given by the row and column.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::writeNote ( integer $row , integer $col , string $note )

Description

Writes a note associated with the cell given by the row and column. NOTE records don't have a length limit.

Parameter

  • integer $row - Zero indexed row

  • integer $col - Zero indexed column

  • string $note - The note to write

Note

This function can not be called statically.

Example

Using writeNote()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeString | PEAR Manual | Worksheet::writeBlank


Worksheet::writeBlank

Worksheet::writeBlank

Worksheet::writeBlank – Write a blank cell to the specified row and column (zero indexed).

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::writeBlank ( integer $row , integer $col , mixed $format )

Description

Write a blank cell to the specified row and column (zero indexed). A blank cell is used to specify formatting without adding a string or a number. A blank cell without a format serves no purpose. Therefore, we don't write a BLANK record unless a format is specified. This is mainly an optimisation for the write_row() and write_col() methods. Returns 0 : normal termination (including no format) -1 : insufficient number of arguments -2 : row or column out of range

Parameter

  • integer $row - Zero indexed row

  • integer $col - Zero indexed column

  • mixed $format - The XF format

Note

This function can not be called statically.

Example

Using writeBlank()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeNote | PEAR Manual | Worksheet::writeFormula


Worksheet::writeFormula

Worksheet::writeFormula

Worksheet::writeFormula – Write a formula to the specified row and column (zero indexed).

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

integer Worksheet::writeFormula ( integer $row , integer $col , string $formula , mixed $format=0 )

Description

Write a formula to the specified row and column (zero indexed). In case of error it will write the error message (instead of the formula) in the corresponding row and column.

Parameter

  • integer $row - Zero indexed row

  • integer $col - Zero indexed column

  • string $formula - The formula text string

  • mixed $format - The optional XF format

Return value

integer - 0 for normal termination, -1 for an error in the formula, -2 for row or column out of range.

Note

This function can not be called statically.

Formulas must start with an equal sign ('=').

Arguments given to an Excel function should be separated by comas (','), not by semicolons (';').

Example

Using writeFormula()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer('formula.xls');
$worksheet =& $workbook->addWorksheet();

$worksheet->write(0, 0, 2);
$worksheet->write(0, 1, "and");
$worksheet->write(0, 2, 2);
$worksheet->write(0, 3, "makes");
$worksheet->writeFormula(0, 4, "=SUM(A1,C1)");

$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeBlank | PEAR Manual | Worksheet::writeUrl


Worksheet::writeUrl

Worksheet::writeUrl

Worksheet::writeUrl – Write a hyperlink. This is comprised of two elements: the visible label and

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::writeUrl ( integer $row , integer $col , string $url , string $string='' , mixed $format=0 )

Description

Write a hyperlink. This is comprised of two elements: the visible label and the invisible link. The visible label is the same as the link unless an alternative string is specified. The label is written using the writeString() method. Therefore the 255 characters string limit applies. $string and $format are optional and their order is interchangeable. The hyperlink can be to a http, ftp, mail, internal sheet, or external directory url. Returns 0 : normal termination -1 : insufficient number of arguments -2 : row or column out of range -3 : long string truncated to 255 chars

Parameter

  • integer $row - Row

  • integer $col - Column

  • string $url - URL string

  • string $string - Alternative label

  • mixed $format - The cell format

Note

This function can not be called statically.

Example

Using writeUrl()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeFormula | PEAR Manual | Worksheet::setRow


Worksheet::setRow

Worksheet::setRow

Worksheet::setRow – This method is used to set the height and XF format for a row.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setRow ( integer $row , integer $height , mixed $format=0 )

Description

This method is used to set the height and XF format for a row. Writes the BIFF record ROW.

Parameter

  • integer $row - The row to set

  • integer $height - Height we are giving to the row. Use NULL to set XF without setting height

  • mixed $format - XF format we are giving to the row

Note

This function can not be called statically.

Example

Using setRow()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::writeUrl | PEAR Manual | Worksheet::mergeCells


Worksheet::mergeCells

Worksheet::mergeCells

Worksheet::mergeCells – This is an Excel97/2000 method. It is required to perform more complicated

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::mergeCells ( integer $first_row , integer $first_col , integer $last_row , integer $last_col )

Description

This is an Excel97/2000 method. It is required to perform more complicated merging than the normal setAlign('merge'). It merges the area given by its arguments.

Parameter

  • integer $first_row - First row of the area to merge

  • integer $first_col - First column of the area to merge

  • integer $last_row - Last row of the area to merge

  • integer $last_col - Last column of the area to merge

Note

This function can not be called statically.

Example

Using mergeCells()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setRow | PEAR Manual | Worksheet::insertBitmap


Worksheet::insertBitmap

Worksheet::insertBitmap

Worksheet::insertBitmap – Insert a 24bit bitmap image in a worksheet. The main record required is

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::insertBitmap ( integer $row , integer $col , string $bitmap , integer $x=0 , integer $y=0 , integer $scale_x=1 , integer $scale_y=1 )

Description

Insert a 24bit bitmap image in a worksheet. The main record required is IMDATA but it must be proceeded by a OBJ record to define its position.

Parameter

  • integer $row - The row we are going to insert the bitmap into

  • integer $col - The column we are going to insert the bitmap into

  • string $bitmap - The bitmap filename

  • integer $x - The horizontal position (offset) of the image inside the cell.

  • integer $y - The vertical position (offset) of the image inside the cell.

  • integer $scale_x - The horizontal scale

  • integer $scale_y - The vertical scale

Note

This function can not be called statically.

Example

Using insertBitmap()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::mergeCells | PEAR Manual | Worksheet::setOutline


Worksheet::setOutline

Worksheet::setOutline

Worksheet::setOutline – This method sets the properties for outlining and grouping

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Worksheet::setOutline ( bool $visible=true , bool $symbols_below=true , bool $symbols_right=true , bool $auto_style=false )

Description

This method sets the properties for outlining and grouping. The defaults correspond to Excel's defaults.

Parameter

  • bool $visible -

  • bool $symbols_below -

  • bool $symbols_right -

  • bool $auto_style -

Note

This function can not be called statically.

Example

Using setOutline()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::insertBitmap | PEAR Manual | Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer


Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer

Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer

Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer – The constructor. It just creates a Workbook

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

object The Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer ( string $filename='' )

Description

The constructor. It just creates a Workbook

Parameter

  • string $filename - The optional filename for the Workbook.

Return value

object The - Workbook created

Note

This function can not be called statically.

Example

Using Spreadsheet_Excel_Writer()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Worksheet::setOutline | PEAR Manual | Spreadsheet_Excel_Writer::send


Spreadsheet_Excel_Writer::send

Spreadsheet_Excel_Writer::send

Spreadsheet_Excel_Writer::send – Send HTTP headers for the Excel file.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Spreadsheet_Excel_Writer::send ( string $filename )

Description

Send HTTP headers with the correct content-type (application/vnd.ms-excel), cache control and filename for the file.

Parameter

  • string $filename - The filename to use for HTTP headers

Note

This function can be called statically, but it is easiest when called from the workbook object.

Example

Using send()

<?php
$workbook->send('filename.xls');
?>
Prev | Spreadsheet_Excel_Writer | Next
Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer | PEAR Manual | Spreadsheet_Excel_Writer::rowcolToCell


Spreadsheet_Excel_Writer::rowcolToCell

Spreadsheet_Excel_Writer::rowcolToCell

Spreadsheet_Excel_Writer::rowcolToCell – Utility function for writing formulas.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

string Spreadsheet_Excel_Writer::rowcolToCell ( integer $row , integer $col )

Description

Utility function for writing formulas. Converts a cell's coordinates to the A1 format.

Parameter

  • integer $row - Row for the cell to convert (0-indexed).

  • integer $col - Column for the cell to convert (0-indexed).

Return value

returns The cell identifier in A1 format on success, PEAR_Error on failure

Example

Using rowcolToCell()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer('rowcol.xls');
$worksheet1 =& $workbook->addWorksheet("rowcol");

$first = 1;
$last = 10;
for ($i = $first; $i <= $last; $i++) {
    $worksheet1->write($i, 1, $i);
}
$cell1 = Spreadsheet_Excel_Writer::rowcolToCell($first, 1);
$cell2 = Spreadsheet_Excel_Writer::rowcolToCell($last, 1);
$worksheet1->write($last + 1, 0, "Total =");
$worksheet1->writeFormula($last + 1, 1, "=SUM($cell1:$cell2)");
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Spreadsheet_Excel_Writer::send | PEAR Manual | Format::setAlign


Format::setAlign

Format::setAlign

Format::setAlign – Set cell alignment.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setAlign ( string $location )

Description

Set cell alignment.

Parameter

  • string $location - alignment for the cell

    Horizontal Alignments (pick one): left, center, right, fill, justify, merge, equal_space.

    Vertical Alignments (pick one): top, vcenter, bottom, vjustify, vequal_space.

    To implement a combination of Horizontal and Vertical Alignments, call this method two times.

Note

This function can not be called statically.

Example

Using setAlign()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

// put text at the top
$format_top =& $workbook->addFormat();
$format_top->setAlign('top');
$format_top->setTextWrap(1);

// center the text horizontally
$format_center =& $workbook->addFormat();
$format_center->setAlign('center');

// put text at the top and center it horizontally
$format_top_center =& $workbook->addFormat();
$format_top_center->setAlign('top');
$format_top_center->setAlign('center');

$worksheet->write(0, 0, 'On top of the world!',
                  $format_top);
$worksheet->write(1, 0, 'c', $format_center);
$worksheet->write(2, 0, 'tc', $format_top_center);

$workbook->send('align.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Spreadsheet_Excel_Writer::rowcolToCell | PEAR Manual | Format::setVAlign


Format::setVAlign

Format::setVAlign

Format::setVAlign – Set cell alignment.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setVAlign ( string $location )

Description

Set cell alignment. This is an alternative to setAlign()

Parameter

  • string $location - alignment for the cell

    top, vcenter, bottom, vjustify, vequal_space.

Note

This function can not be called statically.

Example

Using setVAlign()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

// justify
$format_justify =& $workbook->addFormat('vAlign' => 'vjustify');

// center the text vertically
$format_center =& $workbook->addFormat('vAlign' => 'vcenter');

// justify and center vertically
$format_justify_center =& $workbook->addFormat();
$format_justify_center->setVAlign('vjustify');
$format_justify_center->setVAlign('vcenter');

$worksheet->write(0, 0, 'justify', $format_justify);
$worksheet->write(1, 0, 'center', $format_center);
$worksheet->write(2, 0, 'jc', $format_justify_center);

$workbook->send('align.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setAlign | PEAR Manual | Format::setHAlign


Format::setHAlign

Format::setHAlign

Format::setHAlign – Set cell alignment.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setHAlign ( string $location )

Description

Set cell alignment. This is an alternative to setAlign()

Parameter

  • string $location - alignment for the cell

    left, center, right, fill, justify, merge, equal_space.

Note

This function can not be called statically.

Example

Using setHAlign()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

// put text at the top
$format_top =& $workbook->addFormat();
$format_top->setHAlign('top');
$format_top->setTextWrap(1);

// center the text horizontally
$format_center =& $workbook->addFormat();
$format_center->setHAlign('center');

// put text at the top and center it horizontally
$format_top_center =& $workbook->addFormat();
$format_top_center->setHAlign('top');
$format_top_center->setHAlign('center');

$worksheet->write(0, 0, 'On top of the world!',
                  $format_top);
$worksheet->write(1, 0, 'c', $format_center);
$worksheet->write(2, 0, 'tc', $format_top_center);

$workbook->send('align.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setVAlign | PEAR Manual | Format::setMerge


Format::setMerge

Format::setMerge

Format::setMerge – This is an alias for the unintuitive setAlign('merge')

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setMerge ( )

Description

This is an alias for the unintuitive setAlign('merge')

Note

This function can not be called statically.

Example

Using setMerge()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setHAlign | PEAR Manual | Format::setLocked


Format::setLocked

Format::setLocked

Format::setLocked – Locks a cell.

Synopsis

require_once 'Spreadsheet/Excel/Writer/Format.php';

void Format::setLocked ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Format::setMerge | PEAR Manual | Format::setUnLocked


Format::setUnLocked

Format::setUnLocked

Format::setUnLocked – Unlocks a cell. Useful for unprotecting particular cells of a protected sheet.

Synopsis

require_once 'Spreadsheet/Excel/Writer/Format.php';

void Format::setUnLocked ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Spreadsheet_Excel_Writer | Next
Format::setLocked | PEAR Manual | Format::setBold


Format::setBold

Format::setBold

Format::setBold – Sets the boldness of the text.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setBold ( integer $weight=1 )

Description

Sets the boldness of the text. Bold has a range 100..1000. 0 (400) is normal. 1 (700) is bold.

Parameter

  • integer $weight - Weight for the text, 0 maps to 400 (normal text) 1 maps to 700 (bold text). Valid range is: 100-1000 It's Optional, default is 1 (bold).

Note

This function can not be called statically.

Example

Using setBold()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setUnLocked | PEAR Manual | Format::setBottom


Format::setBottom

Format::setBottom

Format::setBottom – Sets the width for the bottom border of the cell

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setBottom ( integer $style )

Description

Sets the width for the bottom border of the cell

Parameter

  • integer $style - style of the cell border. 1 => thin, 2 => thick.

Note

This function can not be called statically.

Example

Using setBottom()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setBottom(1);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setBold | PEAR Manual | Format::setTop


Format::setTop

Format::setTop

Format::setTop – Sets the width for the top border of the cell

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setTop ( integer $style )

Description

Sets the width for the top border of the cell

Parameter

  • integer $style - style of the cell top border. 1 => thin, 2 => thick.

Note

This function can not be called statically.

Example

Using setTop()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setBottom | PEAR Manual | Format::setLeft


Format::setLeft

Format::setLeft

Format::setLeft – Sets the width for the left border of the cell

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setLeft ( integer $style )

Description

Sets the width for the left border of the cell

Parameter

  • integer $style - style of the cell left border. 1 => thin, 2 => thick.

Note

This function can not be called statically.

Example

Using setLeft()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setTop | PEAR Manual | Format::setRight


Format::setRight

Format::setRight

Format::setRight – Sets the width for the right border of the cell

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setRight ( integer $style )

Description

Sets the width for the right border of the cell

Parameter

  • integer $style - style of the cell right border. 1 => thin, 2 => thick.

Note

This function can not be called statically.

Example

Using setRight()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setLeft | PEAR Manual | Format::setBorder


Format::setBorder

Format::setBorder

Format::setBorder – Set cells borders to the same style

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setBorder ( integer $style )

Description

Set cells borders to the same style

Parameter

  • integer $style - style to apply for all cell borders. 1 => thin, 2 => thick.

Note

This function can not be called statically.

Example

Using setBorder()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setRight | PEAR Manual | Format::setBorderColor


Format::setBorderColor

Format::setBorderColor

Format::setBorderColor – Sets all the cell's borders to the same color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setBorderColor ( mixed $color )

Description

Sets all the cell's borders to the same color

Parameter

  • mixed $color - The color we are setting. Either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setBorderColor()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setBorder | PEAR Manual | Format::setBottomColor


Format::setBottomColor

Format::setBottomColor

Format::setBottomColor – Sets the cell's bottom border color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setBottomColor ( mixed $color )

Description

Sets the cell's bottom border color

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setBottomColor()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setBorderColor | PEAR Manual | Format::setTopColor


Format::setTopColor

Format::setTopColor

Format::setTopColor – Sets the cell's top border color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setTopColor ( mixed $color )

Description

Sets the cell's top border color

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setTopColor()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setBottomColor | PEAR Manual | Format::setLeftColor


Format::setLeftColor

Format::setLeftColor

Format::setLeftColor – Sets the cell's left border color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setLeftColor ( mixed $color )

Description

Sets the cell's left border color

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setLeftColor()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setTopColor | PEAR Manual | Format::setRightColor


Format::setRightColor

Format::setRightColor

Format::setRightColor – Sets the cell's right border color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setRightColor ( mixed $color )

Description

Sets the cell's right border color

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setRightColor()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setLeftColor | PEAR Manual | Format::setFgColor


Format::setFgColor

Format::setFgColor

Format::setFgColor – Sets the cell's foreground color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setFgColor ( mixed $color )

Description

Sets the cell's "foreground color".

The term "foreground color" is misleading. Here, "foreground" means the top layer of a cell's background. To set the color of a cell's contents, use the setColor() method.

The color actually seen may depend on the pattern and background color being used.

The example entitled "How background and foreground colors interact with patterns" is very helpful.

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    See the "Using colors" section, below, for more information.

Using colors

The following colors can be defined by name: black, white, red, green, blue, yellow, magenta and cyan.

To learn what the other indexed colors look like, read Color Palette and the 56 Excel ColorIndex Colors. Beware that the color indexes listed there are displaced by 1 with respect to those used by Spreadsheet_Excel_Writer.

If the predifined colors don't meet your requirements, use the setCustomColor() method.

Note

This function can not be called statically.

Example

Using setFgColor()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

// "regular" green
$format_regular_green =& $workbook->addFormat();
$format_regular_green->setFgColor('green');

// "special" green
$format_special_green =& $workbook->addFormat();
$format_special_green->setFgColor(11);

// our green (overwriting color on index 12)
$workbook->setCustomColor(12, 10, 200, 10);
$format_our_green =& $workbook->addFormat();
$format_our_green->setFgColor(12);

$worksheet->setColumn(0, 0, 30);

$worksheet->write(0, 0, "Regular green", $format_regular_green);
$worksheet->write(1, 0, "Special green (index 11)", $format_special_green);
$worksheet->write(2, 0, "Our green", $format_our_green);

$workbook->send('setFgColor.xls');
$workbook->close();
?>

See

setBgColor(),

setPattern(),

setColor()

Prev | Spreadsheet_Excel_Writer | Next
Format::setRightColor | PEAR Manual | Format::setBgColor


Format::setBgColor

Format::setBgColor

Format::setBgColor – Sets the cell's background color

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setBgColor ( mixed $color )

Description

Sets the cell's "background color".

The term "background color" is misleading. Here, "background" means the bottom layer of a cell's background.

This method only comes into play when creating patterns via the setPattern() method. In general, chances are you are more interested in using the setFgColor() method.

The example entitled "How background and foreground colors interact with patterns" is very helpful.

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setBgColor()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet('testing bg color');
$worksheet->setRow(1, 30);

$format6 =& $workbook->addFormat();
$format6->setBgColor('green');
$format6->setPattern(6);
$worksheet->write(1, 1, 'the bg', $format6);

$workbook->send('setBgColor.xls');
$workbook->close();
?>

See

setFgColor(),

setPattern(),

setColor()

Prev | Spreadsheet_Excel_Writer | Next
Format::setFgColor | PEAR Manual | Format::setColor


Format::setColor

Format::setColor

Format::setColor – Sets the color of a cell's content

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setColor ( mixed $color )

Description

Sets the color of a cell's content

Parameter

  • mixed $color - either a string (like 'blue'), or an integer (range is [8...63]).

    Please see the "Using colors" section of the manual for more information.

Note

This function can not be called statically.

Example

Using setColor()

<?php

?>

See

setFgColor(), setBgColor()

Prev | Spreadsheet_Excel_Writer | Next
Format::setBgColor | PEAR Manual | Format::setPattern


Format::setPattern

Format::setPattern

Format::setPattern – Sets the fill pattern attribute of a cell

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setPattern ( integer $arg=1 )

Description

Sets the fill pattern attribute of a cell. Use in combination with the setBgColor() and setFgColor() methods.

The example entitled "How background and foreground colors interact with patterns" is very helpful.

Parameter

  • integer $arg - Optional. Defaults to 1. Meaningful values are: 0-18. 0 = no background. 1 = solid "background" using the color set by setFgColor().

Note

This function can not be called statically.

Example

How background and foreground colors interact with patterns

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet('testing colors and patterns');
$worksheet->setRow(1, 30);
$worksheet->setRow(2, 30);
$worksheet->setRow(3, 30);

// valid patterns are 0 to 18
for ($i = 0; $i <= 18; $i++)
{
    // green in different patterns
    $another_format1 =& $workbook->addFormat();
    $another_format1->setBgColor('green');
    $another_format1->setPattern($i);
    $worksheet->write(1, $i, "pattern $i", $another_format1);

    // red in different patterns
    $another_format2 =& $workbook->addFormat();
    $another_format2->setFgColor('red');
    $another_format2->setPattern($i);
    $worksheet->write(2, $i, "pattern $i", $another_format2);

    // mixed red and green according to pattern
    $another_format3 =& $workbook->addFormat();
    $another_format3->setBgColor('green');
    $another_format3->setFgColor('red');
    $another_format3->setPattern($i);
    $worksheet->write(3, $i, "pattern $i", $another_format3);
}

$workbook->send('setPattern.xls');
$workbook->close();
?>

See

setFgColor(),

setBgColor(),

setColor()

Prev | Spreadsheet_Excel_Writer | Next
Format::setColor | PEAR Manual | Format::setUnderline


Format::setUnderline

Format::setUnderline

Format::setUnderline – Sets the underline of the text

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setUnderline ( integer $underline )

Description

Sets the underline of the text

Parameter

  • integer $underline - The value for underline. Possible values are 1 => underline, 2 => double underline.

Note

This function can not be called statically.

Example

Using setUnderline()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

  $workbook = new Spreadsheet_Excel_Writer();
  $format_underline =& $workbook->addFormat();
  $format_underline->setUnderline(1);
  $worksheet =& $workbook->addWorksheet();
  $worksheet->write(0, 0, "This is underlined", $format_underline);
  $format_underline->setUnderline(2);
  $worksheet->write(1, 0, "This is twice underlined", $format_underline);
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setPattern | PEAR Manual | Format::setItalic


Format::setItalic

Format::setItalic

Format::setItalic – Sets the font style as italic

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setItalic ( )

Description

Sets the font style as italic

Note

This function can not be called statically.

Example

Using setItalic()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setUnderline | PEAR Manual | Format::setSize


Format::setSize

Format::setSize

Format::setSize – Sets the font size

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setSize ( integer $size )

Description

Sets the font size

Parameter

  • integer $size - The font size (in pixels I think).

Note

This function can not be called statically.

Example

Using setSize()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();
// we can set set all properties on instantiation
$upper_right_side_brick =& $workbook->addFormat(array('right' => 5, 'top' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
// or set all properties one by one
$upper_left_side_brick =& $workbook->addFormat();
$upper_left_side_brick->setLeft(5);
$upper_left_side_brick->setTop(5);
$upper_left_side_brick->setSize(15);
$upper_left_side_brick->setPattern(1);
$upper_left_side_brick->setBorderColor('blue');
$upper_left_side_brick->setFgColor('red');

$lower_right_side_brick =& $workbook->addFormat(array('right' => 5, 'bottom' => 5, 'size' => 15,
                                                      'pattern' => 1, 'bordercolor' => 'blue',
                                                      'fgcolor' => 'red'));
$lower_left_side_brick =& $workbook->addFormat(array('left' => 5, 'bottom' => 5, 'size' => 15,
                                                     'pattern' => 1, 'bordercolor' => 'blue',
                                                     'fgcolor' => 'red'));

$worksheet->setColumn(0, 20, 6);

// Sky
$sky =& $workbook->addFormat(array('fgcolor' => 'cyan', 'pattern' => 1, 'size' => 15));
for ($i = 0; $i <= 10; $i++)
{
    for ($j = 0; $j < 20; $j++) {
        $worksheet->writeBlank($i, $j, $sky);
    }
}

// Cloud
$cloud =& $workbook->addFormat(array('fgcolor' => 'white', 'pattern' => 1, 'size' => 15));
$worksheet->writeBlank(5, 7, $cloud);
$worksheet->writeBlank(4, 8, $cloud);
$worksheet->writeBlank(5, 8, $cloud);
$worksheet->writeBlank(6, 8, $cloud);
$worksheet->writeBlank(4, 9, $cloud);
$worksheet->writeBlank(5, 9, $cloud);
$worksheet->writeBlank(5, 10, $cloud);

// Bricks
for ($j = 0; $j < 20; $j++)
{
    for ($i = 5; $i <= 11; $i++)
    {
        if (($i + $j)%2 == 1) // right side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_right_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_right_side_brick);
        }
        else // left side of brick
        {
            $worksheet->writeBlank(2*$i, $j, $upper_left_side_brick);
            $worksheet->writeBlank(2*$i + 1, $j, $lower_left_side_brick);
        }
    }
}

// hide gridlines so they don't mess with our Excel art.
$worksheet->hideGridLines();

$workbook->send('bricks.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setItalic | PEAR Manual | Format::setTextWrap


Format::setTextWrap

Format::setTextWrap

Format::setTextWrap – Sets text wrapping

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setTextWrap ( )

Description

Sets text wrapping

Note

This function can not be called statically.

Example

Using setTextWrap()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setSize | PEAR Manual | Format::setTextRotation


Format::setTextRotation

Format::setTextRotation

Format::setTextRotation – Sets the orientation of the text

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setTextRotation ( integer $angle )

Description

Sets the orientation of the text

Parameter

  • integer $angle - The rotation angle for the text (clockwise). Possible values are: 0, 90, 270 and -1 for stacking top-to-bottom.

Note

This function can not be called statically.

Example

Using setTextRotation()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setTextWrap | PEAR Manual | Format::setNumFormat


Format::setNumFormat

Format::setNumFormat

Format::setNumFormat – Sets the numeric format.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setNumFormat ( string $num_format )

Description

Sets the numeric format. It can be date, time, currency, etc... The following table lists possible values for $num_format and the corresponding types that a numeric format expects as arguments.

Numeric formats and types
0 | Decimal | The amount of zeros specifies the amount of digits that will be shown
0.00 | Decimal | The amount of zeros after the decimal dot specifies the amount of decimal digits that will be shown
#.## | Decimal | The amount of sharp signs after the decimal dot specifies the maximum amount of decimal digits that will be shown
0% | Percent | The amount of zeros specifies the amount of digits that will be shown.
0.000% | Percent | The amount of zeros after the decimal dot specifies the amount of decimal digits that will be shown.
$#.#;[Red]($#.#) | Currency | Zeros and sharp signs have the same meaning as in other formats.
??/?? | Fraction | The amount of question signs in the denominator determines its precision (maximum amount of digits in the denominator).
# ??/?? | Fraction | A fraction with an integer part. Zeros and sharp signs are used for defining the integer part, and they have the same meaning as in other formats.
0.00E+# | Scientific | In scientific notation base and exponent are formated according to the same rules applied to decimals. For scientific notation zeros and sharp signs appear to be equivalent.
D-MMM-YY | Date | A date represented in the given notation. Month can be a one or two digits month, or a three letter month. Year can have 2 or 4 digits. The argument to be formated as a date is considered to be the number of days since December 30 1899 (Excel's day zero). For dates preceding day zero, negative numbers can be used.
D/M/YYYY h:mm:ss | Date/Time | A date represented in the given notation. The argument to be formated as a date is considered to be the number of days since Excel's day zero.
h:mm:ss AM/PM | Time | A time represented in the given notation. Be careful, the argument to be formated as a time has to be given in days. For example an argument of 0.5 would be presented as '12:00:00 PM'.

The information here presented comes from OpenOffice.org's Documentation of the Microsoft Excel File Format (http://sc.openoffice.org/excelfileformat.pdf).

Parameter

  • string $num_format - The numeric format.

Note

This function can not be called statically.

Example

Using setNumFormat()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

// We'll show dates with a three letter month and four digit year format
$date_format =& $workbook->addFormat();
$date_format->setNumFormat('D-MMM-YYYY');

// number of seconds in a day
$seconds_in_a_day = 86400;
// Unix timestamp to Excel date difference in seconds
$ut_to_ed_diff = $seconds_in_a_day * 25569;

// show Excel's day zero date
$worksheet->write(0, 0, "Excel's day zero");
$worksheet->write(0, 1, 0, $date_format);

// show today's date
$now = time();
$worksheet->write(1, 0, "Today's date:");
$worksheet->write(1, 1, ($now + $ut_to_ed_diff) / $seconds_in_a_day, $date_format);

$workbook->send('num_formatting.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setTextRotation | PEAR Manual | Format::setStrikeOut


Format::setStrikeOut

Format::setStrikeOut

Format::setStrikeOut – Sets font as strikeout.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setStrikeOut ( )

Description

Sets font as strikeout.

Note

This function can not be called statically.

Example

Using setStrikeOut()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setNumFormat | PEAR Manual | Format::setOutLine


Format::setOutLine

Format::setOutLine

Format::setOutLine – Sets outlining for a font.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setOutLine ( )

Description

Sets outlining for a font.

Note

This function can not be called statically.

Example

Using setOutLine()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setStrikeOut | PEAR Manual | Format::setShadow


Format::setShadow

Format::setShadow

Format::setShadow – Sets font as shadow.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setShadow ( )

Description

Sets font as shadow.

Note

This function can not be called statically.

Example

Using setShadow()

<?php

?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setOutLine | PEAR Manual | Format::setScript


Format::setScript

Format::setScript

Format::setScript – Sets the script type of the text

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setScript ( integer $script )

Description

Sets the script type of the text

Parameter

  • integer $script - The value for script type. Possible values are 1 => superscript, 2 => subscript.

Note

This function can not be called statically.

Example

Using setScript()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

  $workbook = new Spreadsheet_Excel_Writer();
  // creating the formats
  $format_superscript =& $workbook->addFormat();
  $format_superscript->setScript(1);
  $format_subscript =& $workbook->addFormat();
  $format_subscript->setScript(2);

  $worksheet =& $workbook->addWorksheet();
  $worksheet->write(0, 0, "This is superscript", $format_superscript);
  $worksheet->write(1, 0, "This is subscript", $format_subscript);
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setShadow | PEAR Manual | Format::setFontFamily


Format::setFontFamily

Format::setFontFamily

Format::setFontFamily – Sets the font family.

Synopsis

require_once "Spreadsheet/Excel/Writer.php";

void Format::setFontFamily ( string $font_family )

Description

Sets the font family.

Parameter

  • string $font_family - The font family name. Possible values are: 'Times New Roman', 'Arial', 'Courier'.

Note

This function can not be called statically.

Example

Using setFontFamily()

<?php
require_once 'Spreadsheet/Excel/Writer.php';

$workbook = new Spreadsheet_Excel_Writer();
$worksheet =& $workbook->addWorksheet();

$format_times =& $workbook->addFormat();
$format_times->setFontFamily('Times New Roman');

$format_courier =& $workbook->addFormat();
$format_courier->setFontFamily('Courier');

$worksheet->write(0, 0, "Hello World, Arial (default)");
$worksheet->write(1, 0, "Hello World, Times New Roman", $format_times);
$worksheet->write(2, 0, "Hello World, Courier", $format_courier);

$workbook->send('fonts.xls');
$workbook->close();
?>
Prev | Spreadsheet_Excel_Writer | Next
Format::setScript | PEAR Manual | File System


File System

File System

Provides Packages for working with files and file system

Table of Contents
  • Archive-Tar
  • File
  • File_Find
  • File_SMBPasswd
  • File_SearchReplace
  • File_HtAccess
Prev | PEAR Packages | Next
Format::setFontFamily | PEAR Manual | Archive-Tar


Archive-Tar

Archive-Tar

Archive_Tar provides an API for handling (compressed) Tar archives.

Table of Contents
  • Archive_Tar::Archive_Tar() -- constructor
  • Archive_Tar::add() -- add files or directories
  • Archive_Tar::addModify() -- add files or directories
  • Archive_Tar::create() -- create archive file
  • Archive_Tar::createModify() -- create a new archive
  • Archive_Tar::extract() -- extract files
  • Archive_Tar::extractList() -- extract a list files
  • Archive_Tar::extractModify() -- extract files to a new dir
  • Archive_Tar::listContent() -- list files and directories in archive
  • Archive_Tar::extractInString() -- extract one file and return it as a string
  • Archive_Tar::addString() -- add a string in the archive
Prev | File System | Next
File System | PEAR Manual | Archive_Tar::Archive_Tar()


Archive_Tar::Archive_Tar()

Archive_Tar::Archive_Tar()

Archive_Tar::Archive_Tar() – constructor

Synopsis

require_once 'Archive/Tar.php';

void Archive_Tar ( string $tarname , mixed $compress = null )

Description

The constructor declares a new Archive_Tar object, identifying it by the name of the tar file.

Parameter

  • string $tarname - the name of the tar archive to work with

  • mixed $compress - if TRUE, indicates that the archive is compressed (using gzip). if NULL the archive is not compressed, if 'gz' or 'bz2', indicates that the archive is compressed with gzip or bz2. For compatibility reason the boolean value TRUE means 'gz'.

Prev | Archive-Tar | Next
Archive-Tar | PEAR Manual | Archive_Tar::add()


Archive_Tar::add()

Archive_Tar::add()

Archive_Tar::add() – add files or directories

Synopsis

require_once 'Archive/Tar.php';

boolean add ( mixed $filelist )

Description

This method adds files and directories to an existing archive. If the archive does not exist, it attempts to create it. The files and directories listed are added at the end of the archive, even if a file with the same name is already archived.

Parameter

  • mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space. For each directory added in the archive, the files and sub-directories are also added.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Invalid file list" | The argument for the function is not correct formatted or build. | Check for typing mistakes in the argument

Note

This function can not be called statically.

Example

Add files to a compressed archive

<?php
$tar_object = new Archive_Tar("tarname.tar.gz", true);
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->add($v_list);
?>
Prev | Archive-Tar | Next
Archive_Tar::Archive_Tar() | PEAR Manual | Archive_Tar::addModify()


Archive_Tar::addModify()

Archive_Tar::addModify()

Archive_Tar::addModify() – add files or directories

Synopsis

require_once 'Archive/Tar.php';

boolean addModify ( mixed $filelist , string $add_dir , string $remove_dir = '' )

Description

This methods add files and directories listed in filelist at the end of the existing archive.

If the archive does not exists it attempts to create it. If a file or directory is already in the archive it will only be added at the end of the archive. There is no update of the existing archived file or directory. However while extracting the archive, the last file will replace the first one. This results in a none optimization of the archive size. If a file or directory does not exists, it is ignored.

Parameter

  • mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space.

  • string $add_dir - a string which contains a path to be added to the memorized path of each element in the list.

  • string $remove_dir - a string which contains a path to be removed from the memorized path of each element in the list, when relevant.

    The path indicated in add_dir will be added at the beginning of the memorized path of each file/directory listed. However it can be set to empty ''. The adding of a path is done after the removing of path. The path add/remove ability enables the user to prepare an archive for extraction in a different path than the original path.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Invalid file list" | The argument for the function is not correctly formatted or build. | Check for typing mistakes in the argument
NULL | "Unable to open in write mode file name " | The file permissions for an existing file do not allow writing or the file is locked. | Check permissions and possible competive programs using the file.
NULL | "Invalid file list" | Archive is empty or corrupted |
NULL | "File filename does not exist" | A file you want to add to the archive does not exist. | Check for typing mistakes in the function argument.
NULL | "Directory dirname can not be read" | A directory or a file in it you want to add to the archive does not exists or the permissions for reading the directory does not allow access. | Check for typing mistakes in the function argument and permissions.
NULL | "Unable to open file filename in binary read mode" | The file to add to the archive could not be read. | Check for typing mistakes in the function argument and file permissions.

Note

This function can not be called statically.

Example

Add files to a compressed archive in a new directory

<?php
$tar_object = new Archive_Tar("tarname.tar");
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->addModify($v_list, "install");
// files are stored in the archive as :
//   install/file.txt
//   install/data
//   install/data/file1.txt
//   install/data/... all the files and sub-dirs of data/
//   install/file.log
?>

Add files to a compressed archive moving to a new directory

<?php
$tar_object = new Archive_Tar("tarname.tar");
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->addModify($v_list, "install", "dev");
// files are stored in the archive as :
//   install/file.txt
//   install/data
//   install/data/file1.txt
//   install/data/...         all the files and sub-dirs of data/
//   install/log/file.log
?>

Add files to a compressed archive moving to a new directory (especially for Windows)

<?php
$tar_object = new Archive_Tar("tarname.tar");
$v_list[0]="d:\\dev\\file.txt";
$v_list[1]="d:\\dev\\data\\";
$v_list[2]="d:\\log\\file.log";
$tar_object->addModify($v_list, "install/temp", "d:\\dev");
// files are stored in the archive as :
//   install/temp/file.txt
//   install/temp/data
//   install/temp/data/file1.txt
//   install/temp/data/...         all the files and sub-dirs of data/
//   install/temp/log/file.log
?>

On Windows system, Windows path format can be used. However if the files are using a Windows path, the $remove_dir parameter must also be in Windows path format. The $add_dir parameter can be in Windows or Unix path format.

Prev | Archive-Tar | Next
Archive_Tar::add() | PEAR Manual | Archive_Tar::create()


Archive_Tar::create()

Archive_Tar::create()

Archive_Tar::create() – create archive file

Synopsis

require_once 'Archive/Tar.php';

boolean create ( mixed $filelist )

Description

This method creates the archive file and adds the listed files or directories.

If a file with the same tar name exists and is writable, it is replaced by the new tar archive (it is not an 'add', but a 'create'). If a file exists and is write-protected or is a folder, the method raises a PEAR_Error.

Parameter

  • mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space. For each directory added in the archive, the files and sub-directories are also added.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Invalid file list" | The argument for the function is not correct formatted or build. | Check for typing mistakes in the argument

Note

This function can not be called statically.

Example

Creating an archive

<?php
$tar_object = new Archive_Tar("myArchive.tar");

// print errors
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);

// Archive content
$v_list[0]="file.txt";
// the slash is optional
$v_list[1]="data/";
$v_list[2]="file.log";

// create the archive
$tar_object->create($v_list);
?>

Creating a compressed archive, use a string as create() argument

<?php
$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$tar_object->create("file.txt data/ file.log");
?>
Prev | Archive-Tar | Next
Archive_Tar::addModify() | PEAR Manual | Archive_Tar::createModify()


Archive_Tar::createModify()

Archive_Tar::createModify()

Archive_Tar::createModify() – create a new archive

Synopsis

require_once 'Archive/Tar.php';

boolean createModify ( array $filelist , string $add_dir , string $remove_dir = '' )

Description

This method creates the archive file and adds the listed files or directories.

If the file already exists and is writable, it is replaced by the new tar. It is a 'create' and not a 'add'. If the file exists and is read-only or is a directory, it is not replaced.

Parameter

  • mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space.

  • string $add_dir - contains a path to be added to the memorized path of each element in the list.

  • string $remove_dir - contains a path to be removed from the memorized path of each element in the list, when relevant. Default is an empty string.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Invalid file list" | The argument for the function is not correctly formatted or build. | Check for typing mistakes in the argument

Note

This function can not be called statically.

Example

Create a new compressed archive in a new directory

<?php
$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->createModify($v_list, "install", "dev");
// files are stored in the archive as :
//   install/file.txt
//   install/data
//   install/data/file1.txt
//   install/data/... all the files and sub-dirs of data/
//   install/log/file.log
?>

Create a new compressed archive in a new directory (especially for Windows)

<?php
$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$v_list[0]="c:\\dev\\file.txt";
$v_list[1]="c:\\dev\\data\\";
$v_list[2]="c:\\log\\file.log";
$tar_object->createModify($v_list, "install/temp", "c:\\dev");
// files are stored in the archive as :
//   install/temp/file.txt
//   install/temp/data
//   install/temp/data/file1.txt
//   install/temp/data/... all the files and sub-dirs of data/
//   install/temp/log/file.log
?>
Prev | Archive-Tar | Next
Archive_Tar::create() | PEAR Manual | Archive_Tar::extract()


Archive_Tar::extract()

Archive_Tar::extract()

Archive_Tar::extract() – extract files

Synopsis

require_once 'Archive/Tar.php';

boolean extract ( string $path )

Description

Extracts the files from the archive into the given path.

While extracting a file: If the file already exists it is replaced without looking for last modification date. If the file already exists and is write protected, the extraction is aborted. If a directory with the same name already exists, the extraction is aborted.

However the result can be a partial extraction that may need to be manually cleaned.

Parameter

  • string $path - the destination path to extract

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Unable to open in read mode archive " | The file is exclusively locked by another application. | Check for other applications working on the file. This can not be caused by a competive processing the archive with Archive_Tar
NULL | " Unable to open in write mode archive " | The file is locked by another application. | Check for other applications working on the file. This maybe caused by a competive processing the archive with Archive_Tar
NULL | " Invalid extract mode mode " | Implementation error | Should not occur, please set up a bug report.
NULL | " Directory name already exists as a file " | A file is marked up as directory in the archive. | Maybe a corrupted archive.
NULL | " File name already exists as a directory " | A directoy is marked up as file in the archive. | Maybe a corrupted archive.
NULL | " File name already exists and is write protected. " | The archive contains a file which already exists in the destination dir and can not be overwritten. | Extract the archive to an empty directory.
NULL | " Unable to create path for name " | One or more new nested directories could not be created in the destination directory. | Ensure that the destination directory and all nested directories have the required permissions.
NULL | " Unable to create directory name " | A directory could not be created in the destination directory. | Ensure that the destination directory has the required permissions.
NULL | " Error while opening name in write binary mode " | The file could not be created. | The file is possibly locked.
NULL | " Extracted file filename does not have the correct file size filesize (size expected). Archive may be corrupted. " | Read the message. | Read the message.

Note

This function can not be called statically.

Example

Extract compressed archive

<?php
$tar = new Archive_Tar('archive.tar.gz', true);
$result = $tar->extract('/home/myFolder');
?>
Prev | Archive-Tar | Next
Archive_Tar::createModify() | PEAR Manual | Archive_Tar::extractList()


Archive_Tar::extractList()

Archive_Tar::extractList()

Archive_Tar::extractList() – extract a list files

Synopsis

require_once 'Archive/Tar.php';

boolean extractList ( array $filelist , string $path = '' , string $remove_path = '' )

Description

This method extracts only the files from the archive that are indicated in the $filelist . These files are extracted in the current directory or in the directory indicated by the optional $path parameter.

Parameter

  • string $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space.

  • string $path - the path of the directory where the files and/or directory need to by extracted.

  • string $remove_path - part of the memorized path that can be removed if present at the beginning of the files or directories path.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Unable to open in read mode archive " | The file is exclusively locked by another application. | Check for other applications working on the file. This can not be caused by a competive processing the archive with Archive_Tar
NULL | " Unable to open in write mode archive " | The file is locked by another application. | Check for other applications working on the file. This maybe caused by a competive processing the archive with Archive_Tar
NULL | " Invalid extractlist mode mode " | Implementation error | Should not occur, please set up a bug report.
NULL | " Directory name already exists as a file " | A file is marked up as directory in the archive. | Maybe a corrupted archive.
NULL | " File name already exists as a directory " | A directoy is marked up as file in the archive. | Maybe a corrupted archive.
NULL | " File name already exists and is write protected. " | The archive contains a file which already exists in the destination dir and can not be overwritten. | Extract the archive to an empty directory.
NULL | " Unable to create path for name " | One or more new nested directories could not be created in the destination directory. | Ensure the destination directory and all nested directories have the required permissions.
NULL | " Unable to create directory name " | A directory could not be created in the destination directory. | Ensure the destination directory has the required permissions.
NULL | " Error while opening name in write binary mode " | The file could not be created. | The file is maybe locked.
NULL | " Extracted file filename does not have the correct file size filesize (size expected). Archive may be corrupted. " | Read the message. | Read the message.

Note

This function can not be called statically.

Example

Extract compressed archive

<?php
// tarname.tar with files :
//   dev/data/file.txt
//   dev/data/log.txt
//   readme.txt

$tar_object = new Archive_Tar("tarname.tar");
$tar_object->extractList("dev/data/file.txt readme.txt", "install",
                         "dev");

// Files will be extracted there :
//   install/data/file.txt
//   install/readme.txt
?>
Prev | Archive-Tar | Next
Archive_Tar::extract() | PEAR Manual | Archive_Tar::extractModify()


Archive_Tar::extractModify()

Archive_Tar::extractModify()

Archive_Tar::extractModify() – extract files to a new dir

Synopsis

require_once 'Archive/Tar.php';

boolean extractModify ( string $path , string $remove_path )

Description

This method extracts all the content of the archive in the directory indicated by path . When relevant the memorized path of the files or directories can be modified by removing the remove_path path at the beginning of the file or directory path.

While extracting a file: If the file already exists it is replaced without looking for last modification date. If the file already exists and is write protected, the extraction is aborted. If a directory with the same name already exists, the extraction is aborted.

While extracting a directory, if a file with the same name already exists, the extraction is aborted. While extracting a file/directory if the destination directory exist and is write protected, or does not exist but can not be created, the extraction is aborted. If after extraction an extracted file does not show the correct stored file size, the extraction is aborted.

Parameter

  • string $path - the path of the directory where the files and/or directories need to by extracted.

  • string $remove_path - part of the memorized path that can be removed if present at the beginning of the files or directories path.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Unable to open in read mode archive " | The file is exclusive locked by another application. | Check for other applications working on the file. This can not be caused by a competive processing the archive with Archive_Tar
NULL | " Unable to open in write mode archive " | The file is locked by another application. | Check for other applications working on the file. This maybe caused by a competive processing the archive with Archive_Tar
NULL | " Invalid extractmodify mode mode " | Implementation error | Should not occur, please set up a bug report.
NULL | " Directory name already exists as a file " | A file is marked up as directory in the archive. | Maybe a corrupted archive.
NULL | " File name already exists as a directory " | A directoy is marked up as file in the archive. | Maybe a corrupted archive.
NULL | " File name already exists and is write protected. " | The archive contains a file which already exists in the destination dir and can not be overwritten. | Extract the archive to an empty directory.
NULL | " Unable to create path for name " | One or more new nested directories could not be created in the destination directory. | Ensure the destination directory and all nested directories have the required rights.
NULL | " Unable to create directory name " | A directory could not be created in the destination directory. | Ensure the destination directory has the required rights.
NULL | " Error while opening name in write binary mode " | The file could not be created. | The file is maybe locked.
NULL | " Extracted file filename does not have the correct file size filesize (size expected). Archive may be corrupted. " | Read the message. | Read the message.

Note

This function can not be called statically.

Example

Extract compressed archive into a new directory ignoring the old one

// tarname.tar with files :
// dev/data/file.txt
// dev/data/log.txt
// readme.txt

$tar_object = new Archive_Tar("tarname.tar");
$tar_object->extractModify("install", "dev");

// Files will be extracted there :
// install/data/file.txt
// install/data/log.txt
// install/readme.txt

Extract compressed archive into a new directory ignoring the old one (especilly for Windows)

// tarname.tar with files :
// dev/data/file.txt
// dev/data/log.txt
// readme.txt

$tar_object = new Archive_Tar("tarname.tar");
$tar_object->extractModify("d:\\install\\temp", "dev");

// Files will be extracted there :
// d:\\install\\temp\\data\\file.txt
// d:\\install\\temp\\data\\log.txt
Prev | Archive-Tar | Next
Archive_Tar::extractList() | PEAR Manual | Archive_Tar::listContent()


Archive_Tar::listContent()

Archive_Tar::listContent()

Archive_Tar::listContent() – list files and directories in archive

Synopsis

require_once 'Archive/Tar.php';

array listContent ( )

Description

Lists the files and the directories of the archive.

Return value

array - each array entry represents a file or folder. The array is not sorted, so the index shows the position of the file or directory in the archive.

Each entry contains the following information:

  • $file['filename'] - Name and path of the file/dir.

  • $file['mode'] - File permissions (result of fileperms())

  • $file['uid'] - user id

  • $file['gid'] - group id

  • $file['size'] - filesize

  • $file['mtime'] - Last modification time (result of filemtime())

  • $file['typeflag'] - empty for file, "5" for directory

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Unable to open in read mode archive " | The file is exclusively locked by another application. | Check for other applications working on the file. This can not be caused by a competive processing the archive with Archive_Tar
NULL | " Invalid listcontent mode mode " | Implementation error | Should not occur, please set up a bug report.
NULL | " Directory name already exists as a file " | A file is marked up as directory in the archive. | Maybe a corrupted archive.
NULL | " File name already exists as a directory " | A directoy is marked up as file in the archive. | Maybe a corrupted archive.
NULL | " File name already exists and is write protected. " | The archive contains a file which already exists in the destination dir and can not be overwritten. | Extract the archive to an empty directory.
NULL | " Unable to create path for name " | One or more new nested directories could not be created in the destination directory. | Ensure the destination directory and all nested directories have the required rights.
NULL | " Unable to create directory name " | A directory could not be created in the destination directory. | Ensure the destination directory has the required rights.
NULL | " Error while opening name in write binary mode " | The file could not be created. | The file is maybe locked.
NULL | " Extracted file filename does not have the correct file size filesize (size expected). Archive may be corrupted. " | Read the message. | Read the message.

Note

This function can not be called statically.

Example

List archive content

<?php
$tar_object = new Archive_Tar("tarname.tar");

if (($v_list  =  $tar_object->listContent()) != 0) {
    for ($i=0; $i<sizeof($v_list); $i++) {
        echo "Filename :'".$v_list[$i]['filename']."'<br>";
        echo " .size :'".$v_list[$i]['size']."'<br>";
        echo " .mtime :'".$v_list[$i]['mtime']."' (".
             date("l dS of F Y h:i:s A", $v_list[$i]['mtime']).")<br>";
        echo " .mode :'".$v_list[$i]['mode']."'<br>";
        echo " .uid :'".$v_list[$i]['uid']."'<br>";
        echo " .gid :'".$v_list[$i]['gid']."'<br>";
        echo " .typeflag :'".$v_list[$i]['typeflag']."'<br>";
   }
}
?>
Prev | Archive-Tar | Next
Archive_Tar::extractModify() | PEAR Manual | Archive_Tar::extractInString()


Archive_Tar::extractInString()

Archive_Tar::extractInString()

Archive_Tar::extractInString() – extract one file and return it as a string

Synopsis

require_once 'Archive/Tar.php';

boolean extractInString ( string $path )

Description

This method extracts the file identified by path from the archive and returns it as a string. It does not use temporary files.

Parameter

  • string $path - the path of the file to extract

Return value

string - the content of the extracted file

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Unable to open in read mode archive " | The file is exclusive locked by another application. | Check for other applications working on the file. This can not be caused by a competive processing the archive with Archive_Tar
NULL | " Invalid extractinstring mode mode " | Implementation error | Should not occur, please set up a bug report.
NULL | " Error while opening name in write binary mode " | The file could not be created. | The file is maybe locked.
NULL | " Extracted file filename does not have the correct file size filesize (size expected). Archive may be corrupted. " | Read the message. | Read the message.

Note

This function can not be called statically.

Example

Extract a file in a string

// tarname.tar with files :
// dev/data/file.txt
// dev/data/log.txt
// dev/readme.txt

$tar_object = new Archive_Tar("tarname.tar");
$text = $tar_object->extractInString("dev/readme.txt");
echo $text;
Prev | Archive-Tar | Next
Archive_Tar::listContent() | PEAR Manual | Archive_Tar::addString()


Archive_Tar::addString()

Archive_Tar::addString()

Archive_Tar::addString() – add a string in the archive

Synopsis

require_once 'Archive/Tar.php';

boolean addString ( string $filename , string $content )

Description

This method adds the string content in the archive like a file with full filename filename .

If the archive does not exists it attempts to create it.

Parameter

  • string $filename - the path and filename that will be associated with the added string in the archive.

  • string $content - the string to add in the archive as a file.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Unable to open in write mode file name " | The file permissions for an existing file do not allow writing or the file is locked. | Check permissions and possible competive programs using the file.
NULL | "Unable to open file filename in binary read mode" | The file to add to the archive could not be read. | Check for typing mistakes in the function argument and file permissions.

Note

This function can not be called statically.

Example

Add a string in a compressed archive

<?php
$tar_object = new Archive_Tar("tarname.tgz");
$content = "this file was generated from a string";
$tar_object->addString("data/readme.txt", $content);
// A file is created in the archive with name :
//   data/readme.txt
?>
Prev | Archive-Tar | Next
Archive_Tar::extractInString() | PEAR Manual | File


File

File

Common file and directory routines

Table of Contents
  • Introduction -- Introduction to the File class
  • Constants -- Predefined Constants
  • File::buildpath() -- build a path from given parts array
  • File::close() -- closes an open file pointer
  • File::getTempDir() -- retrieves the system's temporary directory
  • File::getTempFile() -- returns a path to a temporary file
  • File::isAbsolute() -- checks wether the given path is an absolute path
  • File::read() -- read bytes from a file
  • File::readAll() -- reads a complete file
  • File::readChar() -- reads a single character from a file
  • File::readLine() -- reads a single line from a file
  • File::rewind() -- rewinds a file pointer
  • File::skipRoot() -- strips the root directory from a given path
  • File::stripLeadingSeparators() -- strip leading separators from a path
  • File::stripTrailingSeparators() -- strips trailing separators from a path
  • File::unlock() -- unlocks a locked file pointer
  • File::write() -- writes bytes to a file
  • File::writeChar() -- writes a single character to a file
  • File::writeLine() -- writes a single line to a file
Prev | File System | Next
Archive_Tar::addString() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to the File class

Description

File provides an easy interface to PHP's builtin file and directory functions, plus some functions to deal with paths.

Example

Using File

<?php
require_once 'File.php';

$file = "/home/tal/example.txt";

//Echo the whole file
echo File::readAll($file);

//Now use a different approach
$fp = new File();

//Write a single line to the file, using a Macintosh EOL character and
//truncating the file before writing to it
$fp->writeLine($file, "This is a single line", FILE_MODE_WRITE, "\r");

//strip leading and trailing separators from the file path
echo $fp->stripLeadingSeparators($file);
echo $fp->stripTrailingSeparators($file);

?>
Prev | File | Next
File | PEAR Manual | Constants


Constants

Constants

Constants – Predefined Constants

FILE_DEFAULT_READSIZE

The default number of bytes to read from a file.

Used in

  • File::read()

  • File::readAll()

FILE_MODE_READ

Read-only mode for opened files

Used in

  • File::read()

  • File::readLine()

  • File::rewind()

  • File::close()

  • File::unlock()

FILE_MODE_WRITE

Using this mode, opened files will be truncated first and then new data will be written to them.

Used in

  • File::write()

  • File::writeChar()

  • File::writeLine()

  • File::rewind()

  • File::close()

  • File::unlock()

FILE_MODE_APPEND

Using this mode, new data will be appended to the end of opened files.

Used in

  • File::write()

  • File::writeChar()

  • File::writeLine()

  • File::rewind()

  • File::close()

  • File::unlock()

FILE_LOCK_SHARED

Shared (read) locking mode

Used in

  • File::read()

  • File::readChar()

  • File::readLine()

  • File::readAll()

  • File::write()

  • File::writeChar()

  • File::writeLine()

FILE_LOCK_EXCLUSIVE

Exclusive (write) locking mode

Used in

  • File::read()

  • File::readChar()

  • File::readLine()

  • File::readAll()

  • File::write()

  • File::writeChar()

  • File::writeLine()

Prev | File | Next
Introduction | PEAR Manual | File::buildpath()


File::buildpath()

File::buildpath()

File::buildpath() – build a path from given parts array

Synopsis

require_once 'File.php';

mixed File::buildpath ( array $parts , string $separatir = DIRECTORY_SEPARATOR )

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Using File::write()

<?php
require_once 'File.php';

// deprecated Use File_Util::buildPath() instead.
?>
Prev | File | Next
Constants | PEAR Manual | File::close()


File::close()

File::close()

File::close() – closes an open file pointer

Synopsis

require_once 'File.php';

mixed File::close ( string $filename , string $mode )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::close()

<?php
require_once 'File.php';

$e = File::close('test.txt', FILE_MODE_WRITE);

if (PEAR::isError($e)) {
    echo 'Could not close file : ' . $e->getMessage();
} else {
    echo "Successfully closed file test.txt\n";
}
?>
Prev | File | Next
File::buildpath() | PEAR Manual | File::getTempDir()


File::getTempDir()

File::getTempDir()

File::getTempDir() – retrieves the system's temporary directory

Synopsis

require_once 'File.php';

string File::gettempdir ( )

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Using File::getTempDir()

<?php
require_once 'File.php';

// deprecated Use File_Util::tmpDir() instead
?>
Prev | File | Next
File::close() | PEAR Manual | File::getTempFile()


File::getTempFile()

File::getTempFile()

File::getTempFile() – returns a path to a temporary file

Synopsis

require_once 'File.php';

string File::getTempFile ( string $dirname = null )

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Using File::getTempFile()

<?php
require_once 'File.php';

// deprecated Use File_Util::tmpFile() instead
?>
Prev | File | Next
File::getTempDir() | PEAR Manual | File::isAbsolute()


File::isAbsolute()

File::isAbsolute()

File::isAbsolute() – checks wether the given path is an absolute path

Synopsis

require_once 'File.php';

bool File::isAbsolute ( string $path )

Description

This method checks whether the supplied path is an absolute path (eg. "/foo/bar" or "C:\foo\bar").

Parameter

string $path - the path the will be checked.

Return value

This method returns TRUE if the path is absolute, FALSE otherwise.

Note

This function can be called statically.

Example

Using File::isAbsolute()

<?php
require_once 'File.php';

if (File::isAbsolute("/usr/local") {
 echo "Path is absolute";
} else {
 echo "Path isn't absolute";
}
?>

This short example will output the string 'Path is absolute'.

Prev | File | Next
File::getTempFile() | PEAR Manual | File::read()


File::read()

File::read()

File::read() – read bytes from a file

Synopsis

require_once 'File.php';

mixed File::read ( string $filename , int $size = FILE_DEFAULT_READSIZE , mixed $lock = false )

Description

File::read() reads a specific amount of bytes from a specified file and returns them to the user.

Parameter

  • string $filename - the file to read from

  • int $size - the number of bytes to read from the file (defaults to FILE_DEFAULT_READSIZE)

  • mixed $lock - lock type to use, FALSE if none

Return value

mixed - this function returns the requested bytes from the file if there were no errors, FALSE if it reached EOF or a PEAR_Error object if an error has occured during reading from file.

Throws

Possible PEAR_Error values
Error Code | Error Value | Meaning | Solution
NULL | "File does not exist: $filename " | The file $filename does not exist. | Check if the path that is passed to the function is correct.
NULL | "Failed to open file: $filename " | There are few possible things that might cause that error, usually it's caused by wrong permissions or bad sectors on the harddisk. | Check the permissions of the file (ls -l {file} on UNIX systems) and change them so the file is readable by PHP, check if the harddisk is working properly and has no bad sectors.

Note

This function can be called statically.

See

  • File::readChar()
  • File::readLine()
  • File::readAll()

Example

Using File::read()

<?php
require_once 'File.php';

//output 40 bytes of file foo.bar
echo File::read("/path/to/foo.bar", 40);
?>
Prev | File | Next
File::isAbsolute() | PEAR Manual | File::readAll()


File::readAll()

File::readAll()

File::readAll() – reads a complete file

Synopsis

require_once 'File.php';

mixed File::readAll ( string $filename , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::readAll()

<?php
require_once 'File.php';

?>
Prev | File | Next
File::read() | PEAR Manual | File::readChar()


File::readChar()

File::readChar()

File::readChar() – reads a single character from a file

Synopsis

require_once 'File.php';

mixed File::readCharChar ( string $filename , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::readChar()

<?php
require_once 'File.php';

$e = File::readChar('test.txt');

if (PEAR::isError($e)) {
    echo 'Could not read char from file : ' . $e->getMessage();
} else {
    echo $e;
}
?>
Prev | File | Next
File::readAll() | PEAR Manual | File::readLine()


File::readLine()

File::readLine()

File::readLine() – reads a single line from a file

Synopsis

require_once 'File.php';

mixed File::readLine ( string $filename , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::readLine()

<?php
require_once 'File.php';

$e = File::readLine('test.txt');

if (PEAR::isError($e)) {
    echo 'Could not read from file : ' . $e->getMessage();
} else {
    echo $e;
}
?>
Prev | File | Next
File::readChar() | PEAR Manual | File::rewind()


File::rewind()

File::rewind()

File::rewind() – rewinds a file pointer

Synopsis

require_once 'File.php';

mixed File::rewind ( string $filename , string $mode )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::rewind()

<?php
require_once 'File.php';

$e = File::rewind('test.txt', FILE_MODE_READ);

if (PEAR::isError($e)) {
    echo 'Could not rewind the file : ' . $e->getMessage();
} else {
    echo "File test.txt successfully rewound\n";
}
?>
Prev | File | Next
File::readLine() | PEAR Manual | File::skipRoot()


File::skipRoot()

File::skipRoot()

File::skipRoot() – strips the root directory from a given path

Synopsis

require_once 'File.php';

string File::skipRoot ( string $path )

Description

This method strips the root directory from $path .

Parameter

string $path - the path to be processed.

Return value

If the path is absolute, this method returns the processed path, otherwise, it returns the path untouched.

Note

This function can be called statically.

See

File::isAbsolute()

Example

Using File::skipRoot()

<?php
require_once 'File.php';

echo File::skipRoot("/home/foo/bar");
?>

This example prints out home/foo/bar.

Prev | File | Next
File::rewind() | PEAR Manual | File::stripLeadingSeparators()


File::stripLeadingSeparators()

File::stripLeadingSeparators()

File::stripLeadingSeparators() – strip leading separators from a path

Synopsis

require_once 'File.php';

string File::stripLeadingSeparators ( string $path , string $separator = DIRECTORY_SEPARATOR )

Description

This method removes the leading directory separator (like "/" on *nix) from a path name.

Parameter

  • string $path - the path name where the leading separator should be removed from.

  • string $separator - optional string that defines the separator. This parameter defaults to the value of the constant DIRECTORY_SEPARATOR that is pre-defined by PHP.

Return value

This methods returns the given path name without a leading directory separator.

Note

This function can be called statically.

Example

Using File::stripLeadingSeparators()

<?php
require_once "File.php";

echo File::stripLeadingSeparators("/home/foo/lala/");
?>

This example will print home/foo/lala/.

Prev | File | Next
File::skipRoot() | PEAR Manual | File::stripTrailingSeparators()


File::stripTrailingSeparators()

File::stripTrailingSeparators()

File::stripTrailingSeparators() – strips trailing separators from a path

Synopsis

require_once 'File.php';

string File:stripTrailingSeparators ( string $path , string $separator = DIRECTORY_SEPARATOR )

Description

This method removes the trailing directory separator (like "/" on *nix) from a path name.

Parameter

  • string $path - the path name where the trailing separator should be removed from.

  • string $separator - optional string that defines the separator. This parameter defaults to the value of the constant DIRECTORY_SEPARATOR that is pre-defined by PHP.

Return value

This methods returns the given path name without a trailing directory separator.

Note

This function can be called statically.

Example

Using File:stripTrailingSeparators()

<?php
require_once "File.php";

echo File::stripTrailingSeparators("/home/foo/lala/");
?>

This example will print /home/foo/lala.

Prev | File | Next
File::stripLeadingSeparators() | PEAR Manual | File::unlock()


File::unlock()

File::unlock()

File::unlock() – unlocks a locked file pointer

Synopsis

require_once 'File.php';

mixed File::unlock ( string $filename , string $mode )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::unlock()

<?php
require_once 'File.php';

$e = File::unlock('test.txt');

if (PEAR::isError($e)) {
    echo 'Could not unlock the file : ' . $e->getMessage();
} else {
    echo "Successfully unlocked the file test.txt\n";
}
?>
Prev | File | Next
File::stripTrailingSeparators() | PEAR Manual | File::write()


File::write()

File::write()

File::write() – writes bytes to a file

Synopsis

require_once 'File.php';

mixed File::write ( string $filename , string $char , string $mode = FILE_MODE_APPEND , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::write()

<?php
require_once 'File.php';

$e = File::write('test.txt', 'this is a test line', FILE_MODE_WRITE);

if (PEAR::isError($e)) {
    echo 'Could not write to file : ' . $e->getMessage();
} else {
    echo "Successfully wrote to file test.txt\n";
}
?>
Prev | File | Next
File::unlock() | PEAR Manual | File::writeChar()


File::writeChar()

File::writeChar()

File::writeChar() – writes a single character to a file

Synopsis

require_once 'File.php';

mixed File::writeChar ( string $filename , string $char , string $mode = FILE_MODE_APPEND , mixed $lock = false )

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Using File::writeChar()

<?php
require_once 'File.php';

$e = File::write('test.txt', 'a');

if (PEAR::isError($e)) {
    echo 'Could not write to file : ' . $e->getMessage();
} else {
    echo "Successfully wrote to file test.txt\n";
}
?>
Prev | File | Next
File::write() | PEAR Manual | File::writeLine()


File::writeLine()

File::writeLine()

File::writeLine() – writes a single line to a file

Synopsis

require_once 'File.php';

mixed File::writeLine ( string $filename , string $line , string $mode = FILE_MODE_APPEND , string $crlf = "\n" , mixed $lock = false )

Description

Writes a single line, appending a linefeed by default.

Parameter

  • $filename - Name of file to write to

  • $line - Line of data to be written to file

  • $mode - Write mode, can be either FILE_MODE_WRITE or FILE_MODE_APPEND. Defaults to appending.

  • $crlf - Carriage return / line feed your system is using. Defaults to LF (\n), but can be set to anything. On Unix, \n is used, on Windows \r\n and Mac OS uses \r.

  • $lock - If the file shall be locked

Return value

PEAR_Error when an error occured, number of bytes written when all went well (crlf included).

Example

Using File::writeLine()

<?php
require_once 'File.php';

$e = File::writeLine('test.txt', str_repeat("0123456789", 1000));

if (PEAR::isError($e)) {
    echo 'Could not write to file : ' . $e->getMessage();
} else {
    echo "Successfully wrote to file test.txt\n";
}
?>
Prev | File | Next
File::writeChar() | PEAR Manual | File_Find


File_Find

File_Find

Commonly needed functions to search for files and directories

Table of Contents
  • Search methods -- Types of methods what can be used in search functions
  • File_Find::glob() -- find matches for a pattern in a directory
  • File_Find::maptree() -- create a view map for a directory
  • File_Find::mapTreeMultiple() -- create a recursive view map for a directory
  • File_Find::search() -- find matches for a pattern in a directory
Prev | File System | Next
File::writeLine() | PEAR Manual | Search methods


Search methods

Search methods

Search methods – Types of methods what can be used in search functions

Search methods and their patterns

All search functions use $pattern parameter to specify match for filenames. Format of the $pattern depends on value of another parameter - $pattern_type .

  • If value of $pattern_type is 'php' , then the pattern is case-sensitive string which follows the conventions of the ereg_*-functions.

  • In case of 'perl' pattern type it must follow the preg_*-functions pattern format. It is recommended to use 'perl' , because it is faster.

  • The last 'shell' mode is most simple and should be familiar to everybody with basic computer skills. It is as easy as windows approach, but has some additional concepts borrowed from the FAR Manager software. The text of the following section was borrowed from the FAR Manager documentation.

'shell' search mode file masks

File masks are used to select single files and folders or groups of them. Masks may contain common valid file name symbols, wildcards ('*' and '?') and special expressions:

  • *
  • any number of characters;
  • ?
  • any single character;
  • [c,x-z]
  • any character enclosed by the brackets. Both separate characters and character intervals are allowed.

For example, files ftp.exe, fc.exe and f.ext may be selected using mask f*.ex?, mask *co* will select both color.ini and edit.com, mask [c-f,t]*.txt can select config.txt, demo.txt, faq.txt and tips.txt.

You may enter several file masks separated with commas or semicolons. For example, to select all the documents, you can specify *.doc,*.txt,*.wri in search pattern.

You may use exclude masks. An exclude mask is one or multiple file masks that must not be matched by the files matching the mask. The exclude mask is delimited from the main mask by the character '|'.

Usage examples of exclude masks:

  1. *.cpp

    All files with the extension cpp.

  2. *.*|*.bak,*.tmp

    All files except for the files with extensions bak and tmp.

  3. *.*|

    This mask has an error - the character | is entered, but the mask itself is not specified.

  4. *.*|*.bak|*.tmp

    Also an error - the character | may not be contained in the mask more than once.

  5. |*.bak

    The same as *|*.bak

The comma (or semicolon) is used for separating file masks from each other, and the '|' character separates include masks from exclude masks.

'shell' match mode is available from version 1.2.0 of File_Find

Prev | File_Find | Next
File_Find | PEAR Manual | File_Find::glob()


File_Find::glob()

File_Find::glob()

File_Find::glob() – find matches for a pattern in a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::glob ( string $pattern , string $dirpath , string $pattern_type = 'php' )

Description

Search the directory to find matches for the specified pattern.

Parameter

  • $pattern - a string containing the pattern to search the directory for.

  • $dirpath - a string containing the directory path to search.

  • $pattern_type - a string containing the type of pattern matching functions to use (can either be 'php', 'perl' or 'shell').

    The format of the $pattern depends on the $pattern_type -value. For more information see search methods

Return value

array - an array contains all filenames and name of subdirectories, which matches the pattern. Or a PEAR_Error.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Cannot open directory " | The given directory could not be opend. | Check typing and directory permissions. This can not be caused by a competive processing the archive with Archive_Tar

Note

This function can be called statically.

Example

Find all PHP files in current directory

<?php
include "File/Find.php";

$dir = ".";
$items = &File_Find::glob( '!.*\.php$!', $dir, 'perl' );

print_r($items);
?>
Prev | File_Find | Next
Search methods | PEAR Manual | File_Find::maptree()


File_Find::maptree()

File_Find::maptree()

File_Find::maptree() – create a view map for a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::maptree ( string $directory )

Description

Map the directory tree given by the directory_path parameter.

Parameter

  • string $directory - contains the directory path that you want to map

Return value

array - a two element array, the first element containing a list of all the directories, the second element containing a list of all the files.

Note

This function can be called statically.

Example

Get the map of a directory

<?php
include "File/Find.php";

$dir = "File_Find";
list($directories, $files) = File_Find::maptree($dir);

echo "Directories ";
print_r($directories);

echo "Files ";
print_r($files);
?>

The above example will output something similar to:

Directories Array
(
    [0] => File_Find
    [1] => File_Find\dir2
    [2] => File_Find\dir2\2
    [3] => File_Find\dir2\1
    [4] => File_Find\dir2\0
    [5] => File_Find\dir
    [6] => File_Find\dir\txtdir
    [7] => File_Find\dir\dir3
    [8] => File_Find\dir\dir2
)
Files Array
(
    [0] => File_Find\dir2\2\1.txt
    [1] => File_Find\dir2\1\1.txt
    [2] => File_Find\dir2\0\1.txt
    [3] => File_Find\dir\1.txt
    [4] => File_Find\dir\2.txt
    [5] => File_Find\dir\txtdir\5.txt
    [6] => File_Find\dir\dir3\4.bak
    [7] => File_Find\dir\dir3\4.txt
    [8] => File_Find\dir\dir2\3.bak
    [9] => File_Find\dir\dir2\3.txt
)

Prev | File_Find | Next
File_Find::glob() | PEAR Manual | File_Find::mapTreeMultiple()


File_Find::mapTreeMultiple()

File_Find::mapTreeMultiple()

File_Find::mapTreeMultiple() – create a recursive view map for a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::mapTreeMultiple ( string $directory , integer $maxrecursion = 0 , integer $count = 0 )

Description

Map the directory tree given by the directory_path parameter. Depending on maxrecursion you get the content of the directory and the content of the subdirectories too.

Parameter

  • string $directory - contains the directory path that you want to map

  • integer $maxrecursion - defines the deep of recursive mapping of subdirectories

  • integer $count - can be ignored - internal parameter to track recursion level

Return value

array - a multidimensional array containing all subdirectories and their files

Note

This function can be called statically.

Example

Get the content of a directory including the content of subdirectories

<?php
include "File/Find.php";

$file = File_Find::mapTreemultiple('/usr/', 1);

print_r($file);
?>

The above example will output something similar to:

Array
(
   [0] => file1.tmp
   [1] => file2.tmp
   ['bin'] => Array
      (
         [0] => readme.txt
      )
)

Prev | File_Find | Next
File_Find::maptree() | PEAR Manual | File_Find::search()


File_Find::search()

File_Find::search()

File_Find::search() – find matches for a pattern in a directory

Synopsis

require_once 'File/Find.php';

array &File_Find::search ( string $pattern , string $dirpath , string $pattern_type = 'php' , bool $fullpath = true , string $match = 'files' )

Description

Search the directory to find matches for the specified pattern.

Parameter

  • $pattern - a string containing the pattern to search the directory for.

  • $dirpath - a string containing the directory path to search.

  • $pattern_type - a string containing the type of pattern matching functions to use (can either be 'php', 'perl' or 'shell').

    The format of the $pattern depends on the $pattern_type -value. For more information see search methods

  • $fullpath - whether the string should be matched against the full path or only against the filename

  • $match - can be either 'files', 'directories' or 'both' to specify the kind of list to return

Return value

array - an array containing all filenames

Note

This function can be called statically.

See

File_Find::glob()

Prev | File_Find | Next
File_Find::mapTreeMultiple() | PEAR Manual | File_SMBPasswd


File_SMBPasswd

File_SMBPasswd

Provides an API for managing SAMBA passwd-style files

Table of Contents
  • Introduction -- file format
  • File_SMBPasswd::File_SMBPasswd() -- constructor
  • File_SMBPasswd::load() -- load the contents of an existing smbpasswd file
  • File_SMBPasswd::getFile() -- get the value of the file property
  • File_SMBPasswd::getAccounts() -- get the value of the accounts property
  • File_SMBPasswd::addAccountEncrypted() -- adds a new account with pre-encrypted passwords.
  • File_SMBPasswd::addAccount() -- add a new account with the given plaintext-password.
  • File_SMBPasswd::addUser() -- add a new user with the given plaintext-password.
  • File_SMBPasswd::addMachine() -- add a new maschine-account with the given plaintext-password.
  • File_SMBPasswd::modAccountEncrypted() -- modify an existing account with the given encrypted password.
  • File_SMBPasswd::modAccount() -- modify an exsting account with the given plaintext-password.
  • File_SMBPasswd::modUser() -- modify an exsting account with the given plaintext-password.
  • File_SMBPasswd::delAccount() -- deletes an existing account.
  • File_SMBPasswd::delUser() -- deletes an existing user.
  • File_SMBPasswd::verifyAccountEncrypted() -- Verifies the given account with the given encrypted passwords.
  • File_SMBPasswd::verifyAccount() -- Verifies the given account with the given plaintext passwords.
  • File_SMBPasswd::lock() -- lock the smbpasswd file
  • File_SMBPasswd::unlock() -- unlock the smbpasswd file
  • File_SMBPasswd::save() -- saves the smbpasswd file
  • File_SMBPasswd::printAccounts() -- prints the contents of an existing smbpasswd file
Prev | File System | Next
File_Find::search() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – file format

SAMBA passwd-style files

SAMBA is a free implementation of CIFS/SMB. The password encryption on Unix and Windows is different, therefore SAMBA must have his own file where the passwords are encrypted either as NT-Hash and/or as LAN-Manager-Hash. LAN-Manager-Hashes are weak and shouldn't be used anymore, NT-Hashes are based on MD4, but no salt is used, therefore users with the same passwords have the same NT-Hash. In this file are also stored machine accounts, if the SAMBA server acts as PDC, such entries ends with $.

Prev | File_SMBPasswd | Next
File_SMBPasswd | PEAR Manual | File_SMBPasswd::File_SMBPasswd()


File_SMBPasswd::File_SMBPasswd()

File_SMBPasswd::File_SMBPasswd()

File_SMBPasswd::File_SMBPasswd() – constructor

Synopsis

require_once 'File/SMBPasswd.php';

void File_SMBPasswd::File_SMBPasswd ( string $file )

Description

Creates a new File_SMBPasswd object and bind it to the given file.

Parameter

  • string $file - SAMBA password file to read

Prev | File_SMBPasswd | Next
Introduction | PEAR Manual | File_SMBPasswd::load()


File_SMBPasswd::load()

File_SMBPasswd::load()

File_SMBPasswd::load() – load the contents of an existing smbpasswd file

Synopsis

mixed File_SMBPasswd::load ( )

Description

Load the contents of smbpasswd file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::load()

<?php
require_once('File/SMBPasswd.php');

$fh     = new File_SMBPasswd('/usr/local/private/smbpasswd');
$status = $fh->load();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::File_SMBPasswd() | PEAR Manual | File_SMBPasswd::getFile()


File_SMBPasswd::getFile()

File_SMBPasswd::getFile()

File_SMBPasswd::getFile() – get the value of the file property

Synopsis

string File_SMBPasswd::getFile ( )

Description

Get the value of file property. This property contains the filename of the current smbpasswd file.

Return value

string containing the filename.

Note

This function can not be called statically.

Prev | File_SMBPasswd | Next
File_SMBPasswd::load() | PEAR Manual | File_SMBPasswd::getAccounts()


File_SMBPasswd::getAccounts()

File_SMBPasswd::getAccounts()

File_SMBPasswd::getAccounts() – get the value of the accounts property

Synopsis

array File_SMBPasswd::getAccounts ( )

Description

Get the value of accounts property. This property contains all accounts of the current smbpasswd file.

Return value

array containing all accounts.

Note

This function can not be called statically.

Prev | File_SMBPasswd | Next
File_SMBPasswd::getFile() | PEAR Manual | File_SMBPasswd::addAccountEncrypted()


File_SMBPasswd::addAccountEncrypted()

File_SMBPasswd::addAccountEncrypted()

File_SMBPasswd::addAccountEncrypted() – adds a new account with pre-encrypted passwords.

Synopsis

 mixed File_SMBPasswd::addAccountEncrypted (
  string $user
   , int $userid
   , string $lmhash = ''
   , string $nthash = ''
   , string $comment = ''
   , string $flags = '[U           ]'
)

Description

Modifies an existing account. The passwords must be already encrypted.

Parameter

  • string $user - username to be added

  • int $userid - userid of the user

  • string $lmhash - LAN-Manager-Hash

  • string $nthash - NT-Hash

  • string $comment - comment

  • string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the systems password file.

See

  • File_SMBPasswd::modAccountEncrypted()
  • File_SMBPasswd::modUser()
  • File_SMBPasswd::modAccount()

Example

Using File_SMBPasswd::addAccountEncrypted()

<?php
require_once 'File/SMBPasswd.php';

// add account mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addAccountEncrypted(
    'mbretter',
    1005,
    '75BA30198E6D1975AAD3B435B51404EE',
    'FC156AF7EDCD6C0EDDE3337D427F4EAC',
    'Michael Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::getAccounts() | PEAR Manual | File_SMBPasswd::addAccount()


File_SMBPasswd::addAccount()

File_SMBPasswd::addAccount()

File_SMBPasswd::addAccount() – add a new account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::addAccount ( string $user , int $userid , string $pass = '' , string $comment = '' , string $flags = '[U ]' )

Description

This method works in the same way as File_SMBPasswd::addAccountEncrypted() , except the password has to be given as plaintext. The encryption is done internaly.

Parameter

  • string $user - username to be added

  • int $userid - userid of the user

  • string $pass - plaintext-password

  • string $comment - comment

  • string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

  • File_SMBPasswd::addUser()
  • File_SMBPasswd::addMachine()
  • File_SMBPasswd::addAccountEncrypted()

Example

Using File_SMBPasswd::addAccount()

<?php
require_once 'File/SMBPasswd.php';

// add user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addAccount(
    'mbretter',
    1004,
    'MyPw',
    'Michael Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::addAccountEncrypted() | PEAR Manual | File_SMBPasswd::addUser()


File_SMBPasswd::addUser()

File_SMBPasswd::addUser()

File_SMBPasswd::addUser() – add a new user with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::addUser ( string $user , int $userid , string $pass = '' , string $comment = '' )

Description

This method works in the same way as File_SMBPasswd::addAccount() , except the flags are forced representing a user-account.

Parameter

  • string $user - username to be added

  • int $userid - userid of the user

  • string $pass - plaintext-password

  • string $comment - comment

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

  • File_SMBPasswd::addAccount()
  • File_SMBPasswd::addMachine()
  • File_SMBPasswd::addAccountEncrypted()

Example

Using File_SMBPasswd::addUser()

<?php
require_once 'File/SMBPasswd.php';

// add user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addUser(
    'mbretter',
    1004,
    'MyPw',
    'Michael Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::addAccount() | PEAR Manual | File_SMBPasswd::addMachine()


File_SMBPasswd::addMachine()

File_SMBPasswd::addMachine()

File_SMBPasswd::addMachine() – add a new maschine-account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::addMachine ( string $machine , int $userid , string $comment = '' )

Description

This method works in the same way as File_SMBPasswd::addAccount() , except the flags are forced representing a machine-account, a $ is implicitely added to the machinename.

Parameter

  • string $machine - machinename to be added

  • int $userid - userid of the user

  • string $comment - comment

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the machine to be added must already exist in the system password file.

See

  • File_SMBPasswd::addAccount()
  • File_SMBPasswd::addUser()
  • File_SMBPasswd::addAccountEncrypted()

Example

Using File_SMBPasswd::addMachine()

<?php
require_once 'File/SMBPasswd.php';

// add user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->addMachine(
    'mypc',
    10004,
    'My Turbo PC');
if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::addUser() | PEAR Manual | File_SMBPasswd::modAccountEncrypted()


File_SMBPasswd::modAccountEncrypted()

File_SMBPasswd::modAccountEncrypted()

File_SMBPasswd::modAccountEncrypted() – modify an existing account with the given encrypted password.

Synopsis

 mixed File_SMBPasswd::modAccountEncrypted (
  string $user
   , int $userid
   , string $nthash = ''
   , string $lmhash = ''
   , string $comment = ''
   , string $flags = ''
)

Description

Modifies an existing account using pre-encrypted passwords.

Parameter

  • string $user - username to be added

  • int $userid - userid of the user

  • string $nthash - new NT-Hash

  • string $lmhash - new LM-Hash

  • string $comment - comment

  • string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

  • File_SMBPasswd::addAccount()
  • File_SMBPasswd::modAccount()
  • File_SMBPasswd::modUser()

Example

Using File_SMBPasswd::modAccountEncrypted()

<?php
require_once 'File/SMBPasswd.php';

// modify user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->modAccountEncrypted(
    'mbretter',
    1005,
    '75BA30198E6D1975AAD3B435B51404EE',
    'FC156AF7EDCD6C0EDDE3337D427F4EAC',
    Michaela Bretterklieber);
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::addMachine() | PEAR Manual | File_SMBPasswd::modAccount()


File_SMBPasswd::modAccount()

File_SMBPasswd::modAccount()

File_SMBPasswd::modAccount() – modify an exsting account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::modAccount ( string $user , int $userid , string $pass = '' , string $comment = '' , string $flags = '' )

Description

This method works in the same way as File_SMBPasswd::modAccountEncrypted() , except the password has to be given as plaintext. The encryption is done internaly.

Parameter

  • string $user - username to be modified

  • int $userid - userid of the user

  • string $pass - plaintext-password

  • string $comment - comment

  • string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

See

  • File_SMBPasswd::addAccount()
  • File_SMBPasswd::modAccountEncrypted()
  • File_SMBPasswd::modUser()

Example

Using File_SMBPasswd::modAccount()

<?php
require_once 'File/SMBPasswd.php';

// modify user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->modAccount(
    'mbretter',
    1005,
    'MyPwa',
    'Michaela Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::modAccountEncrypted() | PEAR Manual | File_SMBPasswd::modUser()


File_SMBPasswd::modUser()

File_SMBPasswd::modUser()

File_SMBPasswd::modUser() – modify an exsting account with the given plaintext-password.

Synopsis

mixed File_SMBPasswd::modUser ( string $user , int $userid , string $pass = '' , string $comment = '' , string $flags = '' )

Description

This method modifies an existing user, using a plaintext-password.

Parameter

  • string $user - username to be added

  • int $userid - userid of the user

  • string $pass - plaintext-password

  • string $comment - comment

  • string $flags - flags

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Note that the user to be added must already exist in the system password file.

See

  • File_SMBPasswd::addAccount()
  • File_SMBPasswd::modAccountEncrypted()
  • File_SMBPasswd::modAccount()

Example

Using File_SMBPasswd::modUser()

<?php
require_once 'File/SMBPasswd.php';

// modify user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->modUser(
    'mbretter',
    1005,
    'MyPwa',
    'Michaela Bretterklieber');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::modAccount() | PEAR Manual | File_SMBPasswd::delAccount()


File_SMBPasswd::delAccount()

File_SMBPasswd::delAccount()

File_SMBPasswd::delAccount() – deletes an existing account.

Synopsis

mixed File_SMBPasswd::delAccount ( string $name )

Description

This method deletes an existing account.

Parameter

  • string $name - account name to be deleted (username or machinename)

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

See

  • File_SMBPasswd::delUser()

Example

Using File_SMBPasswd::delAccount()

<?php
require_once 'File/SMBPasswd.php';

// delete user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->delAccount('mbretter');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::modUser() | PEAR Manual | File_SMBPasswd::delUser()


File_SMBPasswd::delUser()

File_SMBPasswd::delUser()

File_SMBPasswd::delUser() – deletes an existing user.

Synopsis

mixed File_SMBPasswd::delUser ( string $user )

Description

This method deletes an existing user.

Parameter

  • string $user - username to be deleted

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

See

  • File_SMBPasswd::delAccount()

Example

Using File_SMBPasswd::delAccount()

<?php
require_once 'File/SMBPasswd.php';

// delete user mbretter
$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
$status = $fh->delUser('mbretter');
if (PEAR::isError($status)) {
    // handle errors
} else {
    $fh->save();
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::delAccount() | PEAR Manual | File_SMBPasswd::verifyAccountEncrypted()


File_SMBPasswd::verifyAccountEncrypted()

File_SMBPasswd::verifyAccountEncrypted()

File_SMBPasswd::verifyAccountEncrypted() – Verifies the given account with the given encrypted passwords.

Synopsis

mixed File_SMBPasswd::verifyAccountEncrypted ( string $user , string $nthash , string $lmhash = '' )

Description

This method verifies the given username and passwords against the entry in the loaded smbpasswd file. The given passwords must already be a valid NT-Hash or LM-Hash, whereas the LM-Hash is optional.

Parameter

  • string $user - username to be verified

  • string $nthash - the NT-Hash

  • string $lmhash - the LM-Hash

Return value

mixed - Returns TRUE on success, FALSE on failure.

See

  • File_SMBPasswd::verifyAccount()

Example

Using File_SMBPasswd::verifyAccount()

<?php
require_once 'File/SMBPasswd.php';

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
if ($fh->verifyAccountEncrypted('mbretter', '75BA30198E6D1975AAD3B435B51404EE')) {
    echo "Account is valid";
} else {
    echo "Account is in-valid";
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::delUser() | PEAR Manual | File_SMBPasswd::verifyAccount()


File_SMBPasswd::verifyAccount()

File_SMBPasswd::verifyAccount()

File_SMBPasswd::verifyAccount() – Verifies the given account with the given plaintext passwords.

Synopsis

mixed File_SMBPasswd::verifyAccount ( string $user , string $pass )

Description

This method verifies the given username and plaintext-password against the entry in the loaded smbpasswd file.

Parameter

  • string $user - username to be verified

  • string $pass - the plaintext password

Return value

mixed - Returns TRUE on success, FALSE on failure.

See

  • File_SMBPasswd::verifyAccountEncrypted()

Example

Using File_SMBPasswd::verifyAccount()

<?php
require_once 'File/SMBPasswd.php';

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$fh->load();
if ($fh->verifyAccount('mbretter', 'MyPw')) {
    echo "Account is valid";
} else {
    echo "Account is in-valid";
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::verifyAccountEncrypted() | PEAR Manual | File_SMBPasswd::lock()


File_SMBPasswd::lock()

File_SMBPasswd::lock()

File_SMBPasswd::lock() – lock the smbpasswd file

Synopsis

mixed File_SMBPasswd::lock ( )

Description

lock the smbpasswd file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::lock()

<?php
require_once('File/SMBPasswd.php');

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$status = $fh->lock();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::verifyAccount() | PEAR Manual | File_SMBPasswd::unlock()


File_SMBPasswd::unlock()

File_SMBPasswd::unlock()

File_SMBPasswd::unlock() – unlock the smbpasswd file

Synopsis

mixed File_SMBPasswd::unlock ( )

Description

unlock the smbpasswd file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::unlock()

<?php
require_once('File/SMBPasswd.php');

$fh = new File_SMBPasswd('/usr/local/private/smbpasswd');
$status = $fh->unlock();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::lock() | PEAR Manual | File_SMBPasswd::save()


File_SMBPasswd::save()

File_SMBPasswd::save()

File_SMBPasswd::save() – saves the smbpasswd file

Synopsis

mixed File_SMBPasswds:save ( )

Description

Saves the contents of File_SMBPasswd object as a corresponding smbpasswd file on the disc. Save implicitely locks the file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_SMBPasswd::save()

<?php
require_once('File_SMBPasswd.php');

$f = new File_SMBPasswd('./smbpasswd');
$f->load();
$ret = $f->addAccount('sepp3', 12, 'MyPw');
if (PEAR::isError($ret)) {
    echo $ret->getMessage();
    exit;
}
$ret = $f->modAccount('sepp', '', 'MyPw');
if (PEAR::isError($ret)) {
    echo $ret->getMessage();
    exit;
}
$ret = $f->delAccount('karli');
if (PEAR::isError($ret)) {
    echo $ret->getMessage();
    exit;
}

$status = $f->save();

if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
}

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::unlock() | PEAR Manual | File_SMBPasswd::printAccounts()


File_SMBPasswd::printAccounts()

File_SMBPasswd::printAccounts()

File_SMBPasswd::printAccounts() – prints the contents of an existing smbpasswd file

Synopsis

void File_SMBPasswd::printAccounts ( )

Description

Print all accounts of the loaded smbpasswd file.

Return value

void

Note

This function can not be called statically.

Example

Using File_SMBPasswd::printAccounts()

<?php
require_once('File/SMBPasswd.php');

$f     = new File_SMBPasswd('/usr/local/private/smbpasswd');
$f->load();
$f->printaccounts();

?>
Prev | File_SMBPasswd | Next
File_SMBPasswd::save() | PEAR Manual | File_SearchReplace


File_SearchReplace

File_SearchReplace

Provides an API for replacing text in files

Table of Contents
  • Introduction -- HowTo s'n'r in files
  • File_SearchReplace::File_SearchReplace() -- constructor
  • File_SearchReplace::getNumOccurences() -- return number of replaces
  • File_SearchReplace::doSearch() -- execute search&replace
  • File_SearchReplace::setDirectories() -- set file location
  • File_SearchReplace::setFiles() -- set the files to scan
  • File_SearchReplace::setFind() -- set pattern to find
  • File_SearchReplace::setIncludeSubdir() -- allow scan in sub directories
  • File_SearchReplace::setReplace() -- set replace string
  • File_SearchReplace::setSearchFunction() -- set search function to use
Prev | File System | Next
File_SMBPasswd::printAccounts() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – HowTo s'n'r in files

Using

With SearchReplace, you can replace a text in as many as desired files by another.

Typical usage

<?php
include 'File/SearchReplace.php' ;
$files = array( "test1.txt",
                "test2.txt",
                "test3.txt" ) ;
$ignoreline = array( "#", ":") ;
$snr = new File_SearchReplace( "Yes", "No", $files, "/mail/", false,
                            $ignoreline) ;
$snr -> doSearch() ;
?>

The example replaces all occurences of "Yes" with "No" in the given $files and in all files in the directory "/mail/" . If a line in a file starts with one of the chars in $ignoreline , possible matches will be ignored.

You can do a new search without creating a new instance of the class.

Do a new search

<?php
...
// string to search
$snr -> setFind( "Er") ;
// string to find
$snr -> setReplace( "Sie") ;
// look in this files
$snr -> setFiles( $files) ;
// look in this directories
$snr -> setDirectories( array( "/neue_briefe/")) ;
// look in the subdirectories too
$snr -> setIncludeSubdir( true) ;
// ignore lines in the files starting with this chars
$snr -> setIgnoreLines( array( "::", "#")) ;
// restart search'n'replace
$snr -> doSearch() ;
?>

Types of search functions

File_SearchReplace supports different kinds of search functions. The type directly influence the format of the required $find -parameter

  • normal - default, the only type supporting the $IgnoreLines -parameter
  • quick - use str_replace()
  • preg - use preg_replace()
  • ereg - use ereg_replace()

To set the type, call setSearchFunction() before doSearch().

Prev | File_SearchReplace | Next
File_SearchReplace | PEAR Manual | File_SearchReplace::File_SearchReplace()


File_SearchReplace::File_SearchReplace()

File_SearchReplace::File_SearchReplace()

File_SearchReplace::File_SearchReplace() – constructor

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::File_SearchReplace ( mixed $find , mixed $replace , string $files , mixed $directories = '' , boolean $include_subdir = true , array $ignore_lines = array() )

Description

Constructor

Parameter

  • mixed $find - the string/regex or array of strings/regexes to find

  • mixed $replace - the string/regex or array of strings/regexes to replace $find

  • array $files - the file(s) to perform this operation on.

  • array $directories - the directories to perform this operation on.

  • boolean $include_subdir - if performing on directories, whether to traverse subdirectories.

  • array $ignore_lines - ignore lines beginning with any of the strings in this array. This feature only works with the "normal" search.

Note

This function can be called statically.

Prev | File_SearchReplace | Next
Introduction | PEAR Manual | File_SearchReplace::getNumOccurences()


File_SearchReplace::getNumOccurences()

File_SearchReplace::getNumOccurences()

File_SearchReplace::getNumOccurences() – return number of replaces

Synopsis

require_once 'File/SearchReplace.php';

integer File_SearchReplace::getNumOccurences ( )

Description

Returns the number of replaced strings after a File_SearchReplace::doSearch() call.

Return value

integer - the number of occurences

Note

This function can not be called statically.

Prev | File_SearchReplace | Next
File_SearchReplace::File_SearchReplace() | PEAR Manual | File_SearchReplace::doSearch()


File_SearchReplace::doSearch()

File_SearchReplace::doSearch()

File_SearchReplace::doSearch() – execute search&replace

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::doSearch ( )

Description

Starts searching for the patterns and replaces them, if found.

Note

This function can not be called statically.

Prev | File_SearchReplace | Next
File_SearchReplace::getNumOccurences() | PEAR Manual | File_SearchReplace::setDirectories()


File_SearchReplace::setDirectories()

File_SearchReplace::setDirectories()

File_SearchReplace::setDirectories() – set file location

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::setDirectories ( array $directories )

Description

Set the directories where the files to scan reside.

Parameter

  • string $directories - the directories to perform

Note

This function can not be called statically.

See

File_SearachReplace constructor()

Prev | File_SearchReplace | Next
File_SearchReplace::doSearch() | PEAR Manual | File_SearchReplace::setFiles()


File_SearchReplace::setFiles()

File_SearchReplace::setFiles()

File_SearchReplace::setFiles() – set the files to scan

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::setFiles ( array $files )

Description

Set the files to scan.

Parameter

  • array $files - the file(s) to scan

Note

This function can not be called statically.

See

File_SearachReplace constructor()

Prev | File_SearchReplace | Next
File_SearchReplace::setDirectories() | PEAR Manual | File_SearchReplace::setFind()


File_SearchReplace::setFind()

File_SearchReplace::setFind()

File_SearchReplace::setFind() – set pattern to find

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::setFind ( mixed $find )

Description

Set the pattern for the string to find.

Parameter

  • mixed $find - the string/regex or arrays of them to find

Note

This function can not be called statically.

See

File_SearchReplace constructor()

Prev | File_SearchReplace | Next
File_SearchReplace::setFiles() | PEAR Manual | File_SearchReplace::setIncludeSubdir()


File_SearchReplace::setIncludeSubdir()

File_SearchReplace::setIncludeSubdir()

File_SearchReplace::setIncludeSubdir() – allow scan in sub directories

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::setIncludeSubdir ( integer $include_subdir )

Description

Enable or disable look up in sub directories for files to scan.

Parameter

  • boolean $inlude_subdir - Whether to traverse subdirectories or not.

Note

This function can not be called statically.

See

File_SearachReplace constructor()

Prev | File_SearchReplace | Next
File_SearchReplace::setFind() | PEAR Manual | File_SearchReplace::setReplace()


File_SearchReplace::setReplace()

File_SearchReplace::setReplace()

File_SearchReplace::setReplace() – set replace string

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::setReplace ( mixed $replace )

Description

Set the replacment string.

Parameter

  • mixed $replace - the string/regex or arrays of them to replace found string/regex with.

Note

This function can not be called statically.

See

File_SearchReplace constructor()

Prev | File_SearchReplace | Next
File_SearchReplace::setIncludeSubdir() | PEAR Manual | File_SearchReplace::setSearchFunction()


File_SearchReplace::setSearchFunction()

File_SearchReplace::setSearchFunction()

File_SearchReplace::setSearchFunction() – set search function to use

Synopsis

require_once 'File/SearchReplace.php';

void File_SearchReplace::setSearchFunction ( array $search_function )

Description

Function to determine which search function is used.

Parameter

  • $search_function - The search function that should be used. Possible values: "normal" , "quick" , "preg" , "ereg"

Note

This function can not be called statically.

See

File_SearachReplace constructor() ,"Types of search functions"

Prev | File_SearchReplace | Next
File_SearchReplace::setReplace() | PEAR Manual | File_HtAccess


File_HtAccess

File_HtAccess

Provides methods to create and manipulate .htaccess files.

Table of Contents
  • Introduction -- what are .htaccess files
  • File_HtAccess::file_htaccess() -- constructor
  • File_HtAccess::load -- load the contents of existing .htaccess file
  • File_HtAccess::save() -- saves the .htaccess file
  • File_HtAccess::setRequire() -- set the value of require property
  • File_HtAccess::addRequire() -- add a value into require property
  • File_HtAccess::delRequire() -- remove a value from require property
  • File_HtAccess::getRequire() -- get the value(s) of require property
  • File_HtAccess::setProperties() -- set the values of objects properties
  • File_HtAccess::setAuthUserFile() -- set the value of authuserfile property
  • File_HtAccess::setAuthGroupFile() -- set the value of authgroupfile property
  • File_HtAccess::setAuthType -- set the value of authtype property
  • File_HtAccess::setAuthDigestFile -- set the value of authdigestfile property
Prev | File System | Next
File_SearchReplace::setSearchFunction() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – what are .htaccess files

What is File_HtAccess?

File_HtAccess provides common methods to create and manipulate Apache / NCSA style .htaccess files. These files together with accompanying password files are used to protect webserver directories. Since File_HtAccess does not provide any means to manipulate or create password files you should use it together with File_Passwd.

What are .htaccess files?

The most common and the original purpose of .htaccess files is to create per-directory password protection of resources. With modern webservers there is vast amount of other things .htaccess files can do. These include: custom error pages, ip based access control, redirecting users automatically, denying directory listing and using different files as an index file.

File_HtAccess concentrates only to password protection of directories, although it is possible to use it to control other things mentioned above too.

A .htaccess file is built from the following basic directives. They differ a bit whether youre using Basic or Digest authentication.

Directives
Directive | Purpose
AuthType | Authentication type being used, "Basic" or "Digest".
AuthName | Authentication realm or name.
AuthUserFile | Full path to password file if using Basic authentication.
AuthGroupFile | Full path to group file if using Basic authentication.
AuthDigestFile | Full path to password file if using Digest authentication.
AuthDigestGroupFile | Full path to group file if using Digest authentication.
Require | Requirements which must be met to grant access.

File_HtAccess provides method accessor methods with corresponding names for each of these directives, such as getAuthType() and setAuthType().

A typical .htaccess file looks like this:

AuthName "Protected"
AuthType Basic
AuthUserFile /usr/local/apache/conf/users.dat
require valid-user

What is Basic authentication

When a client requests resource protected with basic authentication webserver responds with a 401 Authentication Required header. When client receives 401 header it asks the user for username and password. If authentication succeeds, the protected resource will be sent to the client. Otherwise the access will be denied.

What is Digest authentication

Even though the passwords are stored encrypted on serverside they are sent cleartext between client and server when using Basic authentication. With Digest authentication the passwords are never sent cleartext but as a MD5 digest instead. The caveat is, most browsers do not support Digest authentication.

Prev | File_HtAccess | Next
File_HtAccess | PEAR Manual | File_HtAccess::file_htaccess()


File_HtAccess::file_htaccess()

File_HtAccess::file_htaccess()

File_HtAccess::file_htaccess() – constructor

Synopsis

object new File_HtAccess ( string $file='.htaccess' , array $params )

Description

Creates an instance of a File_HtAccess object.

Parameter

  • string $file - filename to use. Defaults to .htaccess

  • array $params - a array of parameters which can be:

    • $params['authname'] - authname

    • $params['authtype'] - authtype

    • $params['authuserfile'] - authuserfile

    • $params['authgroupfile'] - authgroupfile

    • $params['require'] - require

    • $params['additional'] - additional

Return value

object - instance of File_HtAccess

Example

How to create new instance of File_HtAccess

<?php
require_once('File/HtAccess.php');
$fh = new File_HtAccess('.htaccess');
?>
Prev | File_HtAccess | Next
Introduction | PEAR Manual | File_HtAccess::load


File_HtAccess::load

File_HtAccess::load

File_HtAccess::load() – load the contents of existing .htaccess file

Synopsis

mixed File_HtAccess::load ( )

Description

Load the contents of .htaccess file.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_HtAccess::load()

<?php
require_once('File/HtAccess.php');

$fh     = new File_HtAccess('.htaccess');
$status = $fh->load();

if (PEAR::isError($status)) {
  // handle errors
} else {
  // continue processing
}

?>
Prev | File_HtAccess | Next
File_HtAccess::file_htaccess() | PEAR Manual | File_HtAccess::save()


File_HtAccess::save()

File_HtAccess::save()

File_HtAccess::save() – saves the .htaccess file

Synopsis

mixed File_HtAccesss:save ( )

Description

Saves the contents of File_HtAccess object as a corresponding .htaccess file on the disc.

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Example

Using File_HtAccess::save()

<?php
require_once('File/HtAccess.php');

/* create a new .htaccess file with given parameters */
$params['authname']      = 'Private';
$params['authtype']      = 'Basic';
$params['authuserfile']  = '/path/to/.htpasswd';
$params['authgroupfile'] = '/path/to/.htgroup';
$params['require']       = array('group', 'admins');

$fh     = new File_HtAccess('.htaccess', $params);
$status = $fh->save();

if (PEAR::isError($status)) {
    // handle errors
} else {
    // continue processing
}

?>
Prev | File_HtAccess | Next
File_HtAccess::load | PEAR Manual | File_HtAccess::setRequire()


File_HtAccess::setRequire()

File_HtAccess::setRequire()

File_HtAccess::setRequire() – set the value of require property

Synopsis

void File_HtAccess::setRequire ( mixed $require )

Description

Sets the value of require property.This overwrites the previous value. If you need to add a value (user) to require use File_HtAccess::addRequire() instead. Using this method you can control which users will be able to access the protected resources.

Parameter

  • mixed $require - value the requre property to be set to. Can be given as a string or an array. If given as a string separate multiple values with a space.

Return value

void

Note

This function can not be called statically.

See

  • File_HtAccess::addRequire()
  • File_HtAccess::delRequire()
  • File_HtAccess::getRequire()

Example

Using File_HtAccess::setRequire()

<?php
require_once('File/HtAccess.php');

/* let any valid user access the resource */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setRequire('valid-user');
$fh->save();

/* let user tuupola or panula access the resource  */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setRequire(array('user', 'tuupola', 'panula'););
$fh->save();

/* let anyone from group admins to access the resource  */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setRequire(array('group', 'admins'););
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::save() | PEAR Manual | File_HtAccess::addRequire()


File_HtAccess::addRequire()

File_HtAccess::addRequire()

File_HtAccess::addRequire() – add a value into require property

Synopsis

void File_HtAccess::addRequire ( string $require )

Description

Adds a value (user) into require property. Using this method you can control which users will be able to access the protected resources.

Parameter

  • string $require - value (user) to be added to require property.

Return value

void

Note

This function can not be called statically.

See

  • File_HtAccess::setRequire()
  • File_HtAccess::delRequire()
  • File_HtAccess::getRequire()

Example

Using File_HtAccess::addRequire()

<?php
require_once('File/HtAccess.php');

/* add user tuupola to list of users to be granted access */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->addRequire('tuupola');
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::setRequire() | PEAR Manual | File_HtAccess::delRequire()


File_HtAccess::delRequire()

File_HtAccess::delRequire()

File_HtAccess::delRequire() – remove a value from require property

Synopsis

void File_HtAccess::delRequire ( string $require )

Description

Remove a value (user) from require property. Using this method you can control which users will be able to access the protected resources.

Parameter

  • string $require - value (user) to be added to require property.

Return value

void

Note

This function can not be called statically.

See

  • File_HtAccess::setRequire()
  • File_HtAccess::addRequire()
  • File_HtAccess::getRequire()

Example

Using File_HtAccess::delRequire()

<?php
require_once('File/HtAccess.php');

/* remove user viemero from list of users to be granted access */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->delRequire('viemero');
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::addRequire() | PEAR Manual | File_HtAccess::getRequire()


File_HtAccess::getRequire()

File_HtAccess::getRequire()

File_HtAccess::getRequire() – get the value(s) of require property

Synopsis

array File_HtAccess::getRequire ( )

Description

Get the value(s) of require property as an array. Require property contains the usernames or groups users who are allowed to access protected resources. Value valid-user means all users listed in password file are allowed to access.

Parameter

  • string $type - if 'string' return value will be a string with usernames separated by a space character. Otherwise return value will be an array(). Defaults to an array.

Return value

mixed string or array depending on $type parameter.

Note

This function can not be called statically.

See

  • File_HtAccess::setRequire()
  • File_HtAccess::delRequire()
  • File_HtAccess::getRequire()

Example

Using File_HtAccess::getrequire()

<?php
require_once('File/HtAccess.php');

/* add user tuupola and viemero to list of users to be granted access */
$fh = new File_HtAccess('.htaccess');
$fh->addRequire('tuupola');
$fh->addRequire('viemero');

$require1 = $fh->getRequire();
$require2 = $fh->getRequire('string');

print_r($require1);

/* Array              */
/* (                  */
/*    [0] => tuupola  */
/*    [1] => viemero  */
/* )                  */

print_r($require2);

/* tuupola viemero    */

?>
Prev | File_HtAccess | Next
File_HtAccess::delRequire() | PEAR Manual | File_HtAccess::setProperties()


File_HtAccess::setProperties()

File_HtAccess::setProperties()

File_HtAccess::setProperties() – set the values of objects properties

Synopsis

void File_HtAccess::setProperties ( array $params )

Description

Set the values of objects properties as defined by hash given as a parameter. You can use this method as an alternative to passing property values in constructor .

Parameter

  • $params['authname'] - authname

  • $params['authtype'] - authtype

  • $params['authuserfile'] - authuserfile

  • $params['authgroupfile'] - authgroupfile

  • $params['require'] - require

  • $params['additional'] - additional

Return value

void

Note

This function can not be called statically.

See

  • File_HtAccess::file-htaccess()

Example

Using File_HtAccess::setProperties()

<?php
require_once('File/HtAccess.php');

/* let any valid user access the resource */
$fh = new File_HtAccess('.htaccess');

$params['authname']      = 'Private';
$params['authtype']      = 'Basic';
$params['authuserfile']  = '/path/to/.htpasswd';
$params['authgroupfile'] = '/path/to/.htgroup';
$params['require']       = array('group', 'admins');

$fh->setProperties($params);

?>
Prev | File_HtAccess | Next
File_HtAccess::getRequire() | PEAR Manual | File_HtAccess::setAuthUserFile()


File_HtAccess::setAuthUserFile()

File_HtAccess::setAuthUserFile()

File_HtAccess::setAuthUserFile() – set the value of authuserfile property

Synopsis

void File_HtAccess::setAuthUserFile ( string $file )

Description

Sets the value of authuserfile property. AuthUserFile is the password file which contains username:password pairs for Basic authentication. You must give full path to the password file in order for it to work.

Parameter

  • string $file - absolute pathname to the password file.

Return value

void

Note

This function can not be called statically.

See

  • File_HtAccess::getAuthDigestFile()

Example

Using File_HtAccess::setAuthUserFile()

<?php
require_once('File/HtAccess.php');

/* set the password file to /etc/htpasswd */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthUserFile('/etc/htpasswd');
$fh->save();

/* set the password file to .htpasswd in current working directory */
$file = getcwd() . '/.htpasswd';
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthUserFile($file);
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::setProperties() | PEAR Manual | File_HtAccess::setAuthGroupFile()


File_HtAccess::setAuthGroupFile()

File_HtAccess::setAuthGroupFile()

File_HtAccess::setAuthGroupFile() – set the value of authgroupfile property

Synopsis

void File_HtAccess::setAuthGroupFile ( string $file )

Description

Sets the value of authgroupfile property. AuthGroupFile a file containing names of the groups and usernames belonging to the group. You must give full path to the group file in order for it to work.

Parameter

  • string $file - absolute pathname to the group file.

Return value

void

Note

This function can not be called statically.

Example

Using File_HtAccess::setauthgroupfile()

<?php
require_once('File/HtAccess.php');

/* set the group file to /etc/htgroup */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthGroupFile('/etc/htgroup');
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::setAuthUserFile() | PEAR Manual | File_HtAccess::setAuthType


File_HtAccess::setAuthType

File_HtAccess::setAuthType

File_HtAccess::setAuthType – set the value of authtype property

Synopsis

void File_HtAccess::setAuthType ( string $type='Basic' )

Description

Sets the value of authtype property. Almost allways you will be using Basic authentication. Since most browsers don't yet support Digest authentication you should only use Digest if you can control what browsers will be accessing the resources.

Parameter

  • string $type - authentication type to use. Should be Basic os Digest. Defaults to Basic.

Return value

void

Note

This function can not be called statically.

Example

Using File_HtAccess::setAuthType()

<?php
require_once('File/HtAccess.php');

/* use Digest authentication  */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setAuthType('Digest');
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::setAuthGroupFile() | PEAR Manual | File_HtAccess::setAuthDigestFile


File_HtAccess::setAuthDigestFile

File_HtAccess::setAuthDigestFile

File_HtAccess::setAuthDigestFile – set the value of authdigestfile property

Synopsis

void File_HtAccess::setAuthDigestFile ( string $file )

Description

Sets the value of authdigestfile property. AuthDigestFile is the password file which contains username:realm:password pairs for Digest authentication. You must give full path to the password file in order for it to work.

Parameter

  • string $file - absolute pathname to the password file.

Return value

void

Note

This function can not be called statically.

See

  • File_HtAccess::setAuthUserFile()

Example

Using File_HtAccess::setauthdigestfile()

<?php
require_once('File/HtAccess.php');

/* set the password file to /etc/htdigest */
$fh = new File_HtAccess('.htaccess');
$fh->load();
$fh->setauthdigestfile('/etc/htdigest');
$fh->save();

?>
Prev | File_HtAccess | Next
File_HtAccess::setAuthType | PEAR Manual | Gtk


Gtk

Gtk

Provides useful packages for the PHP-Gtk extension.

Table of Contents
  • FileDrop
  • Gtk_ScrollingLabel
  • Gtk_VarDump
Prev | PEAR Packages | Next
File_HtAccess::setAuthDigestFile | PEAR Manual | FileDrop


FileDrop

FileDrop

Setting up GtkWidgets to accept files via Drag'n'Drop in a very easy way.

Table of Contents
  • Introduction -- Why using Gtk_FileDrop?
  • Widget support -- Drops handled on different widget types
  • Example -- How to use Gtk_FileDrop
Prev | Gtk | Next
Gtk | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Why using Gtk_FileDrop?

Contributors

  • Christian Weiske

Description

Gtk_FileDrop provides an easy interface to set up GtkWidgets to receive files via Drag'n'Drop. Widgets can be told to accept a number of MIME-Types as well as a number of file extensions. Values of widgets can automatically be set when drops with valid files occur, or a callback function can be specified which is invoked in this case.

Now one may think that the whole setup process is really simple and would not need a class like this to make widgets accept files. That is right. The setup for making widgets accept drops is an ease - but there are two more steps to do:

  1. Make the widget accept only some types of files

  2. Convert the dropped filenames to usable filenames

The first item is not so hard to implement; we do this by either checking the file extension, or using the MIME_Type package to get the mime type. (Note: * is supported).

The second item is the main problem as all applications seem to ignore the standard for file name exchange and cook their own soup (so using their own format) when passing the file names. This package knows the differences and converts the dropped strings into usable local filenames, regardless of the format the source application uses. For a deeper insight in this topic you should read the PHP-Gtk FileDrop tutorial.

Note: A note about Mozilla/Firefox: Mozilla provides file names only with mime type text/plain only instead of text/uri-list. If we would accept this type as well, the problem arises that every text could be dropped - if it is a file or not. That's why the decision was made not to accept drops from Mozilla.
Prev | FileDrop | Next
FileDrop | PEAR Manual | Widget support


Widget support

Widget support

Widget support – Drops handled on different widget types

Natively supported widgets

By default, the dropped files are displayed in the widget, e.g. if you drop a file over a GtkEntry, the text value of the widget will be overwritten to the filename.

As not all widgets have such simple values, Gtk_FileDrop has built-in support for a number of widget classes and acts different on different types.

Widget support
Widget class | Action taken
GtkEntry | Entry value is replaced with first file
GtkLabel | Label text is replaced with first file
GtkButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkToggleButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkRadioButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkCheckButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkCombo | The entry text is replaced with the first file. The list is not affected.
GtkFileSelection | File name of the file dialog is set to the first dropped file. The directory is changed to the directory name of the file, and the file name (without directory) is set in the file name entry.
GtkList | Every accepted file is appended at the end of the list.

Beside the automatic actions, you can specify a callback as the third parameter of the attach function which is called with the widget itself and an array of accepted files as parameters.

Prev | FileDrop | Next
Introduction | PEAR Manual | Example


Example

Example

Example – How to use Gtk_FileDrop

Using Gtk_FileDrop

General setup

<?php
$accepted_types = array(
    'text/html',
    'text/plain',
    '.dat'
);
Gtk_FileDrop::attach($widget, $accepted_types);
?>

Here we set up the array of accepted file types: The widget shall accept files with MIME-Type text/html, text/plain and files ending with .dat. After this we set up the $widget to accept this files.

Accepting directories

<?php
$accepted_types = array(
    'inode/directory',
);
?>

The MIME type inode/directory has to be used if the widget shall accept directories.

Note: When a file is dropped over a widget which accepts directories only, the directory of the filename is used.

Setup with callback

<?php
function filesDropped($widget, $arFiles) {
    foreach($arFiles as $strFile) {
        echo "The file \"$strFile\" has been dropped\r\n";
    }
}

$accepted_types = array(
    'text/html',
    'text/plain',
    '.dat'
);
Gtk_FileDrop::attach($widget, $accepted_types, 'filesDropped', false);
?>

In this example we use a callback function to print out all dropped files to the console. Further we determine the fourth parameter as false which means that the widget's value is not changed automatically.

To use the callback with objects, you pass an array with the reference of the object:

Using a callback

<?php
Gtk_FileDrop::attach($widget, $accepted_types, array( &$this, 'filesDropped'));
?>

Working example

<?php
if (!extension_loaded('gtk')) {
    dl('php_gtk.' . PHP_SHLIB_SUFFIX);
}
require_once('Gtk/FileDrop.php');

$window = &new GtkWindow();
$window->set_default_size(300, 30);
$window->connect_object('destroy', array('gtk', 'main_quit'));
$window->show();

$entry =& new GtkEntry();
$window->add($entry);
$entry->set_text('drop text files on me');
Gtk_FileDrop::attach($entry, array('text/plain'));

$window->show_all();
gtk::main();
?>
Prev | FileDrop | Next
Widget support | PEAR Manual | Gtk_ScrollingLabel


Gtk_ScrollingLabel

Gtk_ScrollingLabel

A class that creates a scrolling marquee.

This package has been superseded. Please use Gtk2_ScrollingLabel for new projects.

Table of Contents
  • Introduction -- Getting started with Gtk_Scrollinglabel?
  • Gtk_ScrollingLabel::getFullText -- Returns the full text of the label.
  • Gtk_ScrollingLabel::getHiddenText -- Returns all of the text that is not currently visible.
  • Gtk_ScrollingLabel::getScrollingLabel -- Returns a GtkEventBox with the scrolling label inside.
  • Gtk_ScrollingLabel::getStyle -- Gets the label's style widget
  • Gtk_ScrollingLabel::getVisibleLength -- Returns the length of the visible area in characters.
  • Gtk_ScrollingLabel::pause -- Stops the label from scrolling without reseting the label text
  • Gtk_ScrollingLabel::setBounce -- Sets the text to bounce between the borders of the label
  • Gtk_ScrollingLabel::setStartSignal -- Connects the startScroll method to a given event.
  • Gtk_ScrollingLabel::startScroll -- Begins scrolling the text from the start of the string.
  • Gtk_ScrollingLabel::unPause -- Begins scrolling the label from its current position
Prev | Gtk | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Getting started with Gtk_Scrollinglabel?

Contributors

  • Scott Mattocks

Description

Gtk_ScrollingLabel is a class that creates a pseudo-widget which makes scrolling text within a label easy. The text within the label can be set to scroll from left to right, right to left, or bounce within the boundries of the label. The speed of the scrolling text can also be controlled. There are also built in methods to make the text pause or stop when the user moves the mouse over the label and start up again when the mouse leaves the label space.

Getting started with Gtk_ScrollingLabel is easy. All you need to do is instantiate the class, add it to a window, and start the scrolling. Take at look at the example below.

Simple Setup

<?php
// Create a Gtk_ScrollingLabel instance.
require_once 'Gtk/ScrollingLabel.php';
$sLabel =& new Gtk_ScrollingLabel('Scrolling Labels Rule!');

// Create a GtkWindow to put the label in.
$gWin =& new GtkWindow;
$gWin->connect_object('destroy', array('gtk', 'main_quit'));
$gWin->add($sLabel->getWidget());

// Show everything.
$gwin->show_all();

// Start the label and the main loop.
$sLabel->startScroll();
gtk::main();
?>
Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel | PEAR Manual | Gtk_ScrollingLabel::getFullText


Gtk_ScrollingLabel::getFullText

Gtk_ScrollingLabel::getFullText

Gtk_ScrollingLabel::getFullText – Returns the full text of the label.

Synopsis

require_once 'Gtk/ScrollingLabel.php';

string Gtk_ScrollingLabel::getFullText ( )

Description

Returns the full text of the label. The full text is the text that was set on construction or with setFullText() not just what is currently visible.

Return value

returns the full text of the label.

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Introduction | PEAR Manual | Gtk_ScrollingLabel::getHiddenText


Gtk_ScrollingLabel::getHiddenText

Gtk_ScrollingLabel::getHiddenText

Gtk_ScrollingLabel::getHiddenText – Returns all of the text that is not currently visible.

Synopsis

require_once 'Gtk/ScrollingLabel.php';

string Gtk_ScrollingLabel::getHiddenText ( )

Description

Returns the portion of the full label text that is currently not being shown.

Return value

returns the label text that is not visible.

See

getFullText()

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::getFullText | PEAR Manual | Gtk_ScrollingLabel::getScrollingLabel


Gtk_ScrollingLabel::getScrollingLabel

Gtk_ScrollingLabel::getScrollingLabel

Gtk_ScrollingLabel::getScrollingLabel – Returns a GtkEventBox with the scrolling label inside.

Synopsis

require_once 'Gtk/ScrollingLabel.php';

void Gtk_ScrollingLabel::getScrollingLabel ( )

Description

Returns the GtkEventBox that contains the scrolling label.

Return value

returns the GtkEventBox containing the scrolling label.

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::getHiddenText | PEAR Manual | Gtk_ScrollingLabel::getStyle


Gtk_ScrollingLabel::getStyle

Gtk_ScrollingLabel::getStyle

Gtk_ScrollingLabel::getStyle – Gets the label's style widget

Synopsis

require_once 'Gtk/ScrollingLabel.php';

&object Gtk_ScrollingLabel::getStyle ( )

Description

Returns the label's style widget. This lets you make changes to the style to alter the look and feel of the widget. You can change the font of the display, the color of the background, etc.

Return value

returns the GtkStyle widget for the label.

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::getScrollingLabel | PEAR Manual | Gtk_ScrollingLabel::getVisibleLength


Gtk_ScrollingLabel::getVisibleLength

Gtk_ScrollingLabel::getVisibleLength

Gtk_ScrollingLabel::getVisibleLength – Returns the length of the visible area in characters.

Synopsis

require_once 'Gtk/ScrollingLabel.php';

int Gtk_ScrollingLabel::getVisibleLength ( )

Description

Returns the length of the visible area in characters. The length of the visible area is the maximum number of characters that are visible at one time.

Return value

integer the maximum number of characters that are visible at one time.

See

setVisibleLength()

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::getStyle | PEAR Manual | Gtk_ScrollingLabel::pause


Gtk_ScrollingLabel::pause

Gtk_ScrollingLabel::pause

Gtk_ScrollingLabel::pause – Stops the label from scrolling without reseting the label text

Synopsis

require_once 'Gtk/ScrollingLabel.php';

void Gtk_ScrollingLabel::pause ( )

Description

Stops the label from scrolling but does not reset the label text to the begining. If you want the label to stop scrolling and return to its original position (blank), use stopScroll().

Return value

returns true if the scrolling has stopped.

See

unPause()

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::getVisibleLength | PEAR Manual | Gtk_ScrollingLabel::setBounce


Gtk_ScrollingLabel::setBounce

Gtk_ScrollingLabel::setBounce

Gtk_ScrollingLabel::setBounce – Sets the text to bounce between the borders of the label

Synopsis

require_once 'Gtk/ScrollingLabel.php';

boolean Gtk_ScrollingLabel::setBounce ( boolean $bounce )

Description

If $bounce is true, the text will scroll to the left until the first character hits the left edge of the visible window then it will scroll back to the right. When the last character hits the right edge of the visible window the text will scroll back to the left again.

If all of the scrolling text cannot be viewed at once, making the text bounce will have an undesired result. Therefore it is suggested that the length of the text always be at least one character less than the maximum viewable string length.

Parameter

  • boolean $bounce - Whether or not the text should change direction when it hits a label edge.

Return value

returns Whether or not the text is set to bounce

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::pause | PEAR Manual | Gtk_ScrollingLabel::setStartSignal


Gtk_ScrollingLabel::setStartSignal

Gtk_ScrollingLabel::setStartSignal

Gtk_ScrollingLabel::setStartSignal – Connects the startScroll() method to a given event.

Synopsis

require_once 'Gtk/ScrollingLabel.php';

void Gtk_ScrollingLabel::setStartSignal ( string $signal )

Description

setStartSignal() will make the event box listen for the signal $signal and will envoke startScroll() when ever it is heard. The signal should be a signal that GtkEventBox listens for normally or a button press event.

Parameter

  • string $signal - The Gtk signal to connect to startScroll().

Return value

returns The handler id for the connection.

See

startScroll()

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::setBounce | PEAR Manual | Gtk_ScrollingLabel::startScroll


Gtk_ScrollingLabel::startScroll

Gtk_ScrollingLabel::startScroll

Gtk_ScrollingLabel::startScroll – Begins scrolling the text from the start of the string.

Synopsis

require_once 'Gtk/ScrollingLabel.php';

boolean Gtk_ScrollingLabel::startScroll ( )

Description

startScroll() will make the text begin scrolling in the direction given by calling setDirection(). If the text is scrolling left to right (GTK_SCROLLINGLABEL_RIGHT), the current character position is set to the end of the text. This means that the last character of the label will be the first character shown. If the text is scrolling right to left (GTK_SCROLLINGLABEL_LEFT), the current character position is set to zero. This means that first character shown will be a blank space.

This method is best used when connected to an event.

Return value

returns true if the text has started scrolling. false otherwise.

See

setStartSignal()

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::setStartSignal | PEAR Manual | Gtk_ScrollingLabel::unPause


Gtk_ScrollingLabel::unPause

Gtk_ScrollingLabel::unPause

Gtk_ScrollingLabel::unPause – Begins scrolling the label from its current position

Synopsis

require_once 'Gtk/ScrollingLabel.php';

void Gtk_ScrollingLabel::unPause ( )

Description

Begins scrolling the label from its current position. unPause() is different from startScroll() in that it does not reset the label to the begining of the text.

Return value

returns true if the text has started scrolling.

See

pause()

startScroll()

Note

This function can not be called statically.

Prev | Gtk_ScrollingLabel | Next
Gtk_ScrollingLabel::startScroll | PEAR Manual | Gtk_VarDump


Gtk_VarDump

Gtk_VarDump

Provides a simple GUI to examine PHP variables, for example complex arrays or objects.

The GUI consists of two parts: a tree on the left side, displaying the values/objects/arrays that have subkeys/subvalues, and a list with scalar key-value pairs on the right side.

To use it, just include Gtk/VarDump.php and call the constructor with the variable to be dumped.

Inspecting a variable with Gtk_VarDump

<?php
//some test class to dump
class Test
{
    var $color  = 'blue';
    var $foo    = 'bar';
    var $self   = null;
    var $server = null;

    function Test()
    {
        $this->self   =& $this;
        $this->server =& $_SERVER;
    }

    function doNothing()
    {
        //we're doing nothing here
    }
}

//include & display the variable
require_once 'Gtk/VarDump.php';
new Gtk_VarDump(new Test());
?>
Prev | Gtk | Next
Gtk_ScrollingLabel::unPause | PEAR Manual | Gtk2


Gtk2

Gtk2

Provides useful packages for the PHP-Gtk2 extension.

Table of Contents
  • Gtk2_EntryDialog
  • Gtk2_ExceptionDump
  • Gtk2_FileDrop
  • Gtk2_IndexedComboBox
  • Gtk2_PHPConfig
  • Gtk2_ScrollingLabel
  • Gtk2_VarDump
Prev | PEAR Packages | Next
Gtk_VarDump | PEAR Manual | Gtk2_EntryDialog


Gtk2_EntryDialog

Gtk2_EntryDialog

The package provides a simple dialogbox for text input.

Table of Contents
  • Introduction -- About Gtk2_EntryDialog
  • constructor Gtk2_EntryDialog -- Create a entry dialog instance.
  • Gtk2_EntryDialog::new_simple -- Simplified constructor with not so much parameters.
  • Gtk2_EntryDialog::get -- Show the dialog and retrieve the text
  • Gtk2_EntryDialog::run -- Show the dialog and block until a button has been pressed.
  • Gtk2_EntryDialog::get_text -- Returns the text input by the user.
  • Gtk2_EntryDialog::set_text -- Sets the text for the entry
  • Gtk2_EntryDialog::set_default_response -- Set the default response.
Prev | Gtk2 | Next
Gtk2 | PEAR Manual | Introduction


Introduction

Introduction

Introduction – About Gtk2_EntryDialog

About Gtk2_EntryDialog

Gtk2_EntryDialog provides a dialog with a message and one single text input field, and some buttons like OK and Cancel. The class tries to make it as easy as possible to get the text from the user with only a few lines of code, while keeping the full power of the GtkDialog class.

The most easy way to retrieve the text with one line of code is using the get() static method.

Prev | Gtk2_EntryDialog | Next
Gtk2_EntryDialog | PEAR Manual | constructor Gtk2_EntryDialog


constructor Gtk2_EntryDialog

constructor Gtk2_EntryDialog

constructor Gtk2_EntryDialog() – Create a entry dialog instance.

Synopsis

require_once 'Gtk2/EntryDialog.php';

void constructor Gtk2_EntryDialog::__construct ( GtkWindow $parent , GtkDialogFlags $flags , GtkMessageType $type , GtkButtonsType $buttons , string $message , string $default )

Description

Creates a new entry dialog instance. After creating it, you can modify it and finally use the run() to show it and await the input.

You might want to use a more simple constructor, e.g. get() or new_simple()

<?php
require_once 'Gtk2/EntryDialog.php';

$id = new Gtk2_EntryDialog(
    null,                       //parent window
    0,                          //flags (GtkDialogFlags)
    Gtk::MESSAGE_QUESTION,      //type of message
    Gtk::BUTTONS_OK_CANCEL,     //which buttons shall be there
    'What\'s your name?',       //the message
    'Don\'t know'               //The default text
);

$answer = $id->run();
$id->destroy();
if ($answer == Gtk::RESPONSE_OK) {
    echo 'The name is: ';
    var_dump($id->get_text());
} else {
    echo "You cancelled\r\n";
}
?>

Parameter

GtkWindow $parent

Parent window (can be null).

GtkDialogFlags $flags

Dialog flags (use 0 as default)

GtkMessageType $type

Message type (e.g. Gtk::MESSAGE_QUESTION)

GtkButtonsType $buttons

Buttons to show (e.g. Gtk::BUTTONS_OK)

string $message

Message to display.

string $default

Default text for the entry.

Prev | Gtk2_EntryDialog | Next
Introduction | PEAR Manual | Gtk2_EntryDialog::new_simple


Gtk2_EntryDialog::new_simple

Gtk2_EntryDialog::new_simple

Gtk2_EntryDialog::new_simple() – Simplified constructor with not so much parameters.

Synopsis

require_once 'Gtk2/EntryDialog.php';

Gtk2_EntryDialog Gtk2_EntryDialog::new_simple ( string $message , string $default = null , GtkWindow $parent = null )

Description

Simplified constructor with not so much parameters.

Message type is Gtk::MESSAGE_QUESTION, the flags will be Gtk::DIALOG_MODAL if the parent is set. Only one button, OK, will be visible.

<?php
require_once 'Gtk2/EntryDialog.php';

$id = Gtk2_EntryDialog::new_simple(
    'What\'s your name?',       //the message
    'Don\'t know'               //The default text
);

$answer = $id->run();
$id->destroy();
if ($answer == Gtk::RESPONSE_OK) {
    echo 'The name is: ';
    var_dump($id->get_text());
} else {
    echo "You cancelled\r\n";
}
?>

Parameter

string $message

Message to display.

string $default

Default text for the entry.

GtkWindow $parent

Parent window (can be null).

Prev | Gtk2_EntryDialog | Next
constructor Gtk2_EntryDialog | PEAR Manual | Gtk2_EntryDialog::get


Gtk2_EntryDialog::get

Gtk2_EntryDialog::get

Gtk2_EntryDialog::get() – Show the dialog and retrieve the text

Synopsis

require_once 'Gtk2/EntryDialog.php';

string Gtk2_EntryDialog::get ( string $message , string $default , GtkWindow $parent )

Description

Creates a dialog with the given parameters, runs it, and returns the text set. If the user cancelled the dialog, this method returns FALSE. In any other case (even when the text is empty), the a string with the text is returned.

<?php
require_once 'Gtk2/EntryDialog.php';

$text = Gtk2_EntryDialog::get(
    'What\'s your name?',       //the message
    'Don\'t know'               //The default text
);

if ($text !== false) {
    echo 'The name is: ';
    var_dump($text);
} else {
    echo "You cancelled\r\n";
}
?>

Parameter

string $message

Message to display.

string $default

Default text for the entry.

GtkWindow $parent

Parent window (can be null).

Return value

returns False if the user cancelled input, the text (string) otherwise.

Prev | Gtk2_EntryDialog | Next
Gtk2_EntryDialog::new_simple | PEAR Manual | Gtk2_EntryDialog::run


Gtk2_EntryDialog::run

Gtk2_EntryDialog::run

Gtk2_EntryDialog::run() – Show the dialog and block until a button has been pressed.

Synopsis

require_once 'Gtk2/EntryDialog.php';

int Gtk2_EntryDialog::run ( )

Description

Show the dialog and block until a button has been pressed.

Return value

returns The response id of the pressed button.

Prev | Gtk2_EntryDialog | Next
Gtk2_EntryDialog::get | PEAR Manual | Gtk2_EntryDialog::get_text


Gtk2_EntryDialog::get_text

Gtk2_EntryDialog::get_text

Gtk2_EntryDialog::get_text() – Returns the text input by the user.

Synopsis

require_once 'Gtk2/EntryDialog.php';

string Gtk2_EntryDialog::get_text ( )

Description

Retrieves the text from the entry.

Return value

returns The input from the user.

Prev | Gtk2_EntryDialog | Next
Gtk2_EntryDialog::run | PEAR Manual | Gtk2_EntryDialog::set_text


Gtk2_EntryDialog::set_text

Gtk2_EntryDialog::set_text

Gtk2_EntryDialog::set_text() – Sets the text for the entry

Synopsis

require_once 'Gtk2/EntryDialog.php';

string Gtk2_EntryDialog::set_text ( string $text )

Description

Sets the text for the entry.

Prev | Gtk2_EntryDialog | Next
Gtk2_EntryDialog::get_text | PEAR Manual | Gtk2_EntryDialog::set_default_response


Gtk2_EntryDialog::set_default_response

Gtk2_EntryDialog::set_default_response

Gtk2_EntryDialog::set_default_response() – Set the default response.

Synopsis

require_once 'Gtk2/EntryDialog.php';

void Gtk2_EntryDialog::set_default_response ( int $response_id )

Description

Set the default response.

The button with the id will be the default one, allowing you to just press return to activate it.

Parameter

int $response_id

Response code

Prev | Gtk2_EntryDialog | Next
Gtk2_EntryDialog::set_text | PEAR Manual | Gtk2_ExceptionDump


Gtk2_ExceptionDump

Gtk2_ExceptionDump

Catches and displays PHP errors, notices and warnings as well as PEAR Errors and uncaught exceptions.

Table of Contents
  • Introduction -- Using Gtk2_ExceptionDump
  • Re-using Gtk2_ExceptionDump -- Embedding it in own applications
Prev | Gtk2 | Next
Gtk2_EntryDialog::set_default_response | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Using Gtk2_ExceptionDump

About Gtk2_ExceptionDump

Gtk2_ExceptionDump catches and displays common errors and warnings that can be produced in a PHP scripts: PHP errors, notices and warnings as well as PEAR Errors and uncaught exceptions. They are displayed in a Gtk2 window with a tree view, providing the error message and the backtrace with passed parameters.

The most easy thing to do is letting the class handle everything automatically. You can decide which errors should be catched: All, PHP errors, PEAR errors or uncaught exceptions. The following methods need to be called statically to set up error handling:

  • setupExceptionHandler()

  • setupPearErrorHandler()

  • setupPhpErrorHandler()

  • setupAllHandlers()

Letting Gtk2_ExceptionDump handle all errors

<?php
require_once 'Gtk2/ExceptionDump.php';
Gtk2_ExceptionDump::setupAllHandlers();
?>

Handling exceptions by hand

If you don't want to let Gtk2_ExceptionDump handle errors automatically, you can display the window by hand, e.g. in a catch() statement.

Catching exceptions by hand

<?php
try {
    //do some stuff that
    //could throw an exception
} catch (Exception $e) {
    require_once 'Gtk2/ExceptionDump.php';
    Gtk2_ExceptionDump::display($e);
}
?>

More examples

As usually, the package has more examples in the doc directory: /path/to/pear/docs/Gtk2_ExceptionDump/examples/.

Prev | Gtk2_ExceptionDump | Next
Gtk2_ExceptionDump | PEAR Manual | Re-using Gtk2_ExceptionDump


Re-using Gtk2_ExceptionDump

Re-using Gtk2_ExceptionDump

Re-using Gtk2_ExceptionDump – Embedding it in own applications

Re-using Gtk2_ExceptionDump

You can make use of the brain power that went into the development of Gtk2_ExceptionDump by embedding the stack trace treeview into your own application.

There class you want is Gtk2_ExceptionDump_Stack. It's a subclass of GtkTreeView and should be embedded in a GtkScrolledWindow if you use it. The constructor takes the exception object, but it can be omitted and set later by using setException().

Prev | Gtk2_ExceptionDump | Next
Introduction | PEAR Manual | Gtk2_FileDrop


Gtk2_FileDrop

Gtk2_FileDrop

Setting up GtkWidgets to accept files via Drag'n'Drop in a very easy way.

Table of Contents
  • Introduction -- Why using Gtk2_FileDrop?
  • Widget support -- Drops handled on different widget types
  • Example -- How to use Gtk2_FileDrop
Prev | Gtk2 | Next
Re-using Gtk2_ExceptionDump | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Why using Gtk2_FileDrop?

Contributors

  • Christian Weiske

Description

Gtk2_FileDrop provides an easy interface to set up GtkWidgets to receive files via Drag'n'Drop. Widgets can be told to accept a number of MIME-Types as well as a number of file extensions. Values of widgets can automatically be set when drops with valid files occur, or a callback function can be specified which is invoked in this case.

Now one may think that the whole setup process is really simple and would not need a class like this to make widgets accept files. That is right. The setup for making widgets accept drops is an ease - but there are two more steps to do:

  1. Make the widget accept only some types of files

  2. Convert the dropped filenames to usable filenames

The first item is not so hard to implement; we do this by either checking the file extension, or using the MIME_Type package to get the mime type. (Note: * is supported).

The second item is the main problem as all applications seem to ignore the standard for file name exchange and cook their own soup (so using their own format) when passing the file names. This package knows the differences and converts the dropped strings into usable local filenames, regardless of the format the source application uses. For a deeper insight in this topic you should read the PHP-Gtk FileDrop tutorial.

Note: A note about Mozilla/Firefox: Mozilla provides file names only with mime type text/plain only instead of text/uri-list. If we would accept this type as well, the problem arises that every text could be dropped - if it is a file or not. That's why the decision was made not to accept drops from Mozilla.
Note: Gtk2_FileDrop is the port of Gtk_FileDrop to PHP-Gtk2 and PHP5. Thus, it has identical methods and behaves the same.
Prev | Gtk2_FileDrop | Next
Gtk2_FileDrop | PEAR Manual | Widget support


Widget support

Widget support

Widget support – Drops handled on different widget types

Natively supported widgets

By default, the dropped files are displayed in the widget, e.g. if you drop a file over a GtkEntry, the text value of the widget will be overwritten to the filename.

As not all widgets have such simple values, Gtk2_FileDrop has built-in support for a number of widget classes and acts different on different types.

Widget support
Widget class | Action taken
GtkEntry | Entry value is replaced with first file
GtkLabel | Label text is replaced with first file
GtkButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkToggleButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkRadioButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkCheckButton | Label text is replaced with first file if the first and only child is a GtkLabel
GtkCombo | The entry text is replaced with the first file. The list is not affected.
GtkFileSelection | File name of the file dialog is set to the first dropped file. The directory is changed to the directory name of the file, and the file name (without directory) is set in the file name entry.
GtkList | Every accepted file is appended at the end of the list.

Beside the automatic actions, you can specify a callback as the third parameter of the attach function which is called with the widget itself and an array of accepted files as parameters.

Prev | Gtk2_FileDrop | Next
Introduction | PEAR Manual | Example


Example

Example

Example – How to use Gtk2_FileDrop

Using Gtk2_FileDrop

General setup

<?php
$accepted_types = array(
    'text/html',
    'text/plain',
    '.dat'
);
Gtk2_FileDrop::attach($widget, $accepted_types);
?>

Here we set up the array of accepted file types: The widget shall accept files with MIME-Type text/html, text/plain and files ending with .dat. After this we set up the $widget to accept this files.

Accepting directories

<?php
$accepted_types = array(
    'inode/directory',
);
?>

The MIME type inode/directory has to be used if the widget shall accept directories.

Note: When a file is dropped over a widget which accepts directories only, the directory of the filename is used.

Setup with callback

<?php
function filesDropped($widget, $arFiles) {
    foreach($arFiles as $strFile) {
        echo "The file \"$strFile\" has been dropped\r\n";
    }
}

$accepted_types = array(
    'text/html',
    'text/plain',
    '.dat'
);
Gtk2_FileDrop::attach($widget, $accepted_types, 'filesDropped', false);
?>

In this example we use a callback function to print out all dropped files to the console. Further we determine the fourth parameter as false which means that the widget's value is not changed automatically.

To use the callback with objects, you pass an array with the reference of the object:

Using a callback

<?php
Gtk2_FileDrop::attach($widget, $accepted_types, array( &$this, 'filesDropped'));
?>

Working example

<?php
require_once 'Gtk2/FileDrop.php';

$window = new GtkWindow();
$window->set_default_size(300, 30);
$window->connect_simple('destroy', array('gtk', 'main_quit'));
$window->show();

$entry = new GtkEntry();
$window->add($entry);
$entry->set_text('drop text files on me');
Gtk2_FileDrop::attach($entry, array('text/plain'));

$window->show_all();
Gtk::main();
?>
Prev | Gtk2_FileDrop | Next
Widget support | PEAR Manual | Gtk2_IndexedComboBox


Gtk2_IndexedComboBox

Gtk2_IndexedComboBox

Gtk2_IndexedComboBox is a Gtk2 widget similar to the HTML select box - it lets you not only store values as the normal GtkComboBox, but associated key/value pairs.

Gtk2_IndexedComboBox is meant to be as easy to use as possible, and to have an API similar to the combo boxes created with GtkComboBox::new_text(). You can directly add key/value pairs to the widget instead of using the model (which is possible, too). Retrieving the currently selected key can be done with a single method call.

Both keys and values can be strings, thus allowing integers implicitly. This is very useful if you need a widget to select some row ID from a database, but want to display some descriptive string. By default, a single GtkCellRendererText is used as cell renderer.

Table of Contents
  • Simple example -- To get started easily
  • Conquering Glade combo boxes -- How to use glade combos with this class
  • Gtk2_IndexedComboBox -- The main class
  • Gtk2_IndexedComboBox_Model -- Model class behind the scenes
Prev | Gtk2 | Next
Example | PEAR Manual | Simple example


Simple example

Simple example

Simple example – To get started easily

Simple example

In this example, we will create a combo box, add an array of key/value pairs and display the currently selected pair in a label.

Simple Gtk2_IndexedComboBox example

<?php
require_once 'Gtk2/IndexedComboBox.php';

//display this data
$arData = array(
    1   => 'Germany',
    2   => 'United Kingdom',
    3   => 'Spain',
    4   => 'France'
);

//Create combo and set the array
$combo = new Gtk2_IndexedComboBox();
$combo->set_array($arData);
//make #2 active
$combo->set_active_key(2);

//trace changes
$combo->connect('changed', 'comboChanged', $lbl);

function comboChanged($combo, $lbl)
{
    $lbl->set_text(
        "Combo changed:\r\n"
        . 'Key: '   . $combo->get_active_key() . "\r\n"
        . 'Value: ' . $combo->get_active_text()
    );
}

//some label to display changes
$lbl = new GtkLabel("Status\r\n\r\n");

//standard stuff
$vbox = new GtkVBox();
$vbox->pack_start($combo);
$vbox->pack_start($lbl);

$wnd = new GtkWindow();
$wnd->connect_simple('destroy', array('Gtk', 'main_quit'));
$wnd->add($vbox);
$wnd->show_all();
Gtk::main();
?>

At first, we create a new combo widget object. You already could pass the array of data in the constructor if you wanted to, but here we use the set_array() method to do this. After providing the data, entry with id 2 is made active/pre-selected.

Whenever the selection changes, the example displays the selected key and value in a label below the combo box. We use get_active_key() to retrieve the key, and get_active_text() to retrieve the value.

Prev | Gtk2_IndexedComboBox | Next
Gtk2_IndexedComboBox | PEAR Manual | Conquering Glade combo boxes


Conquering Glade combo boxes

Conquering Glade combo boxes

Conquering Glade combo boxes – How to use glade combos with this class

Conquering Glade combo boxes

While designing your user interface with Glade is really convenient and easy, it doesn't allow you to use custom classes as this combo here. Thanks to the MVC model in Gtk2, you still can use this class's power by using the same model as Gtk2_IndexedComboBox uses internally: Gtk2_IndexedComboBox_Model.

Glade file to use

<?xml version="1.0" standalone="no"?> <!--*- mode: xml -*-->
<!DOCTYPE glade-interface SYSTEM "http://glade.gnome.org/glade-2.0.dtd">

<glade-interface>

<widget class="GtkWindow" id="wndTest">
  <property name="visible">True</property>
  <property name="title" translatable="yes">Gtk2_IndexedComboBox_Model test</property>
  <property name="type">GTK_WINDOW_TOPLEVEL</property>
  <property name="window_position">GTK_WIN_POS_NONE</property>
  <property name="modal">False</property>
  <property name="resizable">True</property>
  <property name="destroy_with_parent">False</property>
  <property name="decorated">True</property>
  <property name="skip_taskbar_hint">False</property>
  <property name="skip_pager_hint">False</property>
  <property name="type_hint">GDK_WINDOW_TYPE_HINT_NORMAL</property>
  <property name="gravity">GDK_GRAVITY_NORTH_WEST</property>
  <signal name="destroy" handler="Gtk::main_quit"/>

  <child>
    <widget class="GtkComboBox" id="cmbNormal">
      <property name="visible">True</property>
    </widget>
  </child>
</widget>

</glade-interface>

PHP code

<?php
require_once 'Gtk2/IndexedComboBox/Model.php';

$glade = new GladeXML(dirname(__FILE__) . '/glade.glade');
$glade->signal_autoconnect();

$combo = $glade->get_widget('cmbNormal');
$combo->connect('changed', 'comboChanged');
//show the second column only
$renderer = new GtkCellRendererText();
$combo->pack_start($renderer);
$combo->set_attributes($renderer, 'text', 1);

$mod = new Gtk2_IndexedComboBox_Model();
$combo->set_model($mod);

$mod->append(1, 'One');
$mod->append_array(array(2 => 'Two', 3 => 'Three'));
$mod->prepend(4, 'Four');

function comboChanged($combo)
{
$nActive = $combo->get_active();
$iter = $combo->get_model()->get_iter($nActive);

$key = $combo->get_model()->get_key($iter);
$text = $combo->get_model()->get_text($iter);

echo 'Selected: ' . $key . ' => ' . $text . "\r\n";
}

Gtk::main();
?>

The important thing to remember is that you need to setup your own cell renderer, and tell it which column in the model shall be displayed. Beside that, you just do the normal model-creation-and-setting via set_model().

All data manipulation methods of Gtk2_IndexedComboBox you saw in the previous example are available in the model, Gtk2_IndexedComboBox_Model. Only get_active_key() and get_active_text() cannot be used on the model, since this doesn't know anything about selections. Retrieve the selected GtkTreeIter by combining the calls of get_active() and get_iter(), and pass this iter object to get_key() and get_text().

Prev | Gtk2_IndexedComboBox | Next
Simple example | PEAR Manual | Gtk2_IndexedComboBox


Gtk2_IndexedComboBox

Gtk2_IndexedComboBox

Gtk2_IndexedComboBox – The main class

Gtk2_IndexedComboBox

Gtk2_IndexedComboBox automatically creates the model and sets up the cell renderer when instantiating the widget. You may pass an array of key/value pairs to the constructor if you like to, but also can set them later.

The currently selected (active) key can be retrieved via get_active_key(), the selected (active) value by using get_active_text(). You can preselect a certain key with set_active_key().

If you don't like the renderer or want to change it or its attributes, use get_cell_renderer() and set_cell_renderer().

All other methods to retrieve/store data are convenience methods that act as proxy to the model. For example, Gtk2_IndexedComboBox' method set_array() internally calls the same method on the model, Gtk2_IndexedComboBox_Model. This allows you to quickly add some data to the combo without getting the model first and acting on it.

Prev | Gtk2_IndexedComboBox | Next
Conquering Glade combo boxes | PEAR Manual | Gtk2_IndexedComboBox_Model


Gtk2_IndexedComboBox_Model

Gtk2_IndexedComboBox_Model

Gtk2_IndexedComboBox_Model – Model class behind the scenes

Gtk2_IndexedComboBox_Model

The model class is the data storage for your key/value pairs. It contains two columns, both are of type Gtk::TYPE_STRING and can hold text and numbers. The first is used for the keys, the values are stored in the second column.

The class has several method that allow you to store data in the model: The classis set_array() takes an associative array of key/value pairs. Once set, you can use append_array() and prepend_array() to add new data after or before the current values. You also have the possibility to use insert_array() that takes the position as first, and the data array as second parameter.

Beside the *_array methods, you can add single key/value pairs by using append() and prepend() which take the key as first, and the value as second parameter. insert() wants an additional position number as first parameter, and key/value as second and third.

To delete data from the model, use remove_key(). After finishing your data manipulation, you can retrieve the full associative array of key/value pairs via get_array().

To obtain the key or value of a certain GtkTreeIter (that you got e.g. from the model by using get_iter()), use get_key() and get_text().

Prev | Gtk2_IndexedComboBox | Next
Gtk2_IndexedComboBox | PEAR Manual | Gtk2_PHPConfig


Gtk2_PHPConfig

Gtk2_PHPConfig

Provides a simple GUI to enable the user to edit php.ini values.

Table of Contents
  • Introduction -- About Gtk2_PHPConfig
  • Usage -- Using Gtk2_PHPConfig
Prev | Gtk2 | Next
Gtk2_IndexedComboBox_Model | PEAR Manual | Introduction


Introduction

Introduction

Introduction – About Gtk2_PHPConfig

Description

This package will be useful for PHP-GTK 2 based applications which require the user to make changes to php.ini. The class can parse any existing ini file, or create new ones. Parsing of existing files is currently a little inefficient, suggestions for improvement are welcome. New files and files previously generated by Gtk2_PHPConfig are parsed at a good speed though.

The interface displays all available configuration sections on the left pane, and their corresponding options in the top right pane. The bottom right pane displays the description of the option selected and the facility to change the value of that option.

Prev | Gtk2_PHPConfig | Next
Gtk2_PHPConfig | PEAR Manual | Usage


Usage

Usage

Usage – Using Gtk2_PHPConfig

Using Gtk2_PHPConfig

Simple Configuration GUI

<?php

require_once("Gtk2/PHPConfig.php");

switch ($argc) {
    case 1:
        $test = new Gtk2_PHPConfig(NULL);
        Gtk::main();
        break;
    case 2:
        if (file_exists($argv[1])) {
            echo "\nThe INI File is being parsed... Please be patient...\n";
            $test = new Gtk2_PHPConfig($argv[1]);
            Gtk::main();
            break;
        } else {
            echo "\nThe file does not exist!\n";
        }
    default:
        echo "\nUsage: gtk2_phpconfig [INI File]\n";
        echo "Where [INI File] is an optional argument, and the name of the
        file you want to edit.";
        echo "\nIf no arguments are passed, a new INI file is created\n\n";
        exit();
}

?>

This example is actually the gtk2_phpconfig executable found in /usr/bin (for *nix systems) after installation of the Gtk2_PHPConfig package.

The example script accepts a single optional argument, i.e. the location of the ini file to edit. If not provided, a new file will be created.

Gtk2_PHPConfig extends GtkWindow and can be treated as an application by itself. Hence, the methods used internally are of no significance to the end user. However, you may refer to the API documentation if you are interested in customization or just understanding how the package works.

Prev | Gtk2_PHPConfig | Next
Introduction | PEAR Manual | Gtk2_ScrollingLabel


Gtk2_ScrollingLabel

Gtk2_ScrollingLabel

A class that creates a scrolling marquee.

Table of Contents
  • Introduction -- Getting started with Gtk2_Scrollinglabel
  • Gtk2_ScrollingLabel -- Create a new Scrolling label.
  • Gtk2_ScrollingLabel::getFullText -- Returns the full text of the label.
  • Gtk2_ScrollingLabel::getHiddenText -- Returns all of the text that is not currently visible.
  • Gtk2_ScrollingLabel::getScrollingLabel -- Returns a GtkEventBox with the scrolling label inside.
  • Gtk2_ScrollingLabel::getStyle -- Gets the label's style widget
  • Gtk2_ScrollingLabel::getVisibleLength -- Returns the length of the visible area in characters.
  • Gtk2_ScrollingLabel::pause -- Stops the label from scrolling without reseting the label text
  • Gtk2_ScrollingLabel::setBounce -- Sets the text to bounce between the borders of the label
  • Gtk2_ScrollingLabel::setStartSignal -- Connects the startScroll method to a given event.
  • Gtk2_ScrollingLabel::startScroll -- Begins scrolling the text from the start of the string.
  • Gtk2_ScrollingLabel::unPause -- Begins scrolling the label from its current position
Prev | Gtk2 | Next
Usage | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Getting started with Gtk2_Scrollinglabel

Description

Gtk2_ScrollingLabel is a class that creates a pseudo-widget which makes scrolling text within a label easy. The text within the label can be set to scroll from left to right, right to left, or bounce within the boundries of the label. The speed of the scrolling text can also be controlled. There are also built in methods to make the text pause or stop when the user moves the mouse over the label and start up again when the mouse leaves the label space.

Getting started with Gtk2_ScrollingLabel is easy. All you need to do is instantiate the class, add it to a window, and start the scrolling. Take at look at the example below.

Simple Setup

<?php
// Create a Gtk2_ScrollingLabel instance.
require_once 'Gtk2/ScrollingLabel.php';
$sLabel = new Gtk2_ScrollingLabel('Scrolling Labels Rule!');

// Create a GtkWindow to put the label in.
$gWin = new GtkWindow;
$gWin->connect_simple('destroy', array('Gtk', 'main_quit'));
$gWin->add($sLabel->getWidget());

// Show everything.
$gwin->show_all();

// Start the label and the main loop.
$sLabel->startScroll();
gtk::main();
?>
Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel | PEAR Manual | Gtk2_ScrollingLabel


Gtk2_ScrollingLabel

Gtk2_ScrollingLabel

Gtk2_ScrollingLabel – Create a new Scrolling label.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

void Gtk2_SrollingLabel ( string $text = '' )

Description

Class constructor

Parameter

  • string $text - The text to scroll

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Introduction | PEAR Manual | Gtk2_ScrollingLabel::getFullText


Gtk2_ScrollingLabel::getFullText

Gtk2_ScrollingLabel::getFullText

Gtk2_ScrollingLabel::getFullText – Returns the full text of the label.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

string Gtk2_ScrollingLabel::getFullText ( )

Description

Returns the full text of the label. The full text is the text that was set on construction or with setFullText() not just what is currently visible.

Return value

returns the full text of the label.

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel | PEAR Manual | Gtk2_ScrollingLabel::getHiddenText


Gtk2_ScrollingLabel::getHiddenText

Gtk2_ScrollingLabel::getHiddenText

Gtk2_ScrollingLabel::getHiddenText – Returns all of the text that is not currently visible.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

string Gtk2_ScrollingLabel::getHiddenText ( )

Description

Returns the portion of the full label text that is currently not being shown.

Return value

returns the label text that is not visible.

See

getFullText()

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::getFullText | PEAR Manual | Gtk2_ScrollingLabel::getScrollingLabel


Gtk2_ScrollingLabel::getScrollingLabel

Gtk2_ScrollingLabel::getScrollingLabel

Gtk2_ScrollingLabel::getScrollingLabel – Returns a GtkEventBox with the scrolling label inside.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

void Gtk2_ScrollingLabel::getScrollingLabel ( )

Description

Returns the GtkEventBox that contains the scrolling label.

Return value

returns the GtkEventBox containing the scrolling label.

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::getHiddenText | PEAR Manual | Gtk2_ScrollingLabel::getStyle


Gtk2_ScrollingLabel::getStyle

Gtk2_ScrollingLabel::getStyle

Gtk2_ScrollingLabel::getStyle – Gets the label's style widget

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

&object Gtk2_ScrollingLabel::getStyle ( )

Description

Returns the label's style widget. This lets you make changes to the style to alter the look and feel of the widget. You can change the font of the display, the color of the background, etc.

Return value

returns the GtkStyle widget for the label.

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::getScrollingLabel | PEAR Manual | Gtk2_ScrollingLabel::getVisibleLength


Gtk2_ScrollingLabel::getVisibleLength

Gtk2_ScrollingLabel::getVisibleLength

Gtk2_ScrollingLabel::getVisibleLength – Returns the length of the visible area in characters.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

int Gtk2_ScrollingLabel::getVisibleLength ( )

Description

Returns the length of the visible area in characters. The length of the visible area is the maximum number of characters that are visible at one time.

Return value

integer the maximum number of characters that are visible at one time.

See

setVisibleLength()

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::getStyle | PEAR Manual | Gtk2_ScrollingLabel::pause


Gtk2_ScrollingLabel::pause

Gtk2_ScrollingLabel::pause

Gtk2_ScrollingLabel::pause – Stops the label from scrolling without reseting the label text

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

void Gtk2_ScrollingLabel::pause ( )

Description

Stops the label from scrolling but does not reset the label text to the begining. If you want the label to stop scrolling and return to its original position (blank), use stopScroll().

Return value

returns true if the scrolling has stopped.

See

unPause()

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::getVisibleLength | PEAR Manual | Gtk2_ScrollingLabel::setBounce


Gtk2_ScrollingLabel::setBounce

Gtk2_ScrollingLabel::setBounce

Gtk2_ScrollingLabel::setBounce – Sets the text to bounce between the borders of the label

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

boolean Gtk2_ScrollingLabel::setBounce ( boolean $bounce )

Description

If $bounce is true, the text will scroll to the left until the first character hits the left edge of the visible window then it will scroll back to the right. When the last character hits the right edge of the visible window the text will scroll back to the left again.

If all of the scrolling text cannot be viewed at once, making the text bounce will have an undesired result. Therefore it is suggested that the length of the text always be at least one character less than the maximum viewable string length.

Parameter

  • boolean $bounce - Whether or not the text should change direction when it hits a label edge.

Return value

returns Whether or not the text is set to bounce

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::pause | PEAR Manual | Gtk2_ScrollingLabel::setStartSignal


Gtk2_ScrollingLabel::setStartSignal

Gtk2_ScrollingLabel::setStartSignal

Gtk2_ScrollingLabel::setStartSignal – Connects the startScroll() method to a given event.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

void Gtk2_ScrollingLabel::setStartSignal ( string $signal )

Description

setStartSignal() will make the event box listen for the signal $signal and will envoke startScroll() when ever it is heard. The signal should be a signal that GtkEventBox listens for normally or a button press event.

Parameter

  • string $signal - The Gtk signal to connect to startScroll().

Return value

returns The handler id for the connection.

See

startScroll()

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::setBounce | PEAR Manual | Gtk2_ScrollingLabel::startScroll


Gtk2_ScrollingLabel::startScroll

Gtk2_ScrollingLabel::startScroll

Gtk2_ScrollingLabel::startScroll – Begins scrolling the text from the start of the string.

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

boolean Gtk2_ScrollingLabel::startScroll ( )

Description

startScroll() will make the text begin scrolling in the direction given by calling setDirection(). If the text is scrolling left to right (GTK2_SCROLLINGLABEL_RIGHT), the current character position is set to the end of the text. This means that the last character of the label will be the first character shown. If the text is scrolling right to left (GTK2_SCROLLINGLABEL_LEFT), the current character position is set to zero. This means that first character shown will be a blank space.

This method is best used when connected to an event.

Return value

returns true if the text has started scrolling. false otherwise.

See

setStartSignal()

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::setStartSignal | PEAR Manual | Gtk2_ScrollingLabel::unPause


Gtk2_ScrollingLabel::unPause

Gtk2_ScrollingLabel::unPause

Gtk2_ScrollingLabel::unPause – Begins scrolling the label from its current position

Synopsis

require_once 'Gtk2/ScrollingLabel.php';

void Gtk2_ScrollingLabel::unPause ( )

Description

Begins scrolling the label from its current position. unPause() is different from startScroll() in that it does not reset the label to the begining of the text.

Return value

returns true if the text has started scrolling.

See

pause()

startScroll()

Note

This function can not be called statically.

Prev | Gtk2_ScrollingLabel | Next
Gtk2_ScrollingLabel::startScroll | PEAR Manual | Gtk2_VarDump


Gtk2_VarDump

Gtk2_VarDump

Provides a simple GUI to examine PHP variables, for example complex arrays or objects.

Table of Contents
  • Introduction -- About Gtk2_VarDump
  • Re-using Gtk2_VarDump -- Embedding it in own applications
Prev | Gtk2 | Next
Gtk2_ScrollingLabel::unPause | PEAR Manual | Introduction


Introduction

Introduction

Introduction – About Gtk2_VarDump

About Gtk2_VarDump

Gtk2_VarDump is a simple GUI to examine PHP variables, for example complex arrays or objects. It displays the variable and all sub-variables/array keys/sub-objects in the left pane (a GtkTreeView), and the actual values in a list view on the right side.

The class is very easy to use: Just include the file, and call the static display method with the variable you want to have dumped.

Showing a variable with Gtk2_VarDump

<?php
//include the file
require_once 'Gtk2/VarDump.php';

$myvar = array(
    'hello', 2 => 'world',
    array(1, 2, 3, 'blubb')
);

//graphically dump the variable in an own window
Gtk2_VarDump::display($myvar, 'variable title');
?>
Prev | Gtk2_VarDump | Next
Gtk2_VarDump | PEAR Manual | Re-using Gtk2_VarDump


Re-using Gtk2_VarDump

Re-using Gtk2_VarDump

Re-using Gtk2_VarDump – Embedding it in own applications

Re-using Gtk2_VarDump

Gtk2_VarDump consists of two main parts: A tree on the left, displaying the structure of the variable-to-dump, and a list on the right side, showing the keys and their values. They are arranged on a pane, which itself is contained in the main window.

Now you might want to dump some variables yourself, but integrate this display directly into your own application - without opening a new window for that. Gtk2_VarDump is prepared for that; you can re-use the existing classes.

Gtk2_VarDump_Pane

Gtk2_VarDump_Pane is the container for both tree and list. You can use instantiate it, add it to your interface and call the setVariable() method to display the contents of the variable. The method takes the variable as first parameter, and a user-definable title as optional second parameter.

Gtk2_VarDump_Tree

Gtk2_VarDump_Tree is an descendant of GtkTreeView, and as usual without any scrollbars. Remember to add it to a GtkScrolledWindow. The class has, as Gtk2_VarDump_Pane does, a setVariable() method that takes the variable to be displayed and an optional title that is used for the root element.

The tree has another method: setList() is used to set the list widget that shall display the values. Be sure that the list widget also provides a setVariable() method. Whenever the selection in the tree changes, the list's setVariable() method is called.

Gtk2_VarDump_List

Gtk2_VarDump_List is a descendant of GtkTreeView and simply displays plain key-value pairs. It has, like the other two classes, a setVariable() method that takes the variable to display as first parameter, and an optional title as second parameter.

Prev | Gtk2_VarDump | Next
Introduction | PEAR Manual | HTML


HTML

HTML

Provides packages for working and creating HTML

Table of Contents
  • HTML_Crypt
  • HTML_CSS
  • HTML_Form
  • HTML_Menu
  • HTML_Page2
  • HTML_Progress
  • HTML_Progress2
  • HTML_QuickForm
  • HTML_QuickForm_Controller
  • HTML_QuickForm_Renderer_Tableless
  • HTML_QuickForm_DHTMLRulesTableless
  • HTML_QuickForm_advmultiselect
  • HTML_Table
  • HTML_TagCloud
  • HTML_Template_Flexy
  • HTML_Template_IT
  • HTML_Template_PHPLIB
  • HTML_Template_Sigma
  • HTML_Template_Xipe
  • HTML_TreeMenu
  • Pager
  • Pager_Sliding
Prev | PEAR Packages | Next
Re-using Gtk2_VarDump | PEAR Manual | HTML_Crypt


HTML_Crypt

HTML_Crypt

The HTML_Crypt provides methods to encrypt text, which can be later be decrypted using JavaScript on the client side.

This is very useful to prevent spam robots collecting email addresses from your site, included is a method to add mailto links to the text being generated.

A basic example to encrypt an email address

<?php
// encrypt 'yourname@emailaddress.com'
// with offset 8
$c = new HTML_Crypt('yourname@emailaddress.com', 8);

// add <a href="mailto:"></a> around this email
$c->addMailTo();

// output the javascript which writes the decrypted email.
$c->output();
?>

The "encryption" function is basically works like ROT13, with the difference that the $offset setting replaces the 13. It is also limited to ASCII characters between 32 and 127 (included). Other characters will not be encrypted.

If you don't want to output the generated javascript directly to the browser but use it otherwise or replace a template variable, use getOutput() instead of output() - the first returns the generated javascript, the latter echoes it out.

Prev | HTML | Next
HTML | PEAR Manual | HTML_CSS


HTML_CSS

HTML_CSS

Provides a simple interface for validate, handle and generate cascading style sheets.

Table of Contents
  • Summary
  • Getting started
  • Reference guide
Prev | HTML | Next
HTML_Crypt | PEAR Manual | Summary


Summary

Summary

Table of Contents
  • Why use HTML_CSS ?
  • Features
  • System Requirements
  • About
Prev | HTML_CSS | Next
HTML_CSS | PEAR Manual | Why use HTML_CSS ?


Why use HTML_CSS ?

Why use HTML_CSS ?

Even if a CSS file is easy to modify (text format), there is no PHP interface that provides such degree of handling style sheet declarations. Create from scratch or parsing single or multi data sources begin really so easy with HTML_CSS.

Prev | Summary | Next
Summary | PEAR Manual | Features


Features

Features

  • parse css string.

  • parse css file.

  • parse multiple css data sources at once.

  • output to inline stylesheet declarations.

  • output to document internal stylesheet declarations.

  • output to standalone stylesheet declarations.

  • output to Array of definitions.

  • output to string.

  • output to file.

  • search for selectors and/or properties using Perl-compatible pattern.

  • check validity of CSS data source.

  • support of At Rules.

Prev | Summary | Next
Why use HTML_CSS ? | PEAR Manual | System Requirements


System Requirements

System Requirements

Mandatory resources :

  • PHP 4.3.0 or newer.

  • PEAR 1.5.4 or newer.

  • PEAR::HTML_Common 1.2.4 or newer.

  • pcre extension.

Optional resources :

  • PHP 5.0.0 or newer.

  • PEAR::Services_W3C_CSSValidator 0.1.0 or newer.

  • PHPUnit 3.2.0 or newer.

Prev | Summary | Next
Features | PEAR Manual | About


About

About

Table of Contents
  • FAQ -- Answers to most Frequently Asked Questions
  • News -- What is New in version ?
Prev | Summary | Next
System Requirements | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

HTML_CSS FAQ

    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 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.

    What is CSS ?

    CSS (an acronym for Cascading Style Sheets) is a simple mechanism for adding style (e.g. fonts, colors, spacing) to Web documents.

    HTML_CSS is a PEAR package that provides methods for handling stylesheet declarations.

    Version 1.0.0 does not offers yet methods to validate a style sheet.

    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 want to use HTML_CSS without PEAR. Is it possible ?

    Yes it is. First, you need to download package PEAR::HTML_Common version 1.2 or greater.

    Extract content (Common.php file) in same directory HTML/ as CSS.php file.

    Last, you should create your own error handler, or disable it. See chapter Error Handler for details.

    I want to know property value of a selector, but it can not exist

    With previous release than 1.1.0 it was not possible because HTML_CSS::getStyle() require at least an existing property, or it will return HTML_CSS_ERROR_NO_ELEMENT_PROPERTY.

    With new function HTML_CSS::grepStyle() of version 1.1.0, it's now possible.

    01: <?php
    02    : require_once 'HTML/CSS.php';
    03:
    04: function myErrorHandler()
    05: {
    06:     return PEAR_ERROR_PRINT;  // always print all error messages
    07: }
    08:
    09: $styles = '
    10: h1, h2, h3, h4 { padding: 1em; }
    11: .highlight p, .highlight ul { margin-left: .5em; }
    12: #main p, #main ul { padding-top: 1em; }
    13: '    ;
    14:
    15: $prefs = array(
    16:     'push_callback' => 'myErrorHandler',
    17: );
    18: $attribs = null;
    19:
    20: $css = new HTML_CSS($attribs, $prefs);
    21: $css->parseString($styles);
    22:
    23: $css->getStyle('.highlight p', 'color');
    24:
    25: $styles = $css->grepStyle('/highlight/', '/^color$/');
    26: echo '<pre>'; var_dump($styles); echo '</pre>';
    27: ?>
    Lines 4-7, 15-17, 20 :

    Custom error handler is defined to allow script to continue (print message), when HTML_CSS::getStyle() will raise error at line 23.

    Lines 9-13, 21 :

    Stylesheet used is :

    h1, h2, h3, h4 { padding: 1em; }
.highlight p, .highlight ul { margin-left: .5em; }
#main p, #main ul { padding-top: 1em; }
    Lines 23, 25 :

    While HTML_CSS::getStyle() will raise error (printed by custom error handler), line 25 will return an empty array with no error raised.

    Reason : color property does not exist for .highlight p class selector.

    Prev | About | Next
About | PEAR Manual | News


News

News

News – What is New in version ?

Version 0.2.x

  • Initial PEAR public release occured at end of July 2003.

Version 0.3.x

  • Added the ability to parse CSS from string with HTML_CSS::parseString()

  • Added the ability to parse CSS from file with HTML_CSS::parseFile()

  • Added the ability to generate CSS and store it in a file with HTML_CSS::toFile()

  • Introduced error handling system with PEAR_ErrorStack.

  • Added unit tests with PHPUnit 1.x for API and bugs.

  • Retrieve the settings of individual properties

Version 1.0.x

  • Introduced a new error handling system: PEAR_ErrorStack was replaced by a simple way to plug in any error handling system you might want (default used PEAR_Error object)

  • HTML_CSS::apiVersion() returns now a string rather than a float; compatible with php.version_compare().

  • Added the ability to parse multiple data sources (filename, string) at once with HTML_CSS::parseData()

  • Added the ability to identify if HTML_CSS API output returns an error with HTML_CSS::isError()

  • Introduces package xml 2.0 and drop support of package xml 1.0

  • Unified API arguments for all group functions

  • Klaus Guenther (first package leader) became inactive.

Version 1.1.x

  • Added ability to search if an element/property is defined or not with HTML_CSS::grepStyle()

Version 1.2.x

  • License changed from PHP 3.01 to BSD.

  • Manual license upgrades from version 2.0 to 3.0 of Creative Commons

Version 1.3.x

  • Prevent invalid CSS data source in to be parse

  • Add Content-Disposition to the headers in display() Implement request 12195

  • Remove pointless NEWS file from distribution, clone of ChangeLog.

Version 1.4.x

  • Upgrade requirement to PHP 4.3.0 and PEAR 1.5.4 (to avoid security vulnerability)

  • Coding Standard fixes: (errors/warnings) following recommandation by PHP_CodeSniffer

  • Unit test suites migrated from PHPUnit 1.x to 3.x

  • API 1.4.0 introduces new setter/getter PHP5 facility compatible (magic function __set, __get) for read/write CSS options.

  • Error handler allow now to use PEAR_ERROR_CALLBACK (local to HTML_CSS) to customize action when an error/exception is raised. No more need to use global PEAR::setErrorHandling.

Version 1.5.x

  • Check validity of CSS data source to be parse using the W3C CSS validator service with help of package PEAR::Services_W3C_CSSValidator (require PHP5)

  • Ability to retrieve all options in effect at once with HTML_CSS::getOptions()

  • Add support of At-Rules Implement request 12194

  • Improve support of At-Rules. See bugs

    • 16354 Does not parse multiple simple At-rules properly

    • 16355 Simple at rules nested within other at rules are reported as top level at rules

    • 16357 Multiple equal complex at rules not parsed correctly

    • 16358 Multiple media types on media at rule not parsed correctly

    • 16359 Multiple selectors on a single rule inside a complex at rule not properly parsed

    • 16360 Multiple selectors inside a complex at rule not properly parsed

    HTML_CSS::createAtRule() signature changed. Add optional duplicates parameter to allow to handle two or more instance of a same @charset or @import or @namespace At-Rule. See HTML_CSS_TestSuite_Standard::testCreateAtRuleWithManyDefinitions for example.

Prev | About | Next
FAQ | PEAR Manual | Getting started


Getting started

Getting started

Table of Contents
  • Overview -- features and usage patterns
  • Grouping selectors -- how to handle multiple selector at once
  • Parsing data sources -- load existing style sheet from different data sources
  • Output -- getting results in different format
  • Find definitions -- searching for selectors and properties
Prev | HTML_CSS | Next
News | PEAR Manual | Overview


Overview

Overview

Overview – features and usage patterns

In brief

The purpose of this tutorial is to give the new users of HTML_CSS an overview of its features and usage patterns. It describes a small subset of available functionality, but points to the parts of the documentation that give a more in-depth overview.

Selectors are one of the most important aspects of CSS as they are used to "select" elements on an HTML page so that they can be styled. We will try to explain basic concepts, and how to do the same with HTML_CSS.

A complete tutorial about CSS selectors can be find at maxDesign .

Basic concepts

What is a rule or "rule set" ?

A rule or "rule set" is a statement that tells browsers how to render particular elements on an HTML page. A rule set consists of a selector followed by a declaration block.

Rule set structure

Rule structure

Definition of a rule set structure

Declaration block

The HTML_CSS::setStyle() method is the only one to handle a declaration block.

For example, to declare a such rule :

p { padding: 5px; }

Here is the php code to create the same sentence with HTML_CSS :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$css->setStyle('p', 'padding', '5px');

$css->display();
?>

Grouping declarations

You can use more than one declaration within a declaration block. Each declaration must be separated with a semicolon ";".

For example, to declare a such rule :

p { padding: 5px; margin: 1px; }

Or, with whitespace added to aid readability :

p {
  padding: 5px;
  margin: 1px;
}

Here is the php code to create the same sentence with HTML_CSS :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$css->setStyle('p', 'padding', '5px');
$css->setStyle('p', 'margin', '1px');

$css->display();
?>

Notice that we use twice HTML_CSS::setStyle() method call to declare each declaration block for the same selector.

Grouping selectors

When several selectors share the same declarations, they may be grouped together to save writing the same rule more than once. Each selector must be separated by a comma. For example :

h1, h2, h3, h4 { padding: 1em; }
.highlight p, .highlight ul { margin-left: .5em; }
#main p, #main ul { padding-top: 1em; }

To produce such result, we will need help of 3 new methods :
HTML_CSS::setSameStyle(),
HTML_CSS::createGroup() and
HTML_CSS::setGroupStyle().

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

// two selector groups only
$css->setStyle('.highlight p', 'margin-left', '.5em');
$css->setSameStyle('.highlight ul', '.highlight p');

// or even this way
$g2 = $css->createGroup('#main p, #main ul');
$css->setGroupStyle($g2, 'padding-top', '2em');

// more than two selector groups
$g1 = $css->createGroup('h1, h2, h3, h4');
$css->setGroupStyle($g1, 'padding', '1em');

$css->display();
?>

We should take care than grouping two selectors may be write either with HTML_CSS::setSameStyle() or with couple HTML_CSS::createGroup() and HTML_CSS::setGroupStyle(). When we have to group three or more selectors, there is only one possibility: couple HTML_CSS::createGroup() and HTML_CSS::setGroupStyle().

CSS comments

You can insert comments in CSS to explain your code. Like HTML comments, CSS comments will be ignored by the browser. A CSS comment begins with "/*", and ends with "*/". Comments can appear before or within rule sets as well as across multiple lines.

HTML_CSS 1.0.0 has not yet ability to handle comment such as :

/* Comment here */
p
{
margin: 1em; /* Comment here */
padding: 2em;
/* color: white; */
background-color: blue;
}

/*
multi-line
comment here
*/

The common mistake that people make when writing comments is to expect getting all comments describe with such code below : it's an error.

<?php
$css->setComment('comment here');

$css->setStyle('p', 'margin', '1em');
$css->setStyle('p', 'padding', '2em');
$css->setComment('color: white;');
$css->setStyle('p', 'background-color', 'blue');

$css->setComment('
multi-line
comment here
');
?>

You will only get such result:

/*
multi-line
comment here
 */

p {
  margin: 1em;
  padding: 2em;
  background-color: blue;
}

Only one comment is allowed due to usage of parent class method HTML_Common::setComment().

Prev | Getting started | Next
Getting started | PEAR Manual | Grouping selectors


Grouping selectors

Grouping selectors

Grouping selectors – how to handle multiple selector at once

In brief

Remember, when several selectors share the same declarations, they may be grouped together to save writing the same rule more than once. Each selector must be separated by a comma.

Two cases exists to handle group of selector. The quick and limited solution
(accept only two selectors in a same group) with :
HTML_CSS::setSameStyle().
And the extended/common solution with :
HTML_CSS::createGroup(),
HTML_CSS::setGroupStyle(),
HTML_CSS::addGroupSelector() and
HTML_CSS::removeGroupSelector().

Create group

HTML_CSS::createGroup() creates basically a group for selectors given as first argument. You can identify this group by an identifier (alphanumeric) or let HTML_CSS manage an internal numeric identifier itself.

Let creates this group of selectors :

#main p, #main ul { padding-top: 1em; color: red; }

Identify the group yourself

Identifier is named myGroupID in this example:

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$g1 = $css->createGroup('#main p, #main ul', 'myGroupID');
$css->setGroupStyle($g1, 'padding-top', '1em');
$css->setGroupStyle($g1, 'color', 'red');

$css->display();
?>

Let HTML_CSS do it itself

Note: This is the default behavior.

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$g1 = $css->createGroup('#main p, #main ul');
$css->setGroupStyle($g1, 'padding-top', '1em');
$css->setGroupStyle($g1, 'color', 'red');

$css->display();
?>

Handle group selector

With HTML_CSS::addGroupSelector() and HTML_CSS::removeGroupSelector(), we have ability to add or remove one selector from a selectors list (of a group).

Suppose we have these selectors :

html, body { margin: 2px; padding: 0; border: 0; }

and we want to apply same share properties to new class 'large' and do not anymore apply it to 'body'.

Here are how to do :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

// 1. create the pre-requires data
$g1 = $css->createGroup('html, body');
$css->setGroupStyle($g1, 'margin', '2px');
$css->setGroupStyle($g1, 'padding', '0');
$css->setGroupStyle($g1, 'border', '0');

// 2. remove the body selector
$css->removeGroupSelector(1, 'body');

// 3. add the new 'large' class
$css->addGroupSelector(1, '.large');

$css->display();
?>

Note: Remember that HTML_CSS handle group (numeric) identifier itself (begin at 1, and go to 2, 3, and more).
Prev | Getting started | Next
Overview | PEAR Manual | Parsing data sources


Parsing data sources

Parsing data sources

Parsing data sources – load existing style sheet from different data sources

In brief

One of the great features of HTML_CSS is to parse and load existing style sheet from different data sources : (simple string, css file, combine). We will see in detail all these possibilities with 3 methods : HTML_CSS::parseString(), HTML_CSS::parseFile() and HTML_CSS::parseData().

Parse a simple string

A quick way to create multiple selector definitions in one step is to use the HTML_CSS::parseString() function.

Let creates these definitions :

html, body {
  margin: 2px;
  padding: 0px;
  border: 0px;
}

p, body {
  margin: 4px;
}

Very easy with such script :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$strcss = '
html, body {
  margin: 2px;
  padding: 0px;
  border: 0px;
}

p, body {
  margin: 4px;
}
';
$css->parseString($strcss);

$css->display();
?>

Parse a file contents

Another quick way to create multiple selector definitions in one step is to use the HTML_CSS::parseFile() function. CSS file to load is supposed to be W3C/CSS compliant.

If previous selector definitions was into a file named 'styles.css', then to parse and load contents will be done with such script :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();
$css->parseFile('styles.css');
$css->display();
?>

Tip

If there are duplicate definitions into file contents, you should parse file with call :

<?php
$css->parseFile('styles.css', true);
?>

We will see next why we may find such duplicate definitions.

Parse multi data sources

We have already seen two single sources where CSS data could come from. The last one allow to parse data from multiple sources at once. HTML_CSS::parseData() function take an array as first argument. Each item is either a filename (with .css extension) or a string. Each source is merge to produce at end a unique style sheet.

In script below we load selector definitions from two independent sources: a string and a css file which contents duplicate definitions (parseFile() 2nd argument to set to true to catch this situation; see next section for explains). Internet Explorer).

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

// 1. a string to parse
$strcss = '
body, p { background-color: white; font: 1.2em Arial; }
p, div#black { color: black; }
div{ color: green; }
p { margin-left: 3em; }
';
$css->parseString($strcss);

// 2. a css file with duplicate definitions
$css->parseFile('iehack.css', true);

$css->display();
?>

Allow duplicate definitions

Internet Explorer <= 6 does not handle box model in same way as others browsers that are better W3C compliant. For this reason, we need to fix boxes size with a hack such as this one you can find in example that follow. You can notice the duplicate 'voice-family' and 'height' properties.

To parse these definitions we need to activate the duplicate option of HTML_CSS.

#header {
  background-color: ivory;
  font-family: "Times New Roman", Times, serif;
  font-size: 5mm;
  text-align: center;
  /* IE 5.5 */
  height:81px;
  border-top:1px solid #000;
  border-right:1px solid #000;
  border-left:1px solid #000;
  voice-family: "\"}\"";
  voice-family: inherit;
  /* IE 6 */
  height: 99px;
}

There are two ways :

  • global to all functions: set option allowduplicates on class constructor

  • local to a function: set argument duplicates to TRUE

For example here, we could wrote either (allow global duplicate) :

<?php
require_once 'HTML/CSS.php';

$attr = array('allowduplicates' => true);
$css = new HTML_CSS($attr);

$strcss = '
#header {
  background-color: ivory;
  font-family: "Times New Roman", Times, serif;
  font-size: 5mm;
  text-align: center;
  /* IE 5.5 */
  height:81px;
  border-top:1px solid #000;
  border-right:1px solid #000;
  border-left:1px solid #000;
  voice-family: "\"}\"";
  voice-family: inherit;
  /* IE 6 */
  height: 99px;
}
';
$css->parseString($strcss);

$css->display();
?>

or also (duplicate on local call) :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$strcss = '
#header {
  background-color: ivory;
  font-family: "Times New Roman", Times, serif;
  font-size: 5mm;
  text-align: center;
  /* IE 5.5 */
  height:81px;
  border-top:1px solid #000;
  border-right:1px solid #000;
  border-left:1px solid #000;
  voice-family: "\"}\"";
  voice-family: inherit;
  /* IE 6 */
  height: 99px;
}
';
$css->parseString($strcss, true);

$css->display();
?>
Prev | Getting started | Next
Grouping selectors | PEAR Manual | Output


Output

Output

Output – getting results in different format

In brief

Handle selectors, groups, properties are some basic features of HTML_CSS but
getting results in different format should be the final step of your process.
We have four/five different functions (depending or render you want to get) :
HTML_CSS::toArray(),
HTML_CSS::toInline(),
HTML_CSS::toFile(),
HTML_CSS::toString() and
HTML_CSS::display().

To Array

HTML_CSS::toArray() must be considered as a debug/help function. An easy way to explore HTML_CSS data structures.

For example, explore these definitions :

html, body {
  margin: 2px;
  padding: 0px;
  border: 0px;
}

p, body {
  margin: 4px;
}

div#header { text-align: center; color: red; }

With script :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$strcss = '
html, body {
  margin: 2px;
  padding: 0px;
  border: 0px;
}

p, body {
  margin: 4px;
}

div#header { text-align: center; color: red; }
';
$css->parseString($strcss);

$arr = $css->toArray();
var_export($arr);
?>

To Inline

HTML_CSS::toInline() allow to integrate html tags with styles.

Dissociate html code and presentation layout (CSS) is more than recommanded

Here is a basic example that show a white 'Hello World' on a black background :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$css->setStyle('body', 'background-color', '#0c0c0c');
$css->setStyle('body', 'color', '#ffffff');

echo '<body style="' . $css->toInline('body') . '">';
echo '<p>Hello World</p>';
echo '</body>';
?>

To File

HTML_CSS::toFile() is probably the most interresting solution. You can create a pure CSS file on the fly.

If file already exists, it will be replace without warning !

This script will load an existing style sheet and replace the body definition :

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$css->parseFile('example.css');

$css->setStyle('body', 'background-color', '#0c0c0c');
$css->setStyle('body', 'color', '#ffffff');

$css->toFile('example.css');
?>

To String

HTML_CSS::toString() is analogous to HTML_CSS::toFile() except that result is capture to a PHP variable rather than to a text/css file.

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$strcss = '
ul, body {
  padding: 1em 2em;
}
';
$css->parseString($strcss);
$css->setGroupStyle(1, 'color', 'red');

$str = $css->toString();
echo $str;
// will display
// ul, body { padding: 1em 2em; color: red; }
?>

Display

HTML_CSS::display() is no more no less than just a

<?php
echo $css->toString();
?>

with cache and charset management for browser output.

See also : HTML_CSS::setCharset() and HTML_CSS::setCache() functions.

Prev | Getting started | Next
Parsing data sources | PEAR Manual | Find definitions


Find definitions

Find definitions

Find definitions – searching for selectors and properties

In brief

One of features of HTML_CSS that was still missing to version less or equal than 1.0.1 is ability to detect if a selector (or group of selectors), and/or a property (or group of properties) was already defined. This is now possible with method : HTML_CSS::grepStyle()

Searching for a group of selectors

Let creates these definitions into progress2.css file :

#PB1.cellPB1I, #PB1.cellPB1A {
  width: 15px;
  height: 20px;
  font-family: Courier, Verdana;
  font-size: 8px;
  float: left;
}

#PB1.progressBorderPB1 {
  width: 172px;
  height: 24px;
  border-width: 1px;
  border-style: solid;
  border-color: #404040 #dfdfdf #dfdfdf #404040;
  background-color: #CCCCCC;
}

.progressPercentLabelpct1PB1 {
  width: 50px;
  text-align: right;
  background-color: transparent;
  font-size: 11px;
  font-family: Verdana, Tahoma, Arial;
  font-weight: normal;
  color: #000000;
}

.progressTextLabeltxt1PB1 {
  text-align: left;
  background-color: transparent;
  font-size: 11px;
  font-family: Verdana, Tahoma, Arial;
  font-weight: normal;
  color: #000000;
}

.cellPB1I {
  background-color: #CCCCCC;
}

.cellPB1A {
  background-color: #0033FF;
}

body {
    background-color: #E0E0E0;
    color: #000000;
    font-family: Verdana, Arial;
}

Very easy with such script to find where is declared #PB1 class selectors (names like).

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();
$css->parseFile('progress2.css');

// find all selectors beginning with #PB1
$styles = $css->grepStyle('/^#PB1/');
echo '<pre>'; var_dump($styles); echo '</pre>';
?>

Searching for selectors that set a property

We still used the CSS definitions of previous example, identified by progress2.css file :

Very easy with such script to find where is declared color property.

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();
$css->parseFile('progress2.css');

// find all selectors that set the color property
$styles = $css->grepStyle('/./', '/^color$/');
echo '<pre>'; var_dump($styles); echo '</pre>';
?>
Prev | Getting started | Next
Output | PEAR Manual | Reference guide


Reference guide

Reference guide

Table of Contents
  • Handling options
  • Handle selector and property values
  • Grouping selectors
  • Parsing data sources
  • Checking data sources
  • Output
  • Searching for selectors and/or properties
  • Handling At-Rules
  • Handling error
Prev | HTML_CSS | Next
Find definitions | PEAR Manual | Handling options


Handling options

Handling options

Table of Contents
  • HTML_CSS::__get -- Get option for the class
  • HTML_CSS::__set -- Set option for the class
  • HTML_CSS::getCharset -- Return the charset encoding string
  • HTML_CSS::getContentDisposition -- Return the Content-Disposition header
  • HTML_CSS::getOptions -- Return all options for the class
  • HTML_CSS::setCache -- Set cache flag
  • HTML_CSS::setCharset -- Set charset value
  • HTML_CSS::setContentDisposition -- Set Content-Disposition header
  • HTML_CSS::setLineEnd -- Set lineend value
  • HTML_CSS::setOutputGroupsFirst -- Set groupsfirst flag
  • HTML_CSS::setSingleLineOutput -- Set oneline flag
  • HTML_CSS::setTab -- Set tab value
  • HTML_CSS::setXhtmlCompliance -- Set xhtml flag
Prev | Reference guide | Next
Reference guide | PEAR Manual | HTML_CSS::__get


HTML_CSS::__get

HTML_CSS::__get

HTML_CSS::__get() – Get option for the class

Synopsis

require_once 'HTML/CSS.php';

mixed HTML_CSS::__get ( string $option )

Description

Return current value of an individual option. If option does not exist, returns value is NULL.

Parameter

string $option

Name of option to set

Throws

throws no exceptions thrown

Since

since version 1.4.0 (2007-12-13)

Note

This function can not be called statically.

Prev | Handling options | Next
Handling options | PEAR Manual | HTML_CSS::__set


HTML_CSS::__set

HTML_CSS::__set

HTML_CSS::__set() – Set option for the class

Synopsis

require_once 'HTML/CSS.php';

void HTML_CSS::__set ( string $option , string $val )

Description

Set an individual option value. Option must exist.

Parameter

string $option

Name of option to set

string $val

Value of option to set

Throws

throws no exceptions thrown

Since

since version 1.4.0 (2007-12-13)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::__get | PEAR Manual | HTML_CSS::getCharset


HTML_CSS::getCharset

HTML_CSS::getCharset

HTML_CSS::getCharset() – Return the charset encoding string

Synopsis

require_once 'HTML/CSS.php';

string HTML_CSS::getCharset ( )

Description

By default, HTML_CSS uses iso-8859-1 encoding.

Throws

throws no exceptions thrown

See

see HTML_CSS::setCharset()

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::__set | PEAR Manual | HTML_CSS::getContentDisposition


HTML_CSS::getContentDisposition

HTML_CSS::getContentDisposition

HTML_CSS::getContentDisposition() – Return the Content-Disposition header

Synopsis

require_once 'HTML/CSS.php';

mixed HTML_CSS::getContentDisposition ( )

Description

Get value of Content-Disposition header (inline filename) used to display results

Throws

throws no exceptions thrown

Since

since version 1.3.0 (2007-10-22)

Note

This function can not be called statically.

Return value

returns boolean FALSE if no content disposition, otherwise string for inline filename

See

see HTML_CSS::setContentDisposition()

Prev | Handling options | Next
HTML_CSS::getCharset | PEAR Manual | HTML_CSS::getOptions


HTML_CSS::getOptions

HTML_CSS::getOptions

HTML_CSS::getOptions() – Return all options for the class

Synopsis

require_once 'HTML/CSS.php';

array HTML_CSS::getOptions ( )

Description

Return all configuration options at once

Throws

throws no exceptions thrown

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::getContentDisposition | PEAR Manual | HTML_CSS::setCache


HTML_CSS::setCache

HTML_CSS::setCache

HTML_CSS::setCache() – Set cache flag

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setCache ( bool $cache = true )

Description

Define if the document should be cached by the browser. Default to false.

Parameter

boolean $cache

(optional)

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::getOptions | PEAR Manual | HTML_CSS::setCharset


HTML_CSS::setCharset

HTML_CSS::setCharset

HTML_CSS::setCharset() – Set charset value

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setCharset ( string $type = 'iso-8859-1' )

Description

Define the charset for the file. Default to ISO-8859-1 because of CSS1 compatability issue for older browsers.

Parameter

string $type

(optional) Charset encoding; defaults to ISO-8859-1.

See

see HTML_CSS::getCharset()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setCache | PEAR Manual | HTML_CSS::setContentDisposition


HTML_CSS::setContentDisposition

HTML_CSS::setContentDisposition

HTML_CSS::setContentDisposition() – Set Content-Disposition header

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setContentDisposition ( boolean $enable = true , string $filename = '' )

Description

Defines the Content-Disposition filename for the browser output. Defaults to basename($_SERVER['PHP_SELF']).'.css'

Parameter

boolean $enable

(optional)

string $filename

(optional)

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 1.3.0 (2007-10-22)

See

see HTML_CSS::getContentDisposition()

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setCharset | PEAR Manual | HTML_CSS::setLineEnd


HTML_CSS::setLineEnd

HTML_CSS::setLineEnd

HTML_CSS::setLineEnd() – Set lineend value

Synopsis

require_once 'HTML/CSS.php';

void HTML_CSS::setLineEnd ( string $style )

Description

Set the line end style to Windows, Mac, Unix or a custom string

Parameter

string $style

"win", "mac", "unix" or custom string.

Throws

throws no exceptions thrown

Since

since version 1.4.0 (2007-12-13)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setContentDisposition | PEAR Manual | HTML_CSS::setOutputGroupsFirst


HTML_CSS::setOutputGroupsFirst

HTML_CSS::setOutputGroupsFirst

HTML_CSS::setOutputGroupsFirst() – Set groupsfirst flag

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setOutputGroupsFirst ( bool $value )

Description

Determine whether groups are output before elements or not

Parameter

boolean $value

flag to true if groups are output before elements, false otherwise

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.3.3 (2004-05-20)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setLineEnd | PEAR Manual | HTML_CSS::setSingleLineOutput


HTML_CSS::setSingleLineOutput

HTML_CSS::setSingleLineOutput

HTML_CSS::setSingleLineOutput() – Set oneline flag

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setSingleLineOutput ( bool $value )

Description

Determine whether definitions are output on a single line or multi lines

Parameter

boolean $value

flag to true if single line, false for multi lines

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.3.3 (2004-05-20)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setOutputGroupsFirst | PEAR Manual | HTML_CSS::setTab


HTML_CSS::setTab

HTML_CSS::setTab

HTML_CSS::setTab() – Set tab value

Synopsis

require_once 'HTML/CSS.php';

void HTML_CSS::setTab ( string $string )

Description

Sets the string used to indent HTML

Parameter

string $string

String used to indent ("\11", "\t", ' ', etc.).

Throws

throws no exceptions thrown

Since

since version 1.4.0 (2007-12-13)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setSingleLineOutput | PEAR Manual | HTML_CSS::setXhtmlCompliance


HTML_CSS::setXhtmlCompliance

HTML_CSS::setXhtmlCompliance

HTML_CSS::setXhtmlCompliance() – Set xhtml flag

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setXhtmlCompliance ( bool $value )

Description

Active or not the XHTML mode compliant

Parameter

boolean $value

flag to true if XHTML compliance needed, false otherwise

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.3.2 (2004-03-24)

Note

This function can not be called statically.

Prev | Handling options | Next
HTML_CSS::setTab | PEAR Manual | Handle selector and property values


Handle selector and property values

Handle selector and property values

Table of Contents
  • HTML_CSS::getStyle -- Return the value of a CSS property
  • HTML_CSS::setStyle -- Set or add a CSS definition
Prev | Reference guide | Next
HTML_CSS::setXhtmlCompliance | PEAR Manual | HTML_CSS::getStyle


HTML_CSS::getStyle

HTML_CSS::getStyle

HTML_CSS::getStyle() – Return the value of a CSS property

Synopsis

require_once 'HTML/CSS.php';

mixed|PEAR_Error HTML_CSS::getStyle ( string $element , string $property )

Description

Get the value of a property to an identifed simple CSS element

Parameter

string $element

Element (or class) to be defined

string $property

Property defined

See

see HTML_CSS::setStyle()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_ELEMENT, HTML_CSS_ERROR_NO_ELEMENT_PROPERTY

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Handle selector and property values | Next
Handle selector and property values | PEAR Manual | HTML_CSS::setStyle


HTML_CSS::setStyle

HTML_CSS::setStyle

HTML_CSS::setStyle() – Set or add a CSS definition

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setStyle ( string $element , string $property , string $value , bool $duplicates = null )

Description

Add or change a single value for an element property

Parameter

string $element

Element (or class) to be defined

string $property

Property defined

string $value

Value assigned

boolean $duplicates

(optional) Allow or disallow duplicates.

See

see HTML_CSS::getStyle()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Example

<?php
require_once 'HTML/CSS.php';

// generate an instance
$css = new HTML_CSS();

// let's set some styles for <body>
$css->setStyle('body', 'background-color', '#0c0c0c');
$css->setStyle('body', 'color', '#ffffff');

// now for <h1>
$css->setStyle('h1', 'text-align', 'center');
$css->setStyle('h1', 'font', '16pt helvetica, arial, sans-serif');

// and finally for <p>
$css->setStyle('p', 'font', '12pt helvetica, arial, sans-serif');

// let's make <body> inherit from <p>
$css->setSameStyle('body', 'p');

// and let's put this into a tag:
echo '<body style="' . $css->toInline('body') . '">';
// will output:
// <body style="font:12pt helvetica, arial, sans-serif;background-color:#0c0c0c;color:#ffffff;">
?>
Prev | Handle selector and property values | Next
HTML_CSS::getStyle | PEAR Manual | Grouping selectors


Grouping selectors

Grouping selectors

Table of Contents
  • HTML_CSS::createGroup -- Create a new CSS definition group
  • HTML_CSS::unsetGroup -- Remove a CSS definition group
  • HTML_CSS::getGroupStyle -- Return CSS definition for a CSS group
  • HTML_CSS::setGroupStyle -- Set or add a CSS definition for a CSS group
  • HTML_CSS::addGroupSelector -- Add a selector to a CSS definition group.
  • HTML_CSS::removeGroupSelector -- Remove a selector from a group
  • HTML_CSS::setSameStyle -- Apply same styles on two selectors
Prev | Reference guide | Next
HTML_CSS::setStyle | PEAR Manual | HTML_CSS::createGroup


HTML_CSS::createGroup

HTML_CSS::createGroup

HTML_CSS::createGroup() – Create a new CSS definition group

Synopsis

require_once 'HTML/CSS.php';

mixed|PEAR_Error HTML_CSS::createGroup ( string $selectors , mixed $group = null )

Description

Create a new CSS definition group. Return an integer identifying the group.

Parameter

string $selectors

Selector(s) to be defined, comma delimited.

mixed $group

(optional) Group identifier. If not passed, will return an automatically assigned integer.

See

see HTML_CSS::unsetGroup()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_INVALID_GROUP

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Example

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

// define styles
$css->setStyle('p', 'text-align', 'center');
$css->setStyle('p', 'color', '#ffffff');
$css->setStyle('p', 'text-align', 'left');
$css->setStyle('p', 'font', '16pt helvetica, arial, sans-serif');
$css->setStyle('p', 'font', '12pt helvetica, arial, sans-serif');

// create a selectors group
$groupID = 'myGroup';
$groupID = $css->createGroup('p, a', $groupID);
// define styles of this new group
$css->setGroupStyle($groupID, 'font', '12pt helvetica, arial, sans-serif');

// display result
echo $css->toString();

// will output:
/*
p, a {
  font: 12pt helvetica, arial, sans-serif;
}

p {
  text-align: left;
  color: #ffffff;
  font: 12pt helvetica, arial, sans-serif;
}
*/
?>
Prev | Grouping selectors | Next
Grouping selectors | PEAR Manual | HTML_CSS::unsetGroup


HTML_CSS::unsetGroup

HTML_CSS::unsetGroup

HTML_CSS::unsetGroup() – Remove a CSS definition group

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::unsetGroup ( mixed $group )

Description

Remove a CSS definition group. Use the same identifier as for group creation.

Parameter

mixed $group

CSS definition group identifier

See

see HTML_CSS::createGroup()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_GROUP

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Grouping selectors | Next
HTML_CSS::createGroup | PEAR Manual | HTML_CSS::getGroupStyle


HTML_CSS::getGroupStyle

HTML_CSS::getGroupStyle

HTML_CSS::getGroupStyle() – Return CSS definition for a CSS group

Synopsis

require_once 'HTML/CSS.php';

mixed|PEAR_Error HTML_CSS::getGroupStyle ( mixed $group , string $property )

Description

Get the CSS definition for group created by setGroupStyle()

Parameter

mixed $group

CSS definition group identifier

string $property

Property defined

See

see HTML_CSS::setGroupStyle()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_GROUP, HTML_CSS_ERROR_NO_ELEMENT

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Grouping selectors | Next
HTML_CSS::unsetGroup | PEAR Manual | HTML_CSS::setGroupStyle


HTML_CSS::setGroupStyle

HTML_CSS::setGroupStyle

HTML_CSS::setGroupStyle() – Set or add a CSS definition for a CSS group

Synopsis

require_once 'HTML/CSS.php';

void|int|PEAR_Error HTML_CSS::setGroupStyle ( mixed $group , string $property , string $value , bool $duplicates = null )

Description

Define the new value of a property for a CSS group. The group should exist. If not, use HTML_CSS::createGroup() first

Parameter

mixed $group

CSS definition group identifier

string $property

Property defined

string $value

Value assigned

boolean $duplicates

(optional) Allow or disallow duplicates.

Return value

returns Returns an integer if duplicates are allowed.

See

see HTML_CSS::getGroupStyle()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_GROUP

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Grouping selectors | Next
HTML_CSS::getGroupStyle | PEAR Manual | HTML_CSS::addGroupSelector


HTML_CSS::addGroupSelector

HTML_CSS::addGroupSelector

HTML_CSS::addGroupSelector() – Add a selector to a CSS definition group.

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::addGroupSelector ( mixed $group , string $selectors )

Description

Add a selector to a CSS definition group

Parameter

mixed $group

CSS definition group identifier

string $selectors

Selector(s) to be defined, comma delimited.

Throws

throws HTML_CSS_ERROR_NO_GROUP, HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Example

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

// define styles
$g = $css->createGroup('body, html');
$css->setGroupStyle($g, 'margin', '2px');
$css->setGroupStyle($g, 'padding', '0');
$css->setGroupStyle($g, 'border', '0');

// display intermediate result
echo $css->toString();

// will output:
/*
body, html {
  margin: 2px;
  padding: 0;
  border: 0;
}
*/

// did not reflect a real usage, it's only a study case purpose
$css->removeGroupSelector($g, 'body');

$css->addGroupSelector($g, '.large');
$css->setGroupStyle($g, 'border', 'solid thin');

// display final result
echo $css->toString();

// will output:
/*
html, .large {
  margin: 2px;
  padding: 0;
  border: solid thin;
}*/
?>
Prev | Grouping selectors | Next
HTML_CSS::setGroupStyle | PEAR Manual | HTML_CSS::removeGroupSelector


HTML_CSS::removeGroupSelector

HTML_CSS::removeGroupSelector

HTML_CSS::removeGroupSelector() – Remove a selector from a group

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::removeGroupSelector ( mixed $group , string $selectors )

Description

Definitively remove a selector from a CSS group

Parameter

mixed $group

CSS definition group identifier

string $selectors

Selector(s) to be removed, comma delimited.

Throws

throws HTML_CSS_ERROR_NO_GROUP, HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Grouping selectors | Next
HTML_CSS::addGroupSelector | PEAR Manual | HTML_CSS::setSameStyle


HTML_CSS::setSameStyle

HTML_CSS::setSameStyle

HTML_CSS::setSameStyle() – Apply same styles on two selectors

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setSameStyle ( string $new , string $old )

Description

Set or change the properties of a new basic selector (not group) to the values of an existing selector

Parameter

string $new

New selector that should share the same definitions

string $old

Selector that is already defined

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_ELEMENT

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Example

see HTML_CSS::setStyle() , if you want only to apply the same style as a basic selector.

see HTML_CSS::createGroup() , if you want to apply the same style to a list of selectors.

Prev | Grouping selectors | Next
HTML_CSS::removeGroupSelector | PEAR Manual | Parsing data sources


Parsing data sources

Parsing data sources

Table of Contents
  • HTML_CSS::parseString -- Parse a string
  • HTML_CSS::parseFile -- Parse file content
  • HTML_CSS::parseData -- Parse multiple data sources
Prev | Reference guide | Next
HTML_CSS::setSameStyle | PEAR Manual | HTML_CSS::parseString


HTML_CSS::parseString

HTML_CSS::parseString

HTML_CSS::parseString() – Parse a string

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::parseString ( string $str , bool $duplicates = null )

Description

Parse a string that contains CSS information

Parameter

string $str

text string to parse

boolean $duplicates

(optional) Allows or disallows duplicate style definitions

See

see HTML_CSS::createGroup() , HTML_CSS::setGroupStyle() , HTML_CSS::setStyle()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Parsing data sources | Next
Parsing data sources | PEAR Manual | HTML_CSS::parseFile


HTML_CSS::parseFile

HTML_CSS::parseFile

HTML_CSS::parseFile() – Parse file content

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::parseFile ( string $filename , bool $duplicates = null )

Description

Parse a file that contains CSS information

Parameter

string $filename

file to parse

boolean $duplicates

(optional) Allow or disallow duplicates.

See

see HTML_CSS::parseString()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_FILE

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Parsing data sources | Next
HTML_CSS::parseString | PEAR Manual | HTML_CSS::parseData


HTML_CSS::parseData

HTML_CSS::parseData

HTML_CSS::parseData() – Parse multiple data sources

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::parseData ( array $styles , bool $duplicates = null )

Description

Parse data sources, file(s) or string(s), that contains CSS information

Parameter

array $styles

data sources to parse

boolean $duplicates

(optional) Allow or disallow duplicates.

See

see HTML_CSS::parseString() , HTML_CSS::parseFile()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 1.0.0RC2 (2005-12-15)

Note

This function can not be called statically.

Prev | Parsing data sources | Next
HTML_CSS::parseFile | PEAR Manual | Checking data sources


Checking data sources

Checking data sources

Table of Contents
  • HTML_CSS::validate -- Validate a CSS data source
Prev | Reference guide | Next
HTML_CSS::parseData | PEAR Manual | HTML_CSS::validate


HTML_CSS::validate

HTML_CSS::validate

HTML_CSS::validate() – Validate a CSS data source

Synopsis

require_once 'HTML/CSS.php';

boolean|PEAR_Error HTML_CSS::validate ( array $styles , array &$messages )

Description

Execute the W3C CSS validator service on each data source (filename or string) given by parameter $styles.

Parameter

array $styles

Data sources to check validity

array &$messages

Error and Warning messages issue from W3C CSS validator service

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_INVALID_DEPS, HTML_CSS_ERROR_INVALID_SOURCE

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Prev | Checking data sources | Next
Checking data sources | PEAR Manual | Output


Output

Output

Table of Contents
  • HTML_CSS::toArray -- Return the CSS contents in an array
  • HTML_CSS::toInline -- Return a string-properties for style attribute of an HTML element
  • HTML_CSS::toFile -- Generate CSS and stores it in a file
  • HTML_CSS::toString -- Return current CSS parsed data as a string
  • HTML_CSS::display -- Output CSS Code
Prev | Reference guide | Next
HTML_CSS::validate | PEAR Manual | HTML_CSS::toArray


HTML_CSS::toArray

HTML_CSS::toArray

HTML_CSS::toArray() – Return the CSS contents in an array

Synopsis

require_once 'HTML/CSS.php';

array HTML_CSS::toArray ( )

Description

Return the full contents of CSS data sources (parsed) in an array

Throws

throws no exceptions thrown

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Output | Next
Output | PEAR Manual | HTML_CSS::toInline


HTML_CSS::toInline

HTML_CSS::toInline

HTML_CSS::toInline() – Return a string-properties for style attribute of an HTML element

Synopsis

require_once 'HTML/CSS.php';

string|PEAR_Error HTML_CSS::toInline ( string $element )

Description

Generate and return the CSS properties of an element or class as a string for inline use.

Parameter

string $element

Element or class for which inline CSS should be generated

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Output | Next
HTML_CSS::toArray | PEAR Manual | HTML_CSS::toFile


HTML_CSS::toFile

HTML_CSS::toFile

HTML_CSS::toFile() – Generate CSS and stores it in a file

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::toFile ( string $filename )

Description

Generate current parsed CSS data sources and write result in a user file

Parameter

string $filename

Name of file that content the stylesheet

See

see HTML_CSS::toString()

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_WRITE_FILE

Since

since version 0.3.0 (2003-11-03)

Note

This function can not be called statically.

Prev | Output | Next
HTML_CSS::toInline | PEAR Manual | HTML_CSS::toString


HTML_CSS::toString

HTML_CSS::toString

HTML_CSS::toString() – Return current CSS parsed data as a string

Synopsis

require_once 'HTML/CSS.php';

string HTML_CSS::toString ( )

Description

Generate current parsed CSS data sources and return result as a string

Throws

throws no exceptions thrown

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Output | Next
HTML_CSS::toFile | PEAR Manual | HTML_CSS::display


HTML_CSS::display

HTML_CSS::display

HTML_CSS::display() – Output CSS Code

Synopsis

require_once 'HTML/CSS.php';

void HTML_CSS::display ( )

Description

Send the stylesheet content to standard output, handling cacheControl and contentDisposition headers

Throws

throws no exceptions thrown

See

see HTML_CSS::toString()

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Prev | Output | Next
HTML_CSS::toString | PEAR Manual | Searching for selectors and/or properties


Searching for selectors and/or properties

Searching for selectors and/or properties

Table of Contents
  • HTML_CSS::grepStyle -- Retrieve styles corresponding to an element filter
Prev | Reference guide | Next
HTML_CSS::display | PEAR Manual | HTML_CSS::grepStyle


HTML_CSS::grepStyle

HTML_CSS::grepStyle

HTML_CSS::grepStyle() – Retrieve styles corresponding to an element filter

Synopsis

require_once 'HTML/CSS.php';

array|PEAR_Error HTML_CSS::grepStyle ( string $elmPattern , string $proPattern )

Description

Return array entries of styles that match patterns (Perl compatible)

Parameter

string $elmPattern

Element or class pattern to retrieve

string $proPattern

(optional) Property pattern to retrieve

See

see Regular Expression Functions (Perl-Compatible)

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

Since

since version 1.1.0 (2007-01-01)

Note

This function can not be called statically.

Prev | Searching for selectors and/or properties | Next
Searching for selectors and/or properties | PEAR Manual | Handling At-Rules


Handling At-Rules

Handling At-Rules

Table of Contents
  • HTML_CSS::getAtRulesList -- Return list of supported At-Rules
  • HTML_CSS::createAtRule -- Create a new simple declarative At-Rule
  • HTML_CSS::unsetAtRule -- Remove an existing At-Rule
  • HTML_CSS::getAtRuleStyle -- Get style value of an existing At-Rule
  • HTML_CSS::setAtRuleStyle -- Define a conditional/informative At-Rule
Prev | Reference guide | Next
HTML_CSS::grepStyle | PEAR Manual | HTML_CSS::getAtRulesList


HTML_CSS::getAtRulesList

HTML_CSS::getAtRulesList

HTML_CSS::getAtRulesList() – Return list of supported At-Rules

Synopsis

require_once 'HTML/CSS.php';

void HTML_CSS::getAtRulesList ( )

Description

Return the list of At-Rules supported by API 1.5.0 of HTML_CSS

Throws

throws no exceptions thrown

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Example

<?php
require_once 'HTML/CSS.php';

$list = $css->getAtRulesList();
var_export($list);

// will output:
//
// array (
//   0 => '@charset',
//   1 => '@font-face',
//   2 => '@import',
//   3 => '@media',
//   4 => '@page',
//   5 => '@namespace',
// )
?>
Prev | Handling At-Rules | Next
Handling At-Rules | PEAR Manual | HTML_CSS::createAtRule


HTML_CSS::createAtRule

HTML_CSS::createAtRule

HTML_CSS::createAtRule() – Create a new simple declarative At-Rule

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::createAtRule ( string $atKeyword , string $arguments = '' , bool $duplicates = null )

Description

Create a simple at-rule without declaration style blocks. That include @charset, @import and @namespace

Parameter

string $atKeyword

at-rule keyword

string $arguments

argument list for @charset, @import or @namespace

boolean $duplicates

(optional) Allow or disallow duplicates

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

See

see HTML_CSS::unsetAtRule()

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Prev | Handling At-Rules | Next
HTML_CSS::getAtRulesList | PEAR Manual | HTML_CSS::unsetAtRule


HTML_CSS::unsetAtRule

HTML_CSS::unsetAtRule

HTML_CSS::unsetAtRule() – Remove an existing At-Rule

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::unsetAtRule ( string $atKeyword )

Description

Remove an existing and supported at-rule. See HTML_CSS::getAtRulesList() for a full list of supported At-Rules.

Parameter

string $atKeyword

at-rule keyword

Throws

throws HTML_CSS_ERROR_INVALID_INPUT, HTML_CSS_ERROR_NO_ATRULE

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Prev | Handling At-Rules | Next
HTML_CSS::createAtRule | PEAR Manual | HTML_CSS::getAtRuleStyle


HTML_CSS::getAtRuleStyle

HTML_CSS::getAtRuleStyle

HTML_CSS::getAtRuleStyle() – Get style value of an existing At-Rule

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::getAtRuleStyle ( string $atKeyword , string $arguments , string $selectors , string $property )

Description

Retrieve arguments or style value of an existing At-Rule. See HTML_CSS::getAtRulesList() for a full list of supported At-Rules.

Parameter

string $atKeyword

at-rule keyword

string $arguments

argument list (optional for @font-face)

string $selectors

selectors of declaration style block (optional for @media, @page, @font-face)

string $property

property of a single declaration style block

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

See

see HTML_CSS::setAtRuleStyle()

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Prev | Handling At-Rules | Next
HTML_CSS::unsetAtRule | PEAR Manual | HTML_CSS::setAtRuleStyle


HTML_CSS::setAtRuleStyle

HTML_CSS::setAtRuleStyle

HTML_CSS::setAtRuleStyle() – Define a conditional/informative At-Rule

Synopsis

require_once 'HTML/CSS.php';

void|PEAR_Error HTML_CSS::setAtRuleStyle ( string $atKeyword , string $arguments , string $selectors , string $property , string $value , bool $duplicates = null )

Description

Set arguments and declaration style block for at-rules that follow : "@media, @page, @font-face"

Parameter

string $atKeyword

at-rule keyword

string $arguments

argument list (optional for @font-face)

string $selectors

selectors of declaration style block (optional for @media, @page, @font-face)

string $property

property of a single declaration style block

string $value

value of a single declaration style block

boolean $duplicates

(optional) Allow or disallow duplicates

Throws

throws HTML_CSS_ERROR_INVALID_INPUT

See

see HTML_CSS::getAtRuleStyle()

Since

since version 1.5.0 (2008-01-15)

Note

This function can not be called statically.

Prev | Handling At-Rules | Next
HTML_CSS::getAtRuleStyle | PEAR Manual | Handling error


Handling error

Handling error

Table of Contents
  • Error Handler -- Flexible error handler plug-in system
Prev | Reference guide | Next
HTML_CSS::setAtRuleStyle | PEAR Manual | Error Handler


Error Handler

Error Handler

Error Handler – Flexible error handler plug-in system

Introduction

The HTML_CSS package is implemented with a flexible error handler plug-in system. You may use any error handler that you want. Using PEAR_Error object (default), but also the PEAR_ErrorStack package, or any other error handler you might want to plug in.

Without any configuration, each HTML_CSS API error (basic or exception) will raise a HTML_CSS_Error object that will be return to call script (user script).

Tip

Easy to distinct basic PEAR_Error from other PEAR packages to HTML_CSS errors, even if there is a better and more robust solution: HTML_CSS::isError(). But also provide a unique way to retrieve the level of error (warning, error, exception) with the HTML_CSS_Error::getLevel() method.

As usual you can use the PEAR error API as well.

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

$result = $css->setStyle('div', 'color', 5);
if (PEAR::isError($result)) {
    // do something when an error is raised
}
?>

and output to screen will give something like :

Exception*: invalid input, parameter #3 "$value" was expecting "string",

instead got "integer"** in html_css->setstyle (file [path_to]\[filename] on line 6)***

(1) | error level
(2) | message body with context informations
(3) | call context

Perhaps this standard behavior is not what you want. Don't worry, you can change everything :

  • display or ignore the error

  • display or hide part of message (error level, body, context)

Important: HTML_CSS obey at display_errors and log_errors protocol

Configuring a Handler

A error handler's configuration is determined by the arguments used in its construction. Here's an overview of these parameters.

<?php
require_once 'HTML/CSS.php';

$errorConf = array('error_handler' => 'myErrorHandler',
                   'push_callback' => 'myError',
                   // ... more options
                  );
$css = new HTML_CSS(null, $errorConf);
?>

Error Handler configuration parameters
Option | Type | Description
error_handler | callback | A valid callback (function) to manage errors raised by the HTML_CSS::raiseError() method. Default is: HTML_CSS::_errorHandler
push_callback | callback | A valid callback (function) that decides to following action. Default return: PEAR_ERROR_DIE if exception, NULL otherwise.
error_callback | callback | A valid callback (function) that decides to call a real free user function. Default call: none
message_callback | callback | A valid callback (function) to control message generation. Default is: HTML_CSS_Error::_msgCallback
context_callback | callback | A valid callback (function) to control error context generation. Default is: HTML_CSS_Error::getBacktrace
handler | mixed | any handler-specific settings

Controlling error generation

There are many scenarios in which fine-grained control over error raising is absolutely necessary.

The first level to control error generation is the php.ini directives display_errors and log_errors. When these directives are set to TRUE, then browser and file outputs are effective.

Tip

If you want to ignore all errors raised (no display, no logs) and avoid to include PEAR core class, then you should have something like :

<?php
require_once 'HTML/CSS.php';

function myErrorHandler()
{
    return null;
}

$errorConf = array('error_handler' => 'myErrorHandler');
$css = new HTML_CSS(null, $errorConf);
// ...
?>

Note: Note for users of HTML_CSS 1.4.0 or greater
 You may want to decide to print (yes/no), log (yes/no) error messages with a full free user function local to HTML_CSS
<?php
require_once 'HTML/CSS.php';

function myErrorAction($css_error)
{
    // do what you want: print and/or log $css_error instance of HTML_CSS_Error object
}

$errorConf = array('error_callback' => 'myErrorAction');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
rather than using global PEAR error handler (PEAR::setErrorHandling, PEAR::pushErrorHandling, PEAR::popErrorHandling).
<?php
require_once 'HTML/CSS.php';

function myErrorAction($css_error)
{
    // do what you want: print and/or log $css_error instance of HTML_CSS_Error object
}

PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'myErrorAction');

$css = new HTML_CSS();
// ...
?>

With push_callback option, you can decides to stop script execution (as done with exceptions by default: returns PEAR_ERROR_DIE constant), or continue without filtering (returns NULL).

If you want to write your own callback function for the push_callback option, this one should have two arguments: first one will get the error code, and second will get error level. These are all the necessary informations to do a filtering. Example that follow show how to be aware that a script use wrong argument data type.

<?php
require_once 'HTML/CSS.php';

function myErrorFilter($code, $level)
{
    if ($code === HTML_CSS_ERROR_INVALID_INPUT) {
        error_log('script: '.__FILE__.' used wrong argument data type', 1, 'admin@yoursite.com');
    }
    return null;
}

$errorConf = array('push_callback' => 'myErrorFilter');
$css = new HTML_CSS(null, $errorConf);
// ...
?>

Error Context Display

In some cases, you may want to customize error generation. For instance, for each error (basic/exception), it is useful to include file, line number, and class/function context information in order to trace it. The default option will be sufficient for most cases but you want perhaps customize the output format (render) of context information.

With this example we will change display and log renders.

<?php
require_once 'HTML/CSS.php';

$displayConfig = array(
    'lineFormat' => '<b>%1$s</b>: %2$s<br />%3$s',
    'contextFormat' =>   '<b>File:</b> %1$s <br />'
                       . '<b>Line:</b> %2$s <br />'
                       . '<b>Function:</b> %3$s '
);
$logConfig = array(
    'lineFormat' => '%1$s %2$s [%3$s] %4$s',
    'timeFormat' => '%b'
);

$prefs = array(
    'handler' => array('display' => $displayConfig,
                       'log'     => $logConfig
));

$css = new HTML_CSS(null, $prefs);
// ...
$result = $css->setStyle('div', 'color', 5);
?>

Display render will give something like:

Exception****: invalid input, parameter #3 "$value" was expecting "string", instead got "integer"*****

File: [path_to]\[filename] ******

Line: 22

Function: html_css->setstyle

(1) | error level
(2) | message body with context informations
(3) | call context (file, line, function)

Log render will give something like:

Jun 127.0.0.1******* [exception********] invalid input, parameter #3 "$value" was expecting "string", instead got "integer"*********

(1) | client ip address and execution date
(2) | error level
(3) | message body with context informations
Note: To have both display and log output, check the php.ini display_errors and log_errors values : must be set to TRUE.

Let review, step by step, how to get such results.

Remember that with default classes, there are two drivers : display and log that have both their own configuration parameters. You can override these parameters values with the handler entry in the hash of second argument of the HTML_CSS class constructor.

We did it here with the $prefs variable; it's a two key associative array. First key display defines the display driver values, and the second key log defines the log driver values.

Review the display driver custom values. Only two keys:

  • lineFormat
  • contextFormat

are redefined, thats means remains key

  • eol

keep its default value. See table below.

Display driver configuration parameters
Parameter | Type | Default | Description
eol | string | <br />\n | The end-on-line character sequence
lineFormat string <b>%1$s</b>: %2$s %3$s Log line format specification:

  • 1$ = error level

  • 2$ = error message (body)

  • 3$ = error context
contextFormat string in <b>%3$s</b> (file <b>%1$s</b> on line <b>%2$s</b>) Context format (class, file, line) specification:

  • 1$ = script file name

  • 2$ = line in script file

  • 3$ = class/method names

Tip

If you don't wish to see context information in the error message, then remove the parameter %3$ in the lineFormat option even if contextFormat is set.

Review now the log driver custom values. Only two keys

  • lineFormat
  • timeFormat

are redefined, thats means six remains keys

  • eol
  • contextFormat
  • ident
  • message_type
  • destination
  • extra_headers

keep their default values. See table below.

Log driver configuration parameters
Parameter | Type | Default | Description
eol | string | \n | The end-on-line character sequence
lineFormat string %1$s %2$s [%3$s] %4$s %5$s Log line format specification:

  • 1$ = time error

  • 2$ = ident (client ip)

  • 3$ = error level

  • 4$ = error message (body)

  • 5$ = error context
contextFormat string in %3$s (file %1$s on line %2$s) Context format (class, file, line) specification:

  • 1$ = script file name

  • 2$ = line in script file

  • 3$ = class/method names
timeFormat | string | %b %d %H:%M:%S | Time stamp format used by strftime
ident | string | REMOTE_ADDR | Client IP
message_type | string | 3 | Destination type used by error_log
destination | string | html_css_error.log | Destination name used by error_log
extra_headers | string | NULL | Extra headers depending of destination type

Tip

If you don't wish to see context information in the error message, then remove the parameter %5$ in the lineFormat option even if contextFormat is set.

Custom Error Message Generation

There are two methods of HTML_CSS_Error designed for use with generating error messages efficiently. To use them, you must set the options below in the HTML_CSS class constructor (argument #2):

Option: message_callback

The default message handling callback (HTML_CSS_Error::_getErrorMessage) get an array mapping error codes to error message templates, like so:

<?php
$messages = array(
    HTML_CSS_ERROR_UNKNOWN =>
        'unknown error',
    HTML_CSS_ERROR_INVALID_INPUT =>
        'invalid input, parameter #%paramnum% '
      . '"%var%" was expecting '
      . '"%expected%", instead got "%was%"'
);
?>

Basically, if a variable name is enclosed in percent signs (%), it will be replaced with the value passed in the associative array.

Option: context_callback

The default context handling callback (HTML_CSS_Error::getBackTrace) gets an array of execution functions and discovers where the error was generated.

Prev | Handling error | Next
Handling error | PEAR Manual | HTML_Form


HTML_Form

HTML_Form

This is a simple HTML form generator. It supports all the HTML form element types including file uploads, may return or print the form, just individual form elements or the full form in "table mode" with a fixed layout.

Table of Contents
  • Introduction -- Generating HTML forms.
  • Usage examples -- Using HTML_Form.
Prev | HTML | Next
Error Handler | PEAR Manual | Introduction


Introduction

Edited By

Martin Jansen

Introduction

Introduction – Generating HTML forms.

What is HTML_Form?

This is a simple HTML form generator. It supports all the HTML form element types including file uploads, may return or print the form, just individual form elements or the full form in "table mode" with a fixed layout.

Range of use

Generally one can use HTML_Form in HTML based projects of any form. But especially when using the package in "table mode" one may soon run into design problems, because the table that is created by HTML_Form cannot be equipped with CSS or other ways to control their look. Thus the main usage area of HTML_Form are sites where design does not play the most important role but where it is necessary to get fast results while keeping the code clean at the same time. (Examples are back office websites or places like pear.php.net, where the package is used at a lot of places.)

Simple usage example

Basic example

<?php
require_once "HTML/Form.php";

$form = new HTML_Form('receivingscript.php');

$form->addText("name", "What's your name?");
$form->addSubmit("submit", "Go, Go");

$form->display();
?>

The above example code creates a HTML form that only contains a single textfield with the name "name" and with the label "What's your name" and a submit button labeled "Go, Go".

Supported tags

The following HTML form tags are supported by HTML_Form: textfields, password fields, checkboxes, textareas, submit buttons, reset buttons, select fields, radio buttons, image fields, hidden fields, file upload fields. Additionally one can add blank spaces and plain text to the form.

Prev | HTML_Form | Next
HTML_Form | PEAR Manual | Usage examples


Usage examples

Edited By

Martin Jansen

Usage examples

Usage examples – Using HTML_Form.

Creating the form in "table mode"

Creating a form in "table mode" means that the package returns the complete form in a fixed width table. Whilst this does not work very well for most frontend websites, it is a very convenient way to create forms during development phase or for backend systems where the design does not matter (much).

Creating a form

<?php
require_once "HTML/Form.php";

$form = new HTML_Form('receivingscript.php');

$form->addText("name", "What's your name?");
$form->addText("email", "What's your email address?");
$form->addPassword("password", "Please enter the desired password");
$form->addPlaintext("Tip", "Your password should be hard to guess");
$form->addSubmit("submit", "Submit");

$form->display();
?>

This will display a table where the left column holds the labels of the different fields. In the right column the different fields are placed.

Displaying single form tags

Apart from retrieving the table as a whole, one can also use the API of HTML_Form to directly display single form tags.

Directly displaying form tags

<?php
require_once "HTML/Form.php";

$form = new HTML_Form('receivingscript.php');

$form->displayText("name", "What's your name?");
?>

The above example will print the HTML markup being necessary to render a text input field. It will not print the surrounding <form /> tag or something else!

Returing single form tags

Similar to displaying form tags with the display*() functions HTML_Form can also return the tag instead of printing it.

Returning form tags

<?php
require_once "HTML/Form.php";

$form = new HTML_Form('receivingscript.php');

$str = $form->returnPassword("password", "Choose a password");
?>

The variable $str now contains HTML markup like <input type="password" name="password" />.

Prev | HTML_Form | Next
Introduction | PEAR Manual | HTML_Menu


HTML_Menu

HTML_Menu

With the HTML_Menu class one can easily create and maintain a navigation structure for websites, configuring it via a multidimensional hash structure. Different modes for the HTML output are supported.

Table of Contents
  • Introduction -- Menu structure and supported output modes
  • constructor HTML_Menu::HTML_Menu() -- Initializes the menu, sets the type and menu structure.
  • HTML_Menu::forceCurrentUrl() -- Forces the given URL to be "current"
  • HTML_Menu::get() -- Returns the HTML menu.
  • HTML_Menu::getCurrentURL() -- Returns the URL of the currently selected page.
  • HTML_Menu::getPath() -- Returns the path of the current page in the menu 'tree'.
  • HTML_Menu::render() -- Renders the menu.
  • HTML_Menu::setMenu() -- Sets the menu structure.
  • HTML_Menu::setMenuType() -- Sets the type of the menu.
  • HTML_Menu::setURLEnvVar() -- Sets the environment variable to use to get the current URL.
  • HTML_Menu::setURLPrefix() -- Sets the prefix for the URLs in the menu
  • HTML_Menu::show() -- Prints the HTML menu.
  • Class Summary HTML_Menu_Renderer -- An abstract base class for HTML_Menu renderers (package developer related)
  • HTML_Menu_Renderer::finishLevel() -- Finish the tree level (for types 'tree' and 'sitemap') (package developer related)
  • HTML_Menu_Renderer::finishMenu() -- Finish the menu (package developer related)
  • HTML_Menu_Renderer::finishRow() -- Finish the row in the menu (package developer related)
  • HTML_Menu_Renderer::renderEntry() -- Renders the element of the menu (package developer related)
  • HTML_Menu_Renderer::setMenuType() -- Sets the type of the menu being rendered
  • Class Summary HTML_Menu_DirectRenderer -- The renderer that generates HTML for the menu all by itself.
  • DirectRenderer::setEntryTemplate() -- Sets the template for menu entry.
  • DirectRenderer::setMenuTemplate() -- Sets the menu template (HTML that wraps around rows)
  • DirectRenderer::setRowTemplate() -- Sets the row template (HTML that wraps around entries)
  • DirectRenderer::toHtml() -- returns the HTML generated for the menu
  • Class Summary HTML_Menu_DirectTreeRenderer -- The "direct" renderer for 'tree' and 'sitemap' menu types where level is represented by tags nesting.
  • DirectTreeRenderer::setEntryTemplate() -- Sets the template for menu entry.
  • DirectTreeRenderer::setItemTemplate() -- Sets the item template (HTML that wraps around entries)
  • DirectTreeRenderer::setLevelTemplate() -- Sets the level template (HTML that wraps around the submenu)
  • DirectTreeRenderer::toHtml() -- returns the HTML generated for the menu
  • Class Summary HTML_Menu_ArrayRenderer -- The renderer that creates an array of visible menu entries.
  • ArrayRenderer::toArray() -- returns the resultant array
  • Class Summary HTML_Menu_SigmaRenderer -- The renderer that uses HTML_Template_Sigma instance for menu output.
  • constructor HTML_Menu_SigmaRenderer() -- Class constructor.
  • Class Summary HTML_Menu_SigmaTreeRenderer -- HTML_Template_Sigma-based renderer for 'tree' and 'sitemap' type menus, where menu level is represented by tag nesting.
  • constructor HTML_Menu_SigmaTreeRenderer() -- Class constructor.
  • Class Summary HTML_MenuBrowser -- Simple filesystem browser that can be used to generated menu (3) hashes based on the directory structure.
  • constructor HTML_MenuBrowser::HTML_MenuBrowser() -- Creates the object and optionally sets the directory to scan.
  • HTML_MenuBrowser::addFileInfo() -- Adds further informations to the menu hash gathered from the files in it
  • HTML_MenuBrowser::browse() -- Recursive function that does the scan and builds the menu (3) hash.
  • HTML_MenuBrowser::exploreFile() -- Returns additional menu informations decoded in the file that appears in the menu.
  • HTML_MenuBrowser::getMenu() -- Returns a hash to be used with menu(3)'s setMenu().
  • HTML_MenuBrowser::setDirectory() -- Sets the directory to scan.
  • HTML_MenuBrowser::setIDPrefix() -- Sets the prefix for every id in the menu hash.
  • Package HTML_Menu Constants -- Constants defined in and used by HTML_Menu
Prev | HTML | Next
Usage examples | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Menu structure and supported output modes

Menu hash structure

The menu structure is defined by a multidimensional hash. This makes it quite easy to generate and traverse:

Menu multidimensional hash

<?php
array(
    1 => array(
        'title' => 'Menu item 1',
        'url' => '/item1.php',
        'sub' => array(
            11 => array('title' => 'Menu item 1.1', 'url' => '/item1.1.php'),
            12 => array(
                'title' => 'Menu item 1.2',
                'url' => '/item1.2.php',
                'sub' => array(
                    121 => array('title' => 'Menu item 1.2.1', 'url' => '/item1.2.1.php'),
                    122 => array('title' => 'Menu item 1.2.2', 'url' => '/item1.2.2.php')
                )
            )
        )
    ),
    2 => array(
        'title' => 'Menu item 2',
        'url' => '/item2.php',
        'sub' => array(
            21 => array('title' => 'Menu item 2.1', 'url' => '/item2.1.php'),
            22 => array('title' => 'Menu item 2.2', 'url' => '/item2.2.php')
        )
    )
);
?>

Each entry should have at least 'url' and 'title' keys and may also have 'sub' key containing the children of this entry. Note that keys in the entry arrays serve as node identifiers and should be unique.

The menu entries can also contain custom keys. If such keys are present, then they will be used by renderers in creating the output (this usually means that the content of such a key will be assigned to the template placeholder with the same name).

Supported output modes

HTML_Menu supports five output modes: 'tree' (default), 'rows', 'urhere', 'prevnext' and 'sitemap'. Lets use the array defined above as menu structure assuming that element 'Menu item 1.2' is currently active and try each menu type.

'tree'

This type of the menu mostly follows the internal structure of the menu hash. Different levels of the menu are marked by indentation, only the elements leading to the active item or immediately following it are shown.

Output for menu type 'tree'

Menu item 1
    Menu item 1.1
    Menu item 1.2
        Menu item 1.2.1
        Menu item 1.2.2
Menu item 2
'rows'

This is quite similar to 'tree' type, only different levels are not marked by indentation, but are shown on different rows of the menu.

Output for menu type 'rows'

Menu item 1  Menu item 2
Menu item 1.1  Menu item 1.2
Menu item 1.2.1  Menu item 1.2.2
'urhere'

This is so-called 'breadcrumb' navigation, allowing to easily understand your position within site hierarchy.

Output for menu type 'urhere'

Menu item 1 >> Menu item 1.2
'prevnext'

This is the menu often used in documentation (including the PEAR manual), the links lead to previous, next and parent entries of the current entry.

Output for menu type 'prevnext'

<< Menu item 1.1  ^ Menu item 1 ^  Menu item 1.2.1 >>
'sitemap'

This is 'tree' type menu, but with all entries shown.

Output for menu type 'sitemap'

Menu item 1
    Menu item 1.1
    Menu item 1.2
        Menu item 1.2.1
        Menu item 1.2.2
Menu item 2
    Menu item 2.1
    Menu item 2.2

Usage example

Very basic usage example

<?php
// Load the class
require_once 'HTML/Menu.php';

// Instantiate the menu object, we presume that $data contains menu structure
$menu =& new HTML_Menu($data, 'tree');

// Output the menu
$menu->show();
?>
Prev | HTML_Menu | Next
HTML_Menu | PEAR Manual | constructor HTML_Menu::HTML_Menu()


constructor HTML_Menu::HTML_Menu()

constructor HTML_Menu::HTML_Menu()

constructor HTML_Menu::HTML_Menu() – Initializes the menu, sets the type and menu structure.

Synopsis

require_once 'HTML/Menu.php';

void constructor HTML_Menu::HTML_Menu ( array $menu = null , string $type = 'tree' , string $urlEnvVar = 'PHP_SELF' )

Description

Initializes the menu, sets the menu structure, type and variable to use for determining the current URL. All parameters are optional and can be set later by corresponding methods.

Parameter

array $menu

Menu structure

string $type

Menu type: 'tree', 'rows', 'urhere', 'prevnext', 'sitemap'

string $urlEnvVar

Environment variable to use for determining the current URL.

Throws

throws no exceptions thrown

See

see HTML_Menu::setMenuType(),
                         HTML_Menu::setMenu(),
                         HTML_Menu::setURLEnvVar().

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Introduction | PEAR Manual | HTML_Menu::forceCurrentUrl()


HTML_Menu::forceCurrentUrl()

HTML_Menu::forceCurrentUrl()

HTML_Menu::forceCurrentUrl() – Forces the given URL to be "current"

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::forceCurrentUrl ( string $url )

Description

Use this if you do not want to extract current URL from some environment variable (e.g. $_SERVER['PHP_SELF']) but rather use some custom logic to determine it.

Parameter

string $url

Url to use

Throws

throws no exceptions thrown

See

see HTML_Menu::setURLEnvVar(), HTML_Menu::getCurrentUrl()

Note

This function can not be called statically.

Prev | HTML_Menu | Next
constructor HTML_Menu::HTML_Menu() | PEAR Manual | HTML_Menu::get()


HTML_Menu::get()

HTML_Menu::get()

HTML_Menu::get() – Returns the HTML menu.

Synopsis

require_once 'HTML/Menu.php';

string HTML_Menu::get ( string $menuType = '' )

Description

This method uses HTML_Menu_DirectRenderer for its work. The renderer is used with default templates, you should use the render() method if you want to customize the output.

Parameter

string $menuType

Menu type: 'tree', 'rows', 'urhere', 'prevnext', 'sitemap'

Return value

returns HTML of the menu

Throws

throws no exceptions thrown

See

see HTML_Menu::show(), HTML_Menu::render().

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::forceCurrentUrl() | PEAR Manual | HTML_Menu::getCurrentURL()


HTML_Menu::getCurrentURL()

HTML_Menu::getCurrentURL()

HTML_Menu::getCurrentURL() – Returns the URL of the currently selected page.

Synopsis

require_once 'HTML/Menu.php';

string HTML_Menu::getCurrentURL ( )

Description

The returned string is used for all test against the URL's in the menu structure hash.

Throws

throws no exceptions thrown

See

see HTML_Menu::setURLEnvVar(), HTML_Menu::forceCurrentUrl().

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::get() | PEAR Manual | HTML_Menu::getPath()


HTML_Menu::getPath()

HTML_Menu::getPath()

HTML_Menu::getPath() – Returns the path of the current page in the menu 'tree'.

Synopsis

require_once 'HTML/Menu.php';

array HTML_Menu::getPath ( )

Description

'Path' here means the sequence of entry IDs leading to the current menu entry.

Return value

returns path to the selected menu item

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::getCurrentURL() | PEAR Manual | HTML_Menu::render()


HTML_Menu::render()

HTML_Menu::render()

HTML_Menu::render() – Renders the menu.

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::render ( object HTML_Menu_Renderer &$renderer , string $menuType = '' )

Description

All logic to actually create the output is contained in the renderer. render() just calls the appropriate method to traverse the menu structure.

Parameter

object HTML_Menu_Renderer &$renderer

Renderer to use

string $menuType

type of the menu

Throws

throws PEAR_Error. If the renderer is not designed to handle this type of menu, it will throw an error.

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::getPath() | PEAR Manual | HTML_Menu::setMenu()


HTML_Menu::setMenu()

HTML_Menu::setMenu()

HTML_Menu::setMenu() – Sets the menu structure.

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::setMenu ( array $menu )

Description

The menu structure is defined by a multidimensional hash.

Parameter

array $menu

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::render() | PEAR Manual | HTML_Menu::setMenuType()


HTML_Menu::setMenuType()

HTML_Menu::setMenuType()

HTML_Menu::setMenuType() – Sets the type of the menu.

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::setMenuType ( string $menuType )

Description

Available types are: 'tree', 'rows', 'urhere', 'prevnext', 'sitemap'.

Parameter

string $menuType

type name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::setMenu() | PEAR Manual | HTML_Menu::setURLEnvVar()


HTML_Menu::setURLEnvVar()

HTML_Menu::setURLEnvVar()

HTML_Menu::setURLEnvVar() – Sets the environment variable to use to get the current URL.

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::setURLEnvVar ( string $urlEnvVar )

Description

The default variable name is 'PHP_SELF', which means 'current script name'.

Parameter

string $urlEnvVar

environment variable for current URL

Throws

throws no exceptions thrown

See

see HTML_Menu::getCurrentURL(), HTML_Menu::forceCurrentURL().

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::setMenuType() | PEAR Manual | HTML_Menu::setURLPrefix()


HTML_Menu::setURLPrefix()

HTML_Menu::setURLPrefix()

HTML_Menu::setURLPrefix() – Sets the prefix for the URLs in the menu

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::setURLPrefix ( string $prefix )

Description

This is useful if you have relative URLs in the menu description structure. This prefix will be appended to the URLs from this structure and the result will be compared to "current" URL.

Parameter

string $prefix

menu URL prefix

Throws

throws no exceptions thrown

See

see HTML_Menu::getCurrentURL(),
                         HTML_Menu::forceCurrentURL(),
                         HTML_Menu::setMenu().

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::setURLEnvVar() | PEAR Manual | HTML_Menu::show()


HTML_Menu::show()

HTML_Menu::show()

HTML_Menu::show() – Prints the HTML menu.

Synopsis

require_once 'HTML/Menu.php';

void HTML_Menu::show ( string $menuType = '' )

Description

This method uses HTML_Menu_DirectRenderer for its work. The renderer is used with default templates, you should use the render() method if you want to customize the output.

Parameter

string $menuType

Menu type: 'tree', 'rows', 'urhere', 'prevnext', 'sitemap'

Throws

throws no exceptions thrown

See

see HTML_Menu::get(), HTML_Menu::render().

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu::setURLPrefix() | PEAR Manual | Class Summary HTML_Menu_Renderer


Class Summary HTML_Menu_Renderer

Class Summary HTML_Menu_Renderer

Class Summary HTML_Menu_Renderer – An abstract base class for HTML_Menu renderers (package developer related)

Description

This class defines methods that should be implemented by child classes to provide necessary output logic. You only need to read its description if you intend to write your own renderer.

Class Trees for HTML_Menu_Renderer

  • HTML_Menu_Renderer

Classes that extend HTML_Menu_Renderer
Class | Summary
HTML_Menu_ArrayRenderer | The renderer that creates an array of visible menu entries.
HTML_Menu_DirectRenderer | The renderer that generates HTML for the menu all by itself.
HTML_Menu_DirectTreeRenderer | The "direct" renderer for 'tree' and 'sitemap' menu types where level is represented by tags nesting.
HTML_Menu_SigmaRenderer | The renderer that uses HTML_Template_Sigma instance for menu output.
HTML_Menu_SigmaTreeRenderer | HTML_Template_Sigma-based renderer for 'tree' and 'sitemap' type menus, where menu level is represented by tag nesting.
Prev | HTML_Menu | Next
HTML_Menu::show() | PEAR Manual | HTML_Menu_Renderer::finishLevel()


HTML_Menu_Renderer::finishLevel()

HTML_Menu_Renderer::finishLevel()

HTML_Menu_Renderer::finishLevel() – Finish the tree level (for types 'tree' and 'sitemap') (package developer related)

Synopsis

require_once 'HTML/Menu/Renderer.php';

void HTML_Menu_Renderer::finishLevel ( int $level )

Description

This package is not documented yet.

Parameter

integer $level

current depth in the tree structure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_Menu_Renderer | PEAR Manual | HTML_Menu_Renderer::finishMenu()


HTML_Menu_Renderer::finishMenu()

HTML_Menu_Renderer::finishMenu()

HTML_Menu_Renderer::finishMenu() – Finish the menu (package developer related)

Synopsis

require_once 'HTML/Menu/Renderer.php';

void HTML_Menu_Renderer::finishMenu ( int $level )

Description

This package is not documented yet.

Parameter

integer $level

current depth in the tree structure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu_Renderer::finishLevel() | PEAR Manual | HTML_Menu_Renderer::finishRow()


HTML_Menu_Renderer::finishRow()

HTML_Menu_Renderer::finishRow()

HTML_Menu_Renderer::finishRow() – Finish the row in the menu (package developer related)

Synopsis

require_once 'HTML/Menu/Renderer.php';

void HTML_Menu_Renderer::finishRow ( int $level )

Description

This package is not documented yet.

Parameter

integer $level

current depth in the tree structure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu_Renderer::finishMenu() | PEAR Manual | HTML_Menu_Renderer::renderEntry()


HTML_Menu_Renderer::renderEntry()

HTML_Menu_Renderer::renderEntry()

HTML_Menu_Renderer::renderEntry() – Renders the element of the menu (package developer related)

Synopsis

require_once 'HTML/Menu/Renderer.php';

void HTML_Menu_Renderer::renderEntry ( array $node , int $level , int $type )

Description

This package is not documented yet.

Parameter

array $node

Element being rendered

integer $level

Current depth in the tree structure

integer $type

Type of the element (one of HTML_MENU_ENTRY_* constants)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu_Renderer::finishRow() | PEAR Manual | HTML_Menu_Renderer::setMenuType()


HTML_Menu_Renderer::setMenuType()

HTML_Menu_Renderer::setMenuType()

HTML_Menu_Renderer::setMenuType() – Sets the type of the menu being rendered

Synopsis

require_once 'HTML/Menu/Renderer.php';

void HTML_Menu_Renderer::setMenuType ( string $menuType )

Description

This package is not documented yet.

Parameter

string $menuType

menu type

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_Menu_Renderer::renderEntry() | PEAR Manual | Class Summary HTML_Menu_DirectRenderer


Class Summary HTML_Menu_DirectRenderer

Class Summary HTML_Menu_DirectRenderer

Class Summary HTML_Menu_DirectRenderer – The renderer that generates HTML for the menu all by itself.

Description

This renderer directly generates the menu HTML, thus the name. It is loosely based on HTML_Menu 1.0 code, but while it was needed to subclass HTML_Menu to customize its output, HTML_Menu_DirectRenderer has built-in methods for changing menu appearance.

Class Trees for HTML_Menu_DirectRenderer

  • HTML_Menu_Renderer

    • HTML_Menu_DirectRenderer

HTML_Menu_DirectRenderer Inherited Methods

Inherited from HTML_Menu_Renderer
Method Name | Summary
HTML_Menu_Renderer::finishLevel() | Finish the tree level (for types 'tree' and 'sitemap')
HTML_Menu_Renderer::finishMenu() | Finish the menu
HTML_Menu_Renderer::finishRow() | Finish the row in the menu
HTML_Menu_Renderer::renderEntry() | Renders the element of the menu
HTML_Menu_Renderer::setMenuType() | Sets the type of the menu being rendered.
Prev | HTML_Menu | Next
HTML_Menu_Renderer::setMenuType() | PEAR Manual | DirectRenderer::setEntryTemplate()


DirectRenderer::setEntryTemplate()

DirectRenderer::setEntryTemplate()

DirectRenderer::setEntryTemplate() – Sets the template for menu entry.

Synopsis

require_once 'HTML/Menu/DirectRenderer.php';

void HTML_Menu_DirectRenderer::setEntryTemplate ( mixed $type , string $template = null )

Description

The template should contain at least the {title} placeholder, can also contain {url} and {indent} placeholders, depending on entry type. Default templates are:

<?php
array(
    HTML_MENU_ENTRY_INACTIVE    => '<td>{indent}<a href="{url}">{title}</a></td>',
    HTML_MENU_ENTRY_ACTIVE      => '<td>{indent}<b>{title}</b></td>',
    HTML_MENU_ENTRY_ACTIVEPATH  => '<td>{indent}<b><a href="{url}">{title}</a></b></td>',
    HTML_MENU_ENTRY_PREVIOUS    => '<td><a href="{url}">&lt;&lt; {title}</a></td>',
    HTML_MENU_ENTRY_NEXT        => '<td><a href="{url}">{title} &gt;&gt;</a></td>',
    HTML_MENU_ENTRY_UPPER       => '<td><a href="{url}">^ {title} ^</a></td>',
    HTML_MENU_ENTRY_BREADCRUMB  => '<td><a href="{url}">{title}</a> &gt;&gt; </td>'
);
?>

Parameter

mixed $type

either type (one of HTML_MENU_ENTRY_* constants) or an array 'type' => 'template'

string $template

template for this entry type if $type is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_Menu_DirectRenderer | PEAR Manual | DirectRenderer::setMenuTemplate()


DirectRenderer::setMenuTemplate()

DirectRenderer::setMenuTemplate()

DirectRenderer::setMenuTemplate() – Sets the menu template (HTML that wraps around rows)

Synopsis

require_once 'HTML/Menu/DirectRenderer.php';

void HTML_Menu_DirectRenderer::setMenuTemplate ( string $prepend , string $append )

Description

These are the strings that will be prepended and appended to HTML generated for menu rows on each call to finishMenu(). Defaults are

'<table border="1">'

and

'</table>'

Parameter

string $prepend

this will be prepended to the rows HTML

string $append

this will be appended to the rows HTML

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
DirectRenderer::setEntryTemplate() | PEAR Manual | DirectRenderer::setRowTemplate()


DirectRenderer::setRowTemplate()

DirectRenderer::setRowTemplate()

DirectRenderer::setRowTemplate() – Sets the row template (HTML that wraps around entries)

Synopsis

require_once 'HTML/Menu/DirectRenderer.php';

void HTML_Menu_DirectRenderer::setRowTemplate ( string $prepend , string $append )

Description

These are the strings that will be prepended and appended to HTML generated for menu entries on each call to finishRow(). Defaults are

'<tr>'

and

'</tr>'

Parameter

string $prepend

this will be prepended to the entries HTML

string $append

this will be appended to the entries HTML

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
DirectRenderer::setMenuTemplate() | PEAR Manual | DirectRenderer::toHtml()


DirectRenderer::toHtml()

DirectRenderer::toHtml()

DirectRenderer::toHtml() – returns the HTML generated for the menu

Synopsis

require_once 'HTML/Menu/DirectRenderer.php';

string HTML_Menu_DirectRenderer::toHtml ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
DirectRenderer::setRowTemplate() | PEAR Manual | Class Summary HTML_Menu_DirectTreeRenderer


Class Summary HTML_Menu_DirectTreeRenderer

Class Summary HTML_Menu_DirectTreeRenderer

Class Summary HTML_Menu_DirectTreeRenderer – The "direct" renderer for 'tree' and 'sitemap' menu types where level is represented by tags nesting.

Description

The renderer is designed to output only the menus of type 'tree' and 'sitemap'. It shows the level of the menu by tags nesting, not by outputting some indentation and is able to output e.g. nested HTML lists:

<ul>
    <li>Menu item 1
        <ul>
            <li>Menu item 1.1</li>
            <li>Menu item 1.2</li>
        </ul>
    </li>
    <li>Menu item 2</li>
</ul>

Idea and initial code contributed by Uwe Mindrup.

Class Trees for HTML_Menu_DirectTreeRenderer

  • HTML_Menu_Renderer

    • HTML_Menu_DirectTreeRenderer

HTML_Menu_DirectTreeRenderer Inherited Methods

Inherited from HTML_Menu_Renderer
Method Name | Summary
HTML_Menu_Renderer::finishLevel() | Finish the tree level (for types 'tree' and 'sitemap')
HTML_Menu_Renderer::finishMenu() | Finish the menu
HTML_Menu_Renderer::finishRow() | Finish the row in the menu
HTML_Menu_Renderer::renderEntry() | Renders the element of the menu
HTML_Menu_Renderer::setMenuType() | Sets the type of the menu being rendered.
Prev | HTML_Menu | Next
DirectRenderer::toHtml() | PEAR Manual | DirectTreeRenderer::setEntryTemplate()


DirectTreeRenderer::setEntryTemplate()

DirectTreeRenderer::setEntryTemplate()

DirectTreeRenderer::setEntryTemplate() – Sets the template for menu entry.

Synopsis

require_once 'HTML/Menu/DirectTreeRenderer.php';

void HTML_Menu_DirectTreeRenderer::setEntryTemplate ( mixed $type , string $template = null )

Description

The template should contain at least the {title} placeholder, can also contain {url} placeholder. Default templates are:

<?php
array(
    HTML_MENU_ENTRY_INACTIVE    => '<a href="{url}">{title}</a>',
    HTML_MENU_ENTRY_ACTIVE      => '<strong>{title}</strong>',
    HTML_MENU_ENTRY_ACTIVEPATH  => '<a href="{url}"><em>{title}</em></a>'
);
?>

If custom keys are present in the original menu structure, they will be assigned to the corresponding placeholders.

Parameter

mixed $type

either type (one of HTML_MENU_ENTRY_* constants) or an array 'type' => 'template'

string $template

template for this entry type if $type is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_Menu_DirectTreeRenderer | PEAR Manual | DirectTreeRenderer::setItemTemplate()


DirectTreeRenderer::setItemTemplate()

DirectTreeRenderer::setItemTemplate()

DirectTreeRenderer::setItemTemplate() – Sets the item template (HTML that wraps around entries)

Synopsis

require_once 'HTML/Menu/DirectTreeRenderer.php';

void HTML_Menu_DirectTreeRenderer::setRowTemplate ( string $prepend , string $append )

Description

These are the strings that will be prepended and appended to HTML generated for menu entries. Defaults are

'<li>'

and

'</li>'

Parameter

string $prepend

this will be prepended to the entries HTML

string $append

this will be appended to the entries HTML

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
DirectTreeRenderer::setEntryTemplate() | PEAR Manual | DirectTreeRenderer::setLevelTemplate()


DirectTreeRenderer::setLevelTemplate()

DirectTreeRenderer::setLevelTemplate()

DirectTreeRenderer::setLevelTemplate() – Sets the level template (HTML that wraps around the submenu)

Synopsis

require_once 'HTML/Menu/DirectTreeRenderer.php';

void HTML_Menu_DirectTreeRenderer::setLevelTemplate ( string $prepend , string $append )

Description

These are the strings that will be prepended and appended to HTML generated for menu level. Defaults are

'<ul>'

and

'</ul>'

Parameter

string $prepend

this will be prepended to the rows HTML

string $append

this will be appended to the rows HTML

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
DirectTreeRenderer::setItemTemplate() | PEAR Manual | DirectTreeRenderer::toHtml()


DirectTreeRenderer::toHtml()

DirectTreeRenderer::toHtml()

DirectTreeRenderer::toHtml() – returns the HTML generated for the menu

Synopsis

require_once 'HTML/Menu/DirectTreeRenderer.php';

string HTML_Menu_DirectTreeRenderer::toHtml ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
DirectTreeRenderer::setLevelTemplate() | PEAR Manual | Class Summary HTML_Menu_ArrayRenderer


Class Summary HTML_Menu_ArrayRenderer

Class Summary HTML_Menu_ArrayRenderer

Class Summary HTML_Menu_ArrayRenderer – The renderer that creates an array of visible menu entries.

Output array

The resultant array can be used with e.g. a template engine to produce a completely custom menu look.

All menu types except 'rows' are "rendered" into a one-dimensional array of entries:

<?php
array(
    'entry1',
    ...
    'entryN'
)
?>

while 'rows' produce a two-dimensional array:

<?php
array(
    array('entry 1 for row 1', ..., 'entry M_1 for row 1'),
    ...
    array('entry 1 for row N', ..., 'entry M_N for row 1')
 )
?>

Here entry is

<?php
array(
    'url'    => url element of menu entry
    'title'  => title element of menu entry
    'level'  => entry's depth in the tree structure
    'type   => type of entry, one of HTML_MENU_ENTRY_* constants
 )
?>

A list of the above mentioned HTML_MENU_ENTRY_* constants can be found here.

Class Trees for HTML_Menu_ArrayRenderer

  • HTML_Menu_Renderer

    • HTML_Menu_ArrayRenderer

HTML_Menu_ArrayRenderer Inherited Methods

Inherited from HTML_Menu_Renderer
Method Name | Summary
HTML_Menu_Renderer::finishLevel() | Finish the tree level (for types 'tree' and 'sitemap')
HTML_Menu_Renderer::finishMenu() | Finish the menu
HTML_Menu_Renderer::finishRow() | Finish the row in the menu
HTML_Menu_Renderer::renderEntry() | Renders the element of the menu
HTML_Menu_Renderer::setMenuType() | Sets the type of the menu being rendered.
Prev | HTML_Menu | Next
DirectTreeRenderer::toHtml() | PEAR Manual | ArrayRenderer::toArray()


ArrayRenderer::toArray()

ArrayRenderer::toArray()

ArrayRenderer::toArray() – returns the resultant array

Synopsis

require_once 'HTML/Menu/ArrayRenderer.php';

array HTML_Menu_ArrayRenderer::toArray ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_Menu_ArrayRenderer | PEAR Manual | Class Summary HTML_Menu_SigmaRenderer


Class Summary HTML_Menu_SigmaRenderer

Class Summary HTML_Menu_SigmaRenderer

Class Summary HTML_Menu_SigmaRenderer – The renderer that uses HTML_Template_Sigma instance for menu output.

Description

This renderer uses HTML_Template_Sigma for actual HTML generation. This will allow you to easily plug HTML_Menu into your site's structure if you are using this template engine.

The renderer offers more possibilites for output customization than HTML_Menu_DirectRenderer.

The renderer may also work with HTML_Template_IT instance, but as menu templates tend to have lots of blocks, HTML_Template_Sigma's cache feature will give a significant performance improvement.

Template structure

This minimal template will allow output of any available menu type:

<!-- BEGIN mu_menu_loop -->
<table cellpadding="2" cellspacing="0" border="1">
    <!-- BEGIN mu_row_loop -->
    <tr>
        <!-- BEGIN mu_entry_loop -->
        <!-- BEGIN mu_inactive -->
        <td><!-- BEGIN mu_inactive_indent -->&nbsp;&nbsp;<!-- END mu_inactive_indent --><a href="{mu_url}">{mu_title}</a></td>
        <!-- END mu_inactive -->
        <!-- BEGIN mu_active -->
        <td><!-- BEGIN mu_active_indent -->&nbsp;&nbsp;<!-- END mu_active_indent --><strong>{mu_title}</strong></td>
        <!-- END mu_active -->
        <!-- BEGIN mu_activepath -->
        <td><!-- BEGIN mu_activepath_indent -->&nbsp;&nbsp;<!-- END mu_activepath_indent --><a href="{mu_url}"><strong>{mu_title}</strong></a></td>
        <!-- END mu_activepath -->
        <!-- BEGIN mu_previous -->
        <td><a href="{mu_url}">&lt;&lt;&lt; {mu_title}</a></td>
        <!-- END mu_previous -->
        <!-- BEGIN mu_next -->
        <td><a href="{mu_url}">{mu_title} &gt;&gt;&gt;</a></td>
        <!-- END mu_next -->
        <!-- BEGIN mu_upper -->
        <td><a href="{mu_url}">^ {mu_title} ^</a></td>
        <!-- END mu_upper -->
        <!-- BEGIN mu_breadcrumb -->
        <td><a href="{mu_url}">{mu_title}</a> &gt;&gt;&gt;</td>
        <!-- END mu_breadcrumb -->
        <!-- END mu_entry_loop -->
    </tr>
    <!-- END mu_row_loop -->
</table>
<!-- END mu_menu_loop -->

A more complete example showing possible customizations can be found in the package archive.

Note that blocks and placeholders in the template have mu_ prefix. This is done to prevent name conflicts with existing blocks and placeholders, mu_ is the default prefix, another prefix can be passed to class constructor.

menu_loop

If present, this block will be parse()'d after outputting the current menu or (in case of 'rows' type) current menu level. If menu type is 'rows' and %level%_menu_loop block is present, it will be parse()'d instead.

row_loop

If present, this block will be parse()'d after outputting the current menu row. If menu type is 'rows' and %level%_row_loop block is present, it will be parse()'d instead.

entry_loop

This block should always be present and should be a parent for all menu entries' blocks. It is used to implement "flow", to render entries one after another.

If menu type is 'rows' and %level%_entry_loop block is present, it will be used instead.

inactive, active, activepath, previous, next, upper, breadcrumb

These blocks are used to output menu entries, they correspond to possible entry types. Each block should contain a {title} placeholder and may also contain {url} placeholder and indent block

If menu type is either of 'tree', 'sitemap' or 'rows' and %level%_%entry type% block exists, it will be used instead.

inactive_indent, active_indent, activepath_indent

If present, these blocks are used to indent the entries inside tree-type menus ('tree' and 'sitemap').

Class Trees for HTML_Menu_SigmaRenderer

  • HTML_Menu_Renderer

    • HTML_Menu_SigmaRenderer

HTML_Menu_SigmaRenderer Inherited Methods

Inherited from HTML_Menu_Renderer
Method Name | Summary
HTML_Menu_Renderer::finishLevel() | Finish the tree level (for types 'tree' and 'sitemap')
HTML_Menu_Renderer::finishMenu() | Finish the menu
HTML_Menu_Renderer::finishRow() | Finish the row in the menu
HTML_Menu_Renderer::renderEntry() | Renders the element of the menu
HTML_Menu_Renderer::setMenuType() | Sets the type of the menu being rendered.
Prev | HTML_Menu | Next
ArrayRenderer::toArray() | PEAR Manual | constructor HTML_Menu_SigmaRenderer()


constructor HTML_Menu_SigmaRenderer()

constructor HTML_Menu_SigmaRenderer()

constructor HTML_Menu_SigmaRenderer() – Class constructor.

Synopsis

require_once 'HTML/Menu/SigmaRenderer.php';

void constructor HTML_Menu_SigmaRenderer::HTML_Menu_SigmaRenderer ( object HTML_Template_Sigma &$tpl , string $prefix = 'mu_' )

Description

Sets the template object to use and sets prefix for template blocks and placeholders. We use prefix to avoid name collisions with existing template blocks and it is customisable to allow output of several menus into one template.

Parameter

object HTML_Template_Sigma &$tpl

template object to use for output

string $prefix

prefix for template blocks and placeholders

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_Menu_SigmaRenderer | PEAR Manual | Class Summary HTML_Menu_SigmaTreeRenderer


Class Summary HTML_Menu_SigmaTreeRenderer

Class Summary HTML_Menu_SigmaTreeRenderer

Class Summary HTML_Menu_SigmaTreeRenderer – HTML_Template_Sigma-based renderer for 'tree' and 'sitemap' type menus, where menu level is represented by tag nesting.

Description

The renderer generates outpu similar to that of HTML_Menu_DirectTreeRenderer but offers more possibilites for output customization.

The renderer may also work with HTML_Template_IT instance, but as menu templates tend to have lots of blocks, HTML_Template_Sigma's cache feature will give a significant performance improvement.

Template structure

This is the minimal template for HTML_Menu_SigmaTreeRenderer, containing all the required blocks:

<!-- BEGIN mu_tree_loop -->
    <!-- BEGIN mu_level_open -->
<ul>
    <!-- END mu_level_open -->
        <!-- BEGIN mu_entry_open -->
    <li>
        <!-- END mu_entry_open -->
        <!-- BEGIN mu_active -->
    <strong>{mu_title}</strong>
        <!-- END mu_active -->
        <!-- BEGIN mu_inactive -->
    <a href="{mu_url}">{mu_title}</a>
        <!-- END mu_inactive -->
        <!-- BEGIN mu_activepath -->
    <a href="{mu_url}"><em>{mu_title}</em></a>
        <!-- END mu_activepath -->
        <!-- BEGIN mu_entry_close -->
    </li>
        <!-- END mu_entry_close -->
    <!-- BEGIN mu_level_close -->
</ul>
    <!-- END mu_level_close -->
<!-- END mu_tree_loop -->

A more complete example showing possible customizations can be found in the package archive.

Note that blocks and placeholders in the template have mu_ prefix. This is done to prevent name conflicts with existing blocks and placeholders, mu_ is the default prefix, another prefix can be passed to class constructor.

tree_loop

This block should always be present and should be a parent for all other blocks. It is used to implement "flow", to render entries one after another.

level_open, level_close

These blocks will be used on start and end of each menu level. If level-specific blocks %level%_level_open and %level%_level_close are present, they will be used instead.

entry_open, entry_close

These blocks will be used on start and end of each menu entry. If level-specific blocks %level%_entry_open and %level%_entry_close are present, they will be used instead.

inactive, active, activepath

These blocks are used to output menu entries, they correspond to possible entry types. Each block should contain a {title} placeholder and may also contain {url} placeholder. As usual, if other keys are present in original menu array they will be assigned to corresponding placeholders in the template.

If level-specific block %level%_%entry type% exists, it will be used instead.

Class Trees for HTML_Menu_SigmaTreeRenderer

  • HTML_Menu_Renderer

    • HTML_Menu_SigmaTreeRenderer

HTML_Menu_SigmaTreeRenderer Inherited Methods

Inherited from HTML_Menu_Renderer
Method Name | Summary
HTML_Menu_Renderer::finishLevel() | Finish the tree level (for types 'tree' and 'sitemap')
HTML_Menu_Renderer::finishMenu() | Finish the menu
HTML_Menu_Renderer::finishRow() | Finish the row in the menu
HTML_Menu_Renderer::renderEntry() | Renders the element of the menu
HTML_Menu_Renderer::setMenuType() | Sets the type of the menu being rendered.
Prev | HTML_Menu | Next
constructor HTML_Menu_SigmaRenderer() | PEAR Manual | constructor HTML_Menu_SigmaTreeRenderer()


constructor HTML_Menu_SigmaTreeRenderer()

constructor HTML_Menu_SigmaTreeRenderer()

constructor HTML_Menu_SigmaTreeRenderer() – Class constructor.

Synopsis

require_once 'HTML/Menu/SigmaTreeRenderer.php';

void constructor HTML_Menu_SigmaTreeRenderer::HTML_Menu_SigmaTreeRenderer ( object HTML_Template_Sigma &$tpl , string $prefix = 'mu_' )

Description

Sets the template object to use and sets prefix for template blocks and placeholders. We use prefix to avoid name collisions with existing template blocks and it is customisable to allow output of several menus into one template.

Parameter

object HTML_Template_Sigma &$tpl

template object to use for output

string $prefix

prefix for template blocks and placeholders

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_Menu_SigmaTreeRenderer | PEAR Manual | Class Summary HTML_MenuBrowser


Class Summary HTML_MenuBrowser

Class Summary HTML_MenuBrowser

Class Summary HTML_MenuBrowser – Simple filesystem browser that can be used to generated menu (3) hashes based on the directory structure.

Simple filesystem browser that can be used to generated menu (3) hashes based on the directory structure.

Together with menu (3) and the (userland) cache you can use this browser to generate simple fusebox like applications / content systems.

Let the menubrowser scan your document root and generate a menu (3) structure hash which maps the directory structure, pass it to menu's setMethod() and optionally wrap the cache around all this to save script runs. If you do so, it looks like this:

// document root directory define('DOC_ROOT', '/home/server/www.example.com/');

// instantiate the menubrowser $browser = new menubrowser(DOC_ROOT);

// instantiate menu (3) $menu = new menu($browser->getMenu());

// output the sitemap $menu->show('sitemap');

Now, use e.g. simple XML files to store your content and additional menu informations (title!). Subclass exploreFile() depending on your file format.

Class Trees for HTML_MenuBrowser

  • HTML_MenuBrowser

Prev | HTML_Menu | Next
constructor HTML_Menu_SigmaTreeRenderer() | PEAR Manual | constructor HTML_MenuBrowser::HTML_MenuBrowser()


constructor HTML_MenuBrowser::HTML_MenuBrowser()

constructor HTML_MenuBrowser::HTML_MenuBrowser()

constructor HTML_MenuBrowser::HTML_MenuBrowser() – Creates the object and optionally sets the directory to scan.

Synopsis

require_once 'HTML/MenuBrowser.php';

 void      constructor HTML_MenuBrowser::HTML_MenuBrowser (
 string  $dir = ''
  , string  $index = ''
  , string  $file_suffix = ''
)

Description

This package is not documented yet.

Parameter

string $dir

Directory to scan

string $index

Filename of index pages

string $file_suffix

Suffix for files containing the additional data

Throws

throws no exceptions thrown

See

see HTML_MenuBrowser::$dir

Note

This function can not be called statically.

Prev | HTML_Menu | Next
Class Summary HTML_MenuBrowser | PEAR Manual | HTML_MenuBrowser::addFileInfo()


HTML_MenuBrowser::addFileInfo()

HTML_MenuBrowser::addFileInfo()

HTML_MenuBrowser::addFileInfo() – Adds further informations to the menu hash gathered from the files in it

Synopsis

require_once 'HTML/MenuBrowser.php';

array HTML_MenuBrowser::addFileInfo ( mixed $menu )

Description

This package is not documented yet.

Parameter

mixed $menu

Return value

returns Modified menu hash with the new informations

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
constructor HTML_MenuBrowser::HTML_MenuBrowser() | PEAR Manual | HTML_MenuBrowser::browse()


HTML_MenuBrowser::browse()

HTML_MenuBrowser::browse()

HTML_MenuBrowser::browse() – Recursive function that does the scan and builds the menu (3) hash.

Synopsis

require_once 'HTML/MenuBrowser.php';

array HTML_MenuBrowser::browse ( string $dir , integer $id = 0 , boolean $noindex = false )

Description

This package is not documented yet.

Parameter

string $dir

directory to scan

integer $id

entry id - used only for recursion

boolean $noindex

??? - used only for recursion

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_MenuBrowser::addFileInfo() | PEAR Manual | HTML_MenuBrowser::exploreFile()


HTML_MenuBrowser::exploreFile()

HTML_MenuBrowser::exploreFile()

HTML_MenuBrowser::exploreFile() – Returns additional menu informations decoded in the file that appears in the menu.

Synopsis

require_once 'HTML/MenuBrowser.php';

void HTML_MenuBrowser::exploreFile ( string $file )

Description

You should subclass this method to make it work with your own file formats. I used a simple XML format to store the content.

Parameter

string $file

filename

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_MenuBrowser::browse() | PEAR Manual | HTML_MenuBrowser::getMenu()


HTML_MenuBrowser::getMenu()

HTML_MenuBrowser::getMenu()

HTML_MenuBrowser::getMenu() – Returns a hash to be used with menu(3)'s setMenu().

Synopsis

require_once 'HTML/MenuBrowser.php';

 void      HTML_MenuBrowser::getMenu (
 string  $dir = ''
  , string  $prefix = ''
)

Description

This package is not documented yet.

Parameter

string $dir

directory to scan

string $prefix

id prefix

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_MenuBrowser::exploreFile() | PEAR Manual | HTML_MenuBrowser::setDirectory()


HTML_MenuBrowser::setDirectory()

HTML_MenuBrowser::setDirectory()

HTML_MenuBrowser::setDirectory() – Sets the directory to scan.

Synopsis

require_once 'HTML/MenuBrowser.php';

void HTML_MenuBrowser::setDirectory ( string $dir )

Description

This package is not documented yet.

Parameter

string $dir

directory to scan

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_MenuBrowser::getMenu() | PEAR Manual | HTML_MenuBrowser::setIDPrefix()


HTML_MenuBrowser::setIDPrefix()

HTML_MenuBrowser::setIDPrefix()

HTML_MenuBrowser::setIDPrefix() – Sets the prefix for every id in the menu hash.

Synopsis

require_once 'HTML/MenuBrowser.php';

void HTML_MenuBrowser::setIDPrefix ( string $prefix )

Description

This package is not documented yet.

Parameter

string $prefix

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Menu | Next
HTML_MenuBrowser::setDirectory() | PEAR Manual | Package HTML_Menu Constants


Package HTML_Menu Constants

Package HTML_Menu Constants

Package HTML_Menu Constants – Constants defined in and used by HTML_Menu

All Constants

Constants defined in Menu.php

Constants defined in Menu.php
Name | Value | Line Number | Meaning
HTML_MENU_ENTRY_ACTIVE | 1 | 26 | Active menu entry, the one having the current URL as 'url' attribute
HTML_MENU_ENTRY_ACTIVEPATH | 2 | 27 | Ancestor of the active menu entry
HTML_MENU_ENTRY_BREADCRUMB | 6 | 31 | Ancestor of the active menu entry, for menu type 'urhere'
HTML_MENU_ENTRY_INACTIVE | 0 | 25 | Default menu entry
HTML_MENU_ENTRY_NEXT | 4 | 29 | "Next" menu entry (for menu type 'prevnext')
HTML_MENU_ENTRY_PREVIOUS | 3 | 28 | "Previous" menu entry (for menu type 'prevnext')
HTML_MENU_ENTRY_UPPER | 5 | 30 | "Up" menu entry (for menu type 'prevnext')
Prev | HTML_Menu | Next
HTML_MenuBrowser::setIDPrefix() | PEAR Manual | HTML_Page2


HTML_Page2

HTML_Page2

API to create HTML Pages

Table of Contents
  • Creation -- Making a new page
  • Headers -- Setting title and other meta data
  • Body -- Adding content
  • Output -- Finishing the page
Prev | HTML | Next
Package HTML_Menu Constants | PEAR Manual | Creation


Creation

Creation

Creation – Making a new page

Description

A HTML page is created by instantiating a new HTML_Page2 object. While you may pass an array of attributes to the constructor, it isn't required since the default settings are fairly intuitive.

  • Unix line endings (\n)

  • UTF-8 charset

  • text/html MIME type

  • XHTML 1.0 Transitional doctype

  • English language

If you don't like these settings, you can either pass an array of settings to the constructor or use setter methods such as setDoctype(), setMimeEncoding() or setCharset() .

Creating a HTML page

<?php
require_once 'HTML/Page2.php';
$page = new HTML_Page2();
$page->setTitle('My first HTML page');
$page->addBodyContent('<h1>Hello!</h1>');
$page->display();
?>
Prev | HTML_Page2 | Next
HTML_Page2 | PEAR Manual | Headers


Headers

Headers

Headers – Setting title and other meta data

Setting headers

The method you surely will use is setTitle() that sets the title of the page; the one that your browser displays in its title/window bar.

<?php
$page->setTitle('My first HTML page');
?>

Meta tags can be set with setMetaData() which takes two parameters, the tag name and the content.

<?php
$page->setMetaData('author', 'Christian Weiske');
?>

A link to a bookmark icon (favicon) can be set using addFavicon() .

Links to related pages (previous, next, home etc.) are added with addHeadLink() - the first parameter determines the URL, the second the relation.

<?php
$page->addHeadLink('home.htm', 'Start');
?>

Adding CSS - Cascading stylesheets

A HTML page may contain two types of stylesheets: Inline css and a link to external .css file.

Inline CSS declarations are made with addStyleDeclaration()

<?php
$page->addStyleDeclaration('
div.block {
    border: 1px solid #000;
}
');
?>

Links to external CSS files are created by using addStyleSheet(). The optional third parameter determines which media type the stylesheet shall be used for.

<?php
$page->addStyleSheet('css/dark.css');
$page->addStyleSheet('css/print.css', 'text/css', 'print');
?>

Adding scripts

You may want to add some javascript code to your page; either inline or link to an external .js file.

Inline code blocks are added with addScriptDeclaration() . The optional second parameter defaults to text/javascript but can be changed as needed.

<?php
$page->addScriptDeclaration('
function javaScriptTest() {
    alert("Test");
}
');
?>

Links to external script files are created by using addScript().

<?php
$page->addScript('js/functions.js');
?>
Prev | HTML_Page2 | Next
Creation | PEAR Manual | Body


Body

Body

Body – Adding content

Description

After creating the page and setting headers, you want to add actual content to the page. The method in charge is addBodyContent().

By default, if content already exists, the new content is appended. If you wish to overwrite whatever is in the body, use setBody(); unsetBody() completely empties the body without inserting new content. You can also use prependBodyContent() to prepend content to whatever is currently in the array of body elements.

The following constants are defined to be passed as the flag attribute: HTML_PAGE2_APPEND, HTML_PAGE2_PREPEND and HTML_PAGE2_REPLACE. Their usage should be quite clear from their names.

<?php
$page->addBodyContent('<h1>Hello!</h1>');
$page->addBodyContent('<p>This is a paragraph.</p>');
?>
Prev | HTML_Page2 | Next
Headers | PEAR Manual | Output


Output

Output

Output – Finishing the page

Description

After adding all the headers and content to the page, you want to get the page to the user. display() directly echoes the page to the browser.

If you want to do something with the result page before pushing it to the browser, use toHtml() . It returns the page as string that can be modified further.

<?php
//push it to the browser
$page->display();
//or put it into a variable
$html = $page->toHtml();
?>
Prev | HTML_Page2 | Next
Body | PEAR Manual | HTML_Progress


HTML_Progress

HTML_Progress

This package has been superseded. Please use HTML_Progress2 for new projects.

Prev | HTML | Next
Output | PEAR Manual | HTML_Progress2


HTML_Progress2

HTML_Progress2

How to include a loading bar in your XHTML documents quickly and easily

Table of Contents
  • Introduction -- A feature overview
Prev | HTML | Next
HTML_Progress | PEAR Manual | Introduction


Introduction

Introduction

Introduction – A feature overview

Description

HTML_Progress2 is designed to display a loading bar in your XHTML documents during a long process. Progress bar may be synchronous (COMET) or asynchronous (AJAX).

Features

  • create horizontal, vertival bar and also circle, ellipse and polygons (square, rectangle)

  • allows usage of existing external StyleSheet and/or JavaScript

  • all elements (progress, cells, labels) are customizable by their html properties

  • percent/labels are floating all around the progress meter

  • compliant with all CSS/XHMTL standards

  • integration with all template engines is very easy

  • implements Observer design pattern. It is possible to add Listeners

  • adds a customizable monitor pattern to display a progress bar. User-end can abort progress at any time

  • allows many progress meter on same page without uses of iframe solution

  • error handling system that support native PEAR_Error, but also PEAR_ErrorStack, and any other system you might want to plug-in.

External support resources

  • external documentation ( full user guide )

  • Download page to get the full definitive guide. Three formats available : single HTML page, many HTML pages, Windows HTML help.

Prev | HTML_Progress2 | Next
HTML_Progress2 | PEAR Manual | HTML_QuickForm


HTML_QuickForm

HTML_QuickForm

The PEAR::HTML_QuickForm package provides methods for creating, validating and processing HTML forms.

Table of Contents
  • Introduction
  • Creating a basic form
  • Classes representing form elements
  • Using groups
  • Working with elements' values
  • Outputting the form
Prev | HTML | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Table of Contents
  • QuickStart -- A tutorial for HTML_QuickForm
  • QuickHelp -- Answers to most Frequently Asked Questions
  • QuickForm element types -- What elements can be added to QuickForm
  • Migration to version 3.2 -- API changes to observe
  • Subpackages -- An overview about subpackages and packages that use QuickForm

QuickForm is a convenience library for dealing with HTML forms. It provides Javascript and server-side form validation, and is customizable and extensible in many ways. QuickForm consists of multiple files. The main file is QuickForm.php and should be installed in your pear/HTML directory. The other important files are element.php, which handles all methods relative to form elements, and group.php, which deals with methods relative to groups of elements in the form. Both are located in your HTML/QuickForm directory along with the other form objects. input.php contains a common class for all the elements of input type (text, password...). QuickForm has objects for all the common form elements: select, text, password, checkbox, file, submit, reset, button, image, radio, hidden, textarea. QuickForm provides the possibility to create your own elements as long as you comply with the common API.

Prev | HTML_QuickForm | Next
HTML_QuickForm | PEAR Manual | QuickStart


QuickStart

QuickStart

QuickStart – A tutorial for HTML_QuickForm

Introduction

The purpose of this tutorial is to give the new users of QuickForm an overview of its features and usage patterns. It describes a small subset of available functionality, but points to the parts of the documentation that give a more in-depth overview.

There also exists a somewhat bigger tutorial on QuickForm usage made by Keith Edmunds.

Your first form

Basic QuickForm usage

<?php
// Load the main class
require_once 'HTML/QuickForm.php';

// Instantiate the HTML_QuickForm object
$form = new HTML_QuickForm('firstForm');

// Set defaults for the form elements
$form->setDefaults(array(
    'name' => 'Joe User'
));

// Add some elements to the form
$form->addElement('header', null, 'QuickForm tutorial example');
$form->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, 'Send');

// Define filters and validation rules
$form->applyFilter('name', 'trim');
$form->addRule('name', 'Please enter your name', 'required', null, 'client');

// Try to validate a form
if ($form->validate()) {
    echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</h1>';
    exit;
}

// Output the form
$form->display();
?>

Lets review this example step by step.

Building the form

The line

<?php
$form = new HTML_QuickForm('firstForm');
?>

creates a HTML_QuickForm object that will contain the objects representing elements and all the other necessary information. We only pass the form's name to the constructor, which means that default values will be used for other parameters. In particular, the form's method will default to POST and the form's action to the current file. When using QuickForm, it is easier to keep all the form related logic in one file.

You might guess that

<?php
$form->setDefaults(array(
    'name' => 'Joe User'
));
?>

sets the default value for name element to 'Joe User'. QuickForm has the concept of default values (set via setDefaults() method) and constant ones (set via setConstants()). The difference between them is that user's input overrides default values but not constant ones.

Our form will consist of three elements:

<?php
$form->addElement('header', null, 'QuickForm tutorial example');
$form->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
$form->addElement('submit', null, 'Send');
?>

The first one is not the 'real' element, it is just a heading to improve presentation. The second one actually is a text input box and the third is a submit button. Note that parameters for addElement() method have different meanings for different elements. That is so because they are actually passed to these elements' constructors.

Checking input

The line

<?php
$form->applyFilter('name', 'trim');
?>

defines a filter for the 'name' element value - the function that will be applied to it after form submit. In this case it is a builtin trim() function, but can be any valid callback. Thus we will strip all whitespace from the name, as we do not actually need it and as we want to be sure that a name was entered, not just some spaces.

Next we define a rule for the name field:

<?php
$form->addRule('name', 'Please enter your name', 'required', null, 'client');
?>

This means that QuickForm will display an error message if the name was not entered. The 'client' modifier is here to switch on client-side JavaScript validation in addition to server-side one. Note also that QuickForm will automatically mark required fields in the form.

Validating and processing

We now have the form built and rules defined and need to decide whether to process it or display:

<?php
if ($form->validate()) {
    // Do some stuff
}
?>

The validate() method will consider the form valid (i.e. return TRUE) if some data was actually submitted and all the rules defined for the form were satisfied. In our case this means that 'name' element was not empty.

If the form is validated we need to process the values

<?php
echo '<h1>Hello, ' . htmlspecialchars($form->exportValue('name')) . '!</h1>';
exit;
?>

This is an example, in your scripts you'll usually want to store the values somewhere and to redirect to some other page to prevent a duplicate submit. The process() and exportvalues() methods may be of interest here.

The last line is pretty easy:

<?php
$form->display();
?>

If the form is not valid, which means that it either was not yet submitted or that there were errors, it will be displayed. Error messages (if any) will be displayed near the corresponding elements.

Advanced features

You now should have an understanding of basic QuickForm functionality, but there are many more features in the package, each of them deserving a separate tutorial. This section will give a short overview of them and point you to the complete documentation.

Groups allow to combine several individual elements into one entity and to use it as one element. This is also used to create pseudo-elements like date and hierselect.

QuickForm offers a lot of possibilities to customize form layout and appearance. Form output is done via renderers - special classes containing necessary logic. There are renderers that directly output HTML and those that use template engines for this.

And finally, you can extend QuickForm by adding your own element types, rules and renderers.

Prev | Introduction | Next
Introduction | PEAR Manual | QuickHelp


QuickHelp

QuickHelp

QuickHelp – Answers to most Frequently Asked Questions

Description

This document is based on questions asked on PEAR general mailing list. You are encouraged to search the list archives to find more verbose answers and examples.

HTML_QuickForm FAQ

    The forms I generate with HTML_QuickForm cannot be submitted. When I look at the page's HTML source, I see something like <formArray>.

    Recent versions of HTML_QuickForm package require HTML_Common package version 1.2.1 (CVS revision 1.8 in HTML/Common.php) to work properly. If (and only if) an older version of HTML_Common is loaded, these symptoms occur.

    Please note that

$ pear list

    command may tell you that you have HTML_Common 1.2.1 installed. In this case you also have an older version of HTML_Common somewhere and are including it instead of the proper one. Check your include_path setting in php.ini and/or use PHP's get_included_files() function to find out which file you are really including.

    When I pass some GET parameters to the script containing a form, QuickForm thinks that the form was already submitted, displaying validation errors.

    Constructor of HTML_QuickForm accepts a $trackSubmit parameter. Setting this to TRUE will make QuickForm check whether the form was actually submitted. This also helps if you have several forms defined on one page.

    How do I set default/constant values for 'date' element?

    Date element is essentially a group of selects, you define the structure of this group in the 'format' option when creating the element:

    <?php
    $form    ->addElement('date', 'foo', 'The date:', array('format' => 'Y m d'));
    ?>

    Thus you pass the defaults as an array, just like you do with any other group:

    <?php
    $form    ->setDefaults(array(
            'foo' => array('Y' => 2004, 'm' => 9, 'd' => 29)
    ));
    ?>

    To ease using it with database-backed applications, date element also accepts Unix timestamps (generated by mktime()) and strings. The strings are processed by strtotime() functions, so consider its limitations.

    I receive weird "Call to a member function on a non-object" or "Undefined function" errors, especially when dealing with groups.

    These errors tend to appear when you have something which is not a HTML_QuickForm_element in the $elements array passed to addGroup(). This "something" is usually either a PEAR_Error instance (check for these or setup a handler) or, if register_globals is switched on in php.ini, some submitted values (clear the array before adding elements to it).

    QuickForm generates code which does not validate as XHTML Strict!

    QuickForm does add a 'name' attribute to the <form> tag, which is invalid in XHTML Strict. Quickform does not depend on that attribute since release 3.2.2, and it's only kept for backwards compatibility. If you desire XHTML Strict compliance and your code does not depend on said attribute, you can remove it via removeAttribute() method.

    The 'required' rule does not work for my elements!

    • If your element is a file upload, you should use 'uploadedfile' rule instead.

    • If your element is a group, you should use addGroupRule() method instead of addRule(). This applies to group-based elements like 'date' and 'hierselect' as well.

    How do I change * denotes required field and Invalid information entered. / Please correct these fields. validation messages?

    You should use setRequiredNote() and setJsWarnings() methods, respectively.

    Prev | Introduction | Next
QuickStart | PEAR Manual | QuickForm element types


QuickForm element types

QuickForm element types

QuickForm element types – What elements can be added to QuickForm

Elements overview

As of release 3.2.5, HTML_QuickForm knows 23 element types that can be created via createElement() and added to the form via addElement(). These can be divided into two big groups: standard HTML elements and custom elements.

'button'

Class for <input type="button" /> elements, HTML_QuickForm_button

'checkbox'

Class for <input type="checkbox" /> elements, HTML_QuickForm_checkbox

'file'

Class for <input type="file" /> elements, HTML_QuickForm_file

'hidden'

Class for <input type="hidden" /> elements, HTML_QuickForm_hidden

'image'

Class for <input type="image" /> elements, HTML_QuickForm_image

'password'

Class for <input type="password" /> elements, HTML_QuickForm_password

'radio'

Class for <input type="radio" /> elements, HTML_QuickForm_radio

'reset'

Class for <input type="reset" /> elements, HTML_QuickForm_reset

'select'

Class for <select> elements, HTML_QuickForm_select. The class allows loading of <option> elements from array or database.

'submit'

Class for <input type="submit" /> elements, HTML_QuickForm_submit

'text'

Class for <input type="text" /> elements, HTML_QuickForm_text

'textarea'

Class for <textarea> elements, HTML_QuickForm_textarea

'xbutton'

Class for <button> elements, HTML_QuickForm_xbutton

'advcheckbox'

Class for an advanced checkbox type field, HTML_QuickForm_advcheckbox. Basically this fixes a problem that HTML has had where checkboxes can only pass a single value (the value of the checkbox when checked).

'autocomplete'

Class for a text field with autocompletion feature, HTML_QuickForm_autocomplete. The element looks like a normal HTML input text element that at every keypressed javascript event, searches the array of options for a match and autocompletes the text in case of match.

'date'

Class for a group of elements used to input dates (and times), HTML_QuickForm_date

'group'

Class for a form element group, HTML_QuickForm_group. QuickForm allows grouping of several elements into one entity and using this entity as a new element.

'header'

Class for adding headers to the form, HTML_QuickForm_header

'hiddenselect'

This class, HTML_QuickForm_hiddenselect, behaves as a select element, but instead of creating a <select> it creates hidden elements for all values already selected with setDefaults() or setConstants().

'hierselect'

Class to dynamically create "chained" HTML <select> elements, HTML_QuickForm_hierselect. Choosing an option in the first <select> changes the available options of the second select and so on.

'html'

Deprecated. A pseudo-element used for adding raw HTML to form, HTML_QuickForm_html. Intended for use with the default renderer only, template-based ones may (and probably will) completely ignore this.

'link'

Class for a link type field, HTML_QuickForm_link

'static'

Class for static data, HTML_QuickForm_static

Prev | Introduction | Next
QuickHelp | PEAR Manual | Migration to version 3.2


Migration to version 3.2

Migration to version 3.2

Migration to version 3.2 – API changes to observe

Why these changes?

HTML_QuickForm has improved a lot since version 2.x. With the addition of a new renderer layer, a lot of methods that were located in the main QuickForm class were actually duplicates of methods in the renderers. Those methods were kept to give user time to adjust their code. With release 3.2 they will be removed, making QuickForm class much lighter and consistent.

At the same time, file upload validation was moved to the file element as this is a more appropriate place.

Removed methods

  • QuickForm related

    • HTML_QuickForm::getAttributesString()

    • HTML_QuickForm::addElementGroup()

    • HTML_QuickForm::addHeader()

    • HTML_QuickForm::addData()

  • Renderer related

    • HTML_QuickForm::setElementTemplate()

    • HTML_QuickForm::setHeaderTemplate()

    • HTML_QuickForm::setFormTemplate()

    • HTML_QuickForm::setRequiredNoteTemplate()

    • HTML_QuickForm::clearAllTemplates()

    • HTML_QuickForm_group::setElementTemplate()

    • HTML_QuickForm_group::setGroupTemplate()

  • File upload related

    • HTML_QuickForm::isUploadedFile()

    • HTML_QuickForm::getUploadedFile()

    • HTML_QuickForm::moveUploadedFile()

How to adjust your code

QuickForm related

HTML_QuickForm::getAttributesString()

<?php
$form->getAttributes(true);
?>

will return the same value by using HTML_Common::getAttributes() method.

HTML_QuickForm::addElementGroup()

Arguments order was changed to conform to the way elements are usually added to QuickForm by addElement(). Use HTML_QuickForm::addGroup() instead and swap the element label with the element name.

HTML_QuickForm::addHeader()

A header is now considered like any other element. There is a new HTML_QuickForm_header element that extends HTML_QuickForm_static. Just use

<?php
$form->addElement('header', $header_name, $header_text);
?>

This will also allow you to customize the header rendering based on its name.

HTML_QuickForm::addData()

If you absolutely need this feature, use

<?php
$form->addElement('html', $data)
?>

or consider using some template-based renderer.

Renderer related

Those methods are now handled by the renderers. How to use these methods depends on your choice of renderer. With QuickForm default renderer, you can use these methods like that:

<?php
$form =& new HTML_QuickForm('myform');

$renderer =& $form->defaultRenderer();
$renderer->setFormTemplate('<table><form{attributes}>{content}</form></table>');
$renderer->setHeaderTemplate('<tr><td colspan="2"><b>{header}</b></td></tr>');
$renderer->setGroupTemplate('<table><tr>{content}</tr></table>');
$renderer->setGroupElementTemplate('<td>{element}<br /><!-- BEGIN required -->*<!-- END required -->{label}</td>');
?>

defaultRenderer()will return a reference to QuickForm integrated renderer. You can of course use any other renderer available in QuickForm such as Sigma, ITX, Smarty, Flexy and so on. Have a look at their documentation to see which methods are available for them.

File upload related

File-related methods and rules have been moved to the file element HTML_QuickForm_file because it makes more sense this way and you don't have to include upload-related code if you are not using uploads. You have access to these methods like that:

<?php
$form = new HTML_QuickForm('myform');
$file =& $form->addElement('file', 'myfile', 'Your file:');
$form->addRule('myfile', 'Cannot exceed 1776 bytes', 'maxfilesize', 1776);
if ($file->isUploadedFile()) {
    $file->moveUploadedFile('/tmp', 'testfile.txt');
}
?>

or like that:

<?php
$file =& $form->getElement('myfile');
if ($file->isUploadedFile()) {
     $fileInfo = $file->getValue();
}
?>
Prev | Introduction | Next
QuickForm element types | PEAR Manual | Subpackages


Subpackages

Subpackages

Subpackages – An overview about subpackages and packages that use QuickForm

Subpackages for HTML_QuickForm

This section describes the available subpackages for HTML_QuickForm, e.g. custom elements or renderers.

HTML_QuickForm_advmultiselect

A custom element that emulates via two select boxes a select box that allows selecting of multiple options.

HTML_QuickForm_DHTMLRulesTableless

If you use the Tableless renderer (see below, HTML_QuickForm_Renderer_Tableless), this subpackage replaces the default client-side validation with a JavaScript alert window by dynamic (using DHTML) error messages that are printed directly above each erroneous element. (documentation)

HTML_QuickForm_Livesearch

This is another custom element. It creates an HTML input text element that at every keypressed javascript event, returns a list of options in a dynamic dropdown select box (especially useful to emulate a select box with a huge number of options). This element uses the AJAX technology.

HTML_QuickForm_Renderer_Tableless

This is a replacement for the default renderer of HTML_QuickForm that uses only XHTML and CSS but no table tags, and generates fully valid XHTML output. (documentation)

HTML_QuickForm_SelectFilter

Another custom element that is used to define dynamic filters on the client-side for select elements.

More subpackages

There are some more subpackages available that were not yet proposed as PEAR packages. An example is a DHTMLRules subpackage for forms using the default renderer by Justin Patrin that was not yet proposed as a PEAR package.

Packages that use HTML_QuickForm

This section describes some packages that makes working with HTML_QuickForm easier, either in the case of working with databases or in the case of forms that have multiple pages.

DB_DataObject_FormBuilder

FormBuilder aids in rapid application development using the packages DB_DataObject and HTML_QuickForm. (documentation)

DB_Table

This is a package that builds on PEAR DB and MDB2 to abstract datatypes and automate table creation, data validation, insert, update, delete, and select. It combines these with HTML_QuickForm to automatically generate input forms that match the table column definitions. (documentation)

HTML_QuickForm_Controller

If you want to create forms with multiple pages, this is the right package for you. It is an implementation of a PageController pattern. (documentation)

More packages

You can find more packages that have optional or required dependencies on HTML_QuickForm on the package site.

Prev | Introduction | Next
Migration to version 3.2 | PEAR Manual | Creating a basic form


Creating a basic form

Creating a basic form

Table of Contents
  • constructor HTML_QuickForm::HTML_QuickForm() -- Class constructor
  • HTML_QuickForm::addElement() -- Adds an element into the form
  • HTML_QuickForm::apiVersion() -- Returns the current API version
  • HTML_QuickForm::createElement() -- Creates a new form element of the given type
  • HTML_QuickForm::elementExists() -- Checks if element is in the form
  • HTML_QuickForm::errorMessage() -- Returns an error message for error code
  • HTML_QuickForm::getElementType() -- Returns the type of an element
  • HTML_QuickForm::getElement() -- Returns a reference to the element
  • HTML_QuickForm::getMaxFileSize() -- Returns the value of MAX_FILE_SIZE hidden element
  • HTML_QuickForm::getRegisteredTypes() -- Returns registered element types
  • HTML_QuickForm::insertElementBefore() -- Inserts a new element right before the other element
  • HTML_QuickForm::isError() -- Tells whether a result is an error
  • HTML_QuickForm::isTypeRegistered() -- Checks whether the form element type is supported
  • HTML_QuickForm::registerElementType() -- Registers a new element type
  • HTML_QuickForm::removeElement() -- Removes an element
  • HTML_QuickForm::setMaxFileSize() -- Sets the value of MAX_FILE_SIZE hidden element
  • HTML_QuickForm::updateElementAttr() -- Updates Attributes for one or more elements

To be written.

Prev | HTML_QuickForm | Next
Subpackages | PEAR Manual | constructor HTML_QuickForm::HTML_QuickForm()


constructor HTML_QuickForm::HTML_QuickForm()

constructor HTML_QuickForm::HTML_QuickForm()

constructor HTML_QuickForm::HTML_QuickForm() – Class constructor

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::HTML_QuickForm ( string $formName = '' , string $method = 'post' , string $action = '' , string $target = '' , mixed $attributes = null , bool $trackSubmit = false )

Description

Constructor, sets <form> tag attributes and loads submitted values.

Parameter

string $formName

Form's name.

string $method

(optional) Form's method

string $action

(optional) Form's action

string $target

(optional) Form's target

mixed $attributes

(optional) Extra attributes for <form> tag

boolean $trackSubmit

(optional) Whether to track if the form was submitted by adding a special hidden field. If the name of such field is not present in the $_GET or $_POST values, the form will be considered as not submitted.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Creating a basic form | Next
Creating a basic form | PEAR Manual | HTML_QuickForm::addElement()


HTML_QuickForm::addElement()

HTML_QuickForm::addElement()

HTML_QuickForm::addElement() – Adds an element into the form

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::addElement ( mixed $element )

Description

Adds an element into the form. If $element is a string representing an element type, then this method accepts variable number of parameters, their meaning and count depending on element type.

Parameters starting from second will be passed to the element's constructor, consult the docs for the appropriate element to find out which parameters to pass.

Parameter

mixed $element

element object or type of element to add (text, textarea, file...)

Return value

return reference to added element

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_UNREGISTERED_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::_loadElement() | Tried to add an element of unknown type | Check the type name spelling or use HTML_QuickForm::registerElementType()
QUICKFORM_INVALID_ELEMENT_NAME | Element 'elementName ' already exists in HTML_QuickForm::addElement() | Tried to add an element having a name of an existing element, but of different type | Choose a different name for an element

Note

since 1.0

This function can not be called statically.

Prev | Creating a basic form | Next
constructor HTML_QuickForm::HTML_QuickForm() | PEAR Manual | HTML_QuickForm::apiVersion()


HTML_QuickForm::apiVersion()

HTML_QuickForm::apiVersion()

HTML_QuickForm::apiVersion() – Returns the current API version

Synopsis

require_once 'HTML/QuickForm.php';

float HTML_QuickForm::apiVersion ( ( void )

Description

Returns the current API version

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::addElement() | PEAR Manual | HTML_QuickForm::createElement()


HTML_QuickForm::createElement()

HTML_QuickForm::createElement()

HTML_QuickForm::createElement() – Creates a new form element of the given type

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::createElement ( string $elementType )

Description

Creates a new form element of the given type. This method accepts variable number of parameters, their meaning and count depending on $elementType .

Parameters starting from second will be passed to the element's constructor, consult the docs for the appropriate element to find out which parameters to pass.

Parameter

string $elementType

type of element to create (text, textarea, file...)

Return value

return object, descendant of HTML_QuickForm_element

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_UNREGISTERED_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::_loadElement() | Tried to create an element of unknown type | Check the type name spelling or use HTML_QuickForm::registerElementType()

Note

since 1.0

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::apiVersion() | PEAR Manual | HTML_QuickForm::elementExists()


HTML_QuickForm::elementExists()

HTML_QuickForm::elementExists()

HTML_QuickForm::elementExists() – Checks if element is in the form

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::elementExists ( string $element = null )

Description

Returns TRUE if element is in the form, FALSE otherwise.

Parameter

string $element

form name of element to check

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::createElement() | PEAR Manual | HTML_QuickForm::errorMessage()


HTML_QuickForm::errorMessage()

HTML_QuickForm::errorMessage()

HTML_QuickForm::errorMessage() – Returns an error message for error code

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::errorMessage ( int $value )

Description

Returns a textual error message for QuickForm error code.

Parameter

integer $value

int error code

Return value

return error message

Throws

throws no exceptions thrown

Note

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::elementExists() | PEAR Manual | HTML_QuickForm::getElementType()


HTML_QuickForm::getElementType()

HTML_QuickForm::getElementType()

HTML_QuickForm::getElementType() – Returns the type of an element

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::getElementType ( string $element )

Description

Returns the type of the given element.

Parameter

string $element

Name of form element

Return value

return element type or FALSE if element is not found

Throws

throws no exceptions thrown

Note

since 1.1

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::errorMessage() | PEAR Manual | HTML_QuickForm::getElement()


HTML_QuickForm::getElement()

HTML_QuickForm::getElement()

HTML_QuickForm::getElement() – Returns a reference to the element

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::getElement ( string $element )

Description

Returns a reference to the form element.

Parameter

string $element

Element name

Return value

return reference to element

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::getElement() | Tried to get a non-existant element | Check the element's name spelling

Note

since 2.0

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::getElementType() | PEAR Manual | HTML_QuickForm::getMaxFileSize()


HTML_QuickForm::getMaxFileSize()

HTML_QuickForm::getMaxFileSize()

HTML_QuickForm::getMaxFileSize() – Returns the value of MAX_FILE_SIZE hidden element

Synopsis

require_once 'HTML/QuickForm.php';

int HTML_QuickForm::getMaxFileSize ( ( void )

Description

Returns the value of MAX_FILE_SIZE hidden element (used for file uploads).

Return value

return max file size in bytes

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::getElement() | PEAR Manual | HTML_QuickForm::getRegisteredTypes()


HTML_QuickForm::getRegisteredTypes()

HTML_QuickForm::getRegisteredTypes()

HTML_QuickForm::getRegisteredTypes() – Returns registered element types

Synopsis

require_once 'HTML/QuickForm.php';

array HTML_QuickForm::getRegisteredTypes ( ( void )

Description

Returns an array of registered element types.

Throws

throws

Note

since 1.0

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::getMaxFileSize() | PEAR Manual | HTML_QuickForm::insertElementBefore()


HTML_QuickForm::insertElementBefore()

HTML_QuickForm::insertElementBefore()

HTML_QuickForm::insertElementBefore() – Inserts a new element right before the other element

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::insertElementBefore ( object &$element , string $nameAfter )

Description

Inserts a new element right before the other element.

It is not possible to check whether the $element is already added to the form, therefore if you want to move the existing form element to a new position, you'll have to use removeElement():

<?php
$form->insertElementBefore($form->removeElement('foo', false), 'bar');
?>

Parameter

object &$element

Element to insert (instance of HTML_QuickForm_element)

string $nameAfter

Name of the element before which the new one is inserted

Return value

return reference to inserted element.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_ELEMENT_NAME | Several elements named $nameAfter exist in HTML_QuickForm::insertElementBefore() | Several elements named $nameAfter (e.g.: radios) exist in the form. The method does not handle this case. | Insert before some other element. Consider adding a dummy element with a unique name.
QUICKFORM_INVALID_ELEMENT_NAME | Element '$elementName' already exists in HTML_QuickForm::insertElementBefore() | Element exists with the same name as $element but of different type | Give some other name to the inserted element.
QUICKFORM_NONEXIST_ELEMENT | Element $nameAfter does not exist in HTML_QuickForm::insertElementBefore() | Tried to insert before a non-existant element | Check the element's name spelling

Note

since 3.2.4

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::getRegisteredTypes() | PEAR Manual | HTML_QuickForm::isError()


HTML_QuickForm::isError()

HTML_QuickForm::isError()

HTML_QuickForm::isError() – Tells whether a result is an error

Synopsis

require_once 'HTML/QuickForm.php';

bool HTML_QuickForm::isError ( mixed $value )

Description

Tells whether a result is an error (i.e. whether $value is an instance of HTML_QuickForm_Error).

Parameter

mixed $value

result of some QuickForm function

Return value

return whether $value is an error

Throws

throws no exceptions thrown

Note

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::insertElementBefore() | PEAR Manual | HTML_QuickForm::isTypeRegistered()


HTML_QuickForm::isTypeRegistered()

HTML_QuickForm::isTypeRegistered()

HTML_QuickForm::isTypeRegistered() – Checks whether the form element type is supported

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::isTypeRegistered ( string $type )

Description

Returns whether or not the form element type is supported. New types are added via HTML_QuickForm::registerElementType().

Parameter

string $type

Form element type

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::isError() | PEAR Manual | HTML_QuickForm::registerElementType()


HTML_QuickForm::registerElementType()

HTML_QuickForm::registerElementType()

HTML_QuickForm::registerElementType() – Registers a new element type

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::registerElementType ( string $typeName , string $include , string $className )

Description

Registers a new element type. After that, elements of this type may be created via createElement() and added to form via addElement().

Parameter

string $typeName

Name of element type

string $include

Include path for element type

string $className

Element class name

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::isTypeRegistered() | PEAR Manual | HTML_QuickForm::removeElement()


HTML_QuickForm::removeElement()

HTML_QuickForm::removeElement()

HTML_QuickForm::removeElement() – Removes an element

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::removeElement ( string $elementName , boolean $removeRules = true )

Description

Removes an element from the form.

Parameter

string $elementName

The element name

boolean $removeRules

TRUE if rules for this element are to be removed too

Return value

return reference to element being removed.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$elementName ' does not exist in HTML_QuickForm::removeElement() | Tried to remove a non-existant element | Check the element's name spelling

Note

since 2.0

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::registerElementType() | PEAR Manual | HTML_QuickForm::setMaxFileSize()


HTML_QuickForm::setMaxFileSize()

HTML_QuickForm::setMaxFileSize()

HTML_QuickForm::setMaxFileSize() – Sets the value of MAX_FILE_SIZE hidden element

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::setMaxFileSize ( int $bytes )

Description

Sets the value of MAX_FILE_SIZE hidden element (used for file uploads).

Parameter

integer $bytes

Size in bytes

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::removeElement() | PEAR Manual | HTML_QuickForm::updateElementAttr()


HTML_QuickForm::updateElementAttr()

HTML_QuickForm::updateElementAttr()

HTML_QuickForm::updateElementAttr() – Updates Attributes for one or more elements

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::updateElementAttr ( mixed $elements , mixed $attrs )

Description

Updates Attributes for one or more elements

This may not work for groups and group-based elements (date, hierselect). To ensure proper behaviour, you should update attributes of grouped elements manually.

Parameter

mixed $elements

Array of element names/objects or string of elements to be updated

mixed $attrs

Array or string of html attributes

Throws

throws no exceptions thrown

Note

since 2.10

This function can not be called statically.

Prev | Creating a basic form | Next
HTML_QuickForm::setMaxFileSize() | PEAR Manual | Classes representing form elements


Classes representing form elements

Classes representing form elements

Table of Contents
  • Base classes
  • Standard HTML elements
  • Custom elements

To be written

Prev | HTML_QuickForm | Next
HTML_QuickForm::updateElementAttr() | PEAR Manual | Base classes


Base classes

Base classes

Table of Contents
  • Class Summary HTML_QuickForm_element -- Base class for form elements
  • constructor HTML_QuickForm_element() -- Class constructor
  • HTML_QuickForm_element::accept() -- Accepts a renderer
  • HTML_QuickForm_element::apiVersion() -- Returns the current API version
  • HTML_QuickForm_element::exportValue() -- Returns a 'safe' element's value (package developer related)
  • HTML_QuickForm_element::freeze() -- Freezes the element
  • HTML_QuickForm_element::getFrozenHtml() -- Returns the value of field without HTML tags
  • HTML_QuickForm_element::getLabel() -- Returns the label for the element
  • HTML_QuickForm_element::getName() -- Returns the element name
  • HTML_QuickForm_element::getType() -- Returns the element type
  • HTML_QuickForm_element::getValue() -- Returns the value of the form element
  • HTML_QuickForm_element::isFrozen() -- Returns whether or not the element is frozen
  • HTML_QuickForm_element::onQuickFormEvent() -- Called by HTML_QuickForm whenever form event is made on this element (package developer related)
  • HTML_QuickForm_element::setLabel() -- Sets a label for the element
  • HTML_QuickForm_element::setName() -- Sets the input field name
  • HTML_QuickForm_element::setPersistantFreeze() -- Sets whether element value should persist on freeze
  • HTML_QuickForm_element::setValue() -- Sets the value of the form element
  • HTML_QuickForm_element::unfreeze() -- Unfreezes the element
  • Class Summary HTML_QuickForm_input -- Base class for input form elements
  • constructor HTML_QuickForm_input() -- Class constructor
  • HTML_QuickForm_input::setType() -- Sets the element type
Prev | Classes representing form elements | Next
Classes representing form elements | PEAR Manual | Class Summary HTML_QuickForm_element


Class Summary HTML_QuickForm_element

Class Summary HTML_QuickForm_element

Class Summary HTML_QuickForm_element – Base class for form elements

Description

This is a base class for all QuickForm elements. It defines the API that is implemented by all the child classes representing actual form elements. You should use these elements, there is no need to directly instantiate HTML_QuickForm_element.

If you would like to create your own element to use with QuickForm, you should extend this class or one of its descendants and make sure to implement all methods defined here. There is also toHtml() method defined in HTML_Common that should be implemented.

Class Trees for HTML_QuickForm_element

  • HTML_Common

    • HTML_QuickForm_element

Classes that extend HTML_QuickForm_element
Class | Summary
HTML_QuickForm_group | HTML class for a form element group
HTML_QuickForm_input | Base class for input form elements
HTML_QuickForm_select | Class to dynamically create an HTML SELECT
HTML_QuickForm_static | HTML class for static data
HTML_QuickForm_textarea | HTML class for a textarea type field
Prev | Base classes | Next
Base classes | PEAR Manual | constructor HTML_QuickForm_element()


constructor HTML_QuickForm_element()

constructor HTML_QuickForm_element()

constructor HTML_QuickForm_element() – Class constructor

Synopsis

require_once 'HTML/QuickForm/element.php';

void constructor HTML_QuickForm_element::HTML_QuickForm_element ( string $elementName = null , mixed $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Name of the element

mixed $elementLabel

Label(s) for the element

mixed $attributes

Associative array of tag attributes or HTML attributes name="value" pairs

Throws

throws no exceptions thrown

See

see setName(), setLabel()

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
Class Summary HTML_QuickForm_element | PEAR Manual | HTML_QuickForm_element::accept()


HTML_QuickForm_element::accept()

HTML_QuickForm_element::accept()

HTML_QuickForm_element::accept() – Accepts a renderer

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::accept ( object HTML_QuickForm_Renderer &$renderer , bool $required = false , string $error = null )

Description

This method rarely needs to be called directly, it is usually called from HTML_QuickForm::accept() method.

Parameter

object HTML_QuickForm_Renderer &$renderer

an instance of HTML_QuickForm_Renderer subclass

boolean $required

Whether an element is required

string $error

An error message associated with an element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Base classes | Next
constructor HTML_QuickForm_element() | PEAR Manual | HTML_QuickForm_element::apiVersion()


HTML_QuickForm_element::apiVersion()

HTML_QuickForm_element::apiVersion()

HTML_QuickForm_element::apiVersion() – Returns the current API version

Synopsis

require_once 'HTML/QuickForm/element.php';

float HTML_QuickForm_element::apiVersion ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::accept() | PEAR Manual | HTML_QuickForm_element::exportValue()


HTML_QuickForm_element::exportValue()

HTML_QuickForm_element::exportValue()

HTML_QuickForm_element::exportValue() – Returns a 'safe' element's value (package developer related)

Synopsis

require_once 'HTML/QuickForm/element.php';

mixed HTML_QuickForm_element::exportValue ( array &$submitValues , bool $assoc = false )

Description

This method is not intended to be called directly. It is called by HTML_QuickForm::exportValue() and HTML_QuickForm::exportValues() methods.

The method first tries to find a value for itself in a passed array, if such a value is not found it takes the display value via getValue(). It then filters out the values that cannot possibly be submitted by this element and returns the result.

Parameter

array &$submitValues

array of submitted values to search

boolean $assoc

whether to return the value as associative array

Throws

throws no exceptions thrown

See

see getValue(), HTML_QuickForm::exportValue(), HTML_QuickForm::exportValues().

Note

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::apiVersion() | PEAR Manual | HTML_QuickForm_element::freeze()


HTML_QuickForm_element::freeze()

HTML_QuickForm_element::freeze()

HTML_QuickForm_element::freeze() – Freezes the element

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::freeze ( )

Description

When the element is displayed after the call to freeze(), only its value is displayed without the input tags, thus the element cannot be edited. If persistant freeze is set, then hidden field containing the element value will be output, too.

Note: This method makes sense only with the elements that actually are editable in the first place. It has no effect on buttons, images, hidden fields, static content and the like.

Throws

throws no exceptions thrown

See

see unfreeze(), isFrozen(), setPersistantFreeze(), getFrozenHtml(), HTML_QuickForm::freeze(), HTML_QuickForm::isFrozen().

Note

This function can not be called statically.

Example

Freezing the text element

<?php
require_once 'HTML/QuickForm.php';

$text =& HTML_QuickForm::createElement('text', 'freezeMe');
$text->setValue('Some value');
echo $text->toHtml() . "\n";
$text->freeze();
echo $text->toHtml() . "\n";
$text->setPersistantFreeze(false);
echo $text->toHtml() . "\n";
$text->unfreeze();
echo $text->toHtml() . "\n";
?>

Output

<input name="freezeMe" type="text" value="Some value" />
Some value<input type="hidden" name="freezeMe" value="Some value" />
Some value
<input name="freezeMe" type="text" value="Some value" />

Prev | Base classes | Next
HTML_QuickForm_element::exportValue() | PEAR Manual | HTML_QuickForm_element::getFrozenHtml()


HTML_QuickForm_element::getFrozenHtml()

HTML_QuickForm_element::getFrozenHtml()

HTML_QuickForm_element::getFrozenHtml() – Returns the value of field without HTML tags

Synopsis

require_once 'HTML/QuickForm/element.php';

string HTML_QuickForm_element::getFrozenHtml ( )

Description

This method returns the HTML for the element in frozen state. There is rarely a need to call it directly.

Throws

throws no exceptions thrown

See

see isFrozen(), setPersistantFreeze(), freeze().

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::freeze() | PEAR Manual | HTML_QuickForm_element::getLabel()


HTML_QuickForm_element::getLabel()

HTML_QuickForm_element::getLabel()

HTML_QuickForm_element::getLabel() – Returns the label for the element

Synopsis

require_once 'HTML/QuickForm/element.php';

string HTML_QuickForm_element::getLabel ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setLabel().

Note

since 1.3

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::getFrozenHtml() | PEAR Manual | HTML_QuickForm_element::getName()


HTML_QuickForm_element::getName()

HTML_QuickForm_element::getName()

HTML_QuickForm_element::getName() – Returns the element name

Synopsis

require_once 'HTML/QuickForm/element.php';

string HTML_QuickForm_element::getName ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setName().

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::getLabel() | PEAR Manual | HTML_QuickForm_element::getType()


HTML_QuickForm_element::getType()

HTML_QuickForm_element::getType()

HTML_QuickForm_element::getType() – Returns the element type

Synopsis

require_once 'HTML/QuickForm/element.php';

string HTML_QuickForm_element::getType ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::getName() | PEAR Manual | HTML_QuickForm_element::getValue()


HTML_QuickForm_element::getValue()

HTML_QuickForm_element::getValue()

HTML_QuickForm_element::getValue() – Returns the value of the form element

Synopsis

require_once 'HTML/QuickForm/element.php';

mixed HTML_QuickForm_element::getValue ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setValue(), HTML_QuickForm::getElementValue().

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::getType() | PEAR Manual | HTML_QuickForm_element::isFrozen()


HTML_QuickForm_element::isFrozen()

HTML_QuickForm_element::isFrozen()

HTML_QuickForm_element::isFrozen() – Returns whether or not the element is frozen

Synopsis

require_once 'HTML/QuickForm/element.php';

bool HTML_QuickForm_element::isFrozen ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see freeze().

Note

since 1.3

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::getValue() | PEAR Manual | HTML_QuickForm_element::onQuickFormEvent()


HTML_QuickForm_element::onQuickFormEvent()

HTML_QuickForm_element::onQuickFormEvent()

HTML_QuickForm_element::onQuickFormEvent() – Called by HTML_QuickForm whenever form event is made on this element (package developer related)

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::onQuickFormEvent ( string $event , mixed $arg , object &$caller )

Description

Note: This method is not intended to be called directly.

If you are creating your own element, you should override this method and create handlers for each of available QuickForm events.

'addElement'

This event is sent by HTML_QuickForm::addElement() method when adding a new element to the form. Its handler should usually send 'createElement' and 'updateValue' events.

'createElement'

This event is sent by HTML_QuickForm::createElement() method after the element object is instantiated. Its handler should usually call class constructor using the contents of $arg as parameters.

'setGroupValue'

The event is sent by HTML_QuickForm_group::setValue() method to each of the grouped elements. The handler generally should set the element's value to $arg .

'updateValue'

The event is sent by QuickForm when the element is added to the form and when form default and constant values are set. The handler for this event is the most complex one: it should search for element's value within form's constant, submit (if applicable) and default values (in that order) and set the element's value to the found one.

Parameter

string $event

Name of event

mixed $arg

event arguments

object &$caller

calling object

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::isFrozen() | PEAR Manual | HTML_QuickForm_element::setLabel()


HTML_QuickForm_element::setLabel()

HTML_QuickForm_element::setLabel()

HTML_QuickForm_element::setLabel() – Sets a label for the element

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::setLabel ( mixed $label )

Description

Label is a description text that will be displayed near the element. Some renderers can handle multiple labels for the element.

Parameter

mixed $label

Display text for the element

Throws

throws no exceptions thrown

See

see getLabel().

Note

since 1.3

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::onQuickFormEvent() | PEAR Manual | HTML_QuickForm_element::setName()


HTML_QuickForm_element::setName()

HTML_QuickForm_element::setName()

HTML_QuickForm_element::setName() – Sets the input field name

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::setName ( string $name )

Description

This package is not documented yet.

Parameter

string $name

Input field name attribute

Throws

throws no exceptions thrown

See

see getName().

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::setLabel() | PEAR Manual | HTML_QuickForm_element::setPersistantFreeze()


HTML_QuickForm_element::setPersistantFreeze()

HTML_QuickForm_element::setPersistantFreeze()

HTML_QuickForm_element::setPersistantFreeze() – Sets whether element value should persist on freeze()

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::setPersistantFreeze ( bool $persistant = false )

Description

Sets whether an element value should be kept in an hidden field when the element is frozen or not.

Parameter

boolean $persistant

True if persistant value

Throws

throws no exceptions thrown

See

see freeze(), getFrozenHtml().

Note

since 2.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::setName() | PEAR Manual | HTML_QuickForm_element::setValue()


HTML_QuickForm_element::setValue()

HTML_QuickForm_element::setValue()

HTML_QuickForm_element::setValue() – Sets the value of the form element

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::setValue ( mixed $value )

Description

This sets the display value for the element. It can be different from its submit value.

Parameter

mixed $value

Default value of the form element

Throws

throws no exceptions thrown

See

see getValue().

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::setPersistantFreeze() | PEAR Manual | HTML_QuickForm_element::unfreeze()


HTML_QuickForm_element::unfreeze()

HTML_QuickForm_element::unfreeze()

HTML_QuickForm_element::unfreeze() – Unfreezes the element

Synopsis

require_once 'HTML/QuickForm/element.php';

void HTML_QuickForm_element::unfreeze ( )

Description

Unfreezes the element so that it becomes editable again.

Throws

throws no exceptions thrown

See

see freeze(), isFrozen(), setPersistantFreeze(), getFrozenHtml(), HTML_QuickForm::freeze(), HTML_QuickForm::isFrozen().

Note

This function can not be called statically.

Prev | Base classes | Next
HTML_QuickForm_element::setValue() | PEAR Manual | Class Summary HTML_QuickForm_input


Class Summary HTML_QuickForm_input

Class Summary HTML_QuickForm_input

Class Summary HTML_QuickForm_input – Base class for input form elements

Description

Since <input> elements have very similar HTML representations, they have this common base class. You don't need to instantiate it directly, use one of the child classes.

Class Trees for HTML_QuickForm_input

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

Classes that extend HTML_QuickForm_input
Class | Summary
HTML_QuickForm_button | HTML class for a button type element
HTML_QuickForm_checkbox | HTML class for a checkbox type field
HTML_QuickForm_file | HTML class for a file type element
HTML_QuickForm_hidden | HTML class for a hidden type element
HTML_QuickForm_image | HTML class for a image type element
HTML_QuickForm_password | HTML class for a password type field
HTML_QuickForm_radio | HTML class for a radio type element
HTML_QuickForm_reset | HTML class for a reset type element
HTML_QuickForm_submit | HTML class for a submit type element
HTML_QuickForm_text | HTML class for a text field

HTML_QuickForm_input Inherited Methods

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Base classes | Next
HTML_QuickForm_element::unfreeze() | PEAR Manual | constructor HTML_QuickForm_input()


constructor HTML_QuickForm_input()

constructor HTML_QuickForm_input()

constructor HTML_QuickForm_input() – Class constructor

Synopsis

require_once 'HTML/QuickForm/input.php';

void constructor HTML_QuickForm_input::HTML_QuickForm_input ( string $elementName = null , mixed $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

mixed $elementLabel

Label(s) for the input field

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
Class Summary HTML_QuickForm_input | PEAR Manual | HTML_QuickForm_input::setType()


HTML_QuickForm_input::setType()

HTML_QuickForm_input::setType()

HTML_QuickForm_input::setType() – Sets the element type

Synopsis

require_once 'HTML/QuickForm/input.php';

void HTML_QuickForm_input::setType ( string $type )

Description

This package is not documented yet.

Parameter

string $type

Element type

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Base classes | Next
constructor HTML_QuickForm_input() | PEAR Manual | Standard HTML elements


Standard HTML elements

Standard HTML elements

Table of Contents
  • Class Summary HTML_QuickForm_button -- HTML class for a button type element
  • constructor HTML_QuickForm_button() -- Class constructor
  • Class Summary HTML_QuickForm_checkbox -- HTML class for a checkbox type field
  • constructor HTML_QuickForm_checkbox() -- Class constructor
  • HTML_QuickForm_checkbox::getChecked() -- Returns whether a checkbox is checked
  • HTML_QuickForm_checkbox::getText() -- Returns the checkbox text
  • HTML_QuickForm_checkbox::setChecked() -- Sets whether a checkbox is checked
  • HTML_QuickForm_checkbox::setText() -- Sets the checkbox text
  • Class Summary HTML_QuickForm_file -- HTML class for a file type element
  • constructor HTML_QuickForm_file() -- Class constructor
  • HTML_QuickForm_file::getSize() -- Returns size of file element
  • HTML_QuickForm_file::getValue() -- Returns information about the uploaded file
  • HTML_QuickForm_file::isUploadedFile() -- Checks if the element contains an uploaded file
  • HTML_QuickForm_file::moveUploadedFile() -- Moves an uploaded file into the destination
  • HTML_QuickForm_file::setSize() -- Sets size of file element
  • Class Summary HTML_QuickForm_hidden -- HTML class for a hidden type element
  • constructor HTML_QuickForm_hidden() -- Class constructor
  • Class Summary HTML_QuickForm_image -- HTML class for a image type element
  • constructor HTML_QuickForm_image() -- Class constructor
  • HTML_QuickForm_image::setAlign() -- Sets alignment for image element
  • HTML_QuickForm_image::setBorder() -- Sets border size for image element
  • HTML_QuickForm_image::setSource() -- Sets source for image element
  • Class Summary HTML_QuickForm_password -- HTML class for a password type field
  • constructor HTML_QuickForm_password() -- Class constructor
  • HTML_QuickForm_password::setMaxlength() -- Sets maxlength of password element
  • HTML_QuickForm_password::setSize() -- Sets size of password element
  • Class Summary HTML_QuickForm_radio -- HTML class for a radio type element
  • constructor HTML_QuickForm_radio() -- Class constructor
  • HTML_QuickForm_radio::getChecked() -- Returns whether radio button is checked
  • HTML_QuickForm_radio::getText() -- Returns the radio text
  • HTML_QuickForm_radio::setChecked() -- Sets whether radio button is checked
  • HTML_QuickForm_radio::setText() -- Sets the radio text
  • Class Summary HTML_QuickForm_reset -- HTML class for a reset type element
  • constructor HTML_QuickForm_reset() -- Class constructor
  • Class Summary HTML_QuickForm_select -- Class to dynamically create an HTML SELECT
  • constructor HTML_QuickForm_select() -- Class constructor
  • HTML_QuickForm_select::addOption() -- Adds a new OPTION to the SELECT
  • HTML_QuickForm_select::getMultiple() -- Returns the select mutiple attribute
  • HTML_QuickForm_select::getPrivateName() -- Returns the element name (possibly with brackets appended)
  • HTML_QuickForm_select::getSelected() -- Returns an array of the selected values
  • HTML_QuickForm_select::getSize() -- Returns the select field size
  • HTML_QuickForm_select::load() -- Loads options from different types of data sources
  • HTML_QuickForm_select::loadArray() -- Loads the options from an associative array
  • HTML_QuickForm_select::loadDbResult() -- Loads the options from DB_result object
  • HTML_QuickForm_select::loadQuery() -- Queries a database and loads the options from the results
  • HTML_QuickForm_select::setMultiple() -- Sets the select mutiple attribute
  • HTML_QuickForm_select::setSelected() -- Sets the default values of the select box
  • HTML_QuickForm_select::setSize() -- Sets the select field size, only applies to 'multiple' selects
  • Class Summary HTML_QuickForm_submit -- HTML class for a submit type element
  • constructor HTML_QuickForm_submit() -- Class constructor
  • Class Summary HTML_QuickForm_text -- HTML class for a text field
  • constructor HTML_QuickForm_text -- Class constructor
  • HTML_QuickForm_text::setMaxlength() -- Sets maxlength of text field
  • HTML_QuickForm_text::setSize() -- Sets size of text field
  • Class Summary HTML_QuickForm_textarea -- HTML class for a textarea type field
  • constructor HTML_QuickForm_textarea() -- Class constructor
  • HTML_QuickForm_textarea::setCols() -- Sets width in cols for textarea element
  • HTML_QuickForm_textarea::setRows() -- Sets height in rows for textarea element
  • HTML_QuickForm_textarea::setWrap() -- Sets wrap type for textarea element
  • Class Summary HTML_QuickForm_xbutton -- Class for HTML 4.0 <button> element
  • constructor HTML_QuickForm_xbutton() -- Class constructor
  • HTML_QuickForm_xbutton::setContent() -- Sets the contents of the element
Prev | Classes representing form elements | Next
HTML_QuickForm_input::setType() | PEAR Manual | Class Summary HTML_QuickForm_button


Class Summary HTML_QuickForm_button

Class Summary HTML_QuickForm_button

Class Summary HTML_QuickForm_button – HTML class for a button type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_button

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_button

HTML_QuickForm_button Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
Standard HTML elements | PEAR Manual | constructor HTML_QuickForm_button()


constructor HTML_QuickForm_button()

constructor HTML_QuickForm_button()

constructor HTML_QuickForm_button() – Class constructor

Synopsis

require_once 'HTML/QuickForm/button.php';

void constructor HTML_QuickForm_button::HTML_QuickForm_button ( string $elementName = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $value

(optional)Input field value

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_button | PEAR Manual | Class Summary HTML_QuickForm_checkbox


Class Summary HTML_QuickForm_checkbox

Class Summary HTML_QuickForm_checkbox

Class Summary HTML_QuickForm_checkbox – HTML class for a checkbox type field

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_checkbox

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_checkbox

Classes that extend HTML_QuickForm_checkbox
Class | Summary
HTML_QuickForm_advcheckbox | HTML class for an advanced checkbox type field

HTML_QuickForm_checkbox Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
constructor HTML_QuickForm_button() | PEAR Manual | constructor HTML_QuickForm_checkbox()


constructor HTML_QuickForm_checkbox()

constructor HTML_QuickForm_checkbox()

constructor HTML_QuickForm_checkbox() – Class constructor

Synopsis

require_once 'HTML/QuickForm/checkbox.php';

void constructor HTML_QuickForm_checkbox::HTML_QuickForm_checkbox ( string $elementName = null , string $elementLabel = null , string $text = '' , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

string $text

(optional)Checkbox display text

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_checkbox | PEAR Manual | HTML_QuickForm_checkbox::getChecked()


HTML_QuickForm_checkbox::getChecked()

HTML_QuickForm_checkbox::getChecked()

HTML_QuickForm_checkbox::getChecked() – Returns whether a checkbox is checked

Synopsis

require_once 'HTML/QuickForm/checkbox.php';

bool HTML_QuickForm_checkbox::getChecked ( )

Description

Returns TRUE if checkbox has a "checked" attribute, FALSE otherwise. getValue() is an alias for this method. Thus the only value checkbox element can have in QuickForm is TRUE.

Throws

throws no exceptions thrown

See

see setChecked().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_checkbox() | PEAR Manual | HTML_QuickForm_checkbox::getText()


HTML_QuickForm_checkbox::getText()

HTML_QuickForm_checkbox::getText()

HTML_QuickForm_checkbox::getText() – Returns the checkbox text

Synopsis

require_once 'HTML/QuickForm/checkbox.php';

string HTML_QuickForm_checkbox::getText ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setText().

Note

since 1.1

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_checkbox::getChecked() | PEAR Manual | HTML_QuickForm_checkbox::setChecked()


HTML_QuickForm_checkbox::setChecked()

HTML_QuickForm_checkbox::setChecked()

HTML_QuickForm_checkbox::setChecked() – Sets whether a checkbox is checked

Synopsis

require_once 'HTML/QuickForm/checkbox.php';

void HTML_QuickForm_checkbox::setChecked ( bool $checked )

Description

This sets or removes the element's "checked" attribute based on $checked value. setValue() is an alias for this method.

Parameter

boolean $checked

Whether the field is checked or not

Throws

throws no exceptions thrown

See

see getChecked().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_checkbox::getText() | PEAR Manual | HTML_QuickForm_checkbox::setText()


HTML_QuickForm_checkbox::setText()

HTML_QuickForm_checkbox::setText()

HTML_QuickForm_checkbox::setText() – Sets the checkbox text

Synopsis

require_once 'HTML/QuickForm/checkbox.php';

void HTML_QuickForm_checkbox::setText ( string $text )

Description

This means the text that would be displayed with the checkbox, automatically enclosed in <label> tags. The label in QuickForm's sense is set via setLabel().

Parameter

string $text

Throws

throws no exceptions thrown

See

see getText().

Note

since 1.1

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_checkbox::setChecked() | PEAR Manual | Class Summary HTML_QuickForm_file


Class Summary HTML_QuickForm_file

Class Summary HTML_QuickForm_file

Class Summary HTML_QuickForm_file – HTML class for a file type element

Description

Alongside the usual element's methods, the class has special methods for working with uploaded files. When the class is included it also registers rules for validating the uploaded files.

Class Trees for HTML_QuickForm_file

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_file

HTML_QuickForm_file Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_checkbox::setText() | PEAR Manual | constructor HTML_QuickForm_file()


constructor HTML_QuickForm_file()

constructor HTML_QuickForm_file()

constructor HTML_QuickForm_file() – Class constructor

Synopsis

require_once 'HTML/QuickForm/file.php';

void constructor HTML_QuickForm_file::HTML_QuickForm_file ( string $elementName = null , string $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

string $elementLabel

Input field label

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_file | PEAR Manual | HTML_QuickForm_file::getSize()


HTML_QuickForm_file::getSize()

HTML_QuickForm_file::getSize()

HTML_QuickForm_file::getSize() – Returns size of file element

Synopsis

require_once 'HTML/QuickForm/file.php';

int HTML_QuickForm_file::getSize ( )

Description

This means 'size' attribute of the <input /> element, not size of the uploaded file.

Throws

throws no exceptions thrown

See

see setSize().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_file() | PEAR Manual | HTML_QuickForm_file::getValue()


HTML_QuickForm_file::getValue()

HTML_QuickForm_file::getValue()

HTML_QuickForm_file::getValue() – Returns information about the uploaded file

Synopsis

require_once 'HTML/QuickForm/file.php';

array HTML_QuickForm_file::getValue ( )

Description

Returns the information about the file upload, as in the $_FILES array. Note that while there exists a setValue() method, the method does nothing at all. The file element does not have a value if the form was not submitted.

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_file::getSize() | PEAR Manual | HTML_QuickForm_file::isUploadedFile()


HTML_QuickForm_file::isUploadedFile()

HTML_QuickForm_file::isUploadedFile()

HTML_QuickForm_file::isUploadedFile() – Checks if the element contains an uploaded file

Synopsis

require_once 'HTML/QuickForm/file.php';

bool HTML_QuickForm_file::isUploadedFile ( )

Description

This package is not documented yet.

Return value

returns true if file has been uploaded, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_file::getValue() | PEAR Manual | HTML_QuickForm_file::moveUploadedFile()


HTML_QuickForm_file::moveUploadedFile()

HTML_QuickForm_file::moveUploadedFile()

HTML_QuickForm_file::moveUploadedFile() – Moves an uploaded file into the destination

Synopsis

require_once 'HTML/QuickForm/file.php';

bool HTML_QuickForm_file::moveUploadedFile ( string $dest , string $fileName = '' )

Description

This package is not documented yet.

Parameter

string $dest

Destination directory path

string $fileName

New file name (if not given, original file name will be used).

Return value

returns true if file has been moved successfully, false otherwise.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_file::isUploadedFile() | PEAR Manual | HTML_QuickForm_file::setSize()


HTML_QuickForm_file::setSize()

HTML_QuickForm_file::setSize()

HTML_QuickForm_file::setSize() – Sets size of file element

Synopsis

require_once 'HTML/QuickForm/file.php';

void HTML_QuickForm_file::setSize ( int $size )

Description

This package is not documented yet.

Parameter

integer $size

Size of file element

Throws

throws no exceptions thrown

See

see getSize().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_file::moveUploadedFile() | PEAR Manual | Class Summary HTML_QuickForm_hidden


Class Summary HTML_QuickForm_hidden

Class Summary HTML_QuickForm_hidden

Class Summary HTML_QuickForm_hidden – HTML class for a hidden type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_hidden

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_hidden

HTML_QuickForm_hidden Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_file::setSize() | PEAR Manual | constructor HTML_QuickForm_hidden()


constructor HTML_QuickForm_hidden()

constructor HTML_QuickForm_hidden()

constructor HTML_QuickForm_hidden() – Class constructor

Synopsis

require_once 'HTML/QuickForm/hidden.php';

void constructor HTML_QuickForm_hidden::HTML_QuickForm_hidden ( string $elementName = null , string $value = '' , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $value

(optional)Input field value

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_hidden | PEAR Manual | Class Summary HTML_QuickForm_image


Class Summary HTML_QuickForm_image

Class Summary HTML_QuickForm_image

Class Summary HTML_QuickForm_image – HTML class for a image type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_image

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_image

HTML_QuickForm_image Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
constructor HTML_QuickForm_hidden() | PEAR Manual | constructor HTML_QuickForm_image()


constructor HTML_QuickForm_image()

constructor HTML_QuickForm_image()

constructor HTML_QuickForm_image() – Class constructor

Synopsis

require_once 'HTML/QuickForm/image.php';

void constructor HTML_QuickForm_image::HTML_QuickForm_image ( string $elementName = null , string $src = '' , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Element name attribute

string $src

(optional)Image source

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_image | PEAR Manual | HTML_QuickForm_image::setAlign()


HTML_QuickForm_image::setAlign()

HTML_QuickForm_image::setAlign()

HTML_QuickForm_image::setAlign() – Sets alignment for image element

Synopsis

require_once 'HTML/QuickForm/image.php';

void HTML_QuickForm_image::setAlign ( string $align )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('align' => $align));
?>

Parameter

string $align

alignment for image element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_image() | PEAR Manual | HTML_QuickForm_image::setBorder()


HTML_QuickForm_image::setBorder()

HTML_QuickForm_image::setBorder()

HTML_QuickForm_image::setBorder() – Sets border size for image element

Synopsis

require_once 'HTML/QuickForm/image.php';

void HTML_QuickForm_image::setBorder ( string $border )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('border' => $border));
?>

Parameter

string $border

border for image element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_image::setAlign() | PEAR Manual | HTML_QuickForm_image::setSource()


HTML_QuickForm_image::setSource()

HTML_QuickForm_image::setSource()

HTML_QuickForm_image::setSource() – Sets source for image element

Synopsis

require_once 'HTML/QuickForm/image.php';

void HTML_QuickForm_image::setSource ( string $src )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('src' => $src));
?>

Parameter

string $src

source for image element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_image::setBorder() | PEAR Manual | Class Summary HTML_QuickForm_password


Class Summary HTML_QuickForm_password

Class Summary HTML_QuickForm_password

Class Summary HTML_QuickForm_password – HTML class for a password type field

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_password

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_password

HTML_QuickForm_password Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_image::setSource() | PEAR Manual | constructor HTML_QuickForm_password()


constructor HTML_QuickForm_password()

constructor HTML_QuickForm_password()

constructor HTML_QuickForm_password() – Class constructor

Synopsis

require_once 'HTML/QuickForm/password.php';

void constructor HTML_QuickForm_password::HTML_QuickForm_password ( string $elementName = null , string $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_password | PEAR Manual | HTML_QuickForm_password::setMaxlength()


HTML_QuickForm_password::setMaxlength()

HTML_QuickForm_password::setMaxlength()

HTML_QuickForm_password::setMaxlength() – Sets maxlength of password element

Synopsis

require_once 'HTML/QuickForm/password.php';

void HTML_QuickForm_password::setMaxlength ( string $maxlength )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('maxlength' => $maxlength));
?>

Parameter

string $maxlength

Maximum length of password field

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_password() | PEAR Manual | HTML_QuickForm_password::setSize()


HTML_QuickForm_password::setSize()

HTML_QuickForm_password::setSize()

HTML_QuickForm_password::setSize() – Sets size of password element

Synopsis

require_once 'HTML/QuickForm/password.php';

void HTML_QuickForm_password::setSize ( string $size )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('size' => $size));
?>

Parameter

string $size

Size of password field

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_password::setMaxlength() | PEAR Manual | Class Summary HTML_QuickForm_radio


Class Summary HTML_QuickForm_radio

Class Summary HTML_QuickForm_radio

Class Summary HTML_QuickForm_radio – HTML class for a radio type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_radio

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_radio

HTML_QuickForm_radio Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_password::setSize() | PEAR Manual | constructor HTML_QuickForm_radio()


constructor HTML_QuickForm_radio()

constructor HTML_QuickForm_radio()

constructor HTML_QuickForm_radio() – Class constructor

Synopsis

require_once 'HTML/QuickForm/radio.php';

void constructor HTML_QuickForm_radio::HTML_QuickForm_radio ( string $elementName = null , mixed $elementLabel = null , string $text = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

mixed $elementLabel

Label(s) for a field

string $text

Text to display near the radio

string $value

Input field value

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_radio | PEAR Manual | HTML_QuickForm_radio::getChecked()


HTML_QuickForm_radio::getChecked()

HTML_QuickForm_radio::getChecked()

HTML_QuickForm_radio::getChecked() – Returns whether radio button is checked

Synopsis

require_once 'HTML/QuickForm/radio.php';

string HTML_QuickForm_radio::getChecked ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setChecked().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_radio() | PEAR Manual | HTML_QuickForm_radio::getText()


HTML_QuickForm_radio::getText()

HTML_QuickForm_radio::getText()

HTML_QuickForm_radio::getText() – Returns the radio text

Synopsis

require_once 'HTML/QuickForm/radio.php';

string HTML_QuickForm_radio::getText ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setText().

Note

since 1.1

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_radio::getChecked() | PEAR Manual | HTML_QuickForm_radio::setChecked()


HTML_QuickForm_radio::setChecked()

HTML_QuickForm_radio::setChecked()

HTML_QuickForm_radio::setChecked() – Sets whether radio button is checked

Synopsis

require_once 'HTML/QuickForm/radio.php';

void HTML_QuickForm_radio::setChecked ( bool $checked )

Description

This package is not documented yet.

Parameter

boolean $checked

Whether the field is checked or not

Throws

throws no exceptions thrown

See

see getChecked().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_radio::getText() | PEAR Manual | HTML_QuickForm_radio::setText()


HTML_QuickForm_radio::setText()

HTML_QuickForm_radio::setText()

HTML_QuickForm_radio::setText() – Sets the radio text

Synopsis

require_once 'HTML/QuickForm/radio.php';

void HTML_QuickForm_radio::setText ( string $text )

Description

This means the text that would be displayed with the radio, automatically enclosed in <label> tags. The label in QuickForm's sense is set via setLabel().

Parameter

string $text

Text to display near the radio button

Throws

throws no exceptions thrown

See

see getText().

Note

since 1.1

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_radio::setChecked() | PEAR Manual | Class Summary HTML_QuickForm_reset


Class Summary HTML_QuickForm_reset

Class Summary HTML_QuickForm_reset

Class Summary HTML_QuickForm_reset – HTML class for a reset type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_reset

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_reset

HTML_QuickForm_reset Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_radio::setText() | PEAR Manual | constructor HTML_QuickForm_reset()


constructor HTML_QuickForm_reset()

constructor HTML_QuickForm_reset()

constructor HTML_QuickForm_reset() – Class constructor

Synopsis

require_once 'HTML/QuickForm/reset.php';

void constructor HTML_QuickForm_reset::HTML_QuickForm_reset ( string $elementName = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $value

(optional)Input field value

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_reset | PEAR Manual | Class Summary HTML_QuickForm_select


Class Summary HTML_QuickForm_select

Class Summary HTML_QuickForm_select

Class Summary HTML_QuickForm_select – Class to dynamically create an HTML SELECT

Description

The highlight of this class is that it allows populating the options from associative array or from the database.

Class Trees for HTML_QuickForm_select

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_select

Classes that extend HTML_QuickForm_select
Class | Summary
HTML_QuickForm_hiddenselect | Creates hidden elements with select's values

HTML_QuickForm_select Inherited Methods

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
constructor HTML_QuickForm_reset() | PEAR Manual | constructor HTML_QuickForm_select()


constructor HTML_QuickForm_select()

constructor HTML_QuickForm_select()

constructor HTML_QuickForm_select() – Class constructor

Synopsis

require_once 'HTML/QuickForm/select.php';

void constructor HTML_QuickForm_select::HTML_QuickForm_select ( string $elementName = null , mixed $elementLabel = null , mixed $options = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Select name attribute

mixed $elementLabel

Label(s) for the select

mixed $options

Data to be used to populate options

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

See

see load().

Note

since 1.0

This function can not be called statically.

Example

<?php
$select = $quickform->createElement(
    'select', 'selectname',
    'Label for select',
    array('fr' => 'French', 'de' => 'German', 'en_GB' => 'British English'),
    array('id' => 'selectname', 'onchange' => '...'));
);
?>
Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_select | PEAR Manual | HTML_QuickForm_select::addOption()


HTML_QuickForm_select::addOption()

HTML_QuickForm_select::addOption()

HTML_QuickForm_select::addOption() – Adds a new OPTION to the SELECT

Synopsis

require_once 'HTML/QuickForm/select.php';

void HTML_QuickForm_select::addOption ( string $text , string $value , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $text

Display text for the OPTION

string $value

Value for the OPTION

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_select() | PEAR Manual | HTML_QuickForm_select::getMultiple()


HTML_QuickForm_select::getMultiple()

HTML_QuickForm_select::getMultiple()

HTML_QuickForm_select::getMultiple() – Returns the select mutiple attribute

Synopsis

require_once 'HTML/QuickForm/select.php';

bool HTML_QuickForm_select::getMultiple ( )

Description

This method returns TRUE if a multiple attribute is present in the select, FALSE otherwise.

Return value

returns true if multiple select, false otherwise

Throws

throws no exceptions thrown

See

see setMultiple().

Note

since 1.2

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::addOption() | PEAR Manual | HTML_QuickForm_select::getPrivateName()


HTML_QuickForm_select::getPrivateName()

HTML_QuickForm_select::getPrivateName()

HTML_QuickForm_select::getPrivateName() – Returns the element name (possibly with brackets appended)

Synopsis

require_once 'HTML/QuickForm/select.php';

string HTML_QuickForm_select::getPrivateName ( )

Description

If select has a multiple attribute present, then this method returns the name with brackets appended, else the result is identical to getName().

Throws

throws no exceptions thrown

See

see getName(), getMultiple().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::getMultiple() | PEAR Manual | HTML_QuickForm_select::getSelected()


HTML_QuickForm_select::getSelected()

HTML_QuickForm_select::getSelected()

HTML_QuickForm_select::getSelected() – Returns an array of the selected values

Synopsis

require_once 'HTML/QuickForm/select.php';

array HTML_QuickForm_select::getSelected ( )

Description

This function is an alias to getValue().

Return value

returns of selected values

Throws

throws no exceptions thrown

See

see getValue(), setSelected().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::getPrivateName() | PEAR Manual | HTML_QuickForm_select::getSize()


HTML_QuickForm_select::getSize()

HTML_QuickForm_select::getSize()

HTML_QuickForm_select::getSize() – Returns the select field size

Synopsis

require_once 'HTML/QuickForm/select.php';

int HTML_QuickForm_select::getSize ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see setSize().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::getSelected() | PEAR Manual | HTML_QuickForm_select::load()


HTML_QuickForm_select::load()

HTML_QuickForm_select::load()

HTML_QuickForm_select::load() – Loads options from different types of data sources

Synopsis

require_once 'HTML/QuickForm/select.php';

PEAR_Error HTML_QuickForm_select::load ( mixed &$options , mixed $param1 = null , mixed $param2 = null , mixed $param3 = null , mixed $param4 = null )

Description

This method is a simulated overloaded method. The arguments, other than the first are optional and only mean something depending on the type of the first argument.

If the first argument is an array then all arguments are passed in order to loadArray(). If the first argument is a DB_Result then all arguments are passed in order to loadDbResult(). If the first argument is a string or a DB connection then all arguments are passed in order to loadQuery().

Parameter

mixed &$options

Options source currently supports assoc array or DB_result

mixed $param1

(optional) See function detail

mixed $param2

(optional) See function detail

mixed $param3

(optional) See function detail

mixed $param4

(optional) See function detail

Return value

returns TRUE on success

Throws

throws PEAR_Error

See

see loadArray(), loadDbResult(), loadQuery().

Note

since 1.1

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::getSize() | PEAR Manual | HTML_QuickForm_select::loadArray()


HTML_QuickForm_select::loadArray()

HTML_QuickForm_select::loadArray()

HTML_QuickForm_select::loadArray() – Loads the options from an associative array

Synopsis

require_once 'HTML/QuickForm/select.php';

mixed HTML_QuickForm_select::loadArray ( array $arr , mixed $values = null )

Description

The array should have the form 'option value' => 'option text'.

Parameter

array $arr

Associative array of options

mixed $values

(optional) Array or comma delimited string of selected values

Return value

returns TRUE on success

Throws

throws PEAR_Error

See

see load(), addOption().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::load() | PEAR Manual | HTML_QuickForm_select::loadDbResult()


HTML_QuickForm_select::loadDbResult()

HTML_QuickForm_select::loadDbResult()

HTML_QuickForm_select::loadDbResult() – Loads the options from DB_result object

Synopsis

require_once 'HTML/QuickForm/select.php';

mixed HTML_QuickForm_select::loadDbResult ( object DB_Result &$result , string $textCol = null , string $valueCol = null , mixed $values = null )

Description

If no column names are specified the first two columns of the result are used as the text and value columns respectively.

Parameter

object &$result

DB_result object

string $textCol

(optional) Name of column to display as the OPTION text

string $valueCol

(optional) Name of column to use as the OPTION value

mixed $values

(optional) Array or comma delimited string of selected values

Return value

returns TRUE on success or PEAR_Error

Throws

throws PEAR_Error

See

see load(), addOption().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::loadArray() | PEAR Manual | HTML_QuickForm_select::loadQuery()


HTML_QuickForm_select::loadQuery()

HTML_QuickForm_select::loadQuery()

HTML_QuickForm_select::loadQuery() – Queries a database and loads the options from the results

Synopsis

require_once 'HTML/QuickForm/select.php';

mixed HTML_QuickForm_select::loadQuery ( mixed &$conn , string $sql , string $textCol = null , string $valueCol = null , mixed $values = null )

Description

If no column names are specified the first two columns of the result are used as the text and value columns respectively.

Parameter

mixed &$conn

Either an existing DB connection or a valid dsn

string $sql

SQL query string

string $textCol

(optional) Name of column to display as the OPTION text

string $valueCol

(optional) Name of column to use as the OPTION value

mixed $values

(optional) Array or comma delimited string of selected values

Throws

throws PEAR_Error

See

see load(), loadDbResult(), addOption().

Note

since 1.1

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::loadDbResult() | PEAR Manual | HTML_QuickForm_select::setMultiple()


HTML_QuickForm_select::setMultiple()

HTML_QuickForm_select::setMultiple()

HTML_QuickForm_select::setMultiple() – Sets the select mutiple attribute

Synopsis

require_once 'HTML/QuickForm/select.php';

void HTML_QuickForm_select::setMultiple ( bool $multiple )

Description

This method just adds or removes the multiple attribute of select depending on $multiple value.

Parameter

boolean $multiple

Whether the select supports multi-selections

Throws

throws no exceptions thrown

See

see getMultiple().

Note

since 1.2

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::loadQuery() | PEAR Manual | HTML_QuickForm_select::setSelected()


HTML_QuickForm_select::setSelected()

HTML_QuickForm_select::setSelected()

HTML_QuickForm_select::setSelected() – Sets the default values of the select box

Synopsis

require_once 'HTML/QuickForm/select.php';

void HTML_QuickForm_select::setSelected ( mixed $values )

Description

This method is an alias for setValue(). For multiple selects you can pass either an array or a comma delimited string of values.

Parameter

mixed $values

Array or comma delimited string of selected values

Throws

throws no exceptions thrown

See

see getSelected().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::setMultiple() | PEAR Manual | HTML_QuickForm_select::setSize()


HTML_QuickForm_select::setSize()

HTML_QuickForm_select::setSize()

HTML_QuickForm_select::setSize() – Sets the select field size, only applies to 'multiple' selects

Synopsis

require_once 'HTML/QuickForm/select.php';

void HTML_QuickForm_select::setSize ( int $size )

Description

This package is not documented yet.

Parameter

integer $size

Size of select field

Throws

throws no exceptions thrown

See

see getSize().

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_select::setSelected() | PEAR Manual | Class Summary HTML_QuickForm_submit


Class Summary HTML_QuickForm_submit

Class Summary HTML_QuickForm_submit

Class Summary HTML_QuickForm_submit – HTML class for a submit type element

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_submit

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_submit

HTML_QuickForm_submit Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_select::setSize() | PEAR Manual | constructor HTML_QuickForm_submit()


constructor HTML_QuickForm_submit()

constructor HTML_QuickForm_submit()

constructor HTML_QuickForm_submit() – Class constructor

Synopsis

require_once 'HTML/QuickForm/submit.php';

void constructor HTML_QuickForm_submit::HTML_QuickForm_submit ( string $elementName = null , string $value = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

string $value

Input field value

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_submit | PEAR Manual | Class Summary HTML_QuickForm_text


Class Summary HTML_QuickForm_text

Class Summary HTML_QuickForm_text

Class Summary HTML_QuickForm_text – HTML class for a text field

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_text

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_text

Classes that extend HTML_QuickForm_text
Class | Summary
HTML_QuickForm_autocomplete | HTML class for a text field with autocompletion feature

HTML_QuickForm_text Inherited Methods

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
constructor HTML_QuickForm_submit() | PEAR Manual | constructor HTML_QuickForm_text


constructor HTML_QuickForm_text

constructor HTML_QuickForm_text

constructor HTML_QuickForm_text – Class constructor

Synopsis

require_once 'HTML/QuickForm/text.php';

void constructor HTML_QuickForm_text::HTML_QuickForm_text ( string $elementName = null , string $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_text | PEAR Manual | HTML_QuickForm_text::setMaxlength()


HTML_QuickForm_text::setMaxlength()

HTML_QuickForm_text::setMaxlength()

HTML_QuickForm_text::setMaxlength() – Sets maxlength of text field

Synopsis

require_once 'HTML/QuickForm/text.php';

void HTML_QuickForm_text::setMaxlength ( string $maxlength )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('maxlength' => $maxlength));
?>

Parameter

string $maxlength

Maximum length of text field

Throws

throws no exceptions thrown

Note

since 1.3

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_text | PEAR Manual | HTML_QuickForm_text::setSize()


HTML_QuickForm_text::setSize()

HTML_QuickForm_text::setSize()

HTML_QuickForm_text::setSize() – Sets size of text field

Synopsis

require_once 'HTML/QuickForm/text.php';

void HTML_QuickForm_text::setSize ( string $size )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('size' => $size));
?>

Parameter

string $size

Size of text field

Throws

throws no exceptions thrown

Note

since 1.3

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_text::setMaxlength() | PEAR Manual | Class Summary HTML_QuickForm_textarea


Class Summary HTML_QuickForm_textarea

Class Summary HTML_QuickForm_textarea

Class Summary HTML_QuickForm_textarea – HTML class for a textarea type field

HTML class for a textarea type field

This package is not documented yet.

Class Trees for HTML_QuickForm_textarea

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_textarea

HTML_QuickForm_textarea Inherited Methods

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_text::setSize() | PEAR Manual | constructor HTML_QuickForm_textarea()


constructor HTML_QuickForm_textarea()

constructor HTML_QuickForm_textarea()

constructor HTML_QuickForm_textarea() – Class constructor

Synopsis

require_once 'HTML/QuickForm/textarea.php';

void constructor HTML_QuickForm_textarea::HTML_QuickForm_textarea ( string $elementName = null , mixed $elementLabel = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

Input field name attribute

mixed $elementLabel

Label(s) for a field

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_textarea | PEAR Manual | HTML_QuickForm_textarea::setCols()


HTML_QuickForm_textarea::setCols()

HTML_QuickForm_textarea::setCols()

HTML_QuickForm_textarea::setCols() – Sets width in cols for textarea element

Synopsis

require_once 'HTML/QuickForm/textarea.php';

void HTML_QuickForm_textarea::setCols ( string $cols )

Description

This package is not documented yet.

Parameter

string $cols

Width expressed in cols

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_textarea() | PEAR Manual | HTML_QuickForm_textarea::setRows()


HTML_QuickForm_textarea::setRows()

HTML_QuickForm_textarea::setRows()

HTML_QuickForm_textarea::setRows() – Sets height in rows for textarea element

Synopsis

require_once 'HTML/QuickForm/textarea.php';

void HTML_QuickForm_textarea::setRows ( string $rows )

Description

This package is not documented yet.

Parameter

string $rows

Height expressed in rows

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_textarea::setCols() | PEAR Manual | HTML_QuickForm_textarea::setWrap()


HTML_QuickForm_textarea::setWrap()

HTML_QuickForm_textarea::setWrap()

HTML_QuickForm_textarea::setWrap() – Sets wrap type for textarea element

Synopsis

require_once 'HTML/QuickForm/textarea.php';

void HTML_QuickForm_textarea::setWrap ( string $wrap )

Description

This package is not documented yet.

Parameter

string $wrap

Wrap type

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Standard HTML elements | Next
HTML_QuickForm_textarea::setRows() | PEAR Manual | Class Summary HTML_QuickForm_xbutton


Class Summary HTML_QuickForm_xbutton

Class Summary HTML_QuickForm_xbutton

Class Summary HTML_QuickForm_xbutton – Class for HTML 4.0 <button> element

Class for HTML 4.0 <button> element

This class is named 'xbutton' since the name 'button' was already taken by class representing an <input type="button" /> HTML element. Available since HTML_QuickForm release 3.2.3

Class Trees for HTML_QuickForm_xbutton

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_xbutton

HTML_QuickForm_xbutton Inherited Methods

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Standard HTML elements | Next
HTML_QuickForm_textarea::setWrap() | PEAR Manual | constructor HTML_QuickForm_xbutton()


constructor HTML_QuickForm_xbutton()

constructor HTML_QuickForm_xbutton()

constructor HTML_QuickForm_xbutton() – Class constructor

Synopsis

require_once 'HTML/QuickForm/xbutton.php';

void constructor HTML_QuickForm_xbutton::HTML_QuickForm_xbutton ( string $elementName = null , string $elementContent = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional) Button name

string $elementContent

(optional) Button content (HTML to add between <button></button> tags)

mixed $attributes

(optional) Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.3

Prev | Standard HTML elements | Next
Class Summary HTML_QuickForm_xbutton | PEAR Manual | HTML_QuickForm_xbutton::setContent()


HTML_QuickForm_xbutton::setContent()

HTML_QuickForm_xbutton::setContent()

HTML_QuickForm_xbutton::setContent() – Sets the contents of the element

Synopsis

require_once 'HTML/QuickForm/xbutton.php';

void HTML_QuickForm_xbutton::setContent ( string $content )

Description

Sets the contents of the button element: HTML to add between <button></button> tags.

Parameter

string $content

HTML to add between <button></button> tags

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.3

Prev | Standard HTML elements | Next
constructor HTML_QuickForm_xbutton() | PEAR Manual | Custom elements


Custom elements

Custom elements

Table of Contents
  • Class Summary HTML_QuickForm_advcheckbox -- HTML class for an advanced checkbox type field
  • constructor HTML_QuickForm_advcheckbox() -- Class constructor
  • HTML_QuickForm_advcheckbox::getOnclickJs() -- Create the javascript for the onclick event
  • HTML_QuickForm_advcheckbox::getPrivateName() -- Gets the private name for the element
  • HTML_QuickForm_advcheckbox::setValues() -- Sets the values used by the hidden element
  • Class Summary HTML_QuickForm_autocomplete -- HTML class for a text field with autocompletion feature
  • constructor HTML_QuickForm_autocomplete -- Class constructor
  • HTML_QuickForm_autocomplete::setoptions() -- Sets the options for the autocomplete input text element
  • Class Summary HTML_QuickForm_date -- Class for a group of elements used to input dates (and times).
  • constructor HTML_QuickForm_date() -- Class constructor
  • Class Summary HTML_QuickForm_header -- A pseudo-element used for adding headers to form
  • constructor HTML_QuickForm_header() -- Class constructor
  • Class Summary HTML_QuickForm_hiddenselect -- Creates hidden elements with select's values
  • constructor HTML_QuickForm_hiddenselect() -- Class constructor
  • Class Summary HTML_QuickForm_hierselect -- Class to dynamically create chained HTML Select elements, each select changes the content of the next.
  • constructor HTML_QuickForm_hierselect() -- Class constructor
  • HTML_QuickForm_hierselect::setOptions() -- Sets the options for the select elements
  • HTML_QuickForm_hierselect::setMainOptions() -- DEPRECATED: Sets the options for the first select
  • HTML_QuickForm_hierselect::setSecOptions() -- DEPRECATED: Sets the options for the secondary select
  • Class Summary HTML_QuickForm_html -- A pseudo-element used for adding raw HTML to form (deprecated)
  • constructor HTML_QuickForm_html() -- Class constructor
  • Class Summary HTML_QuickForm_link -- HTML class for a link type field
  • constructor HTML_QuickForm_link() -- Class constructor
  • HTML_QuickForm_link::setHref() -- Sets the links href
  • Class Summary HTML_QuickForm_static -- HTML class for static data
  • constructor HTML_QuickForm_static() -- Class constructor
  • HTML_QuickForm_static::setText() -- Sets the text
Prev | Classes representing form elements | Next
HTML_QuickForm_xbutton::setContent() | PEAR Manual | Class Summary HTML_QuickForm_advcheckbox


Class Summary HTML_QuickForm_advcheckbox

Class Summary HTML_QuickForm_advcheckbox

Class Summary HTML_QuickForm_advcheckbox – HTML class for an advanced checkbox type field

Description

HTML class for an advanced checkbox type field. Basically this fixes a problem that HTML has had where checkboxes can only pass a single value (the value of the checkbox when checked). A value for when the checkbox is not checked cannot be passed, and furthermore the checkbox variable doesn't even exist if the checkbox was submitted unchecked.

It works by creating a hidden field with the passed-in name and creating the checkbox with no name, but with a javascript onclick which sets the value of the hidden field.

Class Trees for HTML_QuickForm_advcheckbox

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_checkbox

          • HTML_QuickForm_advcheckbox

HTML_QuickForm_advcheckbox Inherited Methods

Inherited from HTML_QuickForm_checkbox
Method Name | Summary
Constructor HTML_QuickForm_checkbox::HTML_QuickForm_checkbox() | Class constructor
HTML_QuickForm_checkbox::exportValue() | Return true if the checkbox is checked, null if it is not checked (getValue() returns false)
HTML_QuickForm_checkbox::getChecked() | Returns whether a checkbox is checked
HTML_QuickForm_checkbox::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_checkbox::getText() | Returns the checkbox text
HTML_QuickForm_checkbox::getValue() | Returns the value of the form element
HTML_QuickForm_checkbox::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_checkbox::setChecked() | Sets whether a checkbox is checked
HTML_QuickForm_checkbox::setText() | Sets the checkbox text
HTML_QuickForm_checkbox::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
Custom elements | PEAR Manual | constructor HTML_QuickForm_advcheckbox()


constructor HTML_QuickForm_advcheckbox()

constructor HTML_QuickForm_advcheckbox()

constructor HTML_QuickForm_advcheckbox() – Class constructor

Synopsis

require_once 'HTML/QuickForm/advcheckbox.php';

void constructor HTML_QuickForm_advcheckbox::HTML_QuickForm_advcheckbox ( string $elementName = null , string $elementLabel = null , string $text = null , mixed $attributes = null , mixed $values = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

string $text

(optional)Text to put after the checkbox

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

mixed $values

(optional)Values to pass if checked or not checked

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_advcheckbox | PEAR Manual | HTML_QuickForm_advcheckbox::getOnclickJs()


HTML_QuickForm_advcheckbox::getOnclickJs()

HTML_QuickForm_advcheckbox::getOnclickJs()

HTML_QuickForm_advcheckbox::getOnclickJs() – Create the javascript for the onclick event

Synopsis

require_once 'HTML/QuickForm/advcheckbox.php';

string HTML_QuickForm_advcheckbox::getOnclickJs ( string $elementName )

Description

Create the javascript for the onclick event which will set the value of the hidden field.

Parameter

string $elementName

The element name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
constructor HTML_QuickForm_advcheckbox() | PEAR Manual | HTML_QuickForm_advcheckbox::getPrivateName()


HTML_QuickForm_advcheckbox::getPrivateName()

HTML_QuickForm_advcheckbox::getPrivateName()

HTML_QuickForm_advcheckbox::getPrivateName() – Gets the private name for the element

Synopsis

require_once 'HTML/QuickForm/advcheckbox.php';

string HTML_QuickForm_advcheckbox::getPrivateName ( string $elementName )

Description

This is the name that will be used by the actual checkbox.

Parameter

string $elementName

The element name to make private

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
HTML_QuickForm_advcheckbox::getOnclickJs() | PEAR Manual | HTML_QuickForm_advcheckbox::setValues()


HTML_QuickForm_advcheckbox::setValues()

HTML_QuickForm_advcheckbox::setValues()

HTML_QuickForm_advcheckbox::setValues() – Sets the values used by the hidden element

Synopsis

require_once 'HTML/QuickForm/advcheckbox.php';

void HTML_QuickForm_advcheckbox::setValues ( mixed $values )

Description

If $values is a string then it will be used for checked state. If it is an array, then $values[0] will be used for unchecked state and $values[1] for checked.

Parameter

mixed $values

The values, either a string or an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
HTML_QuickForm_advcheckbox::getPrivateName() | PEAR Manual | Class Summary HTML_QuickForm_autocomplete


Class Summary HTML_QuickForm_autocomplete

Class Summary HTML_QuickForm_autocomplete

Class Summary HTML_QuickForm_autocomplete – HTML class for a text field with autocompletion feature

Description

The element looks like a normal HTML input text element that at every keypressed javascript event searches the array of options for a match and autocompletes the text in case of match. This is similar to the browsers' behaviour when one enters the URL into the Address field.

Class Trees for HTML_QuickForm_autocomplete

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_input

        • HTML_QuickForm_text

          • HTML_QuickForm_text

HTML_QuickForm_autocomplete Inherited Methods

Inherited from HTML_QuickForm_text
Method Name | Summary
HTML_QuickForm_text::HTML_QuickForm_text() | Class constructor
HTML_QuickForm_text::setMaxLength() | Sets maxlength of text field
HTML_QuickForm_text::setSize() | Sets size of text field

Inherited from HTML_QuickForm_input
Method Name | Summary
Constructor HTML_QuickForm_input::HTML_QuickForm_input() | Class constructor
HTML_QuickForm_input::exportValue() | We don't need values from button-type elements (except submit) and files
HTML_QuickForm_input::getName() | Returns the element name
HTML_QuickForm_input::getValue() | Returns the value of the form element
HTML_QuickForm_input::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_input::setName() | Sets the input field name
HTML_QuickForm_input::setType() | Sets the element type
HTML_QuickForm_input::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
HTML_QuickForm_advcheckbox::setValues() | PEAR Manual | constructor HTML_QuickForm_autocomplete


constructor HTML_QuickForm_autocomplete

constructor HTML_QuickForm_autocomplete

constructor HTML_QuickForm_autocomplete – Class constructor

Synopsis

require_once 'HTML/QuickForm/autocomplete.php';

void constructor HTML_QuickForm_autocomplete::HTML_QuickForm_autocomplete ( string $elementName = null , string $elementLabel = null , array $options = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

string $elementLabel

(optional)Input field label

array $options

Autocomplete options

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_autocomplete | PEAR Manual | HTML_QuickForm_autocomplete::setoptions()


HTML_QuickForm_autocomplete::setoptions()

HTML_QuickForm_autocomplete::setoptions()

HTML_QuickForm_autocomplete::setoptions() – Sets the options for the autocomplete input text element

Synopsis

require_once 'HTML/QuickForm/autocomplete.php';

void HTML_QuickForm_autocomplete::setOptions ( array $options )

Description

The strings in this array will be checked by the javascript function for a match with the text being typed. In case of a match the text will be autocompleted.

Parameter

array $options

Array of options for the autocomplete input text element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
constructor HTML_QuickForm_autocomplete | PEAR Manual | Class Summary HTML_QuickForm_date


Class Summary HTML_QuickForm_date

Class Summary HTML_QuickForm_date

Class Summary HTML_QuickForm_date – Class for a group of elements used to input dates (and times).

Description

The element is basically a group of <select>s that allow to input dates and times.

Class Trees for HTML_QuickForm_date

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_group

        • HTML_QuickForm_date

HTML_QuickForm_date Inherited Methods

Inherited from HTML_QuickForm_group
Method Name | Summary
Constructor HTML_QuickForm_group::HTML_QuickForm_group() | Class constructor
HTML_QuickForm_group::accept() | Accepts a renderer
HTML_QuickForm_group::exportValue() | As usual, to get the group's value we access its elements and call
HTML_QuickForm_group::getElementName() | Returns the element name inside the group such as found in the html form
HTML_QuickForm_group::getElements() | Gets the grouped elements
HTML_QuickForm_group::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_group::getGroupType() | Gets the group type based on its elements Will return 'mixed' if elements contained in the group are of different types.
HTML_QuickForm_group::getName() | Returns the group name
HTML_QuickForm_group::getValue() | Returns the value of the group
HTML_QuickForm_group::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_group::setElements() | Sets the grouped elements
HTML_QuickForm_group::setName() | Sets the group name
HTML_QuickForm_group::setValue() | Sets values for group's elements

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
HTML_QuickForm_autocomplete::setoptions() | PEAR Manual | constructor HTML_QuickForm_date()


constructor HTML_QuickForm_date()

constructor HTML_QuickForm_date()

constructor HTML_QuickForm_date() – Class constructor

Synopsis

require_once 'HTML/QuickForm/date.php';

void constructor HTML_QuickForm_date::HTML_QuickForm_date ( string $elementName = null , mixed $elementLabel = null , array $options = array() , mixed $attributes = null )

Description

The $options parameter controls the element's appearance. It is an associative array of the form 'option name' => 'option value'.

'language'

Language code to use for display. Default is 'en'.

date element supports many languages. If your one is not supported, send us the translation, we'll gladly include it.

'format'

Format string for the date, based on PHP's date() function. The following characters are recognised:

D => Short names of days
l => Long names of days
d => Day numbers
M => Short names of months
F => Long names of months
m => Month numbers
Y => Four digit year
y => Two digit year
h => 12 hour format
H => 23 hour format
i => Minutes
s => Seconds
a => am/pm
A => AM/PM
g => 12 hour format w/o leading zeroes
W => week of the year

Default is 'dMY'.

'minYear'

Minimum year in year select. Default is 2001.

'maxYear'

Maximum year in year select. Default is 2010.

Note: On 'minYear' and 'maxYear'
 When 'minYear' > 'maxYear' the years in the select will be displayed in descending order.
'addEmptyOption'

Should an empty option be added to the top of each select box? Default is FALSE. This may be set for individual fields also, if one passes an array of the form array('format char' => TRUE, ..., 'another format char' => FALSE)

'emptyOptionValue'

The value passed by the empty option. Default is ''.

'emptyOptionText'

The text displayed for the empty option. Default is '&nbsp;'. This may be set for individual fields also, if one passes an array of the form array('format char' => 'some text', ..., 'another format char' => 'some other text')

'optionIncrement'

Step to increase the option values by. Works for 'i' and 's' formats currently. Default is array('i' => 1, 's' => 1).

Parameter

string $elementName

Element's name

mixed $elementLabel

Label(s) for an element

array $options

Options to control the element's display

mixed $attributes

Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_date | PEAR Manual | Class Summary HTML_QuickForm_header


Class Summary HTML_QuickForm_header

Class Summary HTML_QuickForm_header

Class Summary HTML_QuickForm_header – A pseudo-element used for adding headers to form

Description

This element is used for adding headers to the form. Unlike usual static elements, the headers are usually rendered using a special template.

Class Trees for HTML_QuickForm_header

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_static

        • HTML_QuickForm_header

HTML_QuickForm_header Inherited Methods

Inherited from HTML_QuickForm_static
Method Name | Summary
Constructor HTML_QuickForm_static::HTML_QuickForm_static() | Class constructor
HTML_QuickForm_static::exportValue() | We override this here because we don't want any values from static elements
HTML_QuickForm_static::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_static::getName() | Returns the element name
HTML_QuickForm_static::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_static::setName() | Sets the element name
HTML_QuickForm_static::setText() | Sets the text
HTML_QuickForm_static::setValue() | Sets the text (uses the standard setValue call to emulate a form element.

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
constructor HTML_QuickForm_date() | PEAR Manual | constructor HTML_QuickForm_header()


constructor HTML_QuickForm_header()

constructor HTML_QuickForm_header()

constructor HTML_QuickForm_header() – Class constructor

Synopsis

require_once 'HTML/QuickForm/header.php';

void constructor HTML_QuickForm_header::HTML_QuickForm_header ( string $elementName = null , string $text = null )

Description

This package is not documented yet.

Parameter

string $elementName

Header name

string $text

Header text

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_header | PEAR Manual | Class Summary HTML_QuickForm_hiddenselect


Class Summary HTML_QuickForm_hiddenselect

Class Summary HTML_QuickForm_hiddenselect

Class Summary HTML_QuickForm_hiddenselect – Creates hidden elements with select's values

Description

This class takes the same arguments as a select element, but instead of creating a <select> it creates hidden elements for all values already selected with setDefaults() or setConstants(). This is useful if you have a select ring that you don't want visible, but you need all selected values to be passed.

Class Trees for HTML_QuickForm_hiddenselect

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_select

        • HTML_QuickForm_hiddenselect

HTML_QuickForm_hiddenselect Inherited Methods

Inherited from HTML_QuickForm_select
Method Name | Summary
Constructor HTML_QuickForm_select::HTML_QuickForm_select() | Class constructor
HTML_QuickForm_select::addOption() | Adds a new OPTION to the SELECT
HTML_QuickForm_select::apiVersion() | Returns the current API version
HTML_QuickForm_select::exportValue() | We check the options and return only the values that _could_ have been
HTML_QuickForm_select::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_select::getMultiple() | Returns the select mutiple attribute
HTML_QuickForm_select::getName() | Returns the element name
HTML_QuickForm_select::getPrivateName() | Returns the element name (possibly with brackets appended)
HTML_QuickForm_select::getSelected() | Returns an array of the selected values
HTML_QuickForm_select::getSize() | Returns the select field size
HTML_QuickForm_select::getValue() | Returns an array of the selected values
HTML_QuickForm_select::load() | Loads options from different types of data sources
HTML_QuickForm_select::loadArray() | Loads the options from an associative array
HTML_QuickForm_select::loadDbResult() | Loads the options from DB_result object
HTML_QuickForm_select::loadQuery() | Queries a database and loads the options from the results
HTML_QuickForm_select::setMultiple() | Sets the select mutiple attribute
HTML_QuickForm_select::setName() | Sets the input field name
HTML_QuickForm_select::setSelected() | Sets the default values of the select box
HTML_QuickForm_select::setSize() | Sets the select field size, only applies to 'multiple' selects
HTML_QuickForm_select::setValue() | Sets the value of the form element

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
constructor HTML_QuickForm_header() | PEAR Manual | constructor HTML_QuickForm_hiddenselect()


constructor HTML_QuickForm_hiddenselect()

constructor HTML_QuickForm_hiddenselect()

constructor HTML_QuickForm_hiddenselect() – Class constructor

Synopsis

require_once 'HTML/QuickForm/hiddenselect.php';

void constructor HTML_QuickForm_hiddenselect::HTML_QuickForm_hiddenselect ( string $elementName = null , mixed $elementLabel = null , mixed $options = null , mixed $attributes = null )

Description

Note that some parameters are unused, as the element is in fact hidden.

Parameter

string $elementName

Select name attribute

mixed $elementLabel

Label(s) for the select (not used)

mixed $options

Data to be used to populate options

mixed $attributes

Either a typical HTML attribute string or an associative array (not used)

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_hiddenselect | PEAR Manual | Class Summary HTML_QuickForm_hierselect


Class Summary HTML_QuickForm_hierselect

Class Summary HTML_QuickForm_hierselect

Class Summary HTML_QuickForm_hierselect – Class to dynamically create chained HTML Select elements, each select changes the content of the next.

Description

Class to dynamically create "chained" HTML Select elements. Choosing an option in the first <select> changes the content of the second select and so on.

This element is considered as a group. Selects will be named groupName[0], groupName[1], ...

Creating a hierselect element based on values from a database table

<?php
require_once 'HTML/QuickForm.php';
$form = new HTML_QuickForm('example');

$form->setDefaults(array('test' => array('4','15')));
$sel =& $form->addElement('hierselect', 'test', 'Test:', null, '/');

$mainOptions = $db->getAssoc('select pkparent, par_desc from parent');

$result = $db->query("select fk_parent, pkchild, chi_desc from child");
while ($result->fetchInto($row)) {
    $secOptions[$row[0]][$row[1]] = $row[2];
}
// Using setMainOptions and setSecOptions is now deprecated
// use setOptions.

$sel->setOptions(array($mainOptions, $secOptions));

$form->display();
?>

Creating more than two select elements is just as simple.

Creating a hierselect element with three select elements

<?php
require_once 'HTML/QuickForm.php';
$form = new HTML_QuickForm('example');

$select1[0] = 'Pop';
$select1[1] = 'Classical';
$select1[2] = 'Funeral doom';

// second select
$select2[0][0] = '--- Artist ---';
$select2[0][1] = 'Red Hot Chil Peppers';
$select2[0][2] = 'The Pixies';

$select2[1][0] = '--- Artist ---';
$select2[1][1] = 'Wagner';
$select2[1][2] = 'Strauss';

$select2[2][0] = '--- Artist ---';
$select2[2][1] = 'Pantheist';
$select2[2][2] = 'Skepticism';

// Create a third select with prices for the cds
$select3[0][0][0] = '--- Choose the artist ---';
$select3[0][1][0] = '15.00$';
$select3[0][2][1] = '17.00$';
$select3[1][0][0] = '--- Choose the artist ---';
$select3[1][1][0] = '15.00$';
$select3[1][2][1] = '17.00$';
$select3[2][0][0] = '--- Choose the artist ---';
$select3[2][1][0] = '15.00$';
$select3[2][2][1] = '17.00$';

// Create the Element
$sel =& $form->addElement('hierselect', 'cds', 'Choose CD:');

// And add the selection options
$sel->setOptions(array($select1, $select2, $select3));

$form->display();
?>

Class Trees for HTML_QuickForm_hierselect

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_group

        • HTML_QuickForm_hierselect

HTML_QuickForm_hierselect Inherited Methods

Inherited from HTML_QuickForm_group
Method Name | Summary
Constructor HTML_QuickForm_group::HTML_QuickForm_group() | Class constructor
HTML_QuickForm_group::accept() | Accepts a renderer
HTML_QuickForm_group::exportValue() | As usual, to get the group's value we access its elements and call
HTML_QuickForm_group::getElementName() | Returns the element name inside the group such as found in the html form
HTML_QuickForm_group::getElements() | Gets the grouped elements
HTML_QuickForm_group::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_group::getGroupType() | Gets the group type based on its elements Will return 'mixed' if elements contained in the group are of different types.
HTML_QuickForm_group::getName() | Returns the group name
HTML_QuickForm_group::getValue() | Returns the value of the group
HTML_QuickForm_group::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_group::setElements() | Sets the grouped elements
HTML_QuickForm_group::setName() | Sets the group name
HTML_QuickForm_group::setValue() | Sets values for group's elements

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
constructor HTML_QuickForm_hiddenselect() | PEAR Manual | constructor HTML_QuickForm_hierselect()


constructor HTML_QuickForm_hierselect()

constructor HTML_QuickForm_hierselect()

constructor HTML_QuickForm_hierselect() – Class constructor

Synopsis

require_once 'HTML/QuickForm/hierselect.php';

void constructor HTML_QuickForm_hierselect::HTML_QuickForm_hierselect ( string $elementName = null , string $elementLabel = null , mixed $attributes = null , mixed $separator = null )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Input field name attribute

Note: If you are displaying several forms on one page, then hierselects in these forms should have unique names. In the other case the values for last hierselect with the same name will overwrite the values for the previous one. It is extremely difficult to cleanly fix this behaviour with current QuickForm architecture, therefore please rely on this workaround. See Request #5718.

string $elementLabel

(optional)Input field label in form

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array.

mixed $separator

String to separate the grouped elements

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_hierselect | PEAR Manual | HTML_QuickForm_hierselect::setOptions()


HTML_QuickForm_hierselect::setOptions()

HTML_QuickForm_hierselect::setOptions()

HTML_QuickForm_hierselect::setOptions() – Sets the options for the select elements

Synopsis

require_once 'HTML/QuickForm/hierselect.php';

void HTML_QuickForm_hierselect::setOptions ( array $options )

Description

Sets the options for the select elements within hierselect. Note that the actual number of selects that will be displayed is governed by the number of the elements in the array passed to this function.

Parameter

array $options

Array of options for the elements, having the following structure:

array(
// options for the first element
array(
'key_1' => 'value 1',
'key_2' => 'value 2',
...
'key_N' => 'value N',
),
// options for the second element
array(
'key_1' => array(
'key_1_1' => 'value 1.1',
'key_1_2' => 'value 1.2',
...
'key_1_M1' => 'value 1.M1'
),
'key_2' => array(
'key_2_1' => 'value 2.1',
'key_2_2' => 'value 2.2',
...
'key_2_M2' => 'value 2.M2'
),
...
'key_N' => array(
'key_N_1' => 'value N.1',
'key_N_2' => 'value N.2',
...
'key_N_MN' => 'value N.MN'
)
)
// options for further elements
...
)
Note: The options for subsequent elements should have keys for all options of the previous elements. Having a select without options is invalid HTML and will break hierselect's JavaScript. See also Bug #5218.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.2

Example

Setting the hierselect options

<?php
$select1 = $select2 = $select3 = array();

$select1[0] = 'Pop';
$select1[1] = 'Classical';
$select1[2] = 'Funeral doom';

// second select
$select2[0][0] = '--- Artist ---';
$select2[0][1] = 'Red Hot Chil Peppers';
$select2[0][2] = 'The Pixies';

$select2[1][0] = '--- Artist ---';
$select2[1][1] = 'Wagner';
$select2[1][2] = 'Strauss';

$select2[2][0] = '--- Artist ---';
$select2[2][1] = 'Pantheist';
$select2[2][2] = 'Skepticism';

// Create a third select with prices for the cds
$select3[0][0][0] = '--- Choose the artist ---';
$select3[0][1][0] = '15.00$';
$select3[0][2][1] = '17.00$';
$select3[1][0][0] = '--- Choose the artist ---';
$select3[1][1][0] = '15.00$';
$select3[1][2][1] = '17.00$';
$select3[2][0][0] = '--- Choose the artist ---';
$select3[2][1][0] = '15.00$';
$select3[2][2][1] = '17.00$';

// Create the Element
$sel =& $form->addElement('hierselect', 'cds', 'Choose CD:');

// And add the selection options
$sel->setOptions(array($select1, $select2, $select3));
?>
Prev | Custom elements | Next
constructor HTML_QuickForm_hierselect() | PEAR Manual | HTML_QuickForm_hierselect::setMainOptions()


HTML_QuickForm_hierselect::setMainOptions()

HTML_QuickForm_hierselect::setMainOptions()

HTML_QuickForm_hierselect::setMainOptions() – DEPRECATED: Sets the options for the first select

Synopsis

require_once 'HTML/QuickForm/hierselect.php';

void HTML_QuickForm_hierselect::setMainOptions ( array $options )

Description

Format is standard key/value pairs for select elements. Example is available in the docs for setSecOptions().

This method has been deprecated. Use setOptions() instead.

Parameter

array $options

Array of options for the first select

Throws

throws no exceptions thrown

See

see HTML_QuickForm_select::loadArray(), setSecOptions().

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 3.2.2

Prev | Custom elements | Next
HTML_QuickForm_hierselect::setOptions() | PEAR Manual | HTML_QuickForm_hierselect::setSecOptions()


HTML_QuickForm_hierselect::setSecOptions()

HTML_QuickForm_hierselect::setSecOptions()

HTML_QuickForm_hierselect::setSecOptions() – DEPRECATED: Sets the options for the secondary select

Synopsis

require_once 'HTML/QuickForm/hierselect.php';

void HTML_QuickForm_hierselect::setSecOptions ( array $options )

Description

Sets the options for the secondary select. Options are passed as a two-dimensional array, where the first key is parent id and the second key is child id, as it is needed to know the parent option to which the secondary option relates.

This method has been deprecated. Use setOptions() instead.

Parameter

array $options

Array of options for the second select

Throws

throws no exceptions thrown

See

see setMainOptions().

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 3.2.2

Example

Setting the hierselect options

<?php
$hierSel =& $form->addElement('hierselect', 'test', 'Test:', null, '/');

$main[0] = 'Pop';
$main[1] = 'Classical';
$main[2] = 'Funeral doom';

$sec[0][1] = 'Red Hot Chili Peppers';
$sec[0][2] = 'The Pixies';
$sec[1][3] = 'Wagner';
$sec[1][4] = 'Strauss';
$sec[2][5] = 'Pantheist';
$sec[2][6] = 'Skepticism';

$hierSel->setMainOptions($main);
$hierSel->setSecOptions($sec);
?>
Prev | Custom elements | Next
HTML_QuickForm_hierselect::setMainOptions() | PEAR Manual | Class Summary HTML_QuickForm_html


Class Summary HTML_QuickForm_html

Class Summary HTML_QuickForm_html

Class Summary HTML_QuickForm_html – A pseudo-element used for adding raw HTML to form (deprecated)

Description

A pseudo-element used for adding raw HTML to form output. Its contents are output as is, without applying any element template.

This element is deprecated. No fixes and changes to its behaviour will be done and it will be removed in the next major version of the package. If you really need to add raw html to the form, you may consider using 'static' element instead.

The element can be used with the Default Renderer only, all other Renderers completely ignore this. Consider using some template-based renderer instead of relying on this feature.

Class Trees for HTML_QuickForm_html

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_static

        • HTML_QuickForm_html

HTML_QuickForm_html Inherited Methods

Inherited from HTML_QuickForm_static
Method Name | Summary
Constructor HTML_QuickForm_static::HTML_QuickForm_static() | Class constructor
HTML_QuickForm_static::exportValue() | We override this here because we don't want any values from static elements
HTML_QuickForm_static::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_static::getName() | Returns the element name
HTML_QuickForm_static::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_static::setName() | Sets the element name
HTML_QuickForm_static::setText() | Sets the text
HTML_QuickForm_static::setValue() | Sets the text (uses the standard setValue call to emulate a form element.

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
HTML_QuickForm_hierselect::setSecOptions() | PEAR Manual | constructor HTML_QuickForm_html()


constructor HTML_QuickForm_html()

constructor HTML_QuickForm_html()

constructor HTML_QuickForm_html() – Class constructor

Synopsis

require_once 'HTML/QuickForm/html.php';

void constructor HTML_QuickForm_html::HTML_QuickForm_html ( string $text = null )

Description

This package is not documented yet.

Parameter

string $text

raw HTML to add

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_html | PEAR Manual | Class Summary HTML_QuickForm_link


Class Summary HTML_QuickForm_link

Class Summary HTML_QuickForm_link

Class Summary HTML_QuickForm_link – HTML class for a link type field

Description

This is used to add <a href="...">...</a> tag within a standard element template.

Class Trees for HTML_QuickForm_link

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_static

        • HTML_QuickForm_link

HTML_QuickForm_link Inherited Methods

Inherited from HTML_QuickForm_static
Method Name | Summary
Constructor HTML_QuickForm_static::HTML_QuickForm_static() | Class constructor
HTML_QuickForm_static::exportValue() | We override this here because we don't want any values from static elements
HTML_QuickForm_static::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_static::getName() | Returns the element name
HTML_QuickForm_static::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_static::setName() | Sets the element name
HTML_QuickForm_static::setText() | Sets the text
HTML_QuickForm_static::setValue() | Sets the text (uses the standard setValue call to emulate a form element.

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
constructor HTML_QuickForm_html() | PEAR Manual | constructor HTML_QuickForm_link()


constructor HTML_QuickForm_link()

constructor HTML_QuickForm_link()

constructor HTML_QuickForm_link() – Class constructor

Synopsis

require_once 'HTML/QuickForm/link.php';

void constructor HTML_QuickForm_link::HTML_QuickForm_link ( mixed $elementName = null , string $elementLabel = null , string $href = null , string $text = null , mixed $attributes = null )

Description

This package is not documented yet.

Parameter

mixed $elementName

string $elementLabel

(optional)Link label

string $href

(optional)Link href

string $text

(optional)Link display text

mixed $attributes

(optional)Either a typical HTML attribute string or an associative array

Throws

throws

Note

since 1.0

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_link | PEAR Manual | HTML_QuickForm_link::setHref()


HTML_QuickForm_link::setHref()

HTML_QuickForm_link::setHref()

HTML_QuickForm_link::setHref() – Sets the links href

Synopsis

require_once 'HTML/QuickForm/link.php';

void HTML_QuickForm_link::setHref ( string $href )

Description

This is just a shortcut for

<?php
$element->updateAttributes(array('href' => $href));
?>

Parameter

string $href

Throws

throws

Note

since 1.0

This function can not be called statically.

Prev | Custom elements | Next
constructor HTML_QuickForm_link() | PEAR Manual | Class Summary HTML_QuickForm_static


Class Summary HTML_QuickForm_static

Class Summary HTML_QuickForm_static

Class Summary HTML_QuickForm_static – HTML class for static data

Description

A static element is an element that cannot have a submit value and thus cannot change due to user input. Such elements are usually used to improve form presentation. Note that elements of HTML_QuickForm_static type are by default rendered inside the same template as the normal form elements.

Class Trees for HTML_QuickForm_static

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_static

Classes that extend HTML_QuickForm_static
Class | Summary
HTML_QuickForm_header | A pseudo-element used for adding headers to form
HTML_QuickForm_html | A pseudo-element used for adding raw HTML to form
HTML_QuickForm_link | HTML class for a link type field

HTML_QuickForm_static Inherited Methods

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Custom elements | Next
HTML_QuickForm_link::setHref() | PEAR Manual | constructor HTML_QuickForm_static()


constructor HTML_QuickForm_static()

constructor HTML_QuickForm_static()

constructor HTML_QuickForm_static() – Class constructor

Synopsis

require_once 'HTML/QuickForm/static.php';

void constructor HTML_QuickForm_static::HTML_QuickForm_static ( string $elementName = null , mixed $elementLabel = null , string $text = null )

Description

This package is not documented yet.

Parameter

string $elementName

Name of the element

mixed $elementLabel

(optional)Label

string $text

(optional)Display text

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
Class Summary HTML_QuickForm_static | PEAR Manual | HTML_QuickForm_static::setText()


HTML_QuickForm_static::setText()

HTML_QuickForm_static::setText()

HTML_QuickForm_static::setText() – Sets the text

Synopsis

require_once 'HTML/QuickForm/static.php';

void HTML_QuickForm_static::setText ( string $text )

Description

This text is essentially the static element itself. Note that setValue() is an alias for setText().

Parameter

string $text

text of the element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Custom elements | Next
constructor HTML_QuickForm_static() | PEAR Manual | Using groups


Using groups

Using groups

Table of Contents
  • HTML_QuickForm::addGroup() -- Adds an element group
  • Class Summary HTML_QuickForm_group -- HTML class for a form element group
  • constructor HTML_QuickForm_group() -- Class constructor
  • HTML_QuickForm_group::getElementName() -- Returns the name of an element inside the group
  • HTML_QuickForm_group::getElements() -- Gets the grouped elements
  • HTML_QuickForm_group::getGroupType() -- Gets the group type based on its elements.
  • HTML_QuickForm_group::setElements() -- Sets the grouped elements

To be written.

Prev | HTML_QuickForm | Next
HTML_QuickForm_static::setText() | PEAR Manual | HTML_QuickForm::addGroup()


HTML_QuickForm::addGroup()

HTML_QuickForm::addGroup()

HTML_QuickForm::addGroup() – Adds an element group

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::addGroup ( array $elements , string $name = null , mixed $groupLabel = '' , string $separator = null , string $appendName = true )

Description

Adds an element group.

Parameter

array $elements

array of elements composing the group

string $name

(optional) group name

mixed $groupLabel

(optional) group label

mixed $separator

(optional) string or array of strings to separate elements

boolean $appendName

(optional) specify whether the group name should be used in the form element name: groupName[elementName] vs elementName

Return value

return reference to added group of elements

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_ELEMENT_NAME | Element '$elementName ' already exists in HTML_QuickForm::addElement() | Tried to add a group having a name of an existing element | Choose a different name for a group

Note

since 2.8

This function can not be called statically.

Example

Using addGroup()

<?php

$group[] =& HTML_QuickForm::createElement('text', 'first', 'First');
$group[] =& HTML_QuickForm::createElement('text', 'last', 'Last');

$form->addGroup($group, 'name', 'Name:', ',&nbsp;');

?>
Prev | Using groups | Next
Using groups | PEAR Manual | Class Summary HTML_QuickForm_group


Class Summary HTML_QuickForm_group

Class Summary HTML_QuickForm_group

Class Summary HTML_QuickForm_group – HTML class for a form element group

Description

Groups allow you to combine several individual elements into one entity and to use it as usual form element. Most of the group's methods use the methods of the grouped elements to do their job. For example, groups do not have values themselves, their setValue() and getValue() methods just call the appropriate methods of grouped elements to set and get their values.

Groups can be used both for visual grouping of the elements (e.g. putting "Submit" and "Reset" buttons on one line), grouping of the elements with the same name (e.g. groups of checkboxes and radiobuttons) and logical grouping of the elements (e.g. group for person's name consisting of two text fields for first and last name).

Class Trees for HTML_QuickForm_group

  • HTML_Common

    • HTML_QuickForm_element

      • HTML_QuickForm_group

Classes that extend HTML_QuickForm_group
Class | Summary
HTML_QuickForm_date | Class for a group of elements used to input dates (and times).
HTML_QuickForm_hierselect | Class to dynamically create two HTML Select elements The first select changes the content of the second select.

HTML_QuickForm_group Inherited Methods

Inherited from HTML_QuickForm_element
Method Name | Summary
Constructor HTML_QuickForm_element::HTML_QuickForm_element() | Class constructor
HTML_QuickForm_element::accept() | Accepts a renderer
HTML_QuickForm_element::apiVersion() | Returns the current API version
HTML_QuickForm_element::exportValue() | Returns a 'safe' element's value
HTML_QuickForm_element::freeze() | Freeze the element so that only its value is returned
HTML_QuickForm_element::getFrozenHtml() | Returns the value of field without HTML tags
HTML_QuickForm_element::getLabel() | Returns display text for the element
HTML_QuickForm_element::getName() | Returns the element name
HTML_QuickForm_element::getType() | Returns element type
HTML_QuickForm_element::getValue() | Returns the value of the form element
HTML_QuickForm_element::isFrozen() | Returns whether or not the element is frozen
HTML_QuickForm_element::onQuickFormEvent() | Called by HTML_QuickForm whenever form event is made on this element
HTML_QuickForm_element::setLabel() | Sets display text for the element
HTML_QuickForm_element::setName() | Sets the input field name
HTML_QuickForm_element::setPersistantFreeze() | Sets wether an element value should be kept in an hidden field when the element is frozen or not
HTML_QuickForm_element::setValue() | Sets the value of the form element
HTML_QuickForm_element::unfreeze() | Unfreezes the form element
Prev | Using groups | Next
HTML_QuickForm::addGroup() | PEAR Manual | constructor HTML_QuickForm_group()


constructor HTML_QuickForm_group()

constructor HTML_QuickForm_group()

constructor HTML_QuickForm_group() – Class constructor

Synopsis

require_once 'HTML/QuickForm/group.php';

void constructor HTML_QuickForm_group::HTML_QuickForm_group ( string $elementName = null , array $elementLabel = null , array $elements = null , mixed $separator = null , bool $appendName = true )

Description

This package is not documented yet.

Parameter

string $elementName

(optional)Group name

array $elementLabel

(optional)Group label

array $elements

(optional)Group elements

mixed $separator

(optional)Use a string for one separator, use an array to alternate the separators.

boolean $appendName

(optional)whether to change elements' names to the form $groupName[$elementName] or leave them as is.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Using groups | Next
Class Summary HTML_QuickForm_group | PEAR Manual | HTML_QuickForm_group::getElementName()


HTML_QuickForm_group::getElementName()

HTML_QuickForm_group::getElementName()

HTML_QuickForm_group::getElementName() – Returns the name of an element inside the group

Synopsis

require_once 'HTML/QuickForm/group.php';

mixed HTML_QuickForm_group::getElementName ( mixed $index )

Description

Returns the name of an element inside the group. This is the name that will be shown in the form HTML output.

Parameter

mixed $index

Element name or element index in the group

Return value

returns string with element name, false if not found

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

Prev | Using groups | Next
constructor HTML_QuickForm_group() | PEAR Manual | HTML_QuickForm_group::getElements()


HTML_QuickForm_group::getElements()

HTML_QuickForm_group::getElements()

HTML_QuickForm_group::getElements() – Gets the grouped elements

Synopsis

require_once 'HTML/QuickForm/group.php';

array &HTML_QuickForm_group::getElements ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 2.4

This function can not be called statically.

Prev | Using groups | Next
HTML_QuickForm_group::getElementName() | PEAR Manual | HTML_QuickForm_group::getGroupType()


HTML_QuickForm_group::getGroupType()

HTML_QuickForm_group::getGroupType()

HTML_QuickForm_group::getGroupType() – Gets the group type based on its elements.

Synopsis

require_once 'HTML/QuickForm/group.php';

string HTML_QuickForm_group::getGroupType ( )

Description

Will return 'mixed' if elements contained in the group are of different types.

Return value

returns group elements type

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Using groups | Next
HTML_QuickForm_group::getElements() | PEAR Manual | HTML_QuickForm_group::setElements()


HTML_QuickForm_group::setElements()

HTML_QuickForm_group::setElements()

HTML_QuickForm_group::setElements() – Sets the grouped elements

Synopsis

require_once 'HTML/QuickForm/group.php';

void HTML_QuickForm_group::setElements ( array $elements )

Description

This package is not documented yet.

Parameter

array $elements

Array of elements

Throws

throws no exceptions thrown

Note

since 1.1

This function can not be called statically.

Prev | Using groups | Next
HTML_QuickForm_group::getGroupType() | PEAR Manual | Working with elements' values


Working with elements' values

Working with elements' values

Table of Contents
  • Getting, setting and processing element values
  • Validation and filters

This section covers the methods QuickForm offers for managing form element's values and working with submitted values.

Prev | HTML_QuickForm | Next
HTML_QuickForm_group::setElements() | PEAR Manual | Getting, setting and processing element values


Getting, setting and processing element values

Getting, setting and processing element values

Table of Contents
  • HTML_QuickForm::setConstants() -- Sets constant form values
  • HTML_QuickForm::setDefaults() -- Sets default form values
  • HTML_QuickForm::isSubmitted() -- Tells whether the form was already submitted
  • HTML_QuickForm::exportValue() -- Returns the element's "safe" value
  • HTML_QuickForm::exportValues() -- Returns "safe" elements' values
  • HTML_QuickForm::getElementValue() -- Returns the element's raw value
  • HTML_QuickForm::getSubmitValue() -- Returns the submitted element's value
  • HTML_QuickForm::getSubmitValues() -- Returns the values submitted by the form
  • HTML_QuickForm::process() -- Performs the form data processing
Prev | Working with elements' values | Next
Working with elements' values | PEAR Manual | HTML_QuickForm::setConstants()


HTML_QuickForm::setConstants()

HTML_QuickForm::setConstants()

HTML_QuickForm::setConstants() – Sets constant form values

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::setConstants ( array $constantValues = null , mixed $filter = null )

Description

Sets constant form values. These values won't be overridden by either default (set via setDefaults()) or submitted (POST or GET) values.

Parameter

array $constantValues

values used to fill the form, array('element name' => 'element value')

mixed $filter

(optional) filter(s) to apply to all default values

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_FILTER | Callback function does not exist in QuickForm::setConstants() | Tried to pass a name of a non-existant function as a callback | Check spelling

Note

since 2.0

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
Getting, setting and processing element values | PEAR Manual | HTML_QuickForm::setDefaults()


HTML_QuickForm::setDefaults()

HTML_QuickForm::setDefaults()

HTML_QuickForm::setDefaults() – Sets default form values

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::setDefaults ( array $defaultValues = null , mixed $filter = null )

Description

Sets default form values. There are overriden by either constant (set via setConstants()) or submitted (POST or GET) values.

Parameter

array $defaultValues

values used to fill the form, array('element name' => 'element value')

mixed $filter

(optional) filter(s) to apply to all default values

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_FILTER | Callback function does not exist in QuickForm::setDefaults() | Tried to pass a name of a non-existant function as a callback | Check spelling

Note

since 1.0

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::setConstants() | PEAR Manual | HTML_QuickForm::isSubmitted()


HTML_QuickForm::isSubmitted()

HTML_QuickForm::isSubmitted()

HTML_QuickForm::isSubmitted() – Tells whether the form was already submitted

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::isSubmitted ( ( void )

Description

Tells whether the form was already submitted. Using this method when $trackSubmit parameter of QuickForm's constructor is used is more reliable than checking whether form's submit values are empty.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

since 3.2.5

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::setDefaults() | PEAR Manual | HTML_QuickForm::exportValue()


HTML_QuickForm::exportValue()

HTML_QuickForm::exportValue()

HTML_QuickForm::exportValue() – Returns the element's "safe" value

Synopsis

require_once 'HTML/QuickForm.php';

mixed HTML_QuickForm::exportValue ( string $element )

Description

This method first tries to find a cleaned-up submitted value, it will return a value set by setValue()/setDefaults()/setConstants() if submitted value does not exist for the given element.

The value that couldn't have possibly been submitted (e.g.: an option that is not present in <select> element's option list) is not considered valid and is not returned.

As the values returned by this method and by exportValues() are expected to be immediately processed and/or stored somewhere, values for file elements that obviously have special processing needs are not returned.

Parameter

string $element

Name of the element

Return value

return element value

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::exportValue() | Tried to get a value of a non-existant element | Check the element's name spelling

Note

since 3.1

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::isSubmitted() | PEAR Manual | HTML_QuickForm::exportValues()


HTML_QuickForm::exportValues()

HTML_QuickForm::exportValues()

HTML_QuickForm::exportValues() – Returns "safe" elements' values

Synopsis

require_once 'HTML/QuickForm.php';

array HTML_QuickForm::exportValues ( mixed $elementList = null )

Description

Returns the values for the form elements. First it tries to return filtered submitted values, if there were none then it takes the values set by setDefaults() or setConstants().

Unlike getSubmitValues(), this will return only the values corresponding to the elements added to the form and only the values that could actually be submitted: if we have 'Yes'/'No' radiobuttons 'Maybe' will not be considered a valid submit value. You also cannot get values for file elements via this method.

Parameter

mixed $elementList

Array/string of element names, whose values we want. If not set then return all elements.

Return value

return An assoc array of elements' values

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::exportValue() | Tried to get a value of a non-existant element | Check the element's name spelling

Note

since 3.1

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::exportValue() | PEAR Manual | HTML_QuickForm::getElementValue()


HTML_QuickForm::getElementValue()

HTML_QuickForm::getElementValue()

HTML_QuickForm::getElementValue() – Returns the element's raw value

Synopsis

require_once 'HTML/QuickForm.php';

mixed &HTML_QuickForm::getElementValue ( string $element )

Description

Returns the element's raw value such as submitted by the form (not filtered), set by setDefaults() or setConstants().

Parameter

string $element

Element name

Return value

return element value

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::getElementValue() | Tried to get a value of a non-existant element | Check the element's name spelling

Note

since 2.0

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::exportValues() | PEAR Manual | HTML_QuickForm::getSubmitValue()


HTML_QuickForm::getSubmitValue()

HTML_QuickForm::getSubmitValue()

HTML_QuickForm::getSubmitValue() – Returns the submitted element's value

Synopsis

require_once 'HTML/QuickForm.php';

mixed HTML_QuickForm::getSubmitValue ( string $element )

Description

Returns the submitted element's value. The value is filtered.

Parameter

string $element

Element name

Return value

return submitted element value or NULL if not set

Throws

throws no exceptions thrown

Note

since 2.0

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::getElementValue() | PEAR Manual | HTML_QuickForm::getSubmitValues()


HTML_QuickForm::getSubmitValues()

HTML_QuickForm::getSubmitValues()

HTML_QuickForm::getSubmitValues() – Returns the values submitted by the form

Synopsis

require_once 'HTML/QuickForm.php';

array HTML_QuickForm::getSubmitValues ( bool $mergeFiles = false )

Description

Returns the values submitted by the form, possibly with uploaded files as well.

Parameter

boolean $mergeFiles

Whether uploaded files should be returned too

Throws

throws no exceptions thrown

Note

since 2.0

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::getSubmitValue() | PEAR Manual | HTML_QuickForm::process()


HTML_QuickForm::process()

HTML_QuickForm::process()

HTML_QuickForm::process() – Performs the form data processing

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::process ( mixed $callback , bool $mergeFiles = true )

Description

Performs the form data processing. It actually calls the $callback passing the submitted values (and files, when $mergeFiles =TRUE) to it.

Parameter

mixed $callback

Callback, either function name or array(&$object, 'method')

boolean $mergeFiles

Whether uploaded files should be processed too

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_PROCESS | Callback function does not exist in QuickForm::process() | Tried to pass a name of a non-existant function as a callback | Check spelling

Note

since 1.0

This function can not be called statically.

Prev | Getting, setting and processing element values | Next
HTML_QuickForm::getSubmitValues() | PEAR Manual | Validation and filters


Validation and filters

Validation and filters

Table of Contents
  • Introduction - validation and filters -- How to process submitted data
  • HTML_QuickForm::addRule() -- Adds a validation rule for the given field
  • HTML_QuickForm::addGroupRule() -- Adds a validation rule for the given group
  • HTML_QuickForm::addFormRule() -- Adds a global validation rule
  • HTML_QuickForm::isElementRequired() -- Returns whether the form element is required
  • HTML_QuickForm::validate() -- Performs the server side validation
  • HTML_QuickForm::getElementError() -- Returns error corresponding to validated element
  • HTML_QuickForm::setElementError() -- Set error message for a form element
  • HTML_QuickForm::registerRule() -- Registers a new validation rule
  • HTML_QuickForm::getRegisteredRules() -- Returns registered validation rules
  • HTML_QuickForm::isRuleRegistered() -- Returns whether the rule is supported
  • HTML_QuickForm::applyFilter() -- Applies a filter for the given field(s)

QuickForm also provides validation rules support. You can code your own validation rules, register them in QuickForm and then call them in your script. By default, QuickForm can handle validation against regular expressions (preg_match style) and check for required elements. If you want client-side validation, QuickForm can generate the javascript code needed. Server-side validation is always on by default.

QuickForm can also make use of filters for data import into the form or for data processing once the form has been submitted. Filters work the same way as rules except that you don't need to register them. You write your filter functions and call them in your script. You can call any php function (ie. trim, addslashes, htmlentities, etc.) and have them applied recursively to your element values.

Prev | Working with elements' values | Next
HTML_QuickForm::process() | PEAR Manual | Introduction - validation and filters


Introduction - validation and filters

Introduction - validation and filters

Introduction - validation and filters – How to process submitted data

Validation rules

QuickForm makes client-side and server-side form validation easy. It allows for validation against regular expressions or custom functions and methods. You can define your own validation rules and apply them to the elements or groups you want. In this section, we will explore the different possibilities QuickForm offers to make validation easier.

QuickForm can verify if required elements are filled when the form is submitted. This works with every type of elements or groups, integer 0 is not considered as an empty value.

<?php
require_once 'HTML/QuickForm.php';

$form = new HTML_QuickForm('myform', 'post');
$form->addElement('text', 'email', 'Your email:');
$form->addElement('submit', 'submit', 'Submit');

// Validation rules

$form->addRule('email', 'E-Mail is required', 'required');

// Validation

if ($form->validate()) {
    $form->freeze();
}
$form->display();
?>
Note: On empty elements validation
 If the element is empty, no validation rules other than required are checked for it. This means that empty element can be invalid only when it is required.
Note: On required uploads
 required rule does not work for file elements. Use uploadedfile.

The HTML_QuickForm::validate() method will scan through each rules in the order they have been set. If a rule is not validated, the error message corresponding to the element will be displayed and the form will be shown once again. You can use templates to set the position of this error message. The order you decide to set your validation rules is important because it will determine which error message is used.

Client-side validation

QuickForm can generate the javascript necessary to validate the form on the client side. This feature works for all standard elements and for groups. Server side validation is always performed in case the client has javascript turned off.

<?php
$form->addRule('email', 'E-Mail is required', 'required', null, 'client');
?>
Tip

By setting the parameter 'client', you trigger the javascript automatic generation.

Built-in validation rules

QuickForm offers a few registered rules that are often used when validating forms. Some of the rules may need an extra $format parameter passed to addRule() / addGroupRule() to work properly.

List of built-in validation rules
Name | Description | $format parameter
required | value is not empty
maxlength | value must not exceed given number of characters | number of characters, integer
minlength | value must have more than given number of characters | number of characters, integer
rangelength | value must have between min and max characters | array(min characters, max characters)
regex | value must pass the regular expression | regular expression to check, string
email | value is a correctly formatted email | whether to perform an additional domain check via checkdnsrr() function, boolean
lettersonly | value must contain only letters
alphanumeric | value must contain only letters and numbers
numeric | value must be a number
nopunctuation | value must not contain punctuation characters
nonzero | value must be a number not starting with 0
compare The rule allows to compare the values of two form fields. This can be used for e.g. 'Password repeat must match password' kind of rule. Please note that you need to pass an array of elements' names to compare as a first parameter to addRule().

Type of comparison to perform, string:

'eq' or '=='

(default) the elements should have the same values

'neq' or '!='

the elements should have different values

'gt' or '>'

first element's value should be greater (compared as numbers)

'gte' or '>='

first element's value should be greater or equal (compared as numbers)

'lt' or '<'

first element's value should be smaller (compared as numbers)

'lte' or '<='

first element's value should be smaller or equal (compared as numbers)
callback | This rule allows to use an external function/method for validation. This can be done either explicitly, by passing a callback as a format parameter or implicitly, by registering it via registerRule(). | Function/method to use, callback.
Validation rules for file uploads
uploadedfile | required file upload
maxfilesize | the file size must not exceed the given number of bytes | maximum file size, integer
mimetype | the file must have a correct MIME type | either a string for single allowed MIME type, or an array of allowed MIME types
filename | the filename must match the given regex | regular expression to test, string
Note: On rules for file uploads
 These rules are defined in HTML/QuickForm/file.php, and are automatically registered when a file type element is added to the form. These rules are server-side only, for obvious reasons.

Usage of builtin rules is covered in rules-builtin.php example provided with the package. The rules-custom.php example covers the usage of custom rule classes and callback type rules. It also contains a NumericRange class for checking whether a number is between a maximum and a minimum.

Validation classes

Since release 3.2 all builtin validation is performed by subclasses of HTML_QuickForm_Rule class. You can create your own subclass of it and implement validate() and getValidationScript() methods. Consult the source for the examples.

Validation functions and methods

When you need a more complex validation, QuickForm can use your own custom-made functions to validate an element or a group. QuickForm can also call a method of a class. This way, it is possible to use PEAR's Validate package or any other class. If you want to use your own functions, you basically have two options:

  1. Register the function via registerRule() using 'callback' as $type and giving the new rule a custom $ruleName. Later you add the rule with this name via addRule() like any buitin rule.

  2. Add the rule of callback type via addRule() passing the name of your function as $format. This way you'll have less characters to type, but will be unable to pass additional data to your function.

Email validation function

<?php
/**
 * Validate an email address
 *
 * @param string    $email         Email address to validate
 * @param boolean   $domainCheck   Check if the domain exists
 */
function checkEmail($email, $domainCheck = false)
{
    if (preg_match('/^[a-zA-Z0-9\._-]+\@(\[?)[a-zA-Z0-9\-\.]+'.
                   '\.([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$/', $email)) {
        if ($domainCheck && function_exists('checkdnsrr')) {
            list (, $domain)  = explode('@', $email);
            if (checkdnsrr($domain, 'MX') || checkdnsrr($domain, 'A')) {
                return true;
            }
            return false;
        }
        return true;
    }
    return false;
}
$form->registerRule('checkmail', 'callback', 'checkEmail');
$form->addRule('email', 'Email is incorrect', 'checkmail', true);
?>

You can pass an extra parameter of the type you want to your function when set with HTML_QuickForm::addRule(). Here we used TRUE to enable the DNS check of our function.

If you use a method, you must specify the class your method is in. Use this syntax when you register your rule:

<?php
// Method checkEmail is in class Validate
$form->registerRule('checkmail', 'callback', 'checkEmail', 'Validate');
?>
Tip

You can also use a javascript function to validate your form, give it the same name as your PHP function, have it return a boolean and set the 'client' parameter.

Group validation

Groups of elements can be validated the same way other elements are, or use a more complex validation scheme. To validate a group as a whole, just use HTML_QuickForm::addRule(). The group elements' values will be passed to the validation function as an array.

You can have more complex validation for your groups using the HTML_QuickForm::addGroupRule() method. This allows for a per element validation. It also makes it possible to specify the number of elements that need to be valid for the group to be valid too.

Complex group validation

<?php
// Group
$id[] = &HTML_QuickForm::createElement('text', 'username', 'Username');
$id[] = &HTML_QuickForm::createElement('text', 'code', 'Code');
$form->addGroup($id, 'id', 'Your ID:', '-');

// Validation rules per element

$rule['username'][] = array('Username is required', 'required');
$rule['username'][] = array('Username contains only letters', 'lettersonly');
$rule['username'][] = array('Username has between 5-8 characters', 'rangelength', array(5, 8));

$rule['code'][] = array('Code is required', 'required');
$rule['code'][] = array('Code contains numbers only', 'regex', '/^\d+$/');
$rule['code'][] = array('Code is 5 numbers long', 'rangelength', array(5, 5));

$form->addGroupRule('id', $rule);
?>

In this example, we have set rules for the elements inside our group. Instead of using their names, we could have used their index (determined by the order they were created) in the group, it would speed up the validation process.

The following example takes the same group and will validate the form only if at least one of our two elements is not empty. To achieve this, we use the howmany parameter and set it to 1.

<?php
$form->addGroupRule('id', 'Fill at least one element', 'required', null, 1);
?>

Conclusion

You have seen that QuickForm makes it easy to validate your elements and groups without having to write all the usually necessary code to find the different values. It takes care of required elements, generates the javascript automatically and adds a lot of flexibility by allowing you to use your own validation functions and regular expressions. It's time to experiment...

Filters

If we add a rule like

<?php
$form->addRule('element', 'The element is required', 'required');
?>

to the form, then any input will satisfy it, including, for example, a single space. This is because the rule simply ensures that there are one or more characters present, and a space character satisfies the rule.

Of course this can be fixed by making a custom regex rule, but there is an easier solution. We usually do not care about leading and trailing spaces at all, and we can make the element's value pass through builtin trim() function before doing any validation on it:

<?php
$form->applyFilter('element', 'trim');
?>

Filters are applied recursively, which means that trim() on an array will work, too. You can pass any valid callback as an argument to applyFilter() method.

Use filters if you want to 'sanitize' user input and do not really care about invalid values.

Prev | Validation and filters | Next
Validation and filters | PEAR Manual | HTML_QuickForm::addRule()


HTML_QuickForm::addRule()

HTML_QuickForm::addRule()

HTML_QuickForm::addRule() – Adds a validation rule for the given field

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::addRule ( mixed $element , string $message , string $type , string $format = '' , string $validation = 'server' , boolean $reset = false , boolean $force = false )

Description

If the element is in fact a group, it will be considered as a whole, an array of group elements' values will be passed to validation function. To validate grouped elements as separate entities, use addGroupRule().

Parameter

mixed $element

Form element name(s). Currently the only builtin rule that expects and correctly handles an array here is compare:

<?php
$form->addElement('password', 'cmpPasswd', 'Password:');
$form->addElement('password', 'cmpRepeat', 'Repeat password:');
$form->addRule(array('cmpPasswd', 'cmpRepeat'), 'The passwords do not match', 'compare', null, 'client');
?>

All other builtin rules will only handle a single element name. callback rules can also handle an array here, but the callback function you provide will obviously need to properly handle an array of values.

string $message

Message to display for invalid data

string $type

Rule type, use getRegisteredRules() to get types. You can also pass a classname for a descendant of HTML_QuickForm_Rule or an instance of such class.

string $format

(optional) Required for extra rule data

string $validation

(optional) Where to perform validation: "server", "client"

boolean $reset

For client-side validation: reset the form element to its original value if there is an error?

boolean $force

Force the rule to be applied, even if the target form element does not exist

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::addRule() | Tried to add a rule for a non-existant element | Check the element's name spelling or use $force to suppress the error.
QUICKFORM_INVALID_RULE | Rule '$type ' is not registered in HTML_QuickForm::addRule() | Rule is not known to QuickForm | Check rule type spelling or use HTML_QuickForm::registerRule().

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
Introduction - validation and filters | PEAR Manual | HTML_QuickForm::addGroupRule()


HTML_QuickForm::addGroupRule()

HTML_QuickForm::addGroupRule()

HTML_QuickForm::addGroupRule() – Adds a validation rule for the given group

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::addGroupRule ( string $group , mixed $arg1 , string $type = '' , string $format = '' , int $howmany = 0 , string $validation = 'server' , bool $reset = false )

Description

Adds a validation rule for the given group of elements

Only groups with a name can be assigned a validation rule. Use addGroupRule() when you need to validate elements inside the group. Also use addRule() if you need to validate the group as a whole.

Parameter

string $group

Form group name

mixed $arg1

Array for multiple elements or error message string for one element. If this is the array, its structure is the following:

array (
'element name or index' => array(
array(rule data),
...
array(rule data)
),
...
'element name or index' => array(
array(rule data),
...
array(rule data)
)
)

rule data here matches the parameters' order and meaning for addRule() method.

Note: If this parameter is an array, all the subsequent parameters are ignored. You should pass all the modifiers for the rules being added within this array (see the example below).
string $type

(optional) Rule type. Use getRegisteredRules() to get types. You can also pass a classname for a descendant of HTML_QuickForm_Rule or an instance of such class.

string $format

(optional) Required for extra rule data

integer $howmany

(optional) How many valid elements should be in the group

string $validation

(optional)Where to perform validation: "server", "client"

boolean $reset

Client-side: whether to reset the element's value to its original state if validation failed.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Group '$group ' does not exist in HTML_QuickForm::addGroupRule() | Tried to add a rule for a non-existant group | Check the group name spelling
QUICKFORM_NONEXIST_ELEMENT | Element '$elementIndex ' not found in group '$group ' in HTML_QuickForm::addGroupRule() | $arg1 is an array and contains an index for an element not present in a group | Check the element index spelling
QUICKFORM_INVALID_RULE | Rule '$type ' is not registered in HTML_QuickForm::addGroupRule() | Rule is not known to QuickForm | Check rule type spelling or use HTML_QuickForm::registerRule().

Note

since 2.5

This function can not be called statically.

Example

Using addGroupRule()

<?php
// a group of 4 checkboxes
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'A', null, 'A');
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'B', null, 'B');
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'C', null, 'C');
$checkbox[] = &HTML_QuickForm::createElement('checkbox', 'D', null, 'D');
$form->addGroup($checkbox, 'ichkABCD', 'ABCD:', array('&nbsp;', '<br />'));
// Simple rule: at least 2 checkboxes should be checked
$form->addGroupRule('ichkABCD', 'Please check at least two boxes', 'required', null, 2);

$idGrp[] = &HTML_QuickForm::createElement('text', 'lastname', 'Name', array('size' => 30));
$idGrp[] = &HTML_QuickForm::createElement('text', 'code', 'Code', array('size' => 5, 'maxlength' => 4));
$form->addGroup($idGrp, 'id', 'ID:', ',&nbsp');
// Complex rule for group's elements
$form->addGroupRule('id', array(
    'lastname' => array(
        array('Name is letters only', 'lettersonly'),
        array('Name is required', 'required', null, 'client')
    ),
    'code' => array(
        array('Code must be numeric', 'numeric')
    )
));
?>
Prev | Validation and filters | Next
HTML_QuickForm::addRule() | PEAR Manual | HTML_QuickForm::addFormRule()


HTML_QuickForm::addFormRule()

HTML_QuickForm::addFormRule()

HTML_QuickForm::addFormRule() – Adds a global validation rule

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::addFormRule ( mixed $rule )

Description

This should be used when you want to add a rule involving several fields or if you want to use some completely custom validation for your form. The rule function/method should return TRUE in case of successful validation and array('element name' => 'error') when there were errors.

Parameter

mixed $rule

A valid callback

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_RULE | Callback function does not exist in HTML_QuickForm::addFormRule() | Tried to pass a name of a non-existant function as a callback | Check spelling

Note

since 3.1

This function can not be called statically.

Example

Using addFormRule()

<?php
require_once ('HTML/QuickForm.php');

$form = new HTML_QuickForm();

// the function checks whether the passwords are the same
function cmpPass($fields)
{
    if (strlen($fields['passwd1']) && strlen($fields['passwd2']) &&
        $fields['passwd1'] != $fields['passwd2']) {
        return array('passwd1' => 'Passwords are not the same');
    }
    return true;
}

$form->addElement('password', 'passwd1', 'Enter password');
$form->addElement('password', 'passwd2', 'Confirm password');

$form->addFormRule('cmpPass');
?>
Prev | Validation and filters | Next
HTML_QuickForm::addGroupRule() | PEAR Manual | HTML_QuickForm::isElementRequired()


HTML_QuickForm::isElementRequired()

HTML_QuickForm::isElementRequired()

HTML_QuickForm::isElementRequired() – Returns whether the form element is required

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::isElementRequired ( string $element )

Description

Returns whether or not the form element is required, i.e. whether a 'required' rule was added for it.

Parameter

string $element

Form element name

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::addFormRule() | PEAR Manual | HTML_QuickForm::validate()


HTML_QuickForm::validate()

HTML_QuickForm::validate()

HTML_QuickForm::validate() – Performs the server side validation

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::validate ( ( void )

Description

Performs the server side validation.

Return value

return TRUE if no error found

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::isElementRequired() | PEAR Manual | HTML_QuickForm::getElementError()


HTML_QuickForm::getElementError()

HTML_QuickForm::getElementError()

HTML_QuickForm::getElementError() – Returns error corresponding to validated element

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::getElementError ( string $element )

Description

Returns error corresponding to validated element. Errors are usually assigned to elements by validate() method.

Parameter

string $element

Name of form element to check

Return value

return error message corresponding to checked element

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::validate() | PEAR Manual | HTML_QuickForm::setElementError()


HTML_QuickForm::setElementError()

HTML_QuickForm::setElementError()

HTML_QuickForm::setElementError() – Set error message for a form element

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::setElementError ( string $element , string $message )

Description

Set error message for a form element. Errors are usually assigned to elements by validate() method. Use this if you need to explicitly set error message for an element.

Parameter

string $element

Name of form element to set error for

string $message

Error message

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::getElementError() | PEAR Manual | HTML_QuickForm::registerRule()


HTML_QuickForm::registerRule()

HTML_QuickForm::registerRule()

HTML_QuickForm::registerRule() – Registers a new validation rule

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::registerRule ( string $ruleName , string $type , string $data1 , string $data2 = null )

Description

Registers a new validation rule

Parameter

string $ruleName

Name of validation rule

string $type

Either: 'regex' or 'callback' ('function' is also kept for backward compatibility). If registering a subclass of HTML_QuickForm_Rule you can pass anything here, preferrably NULL or empty string.

string $data1

Name of function, regular expression, classname of HTML_QuickForm_Rule subclass or an instance of such class.

The callback function needs to return true or false, determining if the rule is passed or not.

string $data2

Object parent of above function, name of the file containing the subclass of HTML_QuickForm_Rule.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::setElementError() | PEAR Manual | HTML_QuickForm::getRegisteredRules()


HTML_QuickForm::getRegisteredRules()

HTML_QuickForm::getRegisteredRules()

HTML_QuickForm::getRegisteredRules() – Returns registered validation rules

Synopsis

require_once 'HTML/QuickForm.php';

array HTML_QuickForm::getRegisteredRules ( ( void )

Description

Returns an array of registered validation rules.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::registerRule() | PEAR Manual | HTML_QuickForm::isRuleRegistered()


HTML_QuickForm::isRuleRegistered()

HTML_QuickForm::isRuleRegistered()

HTML_QuickForm::isRuleRegistered() – Returns whether the rule is supported

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::isRuleRegistered ( string $name )

Description

Returns whether or not the given rule is supported. New rules are registered via registerRule() method.

Parameter

string $name

Validation rule name

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::getRegisteredRules() | PEAR Manual | HTML_QuickForm::applyFilter()


HTML_QuickForm::applyFilter()

HTML_QuickForm::applyFilter()

HTML_QuickForm::applyFilter() – Applies a filter for the given field(s)

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::applyFilter ( mixed $element , mixed $filter )

Description

Applies a data filter for the given field(s). Filter is applied recursively.

Parameter

mixed $element

Form element name or array of such names. Special name '__ALL__' means all the form elements.

mixed $filter

Callback, either function name or array(&$object, 'method')

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_INVALID_FILTER | Callback function does not exist in QuickForm::applyFilter() | Tried to pass a name of a non-existant function as a callback | Check spelling

Note

since 2.0

This function can not be called statically.

Prev | Validation and filters | Next
HTML_QuickForm::isRuleRegistered() | PEAR Manual | Outputting the form


Outputting the form

Outputting the form

Table of Contents
  • Form customization and output helpers
  • Basic renderers
  • Template-based renderers
  • Renderer infrastructure

Your form can be customised in many ways. QuickForm can use different kind of renderers and provides a default one which allows for customization of the form, the elements, the error messages, the headers, the required elements note and the required elements sign. You can also write your own renderers.

Prev | HTML_QuickForm | Next
HTML_QuickForm::applyFilter() | PEAR Manual | Form customization and output helpers


Form customization and output helpers

Form customization and output helpers

Table of Contents
  • HTML_QuickForm::freeze() -- "Freezes" the form's elements
  • HTML_QuickForm::isElementFrozen() -- Checks whether the element is frozen
  • HTML_QuickForm::isFrozen() -- Checks whether the form is frozen
  • HTML_QuickForm::setRequiredNote() -- Sets required note
  • HTML_QuickForm::setJsWarnings() -- Sets JavaScript warning messages
  • HTML_QuickForm::getRequiredNote() -- Returns the required note
  • HTML_QuickForm::getValidationScript() -- Returns the client side validation script
  • HTML_QuickForm::accept() -- Accepts a renderer
  • HTML_QuickForm::defaultRenderer() -- Returns a reference to default renderer object
  • HTML_QuickForm::toArray() -- Returns the form's contents in an array
  • HTML_QuickForm::toHtml() -- Returns an HTML version of the form
  • HTML_QuickForm::display() -- Outputs an HTML version of the form
Prev | Outputting the form | Next
Outputting the form | PEAR Manual | HTML_QuickForm::freeze()


HTML_QuickForm::freeze()

HTML_QuickForm::freeze()

HTML_QuickForm::freeze() – "Freezes" the form's elements

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::freeze ( mixed $elementList = null )

Description

Freezes the elements: elements' values will be displayed without HTML input tags.

Parameter

mixed $elementList

array or string of element(s) to be frozen. If NULL then all the form's elements will be frozen.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
QUICKFORM_NONEXIST_ELEMENT | Element '$element ' does not exist in HTML_QuickForm::freeze() | Tried to freeze a non-existant element | Check the element's name spelling

Note

since 1.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
Form customization and output helpers | PEAR Manual | HTML_QuickForm::isElementFrozen()


HTML_QuickForm::isElementFrozen()

HTML_QuickForm::isElementFrozen()

HTML_QuickForm::isElementFrozen() – Checks whether the element is frozen

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::isElementFrozen ( string $element )

Description

Returns whether or not the form element is frozen.

Parameter

string $element

Form element name

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::freeze() | PEAR Manual | HTML_QuickForm::isFrozen()


HTML_QuickForm::isFrozen()

HTML_QuickForm::isFrozen()

HTML_QuickForm::isFrozen() – Checks whether the form is frozen

Synopsis

require_once 'HTML/QuickForm.php';

boolean HTML_QuickForm::isFrozen ( ( void )

Description

Returns whether or not the whole form is frozen.

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::isElementFrozen() | PEAR Manual | HTML_QuickForm::setRequiredNote()


HTML_QuickForm::setRequiredNote()

HTML_QuickForm::setRequiredNote()

HTML_QuickForm::setRequiredNote() – Sets required note

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::setRequiredNote ( string $note )

Description

Sets the required note. This note is usually displayed below the form when the form contains required fields.

Parameter

string $note

Message indicating some elements are required

Throws

throws no exceptions thrown

Note

since 1.1

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::isFrozen() | PEAR Manual | HTML_QuickForm::setJsWarnings()


HTML_QuickForm::setJsWarnings()

HTML_QuickForm::setJsWarnings()

HTML_QuickForm::setJsWarnings() – Sets JavaScript warning messages

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::setJsWarnings ( string $pref , string $post )

Description

Sets JavaScript warning messages: the first is displayed before element errors, the second after them. Useless if the form had no rules added with 'client' modifier.

Parameter

string $pref

Prefix warning

string $post

Postfix warning

Throws

throws no exceptions thrown

Note

since 1.1

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::setRequiredNote() | PEAR Manual | HTML_QuickForm::getRequiredNote()


HTML_QuickForm::getRequiredNote()

HTML_QuickForm::getRequiredNote()

HTML_QuickForm::getRequiredNote() – Returns the required note

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::getRequiredNote ( ( void )

Description

Returns the required note. This note is usually displayed below the form when the form contains required fields.

Throws

throws no exceptions thrown

Note

since 2.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::setJsWarnings() | PEAR Manual | HTML_QuickForm::getValidationScript()


HTML_QuickForm::getValidationScript()

HTML_QuickForm::getValidationScript()

HTML_QuickForm::getValidationScript() – Returns the client side validation script

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::getValidationScript ( ( void )

Description

Returns JavaScript used to validate the form on client side. Returns an empty string if no rules were added with 'client' modifier.

Throws

throws no exceptions thrown

Note

since 2.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::getRequiredNote() | PEAR Manual | HTML_QuickForm::accept()


HTML_QuickForm::accept()

HTML_QuickForm::accept()

HTML_QuickForm::accept() – Accepts a renderer

Synopsis

require_once 'HTML/QuickForm.php';

void HTML_QuickForm::accept ( object &$renderer )

Description

Accepts a renderer. This method is a part of the Visitor design pattern implementation.

Parameter

object &$renderer

HTML_QuickForm_Renderer object

Throws

throws no exceptions thrown

Note

since 3.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::getValidationScript() | PEAR Manual | HTML_QuickForm::defaultRenderer()


HTML_QuickForm::defaultRenderer()

HTML_QuickForm::defaultRenderer()

HTML_QuickForm::defaultRenderer() – Returns a reference to default renderer object

Synopsis

require_once 'HTML/QuickForm.php';

object &HTML_QuickForm::defaultRenderer ( ( void )

Description

Returns a reference to default renderer object. You can use this method to save a few keystrokes:

<?php
$renderer =& $form->defaultRenderer();
?>

instead of

<?php
require_once 'HTML/QuickForm/Renderer/Default.php';

$renderer =& new HTML_QuickForm_Renderer_Default();
?>

It is also used internally to implement toHtml() and some of the deprecated methods.

Return value

return default renderer object

Throws

throws no exceptions thrown

Note

since 3.0

This function can be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::accept() | PEAR Manual | HTML_QuickForm::toArray()


HTML_QuickForm::toArray()

HTML_QuickForm::toArray()

HTML_QuickForm::toArray() – Returns the form's contents in an array

Synopsis

require_once 'HTML/QuickForm.php';

array HTML_QuickForm::toArray ( boolean $collectHidden = false )

Description

Returns the form's contents in an array, uses Array renderer for this.

Parameter

boolean $collectHidden

Whether to collect hidden elements (passed to the Renderer's constructor)

Return value

return array of form contents, structure is described in renderer documentation.

Throws

throws no exceptions thrown

Note

since 2.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::defaultRenderer() | PEAR Manual | HTML_QuickForm::toHtml()


HTML_QuickForm::toHtml()

HTML_QuickForm::toHtml()

HTML_QuickForm::toHtml() – Returns an HTML version of the form

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::toHtml ( string $in_data = null )

Description

Returns an HTML version of the form, uses Default renderer for this.

Parameter

string $in_data

(optional) Any extra data to insert right before form is rendered. Data will be inserted via addElement('html', $in_data)

Return value

return Html version of the form

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::toArray() | PEAR Manual | HTML_QuickForm::display()


HTML_QuickForm::display()

HTML_QuickForm::display()

HTML_QuickForm::display() – Outputs an HTML version of the form

Synopsis

require_once 'HTML/QuickForm.php';

string HTML_QuickForm::display ( )

Description

Outputs an HTML version of the form, uses Default renderer for this.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

Prev | Form customization and output helpers | Next
HTML_QuickForm::toHtml() | PEAR Manual | Basic renderers


Basic renderers

Basic renderers

Table of Contents
  • Introduction - renderers -- How to output the form
  • HTML_QuickForm_Renderer_Default -- Default renderer
  • HTML_QuickForm_Renderer_Default::clearAllTemplates() -- Clears all templates
  • HTML_QuickForm_Renderer_Default::setElementTemplate() -- Sets element template
  • HTML_QuickForm_Renderer_Default::setFormTemplate() -- Sets form template
  • HTML_QuickForm_Renderer_Default::setGroupElementTemplate() -- Sets template for group elements
  • HTML_QuickForm_Renderer_Default::setGroupTemplate() -- Sets template for a group wrapper
  • HTML_QuickForm_Renderer_Default::setHeaderTemplate() -- Sets header template
  • HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate() -- Sets the template for 'required' note
  • HTML_QuickForm_Renderer_Default::toHtml() -- Returns the HTML
  • HTML_QuickForm_Renderer_Array -- Array representation of the form
  • constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array() -- Constructor
  • HTML_QuickForm_Renderer_Array::setElementStyle() -- Sets a style to use for element rendering
  • HTML_QuickForm_Renderer_Array::toArray() -- Returns the resultant array
  • HTML_QuickForm_Renderer_Object -- Object representation of the form
  • constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object() -- Constructor
  • HTML_QuickForm_Renderer_Object::toObject() -- Returns the resultant object

These renderers are based on pre-3.0 HTML_QuickForm code and require no external classes to do their work.

Prev | Outputting the form | Next
HTML_QuickForm::display() | PEAR Manual | Introduction - renderers


Introduction - renderers

Introduction - renderers

Introduction - renderers – How to output the form

What are renderers?

Before release 3.0, form outputting logic was implemented as methods of HTML_QuickForm class. This led to two problems:

  1. Bloat of the said class (80+ methods!)

  2. Difficulties in adding new output logic (i.e. using template engines)

In release 3.0, new system was implemented. The form output logic is now contained in classes that extend HTML_QuickForm_Renderer, their behaviour is based on Visitor design pattern from the classic "Design Patterns" book. This gives the following advantages:

  1. Code for some particular output method is loaded only when the method is used.

  2. It is much easier to add new output method.

There are 8 renderers available since release 3.1.1, of which 2 are based on pre-3.0 code and 6 are new. The following template engines are directly suported: Smarty, HTML_Template_Sigma, HTML_Template_IT, HTML_Template_Flexy.

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

<?php
// include the renderer class
require_once 'HTML/QuickForm/Renderer/FooBar.php';
// instantiate the renderer
$renderer =& new HTML_QuickForm_Renderer_FooBar($options);
// do some customization
$renderer->adjustSomething('element1', '...');
// ...
$renderer->adjustSomething('elementN', '...');
// process the form
$form->accept($renderer);
// output the results
$renderer->toFooBar();
?>

Actual methods for customization and doing the output will of course depend on renderer type.

Note: Concerning usage examples
 Usage examples provided in the manual are pretty basic. More complex examples for Default renderer can be found in docs/ directory, for all other renderers - in docs/renderers/ directory of HTML_QuickForm.
Prev | Basic renderers | Next
Basic renderers | PEAR Manual | HTML_QuickForm_Renderer_Default


HTML_QuickForm_Renderer_Default

HTML_QuickForm_Renderer_Default

HTML_QuickForm_Renderer_Default – Default renderer

Description

This renderer directly generates and outputs form HTML. It is based on pre-3.0 built-in form output logic.

The renderer has built-in templates for elements, their format is similar to that of HTML_Template_Sigma or HTML_Template_IT (but only placeholders and blocks are supported). When renderer's renderSomething() method is called, it finds the template for the element, makes necessary substitutions and appends the result to the form's HTML.

Usage example

It is recommended to use the Default renderer when you are not using any template engine in your application or do not need to do any customization to form output. It is the fastest way to output a form.

Default renderer usage

<?php
require_once 'HTML/QuickForm/Renderer/Default.php';

$renderer =& new HTML_QuickForm_Renderer_Default();
$form->accept($renderer);

echo $renderer->toHtml();
?>
Tip

HTML_QuickForm::toHtml() method uses the Default renderer internally.

Prev | Basic renderers | Next
Introduction - renderers | PEAR Manual | HTML_QuickForm_Renderer_Default::clearAllTemplates()


HTML_QuickForm_Renderer_Default::clearAllTemplates()

HTML_QuickForm_Renderer_Default::clearAllTemplates()

HTML_QuickForm_Renderer_Default::clearAllTemplates() – Clears all templates

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::clearAllTemplates ( ( void )

Description

Clears all the HTML out of the templates that surround notes, elements, etc.

Useful when you want to use addElement('html', '...') to create a completely custom form look.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default | PEAR Manual | HTML_QuickForm_Renderer_Default::setElementTemplate()


HTML_QuickForm_Renderer_Default::setElementTemplate()

HTML_QuickForm_Renderer_Default::setElementTemplate()

HTML_QuickForm_Renderer_Default::setElementTemplate() – Sets element template

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::setElementTemplate ( string $html , string $element = null )

Description

Sets element template. When called with one parameter, it sets the default element template, when called with two parameters it sets template for the concrete element. The template should include at least the {element} placeholder.

The default element template is

"\n\t<tr>\n\t\t<td align=\"right\" valign=\"top\"><!-- BEGIN required --><span style=\"color: #ff0000\">*</span><!-- END required --><b>{label}</b></td>\n\t\t<td valign=\"top\" align=\"left\"><!-- BEGIN error --><span style=\"color: #ff0000\">{error}</span><br /><!-- END error -->\t{element}</td>\n\t</tr>"

Parameter

string $html

The HTML surrounding an element

string $element

(optional) Name of the element to apply template for

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::clearAllTemplates() | PEAR Manual | HTML_QuickForm_Renderer_Default::setFormTemplate()


HTML_QuickForm_Renderer_Default::setFormTemplate()

HTML_QuickForm_Renderer_Default::setFormTemplate()

HTML_QuickForm_Renderer_Default::setFormTemplate() – Sets form template

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::setFormTemplate ( string $html )

Description

Sets form template. The template should include {attributes} and {content} placeholders.

The default form template is

"\n<form{attributes}>\n<table border=\"0\">\n{content}\n</table>\n</form>"

Parameter

string $html

The HTML surrounding the form tags

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::setElementTemplate() | PEAR Manual | HTML_QuickForm_Renderer_Default::setGroupElementTemplate()


HTML_QuickForm_Renderer_Default::setGroupElementTemplate()

HTML_QuickForm_Renderer_Default::setGroupElementTemplate()

HTML_QuickForm_Renderer_Default::setGroupElementTemplate() – Sets template for group elements

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::setGroupElementTemplate ( string $html , string $group )

Description

Sets element template for elements within a group.

By default, the template is empty.

Parameter

string $html

The HTML surrounding an element

string $group

Name of the group to apply template for

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::setFormTemplate() | PEAR Manual | HTML_QuickForm_Renderer_Default::setGroupTemplate()


HTML_QuickForm_Renderer_Default::setGroupTemplate()

HTML_QuickForm_Renderer_Default::setGroupTemplate()

HTML_QuickForm_Renderer_Default::setGroupTemplate() – Sets template for a group wrapper

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::setGroupTemplate ( string $html , string $group )

Description

Sets template for a group wrapper

This template is contained within a group-as-element template set via setElementTemplate() and contains group's element templates, set via setGroupElementTemplate().

By default, the template is empty.

Parameter

string $html

The HTML surrounding group elements

string $group

Name of the group to apply template for

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::setGroupElementTemplate() | PEAR Manual | HTML_QuickForm_Renderer_Default::setHeaderTemplate()


HTML_QuickForm_Renderer_Default::setHeaderTemplate()

HTML_QuickForm_Renderer_Default::setHeaderTemplate()

HTML_QuickForm_Renderer_Default::setHeaderTemplate() – Sets header template

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::setHeaderTemplate ( string $html )

Description

Sets header template. The template should include the {header} placeholder.

The default header template is

"\n\t<tr>\n\t\t<td style=\"white-space: nowrap; background-color: #CCCCCC;\" align=\"left\" valign=\"top\" colspan=\"2\"><b>{header}</b></td>\n\t</tr>"

Parameter

string $html

The HTML surrounding the header

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::setGroupTemplate() | PEAR Manual | HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate()


HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate()

HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate()

HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate() – Sets the template for 'required' note

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

void HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate ( string $html )

Description

Sets the note indicating required fields template. The template should include the {requiredNote} placeholder.

The default template is

"\n\t<tr>\n\t\t<td></td>\n\t<td align=\"left\" valign=\"top\">{requiredNote}</td>\n\t</tr>"

Parameter

string $html

The HTML surrounding the required note

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::setHeaderTemplate() | PEAR Manual | HTML_QuickForm_Renderer_Default::toHtml()


HTML_QuickForm_Renderer_Default::toHtml()

HTML_QuickForm_Renderer_Default::toHtml()

HTML_QuickForm_Renderer_Default::toHtml() – Returns the HTML

Synopsis

require_once 'HTML/QuickForm/Renderer/Default.php';

string HTML_QuickForm_Renderer_Default::toHtml ( ( void )

Description

Returns the HTML generated for the form.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate() | PEAR Manual | HTML_QuickForm_Renderer_Array


HTML_QuickForm_Renderer_Array

HTML_QuickForm_Renderer_Array

HTML_QuickForm_Renderer_Array – Array representation of the form

Description

This renderer does not output anything itself, it returns the form structure as an array. This array can later be used for generating the output. A usage example is available for this renderer and Smarty template engine, look in docs/renderers directory.

The form array structure is the following:

array(
'frozen' => 'whether the form is frozen',
'javascript' => 'javascript for client-side validation',
'attributes' => 'attributes for <form> tag',
'requirednote => 'note about the required elements',
// if we set the option to collect hidden elements
'hidden' => 'collected html of all hidden elements',
// if there were some validation errors:
'errors' => array(
'1st element name' => 'Error for the 1st element',
...
'nth element name' => 'Error for the nth element'
),
// if there are no headers in the form:
'elements' => array(
element_1,
...
element_N
)
// if there are headers in the form:
'sections' => array(
array(
'header' => 'Header text for the first header',
'name' => 'Name of the first header',
'elements' => array(
element_1,
...
element_K1
)
),
...
array(
'header' => 'Header text for the Mth header',
'elements' => array(
element_1,
...
element_KM
)
)
)
);

where element_i is an array of the form:

array(
'name' => 'element name',
'value' => 'element value',
'type' => 'type of the element',
'frozen' => 'whether element is frozen',
'label' => 'label for the element',
'required' => 'whether element is required',
'error' => 'error associated with the element',
'style' => 'some information about element style (e.g. for Smarty)',
// if element is not a group
'html' => 'HTML for the element'
// if element is a group
'separator' => 'separator for group elements',
'elements' => array(
element_1,
...
element_N
)
);
Tip

HTML_QuickForm::toArray() method uses the Array renderer internally.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Default::toHtml() | PEAR Manual | constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array()


constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array()

constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array()

constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/Array.php';

void HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array ( bool $collectHidden = false bool $staticLabels = false )

Description

This package is not documented yet.

Parameter

boolean $collectHidden

TRUE: collect all hidden elements into string; FALSE: process them as usual form elements

boolean $staticLabels

TRUE: instead of putting an array of labels into the 'label' element of resultant array, create separate keys for them named 'label_$key' where $key is the key in the array of labels (key + 1 if it is numeric). The first element of the array occupies the 'label' element.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Array | PEAR Manual | HTML_QuickForm_Renderer_Array::setElementStyle()


HTML_QuickForm_Renderer_Array::setElementStyle()

HTML_QuickForm_Renderer_Array::setElementStyle()

HTML_QuickForm_Renderer_Array::setElementStyle() – Sets a style to use for element rendering

Synopsis

require_once 'HTML/QuickForm/Renderer/Array.php';

void HTML_QuickForm_Renderer_Array::setElementStyle ( mixed $elementName , string $styleName = null )

Description

Sets a style to use for element rendering (this style can later be checked by e.g. a template engine).

Parameter

mixed $elementName

element name or array ('element name' => 'style name')

string $styleName

style name if $elementName is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array() | PEAR Manual | HTML_QuickForm_Renderer_Array::toArray()


HTML_QuickForm_Renderer_Array::toArray()

HTML_QuickForm_Renderer_Array::toArray()

HTML_QuickForm_Renderer_Array::toArray() – Returns the resultant array

Synopsis

require_once 'HTML/QuickForm/Renderer/Array.php';

array HTML_QuickForm_Renderer_Array::toArray ( ( void )

Description

Returns an array representation of the form built by the renderer.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Array::setElementStyle() | PEAR Manual | HTML_QuickForm_Renderer_Object


HTML_QuickForm_Renderer_Object

HTML_QuickForm_Renderer_Object

HTML_QuickForm_Renderer_Object – Object representation of the form

Description

This renderer does not output anything itself, it returns the form structure as an object. This object can later be used for generating the output. A usage example is available for this renderer and the Flexy template engine, look in docs/renderers directory.

The form object structure is similar to the following:

QuickformForm Object
(
[frozen] =>
[javascript] =>
[attributes] => action="/object.php" method="post" name="form" id="form"
[requirednote] => <span style="font-size:80%; color:#ff0000;">*</span><span style="font-size:80%;"> denotes required field</span>
[hidden] =>
[errors] => stdClass Object
(
)

[elements] => Array
(
[0] => QuickformElement Object
(
[name] => session
[value] => 1234567890
[type] => hidden
[frozen] =>
[label] =>
[required] =>
[error] =>
[style] =>
[html] => <input name="session" type="hidden" value="1234567890" />
[separator] =>
[elements] =>
)

...

)

[sections] => Array
(
[0] => stdClass Object
(
[header] => Personal Information
[elements] => Array
(
[0] => QuickformElement Object
(
[name] => email
[value] =>
[type] => text
[frozen] =>
[label] => Your email:
[required] => 1
[error] =>
[style] =>
[html] => <input name="email" type="text" />
[separator] =>
[elements] =>
)

...

)

)

...

)

)
Tip

HTML_QuickForm::toObject() method uses the object renderer internally.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Array::toArray() | PEAR Manual | constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object()


constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object()

constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object()

constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/Object.php';

void HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object ( bool $collectHidden = false )

Description

This package is not documented yet.

Parameter

boolean $collectHidden

TRUE: collect all hidden elements into string; FALSE: process them as usual form elements

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
HTML_QuickForm_Renderer_Object | PEAR Manual | HTML_QuickForm_Renderer_Object::toObject()


HTML_QuickForm_Renderer_Object::toObject()

HTML_QuickForm_Renderer_Object::toObject()

HTML_QuickForm_Renderer_Object::toObject() – Returns the resultant object

Synopsis

require_once 'HTML/QuickForm/Renderer/Object.php';

QuickformForm HTML_QuickForm_Renderer_Object::toObject ( ( void )

Description

Returns an object representation of the form built by the renderer.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Basic renderers | Next
constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object() | PEAR Manual | Template-based renderers


Template-based renderers

Template-based renderers

Table of Contents
  • HTML_QuickForm_Renderer_ArraySmarty -- A renderer for 'static' Smarty templates
  • constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty() -- Constructor
  • HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate() -- Sets the way elements with validation errors are rendered
  • HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() -- Sets the way required elements are rendered
  • HTML_QuickForm_Renderer_ITDynamic -- Dynamic renderer for Integrated Templates
  • constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic() -- Constructor
  • HTML_QuickForm_Renderer_ITDynamic::setElementBlock() -- Sets the block to use for element rendering
  • HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() -- Sets the name of a block to use for header rendering
  • HTML_QuickForm_Renderer_ITStatic -- Static renderer for Integrated Templates
  • constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic() -- Constructor
  • HTML_QuickForm_Renderer_ITStatic::setErrorTemplate() -- Sets the way elements with validation errors are rendered
  • HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate() -- Sets the way required elements are rendered
  • HTML_QuickForm_Renderer_ObjectFlexy -- A renderer for Flexy templates
  • constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy() -- Constructor
  • HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate() -- Set the filename of the template to render html elements.
  • HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate() -- Set the filename of the template to render html elements.
  • HTML_QuickForm_Renderer_QuickHtml -- Render form elements into HTML in an easy and flexible manner
  • constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml() -- Constructor
  • HTML_QuickForm_Renderer_QuickHtml::toHtml() -- Returns the HTML
  • HTML_QuickForm_Renderer_QuickHtml::elementToHtml() -- Renders a specific form element into HTML

These renderers use template engines to actually generate the HTML for the form.

Prev | Outputting the form | Next
HTML_QuickForm_Renderer_Object::toObject() | PEAR Manual | HTML_QuickForm_Renderer_ArraySmarty


HTML_QuickForm_Renderer_ArraySmarty

HTML_QuickForm_Renderer_ArraySmarty

HTML_QuickForm_Renderer_ArraySmarty – A renderer for 'static' Smarty templates

Description

This renderer was written by Thomas Schulz. It is based on pre-3.0 HTML_QuickForm::toArray() code and ITStatic renderer. It can be used to output the form into the 'static' Smarty template. Usage example for this is available in docs/renderers.

The form array structure is the following:

array (
['frozen'] => 'whether the complete form is frozen',
['javascript'] => 'javascript for client-side validation',
['attributes'] => 'attributes for <form> tag',
['hidden'] => 'html of all hidden elements',
['requirednote'] => 'note about the required elements',
['errors'] => Array
(
['1st_element_name'] => 'Error for the 1st element',
...
['nth_element_name'] => 'Error for the nth element',
),

['header'] => Array
(
['1st_header_name'] => 'Header text for the 1st header',
...
['nth_header_name'] => 'Header text for the nth header'
),

['1st_element_name'] => 'Array for the 1st element',
...
['nth_element_name'] => Array for the nth element'
);

where an element array has the form:

array(
['name'] => 'element name',
['value'] => 'element value',
['type'] => 'type of the element',
['frozen'] => 'whether element is frozen',
['label'] => 'label for the element',
['required'] => 'whether element is required',
// if element is not a group:
['html'] => 'HTML for the element',
// if element is a group:
['separator'] => 'separator for group elements',
['1st_gitem_name'] => 'Array for the 1st element in group',
...
['nth_gitem_name'] => 'Array for the nth element in group'
);
Prev | Template-based renderers | Next
Template-based renderers | PEAR Manual | constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty()


constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty()

constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty()

constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/ArraySmarty.php';

void HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty ( mixed &$tpl )

Description

This package is not documented yet.

Parameter

object &$tpl

A Smarty object to use for form output

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ArraySmarty | PEAR Manual | HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate()


HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate()

HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate()

HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate() – Sets the way elements with validation errors are rendered

Synopsis

require_once 'HTML/QuickForm/Renderer/ArraySmarty.php';

void HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate ( string $template )

Description

You can use {$label} or {$html} placeholders to let the renderer know where where the element label or the element html are positionned according to the error message. They will be replaced accordingly with the right value. The error message will replace the {$error} placeholder. For example: {if $error}<span style="color: red;">{$error}</span>{/if}{$html} will put the error message in red on top of the element html.

If you want all error messages to be output in the main error block, use the {$form.errors} part of the rendered array that collects all raw error messages.

If you want to place all error messages manually, do not specify {$html} nor {$label}.

Groups can have special layouts. With this kind of groups, you have to place the formated error message manually. In this case, use {$form.group.error} where you want the formated error message to appear in the form.

Parameter

string $template

The element error template

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty() | PEAR Manual | HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate()


HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate()

HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate()

HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() – Sets the way required elements are rendered

Synopsis

require_once 'HTML/QuickForm/Renderer/ArraySmarty.php';

void HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate ( string $template )

Description

You can use {$label} or {$html} placeholders to let the renderer know where where the element label or the element html are positionned according to the required tag. They will be replaced accordingly with the right value. You can use the full smarty syntax here, especially a custom modifier for I18N. For example: {if $required}<span style="color: red;">*</span>{/if}{$label|translate} will put a red star in front of the label if the element is required and translate the label.

Parameter

string $template

The required element template

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate() | PEAR Manual | HTML_QuickForm_Renderer_ITDynamic


HTML_QuickForm_Renderer_ITDynamic

HTML_QuickForm_Renderer_ITDynamic

HTML_QuickForm_Renderer_ITDynamic – Dynamic renderer for Integrated Templates

Description

The word 'dynamic' in renderer name means that exact form layout is defined at script runtime. This also means that you can create one template file for all your forms. That template should contain a block for every distinct element 'look' appearing in your forms and also some special blocks. If a special block is not set for an element, the renderer falls back to a default one.

If most of your forms tend to share the same look (a good example would be back-office interface), your best bet will be to use Dynamic renderer. If each of your forms has a really special layout, you should go with a Static one.

Template structure

This is a somewhat minimal template, but it contains all the necessary elements to render any form you are able to define with the package.

{qf_javascript}
<form {qf_attributes}>
<!-- BEGIN qf_hidden_loop -->
{qf_hidden}
<!-- END qf_hidden_loop -->

<table>

<!-- BEGIN qf_errors -->
<tr>
<td>
Collected errors:
<ul>
<!-- BEGIN qf_error_loop -->
<li>{qf_error}</li>
<!-- END qf_error_loop -->
</ul>
</td>
</tr>
<!-- END qf_errors -->

<!-- BEGIN qf_main_loop -->
<!-- BEGIN qf_header -->
<tr>
<th colspan="2">{qf_header}</th>
</tr>
<!-- END qf_header -->

<!-- BEGIN qf_element -->
<tr valign="top">
<td align="right">
<!-- BEGIN qf_element_required --><span style="color: #FF0000;">*</span><!-- END qf_element_required -->
<b>{qf_label}</b>
</td>
<td>
<!-- BEGIN qf_element_error --><span style="color: #FF0000;">{qf_error}</span><br /><!-- END qf_element_error -->
{qf_element}
</td>
</tr>
<!-- END qf_element -->

<!-- BEGIN qf_group -->
<tr valign="top">
<td align="right">
<!-- BEGIN qf_group_required --><span style="color: #FF0000;">*</span><!-- END qf_group_required -->
<b>{qf_group_label}</b>
</td>
<td>
<!-- BEGIN qf_group_error --><span style="color: #FF0000;">{qf_error}</span><br /><!-- END qf_group_error -->
<!-- BEGIN qf_group_loop -->
<!-- BEGIN qf_group_element -->{qf_separator}{qf_label}{qf_element}<!-- END qf_group_element -->
<!-- END qf_group_loop -->
</td>
</tr>
<!-- END qf_group -->

<!-- END qf_main_loop -->

<!-- BEGIN qf_required_note -->
<tr>
<td>&nbsp;</td>
<td align="left" valign="top">{qf_required_note}</td>
</tr>
<!-- END qf_required_note -->
</table>
</form>
qf_main_loop

This block should always be present and should be a parent for all visible elements' blocks. It is used to implement "flow", to render elements one after another.

qf_element

This is the default block for rendering form elements. This block should always be present, as the renderer uses the following logic to decide which block to use for an element's output:

  1. If a special block was set for an element, use that

  2. If a block qf_%element's type% (e.g. qf_password) exists, use that

  3. Use qf_element

qf_element_required

The block will be touch'd if an element is required.

qf_element_error

An error associated with an element will be output here.

qf_header

This is the default block used to output headers. Should be present unless you have no headers in your form.

qf_group

Default block to output groups. Should be present unless you do not use grouped elements.

qf_group_loop

An analog of qf_main_loop, used to render group's elements one after another. A %group's block%_loop should always be present inside %group's block%

qf_group_element

A default block to render group's elements, %group's block%_element should always be present inside %group's block%_loop (for the same reason as the qf_element should be present in qf_main_loop)

qf_error_loop

This is used to output collected errors for the elements that do not have a %element's block%_error block.

qf_hidden_loop

<input type="hidden" /> elements are rendered here.

{qf_javascript}

Javascript for client-side form validation will be output here.

{qf_required_note}

If there are required elements in the form, a note will be output here

Usage example

Assuming the template is in ./qform.html:

<?php
require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
require_once 'HTML/Template/Sigma.php';

// Instantiate the template object and load the template file
$tpl =& new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('qform.html');

// Instantiate the renderer and process the form
$renderer =& new HTML_QuickForm_Renderer_ITDynamic($tpl);
$form->accept($renderer);

// Output the results
$tpl->show();
?>

Note that we do not show how the form is built here, that's because the example will work for virtually any form.

Note: Template class compatibility
 This renderer was developed and tested using HTML_Template_Sigma. While it probably will work with HTML_Template_IT, no warranties can be given.
Note: Removing empty blocks
 The renderer assumes that the template object was set up to remove empty blocks (this is the default behaviour). If that is not true, the results will be pretty discouraging.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() | PEAR Manual | constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic()


constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic()

constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic()

constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/ITDynamic.php';

void HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic ( object &$tpl )

Description

This package is not documented yet.

Parameter

object &$tpl

HTML_Template_ITX/HTML_Template_Sigma object to use

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ITDynamic | PEAR Manual | HTML_QuickForm_Renderer_ITDynamic::setElementBlock()


HTML_QuickForm_Renderer_ITDynamic::setElementBlock()

HTML_QuickForm_Renderer_ITDynamic::setElementBlock()

HTML_QuickForm_Renderer_ITDynamic::setElementBlock() – Sets the block to use for element rendering

Synopsis

require_once 'HTML/QuickForm/Renderer/ITDynamic.php';

void HTML_QuickForm_Renderer_ITDynamic::setElementBlock ( mixed $elementName , string $blockName = null )

Description

Sets the block to use for element rendering.

Parameter

mixed $elementName

element name or array ('element name' => 'block name')

string $blockName

block name if $elementName is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic() | PEAR Manual | HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock()


HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock()

HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock()

HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() – Sets the name of a block to use for header rendering

Synopsis

require_once 'HTML/QuickForm/Renderer/ITDynamic.php';

void HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock ( string $blockName )

Description

Sets the name of a block to use for header rendering

Parameter

string $blockName

block name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ITDynamic::setElementBlock() | PEAR Manual | HTML_QuickForm_Renderer_ITStatic


HTML_QuickForm_Renderer_ITStatic

HTML_QuickForm_Renderer_ITStatic

HTML_QuickForm_Renderer_ITStatic – Static renderer for Integrated Templates

Description

The word 'static' in renderer name means that exact form layout is defined before the execution of the script starts. That also means that you should have an unique template for each form you want to display with this renderer.

The IT Static renderer, as opposed to the IT Dynamic renderer, offers more flexibility in the way you display your forms but might also takes more time to implement. Therefore, if your form is using always the same pattern to display form element labels and form element html, it is recommended to use the Dynamic renderer. On the other hand, if you have many different layouts for your form elements, for example if you alternate text and form elements, you will prefer to use the Static renderer.

Usage example

With the ITStatic renderer, you have to know beforehand which elements (or group of elements) will compose your form. So we will start by defining our elements.

Defining the elements

<?php
require_once ("HTML/QuickForm.php");

$form = new HTML_QuickForm('myform', 'POST');
$form->addElement('header', 'myheader', 'Registration form');

$form->addElement('hidden', 'session', '123456');

$name['last'] = &HTML_QuickForm::createElement('text', 'first', 'First', array('size' => 10));
$name['first'] = &HTML_QuickForm::createElement('text', 'last', 'Last', array('size' => 10));
$form->addGroup($name, 'name', 'Name:', '-');

$form->addElement('text', 'email', 'Your email:');

$select = array(''   => 'Please select...',
                'AU' => 'Australia',
                'FR' => 'France',
                'DE' => 'Germany',
                'IT' => 'Italy');
$form->addElement('select', 'country', 'Country:', $select);

$form->addElement('reset', 'reset', 'Reset');
$form->addElement('submit', 'submit', 'Register');

$form->addElement('checkbox', 'news', '', " Check this box if you don't want to receive our newsletter.");
?>

Now our form contains these elements:

  • One header: 'Registration form'

  • One hidden field

  • One group of two textfields: firstname and lastname

  • One textfield for the E-Mail address

  • One selectbox for the country with an empty default value

  • Two buttons: Reset and Register

  • One checkbox to subscribe to the newsletter

Now that we know which elements compose our form, it will be easy to layout the form using a WYSIWYG or an HTML editor. The idea is to use placeholders instead of labels and element html. The placeholders are named after the form and element or group names: formName_elementName or formName_groupName_elementName. Then you add _label or _html. We will save the following code in a template.html file.

A template

<html>
<head><title>My Form</title>
{myform_javascript}
</head>
<body>
<form {myform_attributes}>
 {myform_session_html}
 <table>
 <tr><th colspan="2">{myform_myheader}</th></tr>
 <tr><td>{myform_name_label}</td><td>{myform_name_html}</td></tr>
 <tr><td>{myform_email_label}</td><td>{myform_email_html}</td></tr>
 <tr><td>{myform_country_label}</td><td>{myform_country_html}</td></tr>
 <tr><td colspan="2" align="right">{myform_reset_html} {myform_submit_html}</td></tr>
</table>
<br /><br />
{myform_news_html}
</form>
</body>
</html>

As you can notice, the layout is static. This makes the Static renderer only useful if your form does not change on runtime. Nevertheless, you can still hide blocks if you use the removeEmptyBlocks option of HTML_Template_IT / HTML_Template_Sigma. Now that we have the elements and the template, we are going to use our Static renderer.

Using the renderer

<?php
require_once 'HTML/Template/Sigma.php';
require_once 'HTML/QuickForm/Renderer/ITStatic.php';

$tpl =& new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('template.html'); // or whatever you called it

$renderer =& new HTML_QuickForm_Renderer_ITStatic($tpl);
$renderer->setRequiredTemplate('{label}<font color="red" size="1">*</font>');
$renderer->setErrorTemplate('<font color="red">{error}</font><br />{html}');

$form->accept($renderer);
$tpl->show();
?>

You can optionally specify the way your required elements and validation errors are rendered using respectively setRequiredTemplate() and setErrorTemplate(). In the given string, you will place either the {label} or the {html} placeholder at the position you want. If you prefer to have all your errors displayed at the same place, pass an empty string to setErrorTemplate() and add this block to your template at the position you want:

<!-- BEGIN myform_error_loop -->
<font color="red">{myform_error}</font><br />
<!-- END myform_error_loop -->

With the Static renderer, it is also possible to customize the way your groups are rendered. If you simply use a placeholder for your whole group, the group will be rendered using HTML_QuickForm default renderer. This means that if a separator string (or an array of separators) was specified, it will be used the usual way. In our form, the group called 'name' was rendered this way, using a - to separate the elements.

The problem we have is that elements inside the group don't show their label, so it is not possible to guess which textfield is firstname and which one is lastname. By replacing the layout for the element 'name' by these new placeholders, can customize the way the group will be displayed:

(...)
 <tr>
  <td>{myform_name_label}</td>
  <td>
   <!-- BEGIN myform_name_error -->{myform_name_error}<!-- END myform_name_error -->
   <table>
    <tr><td>{myform_name_first_html}</td><td>{myform_name_last_html}</td></tr>
    <tr><td>{myform_name_first_label}</td><td>{myform_name_last_label}</td></tr>
    </table>
   </td>
 </tr>
(...)

We need to add a new block and placeholder to let the renderer know where to display the error relative to this group. As you have noticed, every placeholder take the name of his group along with its own name.

Tip

Also note that if you use elements with the same name, like radios that are not in a group, you will have to add an index to the placeholder name starting at 0, like this: {myform_myradio_0_html}, {myform_myradio_1_html}...

We have seen how to use the Static renderer with standard elements and groups of elements. We have seen how to display errors and required tags. They won't show in your form because we did not add any validation rules. Feel free to try to add them as an exercise. You can also add a special placeholder to your template {myform_required_note}, it will display the note that indicates how to find required elements. This renderer usage is very easy, when you feel comfortable with it, you can move on to the Dynamic renderer which might also fit your needs in an other way.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() | PEAR Manual | constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic()


constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic()

constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic()

constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/ITStatic.php';

void HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic ( object &$tpl )

Description

This package is not documented yet.

Parameter

object &$tpl

HTML_Template_IT or other compatible Template object to use

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ITStatic | PEAR Manual | HTML_QuickForm_Renderer_ITStatic::setErrorTemplate()


HTML_QuickForm_Renderer_ITStatic::setErrorTemplate()

HTML_QuickForm_Renderer_ITStatic::setErrorTemplate()

HTML_QuickForm_Renderer_ITStatic::setErrorTemplate() – Sets the way elements with validation errors are rendered

Synopsis

require_once 'HTML/QuickForm/Renderer/ITStatic.php';

void HTML_QuickForm_Renderer_ITStatic::setErrorTemplate ( string $template )

Description

You can use {label} or {html} placeholders to let the renderer know where where the element label or the element html are positionned according to the error message. They will be replaced accordingly with the right value. The error message will replace the {error} place holder. For example: <font color="red">{error}</font>{html} will put the error message in red on top of the element html.

If you want all error messages to be output in the main error block, do not specify {html} nor {label}.

Groups can have special layouts. With this kind of groups, the renderer will need to know where to place the error message. In this case, use error blocks like: <!-- BEGIN form_group_error -->{form_group_error}<!-- END form_group_error --> where you want the error message to appear in the form.

Parameter

string $template

The element error template

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic() | PEAR Manual | HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate()


HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate()

HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate()

HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate() – Sets the way required elements are rendered

Synopsis

require_once 'HTML/QuickForm/Renderer/ITStatic.php';

void HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate ( string $template )

Description

You can use {label} or {html} placeholders to let the renderer know where where the element label or the element html are positionned according to the required tag. They will be replaced accordingly with the right value. For example: <font color="red">*</font>{label} will put a red star in front of the label if the element is required.

Parameter

string $template

The required element template

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ITStatic::setErrorTemplate() | PEAR Manual | HTML_QuickForm_Renderer_ObjectFlexy


HTML_QuickForm_Renderer_ObjectFlexy

HTML_QuickForm_Renderer_ObjectFlexy

HTML_QuickForm_Renderer_ObjectFlexy – A renderer for Flexy templates

Description

This renderer allows you to output your form using a Flexy template. A static and dynamic usage example is available in the docs/renderers directory.

Usage example

The following is an example of using the ObjectFlexy renderer with a simple template.

Defining the elements

<?php

require_once 'HTML/Template/Flexy.php';
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php';

// Form name will be used to find the placeholders.

$form = new HTML_QuickForm('form', 'POST');

// Personal information

$form->addElement('header', 'personal', 'Personal Information');

$form->addElement('text', 'email', 'Your email:');
$form->addElement('password', 'pass', 'Your password:', 'size=10');
$name['last'] = &HTML_QuickForm::createElement('text', 'first', 'First', 'size=10');
$name['first'] = &HTML_QuickForm::createElement('text', 'last', 'Last', 'size=10');
$form->addGroup($name, 'name', 'Name:', ',&nbsp;');
$areaCode = &HTML_QuickForm::createElement('text', '', null,'size=4 maxlength=3');
$phoneNo1 = &HTML_QuickForm::createElement('text', '', null, 'size=4 maxlength=3');
$phoneNo2 = &HTML_QuickForm::createElement('text', '', null, 'size=5 maxlength=4');
$form->addGroup(array($areaCode, $phoneNo1, $phoneNo2), 'phone', 'Telephone:', '-');

// Company information

$form->addElement('header', 'company_info', 'Company Information');

$form->addElement('text', 'company', 'Company:', 'size=20');

$str[] = &HTML_QuickForm::createElement('text', '', null, 'size=20');
$str[] = &HTML_QuickForm::createElement('text', '', null, 'size=20');
$form->addGroup($str, 'street', 'Street:', '<br />');

$addr['zip'] = &HTML_QuickForm::createElement('text', 'zip', 'Zip', 'size=6 maxlength=10');
$addr['city'] = &HTML_QuickForm::createElement('text', 'city', 'City', 'size=15');
$form->addGroup($addr, 'address', 'Zip, city:');

$select = array('' => 'Please select...', 'AU' => 'Australia', 'FR' => 'France', 'DE' => 'Germany', 'IT' => 'Italy');
$form->addElement('select', 'country', 'Country:', $select);

// Other elements

$form->addElement('checkbox', 'news', '', " Check this box if you don't want to receive our newsletter.");

$form->addElement('reset', 'reset', 'Reset');
$form->addElement('submit', 'submit', 'Register');

// Tries to validate the form
if ($form->validate()) {
    // Form is validated, then freezes the data
    $form->freeze();
}

// setup a template object
$options = &PEAR::getStaticProperty('HTML_Template_Flexy','options');
$options = array(
    'templateDir' => './templates',
    'compileDir' => './templates/build',
    'forceCompile' => 1,
    'debug' => 0,
    'local' => 'en'
);

$template = new HTML_Template_Flexy($options);

$renderer =& new HTML_QuickForm_Renderer_ObjectFlexy($template);
$renderer->setLabelTemplate("label.html");
$renderer->setHtmlTemplate("html.html");

$form->accept($renderer);

$view = new StdClass;
$view->form = $renderer->toObject();

$template->compile("flexy-static.html");
$template->outputObject($view);

?>

The template files used above are the following: label.html

A template for the labels

{if:required}
<font color="red" size="1">*</font>
{end:}
{label:h}

html.html

A template for the overall html

{if:error}
<font color="orange" size="1">{error:h}</font><br />
{end:}
{html:h}

flexy-static.html

A template for the form

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- $Id: html-quickform-renderer-objectflexy.xml,v 1.3 2008/10/09 15:16:33 cweiske Exp $ -->
<html>
<head>
<title>Flexy template : 2 column layout example</title>
<style type="text/css">
.errors {
font-family: sans-serif;
color : #000;
background-color : #FFF;
font-size : 12pt;
}
.label {
font-family: sans-serif;
color : Navy;
font-size : 11px;
text-align : right;
vertical-align : top;
white-space: nowrap;
}
.element {
font-family: sans-serif;
background-color : #EEE;
text-align : left;
white-space: nowrap;
}
.note {
font-family: sans-serif;
background-color : #EEE;
text-align : center;
font-size : 10pt;
color : AAA;
white-space: nowrap;
}
th {
font-family: sans-serif;
font-size : small;
color : #FFF;
background-color : #AAA;
}
.maintable {
border : thin dashed #D0D0D0;
background-color : #EEE;
}
</style>
{form.javascript:h}
</head>

<body>

{form.outputHeader():h}
{form.hidden:h}

<table class="maintable" width="600" align="center">
<tr>
<td width="50%" valign="top"><!-- Personal info -->
<table width="100%" cellpadding="4">
<tr><th colspan="2">{form.header.personal:h}</th></tr>
<tr>
<td class="label">{form.name.label:h}</td>
<td class="element">{form.name.error:h}
<table cellspacing="0" cellpadding="1">
<tr>
<td>{form.name.first.html:h}</td>
<td>{form.name.last.html:h}</td>
</tr>
<tr>
<td><font size="1" color="grey">{form.name.first.label:h}</font></td>
<td><font size="1" color="grey">{form.name.last.label:h}</font></td>
</tr>
</table>
</td>
</tr>
<tr>
<td class="label">{form.phone.label:h}</td>
<td class="element">{form.phone.html:h}</td>
</tr>
<tr>
<td class="label">{form.email.label:h}</td>
<td class="element">{form.email.html:h}</td>
</tr>
<tr><td colspan="2" class="note">Please, choose a 8-10 characters password.</td></tr>
<tr>
<td class="label">{form.pass.label:h}</td>
<td class="element">{form.pass.html:h}</td>
</tr>
</table>
</td>

<td width="50%" valign="top"><!-- Company info -->
<table width="100%" cellpadding="4">
<tr><th colspan="2">{form.header.company_info:h}</th></tr>
<tr>
<td class="label">{form.company.label:h}</td>
<td class="element">{form.company.html:h}</td>
</tr>
<tr>
<td class="label" valign="top">{form.street.label:h}</td>
<td class="element">{form.street.html:h}</td>
</tr>
<tr>
<td class="label">{form.address.label:h}</td>
<td class="element">{form.address.error:h}
<table cellspacing="0" cellpadding="1">
<tr>
<td>{form.address.zip.html:h}</td>
<td>{form.address.city.html:h}</td>
</tr>
<tr>
<td><font size="1" color="grey">{form.address.zip.label:h}</font></td>
<td><font size="1" color="grey">{form.address.city.label:h}</font></td>
</tr>
</table>
</td>
</tr>
<tr>
<td class="label">{form.country.label:h}</td>
<td class="element">{form.country.html:h}</td>
</tr>
<tr>
<td class="label">{form.destination.label:h}</td>
<td class="element">{form.destination.html:h}</td>
</tr>
</table>
</td>
</tr>
</table>

<table width="600" align="center">
<tr>
<td>{form.requirednote:h}</td>
<td align="right">{form.reset.html:h}&nbsp;{form.submit.html:h}</td>
</tr>
<tr>
<td colspan="2" style="font-size:11px; color: navy;"><br />{form.news.html:h}</td>
</tr>
</table>

</form>

<br />
<b>Collected Errors:</b><br />
{foreach:form.errors,error}
<font color="red">{error}</font> in element [{name}]<br />
{end:}

&nbsp;
<p><strong>The used "Static" Object</strong></p>
<pre style="font-size: 12px;">
{static_object}
</pre>

</body>
</html>

For more information on Flexy templating, see the package homepage.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate() | PEAR Manual | constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy()


constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy()

constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy()

constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php';

void HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy ( object &$flexy )

Description

This package is not documented yet.

Parameter

object &$flexy

HTML_Template_Flexy or other compatible Template object to use

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ObjectFlexy | PEAR Manual | HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate()


HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate()

HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate()

HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate() – Set the filename of the template to render html elements.

Synopsis

require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php';

void HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate ( string $template )

Description

In your template, {html} is replaced by the unmodified html. If the element is required, {required} will be true. Eg.

{if:error}
<font color="red" size="1">{error:h}</font><br />
{end:}
{html:h}

Parameter

string $template

Filename of template

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy() | PEAR Manual | HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate()


HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate()

HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate()

HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate() – Set the filename of the template to render html elements.

Synopsis

require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php';

void HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate ( string $template )

Description

Set the filename of the template to render form labels. In your template, {label} is replaced by the unmodified label, {error} will be set to the error, if any. {required} will be true if this is a required field Eg.

{if:required}
<font color="orange" size="1">*</font>
{end:}
{label:h}

Parameter

string $template

Filename of template

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate() | PEAR Manual | HTML_QuickForm_Renderer_QuickHtml


HTML_QuickForm_Renderer_QuickHtml

HTML_QuickForm_Renderer_QuickHtml

HTML_QuickForm_Renderer_QuickHtml – Render form elements into HTML in an easy and flexible manner

Description

This renderer has three main distinctives: an easy way to create custom-looking forms, the ability to separate the creation of form elements from their display, and being able to use QuickForm in widget-based template systems.

All of the renderers allow you to create a custom-looking form. However, unlike the default renderer, QuickHtml is solely for creating custom forms and has the additional benefits discussed below.

It is often desirable to separate the creation of form elements and their accompanying rules from their actual display on a page. For example, in the MVC design pattern it may be useful to create the form elements and their rules in the Model classes which control how the submitted data will be saved (field lengths, allowed characters, etc.), but leave the rendering of those form elements to the View classes which only care about how to make the page look a certain way.

A widget is a chunk of re-usable html which can be used with other widgets to create a webpage. Any template system which supports widgets (and nearly all do) can be used with QuickHtml. An example widget may consist of a table with reserved places for the form elements. The form elements would be rendered into those places and then the form tags, any remaining form elements (such as hidden elements), and any accompanying javascript for validation would be wrapped around the table widget.

Usage example

The following is an example usage of the QuickHtml renderer. The "template" system we use is just a simple html widget in which the form elements are placed, but it could be replaced with a more complex template system. A more complex usage example is in docs/renderers/QuickHtml_example.php

QuickHtml renderer usage

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/QuickHtml.php';

// Create form elements and renderer
$form =& new HTML_QuickForm('tmp_form','POST');
$renderer =& new HTML_QuickForm_Renderer_QuickHtml();
// Create a hidden element.  Note how we don't render it explicitly,
// rather we let QuickHtml render it for us at the beginning of the form.
$form->addElement('hidden','tmp_hidden');
// Create 2 radio elements.  Note how we have to give a value when rendering
// them since that is the only way to tell them apart.
$form->addElement('radio','tmp_radio',null,null,'Y');
$form->addElement('radio','tmp_radio',null,null,'N');
// Create a group with a rule
$text = array();
$text[] =& HTML_QuickForm::createElement('text','',null,array('size' => 3));
$text[] =& HTML_QuickForm::createElement('text','',null,array('size' => 4));
$text[] =& HTML_QuickForm::createElement('text','',null,array('size' => 3));
$form->addGroup($text, 'tmp_phone', null, '-');
$form->addRule('tmp_phone','Phone number cannot be empty.','required',null,'client');

// Do the magic of creating the form.  NOTE: order is important here: this must
// be called after creating the form elements, but before rendering them.
$form->accept($renderer);

// Create a very basic template for our form
$html_template = '
<div style="text-align: center; font-weight: bold;">QuickHtml - Basic Example</div>
<div style="text-align: center; background-color: #ccc; margin: 1px;">Phone: %phoneNumber%</div>
<div style="text-align: left; background-color: #ccc; margin: 1px;">Yes: %radioElementYes% No: %radioElementNo%</div>';

// Interpolate the form elements into our template
$html_template = str_replace('%phoneNumber%', $renderer->elementToHtml('tmp_phone'), $html_template);
$html_template = str_replace('%radioElementYes%', $renderer->elementToHtml('tmp_radio', 'Y'), $html_template);
$html_template = str_replace('%radioElementNo%', $renderer->elementToHtml('tmp_radio', 'N'), $html_template);

// The form tags, javascript, and hidden element will be wrapped around
// our html template
echo $renderer->toHtml($html_template);
?>
Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate() | PEAR Manual | constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml()


constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml()

constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml()

constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml() – Constructor

Synopsis

require_once 'HTML/QuickForm/Renderer/QuickHtml.php';

void HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml ( ( void )

Description

The constructor for HTML_QuickForm_Renderer_QuickHtml().

Throws

throws no exceptions thrown

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_QuickHtml | PEAR Manual | HTML_QuickForm_Renderer_QuickHtml::toHtml()


HTML_QuickForm_Renderer_QuickHtml::toHtml()

HTML_QuickForm_Renderer_QuickHtml::toHtml()

HTML_QuickForm_Renderer_QuickHtml::toHtml() – Returns the HTML

Synopsis

require_once 'HTML/QuickForm/Renderer/QuickHtml.php';

string HTML_QuickForm_Renderer_QuickHtml::toHtml ( string $data )

Description

Returns the HTML generated for the form.

Parameter

$data

Any html to put inside the form tags. This would normally be the html template into which you have rendered the form elements.

Throws

throws no exceptions thrown

Prev | Template-based renderers | Next
constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml() | PEAR Manual | HTML_QuickForm_Renderer_QuickHtml::elementToHtml()


HTML_QuickForm_Renderer_QuickHtml::elementToHtml()

HTML_QuickForm_Renderer_QuickHtml::elementToHtml()

HTML_QuickForm_Renderer_QuickHtml::elementToHtml() – Renders a specific form element into HTML

Synopsis

require_once 'HTML/QuickForm/Renderer/QuickHtml.php';

string HTML_QuickForm_Renderer_QuickHtml::elementToHtml ( string $elementName , string $elementValue )

Description

Returns the HTML generated for a specific form element and marks that element as rendered.

Parameter

$elementName

The name of the form element that is being rendered.

$elementValue

The value given to the form element. This is only useful for elements that have the same name (such as a radio button), and can only be told apart based on the value assigned to them.

Throws

throws no exceptions thrown

Prev | Template-based renderers | Next
HTML_QuickForm_Renderer_QuickHtml::toHtml() | PEAR Manual | Renderer infrastructure


Renderer infrastructure

Renderer infrastructure

Table of Contents
  • HTML_QuickForm_Renderer -- Abstract base class for renderers (package developer related)
  • HTML_QuickForm_Renderer::startForm() -- Start visiting a form (package developer related)
  • HTML_QuickForm_Renderer::finishForm() -- Finish visiting a form (package developer related)
  • HTML_QuickForm_Renderer::startGroup() -- Start visiting a group (package developer related)
  • HTML_QuickForm_Renderer::finishGroup() -- Finish visiting a group (package developer related)
  • HTML_QuickForm_Renderer::renderElement() -- Visit an element (package developer related)
  • HTML_QuickForm_Renderer::renderHeader() -- Visit a header (package developer related)
  • HTML_QuickForm_Renderer::renderHidden() -- Visit a hidden element (package developer related)
  • HTML_QuickForm_Renderer::renderHtml() -- Visit a raw HTML/text element (package developer related)

If you want to modify an existing renderer or write a new one, this section will be of interest to you.

Prev | Outputting the form | Next
HTML_QuickForm_Renderer_QuickHtml::elementToHtml() | PEAR Manual | HTML_QuickForm_Renderer


HTML_QuickForm_Renderer

HTML_QuickForm_Renderer

HTML_QuickForm_Renderer – Abstract base class for renderers (package developer related)

Description

Defines the abstract methods that should be implemented by child classes.

QuickForm renderers implement the Visitor design pattern. That means that each form element has an accept() method that is called with a renderer instance as a parameter. This method does the following:

  • If the element contains other elements (HTML_QuickForm_group and HTML_QuickForm itself) then it iterates over them calling each element's accept() method and calls the methods for rendering the container itself (e.g. startForm() and finishForm()).

  • If the element is simple, then it calls the renderer's method for rendering itself (e.g. renderHeader()).

It may seem that renderer object has to have a renderConcreteElement() method for each HTML_QuickForm_concreteElement it may visit, but fortunately most of the elements have fairly similar rendering needs, so instead of separate renderTextarea() and renderCheckbox() we have a generic renderElement() method.

The renderer should take care of "accumulating" the information passed to its methods and of generating some type of output based on it. How this is implemented internally depends on the renderer type.

Creating your own renderer

The first thing you have to decide upon is how your renderer will accumulate the information. You'll probably have to create some data structures to keep it (unless you are going to pass the information to e.g. a template object at once).

Then you have to make concrete implementations for all the abstract methods defined in HTML_QuickForm_Renderer. One notable exception is renderHtml() method that is implemented only in the Default renderer and will probably stay this way.

You'll probably also want to add some public methods for customizing the output and getting the results of the renderer's work. But this depends on the type of the renderer very much.

If you want to contribute the renderer you made to QuickForm, consider the following

  • Your code should be useful to other people (e.g. renderer for some obscure private template engine is a bad contribution).

  • Your renderer should have non-trivial usage examples.

  • And last but not least, you code will have to conform to PEAR coding standards.

Tip

If you have examples for additional uses of an existing renderer, that will be a welcome contribution, too.

Prev | Renderer infrastructure | Next
Renderer infrastructure | PEAR Manual | HTML_QuickForm_Renderer::startForm()


HTML_QuickForm_Renderer::startForm()

HTML_QuickForm_Renderer::startForm()

HTML_QuickForm_Renderer::startForm() – Start visiting a form (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::startForm ( object &$form )

Description

Called when visiting a form, before processing any form elements

Parameter

object &$form

HTML_QuickForm object being visited

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer | PEAR Manual | HTML_QuickForm_Renderer::finishForm()


HTML_QuickForm_Renderer::finishForm()

HTML_QuickForm_Renderer::finishForm()

HTML_QuickForm_Renderer::finishForm() – Finish visiting a form (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::finishForm ( object &$form )

Description

Called when visiting a form, after processing all form elements

Parameter

object &$form

HTML_QuickForm object being visited

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::startForm() | PEAR Manual | HTML_QuickForm_Renderer::startGroup()


HTML_QuickForm_Renderer::startGroup()

HTML_QuickForm_Renderer::startGroup()

HTML_QuickForm_Renderer::startGroup() – Start visiting a group (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::startGroup ( object &$group , bool $required , string $error )

Description

Called when visiting a group, before processing any group elements

Parameter

object &$group

HTML_QuickForm_group object being visited

boolean $required

Whether a group is required

string $error

An error message associated with a group

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::finishForm() | PEAR Manual | HTML_QuickForm_Renderer::finishGroup()


HTML_QuickForm_Renderer::finishGroup()

HTML_QuickForm_Renderer::finishGroup()

HTML_QuickForm_Renderer::finishGroup() – Finish visiting a group (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::finishGroup ( object &$group )

Description

Called when visiting a group, after processing all group elements

Parameter

object &$group

HTML_QuickForm_group object being visited

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::startGroup() | PEAR Manual | HTML_QuickForm_Renderer::renderElement()


HTML_QuickForm_Renderer::renderElement()

HTML_QuickForm_Renderer::renderElement()

HTML_QuickForm_Renderer::renderElement() – Visit an element (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::renderElement ( object &$element , bool $required , string $error )

Description

Called when visiting an element

Parameter

object &$element

HTML_QuickForm_element object being visited

boolean $required

Whether an element is required

string $error

An error message associated with an element

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::finishGroup() | PEAR Manual | HTML_QuickForm_Renderer::renderHeader()


HTML_QuickForm_Renderer::renderHeader()

HTML_QuickForm_Renderer::renderHeader()

HTML_QuickForm_Renderer::renderHeader() – Visit a header (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::renderHeader ( object &$header )

Description

Called when visiting a header element

Parameter

object &$header

HTML_QuickForm_header element being visited

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::renderElement() | PEAR Manual | HTML_QuickForm_Renderer::renderHidden()


HTML_QuickForm_Renderer::renderHidden()

HTML_QuickForm_Renderer::renderHidden()

HTML_QuickForm_Renderer::renderHidden() – Visit a hidden element (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::renderHidden ( object &$element )

Description

Called when visiting a hidden element

Parameter

object &$element

HTML_QuickForm_hidden object being visited

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::renderHeader() | PEAR Manual | HTML_QuickForm_Renderer::renderHtml()


HTML_QuickForm_Renderer::renderHtml()

HTML_QuickForm_Renderer::renderHtml()

HTML_QuickForm_Renderer::renderHtml() – Visit a raw HTML/text element (package developer related)

Synopsis

require_once 'HTML/QuickForm/Renderer.php';

void HTML_QuickForm_Renderer::renderHtml ( object &$data )

Description

Called when visiting a raw HTML/text pseudo-element

Note: Implementation of the method
 HTML_QuickForm_html elements are used to directly add HTML to the form output. Thus they are useful with the Default renderer, but not with template-based one. Default renderer is currently the only one actually implementing this method, all others silently ignore HTML_QuickForm_html elements.

Parameter

object &$data

HTML_QuickForm_html element being visited

Throws

throws no exceptions thrown

Note

abstract

This function can not be called statically.

Prev | Renderer infrastructure | Next
HTML_QuickForm_Renderer::renderHidden() | PEAR Manual | HTML_QuickForm_Controller


HTML_QuickForm_Controller

HTML_QuickForm_Controller

This is an add-on to HTML_QuickForm package that allows (among other things) to build multipage forms.

Cool features:

  • Includes several default Actions that allow easy building of multipage forms.

  • Includes usage examples for common usage cases (single-page form, wizard, tabbed form).

Table of Contents
  • Introduction -- What is this package useful for
  • FAQ -- Understanding package features
  • Class Summary HTML_QuickForm_Controller -- The class implementing a PageController pattern.
  • constructor HTML_QuickForm_Controller() -- Class constructor.
  • Controller::addAction() -- Registers a handler for a specific action.
  • Controller::addPage() -- Adds a new page to the form
  • Controller::applyDefaults() -- Sets the default values for the given page
  • Controller::container() -- Returns a reference to the form's values container.
  • Controller::exportValue() -- Returns the element's value
  • Controller::exportValues() -- Returns the form's values
  • Controller::findInvalid() -- Finds the (first) invalid page
  • Controller::getActionName() -- Finds the names of the current page and the current action.
  • Controller::getNextName() -- Returns the name of the page after the given.
  • Controller::getPage() -- Returns a page
  • Controller::getPrevName() -- Returns the name of the page before the given.
  • Controller::handle() -- Handles an action.
  • Controller::isModal() -- Checks whether the form is modal.
  • Controller::isValid() -- Checks whether the pages of the controller are valid
  • Controller::run() -- Processes the request.
  • Controller::setConstants() -- Initializes constant form values.
  • Controller::setDefaults() -- Initializes default form values.
  • Class Summary HTML_QuickForm_Page -- The class represents a page of a multipage form.
  • constructor HTML_QuickForm_Page() -- Class constructor
  • Page::addAction() -- Registers a handler for a specific action.
  • Page::buildForm() -- Builds a form.
  • Page::getButtonName() -- Returns a name for a submit button that will invoke a specific action.
  • Page::handle() -- Handles an action.
  • Page::isFormBuilt() -- Checks whether the form was already built.
  • Page::loadValues() -- Loads the submit values from the array.
  • Page::setDefaultAction() -- Sets the default action invoked on page-form submit.
  • Class Summary HTML_QuickForm_Action -- Class representing an action to perform on HTTP request.
  • Action::perform() -- Processes the request.
  • Class Summary HTML_QuickForm_Action_Back -- The action for a 'back' button of wizard-type multipage form.
  • Class Summary HTML_QuickForm_Action_Direct -- This action allows to go to a specific page of a multipage form.
  • Class Summary HTML_QuickForm_Action_Display -- This action handles the output of the form.
  • Class Summary HTML_QuickForm_Action_Jump -- The action handles the HTTP redirect to a specific page.
  • Class Summary HTML_QuickForm_Action_Next -- The action for a 'next' button of wizard-type multipage form.
  • Class Summary HTML_QuickForm_Action_Submit -- The action for a 'submit' button.
Prev | HTML | Next
HTML_QuickForm_Renderer::renderHtml() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What is this package useful for

Why "Controller"?

This package implements a PageController design pattern, which essentially means that there is a single page processing requests and actions this page performs depend on parameters passed in GET or POST data. The pattern is described in more detail on Martin Fowler's website and WACT project website.

What does this mean in application to QuickForm: we have a single script which shows and validates different forms depending on data in request. This allows to fairly easy build very complex forms consisting of several pages (think wizards and such).

The most basic implementation of the PageController pattern would look like

<?php
switch ($_REQUEST['action']) {
    case 'foo':
        doFoo();
        break;
    case 'bar':
        doBar();
        break;
    default:
        echo 'Hello, world!';
}
?>

HTML_QuickForm_Controller is a bit more complex. There are three base classes:

  • HTML_QuickForm_Controller: this class extracts the action name from request and calls the appropriate handler. It includes several Pages.

  • HTML_QuickForm_Page: this class (extending HTML_QuickForm) represents a single page of a form.

  • HTML_QuickForm_Action: this class implements the Command design pattern, i.e. is essentially an OO callback.

The action sent in request consists of a page name and an action name, it defines which Page will process the request (e.g. display or validate the form) and what exactly this Page should do.

Basic usage example

Note: Session initialization
 This simple example does not use sessions since there is no need to pass data between pages. You'll need to use sessions when dealing with a real multipage form, though. HTML_QuickForm_Controller does not start a session automatically, you should explicitly call session_start() before instantiating the controller class.

To ease understanding of this package's features, lets take an example form from HTML_QuickForm tutorial and redo it using HTML_QuickForm_Controller:

Basic Controller usage

<?php
// Load the controller
require_once 'HTML/QuickForm/Controller.php';
// Load the base Action class (we will subclass it later)
require_once 'HTML/QuickForm/Action.php';

// Class representing a form
class FirstPage extends HTML_QuickForm_Page
{
    function buildForm()
    {
        $this->_formBuilt = true;

        // Add some elements to the form
        $this->addElement('header', null, 'QuickForm tutorial example');
        $this->addElement('text', 'name', 'Enter your name:', array('size' => 50, 'maxlength' => 255));
        // Note how we set the name of the submit button
        $this->addElement('submit', $this->getButtonName('submit'), 'Send');

        // Define filters and validation rules
        $this->applyFilter('name', 'trim');
        $this->addRule('name', 'Please enter your name', 'required', null, 'client');

        $this->setDefaultAction('submit');
    }
}

// Action to process the form
class ActionProcess extends HTML_QuickForm_Action
{
    function perform(&$page, $actionName)
    {
        echo '<h1>Hello, ' . htmlspecialchars($page->exportValue('name')) . '!</h1>';
    }
}

$page =& new FirstPage('firstForm');

// We only add the 'process' handler, Controller will care for default ones
$page->addAction('process', new ActionProcess());

// Instantiate the Controller
$controller =& new HTML_QuickForm_Controller('tutorial');

// Set defaults for the form elements
$controller->setDefaults(array(
    'name' => 'Joe User'
));

// Add the page to Controller
$controller->addPage($page);

// Process the request
$controller->run();
?>

You may note that the code is more verbose than the original. That is true, but to make a three page wizard-type form you'll only need to create three subclasses of HTML_QuickForm_Page and 'process' event handler based on HTML_QuickForm_Action and add them to Controller, while without the Controller infrastructure it will require a non-trivial amount of programming.

Creating custom pages

You need to subclass HTML_QuickForm_Page and override its buildForm() method. Its contents are pretty self-explanatory (if you are familiar with QuickForm), except for a few things:

<?php
$this->_formBuilt = true;
?>

Form building is a "heavy" operation, thus we call buildForm() only when necessary. To prevent calling it twice (and getting two sets of elements instead of one) we set $_formBuilt property.

The second notable line is

<?php
$this->addElement('submit', $this->getButtonName('submit'), 'Send');
?>

We use getButtonName() method to set the submit button's name and thus to trigger a 'submit' action when the button is clicked.

The third thing is

<?php
$this->setDefaultAction('submit');
?>

The user can submit the form by pressing Enter button, not by clicking on any of the form buttons. Most browsers will not consider any submit button as clicked in this case and will not send its name. setDefaultAction() sets the action (by adding a special hidden element to the form) that will be called in this case.

Creating custom actions

You'll usually need to create handlers for two actions: 'process' and 'display'. While it is difficult to say anything about the former, as only you know how to process your form, for the latter you'll need to subclass HTML_QuickForm_Action_Display and override its _renderForm() method to call the appropriate Renderer and do form output customization.

Tying this all together

Next we instantiate the page class defined above

<?php
$page =& new FirstPage('firstForm');
?>

and add our custom action handler to it

<?php
$page->addAction('process', new ActionProcess());
?>

the 'process' action will be called by the default 'submit' action handler if the form is valid.

Then we instantiate the controller

<?php
$controller =& new HTML_QuickForm_Controller('tutorial');
?>

Note that the name is a required parameter, and if you will have several Controllers in your application they should have different names, as the names are used to store values in sessions.

Then we set the defaults for the form and add the page to it

<?php
$controller->setDefaults(array(
    'name' => 'Joe User'
));
$controller->addPage($page);
?>

It is perfectly legal to do call Page's setDefaults() from within buildForm(), but the former approach allows to set the defaults for the form as a whole, while the latter only for the page in question.

Finally we call the Controller's run() method

<?php
$controller->run();
?>

which will take care of finding the name of the current action and calling the necessary handler. That's all.

Advanced usage examples

...are available in the package archive. Along with the example similar to the provided above, there are two multipage forms:

  • Wizard: form pages contain 'Next' and 'Back' buttons and you can't go to the next page unless the current page is valid.

  • Tabbed form: form has several pages and buttons allow to go directly to the corresponding page. Form is validated only when the global 'Submit' button is pressed.

Prev | HTML_QuickForm_Controller | Next
HTML_QuickForm_Controller | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Understanding package features

Description

This document is based on questions asked on PEAR general mailing list. You are encouraged to search the list archives to find more verbose answers and examples.

How do I change the action attribute of the <form> tag?

The only reason constructor of HTML_QuickForm_Page does not provide a means to set the action attribute is to make it harder to shoot oneself in the foot. That being said, the attribute can still be changed by setAttribute() or updateAttributes() method of HTML_QuickForm_Page (these are inherited from HTML_Common, and you should really consider learning its API).

Meta-question: actions

To avoid confusion lets use the terms "action" for the string containing the name of the action and "action handler" for the subclass of HTML_QuickForm_Action.

Default actions and default action handlers

While you can invent your own action names and create custom handlers for them, you'll most certainly have to deal with the default actions and their handlers first.

'display'

This action has a default handler, HTML_QuickForm_Action_Display, which displays the form using the Default renderer. You should subclass this handler if you want to customize the form output. This action is called automatically when the page needs to be displayed and should not be bound to buttons via getButtonName().

'submit'

This action should be bound to a "global" submit button for a form. It can be the "submit" button of a single-page or tabbed multi-page form, "finish" button of a wizard. This action has a default handler, HTML_QuickForm_Action_Submit, which checks whether all the pages of the form are valid, then either calls the 'process' handler or displays the invalid page.

'next'

This action should be bound to the "Next" button of (usually) a modal multipage form (AKA wizard). This action has a default handler, HTML_QuickForm_Action_Next, which checks the validity of the current page and redirects to the next one if the current is valid (or if the form is not modal). On the last page of a modal multipage form this behaves like the default 'submit' handler.

'back'

This action should be bound to the "Back" button of (usually) a modal multipage form (AKA wizard). This action has a default handler, HTML_QuickForm_Action_Back, which redirects to the previous page if one exists. As of QFC 0.9.3, no form validation takes place on 'back' action.

'jump'

This action has a default handler, HTML_QuickForm_Action_Jump, which just makes HTTP redirect to the given page of the form. This action should not be bound to buttons via getButtonName().

'process'

This is the action called by default 'submit' and 'next' (on the last page of the wizard only) handlers after successful (i.e. without validation errors) form submit. This action doesn't have a default handler, you should define the custom one yourself and implement all the necessary logic to process the form's values in it.

There is also a default handler, HTML_QuickForm_Action_Direct, that does not have a default action name. It is used to go to the specific page of the form and should be explicitly added via Page::addAction() or Controller::addAction() with the name of the target page as $actionName and bound to buttons via getButtonName() using the same name.

How to call an action handler?

You should use Page's handle() method:

<?php
$page->handle('action');
?>

Controller's handle() method will be called automatically if needed.

How to make a custom action?

Create a subclass of HTML_QuickForm_Action, add the necessary logic to its perform() method. Add it to the Page or to the Controller via addAction() with the appropriate name.

If you intend to bind this action to some button via getButtonName(), you should care about storing values in the container():

  1. Build the form.

  2. Get a reference to container.

  3. Fill the container's ['values'][$pageName] and ['valid'][$pageName] elements.

As usual, see the default action handlers' source for the examples.

Can actions be bound to something other than submit buttons?

Controller is able to properly handle actions bound to <input type="image" /> controls, too. You don't have to do anything special, just set the control's name via getButtonName().

If you want to bind an action to something like a hyperlink, you must consider the following: the form must be submitted to be able to get its values, thus you need to write some javascript that will submit the form and somehow pass the action name to the controller.

How do I reset the form?

Controller keeps the form data and validation status in session in so-called container, accessible via container() method. To reset the form you need to clear this container, which is achieved by passing TRUE to container().

How to pass additional data between pages of the form?

The answer is quite simple: you need to use the container() method of HTML_QuickForm_Controller, like this:

<?php
// Note the reference
$data =& $page->controller->container();
$data['_my_stuff'] = $stuff;
?>

On the target page you do

<?php
$data =& $page->controller->container();
$stuff = $data['_my_stuff'];
?>

Please use some prefix for your fields or start their names with underscore to prevent possible name conflicts with the future versions of QFC.

Please note that Controller knows nothing about your additional data, so do not expect it to return it via exportValues() method or the like. You'll have to use the container() method and extract the data yourself. However, your data will be deleted when the container is reset.

How to use template-based renderers?

First of all, please understand that HTML_QuickForm_Page is a subclass of HTML_QuickForm, thus everything that applies to the parent class will apply to the child. You are encouraged to read the section about renderers in HTML_QuickForm and the docs to the renderer you are trying to use. The usage examples are available in docs/renderers/ directory of QuickForm distribution.

As was already pointed out, you should subclass the HTML_QuickForm_Action_Display class if you want to customize the form output and add an instance of this subclass as a handler for Page's 'display' action. Its _renderForm() will contain all renderer-specific code.

The only new problem Controller introduces is the buttons bound to specific actions via getButtonName(). If you are using some kind of Dynamic renderer this will not be a problem, as you need not care about the elements names, but you need these names to output the form via Static renderer.

We'll assume using ITStatic renderer but the same can be applied to other Static renderers as well. You basically have 3 options:

  1. Manually add the buttons/placeholders with the names that should be autogenerated via getButtonName() to the form. This is not recommended, as the names should not be of interest to anyone except Controller itself and should not be used directly.

  2. Put the auto-named buttons into group. You can name the group any way you like, just be sure to set $appendName to false. When ITStatic sees {form_element_html} placeholder, it'll assign group's HTML to it.

  3. Call getButtonName() from within template. Add the following to the template

    <input type="submit" value="Bla-bla" name="func_buttonName('action')" ... />

    and the following to the _renderForm() method of your custom HTML_QuickForm_Action_Display subclass

    <?php
    $tpl    ->setCallbackFunction('buttonName', array(&$page, 'getButtonName'));
    ?>

    This code will work with HTML_Template_Sigma, HTML_Template_ITX (note the X) will require some more tweaking.

How to create a wizard with optional pages?

Thanks to Donald Lobo for this contribution.

Lets assume we have a three-page wizard:

  • Page 1 has a control that lets the user choose the next page.

  • Based on input, the user is directed to either page 2A or page 2B.

  • Both page 2A and 2B go to page 3 (this is commonly referred to as a StateMachine in programming books).

You need to create several action handlers based on QFC's default HTML_QuickForm_Action_Next and HTML_QuickForm_Action_Back. You can do this either at the Page level or at the Controller level. The Page level subclassing is simple, but if you have a complex StateMachine you will end up having multiple subclasses.

For the above example, the 'next' action on page 1 sends the 'user' to either page 2 or page 3 based on input. The handler also sets the 'valid' flag of the page that will not be visited.

The 'back' action on pages 2A and 2B sends the user back to page 1, while the 'next' action sends him to page 3.

Finally, the 'back' action handler on page 3 should examine the input on page 1 and send the user to either 2A or 2B.

The working example is available in statemachine.php file.

I use client-side validation. How do I switch it off for 'Back' button?

Client-side validation is called by form's onSubmit handler, if you remove the handler, the validation will not run. Therefore you need to remove it if user clicks on 'Back' button. This can be achieved f.e. by adding the following as the button's onClick handler:

this.form.onsubmit = null; return true;
Prev | HTML_QuickForm_Controller | Next
Introduction | PEAR Manual | Class Summary HTML_QuickForm_Controller


Class Summary HTML_QuickForm_Controller

Class Summary HTML_QuickForm_Controller

Class Summary HTML_QuickForm_Controller – The class implementing a PageController pattern.

Description

This class keeps track of pages and (default) action handlers for the form, it manages keeping the form values in session, setting defaults and constants for the form as a whole and getting its submit values.

Generally you don't need to subclass this.

Class Trees for HTML_QuickForm_Controller

  • HTML_QuickForm_Controller

Prev | HTML_QuickForm_Controller | Next
FAQ | PEAR Manual | constructor HTML_QuickForm_Controller()


constructor HTML_QuickForm_Controller()

constructor HTML_QuickForm_Controller()

constructor HTML_QuickForm_Controller() – Class constructor.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void constructor HTML_QuickForm_Controller::HTML_QuickForm_Controller ( string $name , bool $modal = true )

Description

Sets the form name and modal/non-modal behaviour. Different multipage forms should have different names, as they are used to store form values in session. Modal forms allow passing to the next page only when all of the previous pages are valid.

Parameter

string $name

form name

boolean $modal

whether the form is modal

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Controller | PEAR Manual | Controller::addAction()


Controller::addAction()

Controller::addAction()

Controller::addAction() – Registers a handler for a specific action.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::addAction ( string $actionName , object HTML_QuickForm_Action &$action )

Description

This handler will be used if the Page that has to handle some action does not have a handler itself.

Parameter

string $actionName

name of the action

object HTML_QuickForm_Action &$action

the handler for the action

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
constructor HTML_QuickForm_Controller() | PEAR Manual | Controller::addPage()


Controller::addPage()

Controller::addPage()

Controller::addPage() – Adds a new page to the form

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::addPage ( object HTML_QuickForm_Page &$page )

Description

This package is not documented yet.

Parameter

object HTML_QuickForm_Page &$page

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::addAction() | PEAR Manual | Controller::applyDefaults()


Controller::applyDefaults()

Controller::applyDefaults()

Controller::applyDefaults() – Sets the default values for the given page

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::applyDefaults ( string $pageName )

Description

This is used to load Page's default and constant values from the container.

Parameter

string $pageName

Name of a page

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::addPage() | PEAR Manual | Controller::container()


Controller::container()

Controller::container()

Controller::container() – Returns a reference to the form's values container.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

array &HTML_QuickForm_Controller::container ( bool $reset = false )

Description

Note: Session initialization
 The package does store the data in session, but it does not start the session automatically. You must call session_start() function yourself before instantiating HTML_QuickForm_Controller.

Returns a reference to a session variable containing the form-page values and pages' validation status. This is a "low-level" method, use exportValues() if you want just to get the form's values.

The structure of the container is the following

array (
'defaults' => array(... default form values ...),
'constants' => array(... constant form values ...),
'values' => array(
'page1' => array(... submitted values for this page ...),
...
'pageN' => array(... submitted values for this page ...)
),
'valid' => array(
'page1' => null if the page was never validated, true if valid, false otherwise
...
'pageN' => null if the page was never validated, true if valid, false otherwise
)
)

Parameter

boolean $reset

If true, then reset the container: clear all default, constant and submitted values

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::applyDefaults() | PEAR Manual | Controller::exportValue()


Controller::exportValue()

Controller::exportValue()

Controller::exportValue() – Returns the element's value

Synopsis

require_once 'HTML/QuickForm/Controller.php';

mixed HTML_QuickForm_Controller::exportValue ( string $pageName , string $elementName )

Description

This package is not documented yet.

Parameter

string $pageName

name of the page

string $elementName

name of the element in the page

Return value

returns value for the element

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::container() | PEAR Manual | Controller::exportValues()


Controller::exportValues()

Controller::exportValues()

Controller::exportValues() – Returns the form's values

Synopsis

require_once 'HTML/QuickForm/Controller.php';

array HTML_QuickForm_Controller::exportValues ( string $pageName = null )

Description

This package is not documented yet.

Parameter

string $pageName

name of the page, if not set then returns values for all pages

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::exportValue() | PEAR Manual | Controller::findInvalid()


Controller::findInvalid()

Controller::findInvalid()

Controller::findInvalid() – Finds the (first) invalid page

Synopsis

require_once 'HTML/QuickForm/Controller.php';

string HTML_QuickForm_Controller::findInvalid ( )

Description

This package is not documented yet.

Return value

returns Name of an invalid page

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::exportValues() | PEAR Manual | Controller::getActionName()


Controller::getActionName()

Controller::getActionName()

Controller::getActionName() – Finds the names of the current page and the current action.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

array HTML_QuickForm_Controller::getActionName ( )

Description

This method searches the $_REQUEST array for an element with a special name and splits the name into page name and action. If such an element is not found, the first page will be default and 'display' the default action.

Return value

returns first element is page name, second is action name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::findInvalid() | PEAR Manual | Controller::getNextName()


Controller::getNextName()

Controller::getNextName()

Controller::getNextName() – Returns the name of the page after the given.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

string HTML_QuickForm_Controller::getNextName ( string $pageName )

Description

This package is not documented yet.

Parameter

string $pageName

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::getActionName() | PEAR Manual | Controller::getPage()


Controller::getPage()

Controller::getPage()

Controller::getPage() – Returns a page

Synopsis

require_once 'HTML/QuickForm/Controller.php';

object HTML_QuickForm_Page &HTML_QuickForm_Controller::getPage ( string $pageName )

Description

This package is not documented yet.

Parameter

string $pageName

Name of a page

Return value

returns A reference to the page

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::getNextName() | PEAR Manual | Controller::getPrevName()


Controller::getPrevName()

Controller::getPrevName()

Controller::getPrevName() – Returns the name of the page before the given.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

string HTML_QuickForm_Controller::getPrevName ( string $pageName )

Description

This package is not documented yet.

Parameter

string $pageName

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::getPage() | PEAR Manual | Controller::handle()


Controller::handle()

Controller::handle()

Controller::handle() – Handles an action.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::handle ( object HTML_QuickForm_Page &$page , string $actionName )

Description

This will be called if the page itself does not have a handler to a specific action. The method also loads and uses default handlers for common actions, if specific ones were not added.

Parameter

object HTML_QuickForm_Page &$page

The page that failed to handle the action

string $actionName

Name of the action

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::getPrevName() | PEAR Manual | Controller::isModal()


Controller::isModal()

Controller::isModal()

Controller::isModal() – Checks whether the form is modal.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

bool HTML_QuickForm_Controller::isModal ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::handle() | PEAR Manual | Controller::isValid()


Controller::isValid()

Controller::isValid()

Controller::isValid() – Checks whether the pages of the controller are valid

Synopsis

require_once 'HTML/QuickForm/Controller.php';

bool HTML_QuickForm_Controller::isValid ( string $pageName = null )

Description

This package is not documented yet.

Parameter

string $pageName

If set, check only the pages before (not including) that page

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::isModal() | PEAR Manual | Controller::run()


Controller::run()

Controller::run()

Controller::run() – Processes the request.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::run ( )

Description

This finds the current page, the current action and passes the action to the page's handle() method.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::isValid() | PEAR Manual | Controller::setConstants()


Controller::setConstants()

Controller::setConstants()

Controller::setConstants() – Initializes constant form values.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::setConstants ( array $constantValues = null )

Description

These values won't get overridden by POST or GET vars

Parameter

array $constantValues

constant values

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::run() | PEAR Manual | Controller::setDefaults()


Controller::setDefaults()

Controller::setDefaults()

Controller::setDefaults() – Initializes default form values.

Synopsis

require_once 'HTML/QuickForm/Controller.php';

void HTML_QuickForm_Controller::setDefaults ( array $defaultValues = null )

Description

This package is not documented yet.

Parameter

array $defaultValues

default values

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Controller::setConstants() | PEAR Manual | Class Summary HTML_QuickForm_Page


Class Summary HTML_QuickForm_Page

Class Summary HTML_QuickForm_Page

Class Summary HTML_QuickForm_Page – The class represents a page of a multipage form.

Description

Generally you'll need to subclass this and define your buildForm() method that will build the form. While it is also possible to instantiate this class and build the form manually, this is not the recommended way.

Class Trees for HTML_QuickForm_Page

  • HTML_QuickForm

    • HTML_QuickForm_Page

Prev | HTML_QuickForm_Controller | Next
Controller::setDefaults() | PEAR Manual | constructor HTML_QuickForm_Page()


constructor HTML_QuickForm_Page()

constructor HTML_QuickForm_Page()

constructor HTML_QuickForm_Page() – Class constructor

Synopsis

require_once 'HTML/QuickForm/Page.php';

void constructor HTML_QuickForm_Page::HTML_QuickForm_Page ( string $formName , string $method = 'post' , string $target = '_self' , mixed $attributes = null )

Description

Note that unlike constructor of HTML_QuickForm there is no $action , as the form is always submitted to the current page. Note also that $formName is not optional.

Parameter

string $formName

Form's name

string $method

Form's method

string $target

Form's target

mixed $attributes

Extra attributes for <form> tag

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Page | PEAR Manual | Page::addAction()


Page::addAction()

Page::addAction()

Page::addAction() – Registers a handler for a specific action.

Synopsis

require_once 'HTML/QuickForm/Page.php';

void HTML_QuickForm_Page::addAction ( string $actionName , object HTML_QuickForm_Action &$action )

Description

This package is not documented yet.

Parameter

string $actionName

name of the action

object HTML_QuickForm_Action &$action

the handler for the action

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
constructor HTML_QuickForm_Page() | PEAR Manual | Page::buildForm()


Page::buildForm()

Page::buildForm()

Page::buildForm() – Builds a form.

Synopsis

require_once 'HTML/QuickForm/Page.php';

void HTML_QuickForm_Page::buildForm ( )

Description

Builds a form. You should override this method when you subclass HTML_QuickForm_Page, it should contain all the necessary addElement(), applyFilter(), addRule() and possibly setDefaults() and setConstants() calls. The method will be called on demand, so please be sure to set $_formBuilt property to TRUE to assure that the method works only once.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Page::addAction() | PEAR Manual | Page::getButtonName()


Page::getButtonName()

Page::getButtonName()

Page::getButtonName() – Returns a name for a submit button that will invoke a specific action.

Synopsis

require_once 'HTML/QuickForm/Page.php';

string HTML_QuickForm_Page::getButtonName ( string $actionName )

Description

Returns a name for a submit button (or an <input type="image"> control) that will invoke a specific action. This means the following: if you do

<?php
$this->addElement('submit', $this->getButtonName('foo'), 'Foo');
?>

inside the buildForm() method and the user later uses this button to submit the form, then the 'foo' handler (added via addAction() will be called.

Parameter

string $actionName

Name of the action

Return value

returns "name" attribute for a submit button

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Page::buildForm() | PEAR Manual | Page::handle()


Page::handle()

Page::handle()

Page::handle() – Handles an action.

Synopsis

require_once 'HTML/QuickForm/Page.php';

void HTML_QuickForm_Page::handle ( string $actionName )

Description

This method simply calls the perform() method of an Action object registered for this action name. If an Action object for it was not registered here, controller's handle() method will be called.

Parameter

string $actionName

Name of the action

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Page::getButtonName() | PEAR Manual | Page::isFormBuilt()


Page::isFormBuilt()

Page::isFormBuilt()

Page::isFormBuilt() – Checks whether the form was already built.

Synopsis

require_once 'HTML/QuickForm/Page.php';

bool HTML_QuickForm_Page::isFormBuilt ( )

Description

This is used to check whether it is necessary to call buildForm() or not.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Page::handle() | PEAR Manual | Page::loadValues()


Page::loadValues()

Page::loadValues()

Page::loadValues() – Loads the submit values from the array.

Synopsis

require_once 'HTML/QuickForm/Page.php';

void HTML_QuickForm_Page::loadValues ( array $values )

Description

The method is NOT intended for general usage. It should be used to assign form values from the container instead of from actual request data.

Parameter

array $values

'submit' values

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Page::isFormBuilt() | PEAR Manual | Page::setDefaultAction()


Page::setDefaultAction()

Page::setDefaultAction()

Page::setDefaultAction() – Sets the default action invoked on page-form submit.

Synopsis

require_once 'HTML/QuickForm/Page.php';

void HTML_QuickForm_Page::setDefaultAction ( string $actionName )

Description

This is necessary as the user may just press Enter instead of clicking one of the named submit buttons and then no action name will be passed to the script.

This method adds a special hidden element to the form the contents of which will be used by Controller if no action name is found in the submitted values.

Parameter

string $actionName

default action name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Page::loadValues() | PEAR Manual | Class Summary HTML_QuickForm_Action


Class Summary HTML_QuickForm_Action

Class Summary HTML_QuickForm_Action

Class Summary HTML_QuickForm_Action – Class representing an action to perform on HTTP request.

Description

The Controller will select the appropriate Action to call on the request and call its perform() method. The subclasses of this class should implement all the necessary business logic.

The default action handlers are described in the FAQ section.

Class Trees for HTML_QuickForm_Action

  • HTML_QuickForm_Action

Classes that extend HTML_QuickForm_Action
Class | Summary
HTML_QuickForm_Action_Back | The action for a 'back' button of wizard-type multipage form.
HTML_QuickForm_Action_Direct | This action allows to go to a specific page of a multipage form.
HTML_QuickForm_Action_Display | This action handles the output of the form.
HTML_QuickForm_Action_Jump | The action handles the HTTP redirect to a specific page.
HTML_QuickForm_Action_Next | The action for a 'next' button of wizard-type multipage form.
HTML_QuickForm_Action_Submit | The action for a 'submit' button.
Prev | HTML_QuickForm_Controller | Next
Page::setDefaultAction() | PEAR Manual | Action::perform()


Action::perform()

Action::perform()

Action::perform() – Processes the request.

Synopsis

require_once 'HTML/QuickForm/Action.php';

void HTML_QuickForm_Action::perform ( object HTML_QuickForm_Page &$page , string $actionName )

Description

This method should be overriden by child classes to provide the necessary logic.

Parameter

object HTML_QuickForm_Page &$page

the current form-page

string $actionName

Current action name, as one Action object can serve multiple actions

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Action | PEAR Manual | Class Summary HTML_QuickForm_Action_Back


Class Summary HTML_QuickForm_Action_Back

Class Summary HTML_QuickForm_Action_Back

Class Summary HTML_QuickForm_Action_Back – The action for a 'back' button of wizard-type multipage form.

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_Action_Back

  • HTML_QuickForm_Action

    • HTML_QuickForm_Action_Back

Prev | HTML_QuickForm_Controller | Next
Action::perform() | PEAR Manual | Class Summary HTML_QuickForm_Action_Direct


Class Summary HTML_QuickForm_Action_Direct

Class Summary HTML_QuickForm_Action_Direct

Class Summary HTML_QuickForm_Action_Direct – This action allows to go to a specific page of a multipage form.

Description

Please note that the name for this action in addAction() should NOT be 'direct', but the name of the page you wish to go to.

Class Trees for HTML_QuickForm_Action_Direct

  • HTML_QuickForm_Action

    • HTML_QuickForm_Action_Direct

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Action_Back | PEAR Manual | Class Summary HTML_QuickForm_Action_Display


Class Summary HTML_QuickForm_Action_Display

Class Summary HTML_QuickForm_Action_Display

Class Summary HTML_QuickForm_Action_Display – This action handles the output of the form.

Description

If you want to customize the form display, subclass this class and override the _renderForm() method, you don't need to change the perform() method itself.

Class Trees for HTML_QuickForm_Action_Display

  • HTML_QuickForm_Action

    • HTML_QuickForm_Action_Display

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Action_Direct | PEAR Manual | Class Summary HTML_QuickForm_Action_Jump


Class Summary HTML_QuickForm_Action_Jump

Class Summary HTML_QuickForm_Action_Jump

Class Summary HTML_QuickForm_Action_Jump – The action handles the HTTP redirect to a specific page.

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_Action_Jump

  • HTML_QuickForm_Action

    • HTML_QuickForm_Action_Jump

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Action_Display | PEAR Manual | Class Summary HTML_QuickForm_Action_Next


Class Summary HTML_QuickForm_Action_Next

Class Summary HTML_QuickForm_Action_Next

Class Summary HTML_QuickForm_Action_Next – The action for a 'next' button of wizard-type multipage form.

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_Action_Next

  • HTML_QuickForm_Action

    • HTML_QuickForm_Action_Next

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Action_Jump | PEAR Manual | Class Summary HTML_QuickForm_Action_Submit


Class Summary HTML_QuickForm_Action_Submit

Class Summary HTML_QuickForm_Action_Submit

Class Summary HTML_QuickForm_Action_Submit – The action for a 'submit' button.

Description

This package is not documented yet.

Class Trees for HTML_QuickForm_Action_Submit

  • HTML_QuickForm_Action

    • HTML_QuickForm_Action_Submit

Prev | HTML_QuickForm_Controller | Next
Class Summary HTML_QuickForm_Action_Next | PEAR Manual | HTML_QuickForm_Renderer_Tableless


HTML_QuickForm_Renderer_Tableless

HTML_QuickForm_Renderer_Tableless

Replacement for the default renderer of HTML_QuickForm that uses only XHTML and CSS but no table tags, and generates fully valid XHTML output.

Table of Contents
  • Introduction
  • Important methods
Prev | HTML | Next
Class Summary HTML_QuickForm_Action_Submit | PEAR Manual | Introduction


Introduction

Introduction

Table of Contents
  • Introduction -- Introduction to HTML_QuickForm_Renderer_Tableless
  • FAQ -- Answers to most Frequently Asked Questions
Prev | HTML_QuickForm_Renderer_Tableless | Next
HTML_QuickForm_Renderer_Tableless | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to HTML_QuickForm_Renderer_Tableless

Overview

HTML_QuickForm_Renderer_Tableless is a replacement of the default renderer of HTML_QuickForm. It has two main goals:

Accessibility: Because of the abandonment of table tags and the addition of for attributes to the label tags and id attributes to the form elements, the generated output provides good accessibility. Challenged person might use screen readers, and unhindered persons benefit from the possibility to click on the labels to set the focus to the belonging form element.

Validity: The generated output of the renderer is fully XHTML 1.1 valid.

Usage

To use this renderer, you just need to copy (and modify if you want) the stylesheet and do something like this:

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/Tableless.php';

$form =& new HTML_QuickForm();
$renderer =& new HTML_QuickForm_Renderer_Tableless();

// usual code, e.g. new form fields, rules, ...

$form->accept($renderer);
echo $renderer->toHtml();
?>

For full XHTML validity, you need to add the following line to your code:

<?php
$form->removeAttribute('name');
?>
Prev | Introduction | Next
Introduction | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

Description

This document is based on questions asked on PEAR general mailing list and other mailing lists and forums.

HTML_QuickForm_Renderer_Tableless FAQ

  1. The div tag in the element template is broken, a closing quote mark is missing! Can you please fix this?
  2. Why are the hidden form elements put into a div with style display: none ?
  3. The layout of the forms is broken in Windows Internet Explorer 7. Is there a solution for this problem?
  4. The layout of the forms is broken in Firefox 1.x. Is there a solution for this problem?
  5. How can I add explainations next to or after form fields with the renderer?
  6. I'm having problems with the layout, the form and/or the other contents of my page are misplaced. How can I fix these problems?
  7. When I use the tableless renderer together with HTML_QuickForm_Controller, I still see tables. What am I doing wrong?
The div tag in the element template is broken, a closing quote mark is missing! Can you please fix this?

No, it is not missing and there is no need to fix the element template.

HTML_QuickForm_Renderer_Tableless requires that HTML_QuickForm >= 3.2.6 is installed. Previous versions don't work correctly for element templates that have two error blocks.

Please use the PEAR installer to avoid such problems in the future. The installer takes care of the dependencies between packages.

Why are the hidden form elements put into a div with style display: none ?

This might sound funny because a hidden element is obviously already hidden, but the simple reason for this is the XHTML validity.

XHTML allows input elements only within block elements. And as form is not a block element, but div is a block element, this trick is used to make the output XHTML valid.

The layout of the forms is broken in Windows Internet Explorer 7. Is there a solution for this problem?

Release 0.4.3 contains a fix for this problem. The solution is to remove the "height: 1px;" style from "form fieldset li" block in the stylesheet.

Warning: This breaks layout compatibility with Firefox 1.x browsers (Firefox 2.0 still works as expected). The next question contains a solution for Firefox 1.x compatibility.

The layout of the forms is broken in Firefox 1.x. Is there a solution for this problem?

You need to add a "float: left;" style to the "form fieldset li" block in the stylesheet. In addition, you need to add the following two blocks to your stylesheet:

* html form fieldset li {
    float: none;
}
*+html form fieldset li {
    float: none;
}

If you don't need compatibility with Windows Internet Explorer 7, you don't need the mentioned CSS hacks, but can just (re-)add the "height: 1px;" style to the "form fieldset li" block in the stylesheet.

How can I add explainations next to or after form fields with the renderer?

This is explained here: Howto: Adding explainations next to form fields with Tableless QuickForm renderer.

I'm having problems with the layout, the form and/or the other contents of my page are misplaced. How can I fix these problems?

Such problems are most likely caused by the style of the fieldsets. You can try two possible solutions.

At first, you can try to add

overflow: hidden;

to the "form fieldset" block.

If this does not solve the problems, then try to remove the following two styles from the "form fieldset" block.

clear: both;
float: left;
When I use the tableless renderer together with HTML_QuickForm_Controller, I still see tables. What am I doing wrong?

You have to tell HTML_QuickForm_Controller about the usage of another renderer. A short tutorial is available: Using the tableless renderer together with HTML_QuickForm_Controller

Prev | Introduction | Next
Introduction | PEAR Manual | Important methods


Important methods

Important methods

Table of Contents
  • HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements -- Adds one or more element names that indicate the end of a fieldset (a new one will be opened when a the next header element occurs)
  • HTML_QuickForm_Renderer_Tableless::clearAllTemplates -- Clears all the HTML out of the templates that surround notes, elements, etc.
  • HTML_QuickForm_Renderer_Tableless::setElementTemplate -- Sets element template
  • HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate -- Sets the template used when closing a fieldset
  • HTML_QuickForm_Renderer_Tableless::setFormTemplate -- Sets form template
  • HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate -- Sets element template for elements within a group
  • HTML_QuickForm_Renderer_Tableless::setGroupTemplate -- Sets template for a group wrapper
  • HTML_QuickForm_Renderer_Tableless::setHeaderTemplate -- Sets header template
  • HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate -- Sets the template used when opening a fieldset
  • HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate -- Sets the template used when opening a hidden fieldset (i.e. a fieldset that is opened when there is no header element)
  • HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate -- Sets the note indicating required fields template
  • HTML_QuickForm_Renderer_Tableless::toHtml -- returns the HTML generated for the form
Prev | HTML_QuickForm_Renderer_Tableless | Next
FAQ | PEAR Manual | HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements


HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements

HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements

HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements() – Adds one or more element names that indicate the end of a fieldset (a new one will be opened when a the next header element occurs)

Synopsis

void HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements ( mixed $element , string $class = '' )

Description

Adds one or more element names that indicate the end of a fieldset (a new one will be opened when the next header element occurs).

If a class name is given, it will be added to each (hidden) fieldset that is generated before each of the specified element. For example, if you specify an array with five element names, all five fieldsets with get this additional class name.

Parameter

mixed $element

Element name(s) (as array or string)

string $class

(optional) Class name for the fieldset(s)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
Important methods | PEAR Manual | HTML_QuickForm_Renderer_Tableless::clearAllTemplates


HTML_QuickForm_Renderer_Tableless::clearAllTemplates

HTML_QuickForm_Renderer_Tableless::clearAllTemplates

HTML_QuickForm_Renderer_Tableless::clearAllTemplates() – Clears all the HTML out of the templates that surround notes, elements, etc.

Synopsis

void HTML_QuickForm_Renderer_tableless::clearAllTemplates ( )

Description

Useful when you want to use addData() to create a completely custom form look

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setElementTemplate


HTML_QuickForm_Renderer_Tableless::setElementTemplate

HTML_QuickForm_Renderer_Tableless::setElementTemplate

HTML_QuickForm_Renderer_Tableless::setElementTemplate() – Sets element template

Synopsis

void HTML_QuickForm_Renderer_Tableless::setElementTemplate ( string $html , string $element = null )

Description

Sets the template for elements.

Parameter

string $html

The HTML surrounding an element

mixed $element

(optional) Name(s) of the element to apply template for (either single element name as string or multiple element names as an array)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::clearAllTemplates | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate


HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate

HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate

HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate() – Sets the template used when closing a fieldset

Synopsis

void HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate ( string $html )

Description

Sets the template used when closing a fieldset.

Parameter

string $html

The HTML used when closing a fieldset

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setElementTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setFormTemplate


HTML_QuickForm_Renderer_Tableless::setFormTemplate

HTML_QuickForm_Renderer_Tableless::setFormTemplate

HTML_QuickForm_Renderer_Tableless::setFormTemplate() – Sets form template

Synopsis

void HTML_QuickForm_Renderer_Tableless::setFormTemplate ( string $html )

Description

Sets the form template.

Parameter

string $html

The HTML surrounding the form tags

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate


HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate

HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate

HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate() – Sets element template for elements within a group

Synopsis

void HTML_QuickForm_Renderer_tableless::setGroupElementTemplate ( string $html , string $group )

Description

Sets element template for elements within a group.

Parameter

string $html

The HTML surrounding an element

string $group

Name of the group to apply template for

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setFormTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setGroupTemplate


HTML_QuickForm_Renderer_Tableless::setGroupTemplate

HTML_QuickForm_Renderer_Tableless::setGroupTemplate

HTML_QuickForm_Renderer_Tableless::setGroupTemplate() – Sets template for a group wrapper

Synopsis

void HTML_QuickForm_Renderer_Tableless::setGroupTemplate ( string $html , string $group )

Description

This template is contained within a group-as-element template set via setTemplate() and contains group's element templates, set via setGroupElementTemplate()

Parameter

string $html

The HTML surrounding group elements

string $group

Name of the group to apply template for

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setHeaderTemplate


HTML_QuickForm_Renderer_Tableless::setHeaderTemplate

HTML_QuickForm_Renderer_Tableless::setHeaderTemplate

HTML_QuickForm_Renderer_Tableless::setHeaderTemplate() – Sets header template

Synopsis

void HTML_QuickForm_Renderer_Tableless::setHeaderTemplate ( string $html )

Description

Sets the header template.

Parameter

string $html

The HTML surrounding the header

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setGroupTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate


HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate

HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate

HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate() – Sets the template used when opening a fieldset

Synopsis

void HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate ( string $html )

Description

Sets the template used when opening a fieldset.

Parameter

string $html

The HTML used when opening a fieldset

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setHeaderTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate


HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate

HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate

HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate() – Sets the template used when opening a hidden fieldset (i.e. a fieldset that is opened when there is no header element)

Synopsis

void HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate ( string $html )

Description

Sets the template used when opening a hidden fieldset (i.e. a fieldset that is opened when there is no header element).

Parameter

string $html

The HTML used when opening a hidden fieldset

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate


HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate

HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate

HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate() – Sets the note indicating required fields template

Synopsis

void HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate ( string $html )

Description

Sets the note indicating required fields template.

Parameter

string $html

The HTML surrounding the required note

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate | PEAR Manual | HTML_QuickForm_Renderer_Tableless::toHtml


HTML_QuickForm_Renderer_Tableless::toHtml

HTML_QuickForm_Renderer_Tableless::toHtml

HTML_QuickForm_Renderer_Tableless::toHtml() – returns the HTML generated for the form

Synopsis

string HTML_QuickForm_Renderer_Tableless::toHtml ( )

Description

Returns the HTML generated for the form.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Important methods | Next
HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate | PEAR Manual | HTML_QuickForm_DHTMLRulesTableless


HTML_QuickForm_DHTMLRulesTableless

HTML_QuickForm_DHTMLRulesTableless

HTML_QuickForm_DHTMLRulesTableless is a DHTML replacement for the standard JavaScript alert window for client-side validation of forms built with HTML_QuickForm when using the HTML_QuickForm_Renderer_Tableless renderer.

In addition to the standard behaviour of HTML_QuickForm (i.e. showing the errors from client-side validation on the "onSubmit" event), this package can also show the errors on the "onBlur" and "onChange" events (see below for information on how to enable this).

Table of Contents
  • Usage
Prev | HTML | Next
HTML_QuickForm_Renderer_Tableless::toHtml | PEAR Manual | Usage


Usage

Usage

To use this package you just need to do something like this:

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/DHTMLRulesTableless.php';
require_once 'HTML/QuickForm/Renderer/Tableless.php';

$form = new HTML_QuickForm_DHTMLRulesTableless(...);
$renderer = new HTML_QuickForm_Renderer_Tableless();

// usual code, e.g. new form fields, rules, ...

$form->accept($renderer);
echo $renderer->toHtml();
?>

As already said for the tableless renderer, you need to add the following line to your code to get full XHTML validity:

<?php
$form->removeAttribute('name');
?>
Note: $form can be used the same way as with the standard HTML_QuickForm package, there is no difference.

To enable validation on "onBlur" and "onChange" events, you need to add the following line before the $form->accept($renderer); call:

<?php
$form->getValidationScript();
?>
Prev | HTML_QuickForm_DHTMLRulesTableless | Next
HTML_QuickForm_DHTMLRulesTableless | PEAR Manual | HTML_QuickForm_advmultiselect


HTML_QuickForm_advmultiselect

HTML_QuickForm_advmultiselect

Element for HTML_QuickForm that emulate a multi-select.

Table of Contents
  • Summary
  • Getting started
  • Reference guide
  • Examples appendix
Prev | HTML | Next
Usage | PEAR Manual | Summary


Summary

Summary

Table of Contents
  • Why use HTML_QuickForm_advmultiselect ?
  • Features
  • System Requirements
  • About
Prev | HTML_QuickForm_advmultiselect | Next
HTML_QuickForm_advmultiselect | PEAR Manual | Why use HTML_QuickForm_advmultiselect ?


Why use HTML_QuickForm_advmultiselect ?

Why use HTML_QuickForm_advmultiselect ?

I am sure we have all been there, dealing with HTML_QuickForm because we need to allow users to select multiple options. With a standard html select box, you can select multiple options if the multiple attribute is set, but you have to hold down the appropriate modifier key (ctrl on windows) in order to do so. It is not a problem for end-user experts, but it is not true for all of us.

A quick list of great features

  • ability to double click on either select box to move elements from one side to the other.

  • add headers to the select boxes.

  • ability to change layout easily, using CSS classes and a mini template.

  • allows to change item size shown of each multiple select box.

  • ability to manage one single list with checkboxes to solve problem if javascript is unavailable.

Prev | Summary | Next
Summary | PEAR Manual | Features


Features

Features

  • ability to double click on either select box to move elements from one side to the other

  • added headers to the select boxes

  • ability to change layout easily, using CSS classes and a mini template

  • allows to change item size shown of each multiple select box

  • ability to manage one single list with checkboxes to solve problem if javascript is unavailable

  • ability to sort lists (by programming, or user-end handling)

  • display live counter (selected/unselected items count). Available since version 1.3.0

  • ability to use fancy attributes (disabled, CSS class and style) on both template mode (single or dual) and keep them on move. Available since version 1.5.0

  • add or remove persistant options (disabled attribute) at run-time. Available since version 1.5.0

Prev | Summary | Next
Why use HTML_QuickForm_advmultiselect ? | PEAR Manual | System Requirements


System Requirements

System Requirements

Mandatory resources :

  • PHP 4.3.10 or newer.

  • PEAR 1.5.4 or newer.

  • PEAR::HTML_Common 1.2.4 or newer.

  • PEAR::HTML_Quickform 3.2.10 or newer.

  • pcre extension.

Optional resources :

  • PHP 5.0.0 or newer.

  • PHPUnit 3.2.0 or newer.

Prev | Summary | Next
Features | PEAR Manual | About


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

HTML_QuickForm_advmultiselect FAQ

    General questions

    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 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.

    What is HTML_QuickForm ?

    HTML_QuickForm is a PEAR package that provides methods for creating, validating and processing HTML forms.

    The purpose of Keith Edmunds tutorial is to give the new users of QuickForm an overview of its features and usage patterns. It describes a small subset of available functionality.

    Don't forget to read also the PEAR Manual, HTML_QuickForm related part.

    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.

    How to

    May i use HTML_QuickForm_advmultiselect if my browser is no javascript compliant or if javascript is disabled ?

    The dual multi-select won't work, but you can display a single multi select box witch checkboxes. To do so, you have to remove {unselected} placeholder in the advmultiselect template element.

    How to validate a HTML_QuickForm_advmultiselect element ?

    You must use the HTML_QuickForm addGroupRule() method rather than HTML_QuickForm addRule() method.

    How to optimize javascript code usage on html generated page ?
    Caution

    Following answers can be applied only for HTML_QuickForm_advmultiselect version 1.3.0 or better.

    Use only once reference of javascript source code. If you have more than one advmultiselect element on your html page, then keep only one call and remove others.

    <script type="text/javascript">
    <?php
    echo $ams1->getElementJs();    // keep one

    //echo $ams2->getElementJs();  // remove others
    ?>
    </script>

    Better solution is to use link to external resource and then reduce amount of javascript source code embedded. Add line of code below between <head> tags of your generated page.

    <script type="text/javascript" src="qfamsHandler.js"></script>

    Note: Fix path to javascript resource if necessary. qfamsHandler.js file can be found in PEAR/data/HTML_QuickForm_advmultiselect directory.

    At least remove {javascript} placeholder if you use default template. You have to set this new one $deftpl, with code something like :

    <?php
    require_once 'HTML/QuickForm.php';
    require_once     'HTML/QuickForm/advmultiselect.php';

    $form = new HTML_QuickForm('ams130');
    // ....
    $ams =& $form->addElement('advmultiselect', 'cars', null, $car_array);

    $deftpl = '
    <table{class}>
    <!-- BEGIN label_2 --><tr><th>{label_2}</th><!-- END label_2 -->
    <!-- BEGIN label_3 --><th>&nbsp;</th><th>{label_3}</th></tr><!-- END label_3 -->
    <tr>
      <td valign="top">{unselected}</td>
      <td align="center">{add}{remove}</td>
      <td valign="top">{selected}</td>
    </tr>
    </table>
    '    ;

    $ams->setElementTemplate($deftpl);
    //...
    ?>

    Troubleshooting guide

    My Quickform advmultiselect element is not displayed on my browser window.

    You should have forgotten to add package ressource itself. This operation is mandatory for all external Quickform elements and not necessary for internal elements such as "radio", "checkbox", "text", "button" ...

    <?php
    require_once 'HTML/QuickForm.php';
    require_once     'HTML/QuickForm/advmultiselect.php';  // <-- DO NOT forget it
    ?>
    My live counter is not updated with a single select list, when I click on checkboxes ?

    With HTML_QuickForm_advmultiselect version 1.3.0 or better you need to add a chunk of javascript code to initialize onclick event handler of each checkboxes.

    <script type="text/javascript" src="qfamsHandler.js"></script>
<script type="text/javascript">
window.qfamsName = new Array();
window.qfamsName[0] = 'cars';
window.qfamsName[1] = 'fruit';
window.addEventListener('load', qfamsInit, false);
</script>

    window.qfamsName is an array what identify each advmultiselect element used on your html page.

    The selected list has one blank entry that you can move to available list

    This problem comes when you set the selected list (see HTML_QuickForm::setDefaults method) with a wrong data array.

    Remember that the available list contains all datas (selected and unselected values). This list is an associative array of "key-code" => "display-value". While selected list is only an array of "key-code".

    Suppose we have to retrieve information from a database (with PEAR::DB), and have a simple table for holding user info. This SQL statement creates a table usable under the default database scheme using MySQL:

    CREATE TABLE user (
   userid VARCHAR(5) NOT NULL,
   gid INT NOT NULL,
   affect INT NOT NULL,
   lastname VARCHAR(50)NOT NULL,
   firstname VARCHAR(50) NOT NULL,
   PRIMARY KEY (userid)
);

    with values :

    INSERT INTO user VALUES ('MJ001', 1, 0, 'Martin', 'Jansen');
INSERT INTO user VALUES ('BG001', 1, 1, 'Greg', 'Beaver');
INSERT INTO user VALUES ('CD001', 1, 0, 'Daniel', 'Convissor');
INSERT INTO user VALUES ('LL001', 2, 1, 'Laurent', 'Laville');

    Column gid identify a user group, while userid identify a single and unique user.

    We will initialize AVAILABLE list (on left side if default template) by a db query something like that:

    <?php
    $queryAll     = 'SELECT userid, CONCAT(lastname, " ", firstname) AS useridentity '
                  . 'FROM user WHERE gid = 1';
    ?>

    and get this array:

    Array
(
    [MJ001] => Jansen Martin
    [BG001] => Beaver Greg
    [CD001] => Convissor Daniel
)

    We will initialize SELECTED list (on right side if default template) by a db query something like that:

    <?php
    // Once you have a valid DataBase object named $db ...

    $querySel = 'SELECT userid FROM user WHERE gid = 1 AND affect = 1';
    $affected_user =& $db->getCol($querySel);
    ?>

    and get this array:

    Array
(
    [0] => BG001
)

    Caution

    Remember that only a key-code array is necessary, other data will make blank line into select box.

    Remains stuff is basic, create the QFAMS element, and load options (available and selected) with the load() method.

    <?php
    require_once 'HTML/QuickForm.php';
    require_once     'HTML/QuickForm/advmultiselect.php';

    $form = new HTML_QuickForm('amsDB');

    // Once you have a valid QuickForm advmultiselect object named $ams in a QuickForm named $form ...

    $ams =& $form->addElement('advmultiselect', 'user',
        array(    'Users:', 'Available', 'Affected'),       // labels
            null,                                           // datas: "key-code" => "display-value"
            array('style' => 'width:200px;')                // custom layout
    );
    $ams->load($db, $queryAll, 'useridentity', 'userid', $affected_user);

    // ...
    ?>

    Tip

    You may use the load() method to set options from :

    <?php
    // ...

    // 1. a php array
    $all_user = array('MJ001' => 'Martin Jansen',
                          'BG001' => 'Greg Beaver',
                          'CD001' => 'Daniel Convissor'
    );
    $affected_user = array('BG001');
    $ams->load($all_user, $affected_user);

    // queries to get data
    $queryAll = 'SELECT userid, CONCAT(lastname, " ", firstname) AS useridentity '
                  . 'FROM user WHERE gid = 1';

    $querySel = 'SELECT userid FROM user WHERE gid = 1 AND affect = 1';
    $affected_user =& $db->getCol($querySel);

    // 2. a db result
    $all_user =& $db->query($queryAll);
    $ams->load($all_user, 'useridentity', 'userid', $affected_user);

    // 3. a db query
    $ams->load($db, $queryAll, 'useridentity', 'userid', $affected_user);

    // ...
    ?>
    Note: This example is available in bundle (see examples/qfams_basic_2.php)
    Prev | About | Next
About | PEAR Manual | News


News

News

News – What is New in version ?

Version 0.5.x

  • add auto arrange feature (developer issue) asked by Jamie Alessio.

  • ability to manage (sort) list with two buttons (Up and Down)

Version 1.0.x

  • Add new example Basic 2 to demonstrate the db options loading feature with PEAR::DB and a MySQL database.

  • Include the first html version of a complete english guide for both beginners and expert users.

Version 1.1.x

  • Ability to select/unselect all items (options) in one stroke. You may also toggle a selection.

Version 1.2.x

  • Add toggle button ability to a dual multi-select boxes.

    Ability to toggle selection was only available for single select box shape since version 1.1.0

Version 1.3.x

  • New placeholders to display live counters (unselected, selected items).

Version 1.4.x

  • License change from PHP 3.01. to BSD.

  • Produces now XHTML 1.0 Strict compliant output

Version 1.5.x

  • remove dreprecated function (setJsElement) since version 1.3.0

  • rewrites JS in object literal notation (uses namespace)

  • add two new buttons to move up to top or down to bottom a selected item

  • add a minimized/compressed version of Javascript code

  • may now load options (class constructor, or load functions) with fancy attributes without additional code

  • options with fancy attributes are kept even if you move them (left right, up down)

  • setElementTemplate() function signature changed (but keep BC) : allow to use only one instance of javascript code

  • add or remove persistant options (disabled attribute) at run-time, with HTML_QuickForm_advmultiselect::setPersistantOptions() .

  • PEAR_Error instance throws have now a level (exception or error) and a code identified by HTML_QUICKFORM_ADVMULTISELECT_ERROR_INVALID_INPUT constant

Prev | About | Next
FAQ | PEAR Manual | Getting started


Getting started

Getting started

Table of Contents
  • Basic features
  • Advanced features
Prev | HTML_QuickForm_advmultiselect | Next
News | PEAR Manual | Basic features


Basic features

Basic features

Table of Contents
  • Overview -- features and usage patterns
  • Your first form -- basic usage
Prev | Getting started | Next
Getting started | PEAR Manual | Overview


Overview

Overview

Overview – features and usage patterns

In brief

The purpose of this tutorial is to give the new users of HTML_QuickForm_advmultiselect an overview of its features and usage patterns. It describes a small subset of available functionality, but points to the parts of the documentation that give a more in-depth overview.

Basic concepts

In a usability test with non-information workers in an intranet application, we could be surprised that none (or few) of the users successfully selected multiple responses when presented in a HTML select element with multiple selection enabled. They simply did not know that control click exist.

To solve this problem, the QuickForm advmultiselect element provides an interface that allow user-end to do their selection very easily. In this interface, there are:

  • a list with all items still available for selection.

  • a list with all items already selected.

  • two buttons to swap items from one list to the other.

For each new item to add to your selection, select it from the unselected list (source), then clic on the add button to move it to the selection list (destination). It does not exists in the source list after transfer.

For each item to remove from your selection, select it in the selected list (source), then clic on the remove button to move it to the unselected list (destination). It does not exists in the source list after transfer.

Prev | Basic features | Next
Basic features | PEAR Manual | Your first form


Your first form

Your first form

Your first form – basic usage

Basic features

We will start by creating a very simple form. Our goals are :

  • change the buttons (add, remove) position. Move at bottom of lists.

  • center headers at top of lists.

  • set list item visible to 5. Default is 10.

  • enlarge both list width to 300 pixels. Default width is only 100 pixels.

  • change background colors element.

Copy the following code to a file, give it a .php extension, and display it in your browser:

<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * using stylesheet rules selectors and a template.
 *
 * The template allows to add label as headers of dual select box
 * and moves the button to another location (below each select box).
 *
 * @version    $Id: firstform.xml,v 1.2 2009/02/09 17:10:32 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_custom_1.php
 *             qfams_custom_1 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom1.png
 *             screenshot (Image PNG, 677x197 pixels) 4.80 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsCustom1');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('size' => 5,
                                 'class' => 'pool', 'style' => 'width:300px;'
                                )
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                           'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                           'class' => 'inputCommand'
));
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td>{selected}</td>
</tr>
<tr>
  <td align="center">{add}</td>
  <td align="center">{remove}</td>
</tr>
</table>';
$ams->setElementTemplate($template);

if (isset($_POST['fruit'])) {
    $form->setDefaults(array('fruit' => $_POST['fruit']));
}

$form->addElement('submit', 'send', 'Send');

?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 1</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: lightyellow;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  background-color: lightblue;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid #7B7B88;
    width: 7em;
    margin-bottom: 2px;
}
 -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>

Lets review this example step by step :

Line 23 :

At the beginning we creates a HTML_Quickform object that will contain the objects representing elements and all the other necessary information. We only pass the form's name to the constructor, which means that default values will be used for other parameters.

Lines 39, 41, 72 :

Our form will consist of three elements:

The first one is not the "real" element, it is just a heading to improve presentation. The second one is our advmultiselect element. Note that parameters for HTML_Quickform::addElement method have different meanings for different elements. That is so because they are actually passed to these elements' constructors.

Lines 26-36 :

The $fruit_array variable sets the default values (code, label) for the fruit advmultiselect element.

Lines 42-44 :

It's time to define the fruit element attributes:

size

Give count of visible item in each list. Default is 10.

style

The select boxes width in pixel. Default is 100.

class

A CSS class identifier to override the look and feel. There is no default.

Lines 46, 55, 56 :

To put headers on each list (wherever you want: at top, or bottom), you need first to set these values. Then second, defines the placeholder in the template (as any other multi-label element).

Important: Placeholders {label_2}, {label_3} are used, in the same way, for all HTML_Quickform renderers , and defines: unselected list (label_2), and selected list (label_3).
Lines 47, 62 and 50, 63 :

Last step to complete definition of a advmultiselect element is to set the add and remove buttons.

Here we gave names Add >> and << Remove, with a skin handled by the inputCommand CSS class.

Placeholders {add}, {remove} must exists into the template. Without them you won't see the move buttons.

Line 69 :

User's input overrides default values of the fruit advmultiselect element.

Line 110 :

Before to validate and process the form, the building form step need one more thing. Don't forget, that to manage swaps between both list, we need some javascript code. It's now time to include into our HTML stream/template.

Note: By given the false value as argument to the getElementJs method, we have choosen to build javascript code with its script tags. Default behavior is to get only raw code without surrounding script tags. May be usefull with template integration and existing js code.
Line 114 :

We have now the form built and need to decide whether to process it or display.

Line 115 :

This is a simple display example. In your scripts you'll usually want to store the values somewhere or do whatever else. The HTML_Quickform::process method may be of interest here.

Line 121 :

The last line is pretty easy. If the form is not valid, which means that it either was not yet submitted or that there were errors, it will be displayed.

Prev | Basic features | Next
Overview | PEAR Manual | Advanced features


Advanced features

Advanced features

Table of Contents
  • Headers -- how to customize labels
  • Buttons -- how to customize action buttons
  • Sorts -- how to sort results
  • Live counters -- get number of item in results

You should now have an understanding of basic HTML_QuickForm_advmultiselect functionality, but there are many more features in the package, each of them deserving a separate tutorial. This section will give a short overview of them and point you to the complete documentation.

The advmultiselect element offers a lot of possibilities to customize its layout and appearance. Remember that form output is done via renderers - special classes containing necessary logic. There are QuickForm renderers that directly output HTML and those that use template engines for this.

Headers allow to give caption (label) to one or both list as any other QuickForm element that support multi-labels system.

Buttons allow to swap items from one list to the other, or arrange order of your selection.

Sorts allow to re-arrange order of the selection, by the end-user. Its also allow to set (by programming) a pre-set order (alphabetic or reverse) to each list.

Prev | Getting started | Next
Your first form | PEAR Manual | Headers


Headers

Headers

Headers – how to customize labels

Introduction

A label is a description text that will be displayed near the element. Some renderers can handle multiple labels for the element. Placeholders used by these renderers are different in naming convention. Nevermind, HTML_QuickForm_advmultiselect used only one standard coding that is equivalent to the QuickForm default renderer.

As {label_2} is the placeholder for the second label (unselected list), {label_3} is the placeholder for the third label (selected list), in the hash setting. See HTML_Quickform::setLabel method.

Important:

The first label is always for the advmultiselect element group itself. Its name depend of the QuickForm renderer used. See examples that follow to notice the difference.

Naming with QuickForm Default Renderer

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$template =
'<tr>
    <td align="right" valign="top">
        <b>{label}</b>
    </td>
    <td valign="top" align="left">
        {element}
        <!-- BEGIN error --><br/><font color="red">{error}</font><br/><!-- END error -->
    </td>
</tr>';

// Create the form, and add a header to it.
$form = new HTML_QuickForm('qfamsLabels');
$form->addElement('header', null, 'QuickForm Labels Example: default renderer');

$cars = array(
    'dodge'     =>  'Dodge',
    'chevy'     =>  'Chevy',
    'bmw'       =>  'BMW',
    'audi'      =>  'Audi',
    'porsche'   =>  'Porsche',
    'kia'       =>  'Kia',
    'subaru'    =>  'Subaru',
    'mazda'     =>  'Mazda',
    'isuzu'     =>  'Isuzu',
);

$labels = array('Cars:', 'Models', 'Your selection');

// Do the magic! Just pass your label to the element as an array!
$form->addElement('advmultiselect', 'cars', $labels, $cars);

// customize the element template
$renderer =&amp; $form->defaultRenderer();
$renderer->setElementTemplate($template);

// output the form
$form->display();
?>

Line 8 :

The first label with default renderer, is always named {label}.

Line 32 :

In this example, its value will be Cars:

Naming with QuickForm ITDynamic Renderer

<?php
require_once 'HTML/Template/Sigma.php';
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$template = '
<form {qf_attributes}>
<table class="maintable">

<!-- BEGIN qf_hidden_block -->
<div style="display: none;">
  <!-- BEGIN qf_hidden_loop -->{qf_hidden}<!-- END qf_hidden_loop -->
</div>
<!-- END qf_hidden_block -->

<!-- BEGIN qf_main_loop -->

  <!-- BEGIN qf_header -->
  <tr><th class="maintable" colspan="2">{qf_header}</th></tr>
  <!-- END qf_header -->

  <!-- BEGIN qf_element -->
  <tr>
    <td align="right" width="30%"><span class="qfLabel">{qf_label}&amp;nbsp;</span></td>
    <td>{qf_element}
      <!-- BEGIN qf_element_error --><br /><span style="color: #FF0000;">{qf_error}</span><!-- END qf_element_error -->
    </td>
  </tr>
  <!-- END qf_element -->

<!-- END qf_main_loop -->
</table>
</form>
';

// Create the form, and add a header to it.
$form = new HTML_QuickForm('qfamsLabels');
$form->addElement('header', null, 'QuickForm Labels Example: itdynamic renderer');

$cars = array(
    'dodge'     =>  'Dodge',
    'chevy'     =>  'Chevy',
    'bmw'       =>  'BMW',
    'audi'      =>  'Audi',
    'porsche'   =>  'Porsche',
    'kia'       =>  'Kia',
    'subaru'    =>  'Subaru',
    'mazda'     =>  'Mazda',
    'isuzu'     =>  'Isuzu',
);

$labels = array('Cars:', 'Models', 'Your selection');

// Do the magic! Just pass your label to the element as an array!
$form->addElement('advmultiselect', 'cars', $labels, $cars);

// set the form template
$tpl = new HTML_Template_Sigma('.');
$tpl->setTemplate($template);

$renderer = new HTML_QuickForm_Renderer_ITDynamic($tpl);

$form->accept($renderer);

// output the form
$tpl->show();
?>

Line 25 :

The first label with ITDynamic renderer, is always named {qf_label}.

Line 53 :

In this example, its value is still Cars:

In practice

Lets review in details how to set the appearance of headers in one of examples included in the package.

After the labels are set:

<?php
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
?>

Have a special look on the advmultiselect template element. Here is it:

<?php
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td>{selected}</td>
</tr>
<tr>
  <td align="center">{add}</td>
  <td align="center">{remove}</td>
</tr>
</table>';
?>

Line 4 :

Header for the unselected list (named Available) is center aligned in bold with the TH tag.

Line 5 :

Header for the selected list (named Selected), is also center aligned in bold with another TH tag.

Tip

To give only a header to the selection list, either you set values as:

<?php
$ams->setLabel(array('Fruit:', null, 'Your selection'));
?>

or you remove line beginning by <!-- BEGIN label_2 --> into the advmultiselect template element.

Prev | Advanced features | Next
Advanced features | PEAR Manual | Buttons


Buttons

Buttons

Buttons – how to customize action buttons

Introduction

There is two categories of button: sort and swap.

The swap buttons are included since origin, while the sort buttons were included in the 0.5.0 version.

With swap buttons, you will do your selection easily. Select item(s) (one or more), from unselected or selected list, then clic on the add or remove button to move your selection from one list to the other.

Tip

You can also double-clic on one item to move it, immediately, to the other list without to clic on the add or remove button.

Since version 1.1.0 you have ability to select or unselect all items in one stroke. You may also toggle a previous selection. This new feature is available through buttons all, none and toggle.

Since version 1.2.0 toggle selection feature is available for both single and dual multi-select boxes.

Note:

  • with one multi-select list, buttons available are only: all, none and toggle.

  • with two multi-select list, buttons available are only: add, remove, moveup, movedown, all, none and toggle.

    Since version 1.5.0, you may add to buttons list : movetop and movebottom.

A full example is given in appendices. See the advanced selection

With sort buttons, you have ability to reorder your selection easily. Select one item then clic on the up or down button to move it to the top or the bottom of your selection.

Note: Order is keep in the $_POST super global array, when the form is submit; Even if you've activated the auto-arrange feature (see $sort parameter of the HTML_QuickForm_advmultiselect class constructor )

Appearance

There is two kinds of button: text and image. These are the standard html buttons we can find in a form. Default appearance is text but you can also easily use image layout. Here is how to do :

<?php
$ams->setButtonAttributes('add',    array('type' => 'image', 'src' => '/img/add.png'));
$ams->setButtonAttributes('remove', array('type' => 'image', 'src' => '/img/remove.png'));
?>

Of course, all images are supported: PNG, GIF ...

Caution

If the image file does not exist, you will get the internal text value as output without nothing else.

Remember that defaults are: " >> " for add button, and " << " for remove button.

Attributes

In version 0.4.0, there were only the basic add and remove buttons. In version 0.5.0, two new buttons were added: moveup and movedown. In version 1.1.0, three new buttons were added: all, none, and toggle. In version 1.5.0, two new buttons were added: movetop and movebottom.

Caution

Any other button identifier than add, remove, all, none, toggle, moveup, movedown, movetop, movebottom will throws a PEAR_Error.

Only five attributes may be set, with these four button identifiers; they are:

name

The form input button name. Default are: 'add', or 'remove', or 'all, or 'none', or 'toggle', or 'up', or 'down', or 'top', or 'bottom'.

Default values of the name attribute are not equivalent to button identifiers.

value

The form input button text. Default are : ' >> ', or ' << ', or ' Select All ', or ' Select None ', or ' Toggle Selection ', or ' Up ', or ' Down ', or ' Top ', or ' Bottom '.

type

The form input button kind. Default is 'button' (Can be either 'button' or 'image').

class

A CSS class identifier in one of your stylesheets.

src

URL of the image file used.

Prev | Advanced features | Next
Headers | PEAR Manual | Sorts


Sorts

Sorts

Sorts – how to sort results

Introduction

There are two kind of sort with the advmultiselect element: The first one is only available by programming and allow an auto-arrange (alphabetic or reverse order) of each select list. The second is for end-user and allow them to sort their selection as they want.

Important: These features required HTML_QuickForm_advmultiselect package version 0.5.0 or better.

Auto-arrange

In some case, it could be interresting to have items lists sort alphabetically when elements are moved between them, rather than gets added to the bottom (default behavior).

To get both list sort alphabetically, you have to set the $sort parameter of the HTML_QuickForm_advmultiselect class constructor with the PHP SORT_ASC constant.

To get both list sort in reverse order, you have to set the $sort parameter of the HTML_QuickForm_advmultiselect class constructor with the PHP SORT_DESC constant.

A full example is given in appendices. See the sort usage

With buttons

The other way to have your selection sorted is with help of two buttons: moveup to move an item to the top of the list, and movedown to move an item to the bottom of the list.

Note: These buttons works only with the selection list

A full example is given in appendices. See the sort usage

Prev | Advanced features | Next
Buttons | PEAR Manual | Live counters


Live counters

Live counters

Live counters – get number of item in results

Introduction

When selection lists have lot of item, we don't expect to count each item one by one.

When it's so easy to count selections on server side, once the form is submitted, there is no ability to do the same in live, until new feature "Live counter".

Important:

This feature require HTML_QuickForm_advmultiselect package version 1.3.0 or better.

A full example is given in appendices. See live counter combines with multiple elements

Identification and localisation

Implements display of live counters (selected, unselected items) is fully independant. Its requires for each counter to add new placeholders.

For item unselected list, these placehodlers are :

  • {unselected_count} for localisation (where the counter value will be displayed)

  • {unselected_count_id} for identification by DOM API (ID attribut of any HTML tag)

For item selected list, these placehodlers are :

  • {selected_count} for localisation (where the counter value will be displayed)

  • {selected_count_id} for identification by DOM API (ID attribut of any HTML tag)

Note:
<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';
// ...
$form = new HTML_QuickForm('amsLC');
$ams =& $form->addElement('advmultiselect', 'cars', null, $car_array);
// ...
?>

Counters identifiers (attribut ID) used by DOM API are identified by string : advmultiselect element name concat with "_selected" or "_unselected" suffix (depending of lists).
Result for example (previous code) : cars_selected or cars_unselected
advmultiselect element with single list (with checkboxes) are identified by string : "qfams_" prefix concat with advmultiselect element name
Result for example (previous code) : qfams_cars
advmultiselect element with double list are identified with string : prefix "__" (two underscores) concat with advmultiselect element name for unselected list. While selection list (selected item) is identified with string : prefix "_" (one underscore) concat with advmultiselect element name.
Result for example (previous code) : __cars and _cars

Important: advmultiselect elements with single list (with checkboxes) are identified by DOM API with only {selected_count} and {selected_count_id} placeholders. No need to add {unselected_count} and {unselected_count_id} placeholders. See example in appendix Live counter combines with multiple elements, and template definition $template1 lines 49-57.
Prev | Advanced features | Next
Sorts | PEAR Manual | Reference guide


Reference guide

Reference guide

Table of Contents
  • Creating the form element
  • Buttons
  • Basic renderer
  • Template-based renderer

This reference describes every method in the HTML_QuickForm_advmultiselect class.

In a two multi-select boxes default shape, there are :

  • a list with all unselected values (on left side)

  • a list with all selected values (on right side)

  • two buttons (add, remove) to swap items from one list to the other (on middle side)

  • optional headers for each list

In a single multi-select box default shape, there are :

  • a list with all values (selected: checkbox on, unselected: checkbox off)

  • none buttons

  • optional header for the list

Note: Buttons (up, down) to sort item are unavailable in a single multi-select box shape.

In a two multi-select boxes custom shape, you may also have :

  • two buttons to sort selected item (by user-end)

Important: There are no order between setting button (up, down) attributes and setting placeholders {moveup}, {movedown} into the template.
Prev | HTML_QuickForm_advmultiselect | Next
Live counters | PEAR Manual | Creating the form element


Creating the form element

Creating the form element

Table of Contents
  • constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect -- Class constructor
  • HTML_QuickForm_advmultiselect::load -- Loads options from different types of data sources
  • HTML_QuickForm_advmultiselect::loadArray -- Loads the options from an associative array
  • HTML_QuickForm_advmultiselect::getPersistantOptions -- Returns list of persistant options
  • HTML_QuickForm_advmultiselect::setPersistantOptions -- Sets which items should be persistant

With the class constructor, you have ability to set the auto-arrange feature. This feature is an option to sort alphabetically (or reverse) when elements are moved between lists. Default behaviour is no sort (add to the bottom).

This feature is only available since version 0.5.0

You may either load options from the class constructor or with the load or loadArray functions.

load and loadArray functions with fancy attributes (disabled, style:color, ...) support are only available since version 1.5.0

Prev | Reference guide | Next
Reference guide | PEAR Manual | constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect


constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect

constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect

constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect() – Class constructor

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

void constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect ( string $elementName = NULL , mixed $elementLabel = NULL , mixed $options = NULL , mixed $attributes = NULL , integer $sort = NULL )

Description

This package is not documented yet.

Parameter

string $elementName

Dual Select name attribute

mixed $elementLabel

Label(s) for the select boxes

mixed $options

Data to be used to populate options

mixed $attributes

Either a typical HTML attribute string or an associative array

integer $sort

Either SORT_ASC for auto ascending arrange, SORT_DESC for auto descending arrange, or NULL for no sort (append at end: default)

Throws

throws no exceptions thrown

Note

since version 0.4.0 (2005-06-25)

This function can not be called statically.

Prev | Creating the form element | Next
Creating the form element | PEAR Manual | HTML_QuickForm_advmultiselect::load


HTML_QuickForm_advmultiselect::load

HTML_QuickForm_advmultiselect::load

HTML_QuickForm_advmultiselect::load() – Loads options from different types of data sources

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

PEAR_Error HTML_QuickForm_advmultiselect::load ( mixed &$options , mixed $param1 = null , mixed $param2 = null , mixed $param3 = null , mixed $param4 = null )

Description

This method overloaded parent method of select element, to allow loading options with fancy attributes.

Parameter

mixed &$options

Options source currently supports assoc array or DB_result

mixed $param1

(optional) See function detail

mixed $param2

(optional) See function detail

mixed $param3

(optional) See function detail

mixed $param4

(optional) See function detail

Return value

returns TRUE on success

Throws

throws PEAR_Error

See

see HTML_QuickForm_advmultiselect::loadArray() .

Note

since version 1.5.0 (2009-02-15)

This function can not be called statically.

Example

<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * loading values with fancy attributes (disabled, ...)
 *
 * @version    $Id: load.xml,v 1.1 2009/02/01 15:12:40 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_custom_3.php
 *             qfams_custom_3 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom3.png
 *             screenshot (Image PNG, 374x275 pixels) 4.96 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsCustom3');
$form->removeAttribute('name');        // XHTML compliance

// same as default element template but wihtout the label (in first td cell)
$withoutLabel = <<<_HTML
<tr valign="top">
    <td align="right">
        &nbsp;
    </td>
    <td align="left">
        <!-- BEGIN error --><span style="color: #ff0000;">{error}</span><br /><!-- END error -->{element}
    </td>
</tr>
_HTML;

// more XHTML compliant
// replace default element template with label, because submit button have no label
$renderer =& $form->defaultRenderer();
$renderer->setElementTemplate($withoutLabel, 'send');

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  array('Pear', array('disabled' => 'disabled')),
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->createElement('advmultiselect', 'fruit', null, null,
                             array('class' => 'pool')
);

$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                           'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                           'class' => 'inputCommand'
));
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td>{selected}</td>
</tr>
<tr>
  <td>{add}</td>
  <td>{remove}</td>
</tr>
</table>';
$ams->setElementTemplate($template);

$ams->load($fruit_array, 'apple,pear');

$form->addElement($ams);
$form->addElement('submit', 'send', 'Send');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 3</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: lightyellow;
}
table.pool td {
  padding-left: 1em;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  background-color: lightblue;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid #7B7B88;
    width: 7em;
    margin-bottom: 2px;
}
 -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Creating the form element | Next
constructor HTML_QuickForm_advmultiselect::HTML_QuickForm_advmultiselect | PEAR Manual | HTML_QuickForm_advmultiselect::loadArray


HTML_QuickForm_advmultiselect::loadArray

HTML_QuickForm_advmultiselect::loadArray

HTML_QuickForm_advmultiselect::loadArray() – Loads the options from an associative array

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

mixed HTML_QuickForm_advmultiselect::loadArray ( array $arr , mixed $values = null )

Description

This method overloaded parent method of select element, to allow to load array of options with fancy attributes.

Parameter

array $arr

Associative array of options

mixed $values

(optional) Array or comma delimited string of selected values

Return value

returns TRUE on success

Throws

throws PEAR_Error

See

see HTML_QuickForm_advmultiselect::load()

Note

since version 1.5.0 (2009-02-15)

This function can not be called statically.

Example

See HTML_QuickForm_advmultiselect::load() example.

Prev | Creating the form element | Next
HTML_QuickForm_advmultiselect::load | PEAR Manual | HTML_QuickForm_advmultiselect::getPersistantOptions


HTML_QuickForm_advmultiselect::getPersistantOptions

HTML_QuickForm_advmultiselect::getPersistantOptions

HTML_QuickForm_advmultiselect::getPersistantOptions() – Returns list of persistant options

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

array HTML_QuickForm_advmultiselect::getPersistantOptions ( )

Description

Returns list of persistant options (key-values) that could not be selected or unselected.

Throws

throws no exceptions thrown

Note

since version 1.5.0 (2009-02-15)

This function can not be called statically.

Prev | Creating the form element | Next
HTML_QuickForm_advmultiselect::loadArray | PEAR Manual | HTML_QuickForm_advmultiselect::setPersistantOptions


HTML_QuickForm_advmultiselect::setPersistantOptions

HTML_QuickForm_advmultiselect::setPersistantOptions

HTML_QuickForm_advmultiselect::setPersistantOptions() – Sets which items should be persistant

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

mixed HTML_QuickForm_advmultiselect::setPersistantOptions ( mixed $optionValues , boolean $persistant = true )

Description

Sets which items should have the disabled attribute to keep it persistant

Parameter

mixed $optionValues

Options (key-values) that should be persistant

boolean $persistant

(optional) TRUE if persistant, FALSE otherwise

Throws

Possible PEAR_Error values
Error message | Reason | Solution
Argument 1 of HTML_QuickForm_advmultiselect::setPersistantOptions is not a valid array | Tried to give array or comma delimited string of selected values | Check the $optionValues argument data type and content
Argument 2 of HTML_QuickForm_advmultiselect::setPersistantOptions is not a boolean | Tried to give a TRUE or FALSE value | Check the $persistant argument data type

Note

since version 1.5.0 (2009-02-15)

This function can not be called statically.

Example

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('ams');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'tangerine' =>  'Tangerine'
);

$ams =& $form->createElement('advmultiselect', 'fruit', null, null,
                             array('class' => 'pool', 'style' => 'width:200px;')
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));

$ams->setButtonAttributes('add'       , 'class=inputCommand');
$ams->setButtonAttributes('remove'    , 'class=inputCommand');
$ams->setButtonAttributes('all'       , 'class=inputCommand');
$ams->setButtonAttributes('none'      , 'class=inputCommand');
$ams->setButtonAttributes('toggle'    , 'class=inputCommand');
$ams->setButtonAttributes('moveup'    , 'class=inputCommand');
$ams->setButtonAttributes('movedown'  , 'class=inputCommand');
$ams->setButtonAttributes('movetop'   , 'class=inputCommand');
$ams->setButtonAttributes('movebottom', 'class=inputCommand');

$templateDual = '
<table{class}>
<!-- BEGIN label_2 --><tr><th>{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th>&nbsp;</th><th>{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td align="center">
    {add}<br />{remove}<br /><br />
    {all}<br />{none}<br />{toggle}<br /><br />
    {moveup}<br />{movedown}<br />{movetop}<br />{movebottom}
  </td>
  <td>{selected}</td>
</tr>
</table>
';

$ams->load($fruit_array, 'pear');

$ams->setPersistantOptions(array('pear', 'tangerine'));

$ams->setElementTemplate($templateDual);

$form->addElement($ams);

$buttons[] =& $form->createElement('submit', null, 'Submit');
$buttons[] =& $form->createElement('reset',  null, 'Reset');
$form->addGroup($buttons, null, '&nbsp;');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect persistant options example</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: #787878;
}
table.pool td {
  padding-left: 1em;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  color: #242424;
  background-color: #eee;
}

.inputCommand {
  width: 120px;
}
<?php echo $ams->getElementCss(); ?>
 -->
</style>
<?php echo $ams->getElementJs(false, true); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    var_dump($clean);

    // if apple fruit is selected, then pear may be remove from next selection
    if (in_array('apple', $clean['fruit'])) {
        $ams->setPersistantOptions('pear', false);
    } else {
        $ams->setPersistantOptions('pear', true);
        $selection = $ams->getSelected();
        if (!in_array('pear', $selection)) {
            array_push($selection, 'pear');
            $ams->setSelected($selection);
        }
    }
}
$form->display();
?>
</body>
</html>
Prev | Creating the form element | Next
HTML_QuickForm_advmultiselect::getPersistantOptions | PEAR Manual | Buttons


Buttons

Buttons

Table of Contents
  • HTML_QuickForm_advmultiselect::setButtonAttributes -- Sets the button attributes

Here, you can choose between standard form text or image button. You can also set the CSS class used to change the look and feel of buttons.

Prev | Reference guide | Next
HTML_QuickForm_advmultiselect::setPersistantOptions | PEAR Manual | HTML_QuickForm_advmultiselect::setButtonAttributes


HTML_QuickForm_advmultiselect::setButtonAttributes

HTML_QuickForm_advmultiselect::setButtonAttributes

HTML_QuickForm_advmultiselect::setButtonAttributes() – Sets the button attributes

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

void HTML_QuickForm_advmultiselect::setButtonAttributes ( string $button , mixed $attributes = NULL )

Description

The basic settings gave standard form input buttons. You may change the look with some CSS if you set the class attribute in the $attributes hash (second parameter). See example section.

Only five attributes may be set, they are:

name

The form input button name. Default are: 'add', or 'remove', or 'all', or 'none', or 'toggle', or 'up', or 'down', or 'top', or 'bottom'.

value

The form input button text. Default are ' >> ', or ' << ', or ' Select All ', or ' Select None ', or ' Toggle Selection ', or ' Up ', or ' Down ', or ' Top ', or ' Bottom '.

type

The form input button kind. Default is 'button' (Can be either 'button' or 'image').

class

A CSS class identifier in one of your stylesheets.

src

URL of the image file used.

Parameter

string $button

Button identifier, either 'add', 'remove', 'all', 'none', 'toggle', 'moveup' 'movedown' 'movetop' or 'movebottom'

mixed $attributes

(optional) Either a typical HTML attribute string or an associative array

Throws

Possible PEAR_Error values
Error message | Reason | Solution
Argument 1 of HTML_QuickForm_advmultiselect::setButtonAttributes is not a string | Tried to give a button identifier of unknown type | Check the $button argument data type
Argument 1 of HTML_QuickForm_advmultiselect::setButtonAttributes has unexpected value | Tried to give a button identifier of unknown value | Check the $button argument data range

Note

since version 0.4.0 (2005-06-25)

This function can not be called statically.

Example

In this example, the 'add' and 'remove' buttons have look set by the css class 'inputCommand'.

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('ams');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array);

$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                          'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                          'class' => 'inputCommand'
));
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td>{selected}</td>
</tr>
<tr>
  <td>{add}</td>
  <td>{remove}</td>
</tr>
</table>';
$ams->setElementTemplate($template);

if (isset($_POST['fruit'])) {
    $form->setDefaults(array('fruit' => $_POST['fruit']));
}

$form->addElement('submit', 'send', 'Send');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect example </title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid #7B7B88;
    width: 7em;
    margin-bottom: 2px;
}
// -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>

You may also use images rather than standard form input button. Replaces lines :

<?php
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                          'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                          'class' => 'inputCommand'
));
?>

by lines that should like :

<?php
$ams->setButtonAttributes('add',    array('type' => 'image',
                                          'src'  => '/img/add.png'
));
$ams->setButtonAttributes('remove', array('type' => 'image',
                                          'src'  => '/img/remove.png'
));
?>
Prev | Buttons | Next
Buttons | PEAR Manual | Basic renderer


Basic renderer

Basic renderer

Table of Contents
  • HTML_QuickForm_advmultiselect::toHtml -- Returns the HTML generated for the advanced mutliple select component

This renderer is based on HTML_QuickForm_advmultiselect code and require no external classes to do its job. It's very similar to HTML_Quickform default renderer .

Prev | Reference guide | Next
HTML_QuickForm_advmultiselect::setButtonAttributes | PEAR Manual | HTML_QuickForm_advmultiselect::toHtml


HTML_QuickForm_advmultiselect::toHtml

HTML_QuickForm_advmultiselect::toHtml

HTML_QuickForm_advmultiselect::toHtml() – Returns the HTML generated for the advanced mutliple select component

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

string HTML_QuickForm_advmultiselect::toHtml ( )

Description

Returns the advmultiselect element structure as HTML.

Throws

throws no exceptions thrown

Note

since version 0.4.0 (2005-06-25)

This function can not be called statically.

Prev | Basic renderer | Next
Basic renderer | PEAR Manual | Template-based renderer


Template-based renderer

Template-based renderer

Table of Contents
  • HTML_QuickForm_advmultiselect::getElementCss -- Gets default element stylesheet for a single multi-select shape render
  • HTML_QuickForm_advmultiselect::getElementJs -- Returns the javascript code generated to handle this element
  • HTML_QuickForm_advmultiselect::setElementTemplate -- Sets element template

Here is the core of customization of this QuickForm element. With the three methods below, you can easily include it in an existing template page with all parts (CSS, JS, lists, buttons) at the right place.

Prev | Reference guide | Next
HTML_QuickForm_advmultiselect::toHtml | PEAR Manual | HTML_QuickForm_advmultiselect::getElementCss


HTML_QuickForm_advmultiselect::getElementCss

HTML_QuickForm_advmultiselect::getElementCss

HTML_QuickForm_advmultiselect::getElementCss() – Gets default element stylesheet for a single multi-select shape render

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

string HTML_QuickForm_advmultiselect::getElementCss ( boolean $raw = TRUE )

Description

If your browser does not support javascript, or for any reasons you have choosen to disable it, then your only possibility is to use the single checkboxes multi-select shape of HTML_QuickForm_advmultiselect element.

You get a more or less decent result with just the basic settings, but it is also highly configurable, so you can almost get what you want.

The basic settings can be applied with just the placeholder {stylesheet} into your template element. It can also be applied with getElementCss() method. If you does not have existing style tags in your html page, you must call the method with FALSE argument. Default behavior returns only the raw css data without style tags. Useful when using with template engine.

Parameter

boolean $raw

(optional) html output with style tags or just raw data

Throws

throws no exceptions thrown

Note

since version 0.4.0 (2005-06-25)

This function can not be called statically.

Example

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('ams');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine'
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));

// template for a single checkboxes multi-select element shape
$template = '
<table{class}>
<!-- BEGIN label_3 --><tr><th>{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{selected}</td>
</tr>
</table>
';
$ams->setElementTemplate($template);

if ($_SERVER['REQUEST_METHOD'] == 'GET') {
    // fruit default values already selected without any end-user actions
    $form->setDefaults(array('fruit' => array('kiwi','lime')));

} elseif (isset($_POST['fruit'])) {
    // fruit end-user selection
    $form->setDefaults(array('fruit' => $_POST['fruit']));
}

$buttons[] =& $form->createElement('submit', null, 'Submit');
$buttons[] =& $form->createElement('reset', null, 'Reset');
$form->addGroup($buttons);
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 4b</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}
<?php echo $ams->getElementCss(); ?>
// -->
</style>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Template-based renderer | Next
Template-based renderer | PEAR Manual | HTML_QuickForm_advmultiselect::getElementJs


HTML_QuickForm_advmultiselect::getElementJs

HTML_QuickForm_advmultiselect::getElementJs

HTML_QuickForm_advmultiselect::getElementJs() – Returns the javascript code generated to handle this element

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

string HTML_QuickForm_advmultiselect::getElementJs ( boolean $raw = TRUE , boolean $min = FALSE )

Description

The basic (and default) settings can be applied with just the placeholder {javascript} into your template element. If you does not have existing script tags in your html page, you must call the method with FALSE argument. Default behaviour returns only the raw js data without script tags. Useful when using with template engine.

Parameter

boolean $raw

(optional) html output with script tags or just raw data

boolean $min

(optional) uses javascript compressed version

Throws

throws no exceptions thrown

Note

since version 0.4.0 (2005-06-25)

$min parameter is available since version 1.5.0

This function can not be called statically.

Prev | Template-based renderer | Next
HTML_QuickForm_advmultiselect::getElementCss | PEAR Manual | HTML_QuickForm_advmultiselect::setElementTemplate


HTML_QuickForm_advmultiselect::setElementTemplate

HTML_QuickForm_advmultiselect::setElementTemplate

HTML_QuickForm_advmultiselect::setElementTemplate() – Sets element template

Synopsis

require_once 'HTML/QuickForm/advmultiselect.php';

void HTML_QuickForm_advmultiselect::setElementTemplate ( string $html = NULL , boolean $js = TRUE )

Description

It is so easy to re-arrange select boxes, headers and buttons position. The template is a bit of html code with reserved placeholders words. They are:

stylesheet

The CSS delimited by the style tags required only for the single multi-select with checkboxes shape. Not included in the default template. You can use instead, the getElementCss() method.

javascript

The JavaScript delimited by the script tags required to manage item of both multi-select boxes. If it is not included, you can use instead, the getElementJs() method.

class

A CSS class identifier in one of your stylesheets that is the default table layout. Default values are:

<table border="0" cellpadding="10" cellspacing="0">

label_2

The unselected list header

label_3

The selected list header

unselected

The unselected list.

selected

The selected list.

add

The add button to swap one (or more) item from the unselected to the selected list.

remove

The remove button to swap one (or more) item back from the selected to the unselected list.

moveup

The button to move one item of the selected list to the top.

movedown

The button to move one item of the selected list to the bottom.

movetop

The button to move one item of the selected list directly at the top of the list

movebottom

The button to move one item of the selected list directly at the bottom of the list

Parameter

string $html

(optional) The HTML surrounding select boxes and buttons

boolean $js

(optional) if we need to include qfams javascript handler

Throws

throws no exceptions thrown

Note

since version 0.4.0 (2005-06-25)

This function can not be called statically.

Example

In this partial example, the fruit list select boxes are set to vertical alignement with images for the 'add' and 'remove' buttons. Default presentation are horizontal alignment with input text buttons in the middle side.

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('ams');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('type' => 'image', 'src' => '/img/down.png'));
$ams->setButtonAttributes('remove', array('type' => 'image', 'src' => '/img/up.png'));

// vertical select box with image buttons as selector
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th></tr><!-- END label_2 -->
<tr>
  <td>{unselected}</td>
</tr>
<tr>
  <td align="center">{add}{remove}</td>
</tr>
<tr>
  <td>{selected}</td>
</tr>
<!-- BEGIN label_3 --><tr><th align="center">{label_3}</th></tr><!-- END label_3 -->
</table>';
$ams->setElementTemplate($template);

// ....
?>
Prev | Template-based renderer | Next
HTML_QuickForm_advmultiselect::getElementJs | PEAR Manual | Examples appendix


Examples appendix

Examples appendix

Table of Contents
  • Basic usage
  • Extended usage
  • Advanced selection usage
  • Sort usage
  • Combines multiple elements
  • Template engine usage
  • Live counter combines with multiple elements
Prev | HTML_QuickForm_advmultiselect | Next
HTML_QuickForm_advmultiselect::setElementTemplate | PEAR Manual | Basic usage


Basic usage

Basic usage

Basic usage with default layout

qfams_basic_1.php script result

This example has no particular goals. It should be your first run to show and handle a advmultiselect element that will emulate a multi-select.

Without any customization

<?php
/**
 * Basic advMultiSelect HTML_QuickForm element
 * without any customization.
 *
 * @version    $Id: examples-basic1.xml,v 1.5 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_basic_1.php
 *             qfams_basic_1 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/basic1.png
 *             screenshot (Image PNG, 406x247 pixels) 4.95 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsBasic1');
$form->removeAttribute('name');        // XHTML compliance

// same as default element template but wihtout the label (in first td cell)
$withoutLabel = <<<_HTML
<tr valign="top">
    <td align="right">
        &nbsp;
    </td>
    <td align="left">
        <!-- BEGIN error --><span style="color: #ff0000;">{error}</span><br /><!-- END error -->{element}
    </td>
</tr>
_HTML;

// more XHTML compliant
// replace default element template with label, because submit button have no label
$renderer =& $form->defaultRenderer();
$renderer->setElementTemplate($withoutLabel, 'send');

$car_array = array(
    'dodge'     =>  'Dodge',
    'chevy'     =>  'Chevy',
    'bmw'       =>  'BMW',
    'audi'      =>  'Audi',
    'porsche'   =>  'Porsche',
    'kia'       =>  'Kia',
    'subaru'    =>  'Subaru',
    'mazda'     =>  'Mazda',
    'isuzu'     =>  'Isuzu',
);

// rendering with all default options
$form->addElement('header', null, 'Advanced Multiple Select: default layout ');

$form->addElement('advmultiselect', 'cars', 'Cars:', $car_array);

$form->addElement('submit', 'send', 'Send');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect basic example 1</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}
 -->
</style>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Examples appendix | Next
Examples appendix | PEAR Manual | Extended usage


Extended usage

Extended usage

Custom usage with a simple template

qfams_custom_1.php script result

In this example, here are our goals :

  • change the buttons (add, remove) position. Move at bottom of lists.

  • center headers at top of lists.

  • set list item visible to 5. Default is 10.

  • enlarge both list width to 300 pixels. Default width is only 100 pixels.

  • change background colors element.

Your first template element

<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * using stylesheet rules selectors and a template.
 *
 * The template allows to add label as headers of dual select box
 * and moves the button to another location (below each select box).
 *
 * @version    $Id: examples-custom1.xml,v 1.5 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_custom_1.php
 *             qfams_custom_1 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom1.png
 *             screenshot (Image PNG, 677x197 pixels) 4.80 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsCustom1');
$form->removeAttribute('name');        // XHTML compliance

// same as default element template but without the label (in first td cell)
$withoutLabel = <<<_HTML
<tr valign="top">
    <td align="right">
        &nbsp;
    </td>
    <td align="left">
        <!-- BEGIN error --><span style="color: #ff0000;">{error}</span><br /><!-- END error -->{element}
    </td>
</tr>
_HTML;

// more XHTML compliant
// replace default element template with label, because submit button have no label
$renderer =& $form->defaultRenderer();
$renderer->setElementTemplate($withoutLabel, 'send');

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('size' => 5,
                                 'class' => 'pool', 'style' => 'width:300px;'
                                )
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                           'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                           'class' => 'inputCommand'
));
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td>{selected}</td>
</tr>
<tr>
  <td align="center">{add}</td>
  <td align="center">{remove}</td>
</tr>
</table>';
$ams->setElementTemplate($template);

$form->addElement('submit', 'send', 'Send');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 1</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: lightyellow;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  background-color: lightblue;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid #7B7B88;
    width: 7em;
    margin-bottom: 2px;
}
 -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Examples appendix | Next
Basic usage | PEAR Manual | Advanced selection usage


Advanced selection usage

Advanced selection usage

Advanced selection

qfams_custom_7.php script result

In this example, here are our goals :

  • add buttons (all, none) to select / unselect all options in one stroke.

  • show two differents layout with checkboxes and dual selectboxes.

How to do a global selection

<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * with extended buttons (select all, select none, toggle selection)
 *
 * @version    $Id: examples-custom7.xml,v 1.5 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_custom_7.php
 *             qfams_custom_7 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom7.png
 *             screenshot (Image PNG, 640x525 pixels) 160 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsCustom7');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('class' => 'pool', 'style' => 'width:200px;')
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));

$ams->setButtonAttributes('add'     , 'class=inputCommand');
$ams->setButtonAttributes('remove'  , 'class=inputCommand');
$ams->setButtonAttributes('all'     , 'class=inputCommand');
$ams->setButtonAttributes('none'    , 'class=inputCommand');
$ams->setButtonAttributes('toggle'  , 'class=inputCommand');
$ams->setButtonAttributes('moveup'  , 'class=inputCommand');
$ams->setButtonAttributes('movedown', 'class=inputCommand');

// template for a single checkboxes multi-select element shape
$template1 = '
<table{class}>
<!-- BEGIN label_3 --><tr><th>{label_3}</th><th>&nbsp;</th></tr><!-- END label_3 -->
<tr>
  <td>{selected}</td>
  <td>{all}<br />{none}<br />{toggle}</td>
</tr>
</table>
';

// template for a dual multi-select element shape
$template2 = '
<table{class}>
<!-- BEGIN label_2 --><tr><th>{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th>&nbsp;</th><th>{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td align="center">
    {add}<br />{remove}<br /><br />{all}<br />{none}<br /><br />{moveup}<br />{movedown}<br />
  </td>
  <td>{selected}</td>
</tr>
</table>
';

if (isset($_POST['multiselect'])) {
    $ams->setElementTemplate($template2);
} else {
    $ams->setElementTemplate($template1);
}

if ($_SERVER['REQUEST_METHOD'] == 'GET') {
    // fruit default values already selected without any end-user actions
    $form->setDefaults(array('fruit' => array('kiwi','lime')));
}

$buttons[] =& $form->createElement('submit', null, 'Submit');
$buttons[] =& $form->createElement('reset',  null, 'Reset');
$buttons[] =& $form->createElement('checkbox', 'multiselect', null,
                                   'use dual select boxes layout');
$form->addGroup($buttons, null, '&nbsp;');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 7</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: cyan;
}
table.pool td {
  padding-left: 1em;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  color: gray;
  background-color: #eee;
}

.inputCommand {
  width: 120px;
}
<?php
if (!isset($_POST['multiselect'])) {
    echo $ams->getElementCss();
}
?>
 -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Examples appendix | Next
Extended usage | PEAR Manual | Sort usage


Sort usage

Sort usage

Auto-arrange feature usage

qfams_custom_5.php script result

In this example, here are our goals :

  • add the end-user sort buttons (up, down).

  • add the ability to sort lists in alphabetic order or reverse (by programming).

How to sort the select boxes

<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * that allows to manage sort of select boxes.
 *
 * @version    $Id: examples-custom5.xml,v 1.5 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_custom_5.php
 *             qfams_custom_5 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom5.png
 *             screenshot (Image PNG, 609x318 pixels) 9.94 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsCustom5');
$form->removeAttribute('name');        // XHTML compliance

// same as default element template but wihtout the label (in first td cell)
$withoutLabel = <<<_HTML
<tr valign="top">
    <td align="right">
        &nbsp;
    </td>
    <td align="left">
        <!-- BEGIN error --><span style="color: #ff0000;">{error}</span><br /><!-- END error -->{element}
    </td>
</tr>
_HTML;

// more XHTML compliant
// replace default element template with label, because submit button have no label
$renderer =& $form->defaultRenderer();
$renderer->setElementTemplate($withoutLabel, 'validate');

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// decides either both select list will have their elements be arranged or not
if (isset($_POST['autoArrange'])) {
    if ($_POST['autoArrange'] == 'A') {
        $sort = SORT_ASC;
    } elseif ($_POST['autoArrange'] == 'D') {
        $sort = SORT_DESC;
    } else {
        $sort = false;
    }
} else {
    $sort = false;
}

// rendering with QF renderer engine and template system
$form->addElement('header', null,
                  'For demo purpose only: must be validate to be active');
$arrange[] =& $form->createElement('radio', null, null, 'Auto arrange asc.',  'A');
$arrange[] =& $form->createElement('radio', null, null, 'Auto arrange desc.', 'D');
$arrange[] =& $form->createElement('radio', null, null, 'No auto arrange',    'N');
$form->addGroup($arrange, 'autoArrange', 'Sort list:');
$form->setDefaults(array('autoArrange' => 'N'));

$form->addElement('submit', 'validate', 'Validate');

$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('class' => 'pool', 'style' => 'width:200px;'),
                           $sort
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));

$ams->setButtonAttributes('add'     , 'class=inputCommand');
$ams->setButtonAttributes('remove'  , 'class=inputCommand');
$ams->setButtonAttributes('moveup'  , 'class=inputCommand');
$ams->setButtonAttributes('movedown', 'class=inputCommand');

// template for a dual multi-select element shape
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th>{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th>&nbsp;</th><th>{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td align="center">
    {add}<br />{remove}<br /><br />{moveup}<br />{movedown}<br />
  </td>
  <td>{selected}</td>
</tr>
</table>
';
$ams->setElementTemplate($template);

if ($_SERVER['REQUEST_METHOD'] == 'GET') {
    // fruit default values already selected without any end-user actions
    $form->setDefaults(array('fruit' => array('kiwi','lime')));
}

$buttons[] =& $form->createElement('submit', null, 'Submit');
$buttons[] =& $form->createElement('reset',  null, 'Reset');
$form->addGroup($buttons, null, '&nbsp;');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 5</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: #339900;
}
table.pool td {
  padding-left: 1em;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  color: white;
  background-color: #006600;
}

.inputCommand {
  width: 60px;
}
 -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Examples appendix | Next
Advanced selection usage | PEAR Manual | Combines multiple elements


Combines multiple elements

Combines multiple elements

Multiple usage with two different layouts

qfams_multiple_1.php script result

In this example, here are our goals :

  • use two advmultiselect elements on the same page.

  • use two different layouts.

Two different layouts on the same page

<?php
/**
 * Mixed advMultiSelect HTML_QuickForm elements.
 * Two widgets on the same page/form with one javascript code instance
 *
 * @version    $Id: examples-multiple1.xml,v 1.5 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_multiple_1.php
 *             qfams_multiple_1 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/multiple1.png
 *             screenshot (Image PNG, 566x392 pixels) 8.82 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsMultiple1');
$form->removeAttribute('name');        // XHTML compliance

// same as default element template but wihtout the label (in first td cell)
$withoutLabel = <<<_HTML
<tr valign="top">
    <td align="right">
        &nbsp;
    </td>
    <td align="left">
        <!-- BEGIN error --><span style="color: #ff0000;">{error}</span><br /><!-- END error -->{element}
    </td>
</tr>
_HTML;

// more XHTML compliant
// replace default element template with label, because submit button have no label
$renderer =& $form->defaultRenderer();
$renderer->setElementTemplate($withoutLabel, 'send');

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

$car_array = array(
    'dodge'     =>  'Dodge',
    'chevy'     =>  'Chevy',
    'bmw'       =>  'BMW',
    'audi'      =>  'Audi',
    'porsche'   =>  'Porsche',
    'kia'       =>  'Kia',
    'subaru'    =>  'Subaru',
    'mazda'     =>  'Mazda',
    'isuzu'     =>  'Isuzu',
);

// rendering with all default options
$form->addElement('header', null, 'Advanced Multiple Select: default layout ');

$ams1 =& $form->addElement('advmultiselect', 'cars', 'Cars:', $car_array);
$ams1->setElementTemplate(null, false);

// rendering with css selectors and API selLabel(), setButtonAttributes()
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams2 =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('size' => 5,
                                 'class' => 'pool', 'style' => 'width:200px;'
                                )
);

$ams2->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams2->setButtonAttributes('add',    array('value' => 'Add', 'name' => 'add1',
                                           'class' => 'inputCommand'
));
$ams2->setButtonAttributes('remove', array('value' => 'Remove', 'name' => 'remove1',
                                           'class' => 'inputCommand'
));
$ams2->setElementTemplate(null, false);

$form->addElement('submit', 'send', 'Send');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect multiple example 1</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: #339900;
  width:450px;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: left;
}
table.pool select {
  color: white;
  background-color: #006600;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid #7B7B88;
    width: 7em;
    margin-bottom: 2px;
}
 -->
</style>
<?php
echo $ams1->getElementJs(false, true);
?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>
Prev | Examples appendix | Next
Sort usage | PEAR Manual | Template engine usage


Template engine usage

Template engine usage

Template usage with Sigma engine

qfams_template_1.php script result

In this example, here are our goals :

  • use a template engine.

  • see how to include a advmultiselect element.

ITDynamic renderer with Sigma

<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * embedded into a Sigma template and using the QF dynamic renderer.
 *
 * @version    $Id: examples-template1.xml,v 1.4 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_template_1.php
 *             qfams_template_1 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/template1.png
 *             screenshot (Image PNG, 665x376 pixels) 23.3 Kb
 */

require_once 'HTML/Template/Sigma.php';
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsTemplate1');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with css selectors and API selLabel(), setButtonAttributes()
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$form->addElement('text', 'name', 'Name:', array('size' => 40, 'maxlength' => 80));

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('size' => 15,
                                 'class' => 'pool', 'style' => 'width:150px;'
                                )
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                           'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                           'class' => 'inputCommand'
));
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th>{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th>&nbsp;</th><th>{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td valign="top">{unselected}</td>
  <td align="center">{add}{remove}</td>
  <td valign="top">{selected}</td>
</tr>
</table>
';
$ams->setElementTemplate($template);

$form->addElement('submit', 'send', 'Send', array('class' => 'inputCommand'));

$form->addRule('name', 'Your name is required', 'required');
$form->addGroupRule('fruit', 'At least one fruit is required', 'required', null, 1);

$form->applyFilter('__ALL__', 'trim');
$form->applyFilter('__ALL__', 'strip_tags');

$valid = $form->validate();

$tpl = new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('itdynamic.html');
$tpl->setVariable('ams_javascript', $ams->getElementJs(false));

$renderer = new HTML_QuickForm_Renderer_ITDynamic($tpl);

$form->accept($renderer);

if ($valid) {
    $clean = $form->getSubmitValues();

    $msg = sprintf("<p>Welcome <b>%s</b> you've selected these fruits:<br />%s</p>",
           $clean['name'], implode(', ', $clean['fruit']));

    $tpl->setVariable('message_form_validate', $msg);
}
$tpl->show();
?>
Prev | Examples appendix | Next
Combines multiple elements | PEAR Manual | Live counter combines with multiple elements


Live counter combines with multiple elements

Live counter combines with multiple elements

Live counter on two advmultiselect elements

qfams_multiple_2.php script result

In this example, here are our goals :

  • use two advmultiselect elements on the same page.

  • show two differents layout with checkboxes and dual selectboxes.

  • show two differents display of live counters with single and dual select boxes.

Multiple live counters on same page

<?php
/**
 * Two advMultiSelect HTML_QuickForm elements with all properties
 * that can be display in one or two select box mode.
 * This example demonstrate the new feature of version 1.3.0 : Live Counter
 *
 * @version    $Id: examples-multiple2.xml,v 1.6 2009/02/11 08:51:16 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_multiple_2.php
 *             qfams_multiple_2 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/multiple2.png
 *             screenshot (Image PNG, 595x511 pixels) 11.9 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsMultiple2');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

$car_array = array(
    'dodge'     =>  'Dodge',
    'chevy'     =>  'Chevy',
    'bmw'       =>  'BMW',
    'audi'      =>  'Audi',
    'porsche'   =>  'Porsche',
    'kia'       =>  'Kia',
    'subaru'    =>  'Subaru',
    'mazda'     =>  'Mazda',
    'isuzu'     =>  'Isuzu',
);

// template for a single checkboxes multi-select element shape with live counter
$template1 = '
<table{class}>
<!-- BEGIN label_3 --><tr><th>{label_3}(<span id="{selected_count_id}">{selected_count}</span>)</th><th>&nbsp;</th></tr><!-- END label_3 -->
<tr>
  <td>{selected}</td>
  <td>{all}<br />{none}<br />{toggle}</td>
</tr>
</table>
';

// template for a dual multi-select element shape with live counter
$template2 = '
<table{class}>
<!-- BEGIN label_2 --><tr><th>{label_2}(<span id="{unselected_count_id}">{unselected_count}</span>)</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th>&nbsp;</th><th>{label_3}(<span id="{selected_count_id}">{selected_count}</span>)</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td align="center">
    {add}<br />{remove}<br /><br />{all}<br />{none}<br />{toggle}<br /><br />{moveup}<br />{movedown}<br />
  </td>
  <td>{selected}</td>
</tr>
</table>
';

$defaults = array();

// first QF ams element
$form->addElement('header', null, 'Advanced Multiple Select: Live Counter - pool1 style ');

$ams1 =& $form->addElement('advmultiselect', 'cars', null, $car_array,
    array('size' => 10, 'class' => 'pool1', 'style' => 'width:200px;')
);
$ams1->setLabel(array('Cars:', 'Available', 'Selected'));
$ams1->setButtonAttributes('add',      array('name' => 'add1',      'class' => 'inputCommand'));
$ams1->setButtonAttributes('remove',   array('name' => 'remove1',   'class' => 'inputCommand'));
$ams1->setButtonAttributes('all',      array('name' => 'all1',      'class' => 'inputCommand'));
$ams1->setButtonAttributes('none',     array('name' => 'none1',     'class' => 'inputCommand'));
$ams1->setButtonAttributes('toggle',   array('name' => 'toggle1',   'class' => 'inputCommand'));
$ams1->setButtonAttributes('moveup',   array('name' => 'moveup1',   'class' => 'inputCommand'));
$ams1->setButtonAttributes('movedown', array('name' => 'movedown1', 'class' => 'inputCommand'));

if (isset($_POST['multiselect1'])) {
    $ams1->setElementTemplate($template2);
} else {
    $ams1->setElementTemplate($template1);
}

// second QF ams element
$form->addElement('header', null, 'Advanced Multiple Select: Live Counter - pool2 style ');

$ams2 =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
    array('size' => 5, 'class' => 'pool2', 'style' => 'width:300px;')
);
$ams2->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams2->setButtonAttributes('add',      array('name' => 'add2',      'class' => 'inputCommand'));
$ams2->setButtonAttributes('remove',   array('name' => 'remove2',   'class' => 'inputCommand'));
$ams2->setButtonAttributes('all',      array('name' => 'all2',      'class' => 'inputCommand'));
$ams2->setButtonAttributes('none',     array('name' => 'none2',     'class' => 'inputCommand'));
$ams2->setButtonAttributes('toggle',   array('name' => 'toggle2',   'class' => 'inputCommand'));
$ams2->setButtonAttributes('moveup',   array('name' => 'moveup2',   'class' => 'inputCommand'));
$ams2->setButtonAttributes('movedown', array('name' => 'movedown2', 'class' => 'inputCommand'));

if (isset($_POST['multiselect2'])) {
    $ams2->setElementTemplate($template2);
} else {
    $ams2->setElementTemplate($template1);
}

$buttons[] =& $form->createElement('submit', null, 'Submit');
$buttons[] =& $form->createElement('reset',  null, 'Reset');
$buttons[] =& $form->createElement('checkbox', 'multiselect1', null,
                                   'cars list dual select');
$buttons[] =& $form->createElement('checkbox', 'multiselect2', null,
                                   'fruit list dual select');
$form->addGroup($buttons, null, '&nbsp;');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect multiple example 2</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool1, table.pool2 {
  border: 0;
  background-color: #339900;
  width:450px;
}
table.pool2 {
  background-color: #CFC;
}
table.pool1 th, table.pool2 th {
  font-size: 80%;
  font-style: italic;
  text-align: left;
}
table.pool1 td, table.pool2 td {
  vertical-align: top;
}
table.pool1 select, table.pool2 select {
  color: white;
  background-color: #006600;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid white;
    width: 9em;
    margin-bottom: 2px;
}
<?php
if (!isset($_POST['multiselect1'])) {
    echo $ams1->getElementCss();
}
if (!isset($_POST['multiselect2'])) {
    echo $ams2->getElementCss();
}
?>
 -->
</style>
<?php echo $ams1->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
<script type="text/javascript">
//
function init() {
    QFAMS.init(['cars','fruit']);
}
window.addEventListener('load', init, false);
//
</script>
</body>
</html>
Prev | Examples appendix | Next
Template engine usage | PEAR Manual | HTML_Table


HTML_Table

HTML_Table

API to create HTML tables

Table of Contents
  • Introduction -- Creating an HTML-Table
  • FAQ -- Answers to most Frequently Asked Questions
  • Constructor HTML_Table::HTML_Table() -- Constructor
  • HTML_Table::addBody() -- Add body
  • HTML_Table::addCol() -- Add column
  • HTML_Table::addRow() -- Add row
  • HTML_Table::altRowAttributes() -- Alternate row attributes
  • HTML_Table::apiVersion() -- Return API version (DEPRECATED)
  • HTML_Table::display() -- Output HTML code
  • HTML_Table::getAutoFill() -- Return autoFill value
  • HTML_Table::getAutoGrow() -- Return autoGrow flag
  • HTML_Table::getBody() -- Return the table object for the tbody group
  • HTML_Table::getCellAttributes() -- Return cell attributes
  • HTML_Table::getCellContents() -- Return cell content
  • HTML_Table::getColCount() -- Return numbers of column
  • HTML_Table::getFooter() -- Return the table object for the tfoot group
  • HTML_Table::getHeader() -- Return the table object for the thead group
  • HTML_Table::getRowAttributes() -- Return row attributes
  • HTML_Table::getRowCount() -- Return number of rows
  • HTML_Table::setAllAttributes() -- Set attributes for all cells
  • HTML_Table::setAutoGrow() -- Set autoGrow flag
  • HTML_Table::setAutoFill() -- Set autoFill value
  • HTML_Table::setCaption() -- Set table caption
  • HTML_Table::setCellAttributes() -- Set cell attributes
  • HTML_Table::setCellContents() -- Set cell content
  • HTML_Table::setColAttributes() -- Set column attributes
  • HTML_Table::setColCount() -- Set number of columns
  • HTML_Table::setColGroup() -- Set a colgroup
  • HTML_Table::setColType() -- Set column type
  • HTML_Table::setHeaderContents() -- Set content of header cell
  • HTML_Table::setRowCount() -- Set row number
  • HTML_Table::setRowType() -- Set row type
  • HTML_Table::setRowAttributes() -- Set row attributes
  • HTML_Table::toHtml() -- Return HTML code
  • HTML_Table::updateAllAttributes() -- Update attributes of all cells
  • HTML_Table::updateCellAttributes() -- Update cell attributes
  • HTML_Table::updateColAttributes() -- Update column attributes
  • HTML_Table::updateRowAttributes() -- Update row attributes
Prev | HTML | Next
Live counter combines with multiple elements | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Creating an HTML-Table

What is HTML_Table?

HTML_Table offers an interface for create a HTML table. You can work with the table like a spreadsheet. Instead of working with HTML code and linear adding of cells, you can address and fill cells independend of there position. There is no different, whether you start with fill a cell at the beginning, in the middle or at the end of the table, a row or a column.

The autoGrow and autoFill value

The autoGrow flag

Normaly, you would define a table with a constant number of rows and columns. But sometimes, you does not know, how many rows or columns you need: ie. transforming user input or the result of a database query to an HTML table.

In this case, you should enable the autoGrow feature. In this mode, HTML_Table adds new rows or columns automatically, if you use a cell address located in a not existing row or column.

The autoFill value

If you create a table of data, sometimes you have not to fill all cells with different values. Perhaps you do not know the value for a cell, or you want to insert a default value - ie. retrieving data about users. Not every user has a mobile, a email address etc., in this case, an "n/a" should be inserted into that specific cell.

So, simply define "n/a" as autoFill value and fill only the cells where data exist. You need not to fill every cell; unfilled cells contain automatically an "n/a" .

Creating a table

The demonstation data

Our HTML table to create should contain the following data:

<?php
$data = array(
 '0' => array('Bakken', 'Stig', '', 'stig@example.com'),
 '1' => array('Merz', 'Alexander', 'alex.example.com', 'alex@example.com'),
 '2' => array('Daniel', 'Adam', '', '')
);
?>

Start

Let us now start by creating a new instance of HTML_Table. The table should be 600 pixel wide. We do not know the quantity of the data to insert into the table - so we enable the autoGrow feature. Unfilled cells should contain an "n/a" .

<?php
require_once 'HTML/Table.php';

$attrs = array('width' => '600');
$table = new HTML_Table($attrs);
$table->setAutoGrow(true);
$table->setAutoFill('n/a');
?>

Setting table attributes is also possible by using the setAttributes() method. Therefore, the example from above can also be written as:

<?php
require_once 'HTML/Table.php';

$attrs = array('width' => '600');
$table = new HTML_Table();
$table->setAttributes($attrs);
// [...]
?>

Add data rows

Now process every data entry. Here we use also the alternate feature of HTML_Table. Every second row will be colored red.

<?php
for ($nr = 0; $nr < count($data); $nr++) {
  $table->setHeaderContents($nr+1, 0, (string)$nr);
  for ($i = 0; $i < 4; $i++) {
    if ('' != $data[$nr][$i]) {
      $table->setCellContents($nr+1, $i+1, $data[$nr][$i]);
    }
  }
}
$altRow = array('bgcolor' => 'red');
$table->altRowAttributes(1, null, $altRow);
?>

Add header cells

Now we want to define the cells in the first row and column as header cells. It should looks like a spreadsheet application, so we want to use the color "silver" as the background colour for each header cell. The first row contains a column headline, the first column the number of the data set row.

<?php
$table->setHeaderContents(0, 0, '');
$table->setHeaderContents(0, 1, 'Surname');
$table->setHeaderContents(0, 2, 'Name');
$table->setHeaderContents(0, 3, 'Website');
$table->setHeaderContents(0, 4, 'EMail');
$hrAttrs = array('bgcolor' => 'silver');
$table->setRowAttributes(0, $hrAttrs, true);
$table->setColAttributes(0, $hrAttrs);
?>

Print the table

It is done! Our table is finished, now we can output the table as HTML code.

<?php
echo $table->toHtml();
?>

The output will look like this:

<table width="600">
<tr>
<th bgcolor="silver">&nbsp;</th>
<th bgcolor="silver">Surname</th>
<th bgcolor="silver">Name</th>
<th bgcolor="silver">Website</th>
<th bgcolor="silver">EMail</th>
</tr>
<tr>
<th bgcolor="silver">0</th>
<td>Bakken</td>
<td>Stig</td>
<td>n/a</td>
<td>stig@example.com</td>
</tr>
<tr>
<th bgcolor="silver">1</th>
<td bgcolor="red">Merz</td>
<td bgcolor="red">Alexander</td>
<td bgcolor="red">alex.example.com</td>
<td bgcolor="red">alex@example.com</td>
</tr>
<tr>
<th bgcolor="silver">2</th>
<td>Daniel</td>
<td>Adam</td>
<td>n/a</td>
<td>n/a</td>
</tr>
</table>

Using thead, tfoot and tbody

If you want to divide your tables into thead, tfoot and tbody groups, you need to get table objects using getHeader(), getFooter(), and getBody(), which you can then use like the normal table object.

<?php
$table = new HTML_Table();
$head =& $table->getHeader();
$foot =& $table->getFooter();
$body =& $table->getBody();
$head->setCellContents(...);
$body->setCellContents(...);
echo $table->toHtml();
?>

In this example, there is no content set for the tfoot group. Therefore, only thead and tbody will be rendered.

Note: The rendering order is thead, then tfoot and as the last group tbody. This is not a bug but intended behaviour because that's the way it is defined in the (X)HTML Standard.

Since release 1.8.0 getBody() and several other methods like setCellAttributes() accept an optional numeric parameter $body that allows you to generate multiple tbody groups in your table. A new group can be generated by using addBody() or, if the autoGrow feature is enabled, by using a new number in one of the mentioned method calls.

Prev | HTML_Table | Next
HTML_Table | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

Description

This document is based on questions asked on PEAR general mailing list and other mailing lists and forums.

HTML_Table FAQ

  1. How can I add attributes to the thead, tfoot or tbody tags?
  2. How can I set attributes for the table tag?
  3. How can I easily add JavaScript sorting facilities to my tables?
How can I add attributes to the thead, tfoot or tbody tags?

Here is an example on how to set the attribute string id="header" for the thead tag. For the other two tags the procedure is similar.

<?php
$table = new HTML_Table();
// [...]
$thead =& $table->getHeader();
$thead->setAttributes(array('id' => 'header'));
// [...]
$table->display();
?>

This would give the following result:

<table>
  <thead id="header">
    [...]
  </thead>
  [...]
</table>
How can I set attributes for the table tag?

Besides the possibility to pass attributes to the HTML_Table constructor, there are several more methods that can be used.

HTML_Table extends HTML_Common which offers methods like setAttributes() or updateAttributes(). A complete list of methods provided by HTML_Common can be found in its API documentation.

How can I easily add JavaScript sorting facilities to my tables?

Stuart Langridge has developed the SortTable JavaScript class that allows adding of sorting facilities to tables very easily. Another class for this purpose is Standardista Table Sorting.

Prev | HTML_Table | Next
Introduction | PEAR Manual | Constructor HTML_Table::HTML_Table()


Constructor HTML_Table::HTML_Table()

Constructor HTML_Table::HTML_Table()

Constructor HTML_Table::HTML_Table() – Constructor

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::HTML_Table ( array $attributes = null , integer $tabOffset=0 , boolean $useTGroups = false )

Description

Class constructor

Parameter

  • array $attributes - Associative array of table tag attributes

  • integer $tabOffset - Tab offset of the table

  • boolean $useTGroups - Whether to use the thead, tfoot and tbody groups or not

Note

This function can not be called statically.

See

HTML_Table::getBody()

HTML_Table::getFooter()

HTML_Table::getHeader()

Prev | HTML_Table | Next
FAQ | PEAR Manual | HTML_Table::addBody()


HTML_Table::addBody()

HTML_Table::addBody()

HTML_Table::addBody() – Add body

Synopsis

require_once 'HTML/Table.php';

int HTML_Table::addBody ( array $attributes = null )

Description

Adds a new body to the table and returns the body identifier

Parameter

  • array $attributes - Associative array of tbody tag attributes

Return value

int - the body identifier

Note

This function can not be called statically.

See

HTML_Table::getBody()

Prev | HTML_Table | Next
Constructor HTML_Table::HTML_Table() | PEAR Manual | HTML_Table::addCol()


HTML_Table::addCol()

HTML_Table::addCol()

HTML_Table::addCol() – Add column

Synopsis

require_once 'HTML/Table.php';

int HTML_Table::addCol ( array $contents = null , mixed $attributes = null , string $type='TD' , int $body=0 )

Description

Adds a table column and returns the column identifier

Parameter

  • array $contents - Must be an indexed array of valid cell contents.

  • mixed $attributes - Associative array or string of table row attributes

  • string $type - Cell type either 'th' or 'td'

  • int $body - The number of the tbody group that should be used

Return value

int - the identifier for the column

Note

This function can not be called statically.

See

HTML_Table::addRow()

Prev | HTML_Table | Next
HTML_Table::addBody() | PEAR Manual | HTML_Table::addRow()


HTML_Table::addRow()

HTML_Table::addRow()

HTML_Table::addRow() – Add row

Synopsis

require_once 'HTML/Table.php';

int HTML_Table::addRow ( array $contents = null , mixed $attributes = null , string $type='TD' , boolean $inTR = false , int $body=0 )

Description

Adds a table row and returns the row identifier

Parameter

  • array $contents - Must be an indexed array of valid cell contents

  • mixed $attributes - Associative array or string of table row attributes. This can also be an array of attributes, in which case the attributes will be repeated in a loop.

  • string $type - Cell type either 'th' or 'td'

  • boolean $inTR - FALSE, if attributes are to be applied in TD tags; TRUE, if attributes are to be applied in TR tag

  • int $body - The number of the tbody group that should be used

Return value

int - the row identifier

Note

This function can not be called statically.

See

HTML_Table::addCol()

Prev | HTML_Table | Next
HTML_Table::addCol() | PEAR Manual | HTML_Table::altRowAttributes()


HTML_Table::altRowAttributes()

HTML_Table::altRowAttributes()

HTML_Table::altRowAttributes() – Alternate row attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::altRowAttributes ( int $start , mixed $attributes1 , mixed $attributes2 , boolean $inTR = false , int $body = null )

Description

Alternates the row attributes starting at $start

Parameter

  • int $start - Row index of row in which alternating begins

  • mixed $attributes1 - Associative array or string of table row attributes

  • mixed $attributes2 - Associative array or string of table row attributes

  • boolean $inTR - FALSE, if attributes are to be applied in td tags; TRUE, if attributes are to be applied in tr tag.

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::setAllAttributes(),
HTML_Table::updateAllAttributes(),
HTML_Table::setColAttributes(),
HTML_Table::updateColAttributes(),
HTML_Table::setCellAttributes(),
HTML_Table::updateCellAttributes(),
HTML_Table::updateRowAttributes(),
HTML_Table::setRowAttributes()

Prev | HTML_Table | Next
HTML_Table::addRow() | PEAR Manual | HTML_Table::apiVersion()


HTML_Table::apiVersion()

HTML_Table::apiVersion()

HTML_Table::apiVersion() – Return API version (DEPRECATED)

Synopsis

require_once 'HTML/Table.php';

double HTML_Table::apiVersion ( )

Description

DEPRECATED: Returns the API version of HTML_Table

Return value

double - the version number

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Prev | HTML_Table | Next
HTML_Table::altRowAttributes() | PEAR Manual | HTML_Table::display()


HTML_Table::display()

HTML_Table::display()

HTML_Table::display() – Output HTML code

Synopsis

require_once 'HTML/Table.php';

string HTML_Table::display ( )

Description

Outputs the table structure as HTML

Note

This function can not be called statically.

See

HTML_Table::toHtml()

Prev | HTML_Table | Next
HTML_Table::apiVersion() | PEAR Manual | HTML_Table::getAutoFill()


HTML_Table::getAutoFill()

HTML_Table::getAutoFill()

HTML_Table::getAutoFill() – Return autoFill value

Synopsis

require_once 'HTML/Table.php';

mixed HTML_Table::getAutoFill ( int $body=0 )

Description

Returns the autoFill value

Parameter

  • int $body - The number of the tbody group that should be used

Return value

mixed - the value, which will be inserted into empty cells

Note

This function can not be called statically.

See

HTML_Table::setAutoFill()

Prev | HTML_Table | Next
HTML_Table::display() | PEAR Manual | HTML_Table::getAutoGrow()


HTML_Table::getAutoGrow()

HTML_Table::getAutoGrow()

HTML_Table::getAutoGrow() – Return autoGrow flag

Synopsis

require_once 'HTML/Table.php';

boolean HTML_Table::getAutoGrow ( int $body=0 )

Description

Returns the value of the autoGrow flag. If a value into an cell, which not exists, HTML_Table will automatically add a necessary row or column, if the flag is TRUE.

Parameter

  • int $body - The number of the tbody group that should be used

Return value

boolean - the flag state

Note

This function can not be called statically.

See

HTML_Table::setAutoGrow()

Prev | HTML_Table | Next
HTML_Table::getAutoFill() | PEAR Manual | HTML_Table::getBody()


HTML_Table::getBody()

HTML_Table::getBody()

HTML_Table::getBody() – Return the table object for the tbody group

Synopsis

require_once 'HTML/Table.php';

mixed HTML_Table::getBody ( int $body=0 )

Description

Returns the table object for a tbody group

Parameter

  • int $body - The number of the tbody group that should be used

Return value

object - the table object for a tbody group

Note

This function can not be called statically.

See

HTML_Table::HTML_Table()

Prev | HTML_Table | Next
HTML_Table::getAutoGrow() | PEAR Manual | HTML_Table::getCellAttributes()


HTML_Table::getCellAttributes()

HTML_Table::getCellAttributes()

HTML_Table::getCellAttributes() – Return cell attributes

Synopsis

require_once 'HTML/Table.php';

array HTML_Table::getCellAttributes ( int $row , int $col , int $body=0 )

Description

Returns the attributes for a given cell

Parameter

  • int $row - Row index

  • int $col - Column index

  • int $body - The number of the tbody group that should be used

Return value

array - the attributes of the specific cell

Note

This function can not be called statically.

See

HTML_Table::getRowAttributes()

Prev | HTML_Table | Next
HTML_Table::getBody() | PEAR Manual | HTML_Table::getCellContents()


HTML_Table::getCellContents()

HTML_Table::getCellContents()

HTML_Table::getCellContents() – Return cell content

Synopsis

require_once 'HTML/Table.php';

mixed HTML_Table::getCellContents ( int $row , int $col , int $body=0 )

Description

Returns the content of an existing cell

Parameter

  • int $row - Row index

  • int $col - Column index

  • int $body - The number of the tbody group that should be used

Return value

mixed - the content of the specified cell

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::getCellAttributes() | PEAR Manual | HTML_Table::getColCount()


HTML_Table::getColCount()

HTML_Table::getColCount()

HTML_Table::getColCount() – Return numbers of column

Synopsis

require_once 'HTML/Table.php';

int HTML_Table::getColCount ( int $row=null , int $body=0 )

Description

Returns the number of columns in the table

Parameter

  • int $row - The row number to serve for cols count

  • int $body - The number of the tbody group that should be used

Return value

int - number of columns

Note

This function can not be called statically.

See

HTML_Table::getRowCount()

Prev | HTML_Table | Next
HTML_Table::getCellContents() | PEAR Manual | HTML_Table::getFooter()


HTML_Table::getFooter()

HTML_Table::getFooter()

HTML_Table::getFooter() – Return the table object for the tfoot group

Synopsis

require_once 'HTML/Table.php';

mixed HTML_Table::getFooter ( )

Description

Returns the table object for the tfoot group

If the usage of the thead, tfoot and tbody groups was not activated via the third parameter of the constructor, the grouping will be activated automatically when calling this function.

Return value

object - the table object for the tfoot group

Note

This function can not be called statically.

See

HTML_Table::HTML_Table()

Prev | HTML_Table | Next
HTML_Table::getColCount() | PEAR Manual | HTML_Table::getHeader()


HTML_Table::getHeader()

HTML_Table::getHeader()

HTML_Table::getHeader() – Return the table object for the thead group

Synopsis

require_once 'HTML/Table.php';

mixed HTML_Table::getHeader ( )

Description

Returns the table object for the thead group

If the usage of the thead, tfoot and tbody groups was not activated via the third parameter of the constructor, the grouping will be activated automatically when calling this function.

Return value

object - the table object for the thead group

Note

This function can not be called statically.

See

HTML_Table::HTML_Table()

Prev | HTML_Table | Next
HTML_Table::getFooter() | PEAR Manual | HTML_Table::getRowAttributes()


HTML_Table::getRowAttributes()

HTML_Table::getRowAttributes()

HTML_Table::getRowAttributes() – Return row attributes

Synopsis

require_once 'HTML/Table.php';

array HTML_Table::getRowAttributes ( int $row , int $body=0 )

Description

Returns the attributes for a given row as contained in the tr tag

Parameter

  • int $row - Row index

  • int $body - The number of the tbody group that should be used

Return value

array - the attributes of the row

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::getHeader() | PEAR Manual | HTML_Table::getRowCount()


HTML_Table::getRowCount()

HTML_Table::getRowCount()

HTML_Table::getRowCount() – Return number of rows

Synopsis

require_once 'HTML/Table.php';

int HTML_Table::getRowCount ( int $body=0 )

Description

Returns the number of rows in the table

Parameter

  • int $body - The number of the tbody group that should be used

Return value

int - number of rows

Note

This function can not be called statically.

See

HTML_Table::getColCount()

Prev | HTML_Table | Next
HTML_Table::getRowAttributes() | PEAR Manual | HTML_Table::setAllAttributes()


HTML_Table::setAllAttributes()

HTML_Table::setAllAttributes()

HTML_Table::setAllAttributes() – Set attributes for all cells

Synopsis

require_once 'HTML_Table.php';

void HTML_Table::setAllAttributes ( mixed $attributes = null , int $body = null )

Description

Sets the attributes for all cells

Parameter

  • mixed $attributes - Associative array or string of table cell attributes

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::updateAllAttributes(),
HTML_Table::setColAttributes(),
HTML_Table::setCellAttributes(),
HTML_Table::setRowAttributes()

Prev | HTML_Table | Next
HTML_Table::getRowCount() | PEAR Manual | HTML_Table::setAutoGrow()


HTML_Table::setAutoGrow()

HTML_Table::setAutoGrow()

HTML_Table::setAutoGrow() – Set autoGrow flag

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setAutoGrow ( bool $grow , int $body = null )

Description

If this flag is set to TRUE, HTML_Table will automatically add new rows or columns when you insert a value into a non-existing cell.

Parameter

  • bool $grow - TRUE to automatically grow

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::getAutoGrow()

Prev | HTML_Table | Next
HTML_Table::setAllAttributes() | PEAR Manual | HTML_Table::setAutoFill()


HTML_Table::setAutoFill()

HTML_Table::setAutoFill()

HTML_Table::setAutoFill() – Set autoFill value

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setAutoFill ( mixed $fill , int $body = null )

Description

The autoFill value will be insert into every cell not filled.

Parameter

  • mixed $fill - standard value for empty cells

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::getAutoFill()

Prev | HTML_Table | Next
HTML_Table::setAutoGrow() | PEAR Manual | HTML_Table::setCaption()


HTML_Table::setCaption()

HTML_Table::setCaption()

HTML_Table::setCaption() – Set table caption

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setCaption ( string $caption , mixed $attributes = null )

Description

Sets the caption of a table. This does not refer to the <th> -tag. The <caption> -tag defines a headline for the whole table.

Parameter

  • string $caption - the caption string

  • mixed $attributes - Associative array or string of caption attributes

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::setAutoFill() | PEAR Manual | HTML_Table::setCellAttributes()


HTML_Table::setCellAttributes()

HTML_Table::setCellAttributes()

HTML_Table::setCellAttributes() – Set cell attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setCellAttributes ( int $row , int $col , mixed $attributes , int $body=0 )

Description

Sets the cell attributes for an existing cell. If the given indices do not exist and autoGrow is TRUE then the given row and/or column is automatically added. If autoGrow is FALSE, an error is returned.

Parameter

  • int $row - Row index

  • int $col - Column index

  • mixed $attributes - Associative array or string of table cell attributes

  • int $body - The number of the tbody group that should be used

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
 | " Invalid table row reference [$row ] " | The row $row does not exists | Enable the autoGrow feature
 | " Invalid table column reference [$column ] " | The column $column does not exists | Enable the autoGrow feature

Note

This function can not be called statically.

See

HTML_Table::setAutoGrow()

Prev | HTML_Table | Next
HTML_Table::setCaption() | PEAR Manual | HTML_Table::setCellContents()


HTML_Table::setCellContents()

HTML_Table::setCellContents()

HTML_Table::setCellContents() – Set cell content

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setCellContents ( int $row , int $col , mixed $contents , string $type='TD' , int $body=0 )

Description

Sets the cell contents for an existing cell. If the given indices do not exist and autoGrow is TRUE then the given row and/or column is automatically added. If autoGrow is FALSE, then an error is returned.

Parameter

  • int $row - Row index

  • int $col - Column index

  • mixed $contents - May contain HTML or any object with a toHTML() method

  • string $type - Cell type either 'th' or 'td'

  • int $body - The number of the tbody group that should be used

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
 | " Invalid table row reference [$row ] " | The row $row does not exists | Enable the autoGrow feature
 | " Invalid table column reference [$column ] " | The column $column does not exists | Enable the autoGrow feature

Note

This function can not be called statically.

See

HTML_Table::setAutoGrow()

Prev | HTML_Table | Next
HTML_Table::setCellAttributes() | PEAR Manual | HTML_Table::setColAttributes()


HTML_Table::setColAttributes()

HTML_Table::setColAttributes()

HTML_Table::setColAttributes() – Set column attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setColAttributes ( int $col , mixed $attributes = null , int $body = null )

Description

Sets the column attributes for an existing column

Parameter

  • int $col - Column index

  • mixed $attributes - Associative array or string of table column attributes

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

See

HTML_Table::setRowAttributes()

Prev | HTML_Table | Next
HTML_Table::setCellContents() | PEAR Manual | HTML_Table::setColCount()


HTML_Table::setColCount()

HTML_Table::setColCount()

HTML_Table::setColCount() – Set number of columns

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setColCount ( int $cols , int $body=0 )

Description

Sets the number of columns in the table

Parameter

  • int $cols - number of columns to create

  • int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setRowCount()

Prev | HTML_Table | Next
HTML_Table::setColAttributes() | PEAR Manual | HTML_Table::setColGroup()


HTML_Table::setColGroup()

HTML_Table::setColGroup()

HTML_Table::setColGroup() – Set a colgroup

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setColGroup ( mixed $colgroup = null , mixed $attributes = null )

Description

Allows to add a colgroup (with attributes)

Parameter

  • mixed $colgroup - Empty string, string with attributes or an associative array of attributes for the columns

  • mixed $attributes - Associative array or string of colgroup attributes

Example

Usage without a col tag

<?php
require_once 'HTML/Table.php';

$table =& new HTML_Table();

$colgroup = '';
$attributes = 'span="3" class="group1"';
$table->setColGroup($colgroup, $attributes);
?>

Usage with col tags

<?php
require_once 'HTML/Table.php';

$table =& new HTML_Table();

$colgroup = array('style="font-size: 120%;"', 'class="col2"', 'align="right"');
$attributes = 'span="3" class="group1"';
$table->setColGroup($colgroup, $attributes);
?>

Usage with multiple colgroups

<?php
require_once 'HTML/Table.php';

$colgroup = array('style="font-size:120%;"', 'class="col2"', 'align="right"');
$attributes = 'span="3" class="group1"';
$table->setColGroup($colgroup, $attributes);

$colgroup = array(array('class' => 'col4'), array('class' => 'col5'));
$attributes = 'span="2" class="group2"';
$table->setColGroup($colgroup, $attributes);
?>

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::setColCount() | PEAR Manual | HTML_Table::setColType()


HTML_Table::setColType()

HTML_Table::setColType()

HTML_Table::setColType() – Set column type

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setColType ( int $col , string $type , int $body = null )

Description

Sets the type of a column to 'th' or 'td'

Parameter

  • int $col - Column index

  • string $type - th or td

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::setColGroup() | PEAR Manual | HTML_Table::setHeaderContents()


HTML_Table::setHeaderContents()

HTML_Table::setHeaderContents()

HTML_Table::setHeaderContents() – Set content of header cell

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setHeaderContents ( int $row , int $col , mixed $contents , int $body=0 )

Description

Defines the specified cell as a header cell and sets the content

Parameter

  • int $row - row index

  • int $col - column index

  • mixed $contents - cell content

  • int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setCellContent()

Prev | HTML_Table | Next
HTML_Table::setColType() | PEAR Manual | HTML_Table::setRowCount()


HTML_Table::setRowCount()

HTML_Table::setRowCount()

HTML_Table::setRowCount() – Set row number

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setRowCount ( int $rows , int $body=0 )

Description

Sets the number of rows in the table

Parameter

  • int $rows - number of rows to create

  • int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setColCount()

Prev | HTML_Table | Next
HTML_Table::setHeaderContents() | PEAR Manual | HTML_Table::setRowType()


HTML_Table::setRowType()

HTML_Table::setRowType()

HTML_Table::setRowType() – Set row type

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setRowType ( int $row , string $type , int $body=0 )

Description

Sets the type of a row to 'th' or 'td'

Parameter

  • int $row - Row index

  • string $type - 'th' or 'td'

  • int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

See

HTML_Table::setColType()

Prev | HTML_Table | Next
HTML_Table::setRowCount() | PEAR Manual | HTML_Table::setRowAttributes()


HTML_Table::setRowAttributes()

HTML_Table::setRowAttributes()

HTML_Table::setRowAttributes() – Set row attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::setRowAttributes ( int $row , mixed $attributes , boolean $inTR = false , int $body=0 )

Description

Sets the attributes for an existing row

Parameter

  • int $row - Row index

  • mixed $attributes - Associative array or string of table row attributes. This can also be an array of attributes, in which case the attributes will be repeated in a loop.

  • boolean $inTR - FALSE, if attributes are to be applied in td tags; TRUE, if attributes are to be applied in tr tag

  • int $body - The number of the tbody group that should be used

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
 | " Invalid table row reference [$row ] " | The row $row does not exists | Enable the autoGrow feature
 | " Invalid table column reference [$column ] " | The column $column does not exists | Enable the autoGrow feature

Note

This function can not be called statically.

See

HTML_Table::setColAttributes()

Prev | HTML_Table | Next
HTML_Table::setRowType() | PEAR Manual | HTML_Table::toHtml()


HTML_Table::toHtml()

HTML_Table::toHtml()

HTML_Table::toHtml() – Return HTML code

Synopsis

require_once 'HTML/Table.php';

string HTML_Table::toHtml ( )

Description

Returns the table structure as HTML

Return value

string - the generated HTML code

Note

This function can not be called statically.

See

HTML_Table::display()

Prev | HTML_Table | Next
HTML_Table::setRowAttributes() | PEAR Manual | HTML_Table::updateAllAttributes()


HTML_Table::updateAllAttributes()

HTML_Table::updateAllAttributes()

HTML_Table::updateAllAttributes() – Update attributes of all cells

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::updateAllAttributes ( mixed $attributes = null , int $body = null )

Description

Updates the attributes for all cells.

Parameter

  • mixed $attributes - Associative array or string of table row attributes

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::toHtml() | PEAR Manual | HTML_Table::updateCellAttributes()


HTML_Table::updateCellAttributes()

HTML_Table::updateCellAttributes()

HTML_Table::updateCellAttributes() – Update cell attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::updateCellAttributes ( int $row , int $col , mixed $attributes , int $body=0 )

Description

Updates the cell attributes passed but leaves other existing attributes intact

Parameter

  • int $row - Row index

  • int $col - Column index

  • mixed $attributes - Associative array or string of table row attributes

  • int $body - The number of the tbody group that should be used

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::updateAllAttributes() | PEAR Manual | HTML_Table::updateColAttributes()


HTML_Table::updateColAttributes()

HTML_Table::updateColAttributes()

HTML_Table::updateColAttributes() – Update column attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::updateColAttributes ( int $col , mixed $attributes = null , int $body = null )

Description

Updates the column attributes for an existing column

Parameter

  • int $col - Column index

  • mixed $attributes - Associative array or string of table row attributes

  • int $body - The number of the tbody group that should be used. NULL indicates that all groups should be used.

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::updateCellAttributes() | PEAR Manual | HTML_Table::updateRowAttributes()


HTML_Table::updateRowAttributes()

HTML_Table::updateRowAttributes()

HTML_Table::updateRowAttributes() – Update row attributes

Synopsis

require_once 'HTML/Table.php';

void HTML_Table::updateRowAttributes ( int $row , mixed $attributes = null , boolean $inTR = false , int $body=0 )

Description

Updates the row attributes for an existing row

Parameter

  • int $row - Row index

  • mixed $attributes - Associative array or string of table row attributes

  • boolean $inTR - FALSE if attributes are to be applied in td tags; TRUE, if attributes are to be applied in tr tag.

  • int $body - The number of the tbody group that should be used

Throws

Possible PEAR_Error values
Error code | Error message | Meaning | Solution
 | " Invalid table row reference [$row ] " | The row $row does not exists | Enable the autoGrow feature
 | " Invalid table column reference [$column ] " | The column $column does not exists | Enable the autoGrow feature

Note

This function can not be called statically.

Prev | HTML_Table | Next
HTML_Table::updateColAttributes() | PEAR Manual | HTML_TagCloud


HTML_TagCloud

HTML_TagCloud

Create and display defined "tags" (words) in a "tag cloud".

Table of Contents
  • Introduction -- Introduction to HTML_TagCloud.
  • Usage examples -- Using HTML_TagCloud.
Prev | HTML | Next
HTML_Table::updateRowAttributes() | PEAR Manual | Introduction


Introduction

Edited By

Shoma Suzuki

Introduction

Introduction – Introduction to HTML_TagCloud.

Overview

This package can be used to generate tag coulds in HTML and CSS. A tag cloud is an visual representation of list of so-called "tags" or keywords, that do have a different font size depending on how often they occur on the page/blog.

More information on tag clouds is available in Wikipedia.

This package does not only visualize frequency, but also timeline infomation. The newer the tag is, the deeper its color will be; older tags will have a lighter color.

Simple usage example

Basic example

<?php
require_once 'HTML/TagCloud.php';

$tags = new HTML_TagCloud();
// add Elements
$tags->addElement('PHP'       ,'http://www.php.net'  , 39, strtotime('-1 day'));
$tags->addElement('XML'       ,'http://www.xml.org'  , 21, strtotime('-2 week'));
$tags->addElement('Perl'      ,'http://www.xml.org'  , 15, strtotime('-1 month'));
$tags->addElement('PEAR'      ,'http://pear.php.net' , 32, time());
$tags->addElement('MySQL'     ,'http://www.mysql.com', 10, strtotime('-2 day'));
$tags->addElement('PostgreSQL','http://pgsql.com'    ,  6, strtotime('-3 week'));
// output HTML and CSS
print $tags->buildALL();
?>

The above example code creates a tag cloud containing five items. The tag used most often is "PHP"; it will appear in the largest font. The tag used latest is"PEAR", it is in the deepest color. Tags are sorted by alphabetically, and escaped in HTML.

Prev | HTML_TagCloud | Next
HTML_TagCloud | PEAR Manual | Usage examples


Usage examples

Edited By

Shoma Suzuki

Usage examples

Usage examples – Using HTML_TagCloud.

Generate HTML and CSS separately

HTML_TagCloud creates HTML and CSS. The HTML is a simple list, decorated by CSS. You are able to output HTML and CSS separately.

output HTML and CSS separately

<?php
// CSS part only
$css = $tags->buildCSS();
// html part only
$taghtml = $tags->buildHTML();
?>

The HTML output depends on the tag data that have been added via addElement(), but the CSS output is static. You can use this package's CSS output statically.

Modify the decoration of the tag

It is possible to modify the colors used by the CSS. You need to define your own class which extends HTML_TagCloud and override color and size properties.

Decoration example

<?php
class MyTags extends HTML_TagCloud
{
    protected $epocLevel = array(
        array(
            'earliest' => array(
                'link'    => 'ffdfdf',
                'visited' => 'ffdfdf',
                'hover'   => 'ffdfdf',
                'active'  => 'ffdfdf',
            ),
        ),
        array(
            'earlier' => array(
                'link'    => 'ff7f7f',
                'visited' => 'ff7f7f',
                'hover'   => 'ff7f7f',
                'active'  => 'ff7f7f',
            ),
        ),
        array(
            'previous' => array(
                'link'    => 'ff7f7f',
                'visited' => 'ff7f7f',
                'hover'   => 'ff7f7f',
                'active'  => 'ff7f7f',
            ),
        ),
        array(
            'recent' => array(
                'link'    => 'ff4f4f',
                'visited' => 'ff4f4f',
                'hover'   => 'ff4f4f',
                'active'  => 'ff4f4f',
            ),
        ),
        array(
            'later' => array(
                'link'    => 'ff1f1f',
                'visited' => 'ff1f1f',
                'hover'   => 'ff1f1f',
                'active'  => 'ff1f1f',
            ),
        ),
        array(
            'latest' => array(
                'link'    => 'ff0000',
                'visited' => 'ff0000',
                'hover'   => 'ff0000',
                'active'  => 'ff0000',
            ),
        ),
    );
    protected $size_suffix = 'pt';
    protected $fontsizerange = 0;
    protected $basefontsize = 12;
}
?>

Omit timeline feature

If you don't want to add timeline information and have the color changing accordingly, just omit the fourth parameter to addElement(). When doing this, the current time is set.

Omitting the timeline

<?php
$tags->addElement('PHP','http://www.php.net', 39);
?>
Prev | HTML_TagCloud | Next
Introduction | PEAR Manual | HTML_Template_Flexy


HTML_Template_Flexy

HTML_Template_Flexy

An extremely flexible Template core, with multiple engines.

Table of Contents
  • Introduction -- What HTML_Template_Flexy can do
  • Configuration Options -- Setting the defaults for HTML_Template_Flexy
  • new HTML_Template_Flexy -- constructor
  • $flexy->compile() -- Converts a template from markup to PHP if required
  • $flexy->outputObject() -- Merges a controller object with the template and outputs the result
  • $flexy->bufferedOutputObject() -- Merges a controller object with the template and returns the result
  • $flexy->getElements() -- Fetch Dynamic HTML Elements from template
  • new HTML_Template_Flexy_Element -- Class constructor
  • $element->setValue() -- Utility function to set or store values from common tag types.
  • $element->setOptions() -- Utility function equivilant to HTML_Select - loadArray **
  • $element->removeAttributes() -- Removes an attributes
  • $element->setAttributes() -- Sets the HTML attributes
  • $element->toHtml -- Output HTML and children
  • $element->toHtmlnoClose() -- Output Open Tag and any children and not Child tag (designed for use with <form + hidden elements>
  • $factory->freeze() -- freeze - freeze's an element. - just copies the value to the override.
  • $factory->fromArray() -- fromArray - builds a set of elements from a key=>value array (eg. DO->toArray()) the second parameter is an optional HTML_Element array to merge it into.
  • $factory->fromArrayPrefixed() -- fromArrayPrefixed - takes a multi dimensional array, and builds the 'xxx[sss][xx]' => value
  • $factory->setErrors() -- setErrors - sets the suffix of an element to a value..
  • $factory->setRequired() -- setRequired - sets the prefix of an element to a value..
  • {variable} -- creates PHP code to echo a variable
  • {method(arguments,#quoted arguments#)} -- creates a PHP method call, and echos the results
  • {foreach:variable,key,value} -- creates a PHP foreach loop
  • {if:variable} -- creates a PHP if statement
  • {end:} -- closes an if or foreach block
  • {else:} -- adds an PHP else in an if block
  • <FORM NAME="name" -- configures automatic form elements
  • <INPUT NAME="name"> -- creates PHP variable for input values
  • <TEXTAREA NAME="name"> -- creates PHP variable for textarea value
  • <SELECT NAME="name"> -- creates PHP variable and code for select lists
  • flexy:if="variable or method()" -- creates a PHP if conditional tag
  • flexy:foreach="variable,key,value" -- creates a PHP foreach loop using a html attribute
  • flexy:start="here" -- Start the output, using this tag and its children.
  • flexy:startchildren="here" -- Start the output using its children.
  • flexy:ignore="yes" -- Prevent Automatic form value replacement
  • flexy:nameuses="variable" -- Use a variable in the name for a flexy form element
  • <FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ... -- Provides a simple way to pass data from PHP to Javascript
Prev | HTML | Next
Usage examples | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What HTML_Template_Flexy can do

Introduction

HTML_Template_Flexy started its life as a simplification of HTML_Template_Xipe, However the long term aim of Flexy is to provide a universal Template Base API for Compiling and native PHP type templates.

Flexy currently supports a number of backends (Template Formats), and is designed to be extended to support more, The Key Formats are:

  • Standard - A rich Tokenizer driven engine, that uses {variable_placeholders}, attribute based (flexy:foreach="...."), and custom tag <flexy:tojavascript ... To rapidly create PHP code from simple markup. These templates are designed to be editable in WYSIWYG HTML editors, without breaking the tags

  • Regex - A classic templating backend, for supporting Smarty, Xipe, or Email type convertion to PHP code.

  • Raw - A non compiling backend, that enables you to create templates using PHP, Useful if you intend to redistribute your application and are concerned about compilation

Data can be assigned in two ways with flexy, depending on your preferred style of working.

  • Push - you put data into the template engine, using $flexy->setData(), and $flexy->setDataByRef(), this is similar to the way Smarty and other templates work.

  • Push/Pull - You provide the outputer with a Data Provider Object, (either a Data Object, or a Controller) that contains the data to display (and objects with methods that can be called). This has the added benefit of making the Variables in the template documentable, using PEAR standards, eg. PHPDoc comments.

With all this Flexibility, it still manages to achieve

  • Very Lightweight Simple API, which easy to learn

  • In Normal operation very little code is actually loaded (so it's fast)

How does HTML_Template_Flexy differ from other template systems

If you look around you will see there are other template systems available in PHP, they generally fall into two categories, Replacement Systems, or PHP Code builders.

Replacement systems like HTML_Template_IT, FastTemplate, PhpLib Template tend to be slower at doing block and nested block type templates and involve alot of code to add each variable to the template.

Php Code builders like Flexy, Smarty, SimpleTemplate (now HTML_Template_Xipe) tend to be better at more complex templates, and can offer a better approach to extendability. (the long term aim of Flexy is to integrate support for all of these PHP Generator templates into a simple package)

The Standard Compiling Backend uses a Tokenizer, which offers the possiblities of using HTML tags and attributes to provide looping and conditionals, and make dynamic XML_Tree like elements of HTML Forms that can be manipulated in your code. (This conversion is only done once when the template compiles)

Typical use example

Flexy template is normally called from within a Controller Class (in the Model,View,Controller paragam). You just send HTML_Template_Flexy, the name of the template, and the object to output. - any variable you want printing out just has to be set in the object being used to ouput.

Typical usage example for HTML_Template_Flexy

<?php

/* configure the application - probably done elsewhere */
require_once 'HTML/Template/Flexy.php';
require_once 'PEAR.php';
$options = &PEAR::getStaticProperty('HTML_Template_Flexy','options');
$config = parse_ini_file('example.ini',TRUE);
$options = $config['HTML_Template_Flexy'];

/* the page controller class */

class controller_test
{

    var $template = "home.html"; // name of template
    var $title;                  // this relates to {title};
    var $numbers = array();      // this relates to {numbers} , used with foreach
    var $anObject;

    var $elements = array();      // this is where the elements are stored

    /* start section - deals with posts, get variables etc.*/

    function controller_test()
    {
        $this->start();
        $this->output();
    }

    function start()
    {
        // the title
        $this->title = "Hello World";

        // store an object.
        $this->anObject = new StdClass;

        // assign a value to a member.
        $this->anObject->member = 'Object Member';

        // if you need form elements - you have to include them.
        require_once 'HTML/Template/Flexy/Element.php';

        // create an HTML Element for the form element.
        $this->elements['input'] = new HTML_Template_Flexy_Element;

        // assign a value to it
        $this->elements['input']->setValue('Hello');

        for ($i = 1;$i< 5;$i++) {
            $this->numbers[$i] = "Number $i";
        }
    }

    /* output section - probably best to put this in the default_controller class */

    function output() {
        $output = new HTML_Template_Flexy();
        $output->compile($this->template);
        $output->outputObject($this,$this->elements);
    }

    function someMethod() {
        return "<b>Hello From A Method</b>";
    }

}

/* the page controller instantaation - probably done with a factory method in your master page controller class */

new controller_test();

?>

Now the example template,

Example Template for HTML_Template_Flexy

//ignore any php tags before this comment
<html>
  <head>
    <title>{title}</title>
  </head>
  <body>
  <H1>{title}</H1>

    <form name="form">
    <table>
      <tr>
        <td>
         <?php /*  this will be merged with the date in the  $element['input']  object*/ ?>

          Input Box: <input name="input">
        </td>
      </tr>

      <?php /*  note here the use for flexy:foreach as an attribute value */ ?>

      <tr flexy:foreach="numbers,number,string">
        <td>

      <?php /*   note here the use for flexy:foreach as an attribute value */ ?>

          <a href="mypage.html?id=%7Bnumber%7D">{string}</a>
        </td>
      </tr>

    </table>

    <?php /*   there is some limited support for array access */ ?>

    this is number 2 : {numbers[2]}

    <?php /*  note that full stops seperate object and variables or methods */ ?>

  This is a {anObject.member}

    <?php /* you can call methods of the object */ ?>

    {someMethod()}

    <?php /* by default everything is htmlspecialchar escaped use the modifier :h to prevent this. */ ?>

    {someMethod():h}

  </body>
</html>

<?php /*  I've used php for comments here as HTML comments didnt work when generating the
manual .. - you dont have to use them - it has nothing to do with the template engine */ ?>

And the output

Output of example for HTML_Template_Flexy

Hello World

Input Box : [Hello     ]
Number 1
Number 2
Number 3
Number 4

this is number 2 : Number 2

This is a member Variable

<B>Hello From A Method</B>

Hello From A Method
Prev | HTML_Template_Flexy | Next
HTML_Template_Flexy | PEAR Manual | Configuration Options


Configuration Options

Configuration Options

Configuration Options – Setting the defaults for HTML_Template_Flexy

Configuration

HTML_Template_Flexy can either be configured globally or on each instance, using an associated array. The easiest way to configure HTML_Template_Flexy is to use ini files (although you may also like to consider the PEAR::Config class, or your own configuration system)

This is a typical configuration file for HTML_Template_Flexy

[HTML_Template_Flexy]

templateDir = /home/me/Projects/myapplication/templates
compileDir =  /home/me/Projects/myapplication/compiled_templates
forceCompile = 0
debug = 0
locale = en
compiler = Standard

To use this ini file with HTML_Template_Flexy, (and Possibly any other classes that use options like this)

Setting the default options

<?php
$config = parse_ini_file('example.ini',TRUE);
foreach($config as $class=>$values) {
  $options = &PEAR::getStaticProperty($class,'options');
  $options = $values;
}
?>

Alternatively you can set (or override) the configuration when you instantate the class

Setting the default options

<?php
  $options = array(
      'templateDir'   => '/home/me/Projects/myapplication/templates',
      'compileDir'    => '/home/me/Projects/myapplication/compiled_templates',
      'forceCompile'  => 0,
      'debug'         => 0,
      'locale'        => 'en',
      'compiler'      => 'Standard',
  );
  $template = new HTML_Template_Flexy($options);
?>

Configuration Options

templateDir directory

This is the directory where all your templates are located

compileDir directory

The directory where the compiled templates will be stored, This directory should be writable by the web server

forceCompile boolean

Normally 0, means that the template will only be compiled once (or if the template file is altered), this is only really usefull if you are developing filters and need to test the result.

debug integer

The default debugging level (default 0=off), 1= shows some debugging information

locale string

Default is 'en' - english. The language use for reading/writing templates. Currently it is only used in the compiled files filename = eg. originalname.html.en.php

Flexy uses get_text() internally if it is installed, and will replace all strings in a HTML page with the return value of get_text(). - This enables the creation of multilanguage sites with a little less pain.

A file {templatename}.strings.serial is created for each file that is parsed, you can use this with PHP's unserialize function to retrieve an array of all the strings in a file. (for translating), or just use the tool xgettext.

compiler string

Default is 'Flexy' - The Flexy Tokenizer Driver engine. Other engines available are regex (similar to Xipe's engine), Raw (For plain PHP files with no replacement or compiling) and Standard (depreciated). You can use this field to load your own engines, either based Off the core code, or totally seperate..

multiSource boolean

Default is false - Allow the same template to exist in multiple places (eg. if you have theme's and want to fall back to a default template if the themed version doesnt exist.)

templateDirOrder string

Default is '' - by default, the first matched template is used, if you have multiple paths, and want the last in the list to be used, then set this to 'reverse'

filters array|string

an array or comma seperated string of filters ONLY USED BY THE Regex backend, available filters are: BodyOnly (strip everything before and after body tag), Mail (add an extra line break after php tags.), Php (removes php code, not very reliably), SimpleTags (variable, method etc. replacement), XML (replace XML opening tag with echos.)

nonHTML boolean

default is false - if you use the Flexy compiler, it turns off parsing of HTML, (not heavily tested)

allowPHP boolean|string

default is false - allows php code in templates, normally off to help you reduce the chance of you shooting your self in the foot by forgetting to escape output.. (can be usefull for complex looping), but not normally recommended. setting to true, enables PHP code, setting to 'delete' removes php code. (although it doesnt prevent XSS attacks, so it is only suited to trusted users)

flexyIgnore boolean

default is false - setting to true, will turn off the conversion of html form elements into HTML_Template_Flexy_Element's

numberFormat string

default is ",2,'.',','" - this is the piece of code that is appended to the output engine when using the :n modifier, eg. {xxxx:n} is replaced with number_format($t->xxxx,2,'.',','); see the php manual page for number_format the default output would be: 1,200.00

url_rewrite string

when compiling the template flexy can rewrite <img src, <script src, <a href and xul stylesheet urls. The format is "match/original:new/url, match/another/original:new/url" each combo is seperated by a comma, and the colon seperates the pair. This helps previewing templates without using the engine.

compileToString boolean

default false - if set to true, the compile will return a string of the compiled template, rather than writing it to the cache file. eg. {object._myvar}

privates boolean

default false - if set to true, you can access variables prefixed with an underscore (normally private in PEAR's coding standards) eg. {someobject._myprivatevar} and {_myprivate}

globals boolean

default false - if set to true, you can access php's globals and superglobals, eg. {_POST[myvar]}, {GLOBALS[somevalue]}

globalfunctions boolean

default false - if set to true, you can access any native php function using the GLOBALS. prefix eg. {GLOBALS.date(#d/m/Y#)} obviously you should trust your template authors, as they can easily run exec() if this is enabled.

locale string

default 'en' - either used to search for language specific templates with {filename}.{locale}.{extension} or in conjunction with the Translation2 language translation toolkit, to set the language used to translate templates to at compile time.

Translation2 mixed

default false - you can set this to an array or an existing Translation2 object eg. Translation2 => array('driver'=>'dataobjectsimple', options=>array()));

strict boolean

default false - By default warnings about undefined variabes are hidden, this turns on all PHP warnings during the outputObject calls. Can be usefull for finding bugs hidden by method callbacks.

fatalError int

default constant HTML_TEMPLATE_FLEXY_ERROR_DIE - this determines the behaviour when compiling a template fails, normally flexy will die and report the error to the screen, you can change this to HTML_TEMPLATE_FLEXY_ERROR_RETURN, if you want to recieve a PEAR_Error object from compile().

plugins string|array

loads plugin classes, (by default from the Plugin folder), these can be used either via {plugin.nameofmethod} or as a modifier {outputstring:dateformat}, default formats are normally collected via configuration options plugin.dateformat, plugin.numberformat.decimals, plugin.numberformat.point, plugin.numberformat.thousands

Prev | HTML_Template_Flexy | Next
Introduction | PEAR Manual | new HTML_Template_Flexy


new HTML_Template_Flexy

new HTML_Template_Flexy

new HTML_Template_Flexy – constructor

Synopsis

require_once 'HTML/Template/Flexy.php';

new HTML_Template_Flexy ( array $options )

Description

The Object Constructor accepts options as its arguments. Normally, you do not need to provide any options, as they are set by the PEAR::getStaticPropery(), as described in the configuration.

Parameter

  • array $options - anything you need to change from the default settings

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
Configuration Options | PEAR Manual | $flexy->compile()


$flexy->compile()

$flexy->compile()

$flexy->compile() – Converts a template from markup to PHP if required

Synopsis

void $flexy-> compile ( string $template )

Description

If necessary it will convert the Template markup into PHP code, and writes it to the compiledTemplate directory adding the {locale}.php to the end of the filename. The Template is only compiled if

  • No compiled file exists

  • The file modification date of the template is greater than the compiled one

  • The forceCompile Flag was set in config or when you created the template object.

It is not normally necessary to set the forceCompile flag, unless you are working on the engine itself.

Parameter

  • string $template - Used in conjuction with the config variable 'templateDir' to locate the template to compile into PHP code.

Return value

string - the location of the compiled file (which could be used with include) - although it is recommended to use the outputObject methods.

Note

This function can not be called statically.

Example

Compiling multiple files.

<?php
class controller_test
{

    var $masterTemplate = "master.html"
    var $template = "home.html"; // name of template
    var $title;                // page title;
    var $numbers = array();    // an array example

    /* start section - deals with posts, get variables etc.*/

    function controller_test()
    {
        $this->start();
        $this->output();
    }

    function start()
    {
        $this->title = "<Hello World>";

        for ($i = 1;$i< 5;$i++) {
            $this->numbers[$i] = "Number $i";
        }
    }

    /* output section - probably best to put this in the default_controller class */

    function output() {
        $master = new HTML_Template_Flexy();
        $master->compile('some_file_name');
        $master->outputObject($this);
    }

    function outputBody() {
        $body = new HTML_Template_Flexy();
        $body->compile($this->template);
        $body->outputObject($this);
    }

}

new controller_test;
?>

Master template example

Page Header Goes here.

{outputBody()}

Page Footer Goes here

Simple ouput example

Page Header Goes here.

some numbers
Number 1
Number 2
Number 3
Number 4

Page Footer Goes here
Prev | HTML_Template_Flexy | Next
new HTML_Template_Flexy | PEAR Manual | $flexy->outputObject()


$flexy->outputObject()

$flexy->outputObject()

$flexy->outputObject() – Merges a controller object with the template and outputs the result

Synopsis

void $flexy-> outputObject ( object $controllerObject , array $elements )

Description

This makes the values of the supplied object (and optionally loads the HTML_Template_Flexy_Elements) available to the template when it is run.

Parameter

  • object $controllerObject - The object you want to use with the template, the values of the object will relate to the $controllerObject->tag will map to {tag} on the template

  • array $elements - This is an associative array of form, or dynamic elements names (or id's) which will be merged with the one defined in the template.

Note

This function can not be called statically.

Example

PHP code initiating the template, and outputing it

<?php
class example {
  var $tag = ">> hello world";
}

$data = new example;

$elements['test'] = new HTML_Template_Flexy_Element;
$elements['test']->setValue("hello input");

$output = new HTML_Template_Flexy();
$output->compile("hello.html");
$output->outputObject($data,$elements);
?>

The Template with some tags

<B>{tag}</B>
<B>{tag:h}</B>
<INPUT name="test">

Resulting output

<B>&gt;&gt; hello world</B>
<B>>> hello world</B>
<INPUT name="test" value="hello input">
Prev | HTML_Template_Flexy | Next
$flexy->compile() | PEAR Manual | $flexy->bufferedOutputObject()


$flexy->bufferedOutputObject()

$flexy->bufferedOutputObject()

$flexy->bufferedOutputObject() – Merges a controller object with the template and returns the result

Synopsis

string $flexy->bufferedOutputObject ( object $controllerObject , array $elements )

Description

This maps the values of the supplied object and runs the compiled template, and returns the result.

This can be used in conjuction with PEAR::Cache, or in the example below, with a email template (note this still needs testing.. - the backend should eventually support a native tokenizer for email templates.)

Parameter

  • object $controllerObject - The object you want to use with the template, the values of the object will relate to the $controllerObject->tag will map to {tag} on the template

  • array $elements - This is an associative array of form, or dynamic elements names (or id's) which will be merged with the one defined in the template.

Return value

string - the object variables overlayed on the template

Note

This function can not be called statically.

Example

Person DataObject send_password method

<?php
class DataObjects_Person {
    var $id;
    var $name;
    var $password;
    var $cleartextPassword;
    var $email;

    function sendEmail($templateFile,$content) {

            $content = is_object($content) ? $content : (object) $content;
            foreach(get_object_vars($this) as $k=>$v) {
                $content->$k = $v;
            }
            /* use the regex compiler, as it doesnt parse <tags */
            $template = new HTML_Template_Flexy( array(
                    'compiler'    => 'Regex',
                     'filters' => array('SimpleTags','Mail'),
                ));

            /* compile a text file (email template) */
            $template->compile($templateFile);

            /* use variables from this object to ouput data. */
            $mailtext = $template->bufferedOutputObject($content);
            //echo "<PRE>";print_R($mailtext);

            /* With the output try and send an email, using a few tricks in Mail_MimeDecode. */
            require_once 'Mail/mimeDecode.php';
            require_once 'Mail.php';

            $decoder = new Mail_mimeDecode($mailtext);
            $parts = $decoder->getSendArray();
            if (PEAR::isError($parts)) {
                return $parts;

            }
            list($recipents,$headers,$body) = $parts;

            $mailOptions = PEAR::getStaticProperty('Mail','options');
            $mail = Mail::factory("SMTP",$mailOptions);

            return PEAR::isError($mail) ? $mail : $mail->send($recipents,$headers,$body);

        }

}
?>

An email template (using the Regex Parser - hence the {t.*})

From: "HTML_Template_Flexy" <html_template_flexy@pear.php.net>
Sender: "HTML_Template_Flexy"  <html_template_flexy@pear.php.net>
To: {t.email}
Subject: Here is your new password
Content-Type: text/plain; charset=us-ascii

Dear {t.name}

Your New Password is {t.cleartextPassword}

please use it  to log into your bank account :)

The resulting email head and body

From: "HTML_Template_Flexy" <html_template_flexy@pear.php.net>
Sender: "HTML_Template_Flexy"  <html_template_flexy@pear.php.net>
To: demo@example.com
Subject: Here is your new password
Content-Type: text/plain; charset=us-ascii

Dear Fred Blobs

Your New Password is 0ab123dcc

please use it  to log into your bank account :)
Prev | HTML_Template_Flexy | Next
$flexy->outputObject() | PEAR Manual | $flexy->getElements()


$flexy->getElements()

$flexy->getElements()

$flexy->getElements() – Fetch Dynamic HTML Elements from template

Synopsis

array $flexy-> getElements ( )

Description

All Form elements, FORM, INPUT, SELECT and any HTML tag that includes the attribute flexy:dynamic Is converted into HTML_Template_Flexy_Element's and stored serialized in the same folder as the Compiled flexy template.

You can use this array to make changes to these elements or find out what form elements exist on a page.

Note: you should put the modified result as the $elements argument of >outputObject(), you do not however have to fetch the elements to assign them, you can just create blank elements, and merge them.

Return value

array - of Elements contained within the template. (or an empty array if no form/dynamic elements are used)

Note

This function can not be called statically.

Example

Introspecting a template

<?php
$form = new HTML_Template_Flexy();
$form->compile('some_file_name');
print_r($form->getElements());
?>

template example

<BODY>
  <FORM name="XXXX">
    <INPUT name="yyy">
    <SELECT name="zzz">
       <OPTION value="aaaa">AAAAA</OPTION>
    </SELECT>
  </FORM>
</BODY>

template compiled

<BODY>
  <?php echo $this->elements['XXXX']->toHtmlnoClose();?>
    <?php echo $this->elements['yyy']->toHtml();?>
    <?php echo $this->elements['zzz']->toHtml();?>
  </form>
</BODY>

output from the Introspection

Array
(
[XXXX] => html_template_flexy_element Object
(
[tag] => form
[attributes] => Array
(
[name] => XXXX
)

[children] => Array
(
)

[override] =>
[prefix] =>
[suffix] =>
[value] =>
)

[yyy] => html_template_flexy_element Object
(
[tag] => input
[attributes] => Array
(
[name] => yyy
)

[children] => Array
(
)

[override] =>
[prefix] =>
[suffix] =>
[value] =>
)

[zzz] => html_template_flexy_element Object
(
[tag] => select
[attributes] => Array
(
[name] => zzz
)

[children] => Array
(
[0] =>

[1] => html_template_flexy_element Object
(
[tag] => option
[attributes] => Array
(
[value] => aaaa
)

[children] => Array
(
[0] => AAAAA
)

[override] =>
[prefix] =>
[suffix] =>
[value] =>
)

[2] =>

)

[override] =>
[prefix] =>
[suffix] =>
[value] =>
)

)
Prev | HTML_Template_Flexy | Next
$flexy->bufferedOutputObject() | PEAR Manual | new HTML_Template_Flexy_Element


new HTML_Template_Flexy_Element

new HTML_Template_Flexy_Element

new HTML_Template_Flexy_Element – Class constructor

Synopsis

require_once 'HTML/Template/Flexy/Element.php';

new HTML_Template_Flexy_Element ( string $tag = '' , array $attributes = null )

Description

Flexy uses a single lightweight class to represent All HTML Tags, All the variables of the class are public, and you are encouraged to use them. And the methods provide generic assignment and conversion abilities.

To force the toHtml() method to generate XHTML, rather than standard HTML, use $element->setAttributes(array('flexy:xhtml'=>true)); or add flexy:xhtml="true" to the attribute of the element in the template.

Parameter

  • $tag - The name of the HTML Tag eg. img for <img ....

  • $attributes - Associative array of attributes, where key="value" is output when you turn it in toHtml(), If you need to represent a attribute without a value, use TRUE as the value. This also accepts a string in the format "href='/test.jpg' alt='test'", which will be parsed into the attributes array of the object.

Public Properties

string $element->tag

The name of the html element eg. img for <img...

array $element->attributes

Attributes for the element

array $element->children

All the sub elements inside this, can be any object that implements toHtml(), or a string.

string $element->override

this value of thiswill be output when toHtml() is called, rather than the tags.

string|object $element->prefix

string or object that implements toHtml() method, and is returned by toHtml() before the tag HTML

string|object $element->suffix

string or object that implements toHtml() method, and is returned by toHtml() after the tag HTML

mixed $element->value

when you create an element, that is to be merged later with a full definition, you can assign the value here, and during toHtml(), the toValue() method will be called and select options, checkboxes and input values will be correctly filled in.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Using an element to change a template.

<?php
$form = new HTML_Template_Flexy();
$form->compile('some_file_name');

// create an instance (note you dont have to specify any details..)

$elements['test'] = new HTML_Template_Flexy_Element;

// change an attribute
$elements['test']->attributes['class'] = 'bold';

// sets the value
$elements['test']->setValue('Fred');

// wrap it with something
$elements['test']->prefix = '******';
$elements['test']->suffix = '!!!!!!';

// for the different types of elements:
$elements['test_textarea'] = new HTML_Template_Flexy_Element;
$elements['test_textarea']->setValue('Blogs');

// select options
$elements['test_select'] = new HTML_Template_Flexy_Element;
$elements['test_select']->setOptions( array(
  '123' => 'a select option',
  '1234' => 'another select option'
));
$elements['test_select']->setValue('1234');

// checkboxes
$elements['test_checkbox'] = new HTML_Template_Flexy_Element;
$elements['test_checkbox']->setValue(1);
$elements['test_checkbox']->setAttributes(array('flexy:xhtml'=>true));

// array type checkboxes..
$elements['test_checkbox_array[]'] = new HTML_Template_Flexy_Element;
$elements['test_checkbox_array[]']->setValue(array(1,2));

// radio buttons
$elements['test_radio'] = new HTML_Template_Flexy_Element;
$elements['test_radio']->setValue('yes');

$form->outputObject(new StdClass, $elements);

// in the example below, the new data you have added is to the existing attributes
?>

template example

<body>
  <form name="xxxx">

    <input name="test" length="12">

    <textarea name="test_textarea"></textarea>

    <select name="test_select"></select>

    <input name="test_checkbox" type="checkbox" value="1">

    <input name="test_checkbox_array[]" type="checkbox" value="1" />1<br />
    <input name="test_checkbox_array[]" type="checkbox" value="2" />2<br />
    <input name="test_checkbox_array[]" type="checkbox" value="3" />3<br />

    <input name="test_radio" type="radio" id="yes" value="yes" />yes<br />
    <input name="test_radio" type="radio" id="no" value="no" />no<br />

  </form>
</body>

output from the Template

<body>
  <form name="xxxx">

    ******<input name="test"  length="12" class="bold" value="fred">!!!!!!

    <textarea name="test_textarea">blogs</textarea>

    <select name="test_select">
      <option value="123">a selection option</option>
      <option value="1234" selected>another selection option</option>

    </select>

    <input name="test_checkbox" type="checkbox" value="1" checked="checked" />

    <input name="test_checkbox_array[]" type="checkbox" value="1" checked>1<br />
    <input name="test_checkbox_array[]" type="checkbox" value="2" checked>2<br />
    <input name="test_checkbox_array[]" type="checkbox" value="3">3<br />

    <input name="test_radio" type="radio" id="yes" value="yes" checked>yes<br />
    <input name="test_radio" type="radio" id="no" value="no">no<br />

  </form>
</body>
Prev | HTML_Template_Flexy | Next
$flexy->getElements() | PEAR Manual | $element->setValue()


$element->setValue()

$element->setValue()

$element->setValue() – Utility function to set or store values from common tag types.

Synopsis

$element->setValue ( mixed $value )

Description

This is used to set the values of form elements, results depend on the type of element

  • text,password inputs, buttons Fills in the value attribute

  • checkboxs / radio buttons adds a checked tag to the matching element

  • textarea fills in the text area content

  • checkbox with arrays adds checked to the matching elements

  • selects adds selected to the

Parameter

  • $value The value to assign a form element, (use arrays for multiple selects or checkbox groups)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
new HTML_Template_Flexy_Element | PEAR Manual | $element->setOptions()


$element->setOptions()

$element->setOptions()

$element->setOptions() – Utility function equivilant to HTML_Select - loadArray **

Synopsis

$element->setOptions ( mixed $array , boolean $noValue = false )

Description

Used with HTML Selects, to fill in the options available

Parameter

  • $array the options to appear.

  • $noValue don't use the keys from the array sent as the value= part of the option tag.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$element->setValue() | PEAR Manual | $element->removeAttributes()


$element->removeAttributes()

$element->removeAttributes()

$element->removeAttributes() – Removes an attributes

Synopsis

$element->removeAttributes ( mixed $attrs )

Description

use this to remove attributes from the tag when the element is rendered, It may be easier to access the attributes array directly and assign the value to false.

Parameter

  • $attributes name or array of names to remove from tag

Throws

throws

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$element->setOptions() | PEAR Manual | $element->setAttributes()


$element->setAttributes()

$element->setAttributes()

$element->setAttributes() – Sets the HTML attributes

Synopsis

require_once 'Flexy/Element.php';

HTML_Template_Flexy_Element::setAttributes ( mixed $attributes )

Description

Can be used to set attribute values, It is easier to set the attributes directly using the public attributes property.

Parameter

  • $attributes Either a typical HTML attribute string or an associative array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$element->removeAttributes() | PEAR Manual | $element->toHtml


$element->toHtml

$element->toHtml

$element->toHtml – Output HTML and children

Synopsis

string $element->toHtml ( )

Description

returns the HTML to represent the object. If you wish to implement your own element, you only need to implement this method, and assign it to the element array..

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$element->setAttributes() | PEAR Manual | $element->toHtmlnoClose()


$element->toHtmlnoClose()

$element->toHtmlnoClose()

$element->toHtmlnoClose() – Output Open Tag and any children and not Child tag (designed for use with <form + hidden elements>

Synopsis

string $element->toHtmlnoClose ( )

Description

Used by the template to represent form tags, which only the opening tag are rendered dynamically (so, all tags inside the tag are not forced to be dynamic).

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$element->toHtml | PEAR Manual | $factory->freeze()


$factory->freeze()

$factory->freeze()

$factory->freeze() – freeze - freeze's an element. - just copies the value to the override.

Synopsis

require_once 'Flexy/Factory.php';

array HTML_Template_Flexy_Factory::freeze ( array $array )

Description

this probably needs more thought.. - it would probably need to merge the full tag info with types, to be usefull..

$ar = HTML_Element_Factory::freeze($ar);

Parameter

  • $array (return by refernce key(tag name) => HTML_Template_Flexy_Element

Return value

return Array of HTML_Template_Flexy_Elements

Throws

throws no exceptions thrown

Note

Not documented yet.

Prev | HTML_Template_Flexy | Next
$element->toHtmlnoClose() | PEAR Manual | $factory->fromArray()


$factory->fromArray()

$factory->fromArray()

$factory->fromArray() – fromArray - builds a set of elements from a key=>value array (eg. DO->toArray()) the second parameter is an optional HTML_Element array to merge it into.

Synopsis

require_once 'Flexy/Factory.php';

array HTML_Template_Flexy_Factory::fromArray ( array $ar , optional $ret = array() )

Description

This package is not documented yet.

Parameter

  • $ar key(tag name) => value

  • $ret array key(tag name) => HTML_Element

Return value

return Array of HTML_Template_Flexy_Elements

Throws

throws no exceptions thrown

Note

Not documented yet.

Prev | HTML_Template_Flexy | Next
$factory->freeze() | PEAR Manual | $factory->fromArrayPrefixed()


$factory->fromArrayPrefixed()

$factory->fromArrayPrefixed()

$factory->fromArrayPrefixed() – fromArrayPrefixed - takes a multi dimensional array, and builds the 'xxx[sss][xx]' => value

Synopsis

require_once 'Flexy/Factory.php';

array HTML_Template_Flexy_Factory::fromArrayPrefixed ( array $prefix , array $ar , optional $ret = array() )

Description

This package is not documented yet.

Parameter

  • $prefix

  • $ar

  • $ret

Return value

return Array of HTML_Template_Flexy_Elements

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$factory->fromArray() | PEAR Manual | $factory->setErrors()


$factory->setErrors()

$factory->setErrors()

$factory->setErrors() – setErrors - sets the suffix of an element to a value..

Synopsis

require_once 'Flexy/Factory.php';

array HTML_Template_Flexy_Factory::setErrors ( array $ret , array $set , string $format = '<span class="error">%s</span>' )

Description

HTML_Element_Factory::setErrors($elements,array('name','not long enough'));

Parameter

  • $prefix

  • $ar

  • $ret

Return value

return Array of HTML_Template_Flexy_Element's

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$factory->fromArrayPrefixed() | PEAR Manual | $factory->setRequired()


$factory->setRequired()

$factory->setRequired()

$factory->setRequired() – setRequired - sets the prefix of an element to a value..

Synopsis

array HTML_Template_Flexy_Factory::setRequired ( array $ret , array $set , string $format = '>span class="required"<*>/span<' )

Description

HTML_Element_Factory::setRequired($elements,array('name',true));

Parameter

  • $prefix

  • $ar

  • $ret

Return value

return Array of HTML_Template_Flexy_Element's

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Flexy | Next
$factory->setErrors() | PEAR Manual | {variable}


{variable}

{variable}

{variable} – creates PHP code to echo a variable

Synopsis

 Usage (
 {variable}
  , {variable:h}
  , {variable:u}
)

Description

creates PHP code to echo a variable, with optional modifier. Modifiers are

  • No Modifier - does htmlspecialchars($variable)

  • :h - echos without any change - eg. raw

  • :u - echos urlencode($variable)

by default variables are assumed to have calling scope, and are prefixed with $t->, however if they are inside a loop (foreach), then the variables created by the loop are added to the scope and the prefix is not added.

Accessing object variables can be done using a dot as separator: {object.property}, calling methods is identical: {object.method()}.

Example

setting an object variable

$this->a = "hello >>";
$template->outputObject($this);

Outputting the variable

{a}
{a:h}
{a:u}

Compiled template

<?php echo htmlspecialchars($t->a); ?>
<?php echo $t->a; ?>
<?php echo urlencode($t->a); ?>

Simple ouput example

hello &gt;&gt;
hello >>
hello+%3E%3
Prev | HTML_Template_Flexy | Next
$factory->setRequired() | PEAR Manual | {method(arguments,#quoted arguments#)}


{method(arguments,#quoted arguments#)}

{method(arguments,#quoted arguments#)}

{method(arguments,#quoted arguments#)} – creates a PHP method call, and echos the results

Synopsis

 Usage (
 {method()}
  , {method():h}
  , {method():u}
  , {object.method()}
  , {method(with.a.variable)}
  , {method(with.multiple,variables)}
  , {method(with.variables,#and strings or literals#)}
)

Description

creates an PHP method call, any with any number of arguments, as variables or literals (quoted in #). the return value is echoed, and passed by a modifier (like variables)

  • No Modifier - does htmlspecialchars($variable)

  • :h - echos without any change - eg. raw

  • :u - echos urlencode($variable)

Example

Including another template

class example_page {
    var $masterTemplate = "master.html";
    var $bodyTemplate =   "body.html";

    function ucfirst($string) {
        return ucfirst($string);
    }

    function includeBody() {
        $template = new HTML_Template_Flexy();
        $template->compile($this->bodyTemplate);
        $template->outputObject($this);
    }
}

Calling includeBody in template, and ucfirst

{ucfirst(#this is the header#)}

{includeBody():h}

Footer Goes Here.

Compiled template

<?php echo htmlspecialchars($t->ucfirst("this is the header")); ?>

<?php echo $t->includeBody(); ?>

Footer Goes Here.

Output from the code

This is the header

Hello World

Footer Goes Here.
Prev | HTML_Template_Flexy | Next
{variable} | PEAR Manual | {foreach:variable,key,value}


{foreach:variable,key,value}

{foreach:variable,key,value}

{foreach:variable,key,value} – creates a PHP foreach loop

Synopsis

Usage ( {foreach:variable,key,value} , {foreach:variable,value} )

Description

creates a foreach loop, needs an {end:} tag. note that the engine will add the variable to the scope, so they will not be prefixed with $t-> when used inside the loop.

Parameter

  • string variable - relates to $object->variable

  • string key - creates a variable 'key' in the current scope.

  • string value - optionally creates a variable 'value' in the current scope. (as in $key=>$value)

Example

Setting variables for foreach

$this->a = array(
  "dog" => "cat",
  "fire" => "water"
);
$this->b = array('a','b','c');

$template->outputObject($this);

Foreach in template

{foreach:a,k,v}
  k is {k}, and v is {v}
{end:}
{foreach:b,v}
  v is {v}
{end:}

Compiled template

 <?php if (is_array($t->a)) foreach($t->a as $k => $v) { ?>
  k is <?php echo htmlspecialchars($k); ?>, and v is <?php echo htmlspecialchars($v); ?>
<?php } ?>
<?php if (is_array($t->a)) foreach($t->b as $v) { ?>
  v is <?php echo htmlspecialchars($v); ?>
<?php } ?>

example output

k is dog, v is cat
k is fire, v is water
v is a
v is b
v is c
Prev | HTML_Template_Flexy | Next
{method(arguments,#quoted arguments#)} | PEAR Manual | {if:variable}


{if:variable}

{if:variable}

{if:variable} – creates a PHP if statement

Synopsis

Usage ( {if:variable} , {if:method()} )

Description

creates an if statement, with the argument as a variable or method. You must close an if statement with an {end:} statement, and you may use {else:} with it.

Example

Setting variables for if

class example {
    function showDog() {
        return true;
    }

    function output() {

        $this->showStuff = true;

        .........
        $template->outputObject($this);
    }
}

The template

{if:showStuff}Hello{end:}
{if:showDog()}Doggy{end:}

Compiled template

<?php if ($t->showStuff)  { ?>Hello<?php } ?>
<?php if ($t->showDog()) {  ?>Doggy<?php } ?>

The output

Hello
Doggy
Prev | HTML_Template_Flexy | Next
{foreach:variable,key,value} | PEAR Manual | {end:}


{end:}

{end:}

{end:} – closes an if or foreach block

Synopsis

Usage ( {end:} )

Description

adds a closing brace in PHP so that blocks of conditional HTML are shown correctly. You do not need to use {end:} tags if you are using HTML tag attributes like IF="a,b", as the closing HTML tag will indicate that.

Example

Setting variables for if

class example {
    function showDog() {
        return true;
    }

    function output() {

        $this->showStuff = true;

        .........
        $template->outputObject($this);
    }
}

The template

{if:showStuff}Hello{end:}
{if:showDog()}Doggy{end:}

The compiled template

<?php if ($t->showStuff)  { ?>Hello<?php } ?>
<?php if ($t->showDog()) {  ?>Doggy<?php } ?>

The output

Hello
Doggy
Prev | HTML_Template_Flexy | Next
{if:variable} | PEAR Manual | {else:}


{else:}

{else:}

{else:} – adds an PHP else in an if block

Synopsis

Usage ( {else:} )

Description

adds an else statement in PHP so that blocks of conditional HTML are shown correctly.

Example

Setting variables for if

class example {

    function output() {

        $this->showStuff = false;

        .........
        $template->outputObject($this);
    }
}

Else in template

{if:showStuff}Hello{else:}World{end:}

Compiled template

<?php if ($t->showStuff)  { ?>Hello<?php } else { ?>World<<?php } ?>

The output

World
Prev | HTML_Template_Flexy | Next
{end:} | PEAR Manual | <FORM NAME="name"


<FORM NAME="name"

<FORM NAME="name"

<FORM NAME="name" – configures automatic form elements

Synopsis

Usage ( <FORM NAME="name"> )

Description

By default, all forms are converted to HTML_Template_Flexy_Elements, so they can be altered at runtime.

Example

Using an element to change a template.

<?php
$form = new HTML_Template_Flexy();
$form->compile('some_file_name');

// create an instance (note you dont have to specify any details..)

$elements['theform'] = new HTML_Template_Flexy_Element;

// change an attribute
$elements['theform']->attributes['action'] = 'http://pear.php.net';

//

// for the different types of elements:
$elements['test_textarea'] = new HTML_Template_Flexy_Element;
$elements['test_textarea']->setValue('Blogs');

// select options
$elements['test_select'] = new HTML_Template_Flexy_Element;
$elements['test_select']->setOptions( array(
  '123' => 'a select option',
  '1234' => 'another select option'
));
$elements['test_select']->setValue('1234');

// checkboxes
$elements['test_checkbox'] = new HTML_Template_Flexy_Element;
$elements['test_checkbox']->setValue(1);

// array type checkboxes..
$elements['test_checkbox_array[]'] = new HTML_Template_Flexy_Element;
$elements['test_checkbox_array[]']->setValue(array(1,2));

// radio buttons
$val = 'yes';
$elements['test_radio'] = new HTML_Template_Flexy_Element;
// if you have a default - you may want default to using it..
$elements['test_radio']->setValue($val != 'no' ? $val : 'no');

$form->outputObject(new StdClass, $elements);

// in the example below, the new data you have added is to the existing attributes
?>

template example

<BODY>
  <FORM name="theform">

      <TEXTAREA name="test_textarea"></TEXTAREA>

    <SELECT name="test_select"></SELECT>

    <input name="test_checkbox" type="checkbox" value="1">

    <input name="test_checkbox_array[]" type="checkbox" value="1">1<BR>
    <input name="test_checkbox_array[]" type="checkbox" value="2">2<BR>
    <input name="test_checkbox_array[]" type="checkbox" value="3">3<BR>

    <!-- you need to use id's -->
    <input name="test_radio" type="radio" id="radio_yes" value="yes">yes<BR>
    <input name="test_radio" type="radio" id="radio_no" value="no">no<BR>

  </FORM>
</BODY>

output from the Template

<BODY>
  <FORM name="theform" action="http://pear.php.net">

    <TEXTAREA name="test_textarea">Blogs</TEXTAREA>

    <SELECT name="test_select">
      <option value="123">a selection option</option>
      <option value="1234" selected>another selection option</option>

    </SELECT>

    <input name="test_checkbox" type="checkbox" value="1" checked>

    <input name="test_checkbox_array[]" type="checkbox" value="1" checked>1<BR>
    <input name="test_checkbox_array[]" type="checkbox" value="2" checked>2<BR>
    <input name="test_checkbox_array[]" type="checkbox" value="3">3<BR>

    <input name="test_radio" type="radio" value="yes" id="radio_yes" checked>yes<BR>
    <input name="test_radio" type="radio" value="no" id="radio_no">no<BR>

  </FORM>
</BODY>
Prev | HTML_Template_Flexy | Next
{else:} | PEAR Manual | <INPUT NAME="name">


<INPUT NAME="name">

<INPUT NAME="name">

<INPUT NAME="name"> – creates PHP variable for input values

Synopsis

Usage ( <INPUT NAME="name"> )

Description

fills in the form with values based on the form name and the tag name. If flexyignore is used, it is left alone (or if the body or form has a flexyignore tag it will be left alone).

Example

Using an element to change a template.

<?php
$form = new HTML_Template_Flexy();
$form->compile('some_file_name');

// create an instance (note you dont have to specify any details..)

$elements['test'] = new HTML_Template_Flexy_Element;

// change an attribute
$elements['test']->attributes['class'] = 'bold';

// sets the value
$elements['test']->setValue('Fred');

// wrap it with something
$elements['test']->prefix = '******';
$elements['test']->suffix = '!!!!!!';

$form->outputObject(new StdClass, $elements);

// in the example below, the new data you have added is to the existing attributes
?>

template example

<BODY>
  <FORM name="XXXX" flexy:ignoreonly="yes">

    <INPUT name="test" length="12">

  </FORM>
</BODY>

compiled template

<BODY>
  <FORM name="XXXX">

    <?php echo $this->elements['test']->toHtml();?>

  </FORM>
</BODY>

output from the Template

<BODY>
  <FORM name="XXXX">

    ******<INPUT name="test"  length="12" class="bold" value="Fred">!!!!!!

  </FORM>
</BODY>
Prev | HTML_Template_Flexy | Next
<FORM NAME="name" | PEAR Manual | <TEXTAREA NAME="name">


<TEXTAREA NAME="name">

<TEXTAREA NAME="name">

<TEXTAREA NAME="name"> – creates PHP variable for textarea value

Synopsis

Usage ( <TEXTAREA NAME="name"> )

Description

fills in the form with values based on the form name and the tag name. If flexyignore is used, it is left alone (or if the body or form has a flexyignore tag it will be left alone).

Example

Using an element to change a template.

<?php
$form = new HTML_Template_Flexy();
$form->compile('some_file_name');

// create an instance (note you dont have to specify any details..)

$elements['test'] = new HTML_Template_Flexy_Element;

// change an attribute
$elements['test']->attributes['class'] = 'bold';

// sets the value
$elements['test']->setValue('Fred');

$form->outputObject(new StdClass, $elements);

// in the example below, the new data you have added is to the existing attributes
?>

template example

<BODY>
  <FORM name="XXXX" flexy:ignoreonly="yes">

    <textarea name="test"></textarea>

  </FORM>
</BODY>

compiled template

<BODY>
  <FORM name="XXXX">

    <?php echo $this->elements['test']->toHtml();?>

  </FORM>
</BODY>

output from the Template

<BODY>
  <FORM name="XXXX">

     <textarea name="test" class="bold">Fred</textarea>

  </FORM>
</BODY>
Prev | HTML_Template_Flexy | Next
<INPUT NAME="name"> | PEAR Manual | <SELECT NAME="name">


<SELECT NAME="name">

<SELECT NAME="name">

<SELECT NAME="name"> – creates PHP variable and code for select lists

Synopsis

Usage ( <SELECT NAME="name"> )

Description

fills in the select values based on the form name and the tag name and adds code to check if the object variable matches them. If flexyignore is used, it is left alone. If static is set, the currently defined options will be used.

Example

Using an element to change a template.

<?php
$form = new HTML_Template_Flexy();
$form->compile('some_file_name');

// create an instance (note you dont have to specify any details..)

// select options
$elements['test_select'] = new HTML_Template_Flexy_Element;
$elements['test_select']->setOptions( array(
  '123' => 'a select option',
  '1234' => 'another select option'
));
$elements['test_select']->setValue('1234');

$form->outputObject(new StdClass, $elements);

// in the example below, the new data you have added is to the existing attributes
?>

template example

<BODY>
  <FORM name="theform" flexy:ignoreonly="yes">
       <SELECT name="test_select"></SELECT>

  </FORM>
</BODY>

compiled template

<BODY>
  <FORM name="theform">

    <?php echo $this->elements['test_select']->toHtml();?>

  </FORM>
</BODY>

output from the Template

<BODY>
  <FORM name="theform">

    <SELECT name="test_select">
      <option value="123">a selection option</option>
      <option value="1234" selected>another selection option</option>

    </SELECT>

  </FORM>
</BODY>
Prev | HTML_Template_Flexy | Next
<TEXTAREA NAME="name"> | PEAR Manual | flexy:if="variable or method()"


flexy:if="variable or method()"

flexy:if="variable or method()"

flexy:if="variable or method()" – creates a PHP if conditional tag

Synopsis

Usage ( flexy:if="variable" , flexy:if="method()" , flexy:if="object.method()" )

Description

creates an if condition surrounding the tag that it's included in.

Parameter

  • string variable - relates to $object->variable

  • string method - relates to $object->method()

  • string object.method relates to $object->object->method()

Example

Setting variables for foreach

class output {
    function hasTest() {
        return false;
    }

    function run() {
        $this->a = true;
        $this->message = 'oops'
        $template->outputObject($this);
    }
}

flexy:if in template

<a href="{baseURL}/somepath.html" flexy:if="a">this is the a link</a>
<a href="{baseURL}/somepath.html" flexy:if="!a">this is not the a link</a>
<b flexy:if="hasTest()">hasTest is true</b>
<b flexy:if="!hasTest()">hasTest is false</b>

<span flexy:if="message" class="error">{message}</span>

Compiled template

<?php if ($t->a)  { ?><A HREF="<?php echo htmlspecialchars($t->baseURL); ?>/somepath.html">this is the a link</A><?php } ?>
<?php if (!$t->a)  { ?><A HREF="<?php echo htmlspecialchars($t->baseURL); ?>/somepath.html">this is not the a link</A><?php } ?>
<?php if (isset($t) && method_exists($t,'hasTest')) if ($t->hasTest()) {  ?><B>hasTest is true</B><?php } ?>
<?php if (isset($t) && method_exists($t,'hasTest')) if (!$t->hasTest()) {  ?><B>hasTest is false</B><?php } ?>

<?php if ($t->message)  { ?><SPAN CLASS="error"><?php echo htmlspecialchars($t->message); ?></SPAN><?php } ?>

Simple ouput example

this is the a link
hasTest is false

oops
Prev | HTML_Template_Flexy | Next
<SELECT NAME="name"> | PEAR Manual | flexy:foreach="variable,key,value"


flexy:foreach="variable,key,value"

flexy:foreach="variable,key,value"

flexy:foreach="variable,key,value" – creates a PHP foreach loop using a html attribute

Synopsis

Usage ( flexy:foreach="variable,key,value" , flexy:foreach="variable,value" )

Description

creates a foreach loop, around the tag and close tag.

Parameter

  • string variable - relates to $object->variable

  • string key - creates a variable 'key' in the current scope.

  • string value - optionally creates a variable 'value' in the current scope. (as in $key=>$value)

Example

Setting variables for foreach

$this->a = array(
  "dog" => "cat",
  "fire" => "water"
);

$this->b = array('a','b','c');

$template->outputObject($this);

Foreach in template

<table>
  <tr flexy:foreach="a,k,v">
    <td>k is {k}, and v is {v}</td>
  </tr>
</table>
<table>
  <tr flexy:foreach="b,v">
    <td>v is {v}</td>
  </tr>
</table>

Compiled template

<table>
 <?php if (is_array($t->a)) foreach($t->a as $k => $v) { ?><tr>
  <td>k is <?php echo htmlspecialchars($t->k); ?>, and v is <?php echo htmlspecialchars($t->v); ?></td>
 </tr><?php } ?>
</table>
<table>
 <?php if (is_array($t->b)) foreach($t->b as $v) { ?><tr>
  <td>v is <?php echo htmlspecialchars($t->v); ?></td>
 </tr><?php } ?>
</table>

Simple ouput example

k is dog, v is cat
k is fire, V is water

v is a
v is b
v is c
Prev | HTML_Template_Flexy | Next
flexy:if="variable or method()" | PEAR Manual | flexy:start="here"


flexy:start="here"

flexy:start="here"

flexy:start="here" – Start the output, using this tag and its children.

Synopsis

Usage ( flexy:start="here" )

Description

Tells the generator to start outputing using this tag. This can be useful if you want to edit the template in a editor that expects a head/footer, and you can list the available tags in the comments at the top of the page.

The actual value of the tag is not relivant.

Example

Template with flexy:start

<HTML>
  <HEAD></HEAD>
  <BODY>
    <H1>This is an example</H1>
    <FORM name="input" flexy:start="yes">
      <INPUT name="hello" flexy:ignore="yes">
    </FORM>
  </BODY>
</HTML>

Compiled template

   <FORM NAME="input">
      <INPUT NAME="hello">
    </FORM>
Prev | HTML_Template_Flexy | Next
flexy:foreach="variable,key,value" | PEAR Manual | flexy:startchildren="here"


flexy:startchildren="here"

flexy:startchildren="here"

flexy:startchildren="here" – Start the output using its children.

Synopsis

Usage ( flexy:startchildren="here" )

Description

Tells the generator to start outputing using the children of this tag. This can be useful if you want to edit the template in a editor that expects a head/footer, normally adding this to body

The actual value of the tag is not relivant.

Example

Template with flexystartchildren

<HTML>
  <HEAD></HEAD>
  <BODY flexy:startchildren="here">
    <H1>This is an example</H1>
    <FORM name="input" flexy:ignoreonly="yes">
      <INPUT name="hello" flexy:ignore="yes">
    </FORM>
  </BODY>
</HTML>

Compiled template

    <H1>This is an example</H1>
    <FORM NAME="input">
      <INPUT NAME="hello">
    </FORM>
Prev | HTML_Template_Flexy | Next
flexy:start="here" | PEAR Manual | flexy:ignore="yes"


flexy:ignore="yes"

flexy:ignore="yes"

flexy:ignore="yes" – Prevent Automatic form value replacement

Synopsis

Usage ( flexy:ignore="yes" )

Description

Tells the generator not to replace form elements with PHP code. Can be used with a Form Tag, or individual elements.

Note: <input>s and <textarea>s with flexy:include or flexy:ignore: If you are turning off flexy element creation with flexy:ignore="yes", then this is not inherited by included templates, and you need to add that tag to the included template as well.

Example

Template with flexy:ignore

<form name="theform1">
  <input name="theinput1">
  <input name="theinput2" value="dummy">
</form>

<form name="theform2" flexy:ignore>
  <input name="theinput3" value="dummy">
  <input name="theinput4" value="dummy">
</form>

<form name="theform3">
  <input name="theinput5" value="dummy" flexy:ignore>
  <input name="theinput6" value="dummy">
</form>

<form name="theform4" flexy:ignoreonly="yes">
  <input name="theinput7" value="dummy">
  <input name="theinput8" value="dummy">
</form>

Compiled template

 <?php echo $this->elements['theform1']->toHtmlnoClose();?>
 <?php echo $this->elements['theinput1']->toHtml();?>
 <?php echo $this->elements['theinput2']->toHtml();?>
 </form>

<form name="theform2">
  <input name="theinput3" value="dummy">
  <input name="theinput4" value="dummy">
</form>

<?php echo $this->elements['theform3']->toHtmlnoClose();?>
  <input name="theinput5" value="dummy" flexy:ignore>
 <?php echo $this->elements['theinput6']->toHtml();?>
</form>

 <form name="theform4">
   <?php echo $this->elements['theinput7']->toHtml();?>
 <?php echo $this->elements['theinput8']->toHtml();?>
 </form>
Prev | HTML_Template_Flexy | Next
flexy:startchildren="here" | PEAR Manual | flexy:nameuses="variable"


flexy:nameuses="variable"

flexy:nameuses="variable"

flexy:nameuses="variable" – Use a variable in the name for a flexy form element

Synopsis

Usage ( flexy:nameuses="variable" name="sometag[%s]" )

Description

If you have a form with multiple input boxes (eg. group members), which are dynamically generated, then this attribute can be used to generate flexy elements based on sprintf'ing the variable value into the name attribute value.

Example

Template with flexy:ignore

<html>
  <head>
    <title>Example of name Uses</title>
  </head>
  <body>
    <form name="formtest">
      <span flexy:foreach="data,key,row">
        {key}: <input name="data%s" flexy:nameuses="key" type="hidden" size="10"><br>
      </span>
    </form>
  </body>
</html>

Backend Code Snippet

<?php
$this->data = array();
$elem = array();
$elem['formtest'] = &new HTML_Template_Flexy_Element();
$elem['formtest']->attributes['method'] = 'post';
$elem['formtest']->attributes['action'] = 'test';

for($i = 0; $i < 10; $i++) {
        $this->data[$i] = $i;

        $elem["data$i"] = new HTML_Template_Flexy_Element();
        $elem["data$i"]->attributes['type'] = 'text';
        $elem["data$i"]->attributes['size'] = $i;

}
$flexy->outputObject($this, $elem);

?>

Compiled template

<html>
  <head>
    <title>Example of name Uses</title>
  </head>
  <body>
    <?php echo $this->elements['formtest']->toHtmlnoClose();?>
<?php if ($this->options['strict'] || (is_array($t->data)  || is_object($t->data)))
foreach($t->data as $key => $row) {?>
      <?php echo htmlspecialchars($key);?>: <?php if (!isset($this->elements[sprintf('data%s',$key)])) $this->elements[sprintf('data%s',$key)]= $this->elements['data%s'];
                $this->elements[sprintf('data%s',$key)] = $this->mergeElement($this->elements['data%s'],$this->elements[sprintf('data%s',$key)]);
                $this->elements[sprintf('data%s',$key)]->attributes['name'] = sprintf('data%s',$key);
                echo $this->elements[sprintf('data%s',$key)]->toHtml();?><br>
<?php }?>
    </form>
  </body>
</html>

Resulting Output

 <html>
  <head>
    <title>test for PEAR bug#4683</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <form name="formtest" method="post" action="test">
      0: <input name="data0" type="text" size="0"><br>
      1: <input name="data1" type="text" size="1"><br>
      2: <input name="data2" type="text" size="2"><br>
      3: <input name="data3" type="text" size="3"><br>
      4: <input name="data4" type="text" size="4"><br>
      5: <input name="data5" type="text" size="5"><br>
      6: <input name="data6" type="text" size="6"><br>
      7: <input name="data7" type="text" size="7"><br>
      8: <input name="data8" type="text" size="8"><br>
      9: <input name="data9" type="text" size="9"><br>
    </form>
  </body>
</html>
Prev | HTML_Template_Flexy | Next
flexy:ignore="yes" | PEAR Manual | <FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ...


<FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ...

<FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ...

<FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ... – Provides a simple way to pass data from PHP to Javascript

Synopsis

Usage ( <flexy:tojavascript JSVAR="PHPVAR" ...> )

Description

To reduce the "WTF" effect of magically having javascript code that looks like flexy tags completely broken by the template engine, Flexy deliberately turns the parser OFF when dealing with script contents (see Configuration Options for details of PHP in script tags)

As a result of this, it is not possible to put any flexy tags within blocks of javascript code. the flexy:tojavascript tag solves this in a way that enables javascript to be tested seperatly from the application, and also serves to encourage better coding practices. (eg. seperating your code with distinct lines of communication)

This feature depends on PEAR's HTML_Javascript Library

Example

A template with javascript and flexy:tojavasscript

<?php
<html><head>
<title>Example</title>

<flexy:toJavascript
    flexy:prefix="test_abc_"
    abcg="xyz"
    abcd="xyz"
    srcXxx="xyz"
>
<!--

We can use the inner contents for testing the template in a browser.
The template will remove these contents when it is compiled.
-->
    <script type="text/javascript">

    var test_abc_abcg = '123';
    var test_abc_abcd = '123';
    var test_abc_srcXxx = '123';

    </script>

</flexy:toJavascript>

<flexy:toJavascript abcg="xyz">
    <script type="text/javascript">
    var xyz = '123';
    </script>
</flexy:toJavascript>

<body>
<p>Example of flexy:toJavascript with default values.</p>
</body></html>
?>

compiled template

<html><head>
<title>Example</title>

<?php require_once 'HTML/Javascript/Convert.php';?>
<script type='text/javascript'>
<?php $__tmp = HTML_Javascript_Convert::convertVar($t->xyz,'test_abc_abcg',true);
    echo (is_a($__tmp,"PEAR_Error")) ? ("<pre>".print_r($__tmp,true)."</pre>") : $__tmp;?>
<?php $__tmp = HTML_Javascript_Convert::convertVar($t->xyz,'test_abc_abcd',true);
    echo (is_a($__tmp,"PEAR_Error")) ? ("<pre>".print_r($__tmp,true)."</pre>") : $__tmp;?>
<?php $__tmp = HTML_Javascript_Convert::convertVar($t->xyz,'test_abc_srcXxx',true);
    echo (is_a($__tmp,"PEAR_Error")) ? ("<pre>".print_r($__tmp,true)."</pre>") : $__tmp;?>
</script>

?php require_once 'HTML/Javascript/Convert.php';?>
<script type='text/javascript'>
<?php $__tmp = HTML_Javascript_Convert::convertVar($t->xyz,'abcg',true);
    echo (is_a($__tmp,"PEAR_Error")) ? ("<pre>".print_r($__tmp,true)."</pre>") : $__tmp;?>
</script>

<body>
<p>Example of flexy:toJavascript with default values.</p>
</body></html>

output from the Template (with no values set)

<html><head>
<title>Example</title>

<script type='text/javascript'>
test_abc_abcg = null;
test_abc_abcd = null;
test_abc_srcXxx = null;
</script>

<script type='text/javascript'>
abcg = null;
</script>

<body>
<p>Example of flexy:toJavascript with default values.</p>
</body></html>
Prev | HTML_Template_Flexy | Next
flexy:nameuses="variable" | PEAR Manual | HTML_Template_IT


HTML_Template_IT

HTML_Template_IT

Table of Contents
  • Introduction -- Creating and Parsing templates
  • HTML_Template_IT::HTML_Template_IT() -- constructor
  • HTML_Template_IT::get() -- get a block including replacments
  • HTML_Template_IT::getGlobalvariables() -- returns an array of all global variables from the variable cache
  • HTML_Template_IT::loadTemplatefile() -- load a template file
  • HTML_Template_IT::parse() -- parse a block
  • HTML_Template_IT::parseCurrentBlock() -- parse the current block
  • HTML_Template_IT::setCurrentBlock() -- set the current block
  • HTML_Template_IT::setRoot() -- set the template root directory
  • HTML_Template_IT::setOption() -- sets an option
  • HTML_Template_IT::setTemplate() -- set a template
  • HTML_Template_IT::setVariable() -- set a variable
  • HTML_Template_IT::show() -- print a block including replacments
  • HTML_Template_IT::touchBlock() -- preserve empty block
Prev | HTML | Next
<FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ... | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Creating and Parsing templates

Templates

A template consists of text and special labeled blocks and placeholders. The content of blocks can be re-used and parsed multiple times with different placeholder values.

A typical template

<html>
 <body>
  Userlist
  <table>
<!-- BEGIN row -->
   <tr>
    <td>{USERNAME}</td>
    <td>{EMAIL}</td>
   </tr>
<!-- END row -->
  </table>
 </body>
</html>

Placeholder

Placeholders can be defined in templates and are filled from PHP code with content. The format of placeholder up to version (1.1.x) is

{[0-9A-Za-z_-]+}

Since version 1.2.x dots are allowed, too.

{[\.0-9A-Za-z_-]+}

This means, the name of the placeholder can consist of upper- and lowercase letters, underscores and hypens. The name must be placed between curly brackets without any spaces. Valid names are i.e.:

  • {Placeholder}
  • {place2_holder}
  • {PLACEHOLDER1}
  • {Place-Holder}

Valid names since version 1.2.x

  • {Place.Holder}

Non-valid names are i.e.

  • { Placeholder 3 } (spaces)
  • {place*holder} (char isn't permitted)

Blocks

The format of a block is

<!-- BEGIN [0-9A-Za-z_-]+ -->
... block content ...
<!-- END [0-9A-Za-z_-]+ -->

Since version 1.2.x dots are allowed in block definitions

<!-- BEGIN [\.0-9A-Za-z_-]+ -->
... block content ...
<!-- END [\.0-9A-Za-z_-]+ -->

The rules for the block name are the same like for placeholders. In contrast to placeholders the spaces in the block markup are required.

The nesting of blocks is permitted, but be careful while parsing. You have to set and parse the deepest inner block first and then set and parse from inner to outer.

In IT the whole template file itself is nested in a meta block called "__global__". Most block-related functions use this block name as default.

Usage Example

The template

<html>
<table border>
<!-- BEGIN row -->
<tr>
<!-- BEGIN cell -->
<td>
{DATA}
</td>
<!-- END cell -->
</tr>
<!-- END row -->
</table>
</html>

The script

<?php
  require_once "HTML/Template/IT.php";

  $data = array
  (
    "0" => array("Stig", "Bakken"),
    "1" => array("Martin", "Jansen"),
    "2" => array("Alexander", "Merz")
  );

  $tpl = new HTML_Template_IT("./templates");

  $tpl->loadTemplatefile("main.tpl.htm", true, true);

  foreach($data as $name) {
    foreach($name as $cell) {
        // Assign data to the inner block
        $tpl->setCurrentBlock("cell") ;
        $tpl->setVariable("DATA", $cell) ;
        $tpl->parseCurrentBlock("cell") ;
    }

     // parse outter block
     $tpl->parse("row");
  }
  // print the output
  $tpl->show();

?>

The output

<html>
<table border>
<tr>
<td>
Stig
</td>
<td>
Bakken
</td>
</tr>
<tr>
<td>
Martin
</td>
<td>
Jansen
</td>
</tr>
<tr>
<td>
Alexander
</td>
<td>
Merz
</td>
</tr>
</table>
</html>
Prev | HTML_Template_IT | Next
HTML_Template_IT | PEAR Manual | HTML_Template_IT::HTML_Template_IT()


HTML_Template_IT::HTML_Template_IT()

HTML_Template_IT::HTML_Template_IT()

HTML_Template_IT::HTML_Template_IT() – constructor

Synopsis

require_once 'HTML/Template/IT.php';

void HTML_Template_IT::HTML_Template_IT ( string $root = '.' )

Description

Constructor. Create a new instance of HTML_Template_IT and sets the search path for templates.

Parameter

  • string $root - path to the directory of the template files

Return value

object - a new HTML_Template_IT object

Note

This function can be called statically.

See

HTML_Template_IT::setRoot()

Prev | HTML_Template_IT | Next
Introduction | PEAR Manual | HTML_Template_IT::get()


HTML_Template_IT::get()

HTML_Template_IT::get()

HTML_Template_IT::get() – get a block including replacments

Synopsis

require_once 'HTML/Template/IT.php';

string HTML_Template_IT::get ( string $block = "__global__" )

Description

This functions return a block with all replacements done.

Parameter

  • string $block - The block to return. If not used, the whole template is returned.

Return value

string - the template with all replacements done.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
IT_BLOCK_NOT_FOUND | " Cannot find this block block " | The given block does not exists. | Check for typing mistakes in the argument.

Note

This function can not be called statically.

See

HTML_Template_IT::parse()

Prev | HTML_Template_IT | Next
HTML_Template_IT::HTML_Template_IT() | PEAR Manual | HTML_Template_IT::getGlobalvariables()


HTML_Template_IT::getGlobalvariables()

HTML_Template_IT::getGlobalvariables()

HTML_Template_IT::getGlobalvariables() – returns an array of all global variables from the variable cache

Synopsis

require_once 'HTML/Template/IT.php';

array HTML_Template_IT::getGlobalvariables ( )

Description

Gets an array of all global variables in the variable cache. Only variables that are filled using HTML_Template_IT::setVariable() are returned. The returned has two values. The first values holds an array with the names of the global variables, the second value holds an array with all the values.

Return value

array - An array. The key 0 holds an array with the names of all filled variables, the key 1 holds an array with names of the according values.

Example

Script

<?php

require_once("HTML/Template/IT.php");

$template = <<<EOF
<!-- BEGIN a -->
    Hello {username}
<!-- END a -->
Welcome to {page},
You are visitor number {visitorcount}.
EOF;

$tpl = new HTML_Template_IT('.');
$tpl->setTemplate($template);

// set the {page} variable. It will be returned by getGlobalvariables then.
$tpl->setVariable("page", "http://example.com");
$tpl->setVariable("username", "foo");

// getGlobalvariables won't return {username} as it is not a global variable
// It won't return {visitorcount} as it is not set
print_r($tpl->getGlobalvariables());

?>

The output

Array
(
[0] => Array
(
[0] => @{page}@
)

[1] => Array
(
[0] => http://example.com
)

)

Note

This function can not be called statically.

See

HTML_Template_IT::setVariable(),

Prev | HTML_Template_IT | Next
HTML_Template_IT::get() | PEAR Manual | HTML_Template_IT::loadTemplatefile()


HTML_Template_IT::loadTemplatefile()

HTML_Template_IT::loadTemplatefile()

HTML_Template_IT::loadTemplatefile() – load a template file

Synopsis

require_once 'HTML/Template/IT.php';

boolean HTML_Template_IT::loadTemplatefile ( string $filename , boolean $removeUnknownVariables = true , boolean $removeEmptyBlocks = true )

Description

Loads a template from a file and generates internal lists for blocks and variables.

Parameter

  • string $filename - file to load

  • boolean $removeUnknownVariables - if TRUE, not substituted placeholders in a block will be removed

  • boolean $removeEmptyBlocks - if TRUE, not touched blocks will be removed. Blocks can be touched with HTML_Template_IT::touchBlock().

Return value

boolean - Returns TRUE on success, FALSE on failure.

Example

Templatefile main.tpl.htm

<html>
 <body>
User {USERNAME} logged in successfull as {ROLE}.
 </body>
</html>

Script with $removeUnknownVariables = FALSE

<?php
require_once 'HTML/Template/IT.php';

$tpl = new HTML_Template_IT('.');
$tpl->loadTemplatefile ('main.tpl.htm', false, false);

$tpl->setVariable ('USERNAME', 'foo');
// Placeholder ROLE is not set
$tpl->show();
?>

Output

User foo logged in successfull as {ROLE}.

Script with $removeUnknownVariables = TRUE

<?php
require_once 'HTML/Template/IT.php';

$tpl = new HTML_Template_IT('.');
$tpl->loadTemplatefile ('main.tpl.htm', true, true);

$tpl->setVariable ('USERNAME', 'foo');
// Placeholder ROLE is not set, but $removeUnknownVariables is set to true.
$tpl->show();
?>

Output

User foo logged in successfull as .

Note

This function can not be called statically.

See

HTML_Template_IT::setTemplate()

Prev | HTML_Template_IT | Next
HTML_Template_IT::getGlobalvariables() | PEAR Manual | HTML_Template_IT::parse()


HTML_Template_IT::parse()

HTML_Template_IT::parse()

HTML_Template_IT::parse() – parse a block

Synopsis

require_once 'HTML/Template/IT.php';

void HTML_Template_IT::parse ( string $block = "__global__" , boolean $flag_recursion = false )

Description

Parses the defined block, performs all substitutions and appends the result to already parsed blocks.

Parameter

  • string $block - block to parse. When not set the complete template is used.

  • boolean $flag_recursion - Used internally. Can be ignored

Return value

boolean - Returns TRUE if there was no placeholder to substitute, otherwise FALSE or IT_Error.

Example

The template cvsnames.tpl.htm

<html>
 <table>
<!-- BEGIN row -->
  <tr>
   <td>
    {CVS_USERNAME}
   </td>
   <td>
    {REALNAME}
   </td>
  </tr>
<!-- END row -->
 </table>
</html>

The script

<?php
  require_once "HTML/Template/IT.php";

  $data = array
  (
    "0" => array("cvs_username" => "pajoye",
                 "realname" => "Pierre-Alain Joye"),
    "1" => array("cvs_username" => "dsp",
                 "realname" => "David Soria Parra")
  );

  $tpl = new HTML_Template_IT("./templates");

  $tpl->loadTemplatefile("cvsnames.tpl.htm", true, true);

  foreach($data as $name) {

     $tpl->setVariable("CVS_USERNAME", $name["cvs_username"]);
     $tpl->setVariable("REALNAME", $name["realname"]);

     $tpl->parse("row");
  }

  // show() parses the __global__ block and
  // print the output
  $tpl->show();

?>

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
IT_BLOCK_NOT_FOUND | " Cannot find this block block " | The given block does not exists. | Check for typing mistakes in the argument.

Note

This function can not be called statically.

See

HTML_Template_it::parseCurrentBlock()

Prev | HTML_Template_IT | Next
HTML_Template_IT::loadTemplatefile() | PEAR Manual | HTML_Template_IT::parseCurrentBlock()


HTML_Template_IT::parseCurrentBlock()

HTML_Template_IT::parseCurrentBlock()

HTML_Template_IT::parseCurrentBlock() – parse the current block

Synopsis

require_once 'HTML/Template/IT.php';

void HTML_Template_IT::parseCurrentBlock ( )

Description

Parses the current block. The current block can be set with HTML_Template_IT::setCurrentBlock().

Return value

boolean - Returns TRUE if there was no placeholder to substitute, otherwise FALSE or IT_Error.

Example

The template cvsnames.tpl.htm

<html>
 <table>
<!-- BEGIN row -->
  <tr>
   <td>
    {CVS_USERNAME}
   </td>
   <td>
    {REALNAME}
   </td>
  </tr>
<!-- END row -->
 </table>
</html>

Script

<?php
  require_once "HTML/Template/IT.php";

  $data = array
  (
    "0" => array("cvs_username" => "pajoye",
                 "realname" => "Pierre-Alain Joye"),
    "1" => array("cvs_username" => "dsp",
                 "realname" => "David Soria Parra")
  );

  $tpl = new HTML_Template_IT("./templates");

  $tpl->loadTemplatefile("cvsnames.tpl.htm", true, true);

  // set the current block, which can now be used with parseCurrentBlock()
  $tpl->setCurrentBlock("row");
  foreach($data as $name) {
     // Assign data to the inner block

     $tpl->setVariable("CVS_USERNAME", $name["cvs_username"]);
     $tpl->setVariable("REALNAME", $name["realname"]);

     // parse the current set block
     $tpl->parseCurrentBlock();
  }

  // show() parses the __global__ block and
  // print the output
  $tpl->show();

?>

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
IT_BLOCK_NOT_FOUND | " Cannot find this block block " | The given block does not exists. | Check for typing mistakes in the argument.

Note

This function can not be called statically.

See

HTML_Template_it::parse(), HTML_Template_it::setCurrentBlock()

Prev | HTML_Template_IT | Next
HTML_Template_IT::parse() | PEAR Manual | HTML_Template_IT::setCurrentBlock()


HTML_Template_IT::setCurrentBlock()

HTML_Template_IT::setCurrentBlock()

HTML_Template_IT::setCurrentBlock() – set the current block

Synopsis

require_once 'HTML/Template/IT.php';

boolean HTML_Template_IT::setCurrentBlock ( string $block = "__global__" )

Description

Sets the name of the current block, where placeholder should be substituted. The current block can be parsed with HTML_Template_IT::parseCurrentTemplate().

Parameter

  • string $block - block to set, if not given, the complete template is set

Return value

boolean - TRUE, if found and succcessful set, otherwise IT_Error will be returned.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
IT_BLOCK_NOT_FOUND | " Cannot find this block block " | The given block does not exists. | Check for typing mistakes in the argument.

Note

This function can not be called statically.

See

HTML_Template_it::parseCurrentBlock(),

Prev | HTML_Template_IT | Next
HTML_Template_IT::parseCurrentBlock() | PEAR Manual | HTML_Template_IT::setRoot()


HTML_Template_IT::setRoot()

HTML_Template_IT::setRoot()

HTML_Template_IT::setRoot() – set the template root directory

Synopsis

require_once 'HTML/Template/IT.php';

void HTML_Template_IT::setRoot ( string $root )

Description

Sets the path to the template directory where HTML_Template_IT::loadTemplatefile() searches for templates. Every filename is prefixed with the given string.

Parameter

  • string $root - Path to the template directory.

Example

Directorytree.

./
./testscript.php
./templates/design01/main.tpl.htm
./templates/design01/table.tpl.htm
./templates/design02/main.tpl.htm
./templates/design02/table.tpl.htm

script - testscript.php

<?php
  /*
   * testscipt.php - sets a random design
   */

  require_once "HTML/Template/IT.php";

  $tpl = new HTML_Template_IT();

  $randomNumber = (int) round(rand(0,1));
  switch ($randomNumber)
  {
     case 0:
         // Set root to design01 so the called main.tpl.htm is searched there
         $tpl->setRoot("./templates/design01");
         break;
     case 1:
     default:
         // Set root to design02 so the called main.tpl.htm is searched there
         $tpl->setRoot("./templates/design02");
         break;
  }

  /* Loads either ./templates/design01/main.tpl.htm
   * or ./templates/design02/main.tpl.htm depending on the root directory set
   * with setRoot in the switch */
  $tpl->loadTemplatefile("main.tpl.htm", true, true);

  /* ... assign variables .. */

  // show
  $tpl->show();

?>

Note

This function can not be called statically.

See

HTML_Template_IT::HTML_Template_IT(), HTML_Template_IT::loadTemplatefile()

Prev | HTML_Template_IT | Next
HTML_Template_IT::setCurrentBlock() | PEAR Manual | HTML_Template_IT::setOption()


HTML_Template_IT::setOption()

HTML_Template_IT::setOption()

HTML_Template_IT::setOption() – sets an option

Synopsis

require_once 'HTML/Template/IT.php';

int HTML_Template_IT::setOption ( string $option , mixed $value )

Description

Sets an option. Please notice that changing some option might result in an unexpected behaviour of HTML_Template_IT.

Return value

int - Returns 1 on success, otherwise an IT_Error object.

Parameter

  • mixed $option - Option identifier

  • mixed $value - New value of the option

Options

Note: Currently setOption allows to set only two options. Instead of using this method, access the properties directly on the template object.
Possible options:
Option | Default value | Description
removeUnknownVariables | TRUE | If TRUE all template variables, which are not filled, are removed while parsing. This option is usually set by calling HTML_Template_IT::loadTemplatefile() or HTML_Template_IT::setTemplate().
removeEmptyBlocks | TRUE | If TRUE all blocks not containing any filled template variables are removed. This option is usually set by calling HTML_Template_IT::loadTemplatefile() or HTML_Template_IT::setTemplate().
clearCache | FALSE | If TRUE parsed blocks are not cached. If you don't know exactly what you do, just leave the default value.
clearCacheOnParse | FALSE | If TRUE the variable cache will be cleaned after parsing. If you don't know exactly what you do, just leave the default value.
openingDelimiter | '{' | Defines the character, every template variable has to start with. If you change this value, you have to call init() to reinitialise the template. If you don't know exactly what you do, just leave the default value.
closingDelimiter | '}' | Defines the character, every template variable has to end with. If you change this value, you have to call init() to reinitialise the template. If you don't know exactly what you do, just leave the default value.
blocknameRegExp | '[\.0-9A-Za-z_-]+' | The regular expression, thats used to parse block names. If you change this value, you have to call init() to reinitialise the template. If you don't know exactly what you do, just leave the default value.
variablenameRegExp | '[\.0-9A-Za-z_-]+' | The regular expression, thats used to parse template variable names. If you change this value, you have to call init() to reinitialise the template. If you don't know exactly what you do, just leave the default value.

Note

This function can not be called statically.

See

HTML_Template_IT::loadTemplatefile()

HTML_Template_IT::setTemplate()

Prev | HTML_Template_IT | Next
HTML_Template_IT::setRoot() | PEAR Manual | HTML_Template_IT::setTemplate()


HTML_Template_IT::setTemplate()

HTML_Template_IT::setTemplate()

HTML_Template_IT::setTemplate() – set a template

Synopsis

require_once 'HTML/Template/IT.php';

boolean HTML_Template_IT::setTemplate ( string $template , boolean $removeUnkownVariables = true , boolean $removeEmptyBlocks = true )

Description

Loads template from a string and controls the behavior in case of unused variables and blocks

Parameter

  • string $template - The content of the template.

  • boolean $removeUnknowVariables - if TRUE, not substituted placeholders in a block will be removed

  • boolean $removeEmptyBlocks - if TRUE, not touched blocks will be removed

Return value

boolean - Returns TRUE on success, FALSE on failure.

Example

Script

<?php
  require_once "HTML/Template/IT.php";

  $data = array
  (
    "0" => array("Stig", "Bakken"),
    "1" => array("Martin", "Jansen"),
    "2" => array("Alexander", "Merz")
  );

  $templateString = <<<EOD
<html>
 <table>
<!-- BEGIN row -->
  <tr>
<!-- BEGIN cell -->
   <td>
    {DATA}
   </td>
<!-- END cell -->
  </tr>
<!-- END row -->
 </table>
</html>
EOD;

  $tpl = new HTML_Template_IT();
  $tpl->setTemplate($templateString, true, true);

  foreach($data as $name) {
    foreach($name as $cell) {
        // Assign data to the inner block
        $tpl->setCurrentBlock("cell") ;
        $tpl->setVariable("DATA", $cell) ;
        $tpl->parseCurrentBlock("cell") ;
    }

     // parse outter block
     $tpl->parse("row");
  }
  // show
  $tpl->show();

?>

Note

This function can not be called statically.

See

HTML_Template_IT::loadTemplatefile()

Prev | HTML_Template_IT | Next
HTML_Template_IT::setOption() | PEAR Manual | HTML_Template_IT::setVariable()


HTML_Template_IT::setVariable()

HTML_Template_IT::setVariable()

HTML_Template_IT::setVariable() – set a variable

Synopsis

require_once 'HTML/Template/IT.php';

void HTML_Template_IT::setVariable ( mixed $placeholder , mixed $variable = "" )

Description

Set the value of a variable in the current template block. If $placeholder is an array, the key of an element is treated as a placeholder name while the value is treated as its substitution.

Parameter

  • mixed $placeholder - name of the placeholder to substitute or a array with the placeholder as key and the data to assign as value.

  • mixed $variable - if $placeholder is not a array, the value to assign to the placeholder.

Example

Template - cvsnames.tpl.htm

<html>
 <table>
<!-- BEGIN row -->
  <tr>
   <td>
    {CVS_USERNAME}
   </td>
   <td>
    {REALNAME}
   </td>
   <td>
    <ul>
    <!-- BEGIN project_row -->
     <li>{PROJECT}</li>
    <!-- END project_row -->
    </ul>
   </td>
  </tr>
<!-- END row -->
 </table>
</html>

Script

<?php
  require_once "HTML/Template/IT.php";

  $data = array
  (
    "0" => array("cvs_username" => "pajoye",
                 "realname" => "Pierre-Alain Joye",
                 "projects" => array("PEAR",
                                     "PEAR_Frontend_Web",
                                     "PEAR_RemoteInstaller",
                                      "HTML_Template_IT")),
    "1" => array("cvs_username" => "dsp",
                 "realname" => "David Soria Parra",
                 "projects" => array("HTML_Template_IT"))
  );

  $tpl = new HTML_Template_IT("./templates");

  $tpl->loadTemplatefile("cvsnames.tpl.htm", true, true);

  foreach($data as $name) {
     // Assign data to the inner block

     $tpl->setCurrentBlock("project_row");
     foreach ($name['projects'] as $projectname) {
         $tpl->setVariable("PROJECT", $projectname);
         $tpl->parseCurrentBlock();
     }

     // use the possbility to set the placeholders using an assoc array
     $tpl->setVariable(
                      array("CVS_USERNAME" => $name["cvs_username"],
                            "REALNAME" => $name["realname"])
                      );

     $tpl->parse("row");
  }

  // show() parses the __global__ block and
  // print the output
  $tpl->show();

?>

Note

This function can not be called statically.

See

HTML_Template_IT::parse()

Prev | HTML_Template_IT | Next
HTML_Template_IT::setTemplate() | PEAR Manual | HTML_Template_IT::show()


HTML_Template_IT::show()

HTML_Template_IT::show()

HTML_Template_IT::show() – print a block including replacments

Synopsis

require_once 'HTML/Template/IT.php';

void HTML_Template_IT::show ( string $block )

Description

This functions prints a block with all replacements done.

Parameter

  • string $block - The block to return. If not used, the whole template is returned.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
IT_BLOCK_NOT_FOUND | " Cannot find this block block " | The given block does not exists. | Check for typing mistakes in the argument.

Note

This function can not be called statically.

See

HTML_Template_IT::get()

Prev | HTML_Template_IT | Next
HTML_Template_IT::setVariable() | PEAR Manual | HTML_Template_IT::touchBlock()


HTML_Template_IT::touchBlock()

HTML_Template_IT::touchBlock()

HTML_Template_IT::touchBlock() – preserve empty block

Synopsis

require_once 'HTML/Template/IT.php';

boolean HTML_Template_IT::touchBlock ( string $block )

Description

Preserves an empty template block, even if $removeEmptyBlocks is TRUE and no substition of placeholders took place.

Parameter

  • string $block - block to preserve

Return value

boolean - TRUE, if block was found, otherwise IT_Error.

Example

Template - login.tpl.htm

<html>
<body>
<!-- BEGIN login_successfull -->
You have logged in successfully!
<!-- END login_successfull -->
<!-- BEGIN login_failed -->
Login failed
<!-- END login_failed -->
</body>
</html>

Script

<?php
  require_once "HTML/Template/IT.php";

  // Remove blocks with no placeholders, or no placeholders set ($removeEmptyBlocks=true)
  $tpl->loadTemplatefile("login.tpl.htm", true, true);

  // hypothetical
  if (login_successfull($username, $password)) {
    // print login_successfull block.
    // login_failed is removed, due to $removeEmptyBlocks = true
    $tpl->touchBlock("login_successfull");
  } else {
    $tpl->touchBlock("login_failed");
  }

  $tpl->show();

?>

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
IT_BLOCK_NOT_FOUND | " Cannot find this block block " | The given block does not exists. | Check for typing mistakes in the argument.

Note

This function can not be called statically.

Prev | HTML_Template_IT | Next
HTML_Template_IT::show() | PEAR Manual | HTML_Template_PHPLIB


HTML_Template_PHPLIB

HTML_Template_PHPLIB

HTML_Template_PHPLIB is the PEARified version of the once-so-famous PHPLIB template class. It provides variables and repeatable blocks. The original PHPLIB code can be found at phplib.sf.net.

Table of Contents
  • Concept
  • Simple example
  • Loading files
  • Defining blocks
  • Setting variables
  • Parsing blocks
  • Finish & output
Prev | HTML | Next
HTML_Template_IT::touchBlock() | PEAR Manual | Concept


Concept

Concept

When using HTML_Template_PHPLIB to generate HTML or other code from templates, you do the following steps:

  1. Create template class instance

  2. Load template file

  3. Define blocks

  4. Set variables, parse blocks

  5. Finish and output

Variables are placeholders in your HTML code that can be replaced with dynamic values provided from database or calculated in your code. An example for a variable is {CODE_AUTHOR}: You enclose the variable name in curly braces. The name of the variable may contain any characters, except spaces, tabs and newlines.

Blocks surround certain pieces of HTML code and can be re-used, e.g. a <tr>row in a table. Blocks are defined by using HTML comments, containing BEGIN or END, and the block name. Example:

<table>
 <caption>Authors</caption>
 <thead>
  <tr><th>Name</th><th>Email</th></tr>
 </thead>
 <tbody>
<!-- BEGIN authorline -->
  <tr><td>{AUTHOR_NAME}</td><td>{AUTHOR_EMAIL}</td></tr>
<!-- END authorline -->
 </tbody>
</table>
Prev | HTML_Template_PHPLIB | Next
HTML_Template_PHPLIB | PEAR Manual | Simple example


Simple example

Simple example

Template file: authors.tpl

<html>
 <head><title>{PAGE_TITLE}</title></head>
 <body>
  <table>
   <caption>Authors</caption>
   <thead>
    <tr><th>Name</th><th>Email</th></tr>
   </thead>
   <tfoot>
    <tr><td colspan="2">{NUM_AUTHORS}</td></tr>
   </tfoot>
   <tbody>
<!-- BEGIN authorline -->
    <tr><td>{AUTHOR_NAME}</td><td>{AUTHOR_EMAIL}</td></tr>
<!-- END authorline -->
   </tbody>
  </table>
 </body>
</html>

PHP code: authors.php

<?php
//we want to display this author list
$authors = array(
    'Christian Weiske'  => 'cweiske@php.net',
    'Bjoern Schotte'     => 'schotte@mayflower.de'
);

require_once 'HTML/Template/PHPLIB.php';
//create template object
$t =& new HTML_Template_PHPLIB(dirname(__FILE__), 'keep');
//load file
$t->setFile('authors', 'authors.tpl');
//set block
$t->setBlock('authors', 'authorline', 'authorline_ref');

//set some variables
$t->setVar('NUM_AUTHORS', count($authors));
$t->setVar('PAGE_TITLE', 'Code authors as of ' . date('Y-m-d'));

//display the authors
foreach ($authors as $name => $email) {
    $t->setVar('AUTHOR_NAME', $name);
    $t->setVar('AUTHOR_EMAIL', $email);
    $t->parse('authorline_ref', 'authorline', true);
}

//finish and echo
echo $t->finish($t->parse('OUT', 'authors'));
?>
Prev | HTML_Template_PHPLIB | Next
Concept | PEAR Manual | Loading files


Loading files

Loading files

Template file locations are relative to a definable root directory. You can specify it directly in the constructor (first parameter, defaults to .) or via setRoot().

Files are referenced via handle names. Thus you need to specify the handle name as first parameter, and the file's name as second parameter when calling setFile(). To speed things up, you may pass an array of handle-filename pairs to the method.

Loading a template file

<?php
$t =& new HTML_Template_PHPLIB(dirname(__FILE__), 'keep');
$t->setFile('authors', 'authors.tpl');
?>
Prev | HTML_Template_PHPLIB | Next
Simple example | PEAR Manual | Defining blocks


Defining blocks

Defining blocks

If you want to re-use certains parts of your HTML code multiple times, e.g. rows in a table, you can define blocks as described in the example above.

Blocks are not automatically detected, they need to be defined explicitely via the setBlock() method. The method takes the handle of the file in which the block is located as first parameter, the name of the block as written in the file as second and the new block handle as third parameter.

Defining a block

<?php
$t->setBlock('authors', 'authorline', 'authorline_ref');
?>

In the example template (available as handle authors), a block named authorline is defined. The handle of the block is now authorline_ref.

Prev | HTML_Template_PHPLIB | Next
Loading files | PEAR Manual | Setting variables


Setting variables

Setting variables

This is the most easy part: Just use setVar() with the variable name and its new value. An optional third boolean parameter tells if the value should be appended to the existing value (defaults to false).

Setting a variable

<?php
$t->setVar('AUTHOR_NAME', 'Christian Weiske');
?>

Variables set influence all variables in the template, no matter if they are defined within a block or not.

Prev | HTML_Template_PHPLIB | Next
Defining blocks | PEAR Manual | Parsing blocks


Parsing blocks

Parsing blocks

Once you filled all variables in a block, you want to "save" them to be able to re-use the block another time. Method parse() is useful here. First parameter is the variable/handle in which the block content shall be stored, second is the handle name of the block. The optional third parameter tells if you want to append the block content to the handle value or not - it defaults to false, but you probably want to do that.

Parsing a block

<?php
foreach ($authors as $name => $email) {
    $t->setVar('AUTHOR_NAME', $name);
    $t->setVar('AUTHOR_EMAIL', $email);
    $t->parse('authorline_ref', 'authorline', true);
}
?>

In this example, handle authorline_ref is filled with the contents of block authorline. If the third parameter would be false instead of true, only the last line would be in it at the end.

Prev | HTML_Template_PHPLIB | Next
Setting variables | PEAR Manual | Finish & output


Finish & output

Finish & output

When you're done with setting variables and parsing your blocks, it's time to write the contents to your client. At first, you need to parse() the contents of the file handle into a new handle.

To remove all unused variables and blocks, you might want to call finish(). Depending on the value set for unknowns (as second paramter in the constructor, or via setUnknowns()), unused variables are either erased (remove), kept (keep) or commented out (comment).

To echo your HTML, either directly use the return value of finish(), or use get() to retrieve the content.

Finishing a file and writing it out

<?php
$t->parse('OUT', 'authors');
$htmlcode = $t->finish(
    $tpl->get('OUT')
);
echo $htmlcode;
?>

Finishing a file and writing it out, the easy way

<?php
echo $tpl->finish($t->parse('OUT', 'authors'));
?>
Prev | HTML_Template_PHPLIB | Next
Parsing blocks | PEAR Manual | HTML_Template_Sigma


HTML_Template_Sigma

HTML_Template_Sigma

HTML_Template_Sigma: implementation of Integrated Templates API with template 'compilation' added.

Class Trees for HTML_Template_Sigma()

  • PEAR

    • HTML_Template_Sigma

Table of Contents
  • Introduction - template syntax -- Creating and editing templates
  • Introduction - cache -- How Sigma caches the "prepared" templates
  • constructor HTML_Template_Sigma() -- constructor
  • addBlock() -- Adds a block to the template
  • addBlockfile() -- Adds a block contained in the file to the template
  • blockExists() -- Checks if the block exists in the template
  • clearVariables() -- Clears the variables
  • errorMessage() -- Returns a textual error message for an error code
  • get() -- Returns a block with all replacements done.
  • getBlockList() -- Returns a list of blocks within a template.
  • getCurrentBlock() -- Returns the current block name
  • getPlaceholderList() -- Returns a list of placeholders within a block.
  • hideBlock() -- Hides the block even if it is not "empty".
  • loadTemplateFile() -- Loads a template file.
  • parse() -- Parses the given block.
  • parseCurrentBlock() -- Parses the current block
  • placeholderExists() -- Checks whether the placeholder exists
  • replaceBlock() -- Replaces an existing block with new content.
  • replaceBlockfile() -- Replaces an existing block with new content from a file.
  • setCacheRoot() -- Sets the directory to cache "prepared" templates in.
  • setCallbackFunction() -- Sets a callback function.
  • setCurrentBlock() -- Sets the name of the current block.
  • setGlobalVariable() -- Sets a global variable value.
  • setOption() -- Sets the option for the template class
  • setRoot() -- Sets the file root for templates.
  • setTemplate() -- Sets the template.
  • setVariable() -- Sets a variable value.
  • show() -- Prints a block with all replacements done.
  • touchBlock() -- Preserves the block even if empty blocks should be removed.
Prev | HTML | Next
Finish & output | PEAR Manual | Introduction - template syntax


Introduction - template syntax

Introduction - template syntax

Introduction - template syntax – Creating and editing templates

Placeholders

The default format of placeholder is

{[0-9A-Za-z_-]+}

This means, the name of the placeholder can consist of upper- and lowercase letters, numbers, underscores and hyphens. The name must be placed between curly brackets without any spaces.

Actual values for the placeholders are set using setVariable() and setGlobalVariable() methods. Placeholders for which no values were set are removed from output by default.

Blocks

The format of a block is

<!-- BEGIN [0-9A-Za-z_-]+ -->
... block content ...
<!-- END [0-9A-Za-z_-]+ -->

The rules for the block name are the same like for placeholders. In contrast to placeholders the spaces in the block markup are required.

The nesting of blocks is permitted, but be careful while parsing. You have to parse() the innermost block first and then go from inner to outer.

In Sigma the whole template itself is treated as a virtual block called "__global__". Most block-related functions use this block name as default.

<!-- INCLUDE --> statements

It is possible to include a template file from within another template file using an <!-- INCLUDE filename --> statement:

... some content ...
<!-- INCLUDE filename.html -->
... some more content ...

When such a template file gets loaded, the <!-- INCLUDE filename.html --> will be replaced by contents of filename.html.

Some things to note:

  • <!-- INCLUDE --> statements are only processed when loading the template files from disk. If you use setTemplate() method to set the template or addBlock() and replaceBlock() to work with its blocks, then <!-- INCLUDE --> statements in these templates will not be replaced!

  • Although this functionality is implemented using addBlockfile(), unlike addBlockfile() no new blocks are created in the template.

  • <!-- INCLUDE --> statements are processed before any variable substitution can take place. So <!-- INCLUDE {placeholder} --> will not work unless you actually have a file named {placeholder} and want to load it.

Template functions

Sigma templates can contain simple function calls. This means that the author of the template can add a special placeholder to it

... some content ...
func_h1("embedded in h1")
... some more content ...

Sigma will parse the template for these placeholders and will allow you to define a callback function for them via setCallbackFunction(). Callback will be called automatically when the block containing such function call is parse()'d.

Format of such function name is as follows

func_[_a-zA-Z]+[A-Za-z_0-9]*

that means that it should start with a 'func_' prefix, then has a letter or an undercore and then a sequence of letters, digits or underscores. Arguments to these template functions can contain variable placeholders

func_translate('Hello, {username}')

but not blocks or other function calls.

Quoting of template function arguments

Note: The information in this section applies to HTML_Template_Sigma version 1.1.2 and later, please upgrade if you have problems with template function arguments in previous versions.

Quoting of function arguments is not mandatory, the following is a perfectly valid template function:

func_uppercase(Some unquoted text)

But consider the following: function arguments are contained within parentheses and separated by commas. Therefore if closing parenthesis ')' or comma ',' appears in function argument, it should be quoted.

The next thing to consider is that HTML_Template_Sigma is mostly targeted for generating HTML. Therefore a quoted string within an argument is most probably a tag attribute. The contents of such strings are not parsed for commas and parentheses. Therefore the following is also a perfectly valid template function:

func_foo(<a href="javascript:foo(bar, baz)">Do foo</a>)

But if you have an unmatched single or double quote in your argument or if the argument starts with a quote, it should be quoted.

Finally, the argument should be quoted if it is an empty string or if its leading or trailing whitespace is significant (leading and trailing whitespace will be removed from unquoted arguments).

The arguments can be quoted using either single or double quotes. If an argument contains a quote of the same type, then it should be escaped using the backslash symbol '\'. The backslash symbol itself should also be escaped,

func_foo('O\'really')
func_foo('AC\\DC')

will pass O'really and AC\DC to the relevant callbacks.

Valid and invalid template function arguments

Valid arguments:
func_foo(Some unquoted text)
func_foo("Some quoted text")
func_foo(<a href="javascript:foo(bar, baz)">Do foo</a>)
func_foo('O\'really')
func_foo('AC\\DC')

Invalid arguments:
func_foo(Hello, {username}) contains a comma, will yield two arguments instead of one
func_foo(O'really) unmatched single quote
func_foo('O'really') unescaped single quote
func_foo(, 'whatever') empty arguments should be quoted

Shorthand for template functions

Since release 1.1.0, instead of using

func_callback({var})

you can write

{var:callback}

There are 3 automatically registered template functions

  • 'h' for htmlspecialchars()

  • 'e' for htmlentities() (available since release 1.2.0)

  • 'u' for urlencode()

  • 'r' for rawurlencode() (available since release 1.2.0)

  • 'j' for a method of Sigma that escapes the string for usage in Javascript string constants.

Thus, if you add {var:h} placeholder to the template, var will be have unsafe characters replaced by corresponding HTML entitites.

Since release 1.2.0 it is possible to provide the charset parameter for 'h' and 'e' callbacks via setOption().

Template comments

Since release 1.2.0 it is possible to add comments to the template file:

<!-- COMMENT -->
Some text here
<!-- /COMMENT -->

These comments will be removed from the output, unlike standard HTML comments.

Usage Example

Note: Other usage examples
 There are several usage examples in the package archive that cover most of its functionality. You are encouraged to review them along with the docs.

The table.html template file

<html>
<body>
<table cellpadding="2" cellspacing="0" border="1">
<!-- INCLUDE table_header.html -->
<!-- BEGIN table_row -->
<tr>
<td bgcolor="func_bgcolor('#CCCCCC', '#F0F0F0')">{first_name}</td>
<td bgcolor="func_bgcolor('#CCCCCC', '#F0F0F0')">{last_name}</td>
</tr>
<!-- END table_row -->
</table>
</body>
</html>

The table_header.html template file

<!-- COMMENT -->
This text will not appear in output.
<!-- /COMMENT -->
<tr>
<th>First name</th>
<th>Last name</th>
</tr>

The script

<?php

require_once 'HTML/Template/Sigma.php';

function toggle($item1, $item2)
{
    static $i = 1;

    return $i++ % 2? $item1: $item2;
}

$data = array (
    array("Stig", "Bakken"),
    array("Martin", "Jansen"),
    array("Alexander", "Merz")
);

$tpl =& new HTML_Template_Sigma('.');

$tpl->loadTemplateFile('table.html');

$tpl->setCallbackFunction('bgcolor', 'toggle');

foreach ($data as $name) {
    // assign data
    $tpl->setVariable(array(
        'first_name'  => $name[0],
        'last_name' => $name[1]
    ));
    // process the block
    $tpl->parse('table_row');
}

// print out the output
$tpl->show();
?>

The output

<html>
<body>
<table cellpadding="2" cellspacing="0" border="1">
<tr>
<th>First name</th>
<th>Last name</th>
</tr>

<tr>
<td bgcolor="#CCCCCC">Stig</td>
<td bgcolor="#CCCCCC">Bakken</td>
</tr>

<tr>
<td bgcolor="#F0F0F0">Martin</td>
<td bgcolor="#F0F0F0">Jansen</td>
</tr>

<tr>
<td bgcolor="#CCCCCC">Alexander</td>
<td bgcolor="#CCCCCC">Merz</td>
</tr>

</table>
</body>
</html>
Prev | HTML_Template_Sigma | Next
HTML_Template_Sigma | PEAR Manual | Introduction - cache


Introduction - cache

Introduction - cache

Introduction - cache – How Sigma caches the "prepared" templates

Cache FAQ

  1. What exactly is this cache feature?
  2. What about data?
  3. Is the cached version regenerated when the template changes?
  4. Is there any TTL setting?
  5. Any way to flush the cache?
  6. Does this give significant performance gains?
What exactly is this cache feature?

This is the way to bypass RegExp parsing on template load. Instead of parsing the original template on every request, we keep its internal representation (a serialized array, essentially) and load it instead.

Think about template compilation in Smarty. Only Sigma does not compile templates to PHP code.

What about data?

No data caching is taking place. If you want to do this, consider using some of the PEAR's cache packages.

Is the cached version regenerated when the template changes?

Yes.

Is there any TTL setting?

No. Cached version is considered valid until the source template changes.

Any way to flush the cache?

Yes, just delete all the files in the cache dir.

Does this give significant performance gains?

Yes. The answer is based on personal experience.

If you are going to perform some benchmarks, then use some real-world complex templates, not artificial ones. The performance gain will be greater with bigger and more complex (dozens of blocks) ones.

Cache usage

Caching is completely transparent. To take advantage of this feature you only have to either pass a second parameter to the constructor or call a setCacheRoot() method later.

<?php
require_once 'HTML/Template/Sigma.php';

$tpl =& new HTML_Template_Sigma('./templates', './templates/prepared');

$tpl->loadTemplateFile('default.html');

// go on

?>

For each distinct template file in ./templates loaded with either loadTemplatefile(), addBlockfile(), replaceBlockfile() or <!-- INCLUDE --> a prepared version will be generated in ./templates/prepared.

Prev | HTML_Template_Sigma | Next
Introduction - template syntax | PEAR Manual | constructor HTML_Template_Sigma()


constructor HTML_Template_Sigma()

constructor HTML_Template_Sigma()

constructor HTML_Template_Sigma() – constructor

Synopsis

require_once 'HTML/Template/Sigma.php';

 void HTML_Template_Sigma::HTML_Template_Sigma (
 string  $root = ''
  , string  $cacheRoot = ''
)

Description

Constructor: builds some complex regular expressions and optionally sets the root directories.

Make sure that you call this constructor if you derive your template class from this one.

Parameter

string $root

root directory for templates

string $cacheRoot

directory to cache "prepared" templates in

Throws

throws no exceptions thrown

See

see HTML_Template_Sigma::setRoot(), HTML_Template_Sigma::setCacheRoot()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
Introduction - cache | PEAR Manual | addBlock()


addBlock()

addBlock()

addBlock() – Adds a block to the template

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::addBlock ( string $placeholder , string $block , string $template )

Description

Adds a block to the template changing a variable placeholder to a block placeholder. This means that a new block will be integrated into the template in place of a variable placeholder. The variable placeholder will be removed and the new block will behave in the same way as if it was inside the original template.

The block content must not start with <!-- BEGIN blockname --> and end with <!-- END blockname -->, if it does the error will be thrown.

Parameter

string $placeholder

name of the variable placeholder, the name must be unique within the template.

string $block

name of the block to be added

string $template

content of the block

Return value

return SIGMA_OK on success, error object on failure

See

see HTML_Template_Sigma::addBlockfile()

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_EXISTS | Block '$block ' already exists | Tried to add a block with a name that is already present in the template | Choose a different name for a new block
SIGMA_PLACEHOLDER_NOT_FOUND | Variable placeholder '$placeholder ' not found | There is no placeholder to replace by a new block in the template | Check the spelling of the placeholder name
SIGMA_PLACEHOLDER_DUPLICATE | Placeholder '$placeholder ' should be unique, found in multiple blocks | A placeholder to be replaced by a new block should appear only in one place | Check the spelling of the placeholder name, choose a different placeholder
SIGMA_BLOCK_DUPLICATE | The name of a block must be unique within a template. Block 'blockname' found twice. | The added block contains a subblock that has the same name as the existing one | Check the $template and rename the block to something else
SIGMA_CALLBACK_SYNTAX_ERROR | Cannot parse template function: (error description) | Bogus syntax for template function parameters. | Fix the template function definition, pay special attention to quoting rules.

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
constructor HTML_Template_Sigma() | PEAR Manual | addBlockfile()


addBlockfile()

addBlockfile()

addBlockfile() – Adds a block contained in the file to the template

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::addBlockfile ( string $placeholder , string $block , string $filename )

Description

Adds a block taken from a file to the template, changing a variable placeholder to a block placeholder.

Parameter

string $placeholder

name of the variable placeholder

string $block

name of the block to be added

string $filename

template file that contains the block

Return value

return SIGMA_OK on success, error object on failure

See

see HTML_Template_Sigma::addBlock()

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_EXISTS | Block '$block ' already exists | Tried to add a block with a name that is already present in the template | Choose a different name for a new block
SIGMA_PLACEHOLDER_NOT_FOUND | Variable placeholder '$placeholder ' not found | There is no placeholder to replace by a new block in the template | Check the spelling of the placeholder name
SIGMA_PLACEHOLDER_DUPLICATE | Placeholder '$placeholder ' should be unique, found in multiple blocks | A placeholder to be replaced by a new block should appear only in one place | Check the spelling of the placeholder name, choose a different placeholder
SIGMA_TPL_NOT_FOUND | Cannot read the template file '$filename ' | File is unreadable for some reason | Check if the file exists and has correct permissions set
SIGMA_CACHE_ERROR | Cannot save template file 'filename' | A prepared template file cannot be saved | Check if the directory for prepared templates cache exists and is writeable for your script
SIGMA_BLOCK_DUPLICATE | The name of a block must be unique within a template. Block 'blockname' found twice. | The added file contains a block that has the same name as the existing one | Check the file and rename the block to something else
SIGMA_CALLBACK_SYNTAX_ERROR | Cannot parse template function: (error description) | Bogus syntax for template function parameters. | Fix the template function definition, pay special attention to quoting rules.

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
addBlock() | PEAR Manual | blockExists()


blockExists()

blockExists()

blockExists() – Checks if the block exists in the template

Synopsis

require_once 'HTML/Template/Sigma.php';

bool HTML_Template_Sigma::blockExists ( string $block )

Description

Checks if the block exists in the template

Parameter

string $block

block name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
addBlockfile() | PEAR Manual | clearVariables()


clearVariables()

clearVariables()

clearVariables() – Clears the variables

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::clearVariables ( ( void )

Description

Global variables are not affected, only the ones set via setVariable(). The method is useful when you add a lot of variables via setVariable() and are not sure whether all of them appear in the block you parse(). If you clear the variables after parse(), you don't risk them suddenly showing up in other blocks.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
blockExists() | PEAR Manual | errorMessage()


errorMessage()

errorMessage()

errorMessage() – Returns a textual error message for an error code

Synopsis

require_once 'HTML/Template/Sigma.php';

string HTML_Template_Sigma::errorMessage ( integer $code , string $data = null )

Description

Returns a textual error message for an error code. This is usually called when throwing a error, there is seldom need to call this method directly.

Parameter

integer $code

error code

string $data

additional data to insert into message

Return value

return error message

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
clearVariables() | PEAR Manual | get()


get()

get()

get() – Returns a block with all replacements done.

Synopsis

require_once 'HTML/Template/Sigma.php';

string HTML_Template_Sigma::get ( string $block = '__global__' , bool $clear = false )

Description

Returns a parsed block: block with all replacements done.

This method will automatically call parse(), only if called with $block ='__global__' when '__global__' was not parse()'d before. In all other cases you should call parse() before calling get()

Parameter

string $block

block name

boolean $clear

whether to clear parsed block contents

Return value

return block with all replacements done

See

see HTML_Template_Sigma::show()

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
errorMessage() | PEAR Manual | getBlockList()


getBlockList()

getBlockList()

getBlockList() – Returns a list of blocks within a template.

Synopsis

require_once 'HTML/Template/Sigma.php';

array HTML_Template_Sigma::getBlockList ( string $parent = '__global__' , bool $recursive = false )

Description

Returns a list of blocks within a template.

If $recursive is FALSE, it returns just a 'flat' array of $parent 's direct subblocks. If $recursive is TRUE, it builds a tree of template blocks using $parent as root. Tree structure is compatible with PEAR::Tree's Memory_Array driver.

Parameter

string $parent

parent block name

boolean $recursive

whether to return a tree of child blocks (TRUE) or a 'flat' array (FALSE)

Return value

return a list of child blocks

See

see HTML_Template_Sigma::blockExists(), HTML_Template_Sigma::getPlaceholderList()

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$parent ' | There is no block $parent in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
get() | PEAR Manual | getCurrentBlock()


getCurrentBlock()

getCurrentBlock()

getCurrentBlock() – Returns the current block name

Synopsis

require_once 'HTML/Template/Sigma.php';

string HTML_Template_Sigma::getCurrentBlock ( ( void )

Description

Returns the current block name (set by HTML_Template_Sigma::setCurrentBlock())

Return value

return block name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
getBlockList() | PEAR Manual | getPlaceholderList()


getPlaceholderList()

getPlaceholderList()

getPlaceholderList() – Returns a list of placeholders within a block.

Synopsis

require_once 'HTML/Template/Sigma.php';

array HTML_Template_Sigma::getPlaceholderList ( string $block = '__global__' )

Description

Returns a list of placeholders within a block.

Only 'normal' placeholders are in the list, not ones automatically created for blocks and template functions.

Parameter

string $block

block name

Return value

return a list of placeholders

See

see HTML_Template_Sigma::placeholderExists(), HTML_Template_Sigma::getBlockList()

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
getCurrentBlock() | PEAR Manual | hideBlock()


hideBlock()

hideBlock()

hideBlock() – Hides the block even if it is not "empty".

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::hideBlock ( string $block )

Description

Hides the block even if it is not "empty".

Is somewhat an opposite to touchBlock().

Consider a block (a 'edit' link for example) that should be visible to registered/"special" users only, but its visibility is triggered by some little 'id' field passed in a large array into setVariable(). You can either carefully juggle your variables to prevent the block from appearing (a fragile solution) or simply call hideBlock()

Parameter

string $block

block name

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
getPlaceholderList() | PEAR Manual | loadTemplateFile()


loadTemplateFile()

loadTemplateFile()

loadTemplateFile() – Loads a template file.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::loadTemplateFile ( string $filename , boolean $removeUnknownVariables = true , boolean $removeEmptyBlocks = true )

Description

Loads a template file. If caching is on, then it checks whether a "prepared" template exists. If it does, it gets loaded instead of the original, if it does not, then the original gets loaded and prepared and then the prepared version is saved. addBlockfile() and replaceBlockfile() implement quite the same logic.

Parameter

string $filename

filename

boolean $removeUnknownVariables

remove unknown/unused variables?

boolean $removeEmptyBlocks

remove empty blocks?

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_TPL_NOT_FOUND | Cannot read the template file '$filename ' | File is unreadable for some reason | Check if the file exists and has correct permissions set
SIGMA_CACHE_ERROR | Cannot save template file 'filename' | A prepared template file cannot be saved | Check if the directory for prepared templates cache exists and is writeable for your script
SIGMA_BLOCK_DUPLICATE | The name of a block must be unique within a template. Block 'blockname' found twice. | The loaded file contains two blocks sharing the same name | Check the file and rename one of the blocks to something else
SIGMA_CALLBACK_SYNTAX_ERROR | Cannot parse template function: (error description) | Bogus syntax for template function parameters. | Fix the template function definition, pay special attention to quoting rules.

See

see HTML_Template_Sigma::setTemplate(), HTML_Template_Sigma::$removeUnknownVariables, HTML_Template_Sigma::$removeEmptyBlocks

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
hideBlock() | PEAR Manual | parse()


parse()

parse()

parse() – Parses the given block.

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::parse ( string $block = '__global__' , boolean $flagRecursion = false , boolean $fakeParse = false )

Description

Parses the given block. It substitutes local and global variables appearing in the block and set via setVariable() and setGlobalVariable(), calls all the callback functions and recursively processes the subblocks of the block.

Parameter

string $block

block name

boolean $flagRecursion

TRUE if the function is called recursively (do not set this to TRUE yourself!)

boolean $fakeParse

TRUE if parsing a "hidden" block (do not set this to TRUE yourself!)

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

See

see HTML_Template_Sigma::parseCurrentBlock()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
loadTemplateFile() | PEAR Manual | parseCurrentBlock()


parseCurrentBlock()

parseCurrentBlock()

parseCurrentBlock() – Parses the current block

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::parseCurrentBlock ( ( void )

Description

Parses the current block (set by HTML_Template_Sigma::setCurrentBlock())

Throws

throws no exceptions thrown

See

see HTML_Template_Sigma::parse(), HTML_Template_Sigma::setCurrentBlock()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
parse() | PEAR Manual | placeholderExists()


placeholderExists()

placeholderExists()

placeholderExists() – Checks whether the placeholder exists

Synopsis

require_once 'HTML/Template/Sigma.php';

string HTML_Template_Sigma::placeholderExists ( string $placeholder , string $block = '' )

Description

Checks whether the placeholder exists in the template, returns the name of the (first) block that contains the specified placeholder.

Parameter

string $placeholder

Name of the placeholder you're searching

string $block

Name of the block to scan. If left out (default) all blocks are scanned.

Return value

return Name of the (first) block that contains the specified placeholder. If the placeholder was not found an empty string is returned.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
parseCurrentBlock() | PEAR Manual | replaceBlock()


replaceBlock()

replaceBlock()

replaceBlock() – Replaces an existing block with new content.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::replaceBlock ( string $block , string $template , boolean $keepContent = false )

Description

Replaces an existing block with new content. This function will replace a block of the template and all blocks contained in it and add a new block instead. This means you can dynamically change your template.

Sigma analyses the way you've nested blocks and knows which block belongs into another block. This nesting information helps to make the API short and simple. Replacing blocks does not only mean that Sigma has to update the nesting information (relatively time consuming task) but you have to make sure that you do not get confused due to the template change yourself.

Parameter

string $block

name of a block to replace

string $template

new content

boolean $keepContent

TRUE if the parsed contents of the block should be kept

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template
SIGMA_BLOCK_DUPLICATE | The name of a block must be unique within a template. Block 'blockname' found twice. | The new block contains a subblock that has the same name as the existing one | Check the $template and rename the block to something else
SIGMA_CALLBACK_SYNTAX_ERROR | Cannot parse template function: (error description) | Bogus syntax for template function parameters. | Fix the template function definition, pay special attention to quoting rules.

See

see HTML_Template_Sigma::replaceBlockfile(), HTML_Template_Sigma::addBlock()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
placeholderExists() | PEAR Manual | replaceBlockfile()


replaceBlockfile()

replaceBlockfile()

replaceBlockfile() – Replaces an existing block with new content from a file.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::replaceBlockfile ( string $block , string $filename , boolean $keepContent = false )

Description

Replaces an existing block with new content from a file.

Parameter

string $block

name of a block to replace

string $filename

template file that contains the block

boolean $keepContent

TRUE if the parsed contents of the block should be kept

Return value

return SIGMA_OK on success, error object on failure

See

see HTML_Template_Sigma::replaceBlock(), HTML_Template_Sigma::addBlockfile()

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template
SIGMA_BLOCK_DUPLICATE | The name of a block must be unique within a template. Block 'blockname' found twice. | The loaded block contains a subblock that has the same name as the existing one | Check the file contents and rename the block to something else
SIGMA_TPL_NOT_FOUND | Cannot read the template file '$filename ' | File is unreadable for some reason | Check if the file exists and has correct permissions set
SIGMA_CACHE_ERROR | Cannot save template file 'filename' | A prepared template file cannot be saved | Check if the directory for prepared templates cache exists and is writeable for your script
SIGMA_CALLBACK_SYNTAX_ERROR | Cannot parse template function: (error description) | Bogus syntax for template function parameters. | Fix the template function definition, pay special attention to quoting rules.

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
replaceBlock() | PEAR Manual | setCacheRoot()


setCacheRoot()

setCacheRoot()

setCacheRoot() – Sets the directory to cache "prepared" templates in.

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::setCacheRoot ( string $root )

Description

Sets the directory to cache "prepared" templates in, the directory should be writable for PHP.

The "prepared" template contains an internal representation of template structure: essentially a serialized array of $_blocks, $_blockVariables, $_children and $_functions, may also contain $_triggers. This allows to bypass expensive calls to HTML_Template_Sigma::_buildBlockVariables() and especially HTML_Template_Sigma::_buildBlocks() when reading the "prepared" template instead of the "source" one.

The files in this cache do not have any TTL and are regenerated when the source templates change.

Parameter

string $root

directory name

Throws

throws no exceptions thrown

See

see HTML_Template_Sigma::HTML_Template_Sigma()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
replaceBlockfile() | PEAR Manual | setCallbackFunction()


setCallbackFunction()

setCallbackFunction()

setCallbackFunction() – Sets a callback function.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::setCallbackFunction ( string $tplFunction , mixed $callback , bool $preserveArgs = false )

Description

Sets a callback function. Sigma templates can contain simple function calls. This means that the author of the template can add a special placeholder to it: func_h1("embedded in h1") Sigma will parse the template for these placeholders and will allow you to define a callback function for them. Callback will be called automatically when the block containing such function call is parse()'d.

Please note that arguments to these template functions can contain variable placeholders: func_translate('Hello, {username}'), but not blocks or other function calls.

This should NOT be used to add logic (except some presentation one) to the template. If you use a lot of such callbacks and implement business logic through them, then you're reinventing the wheel. Consider using XML/XSLT, native PHP or some other template engine.

Script:

<?php
function h_one($arg)
{
    return '<h1>' . $arg . '</h1>';
}
// ...
$tpl = new HTML_Template_Sigma(' ... ');
// ...
$tpl->setCallbackFunction('h1', 'h_one');
// ...
$tpl->show()
?>

template:

...
func_h1('H1 Headline')
...

Parameter

string $tplFunction

Function name in the template

mixed $callback

A callback: anything that can be passed to call_user_func_array()

boolean $preserveArgs

If TRUE, then no variable substitution in arguments will take place before function call

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_INVALID_CALLBACK | Callback does not exist | The $callback is not an existing function or method | Check spelling, check whether the object was correctly instantiated if using the method callback

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setCacheRoot() | PEAR Manual | setCurrentBlock()


setCurrentBlock()

setCurrentBlock()

setCurrentBlock() – Sets the name of the current block.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::setCurrentBlock ( string $block = '__global__' )

Description

Sets the name of the current block: the one in which variables will be substituted.

Parameter

string $block

block name

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setCallbackFunction() | PEAR Manual | setGlobalVariable()


setGlobalVariable()

setGlobalVariable()

setGlobalVariable() – Sets a global variable value.

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::setGlobalVariable ( mixed $variable , string $value = '' )

Description

Sets a global variable value. Global variables are "special": they do not get cleared after substitution and do not make blocks not empty if substituted.

Parameter

mixed $variable

variable name or array ('varname'=>'value')

string $value

variable value if $variable is not an array

Throws

throws no exceptions thrown

See

see HTML_Template_Sigma::setVariable()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setCurrentBlock() | PEAR Manual | setOption()


setOption()

setOption()

setOption() – Sets the option for the template class

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::setOption ( string $option , mixed $value )

Description

Sets the option for the template class. Currently it understands the following options:

preserve_data

If set to TRUE, then do not substitute variables and remove unused placeholders in data added through setVariable() and setGlobalVariable(). See also bugs #20199 and #21951. Default is FALSE, for performance reasons.

trim_on_save

Whether to trim extra whitespace from template on cache save. Generally safe to have this on, unless you have <pre></pre> in templates or want to preserve HTML indentantion. Default is TRUE

charset

Character set to use by builtin 'h' and 'e' callbacks. Default is 'iso-8859-1'. Available since release 1.2.0

Parameter

string $option

option name

mixed $value

option value

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_UNKNOWN_OPTION | Unknown option '$option ' | $option is not known to Sigma | Check the option name spelling

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setGlobalVariable() | PEAR Manual | setRoot()


setRoot()

setRoot()

setRoot() – Sets the file root for templates.

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::setRoot ( string $root )

Description

Sets the file root for templates. The file root gets prefixed to all filenames passed to the object.

Parameter

string $root

directory name

Throws

throws no exceptions thrown

See

see HTML_Template_Sigma::HTML_Template_Sigma()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setOption() | PEAR Manual | setTemplate()


setTemplate()

setTemplate()

setTemplate() – Sets the template.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::setTemplate ( string $template , boolean $removeUnknownVariables = true , boolean $removeEmptyBlocks = true )

Description

Sets the template. You can either load a template file from disk with loadTemplateFile() or set the template manually using this function.

Parameter

string $template

template content

boolean $removeUnknownVariables

remove unknown/unused variables?

boolean $removeEmptyBlocks

remove empty blocks?

Return value

return SIGMA_OK on success, error object on failure

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_DUPLICATE | The name of a block must be unique within a template. Block 'blockname' found twice. | The $template contains two blocks sharing the same name | Check the $template and rename one of the blocks to something else
SIGMA_CALLBACK_SYNTAX_ERROR | Cannot parse template function: (error description) | Bogus syntax for template function parameters. | Fix the template function definition, pay special attention to quoting rules.

See

see HTML_Template_Sigma::loadTemplateFile()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setRoot() | PEAR Manual | setVariable()


setVariable()

setVariable()

setVariable() – Sets a variable value.

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::setVariable ( mixed $variable , string $value = '' )

Description

Sets a variable value. The function can be used either like setVariable("varname", "value") or with one array $variables["varname"] = "value" given setVariable($variables)

Parameter

mixed $variable

variable name or array ('varname'=>'value')

string $value

variable value if $variable is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setTemplate() | PEAR Manual | show()


show()

show()

show() – Prints a block with all replacements done.

Synopsis

require_once 'HTML/Template/Sigma.php';

void HTML_Template_Sigma::show ( string $block = '__global__' )

Description

Prints a block with all replacements done.

Parameter

string $block

block name

Throws

throws no exceptions thrown

See

see HTML_Template_Sigma::get()

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
setVariable() | PEAR Manual | touchBlock()


touchBlock()

touchBlock()

touchBlock() – Preserves the block even if empty blocks should be removed.

Synopsis

require_once 'HTML/Template/Sigma.php';

mixed HTML_Template_Sigma::touchBlock ( string $block )

Description

Sometimes you have blocks that should be preserved although they are empty (no placeholder replaced). Think of a shopping basket. If it's empty you have to show a message to the user. If it's filled you have to show the contents of the shopping basket. Now where to place the message that the basket is empty? It's not a good idea to place it in you application as customers tend to like unecessary minor text changes. Having another template file for an empty basket means that one fine day the filled and empty basket templates will have different layouts.

So blocks that do not contain any placeholders but only messages like "Your shopping basked is empty" are introduced. Now if there is no replacement done in such a block the block will be recognized as "empty" and by default ($removeEmptyBlocks = true) be stripped off. To avoid this you can call touchBlock()

Parameter

string $block

block name

Return value

return SIGMA_OK on success, error object on failure

See

see HTML_Template_Sigma::$removeEmptyBlocks

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
SIGMA_BLOCK_NOT_FOUND | Cannot find block '$block ' | There is no block $block in the template | Check the block name spelling, check whether you added all the necessary blocks to the template

Note

This function can not be called statically.

Prev | HTML_Template_Sigma | Next
show() | PEAR Manual | HTML_Template_Xipe


HTML_Template_Xipe

HTML_Template_Xipe

The template engine is a compiling engine, all templates are compiled into PHP-files. This will make the delivery of the files faster on the next request, since the template doesn't need to be compiled again. If the template changes it will be recompiled. There is no new template language to learn. Beside the default mode, there is a set of constructs since version 1.6 which allow you to edit your templates with WYSIWYG editors

Table of Contents
  • Introduction -- A simple, fast and powerful template engine.
Prev | HTML | Next
touchBlock() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – A simple, fast and powerful template engine.

HTML_Template_Xipe Description

The template engine is a compiling engine, all templates are compiled into PHP-files. This will make the delivery of the files faster on the next request, since the template doesn't need to be compiled again. If the template changes it will be recompiled. There is no new template language to learn. Beside the default mode, there is a set of constructs since version 1.6 which allow you to edit your templates with WYSIWYG editors. By default the template engine uses indention for building blocks (you can turn that off). This feature was inspired by Python and by the need I felt to force myself to write proper HTML-code, using proper indentions, to make the code better readable.

Unfortunately, complete documentation is not available at the moment.

Prev | HTML_Template_Xipe | Next
HTML_Template_Xipe | PEAR Manual | HTML_TreeMenu


HTML_TreeMenu

HTML_TreeMenu

This manual page shows the basic steps to get HTML_TreeMenu working.

Table of Contents
  • Installing the files
  • Simple example
  • Tree-construction methods
Prev | HTML | Next
Introduction | PEAR Manual | Installing the files


Installing the files

Installing the files

Before using HTML_TreeMenu, you'll have to put some files in your project's htdocs directory:

  • TreeMenu.js

  • images

You can get on your harddrive in $pear_data_dir/HTML_TreeMenu or online at the PEAR CVS-Web.

Prev | HTML_TreeMenu | Next
HTML_TreeMenu | PEAR Manual | Simple example


Simple example

Simple example

<?php

require_once 'HTML/TreeMenu.php';

$menu_styles      = new HTML_TreeNode(array('text'=>'Styles'));
$menu_pays        = new HTML_TreeNode(array('text'=>'Countries'));
$menu_restaurants = new HTML_TreeNode(array('text'=>'Restaurants'));
$menu_plats       = new HTML_TreeNode(array('text'=>'Menus'));

for ($i = 1; $i < 10; $i) {
    $menu_styles->addItem(new HTML_TreeNode(array('icon'=>'Image '.($i 0))));
    $menu_pays->addItem(new HTML_TreeNode(array('icon'=>'Image '.($i 10))));
    $menu_restaurants->addItem(new HTML_TreeNode(array('icon'=>'Image '.($i 20))));
    $menu_plats->addItem(new HTML_TreeNode(array('icon'=>'Image '.($i 30))));
}

$menu  = new HTML_TreeMenu();
$menu->addItem($menu_styles);
$menu->addItem($menu_pays);
$menu->addItem($menu_restaurants);
$menu->addItem($menu_plats);

// Chose a generator. You can generate DHTML or a Listbox
$tree = new HTML_TreeMenu_DHTML($menu);

echo $tree->toHTML();

?>
Prev | HTML_TreeMenu | Next
Installing the files | PEAR Manual | Tree-construction methods


Tree-construction methods

Tree-construction methods

Actually, you have three different methods to build the tree:

By hand

This is the 'hard' way, like the example above. You have to set each node by hand.

Importing XML

You can import a formatted XML file into the tree structure. It supports string of XML_Tree object :)

XML Format

<treemenu>
  <node text="First node" icon="folder.gif" expandedIcon="folder-expanded.gif" />
  <node text="Second node" icon="folder.gif" expandedIcon="folder-expanded.gif">
    <node text="Sub node" icon="folder.gif" expandedIcon="folder-expanded.gif" />
  </node>
  <node text="Third node" icon="folder.gif" expandedIcon="folder-expanded.gif">
</treemenu>

Example with a string (not tested)

<?php
require_once 'HTML/TreeMenu.php';

// Load the XML file
$xml = file_get_contents('tree.xml');

$menu = new HTML_TreeMenu();
$menu->createFromXML($xml);

// Chose a generator. You can generate DHTML or a Listbox
//$tree = new HTML_TreeMenu_Listbox($menu);
$tree = new HTML_TreeMenu_DHTML($menu);

echo $tree->toHTML();

?>
Prev | HTML_TreeMenu | Next
Simple example | PEAR Manual | Pager


Pager

Pager

Data paging class which also builds links to the pages.

Table of Contents
  • Introduction -- Usage of Pager 2.x
  • Pager "Jumping" vs. "Sliding" -- Feature comparison of the two pager styles
  • Pager::factory -- Creates a pager instance
  • Pager::setOptions -- Set or change option after the Pager object has been constructed
  • Pager::build -- Generate or refresh the links and paged data after a call to setOptions
  • Pager::getCurrentPageID -- Returns current page number
  • Pager::getLinks -- Returns back/next/first/last and page links, both as ordered and associative array.
  • Pager::getNextPageID -- Returns next page number.
  • Pager::getOffsetByPageId -- Returns offsets for given pageID.
  • Pager::getPageData -- Returns an array of current pages data
  • Pager::getPageIdByOffset -- Returns the page number for the given offset
  • Pager::getPageRangeByPageId -- Returns offsets for given pageID.
  • Pager::getPageSelectBox -- Returns a string with a XHTML SELECT menu, to choose the page to display.
  • Pager::getPreviousPageID -- Returns previous page number.
  • Pager::getPerPageSelectBox -- Returns a string with a XHTML SELECT menu, to choose how many items per page should be displayed.
  • Pager::isFirstPage -- Returns whether current page is first page
  • Pager::isLastPage -- Returns whether current page is last page
  • Pager::isLastPageComplete -- Returns whether last page is complete
  • Pager::numItems -- Returns number of items
  • Pager::numPages -- Returns number of pages
  • Pager::Pager -- Creates a pager instance
Prev | HTML | Next
Tree-construction methods | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Usage of Pager 2.x

What is Pager?

Pager is a class to page an array of data. It is taken as input and it is paged according to various parameters. Pager also builds links within a specified range, and allows complete customization of the output (it even works with mod_rewrite). It is compatible with Pager v.1.x and Pager_Sliding API

Example 1

This simple example will page the array of alphabetical letters, giving back pages with 3 letters per page, and links to the previous two / next two pages:

<?php
require_once 'Pager.php';
$params = array(
    'mode'       => 'Jumping',
    'perPage'    => 3,
    'delta'      => 2,
    'itemData'   => array('a','b','c','d','e',[...omissis...],'z')
);
$pager = & Pager::factory($params);
$data  = $pager->getPageData();
$links = $pager->getLinks();
//$links is an ordered+associative array with 'back'/'pages'/'next'/'first'/'last'/'all' links.
//NB: $links['all'] is the same as $pager->links;

//echo links to other pages:
echo $links['all'];

//Pager can also generate <link rel="first|prev|next|last"> tags
echo $pager->linkTags;

//Show data for current page:
echo 'PAGED DATA: ' ; print_r($data);

//Results from methods:
echo 'getCurrentPageID()...: '; var_dump($pager->getCurrentPageID());
echo 'getNextPageID()......: '; var_dump($pager->getNextPageID());
echo 'getPreviousPageID()..: '; var_dump($pager->getPreviousPageID());
echo 'numItems()...........: '; var_dump($pager->numItems());
echo 'numPages()...........: '; var_dump($pager->numPages());
echo 'isFirstPage()........: '; var_dump($pager->isFirstPage());
echo 'isLastPage().........: '; var_dump($pager->isLastPage());
echo 'isLastPageComplete().: '; var_dump($pager->isLastPageComplete());
echo '$pager->range........: '; var_dump($pager->range);
?>

In case you're wondering, $pager->range is a numeric array; its keys are the numbers of the pages in the current range, and the matching values are booleans (TRUE if its key represents currentPage, FALSE otherwise). This array can be useful to build the links manually, e.g. when using a template engine.

Example 2

This example shows how you can use this class with mod_rewite. Let's suppose we have a .htaccess like this:

---------
RewriteEngine on
#Options FollowSymlinks

RewriteBase /
RewriteRule ^articles/([a-z]{1,12})/art([0-9]{1,4})\.html$ /article.php?num=$2&amp;month=$1 [L]
---------

It should transform an url like "/articles/march/art15.html" into "/article.php?num=15&month=march"

<?php
require_once 'Pager.php';

$month = 'september';
$params = array(
    'mode'      => 'Sliding',
    'append'    => false,
    'urlVar'    => 'num',
    'path'      => 'http://myserver.com/articles/' . $month,
    'fileName'  => 'art%d.html',  //Pager replaces "%d" with page number...
    'itemData'  => array('a','b','c',[...omissis...],'z'),
    'perPage'   => 3
);
$pager = & Pager::factory($params);

$data  = $pager->getPageData();
echo $pager->links;
echo 'Data for current page: '; print_r($data);
?>

More pagers in a single page

Using more than one pager in a single page is as simple as using a different urlVar for each pager:

<?php
require_once 'Pager.php';

//first pager
$params1 = array(
    'perPage'    => 3,
    'urlVar'     => 'pageID_articles',  //1st identifier
    'itemData'   => $someArray
);
$pager1 = & Pager::factory($params1);
$data1  = $pager1->getPageData();
$links1 = $pager1->getLinks();

//second pager
$params2 = array(
    'perPage'    => 8,
    'urlVar'     => 'pageID_news',      //2nd identifier
    'itemData'   => $someOtherArray
);
$pager2 = & Pager::factory($params2);
$data2  = $pager2->getPageData();
$links2 = $pager2->getLinks();
?>

Pager and big db resultsets

If you want to paginate db resultsets, fetching them all into an array and passing it to Pager might not be the best option. You can still leverage Pager and have good performances using a wrapper. There is a sample wrapper for each one of the PEAR db abstraction systems in the /docs/examples/ dir of the package. You may use it as-is or customize it to your needs.

Adding extra variables to the querystring

If you need to add some extra variables to the querystring, use the extraVars parameter:

<?php
$params = array(
    'extraVars' => array(
        'firstKey'  => 'firstValue',
        'secondKey' => 'secondValue',
        //...
    ),
    //...
);
$pager1 = & Pager::factory($params);
?>

Important note for PHP 5 users

Since version 2.2.1, Pager works with PHP 5 too, but you must use the factory() method instead of the constructor (which is deprecated):

<?php
require_once 'Pager.php';

//wrong:
//$pager =& new Pager($params);

//right
$pager =& Pager::factory($params);

//continue as you did before
?>

If you are using a previous revision and cannot update, you must write the following code on PHP 5:

<?php
//chose your preferred mode [Jumping | Sliding]:

//require_once 'Pager/Jumping.php';
require_once 'Pager/Sliding.php';

//$pager =& new Pager_Jumping($params);
$pager =& new Pager_Sliding($params);

//continue as you did before
?>

Pager Tutorials

There are some other online resources with in-depth coverage of what Pager can do: PEAR::Pager tutorials.

  • How to efficiently paginate database results

  • Create pretty links with Pager and mod_rewrite

  • Navigation with Pager and AJAX (or simple Javascript)

  • Article pagination, or how to navigate through the paragraphs with Pager

  • Two examples: Paginate db results with Pager_Wrapper and display them with AJAX. Use Pager with the Smarty template engine.

Prev | Pager | Next
Pager | PEAR Manual | Pager "Jumping" vs. "Sliding"


Pager "Jumping" vs. "Sliding"

Pager "Jumping" vs. "Sliding"

Pager "Jumping" vs. "Sliding" – Feature comparison of the two pager styles

What are the differences between the two styles?

Since an example is worth 1000 words:

"Jumping" Pager logic

Let's suppose that the data spans on 15 pages, and the window width is 5 page links. The links are built on "frames" of 5 pages each: [1-5] [6-10] [11-15] Pager in "Jumping" mode always shows the same 5 page links while you are on one of these pages. Here's a temporal succession of the links, starting from page 1 and moving forward. There are brakets around current page number to highlight this:

<?php
a)    {1} 2  3  4  5  =>   // first frame: [1-5]
b) <=  1 {2} 3  4  5  =>
c) <=  1  2 {3} 4  5  =>
d) <=  1  2  3 {4} 5  =>
e) <=  1  2  3  4 {5} =>   // HERE IT JUMPS TO THE NEXT FRAME
f) <= {6} 7  8  9 10  =>   // second frame: [6-10]
g) <=  6 {7} 8  9 10  =>
h) <=  6  7 {8} 9 10  =>
?>

and so on. See what a "jumping window" frame is? When you reach a limit (in the example, you go from page 5 to page 6), it "jumps" to next frame (links from page 6 to 10).

"Sliding" Pager logic

Instead of jumping from one frame to the other, with Pager in "Sliding" mode the change is done smoothly, and the current page is always shown at the center of the "window" (except of course for the first and the last pages):

<?php
a)       {1} 2  3  4  5  => [15]
b) [1] <= 1 {2} 3  4  5  => [15]
c) [1] <= 1  2 {3} 4  5  => [15]  // HERE IT's STARTING WORKING AS DESIGNED
d) [1] <= 2  3 {4} 5  6  => [15]  // see: current page number is at the center of the window
e) [1] <= 3  4 {5} 6  7  => [15]  // and it stays there...
f) [1] <= 4  5 {6} 7  8  => [15]
g) [1] <= 5  6 {7} 8  9  => [15]
h) [1] <= 6  7 {8} 9 10  => [15]
?>

and so on.

Other differences

Apart from the different "philosophy", there is one difference in the delta parameter: in "Jumping" mode, it's the number of page numbers to show; in "Sliding" mode it's the number of page numbers to show before and after the current one.

Prev | Pager | Next
Introduction | PEAR Manual | Pager::factory


Pager::factory

Pager::factory

Pager::factory() – Creates a pager instance

Synopsis

require_once 'Pager.php';

object &factory ( array $options )

Parameter

Pager::factory() method takes an associative array of parameters as input values. This is the complete list of these options:

  • itemData [array]

    Array of items to page.

  • totalItems [integer]

    Number of items to page (used only if itemData is not provided).

  • perPage [integer]

    Number of items to display on each page.

  • delta [integer]

    Number of page numbers to display before and after the current one.

  • mode [string]

    "Jumping" or "Sliding" -window - It determines pager behaviour.

  • httpMethod [string]

    Specifies the HTTP method to use. Valid values are 'GET' or 'POST'.

  • formID [string]

    Specifies which HTML form to use in POST mode.

  • importQuery [boolean]

    if true (default behaviour), variables and values are imported from the submitted data (query string) and used in the generated links, otherwise they're ignored completely

  • currentPage [integer]

    Initial page number (if you want to show page #2 by default, set currentPage to 2)

  • expanded [boolean]

    if TRUE, window size is always 2*delta+1

  • linkClass [string]

    Name of CSS class used for link styling.

  • urlVar [string]

    Name of URL var used to indicate the page number. Default value is "pageID".

  • path [string]

    Complete path to the page (without the page name).

  • fileName [string]

    name of the page, with a "%d" if append == TRUE.

  • fixFileName [boolean]

    If set to FALSE, the fileName option is not overridden. Use at your own risk.

  • append [boolean]

    If TRUE pageID is appended as GET value to the URL. If FALSE it is embedded in the URL according to fileName specs.

  • altFirst [string]

    Alt text to display on the link of the first page. Default value is "first page"; if you want a string with the page number, use "%d" as a placeholder (for instance "page %d")

  • altPrev [string]

    Alt text to display on the link of the previous page. Default value is "previous page";

  • altNext [string]

    Alt text to display on the link of the next page. Default value is "next page";

  • altLast [string]

    Alt text to display on the link of the last page. Default value is "last page"; if you want a string with the page number, use "%d" as a placeholder (for instance "page %d")

  • altPage [string]

    Alt text to display before the page number. Default value is "page " (followed by the page number). You can optionally use "%d" as a placeholder (for instance "page n. %d") to place the page number where you want.

  • prevImg [string]

    Something to display instead of "<<". It can be text such as "<< PREV" or an <img/> as well.

  • nextImg [string]

    Something to display instead of ">>". It can be text such as "NEXT >>" or an <img/> as well.

  • separator [string]

    What to use to separate numbers. It can be an <img/>, a comma, an hyphen, or whatever.

  • spacesBeforeSeparator [integer]

    Number of spaces before the separator.

  • spacesAfterSeparator [integer]

    Number of spaces after the separator.

  • firstLinkTitle [string]

    String used as title in <link rel="first"> tag

  • nextLinkTitle [string]

    String used as title in <link rel="next"> tag

  • prevLinkTitle [string]

    String used as title in <link rel="previous"> tag

  • lastLinkTitle [string]

    String used as title in <link rel="last"> tag

  • curPageLinkClassName [string]

    CSS class name for the current page link.

  • curPageSpanPre [string]

    Text before the current page link.

  • curPageSpanPost [string]

    Text after the current page link.

  • firstPagePre [string]

    String used before the first page number. It can be an <img/>, a "{", an empty string, or whatever.

  • firstPageText [string]

    String used in place of the first page number.

  • firstPagePost [string]

    String used after the first page number. It can be an <img/>, a "}", an empty string, or whatever.

  • lastPagePre [string]

    Similar to firstPagePre , but used for last page number.

  • lastPageText [string]

    Similar to firstPageText , but used for last page number.

  • lastPagePost [string]

    Similar to firstPagePost , but used for last page number.

  • clearIfVoid [boolean]

    if there's only one page, don't display pager links (returns an empty string).

  • extraVars [array]

    additional URL vars to be added to the querystring.

  • excludeVars [array]

    URL vars to be excluded from the querystring.

  • useSessions [boolean]

    if TRUE, number of items to display per page is stored in the $_SESSION[$_sessionVar] var.

  • closeSession [boolean]

    if TRUE, the session is closed just after R/W.

  • sessionVar [string]

    Name of the session var for perPage value. A value different from default can be useful when using more than one Pager istance in the page.

  • showAllText [string]

    Text to be used for the 'show all' option in the select box generated by getPerPageSelectBox()

  • pearErrorMode [constant]

    PEAR_ERROR mode for raiseError(). Default is PEAR_ERROR_RETURN.

REQUIRED options are:

  • fileName IF append ==FALSE (default is TRUE)

  • itemData OR totalItems (if itemData is set, totalItems is overwritten)

Return value

object - a specific Pager instance or a PEAR_Error object, if fails

Prev | Pager | Next
Pager "Jumping" vs. "Sliding" | PEAR Manual | Pager::setOptions


Pager::setOptions

Pager::setOptions

Pager::setOptions() – Set or change option after the Pager object has been constructed

Synopsis

require_once 'Pager.php';

array Pager::setOptions ( array $options )

Description

Remember to call build() after this method to regenerate the data and the links.

Parameter

  • integer $index - an associative array of options. See Pager::factory() for the full list of options.

Return value

return PAGER_OK constant on success

Prev | Pager | Next
Pager::factory | PEAR Manual | Pager::build


Pager::build

Pager::build

Pager::build() – Generate or refresh the links and paged data after a call to setOptions()

Synopsis

require_once 'Pager.php';

array Pager::build ( )

Description

  • If you want to change an option after the Pager object has been constructed, after the call to setOptions() you have to generate or refresh the links and paged data with this method.

Prev | Pager | Next
Pager::setOptions | PEAR Manual | Pager::getCurrentPageID


Pager::getCurrentPageID

Pager::getCurrentPageID

Pager::getCurrentPageID() – Returns current page number

Synopsis

require_once 'Pager.php';

integer getCurrentPageID ( )

Return value

integer - Current page number.

Prev | Pager | Next
Pager::build | PEAR Manual | Pager::getLinks


Pager::getLinks

Pager::getLinks

Pager::getLinks() – Returns back/next/first/last and page links, both as ordered and associative array.

Synopsis

require_once 'Pager.php';

array Pager::getLinks ( integer $pageID = null )

Parameter

  • integer $pageID - Optional pageID. If specified, linksfor that page are provided instead of current one.

Return value

return back/pages/next/first/last/all links, both as numeric and associative array.

Prev | Pager | Next
Pager::getCurrentPageID | PEAR Manual | Pager::getNextPageID


Pager::getNextPageID

Pager::getNextPageID

Pager::getNextPageID() – Returns next page number.

Synopsis

require_once 'Pager.php';

mixed Pager::getNextPageID ( )

Description

If current page is last page this function returns FALSE, otherwise returns next page number.

Return value

return Next page number or FALSE

Prev | Pager | Next
Pager::getLinks | PEAR Manual | Pager::getOffsetByPageId


Pager::getOffsetByPageId

Pager::getOffsetByPageId

Pager::getOffsetByPageId() – Returns offsets for given pageID.

Synopsis

require_once 'Pager.php';

array Pager::getOffsetByPageId ( integer $pageid = null )

Description

Returns offsets for given pageID . Eg, if you pass it pageID one and your perPage limit is 10 it will return (1, 10). pageID =2 would give you (11, 20).

if the method is called without parameter, pageID is set to currentPage

Parameter

  • integer $pageid - PageID to get offsets for

Return value

return array with first and last offsets

Deprecated

deprecated

Prev | Pager | Next
Pager::getNextPageID | PEAR Manual | Pager::getPageData


Pager::getPageData

Pager::getPageData

Pager::getPageData() – Returns an array of current pages data

Synopsis

require_once 'Pager.php';

array Pager::getPageData ( integer $pageID = null )

Parameter

  • integer $pageID - Desired page ID (optional)

Return value

return array of data for this page.

Prev | Pager | Next
Pager::getOffsetByPageId | PEAR Manual | Pager::getPageIdByOffset


Pager::getPageIdByOffset

Pager::getPageIdByOffset

Pager::getPageIdByOffset() – Returns the page number for the given offset

Synopsis

require_once 'Pager.php';

array Pager::getPageIdByOffset ( integer $index )

Description

This method is only available in "Jumping" mode.

Parameter

  • integer $index - Offset to get pageID for

Return value

return Page number for this offset

Prev | Pager | Next
Pager::getPageData | PEAR Manual | Pager::getPageRangeByPageId


Pager::getPageRangeByPageId

Pager::getPageRangeByPageId

Pager::getPageRangeByPageId() – Returns offsets for given pageID.

Synopsis

require_once 'Pager.php';

array Pager::getPageRangeByPageId ( integer $pageid = null )

Description

Given a PageId, it returns the limits of the range of pages displayed. While getOffsetByPageId() returns the offset of the data within the current page, this method returns the offsets of the page numbers interval.

E.g., in "Jumping" mode, if you have pageId =3 and delta =10, it will return (1, 10). pageID =8 would give you (1, 10) as well, because 1 <= 8 <= 10. pageID =11 would give you (11, 20).

In "Sliding" mode, if you have pageId =5 and delta =2, it will return (3, 7). pageID of 9 would give you (4, 8).

if the method is called without parameter, pageID is set to currentPage number

Parameter

  • integer $pageid - PageID to get offsets for

Return value

return array with first and last offsets

Prev | Pager | Next
Pager::getPageIdByOffset | PEAR Manual | Pager::getPageSelectBox


Pager::getPageSelectBox

Pager::getPageSelectBox

Pager::getPageSelectBox() – Returns a string with a XHTML SELECT menu, to choose the page to display.

Synopsis

require_once 'Pager.php';

array Pager::getPageSelectBox ( array $params , string $extraAttributes = '' )

Parameter

  • array $params (optional)

    • 'optionText' : text to show in each option. Use '%d' where you want to see the number of the page.

    • 'autoSubmit' : if true, add some js code to submit the form on the onChange event

  • string $extraAttributes (html attributes) Tag attributes or HTML attributes (id="foo" pairs), will be inserted in the <select> tag.

Description

Returns a string with a XHTML SELECT menu with the page numbers, useful as an alternative to the links

Example

This example shows how you can create a select box to let your users choose the number of the page to go to.

<?php
include 'Pager.php';

$params = array(
    'mode'       => 'Jumping',
    'perPage'    => 3,
    'delta'      => 2,
    'itemData'   => array('a','b','c','d','e',[...omissis...],'z'),
);
$pager = & Pager::factory($params);

$selectBoxParams = array(
    'optionText' => 'page %d',
    'autoSubmit' => true,
);
$selectBox = $pager->getPageSelectBox();

echo '<form action="' . htmlspecialchars($_SERVER['PHP_SELF']) . '" method="GET">';
echo $selectBox;
echo '<input type="submit" value="submit" />';
echo '</form>';
?>

Return value

return string with the XHTML SELECT menu.

Prev | Pager | Next
Pager::getPageRangeByPageId | PEAR Manual | Pager::getPreviousPageID


Pager::getPreviousPageID

Pager::getPreviousPageID

Pager::getPreviousPageID() – Returns previous page number.

Synopsis

require_once 'Pager.php';

mixed Pager::getPreviousPageID ( )

Description

If current page is first page this function returns FALSE, otherwise returns previous page number.

Return value

return Previous page number or FALSE.

Prev | Pager | Next
Pager::getPageSelectBox | PEAR Manual | Pager::getPerPageSelectBox


Pager::getPerPageSelectBox

Pager::getPerPageSelectBox

Pager::getPerPageSelectBox() – Returns a string with a XHTML SELECT menu, to choose how many items per page should be displayed.

Synopsis

require_once 'Pager.php';

array Pager::getPerPageSelectBox ( integer $start = 5 , integer $end = 30 , integer $step = 5 , boolean $showAllData = false , string $optionText = '%d' )

Parameter

  • integer $start - Min. number of items per page (optional)

  • integer $end - Max. number of items per page (optional)

  • integer $step - Increment between two options (optional)

  • boolean $showAllData - If true, perPage is set equal to totalItems (optional)

  • array $extraParams (optional)

    • 'optionText' : text to show in each option. Use '%d' where you want to see the number of pages selected.

    • 'attributes' : (html attributes) Tag attributes or HTML attributes (id="foo" pairs), will be inserted in the <select> tag.

    • 'checkMaxLimit' : if true, Pager checks if $end is bigger than $totalItems, and doesn't show the extra select options.

Description

Returns a string with a XHTML SELECT menu, useful for letting the user choose how many items per page should be displayed. If parameter useSessions is TRUE, this value is stored in a session var. The string isn't echoed right away so you can use it with template engines.

Example

This example shows how you can create a select box to let your users choose the number of items to display on each page.

<?php
include 'Pager/Pager.php';

$params = array(
    'mode'       => 'Jumping',
    'perPage'    => 3,
    'delta'      => 2,
    'itemData'   => array('a','b','c','d','e',[...omissis...],'z')
);
$pager = & Pager::factory($params);

$selectBox = $pager->getPerPageSelectBox();

echo '<form action="' . htmlspecialchars($_SERVER['PHP_SELF']) . '" method="GET">';
echo $selectBox;
echo '<input type="submit" value="submit" />';
echo '</form>';
?>

Return value

return string with the XHTML SELECT menu.

Prev | Pager | Next
Pager::getPreviousPageID | PEAR Manual | Pager::isFirstPage


Pager::isFirstPage

Pager::isFirstPage

Pager::isFirstPage() – Returns whether current page is first page

Synopsis

require_once 'Pager.php';

bool Pager::isFirstPage ( )

Return value

return TRUE or FALSE, wrt it is the first page or not.

Prev | Pager | Next
Pager::getPerPageSelectBox | PEAR Manual | Pager::isLastPage


Pager::isLastPage

Pager::isLastPage

Pager::isLastPage() – Returns whether current page is last page

Synopsis

require_once 'Pager.php';

bool Pager::isLastPage ( )

Return value

return TRUE or FALSE, wrt it is the last page or not.

Prev | Pager | Next
Pager::isFirstPage | PEAR Manual | Pager::isLastPageComplete


Pager::isLastPageComplete

Pager::isLastPageComplete

Pager::isLastPageComplete() – Returns whether last page is complete

Synopsis

require_once 'Pager.php';

bool Pager::isLastPageComplete ( )

Return value

return TRUE or FALSE, wrt the last page is complete (i.e. it has perPage values in the array for the last page) or not.

Prev | Pager | Next
Pager::isLastPage | PEAR Manual | Pager::numItems


Pager::numItems

Pager::numItems

Pager::numItems() – Returns number of items

Synopsis

require_once 'Pager.php';

int Pager_Sliding::numItems ( )

Return value

return integer - Number of items

Prev | Pager | Next
Pager::isLastPageComplete | PEAR Manual | Pager::numPages


Pager::numPages

Pager::numPages

Pager::numPages() – Returns number of pages

Synopsis

require_once 'Pager.php';

int Pager_Sliding::numPages ( )

Return value

return integer - Number of pages

Prev | Pager | Next
Pager::numItems | PEAR Manual | Pager::Pager


Pager::Pager

Pager::Pager

Pager::Pager() – Creates a pager instance

Synopsis

require_once 'Pager.php';

object &Pager ( array $options )

Deprecated

The constructor is deprecated in favour of the new factory() method, which is PHP5 compatible too.

Parameter

Pager constructor takes an associative array of parameters as input values. This is the complete list of these options:

  • itemData [array]

    Array of items to page.

  • totalItems [integer]

    Number of items to page (used only if itemData is not provided).

  • perPage [integer]

    Number of items to display on each page.

  • delta [integer]

    Number of page numbers to display before and after the current one.

  • mode [string]

    "Jumping" or "Sliding" -window - It determines pager behaviour.

  • expanded [boolean]

    if TRUE, window size is always 2*delta+1

  • linkClass [string]

    Name of CSS class used for link styling.

  • urlVar [string]

    Name of URL var used to indicate the page number. Default value is "pageID".

  • path [string]

    Complete path to the page (without the page name).

  • fileName [string]

    name of the page, with a "%d" if append == TRUE.

  • append [boolean]

    If TRUE pageID is appended as GET value to the URL. If FALSE it is embedded in the URL according to fileName specs.

  • altPrev [string]

    Alt text to display for prev page, on prev link. Default value is "previous page";

  • altNext [string]

    Alt text to display for next page, on next link. Default value is "next page";

  • altPage [string]

    Alt text to display before the page number. Default value is "page ".

  • prevImg [string]

    Something to display instead of "<<". It can be text such as "<< PREV" or an <img/> as well.

  • nextImg [string]

    Something to display instead of ">>". It can be text such as "NEXT >>" or an <img/> as well.

  • separator [string]

    What to use to separate numbers. It can be an <img/>, a comma, an hyphen, or whatever.

  • spacesBeforeSeparator [integer]

    Number of spaces before the separator.

  • spacesAfterSeparator [integer]

    Number of spaces after the separator.

  • firstPagePre [string]

    String used before first page number. It can be an <img/>, a "{", an empty string, or whatever.

  • firstPageText [string]

    String used in place of first page number.

  • firstPagePost [string]

    String used after first page number. It can be an <img/>, a "}", an empty string, or whatever.

  • lastPagePre [string]

    Similar to firstPagePre , but used for last page number.

  • lastPageText [string]

    Similar to firstPageText , but used for last page number.

  • lastPagePost [string]

    Similar to firstPagePost , but used for last page number.

  • curPageLinkClassName [string]

    Name of CSS class used for current page link.

  • clearIfVoid [boolean]

    if there's only one page, don't display pager (returns an empty string).

  • useSessions [boolean]

    if TRUE, number of items to display per page is stored in the $_SESSION[$_sessionVar] var.

  • closeSession [boolean]

    if TRUE, the session is closed just after R/W.

  • sessionVar [string]

    Name of the session var for perPage value. A value different from default can be useful when using more than one Pager istance in the page.

  • pearErrorMode [constant]

    PEAR_ERROR mode for raiseError(). Default is PEAR_ERROR_RETURN.

REQUIRED options are:

  • fileName IF append ==FALSE (default is TRUE)

  • itemData OR totalItems (if itemData is set, totalItems is overwritten)

Return value

object - a specific Pager instance or a PEAR_Error object, if fails

Prev | Pager | Next
Pager::numPages | PEAR Manual | Pager_Sliding


Pager_Sliding

Pager_Sliding

Data paging class which also builds links to the pages.

Table of Contents
  • Introduction -- Usage of Pager_Sliding
  • Pager (v.1.x) vs. Pager_Sliding -- Feature comparison of the two classes
  • Pager_Sliding::getCurrentPageID -- Returns current page number
  • Pager_Sliding::getLinks -- Returns back/next/first/last and page links, both as ordered and associative array.
  • Pager_Sliding::getNextPageID -- Returns next page number.
  • Pager_Sliding::getOffsetByPageId -- Returns offsets for given pageID.
  • Pager_Sliding::getPageData -- Returns an array of current pages data
  • Pager_Sliding::getPageIdByOffset -- Overload PEAR::Pager method. VOID.
  • Pager_Sliding::getPreviousPageID -- Returns previous page number.
  • Pager_Sliding::isFirstPage -- Returns whether current page is first page
  • Pager_Sliding::isLastPage -- Returns whether current page is last page
  • Pager_Sliding::isLastPageComplete -- Returns whether last page is complete
  • Pager_Sliding::numItems -- Returns number of items
  • Pager_Sliding::numPages -- Returns number of pages
  • Pager_Sliding::Sliding -- Creates a pager instance
Prev | HTML | Next
Pager::Pager | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Usage of Pager_Sliding

What is Pager_Sliding?

Pager_Sliding is a class to page an array of data. It is taken as input and it is paged according to various parameters. Pager_Sliding also builds links within a specified range, and allows complete customization of the output (it even works with mod_rewrite). It is compatible with PEAR::Pager's API

Deprecated

This package is deprecated in favour of the new Pager v.2.x.

Example 1

This simple example will page the array of alphabetical letters, giving back pages with 3 letters per page, and links to the previous two / next two pages:

<?php
require_once 'Pager/Sliding.php';
$params = array(
            'perPage'    => 3,
            'delta'      => 2,
            'itemData'   => array('a','b','c','d','e',[...omissis...],'z')
            );
$pager = & new Pager_Sliding($params);
$data  = $pager->getPageData();
$links = $pager->getLinks();
//$links is an ordered+associative array with 'back'/'pages'/'next'/'first'/'last'/'all' links.
//NB: $links['all'] is the same as $pager->links;

//echo links to other pages:
echo $links['all']

//Show data for current page:
echo 'PAGED DATA: ' ; print_r($data);

//Results from methods:
echo 'getCurrentPageID()...: '; var_dump($pager->getCurrentPageID());
echo 'getNextPageID()......: '; var_dump($pager->getNextPageID());
echo 'getPreviousPageID()..: '; var_dump($pager->getPreviousPageID());
echo 'numItems()...........: '; var_dump($pager->numItems());
echo 'numPages()...........: '; var_dump($pager->numPages());
echo 'isFirstPage()........: '; var_dump($pager->isFirstPage());
echo 'isLastPage().........: '; var_dump($pager->isLastPage());
echo 'isLastPageComplete().: '; var_dump($pager->isLastPageComplete());
echo '$pager->range........: '; var_dump($pager->range);
?>

In case you're wondering, $pager->range is a numeric array; its keys are the numbers of the pages in the current range, and the matching values are booleans (TRUE if its key represents currentPage, FALSE otherwise). This array can be useful to build the links manually, e.g. when using a template engine.

Example 2

This example shows how you can use this class with mod_rewite. Let's suppose we have a .htaccess like this:

---------
RewriteEngine on
#Options FollowSymlinks

RewriteBase /
RewriteRule ^articles/([a-z]{1,12})/art([0-9]{1,4})\.html$ /article.php?num=$2&amp;month=$1 [L]
---------

It should transform an url like "/articles/march/art15.html" into "/article.php?num=15&month=march"

<?php
require_once 'Pager/Sliding.php';

$month = 'september';
$params = array(
            'append'    => false,
            'urlVar'    => 'num',
            'path'      => 'http://myserver.com/articles/' . $month,
            'fileName'  => 'art%d.html',  //Pager replaces "%d" with page number...
            'itemData'  => array('a','b','c',[...omissis...],'z'),
            'perPage'   => 3
            );
$pager = & new Pager_Sliding($params);

$data  = $pager->getPageData();
echo $pager->links;
echo 'Data for current page: '; print_r($data);
?>

More pagers in a single page

Using more than one pager in a single page is as simple as using a different urlVar for each pager:

<?php
require_once 'Pager/Sliding.php';

//first pager
$params1 = array(
            'perPage'    => 3,
            'urlVar'     => pageID_articles,  //1st identifier
            'itemData'   => $someArray
            );
$pager1 = & new Pager_Sliding($params1);
$data1  = $pager1->getPageData();
$links1 = $pager1->getLinks();

//second pager
$params2 = array(
            'perPage'    => 8,
            'urlVar'     => pageID_news,      //2nd identifier
            'itemData'   => $someOtherArray
            );
$pager2 = & new Pager_Sliding($params2);
$data2  = $pager2->getPageData();
$links2 = $pager2->getLinks();
?>
Prev | Pager_Sliding | Next
Pager_Sliding | PEAR Manual | Pager (v.1.x) vs. Pager_Sliding


Pager (v.1.x) vs. Pager_Sliding

Pager (v.1.x) vs. Pager_Sliding

Pager (v.1.x) vs. Pager_Sliding – Feature comparison of the two classes

What are the differences with Pager?

While Pager v.1.x has a "jumping window" style, Pager_Sliding has a "sliding window" style. What does that mean? Let's see an example:

Pager v.1.x logic

Let's suppose that the data spans on 15 pages, and the window width is 5 page links. The links are built on "frames" of 5 pages each: [1-5] [6-10] [11-15] Pager v.1.x always shows the same 5 page links while you are on one of these pages. Here's a temporal succession of the links, starting from page 1 and moving forward. There are brakets around current page number to highlight this:

<?php
a)    {1} 2  3  4  5  =>   // first frame: [1-5]
b) <=  1 {2} 3  4  5  =>
c) <=  1  2 {3} 4  5  =>
d) <=  1  2  3 {4} 5  =>
e) <=  1  2  3  4 {5} =>   // HERE IT JUMPS TO THE NEXT FRAME
f) <= {6} 7  8  9 10  =>   // second frame: [6-10]
g) <=  6 {7} 8  9 10  =>
h) <=  6  7 {8} 9 10  =>
?>

and so on. See what a "jumping window" frame is? When you reach a limit (in the example, you go from page 5 to page 6), it "jumps" to next frame (links from page 6 to 10).

Pager_Sliding logic

Instead of jumping from one frame to the other, with Pager_Sliding the change is done smoothly, and the current page is always shown at the center of the "window" (except of course for the first and the last pages):

<?php
a)       {1} 2  3  4  5  => [15]
b) [1] <= 1 {2} 3  4  5  => [15]
c) [1] <= 1  2 {3} 4  5  => [15]  // HERE IT's STARTING WORKING AS DESIGNED
d) [1] <= 2  3 {4} 5  6  => [15]  // see: current page number is at the center of the window
e) [1] <= 3  4 {5} 6  7  => [15]  // and it stays there...
f) [1] <= 4  5 {6} 7  8  => [15]
g) [1] <= 5  6 {7} 8  9  => [15]
h) [1] <= 6  7 {8} 9 10  => [15]
?>

and so on.

Other differences

Apart from the different "philosophy", Pager_Sliding is also designed to be highly customizable.

UPDATE: since Pager 2.x release, every option once only available in Pager_Sliding is now fully implemented in Pager too, and more. As stated in the Intro, Pager_Sliding is now deprecated in favour of the new Pager v.2.x. You can have both behaviours ("Jumping" and "Sliding") in Pager v.2.x, just change the mode . Please refer to Pager docs for more details.

  • There are *many* options to change the look and feel of the links in your page. They are explained in the constructor docs.

  • It can work with Apache mod_rewrite module too, see the examples for that.

  • It is "template"-friendly, i.e. you can assign the processed links and page numbers to your custom vars and use them to draw your link bar according to your page layout, without worrying about the underlying logic.

  • You can easily extend the class; this is useful if you plan to use the class in many different pages and you don't want to set the same options everytime: just set your preferred default values in your extending class and you're done!

Prev | Pager_Sliding | Next
Introduction | PEAR Manual | Pager_Sliding::getCurrentPageID


Pager_Sliding::getCurrentPageID

Pager_Sliding::getCurrentPageID

Pager_Sliding::getCurrentPageID() – Returns current page number

Synopsis

require_once 'Pager/Sliding.php';

integer getCurrentPageID ( )

Return value

integer - Current page number.

Prev | Pager_Sliding | Next
Pager (v.1.x) vs. Pager_Sliding | PEAR Manual | Pager_Sliding::getLinks


Pager_Sliding::getLinks

Pager_Sliding::getLinks

Pager_Sliding::getLinks() – Returns back/next/first/last and page links, both as ordered and associative array.

Synopsis

require_once 'Pager/Sliding.php';

array Pager_Sliding::getLinks ( integer $pageID = null )

Parameter

  • integer $pageID - Optional pageID. If specified, linksfor that page are provided instead of current one.

Return value

return back/pages/next/first/last/all links, both as numeric and associative array.

Prev | Pager_Sliding | Next
Pager_Sliding::getCurrentPageID | PEAR Manual | Pager_Sliding::getNextPageID


Pager_Sliding::getNextPageID

Pager_Sliding::getNextPageID

Pager_Sliding::getNextPageID() – Returns next page number.

Synopsis

require_once 'Pager/Sliding.php';

mixed Pager_Sliding::getNextPageID ( )

Description

If current page is last page this function returns FALSE, otherwise returns next page number.

Return value

return Next page number or FALSE

Prev | Pager_Sliding | Next
Pager_Sliding::getLinks | PEAR Manual | Pager_Sliding::getOffsetByPageId


Pager_Sliding::getOffsetByPageId

Pager_Sliding::getOffsetByPageId

Pager_Sliding::getOffsetByPageId() – Returns offsets for given pageID.

Synopsis

require_once 'Pager/Sliding.php';

array Pager_Sliding::getOffsetByPageId ( integer $pageid = null )

Description

Eg, if you pass it pageID = 5 and your delta is 2 it will return you 3 and 7. PageID of 6 would give you 4 and 8

NB: The behaviour of this function could be misleading: it was left only for compatibility with PEAR::Pager. It could raise some confusion when pageID is within delta positions from an extreme: in fact this method returns also the extremes, while $this->_getPageLinks leaves them out. Pager_Sliding works this way: if pageID is NOT an extreme, show first and last page within brackets: [1] << 5 | _6_ | 7 >> [15] So when dealing with pageID within delta positions from an extreme, this method would return the extreme as well, while $this->_getPageLinks would return (for instance) 2 | _3_ | 4 | 5 even if pageID is 3 and delta is 2. Consider this method deprecated and/or subject to changes.

Parameter

  • integer $pageid - PageID to get offsets for

Return value

return array with first and last offsets

Deprecated

deprecated

Prev | Pager_Sliding | Next
Pager_Sliding::getNextPageID | PEAR Manual | Pager_Sliding::getPageData


Pager_Sliding::getPageData

Pager_Sliding::getPageData

Pager_Sliding::getPageData() – Returns an array of current pages data

Synopsis

require_once 'Pager/Sliding.php';

array Pager_Sliding::getPageData ( integer $pageID = null )

Parameter

  • integer $pageID - Desired page ID (optional)

Return value

return array of data for this page.

Prev | Pager_Sliding | Next
Pager_Sliding::getOffsetByPageId | PEAR Manual | Pager_Sliding::getPageIdByOffset


Pager_Sliding::getPageIdByOffset

Pager_Sliding::getPageIdByOffset

Pager_Sliding::getPageIdByOffset() – Overload PEAR::Pager method. VOID.

Synopsis

require_once 'Pager/Sliding.php';

array Pager_Sliding::getPageIdByOffset ( integer $index )

Parameter

  • integer $index - Offset to get pageID for

Return value

return Page number for this offset

Deprecated

deprecated. It is only here for compatibility with PEAR::Pager.

Prev | Pager_Sliding | Next
Pager_Sliding::getPageData | PEAR Manual | Pager_Sliding::getPreviousPageID


Pager_Sliding::getPreviousPageID

Pager_Sliding::getPreviousPageID

Pager_Sliding::getPreviousPageID() – Returns previous page number.

Synopsis

require_once 'Pager/Sliding.php';

mixed Pager_Sliding::getPreviousPageID ( )

Description

If current page is first page this function returns FALSE, otherwise returns previous page number.

Return value

return Previous page number or FALSE.

Prev | Pager_Sliding | Next
Pager_Sliding::getPageIdByOffset | PEAR Manual | Pager_Sliding::isFirstPage


Pager_Sliding::isFirstPage

Pager_Sliding::isFirstPage

Pager_Sliding::isFirstPage() – Returns whether current page is first page

Synopsis

require_once 'Pager/Sliding.php';

bool Pager_Sliding::isFirstPage ( )

Return value

return TRUE or FALSE, wrt it is the first page or not.

Prev | Pager_Sliding | Next
Pager_Sliding::getPreviousPageID | PEAR Manual | Pager_Sliding::isLastPage


Pager_Sliding::isLastPage

Pager_Sliding::isLastPage

Pager_Sliding::isLastPage() – Returns whether current page is last page

Synopsis

require_once 'Pager/Sliding.php';

bool Pager_Sliding::isLastPage ( )

Return value

return TRUE or FALSE, wrt it is the last page or not.

Prev | Pager_Sliding | Next
Pager_Sliding::isFirstPage | PEAR Manual | Pager_Sliding::isLastPageComplete


Pager_Sliding::isLastPageComplete

Pager_Sliding::isLastPageComplete

Pager_Sliding::isLastPageComplete() – Returns whether last page is complete

Synopsis

require_once 'Pager/Sliding.php';

bool Pager_Sliding::isLastPageComplete ( )

Return value

return TRUE or FALSE, wrt the last page is complete (i.e. it has perPage values in the array for the last page) or not.

Prev | Pager_Sliding | Next
Pager_Sliding::isLastPage | PEAR Manual | Pager_Sliding::numItems


Pager_Sliding::numItems

Pager_Sliding::numItems

Pager_Sliding::numItems() – Returns number of items

Synopsis

require_once 'Pager/Sliding.php';

int Pager_Sliding::numItems ( )

Return value

return integer - Number of items

Prev | Pager_Sliding | Next
Pager_Sliding::isLastPageComplete | PEAR Manual | Pager_Sliding::numPages


Pager_Sliding::numPages

Pager_Sliding::numPages

Pager_Sliding::numPages() – Returns number of pages

Synopsis

require_once 'Pager/Sliding.php';

int Pager_Sliding::numPages ( )

Return value

return integer - Number of pages

Prev | Pager_Sliding | Next
Pager_Sliding::numItems | PEAR Manual | Pager_Sliding::Sliding


Pager_Sliding::Sliding

Pager_Sliding::Sliding

Pager_Sliding::Sliding() – Creates a pager instance

Synopsis

require_once 'Pager/Sliding.php';

object &Sliding ( array $options )

Parameter

Pager_Sliding constructor takes an associative array of parameters as input values. This is the complete list of these options:

  • itemData [array]

    Array of items to page.

  • totalItems [integer]

    Number of items to page (used only if itemData is not provided).

  • perPage [integer]

    Number of items to display on each page.

  • delta [integer]

    Number of page numbers to display before and after the current one.

  • expanded [boolean]

    if TRUE, window size is always 2*delta+1

  • linkClass [string]

    Name of CSS class used for link styling.

  • urlVar [string]

    Name of URL var used to indicate the page number. Default value is "pageID".

  • path [string]

    Complete path to the page (without the page name).

  • fileName [string]

    name of the page, with a "%d" if append == TRUE.

  • append [boolean]

    If TRUE pageID is appended as GET value to the URL. If FALSE it is embedded in the URL according to fileName specs.

  • altPrev [string]

    Alt text to display for prev page, on prev link. Default value is "previous page";

  • altNext [string]

    Alt text to display for next page, on next link. Default value is "next page";

  • altPage [string]

    Alt text to display before the page number. Default value is "page ".

  • prevImg [string]

    Something to display instead of "<<". It can be text such as "<< PREV" or an <img/> as well.

  • nextImg [string]

    Something to display instead of ">>". It can be text such as "NEXT >>" or an <img/> as well.

  • separator [string]

    What to use to separate numbers. It can be an <img/>, a comma, an hyphen, or whatever.

  • spacesBeforeSeparator [integer]

    Number of spaces before the separator.

  • spacesAfterSeparator [integer]

    Number of spaces after the separator.

  • firstPagePre [string]

    String used before first page number. It can be an <img/>, a "{", an empty string, or whatever.

  • firstPagePost [string]

    String used after first page number. It can be an <img/>, a "}", an empty string, or whatever.

  • lastPagePre [string]

    Similar to firstPagePre , but used for last page number.

  • lastPagePost [string]

    Similar to firstPagePost , but used for last page number.

  • curPageLinkClassName [string]

    Name of CSS class used for current page link.

  • lastPagePost [boolean]

    if there's only one page, don't display pager (returns an empty string).

REQUIRED options are:

  • fileName IF append ==FALSE (default is TRUE)

  • itemData OR totalItems (if itemData is set, totalItems is overwritten)

Return value

object - a specific Pager_Sliding instance or a PEAR_Error object, if fails

Prev | Pager_Sliding | Next
Pager_Sliding::numPages | PEAR Manual | HTTP


HTTP

HTTP

Provides Packages for working with the Hyper-Text-Transfer-Protocol.

Table of Contents
  • HTTP
  • HTTP_Client
  • HTTP_Download
  • HTTP_Request
  • HTTP_Session
  • HTTP_Session2
  • HTTP_Upload
Prev | PEAR Packages | Next
Pager_Sliding::Sliding | PEAR Manual | HTTP


HTTP

HTTP

Provides a set of usefull, static functions related to the Hyper-Text-Transfer-Protocol.

Table of Contents
  • HTTP::Date -- format a date
  • HTTP::head -- sends a "HEAD" command
  • HTTP::negotiateLanguage -- Negotiate language with the user's browser
  • HTTP::redirect -- redirects the client
Prev | HTTP | Next
HTTP | PEAR Manual | HTTP::Date


HTTP::Date

HTTP::Date

HTTP::Date – format a date

Synopsis

require_once 'HTTP.php';

string HTTP::date ( integer time )

Description

Converts a UNIX timestamp into an RFC compliant HTTP header line. This function honors the "y2k_compliance" php.ini directive.

Parameter

  • integer $time - a UNIX timestamp

Return value

string - a RFC compliant date header line

Note

This function can be called statically.

Prev | HTTP | Next
HTTP | PEAR Manual | HTTP::head


HTTP::head

HTTP::head

HTTP::head – sends a "HEAD" command

Synopsis

require_once 'HTTP.php';

array HTTP::head ( string $url )

Description

Sends a "HEAD" HTTP command to a server and returns the headers in an associative array.

Example

HEAD request to example.com

<?php
require_once "PEAR.php";
require_once "HTTP.php";

$result = HTTP::head("http://example.com/");

if (PEAR::isError($result)) {
    echo "Error: " . $result->getMessage();
} else {
    echo "<pre>";
    print_r($result);
    echo "</pre>";
}
?>

The output of the print_r() call is shown below.

Parameter

  • string $url - a valid absolute URL

Return value

array - an array containing the header lines or a PEAR_Error.

Example output:

<?php
Array
(
    [response_code] => 200
    [response] => HTTP/1.1 200 OK
    [Date] => Tue, 25 Nov 2003 22:08:57 GMT
    [Server] => Apache/1.3.27 (Unix)  (Red-Hat/Linux)
    [Last-Modified] => Wed, 08 Jan 2003 23:11:55 GMT
    [ETag] => "3f80f-1b6-3e1cb03b"
    [Accept-Ranges] => bytes
    [Content-Length] => 438
    [Connection] => close
    [Content-Type] => text/html
)
?>

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "HTTP::head Error $errstr ($erno )" | Connection to server failed | Check connectivity of your host and the given URL in $url

Note

This function can be called statically.

Prev | HTTP | Next
HTTP::Date | PEAR Manual | HTTP::negotiateLanguage


HTTP::negotiateLanguage

HTTP::negotiateLanguage

HTTP::negotiateLanguage – Negotiate language with the user's browser

Synopsis

require_once 'HTTP.php';

string HTTP::negotiateLanguage ( array $supported , string $default = 'en_US' )

Description

Negotiate language with the user's browser through the Accept-Language HTTP header or the user's host address. Language codes are generally in the form "ll" for a language spoken in only one country, or "ll-CC" for a language spoken in a particular country. For example, U.S. English is "en-US", while British English is "en-UK". Portugese as spoken in Portugal is "pt-PT", while Brazilian Portugese is "pt-BR". Two-letter country codes can be found in the ISO 3166 standard.

Quantities in the Accept-Language: header are supported, for example:

Accept-Language: en-UK;q=0.7, en-US;q=0.6, no;q=1.0, dk;q=0.8

Example

Usage example

<?php
require_once "HTTP.php";

$supported = array("de" => true, "en-US" => true);

echo HTTP::negotiateLanguage($supported);
?>

This example negotiates with the user agent if any of the languages, which are specified in supported, are supported on the user's system. If the negotiation has a positive result, the language code of the most preferred language is printed. Otherwise the default language code (en-US) is printed.

Being able to perform language negotiation is a big help when developing internationalized website with pages, that are available in more than one language. Using negotiation, the user will always get pages in the language which he prefers. (Assuming that their user agent is configured properly.)

Parameter

  • array $supported - an associative array indexed by language codes (country codes) supported by the application. Values must evaluate to TRUE.

  • string $default - the default language that should be used if none of the other languages are found during negotiation.

Return value

string - a language code

Note

This function can be called statically.

The returned language is only a hint! Sending the accepted languages by the client is optional. The language settings of the browser do not have to meet the user's native language - for example a german traveller in a spanish internet cafe. You can improve your result by combining it with the result of the Net_Geo package. Apart from that, you should still give the user the chance to manually choose their preferred language menu.

Prev | HTTP | Next
HTTP::head | PEAR Manual | HTTP::redirect


HTTP::redirect

HTTP::redirect

HTTP::redirect – redirects the client

Synopsis

require_once 'HTTP.php';

void HTTP::redirect ( string url )

Description

This function redirects the client. This is done by issuing a Location: header and exiting.

Example

Redirecting to another site

<?php
require_once 'HTTP.php';

HTTP::redirect("http://example.com/");
?>

Local redirect

<?php
require_once 'HTTP.php';

HTTP::redirect("/foo.php");
?>

This will redirect the client to /foo.php. The method will take care of adding the right hostname as required by RFC 2616.

Parameter

  • string $url - the new URL, where to client should be redirected to.

Note

This function can be called statically.

Avoid sending any kind of data to the client before calling redirect().

The location header requires an absolute URL. If not given, redirect() tries to build one from $url . So if the redirect fails, set the absolute URL manually as argument.

Prev | HTTP | Next
HTTP::negotiateLanguage | PEAR Manual | HTTP_Client


HTTP_Client

HTTP_Client

Table of Contents
  • Class Summary HTTP_Client -- A simple HTTP client class.
  • constructor HTTP_Client::HTTP_Client() -- Constructor
  • HTTP_Client::attach() -- Adds a Listener to the list of listeners that are notified of the object's events
  • HTTP_Client::currentResponse() -- Returns the most recent HTTP response
  • HTTP_Client::detach() -- Removes a Listener from the list of listeners
  • HTTP_Client::get() -- Sends a 'GET' HTTP request
  • HTTP_Client::head() -- Sends a 'HEAD' HTTP request
  • HTTP_Client::post() -- Sends a 'POST' HTTP request
  • HTTP_Client::reset() -- Clears object's internal properties
  • HTTP_Client::setDefaultHeader() -- Sets default header(s) for HTTP requests
  • HTTP_Client::setMaxRedirects() -- Sets the maximum number of redirects that will be processed.
  • HTTP_Client::setRequestParameter() -- Sets parameter(s) for HTTP requests
  • Class Summary HTTP_Client_CookieManager -- Stores cookies and passes them between HTTP requests.
  • constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager() -- Constructor
  • HTTP_Client_CookieManager::addCookie() -- Explicitly adds cookie to the list
  • HTTP_Client_CookieManager::passCookies() -- Adds cookies to the request
  • HTTP_Client_CookieManager::reset() -- Clears the cookies list
  • HTTP_Client_CookieManager::updateCookies() -- Updates cookie list from HTTP server response
Prev | HTTP | Next
HTTP::redirect | PEAR Manual | Class Summary HTTP_Client


Class Summary HTTP_Client

Class Summary HTTP_Client

Class Summary HTTP_Client – A simple HTTP client class.

HTTP_Client

A simple HTTP client class. The class wraps around HTTP_Request providing a higher-level API for performing multiple HTTP requests. It handles HTTP redirects, stores cookies and sets referrers between requests.

Class Trees for HTTP_Client

  • HTTP_Client

Prev | HTTP_Client | Next
HTTP_Client | PEAR Manual | constructor HTTP_Client::HTTP_Client()


constructor HTTP_Client::HTTP_Client()

constructor HTTP_Client::HTTP_Client()

constructor HTTP_Client::HTTP_Client() – Constructor

Synopsis

require_once 'HTTP/Client.php';

void constructor HTTP_Client::HTTP_Client ( array $defaultRequestParams = null , array $defaultHeaders = null )

Description

Sets default request parameters and default headers.

Parameter

array $defaultRequestParams

Parameters to pass to HTTP_Request's constructor

array $defaultHeaders

Default headers to send on every request

Throws

throws no exceptions thrown

See

see setDefaultHeader(), setRequestParameter()

Note

This function can not be called statically.

Prev | HTTP_Client | Next
Class Summary HTTP_Client | PEAR Manual | HTTP_Client::attach()


HTTP_Client::attach()

HTTP_Client::attach()

HTTP_Client::attach() – Adds a Listener to the list of listeners that are notified of the object's events

Synopsis

require_once 'HTTP/Client.php';

boolean HTTP_Client::attach ( object HTTP_Request_Listener &$listener , boolean $propagate = false )

Description

The attached Listeners are notified of the following events:

'request'

sent before a HTTP request that is not a result of previous redirect.

'httpSuccess'

sent upon receiving a successfull 2xx response (or 3xx response, if it is not a redirect or if redirect processing is disabled).

'httpRedirect'

sent when a 3xx redirection response is received, before following a redirect

'httpError'

sent on 4xx, 5xx response

If $propagate is TRUE the Listener will be attached to the created HTTP_Request objects and will be notified of their events as well.

Parameter

object HTTP_Request_Listener &$listener

Listener instance to attach

boolean $propagate

Whether the listener should be attached to the created HTTP_Request objects

Return value

returns whether the listener was successfully attached

Throws

throws no exceptions thrown

See

see detach()

Note

This function can not be called statically.

Prev | HTTP_Client | Next
constructor HTTP_Client::HTTP_Client() | PEAR Manual | HTTP_Client::currentResponse()


HTTP_Client::currentResponse()

HTTP_Client::currentResponse()

HTTP_Client::currentResponse() – Returns the most recent HTTP response

Synopsis

require_once 'HTTP/Client.php';

array& HTTP_Client::currentResponse ( )

Description

The returned array has the following keys: 'code', 'headers', 'body'.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::attach() | PEAR Manual | HTTP_Client::detach()


HTTP_Client::detach()

HTTP_Client::detach()

HTTP_Client::detach() – Removes a Listener from the list of listeners

Synopsis

require_once 'HTTP/Client.php';

boolean HTTP_Client::detach ( object HTTP_Request_Listener &$listener )

Description

This package is not documented yet.

Parameter

object HTTP_Request_Listener &$listener

Listener instance to detach

Return value

returns whether the listener was successfully detached

Throws

throws no exceptions thrown

See

see attach()

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::currentResponse() | PEAR Manual | HTTP_Client::get()


HTTP_Client::get()

HTTP_Client::get()

HTTP_Client::get() – Sends a 'GET' HTTP request

Synopsis

require_once 'HTTP/Client.php';

integer HTTP_Client::get ( string $url , mixed $data = null , boolean $preEncoded = false )

Description

This package is not documented yet.

Parameter

string $url

URL

mixed $data

additional data to send

boolean $preEncoded

Whether the data is already urlencoded

Return value

returns HTTP response code

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::detach() | PEAR Manual | HTTP_Client::head()


HTTP_Client::head()

HTTP_Client::head()

HTTP_Client::head() – Sends a 'HEAD' HTTP request

Synopsis

require_once 'HTTP/Client.php';

integer HTTP_Client::head ( string $url )

Description

This package is not documented yet.

Parameter

string $url

URL

Return value

returns HTTP response code

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::get() | PEAR Manual | HTTP_Client::post()


HTTP_Client::post()

HTTP_Client::post()

HTTP_Client::post() – Sends a 'POST' HTTP request

Synopsis

require_once 'HTTP/Client.php';

integer HTTP_Client::post ( string $url , mixed $data , boolean $preEncoded = false , array $files = array() )

Description

This package is not documented yet.

Parameter

string $url

URL

mixed $data

Data to send

boolean $preEncoded

Whether the data is already urlencoded

array $files

Files to upload. Elements of the array should have the form: array(name, filename(s)[, content type]), see HTTP_Request::addFile()

Return value

returns HTTP response code

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::head() | PEAR Manual | HTTP_Client::reset()


HTTP_Client::reset()

HTTP_Client::reset()

HTTP_Client::reset() – Clears object's internal properties

Synopsis

require_once 'HTTP/Client.php';

void HTTP_Client::reset ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::post() | PEAR Manual | HTTP_Client::setDefaultHeader()


HTTP_Client::setDefaultHeader()

HTTP_Client::setDefaultHeader()

HTTP_Client::setDefaultHeader() – Sets default header(s) for HTTP requests

Synopsis

require_once 'HTTP/Client.php';

void HTTP_Client::setDefaultHeader ( mixed $name , string $value = null )

Description

These are standard HTTP headers that will be sent by all created HTTP_Request objects.

Parameter

mixed $name

header name or array ('header name' => 'header value')

string $value

header value if $name is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::reset() | PEAR Manual | HTTP_Client::setMaxRedirects()


HTTP_Client::setMaxRedirects()

HTTP_Client::setMaxRedirects()

HTTP_Client::setMaxRedirects() – Sets the maximum number of redirects that will be processed.

Synopsis

require_once 'HTTP/Client.php';

void HTTP_Client::setMaxRedirects ( int $value )

Description

Setting this value to 0 disables redirect processing. If it is not 0 and the number of redirects after a request is bigger than this number, then an error will be raised.

Parameter

integer $value

Max number of redirects to process

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::setDefaultHeader() | PEAR Manual | HTTP_Client::setRequestParameter()


HTTP_Client::setRequestParameter()

HTTP_Client::setRequestParameter()

HTTP_Client::setRequestParameter() – Sets parameter(s) for HTTP requests

Synopsis

require_once 'HTTP/Client.php';

void HTTP_Client::setRequestParameter ( mixed $name , string $value = null )

Description

These parameters will be passed to constructors of created HTTP_Request instances.

Parameter

mixed $name

parameter name or array ('parameter name' => 'parameter value')

string $value

parameter value if $name is not an array

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client::setMaxRedirects() | PEAR Manual | Class Summary HTTP_Client_CookieManager


Class Summary HTTP_Client_CookieManager

Class Summary HTTP_Client_CookieManager

Class Summary HTTP_Client_CookieManager – Stores cookies and passes them between HTTP requests.

HTTP_Client_CookieManager

Stores cookies and passes them between HTTP requests. While this class is a part of HTTP_Client package, it can be used separately.

Class Trees for HTTP_Client_CookieManager

  • HTTP_Client_CookieManager

Prev | HTTP_Client | Next
HTTP_Client::setRequestParameter() | PEAR Manual | constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()


constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()

constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()

constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager() – Constructor

Synopsis

require_once 'HTTP/Client/CookieManager.php';

void constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
Class Summary HTTP_Client_CookieManager | PEAR Manual | HTTP_Client_CookieManager::addCookie()


HTTP_Client_CookieManager::addCookie()

HTTP_Client_CookieManager::addCookie()

HTTP_Client_CookieManager::addCookie() – Explicitly adds cookie to the list

Synopsis

require_once 'ClientCookieManager.php';

void HTTP_Client_CookieManager::addCookie ( array $cookie )

Description

This package is not documented yet.

Parameter

array $cookie

An array representing cookie, this function expects all of the array's fields ('name', 'value', 'domain', 'path', 'expires', 'secure') to be set.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager() | PEAR Manual | HTTP_Client_CookieManager::passCookies()


HTTP_Client_CookieManager::passCookies()

HTTP_Client_CookieManager::passCookies()

HTTP_Client_CookieManager::passCookies() – Adds cookies to the request

Synopsis

require_once 'HTTP/Client/CookieManager.php';

void HTTP_Client_CookieManager::passCookies ( object An &$request )

Description

The method sends only the cookies that should be sent with the request and it adds them in right order.

Parameter

object HTTP_Request &$request

HTTP_Request object

Throws

throws no exceptions thrown

See

see updateCookies(), addCookie()

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client_CookieManager::addCookie() | PEAR Manual | HTTP_Client_CookieManager::reset()


HTTP_Client_CookieManager::reset()

HTTP_Client_CookieManager::reset()

HTTP_Client_CookieManager::reset() – Clears the cookies list

Synopsis

require_once 'HTTP/Client/CookieManager.php';

void HTTP_Client_CookieManager::reset ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client_CookieManager::passCookies() | PEAR Manual | HTTP_Client_CookieManager::updateCookies()


HTTP_Client_CookieManager::updateCookies()

HTTP_Client_CookieManager::updateCookies()

HTTP_Client_CookieManager::updateCookies() – Updates cookie list from HTTP server response

Synopsis

require_once 'HTTP/Client/CookieManager.php';

void HTTP_Client_CookieManager::updateCookies ( object HTTP_Request &$request )

Description

This method gets the cookies from HTTP response received by HTTP_Request instance and adds them to the object's internal list.

Parameter

object HTTP_Request &$request

HTTP_Request object containing the HTTP response, i.e. its sendRequest() should already be called.

Throws

throws no exceptions thrown

See

see passCookies(), addCookie()

Note

This function can not be called statically.

Prev | HTTP_Client | Next
HTTP_Client_CookieManager::reset() | PEAR Manual | HTTP_Download


HTTP_Download

HTTP_Download

Send HTTP Downloads

Table of Contents
  • Intro -- Introduction in usage of HTTP_Download
  • HTTP_Download::HTTP_Download -- Constructor
  • HTTP_Download::setParams -- Set various parameters
  • HTTP_Download::setFile -- Set file path
  • HTTP_Download::setData -- Set raw data
  • HTTP_Download::setResource -- Set resource for download
  • HTTP_Download::setGzip -- Whether to gzip the download on the fly or not. (requires ext/zlib)
  • HTTP_Download::setCache -- Whether to allow caching of the download on the clients side.
  • HTTP_Download::setCacheControl -- Control cache privacy and validity.
  • HTTP_Download::setBufferSize -- Set size of buffer in bytes.
  • HTTP_Download::setThrottleDelay -- Set throttle delay in seconds
  • HTTP_Download::setContentType -- Set content type
  • HTTP_Download::setLastModified -- Set "Last-Modified"
  • HTTP_Download::setContentDisposition -- Set content disposition
  • HTTP_Download::guessContentType -- Guess content type of file
  • HTTP_Download::send -- Send file
  • HTTP_Download::staticSend -- Static send
  • HTTP_Download::sendArchive -- Send an archive created on the fly
Prev | HTTP | Next
HTTP_Client_CookieManager::updateCookies() | PEAR Manual | Intro


Intro

Intro

Intro – Introduction in usage of HTTP_Download

Introduction

HTTP_Download provides an interface to easily send any arbitrary data to HTTP clients. HTTP_Download can gain its data from variables, files or stream resources.

With this package you can easily handle (hidden) downloads. Hidden means not accessible by the public - for instance if you want to restrict access to particular downloads.

It supports HTTP compression, caching and partial downloads, resuming and sending raw data, for example from database BLOBs.

ATTENTION: You shouldn't use this package together with ob_gzhandler or zlib.output_compression enabled in your php.ini, especially if you want to send already gzipped data!

Usage Examples:

Have a look at the following examples:

Static send:

<?php
1  $params = array(
2   'file'                => '../hidden/download.tgz',
3   'contenttype'         => 'application/x-gzip',
4   'contentdisposition'  => array(HTTP_DOWNLOAD_ATTACHMENT, 'latest.tgz'),
5  );
6
7  $error = HTTP_Download::staticSend($params, false);
?>

Send a hidden file:

<?php
1  $dl = &new HTTP_Download();
2  $dl->setFile('../hidden/download.tgz');
3  $dl->setContentDisposition(HTTP_DOWNLOAD_ATTACHMENT, 'latest.tgz');
4  // with ext/magic.mime
5  // $dl->guessContentType();
6  // else:
7  $dl->setContentType('application/x-gzip');
8  $dl->send();
?>

Send arbitrary data:

<?php
1  $dl = &new HTTP_Download();
2  $dl->setData($data);
3  $dl->setLastModified($unix_timestamp);
4  $dl->setContentType('application/x-gzip');
5  $dl->setContentDisposition(HTTP_DOWNLOAD_ATTACHMENT, 'latest.tgz');
6  $dl->send();
?>

Limiting bandwidth:

<?php
1  $dl = &new HTTP_Download();
2  $dl->setFile('huge_file.bin');
3  $dl->setBufferSize(25 * 1024); // 25 K
4  $dl->setThrottleDelay(1);   // 1 sec
5  $dl->send();
?>

Sending a PostgreSQL LOB:

<?php
1  require_once 'HTTP/Download.php';
2  require_once 'HTTP/Download/PgLOB.php';
3  $dl = &new HTTP_Download();
4  $dl->setResource(
5    HTTP_Download_PgLOB::open(pg_connect('dbname=lobs'), 12345));
6  $dl->send();
?>
Prev | HTTP_Download | Next
HTTP_Download | PEAR Manual | HTTP_Download::HTTP_Download


HTTP_Download::HTTP_Download

HTTP_Download::HTTP_Download

HTTP_Download::HTTP_Download() – Constructor

Synopsis

require_once 'HTTP/Download.php';

object new HTTP_Download ( array $params = array() )

Description

Creates an instance of an HTTP_Download object and sets supplied parameters.

Parameter

  • array $params - An associative array of parameters:

    • one of:

      • $params['file'] - filepath

      • $params['data'] - raw data

      • $params['resource'] - resource handle

    • and any of:

      • $params['gzip'] - whether to gzip the download

      • $params['cache'] - whether to allow client side caching of the download

      • $params['lastmodified'] - unix timestamp of last modification

      • $params['contenttype'] - content type

      • $params['contentdisposition'] - content disposition

      • $params['buffersize'] - amount of bytes read at once from files or resources

      • $params['throttledelay'] - amount of seconds to sleep after each chunk that has been sent

      • $params['cachecontrol'] - cache privacy and validity

See

See also
setFile(),
setData(),
setResource(),
setGzip(),
setCache(),
setContentType(),
setLastModified(),
setContentDisposition(),
setBufferSize(),
setThrottleDelay(),
setCacheControl(),
setParams().

Prev | HTTP_Download | Next
Intro | PEAR Manual | HTTP_Download::setParams


HTTP_Download::setParams

HTTP_Download::setParams

HTTP_Download::setParams() – Set various parameters

Synopsis

mixed HTTP_Download::setParams ( array $params )

Description

Set the parameters for the download.

You can use this method as an alternative to passing the parameters in the constructor or calling the setter of each parameter.

Parameter

  • array $params - An associative array of parameters:

    • one of:

      • $params['file'] - filepath

      • $params['data'] - raw data

      • $params['resource'] - resource handle

    • and any of:

      • $params['gzip'] - whether to gzip the download

      • $params['cache'] - whether to allow client side caching of the download

      • $params['lastmodified'] - unix timestamp of last modification

      • $params['contenttype'] - content type

      • $params['contentdisposition'] - content disposition

      • $params['buffersize'] - amount of bytes read at once from files or resources

      • $params['throttledelay'] - amount of seconds to sleep after each chunk that has been sent

      • $params['cachecontrol'] - cache privacy and validity

See

See also
setFile(),
setData(),
setResource(),
setGzip(),
setCache(),
setContentType(),
setLastModified(),
setContentDisposition(),
setBufferSize(),
setThrottleDelay(),
setCacheControl().

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::HTTP_Download | PEAR Manual | HTTP_Download::setFile


HTTP_Download::setFile

HTTP_Download::setFile

HTTP_Download::setFile() – Set file path

Synopsis

mixed HTTP_Download::setFile ( string $file , bool $send_404 = true )

Description

Set the path to the file for the download.

Parameter

  • string $file - file path

  • bool $send_404 = true - whether to send "HTTP 404 File Not Found", if file couldn't be found

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setParams | PEAR Manual | HTTP_Download::setData


HTTP_Download::setData

HTTP_Download::setData

HTTP_Download::setData() – Set raw data

Synopsis

void HTTP_Download::setData ( mixed $data = null )

Description

Set $data to null if you want to unset.

Otherwise you can send any arbitrary data ie. from a database BLOB.

Parameter

  • mixed $data = null - any arbietrary data as string to send or null to unset

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setFile | PEAR Manual | HTTP_Download::setResource


HTTP_Download::setResource

HTTP_Download::setResource

HTTP_Download::setResource() – Set resource for download

Synopsis

mixed HTTP_Download::setResource ( mixed $handle = null )

Description

Set the resource handle to retrieve the data for the download.

The resource handle supplied will be closed after sending the download.

Set $handle to null if you want to unset.

Note: This cannot be used with resources of databases that populate their BLOBs as resource handles like PostgreSQL. A possible solution would be to write a stream wrapper.

Returns a PEAR_Error if $handle is no valid resource or not null.

Parameter

  • mixed $handle = null - (int) resource handle or null

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setData | PEAR Manual | HTTP_Download::setGzip


HTTP_Download::setGzip

HTTP_Download::setGzip

HTTP_Download::setGzip() – Whether to gzip the download on the fly or not. (requires ext/zlib)

Synopsis

mixed HTTP_Download::setGzip ( bool $gzip = false )

Description

Define whether you want to send the download gzipped or not.

Returns a PEAR_Error if ext/zlib is not available.

Parameter

  • bool $gzip = false - whether to gzip the download on the fly

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setResource | PEAR Manual | HTTP_Download::setCache


HTTP_Download::setCache

HTTP_Download::setCache

HTTP_Download::setCache() – Whether to allow caching of the download on the clients side.

Synopsis

void HTTP_Download::setCache ( bool $cache = true )

Description

Define whether you want to allow caching of the download on the clients side.

If set to true (default), HTTP_Download will emit some caching headers like Cache-Control, Last-Modified and ETag.

Parameter

  • bool $cache = true - whether to allow caching of the download

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setGzip | PEAR Manual | HTTP_Download::setCacheControl


HTTP_Download::setCacheControl

HTTP_Download::setCacheControl

HTTP_Download::setCacheControl() – Control cache privacy and validity.

Synopsis

void HTTP_Download::setCacheControl ( string $cache = "public" , int $maxage = 0 )

Description

Define the contents of the Cache-Control header.

If set to set to "public", proxies are adviced to cache the response, if set to "private", proxies are adviced to do not.

The maxage paramter controls the amount of seconds an entity is suggested to be cached. Many user agents won't even send a request for subsequent requests to the same resource within the specified time frame.

Parameter

  • string $cache = "public" - whether to allow proxy caching

  • int $maxage = 0 - maximum age of the cached entity

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setCache | PEAR Manual | HTTP_Download::setBufferSize


HTTP_Download::setBufferSize

HTTP_Download::setBufferSize

HTTP_Download::setBufferSize() – Set size of buffer in bytes.

Synopsis

mixed HTTP_Download::setBufferSize ( int $size = 2097152 )

Description

The amount of bytes specified as buffer size is the maximum amount of data read at once from resources or files. The default size is 2M (2097152 bytes).

Be aware that if you enable gzip compression and you set a very low buffer size that the actual file size may grow due to added gzip headers for each sent chunk of the specified size.

Returns PEAR_Error (HTTP_DOWNLOAD_E_INVALID_PARAM) if $size is not greater than 0 bytes.

Parameter

  • int $size = 2097152 - amount of bytes to buffer

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setCacheControl | PEAR Manual | HTTP_Download::setThrottleDelay


HTTP_Download::setThrottleDelay

HTTP_Download::setThrottleDelay

HTTP_Download::setThrottleDelay() – Set throttle delay in seconds

Synopsis

void HTTP_Download::setThrottleDelay ( float $seconds = 0 )

Description

Set the amount of seconds to sleep after each chunck that has been sent. One can implement some sort of throttle through adjusting the buffer size and the throttle delay. With a setting of buffersize=25600 and throttledelay=1 HTTP_Download will sleep a second after each 25 K of data sent.

Just be aware that if gzip'ing is enabled, decreasing the chunk size too much leads to proportionally increased network traffic due to added gzip header and bottom bytes around each chunk.

Parameter

  • float $seconds = 0 - amount of seconds to sleep

Return value

Returns void.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setBufferSize | PEAR Manual | HTTP_Download::setContentType


HTTP_Download::setContentType

HTTP_Download::setContentType

HTTP_Download::setContentType() – Set content type

Synopsis

mixed HTTP_Download::setContentType ( string $content_type = 'application/x-octetstream' )

Description

Set a reasonable content type for the download.

Examples:

  • application/pdf

  • application/zip

  • text/css

Returns PEAR_Error if $content_type doesn't seem to be valid.

Parameter

  • string $content_type = 'application/x-octetstream' - a reasonable content type

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setThrottleDelay | PEAR Manual | HTTP_Download::setLastModified


HTTP_Download::setLastModified

HTTP_Download::setLastModified

HTTP_Download::setLastModified() – Set "Last-Modified"

Synopsis

void HTTP_Download::setLastModified ( int $last_modified )

Description

Set the time (unix timestamp) of last modification of the download.

This is usually determined by filemtime($file) in setFile().

Parameter

  • int $last_modified - unix timestamp of last modification time

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setContentType | PEAR Manual | HTTP_Download::setContentDisposition


HTTP_Download::setContentDisposition

HTTP_Download::setContentDisposition

HTTP_Download::setContentDisposition() – Set content disposition

Synopsis

void HTTP_Download::setContentDisposition ( string $disposition = HTTP_DOWNLOAD_ATTACHMENT , string $file_name = null )

Description

Set content disposition of the download.

"Content-Disposition" is not HTTP compliant, but most browsers follow this header, so it was borrowed from MIME standard. It looks like this: "Content-Disposition: attachment; filename=example.tgz".

Parameter

  • string $disposition = HTTP_DOWNLOAD_ATTACHMENT - the disposition of the download (either 'attachment' or 'inline')

  • string $file_name = null - the file name the browser's download window should show

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setLastModified | PEAR Manual | HTTP_Download::guessContentType


HTTP_Download::guessContentType

HTTP_Download::guessContentType

HTTP_Download::guessContentType() – Guess content type of file

Synopsis

mixed HTTP_Download::guessContentType ( )

Description

Use only if you send a file.

First we try to use MIME_Type, if installed, to detect the content type, else we check if ext/mime_magic is loaded and properly configured.

Returns PEAR_Error if:

  • MIME_Type failed to detect a proper content type (HTTP_DOWNLOAD_E_INVALID_CONTENT_TYPE)
  • ext/magic.mime is not installed, or not properly configured (HTTP_DOWNLOAD_E_NO_EXT_MMAGIC)
  • mime_content_type() couldn't guess content type or returned a content type considered to be bogus by setContentType() (HTTP_DOWNLOAD_E_INVALID_CONTENT_TYPE)

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::setContentDisposition | PEAR Manual | HTTP_Download::send


HTTP_Download::send

HTTP_Download::send

HTTP_Download::send() – Send file

Synopsis

mixed HTTP_Download::send ( bool $autoSetContentDisposition = true )

Description

Send the download.

Returns PEAR_Error if:

  • HTTP headers were already sent

  • HTTP Range was invalid

Parameter

  • bool $autoSetContentDisposition = true - automatically sets the Content-Disposition to HTTP_DOWNLOAD_ATTACHMENT header if not already set

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | HTTP_Download | Next
HTTP_Download::guessContentType | PEAR Manual | HTTP_Download::staticSend


HTTP_Download::staticSend

HTTP_Download::staticSend

HTTP_Download::staticSend() – Static send

Synopsis

mixed HTTP_Download::staticSend ( array $params , bool $guess = false )

Description

Send a download statically without instantiating an HTTP_Download object.

Parameter

  • array $params - An associative array of parameters:

    • one of:

      • $params['file'] - filepath

      • $params['data'] - raw data

      • $params['resource'] - resource handle

    • and any of:

      • $params['gzip'] - whether to gzip the download

      • $params['cache'] - whether to allow client side caching of the download

      • $params['lastmodified'] - unix timestamp of last modification

      • $params['contenttype'] - content type

      • $params['contentdisposition'] - content disposition

      • $params['buffersize'] - amount of bytes read at once from files or resources

      • $params['throttledelay'] - amount of seconds to sleep after each chunk that has been sent

  • bool $guess = false - whether to call guessContentType()

See

See also
setFile(),
setData(),
setResource(),
setGzip(),
setCache(),
setContentType(),
setLastModified(),
setContentDisposition(),
setBufferSize(),
setThrottleDelay(),
setParams().

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function should be called statically.

Prev | HTTP_Download | Next
HTTP_Download::send | PEAR Manual | HTTP_Download::sendArchive


HTTP_Download::sendArchive

HTTP_Download::sendArchive

HTTP_Download::sendArchive() – Send an archive created on the fly

Synopsis

mixed HTTP_Download::sendArchive ( string $name , mixed $files , string $type = HTTP_DOWNLOAD_TGZ , string $add_path = '' , string $strip_path = '' )

Description

Send an archive created on the fly by Archive_Tar or Archive_Zip.

The parameter $files can be an array of files/directories or a space separated string of files/directories which should be packed to an archive.

The parameter $type can be one of HTTP_DOWNLOAD_TAR, HTTP_DOWNLOAD_TGZ, HTTP_DOWNLOAD_BZ2 and HTTP_DOWNLOAD_ZIP.

Note: The usage of this method is deprecated. Use HTTP_Download_Archive::send() instead.

Parameter

  • string $name - the name the archive should have

  • mixed $files - list of files/directories

  • string $type = - the format of the archive (TAR, TGZ, BZ2 or ZIP)

  • string $add_path = '' - path that should be prepended to the files

  • string $strip_path = '' - path that should be stripped from the files

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function should be called statically.

Prev | HTTP_Download | Next
HTTP_Download::staticSend | PEAR Manual | HTTP_Request


HTTP_Request

HTTP_Request

The package provides an easy way to perform HTTP requests. It supports GET/POST/HEAD/TRACE/PUT/DELETE, Basic authentication, Proxy, Proxy Authentication, SSL, file uploads etc.

Table of Contents
  • Introduction -- Introduction to HTTP_Request
  • Basic Authentication -- Authentication for protected websites
  • Cookies -- Making use of Cookies within HTTP_Request.
  • File uploads -- Uploading files via HTTP
  • Request headers -- Adding additional headers to the HTTP request.
  • Proxy Authorization -- Making use of a HTTP proxy
  • Response Evaluation -- Evaluating the information from a HTTP response
  • HTTP_Request_Listener -- attaching listeners to HTTP_Request operations
Prev | HTTP | Next
HTTP_Download::sendArchive | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to HTTP_Request

Overview

With this package, one can easily perform HTTP request from within PHP scripts. It support GET/POST/HEAD/TRACE/PUT/DELETE, Basic authentication, Proxy, Proxy Authentication, SSL, file uploads etc.

Because of the above mentioned features HTTP_Request makes it possible to mimic big parts of web browsers such as the widely-known Mozilla browser in PHP applications. Possible application areas are:

  • Checking the validity of WWW links with the help of getResponseCode.

  • Grabbing remote web pages and parsing the result.

  • etc.

A few examples

Fetches yahoo.com and displays it

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://www.yahoo.com/");
if (!PEAR::isError($req->sendRequest())) {
    echo $req->getResponseBody();
}
?>

Fetching two website in a row

In this example, two websites are fetched and displayed. To the first one a POST parameter is passed. The POST data stack is cleared before the second website is fetched.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://www.php.net");
$req->setMethod(HTTP_REQUEST_METHOD_POST);
$req->addPostData("Foo", "bar");
if (!PEAR::isError($req->sendRequest())) {
     $response1 = $req->getResponseBody();
} else {
     $response1 = "";
}

$req->setMethod(HTTP_REQUEST_METHOD_GET);
$req->setURL("http://pear.php.net");
$req->clearPostData();
if (!PEAR::isError($req->sendRequest())) {
     $response2 = $req->getResponseBody();
} else {
     $response2 = "";
}

echo $response1;
echo $response2;
?>
Prev | HTTP_Request | Next
HTTP_Request | PEAR Manual | Basic Authentication


Basic Authentication

Basic Authentication

Basic Authentication – Authentication for protected websites

Introduction to Basic Authentication

Basic Authentication is a challenge-response mechanism described in RFC 2617.

How to use Basic Authentication

Basic Authentication

The following example assumes that one wants to fetch a page /protected.html on the host example.com that is protected using Basic Authentication. The necessary username to pass the authentication is johndoe and the appendant password is foo.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/protected.html");
$req->setBasicAuth("johndoe", "foo");

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    echo $req->getResponseBody();
}
?>
Prev | HTTP_Request | Next
Introduction | PEAR Manual | Cookies


Cookies

Cookies

Cookies – Making use of Cookies within HTTP_Request.

How to add Cookie to a HTTP request

Adding a cookie to the request

In this example a cookie named version is added to the HTTP request. The value of this cookie is the version string of the PHP interpreter that is running the instance of HTTP_Request.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->addCookie("version", phpversion());

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    echo $req->getResponseBody();
}
?>

Reading cookies from a HTTP response

Reading cookies that come with a HTTP response is shown in this following example.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    print_r($req->getResponseCookies());
}
?>
Prev | HTTP_Request | Next
Basic Authentication | PEAR Manual | File uploads


File uploads

File uploads

File uploads – Uploading files via HTTP

How to use file uploads

Upload a PDF document

In this example a file named /home/johndoe/text.pdf is uploaded to the remote machine upload.example.com. Additionally Basic Authentication is used to ensure that John is allowed to upload something.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://upload.example.com/upload.php");
$req->setBasicAuth("johndoe", "foo");
$req->setMethod(HTTP_REQUEST_METHOD_POST);

$result = $req->addFile('file_upload_field', '/home/johndoe/text.pdf', 'application/pdf');
if (PEAR::isError($result)) {
    echo $result->getMessage();
} else {

    $response = $req->sendRequest();

    if (PEAR::isError($response)) {
        echo $response->getMessage();
    } else {
        echo $req->getResponseBody();
    }
}
?>
Prev | HTTP_Request | Next
Cookies | PEAR Manual | Request headers


Request headers

Request headers

Request headers – Adding additional headers to the HTTP request.

How to add request headers

Adding a custom request header

In this example a HTTP header X-PHP-Version is added to the HTTP request. The value of this header is the version string of the PHP interpreter that is running the instance of HTTP_Request.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->addHeader("X-PHP-Version", phpversion());

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    echo $req->getResponseBody();
}
?>

Headers that have been added to the HTTP_Request object can be removed with the method removeHeader(), before sendRequest() has been called.

Prev | HTTP_Request | Next
File uploads | PEAR Manual | Proxy Authorization


Proxy Authorization

Proxy Authorization

Proxy Authorization – Making use of a HTTP proxy

How to use Proxy Authorization

Using a proxy server with anonymous access

In this example it is assumed that one wants to use the machine with the hostname proxy.example.com, where a proxy server is listening on port 8080, to proxy the outgoing connection to example.com.

The second parameter of setProxy() is optional and defaults to 8080.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->setProxy("proxy.example.com", 8080);
?>

Using proxy authorization

This is the same example as above, except that a username/password tuple is provided, which authorizes the user at the proxy server: The username is johndoe and the appendant password is foo.

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->setProxy("proxy.example.com", 8080, "johndoe", "foo");
?>
Prev | HTTP_Request | Next
Request headers | PEAR Manual | Response Evaluation


Response Evaluation

Response Evaluation

Response Evaluation – Evaluating the information from a HTTP response

Introduction

Because HTTP is a protocol based on the Request - Response scheme, every HTTP request is followed by a HTTP response. HTTP_Request offers several methods to evaluate the information from these responses.

Response Codes

A important part of the HTTP response is the response code. The most well-known response code probably is 404, which you may have seen in your browser at several occasions. The meaning of 404 is that the requested ressource could not be found. A complete list of status codes can be found in RFC 2616.

Checking the response code

<?php
require_once "HTTP/Request.php";

$urls = array(
    "http://www.example.com/",
    "http://example.com/thisdoesnotexist.html"
    );

$req =& new HTTP_Request("");
foreach ($urls as $url) {
    $req->setURL($url);
    $req->sendRequest();

    $code = $req->getResponseCode();
    switch ($code) {
    case 404:
        echo "Document not found\n";
        break;

    case 200:
        echo "Everything's ok\n";
        break;

    /* ... */
    }
}
?>

Response Headers

Similar to a HTTP request a HTTP response consists of a header and a body. HTTP_Request offers a method to access the header of the response.

Getting all headers from the response

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->sendRequest();

foreach ($req->getResponseHeader() as $name => $value) {
    echo $name . " = " . $value . "\n";
}
?>

This will print all headers and the appendant values.

Getting a specific header

<?php
require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->sendRequest();

echo $req->getResponseHeader("Date");
?>

This will print the value of the Date: header.

Response Cookies

Fetching the cookies that are part of the HTTP response is described in the Cookies section.

Prev | HTTP_Request | Next
Proxy Authorization | PEAR Manual | HTTP_Request_Listener


HTTP_Request_Listener

HTTP_Request_Listener

HTTP_Request_Listener – attaching listeners to HTTP_Request operations

Introduction to HTTP_Request_Listener

HTTP_Request_Listener is an abstract class that can be extended to capture events and respond to them as they occur. Included with HTTP_Request is an example of a console-based progress bar. To implement this, the HTTP_Request_DownloadListener class is used, which uses the Console_ProgressBar package to display a download progress meter.

Example usage of HTTP_Request_Listener

In order to use a listener, it must attach to the specific HTTP_Request or HTTP_Response object that you want to monitor. The attach code is shown at the bottom of the example. As you can see, the event listener is propagated from the HTTP_Request object to any child HTTP_Response objects, and attaching only need happen to the first HTTP_Request object.

Download progress bar with HTTP_Request_Listener

<?php
/**
 * An example of Listener usage with HTTP_Request. This downloads and saves
 * the file displaying the progress bar in the process.
 *
 * Note two things:
 * 1) The file should be run in console, not in browser;
 * 2) You should turn output buffering OFF for this to work properly.
 */

require_once 'HTTP/Request.php';
require_once 'HTTP/Request/Listener.php';
require_once 'Console/ProgressBar.php';

PEAR::setErrorHandling(PEAR_ERROR_DIE);

set_time_limit(0);

class HTTP_Request_DownloadListener extends HTTP_Request_Listener
{
   /**
    * Handle for the target file
    * @var int
    */
    var $_fp;

   /**
    * Console_ProgressBar intance used to display the indicator
    * @var object
    */
    var $_bar;

   /**
    * Name of the target file
    * @var string
    */
    var $_target;

   /**
    * Number of bytes received so far
    * @var int
    */
    var $_size = 0;

    function HTTP_Request_DownloadListener()
    {
        $this->HTTP_Request_Listener();
    }

   /**
    * Opens the target file
    * @param string Target file name
    * @throws PEAR_Error
    */
    function setTarget($target)
    {
        $this->_target = $target;
        $this->_fp = @fopen($target, 'wb');
        if (!$this->_fp) {
            PEAR::raiseError("Cannot open '{$target}'");
        }
    }

    function update(&$subject, $event, $data = null)
    {
        switch ($event) {
            case 'sentRequest':
                $this->_target = basename($subject->_url->path);
                break;

            case 'gotHeaders':
                if (isset($data['content-disposition']) &&
                    preg_match('/filename="([^"]+)"/', $data['content-disposition'], $matches)) {

                    $this->setTarget(basename($matches[1]));
                } else {
                    $this->setTarget($this->_target);
                }
                $this->_bar =& new Console_ProgressBar(
                    '* ' . $this->_target . ' %fraction% KB [%bar%] %percent%', '=>', '-',
                    79, (isset($data['content-length'])? round($data['content-length'] / 1024): 100)
                );
                $this->_size = 0;
                break;

            case 'tick':
                $this->_size += strlen($data);
                $this->_bar->update(round($this->_size / 1024));
                fwrite($this->_fp, $data);
                break;

            case 'gotBody':
                fclose($this->_fp);
                break;

            case 'connect':
            case 'disconnect':
                break;

            default:
                PEAR::raiseError("Unhandled event '{$event}'");
        } // switch
    }
}

// Try using any other package if you like, but choose the bigger ones
// to be able to see the progress bar
$url = 'http://pear.php.net/get/HTML_QuickForm-stable';

$req =& new HTTP_Request($url);

$download =& new HTTP_Request_DownloadListener();
$req->attach($download);
$req->sendRequest(false);
?>

Events that can be caught

The HTTP_Request class sends these events:

  • connect - upon server connection, this event is sent

  • sentRequest - after the request was sent, this event is sent

  • disconnect - after server disconnect, this event is sent

The HTTP_Response class sends these events:

  • gotHeaders - this event is sent after receiving response headers (headers are passed in $data as an associative array)

  • tick - this event is sent on receiving a part of response body (the part is passed in $data as a string)

  • gzTick - this event is sent on receiving a part of response body that is gzip-compressed (the part is passed in $data as a string)

  • gotBody - this event is sent on after receiving the complete response body (the decoded body is passed as a string in $data if it was gzipped)

Prev | HTTP_Request | Next
Response Evaluation | PEAR Manual | HTTP_Session


HTTP_Session

HTTP_Session

The package provides an Object-oriented interface to the session_* family functions. It provides extra features such as database storage for session data using the DB, MDB and MDB2 package. It introduces new methods like isNew(), useCookies(), setExpire(), setIdle(), isExpired(), isIdled() and others.

Table of Contents
  • Introduction -- Introduction to HTTP_Session
  • Database container -- Store session data in a database with HTTP_Session
Prev | HTTP | Next
HTTP_Request_Listener | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to HTTP_Session

Overview

This package provides access to session-state values as well as session-level settings and lifetime management methods. Based on the standart PHP session handling mechanism it provides more advanced features such as database containers, idle and expire timeouts, etc.

A few examples

Setting some options and detection of a new session

<?php
HTTP_Session::setCookieless(false);
HTTP_Session::start('MySessionID');
HTTP_Session::set('variable', 'Tet string');
if (HTTP_Session::isNew()) {
    echo('new session was created with the current request');
    $visitors++; // Increase visitors count
}

// after successful login use: HTTP_Session::regenerateId();
?>

Setting timeouts

<?php
HTTP_Session::start();
HTTP_Session::setExpire(time() + 60 * 60); // expires in one hour
HTTP_Session::setIdle(time() + 10 * 60);   // idles in ten minutes

// expired
if (HTTP_Session::isExpired()) {
    echo('Your session is expired!');
    HTTP_Session::destroy();
}

// idled
if (HTTP_Session::isIdle()) {
    echo('You've been idle for too long!);
    HTTP_Session::destroy();
}

HTTP_Session::updateIdle();
?>
Prev | HTTP_Session | Next
HTTP_Session | PEAR Manual | Database container


Database container

Database container

Database container – Store session data in a database with HTTP_Session

Overview

HTTP_Session lets you store the session data in a database making use of the DB, MDB and MDB2 packages.

Example

Using MDB2 to store session data in a database

<?php
/* create the following table in your database
CREATE TABLE sessiondata (
  id     varchar(32)    NOT NULL,
  expiry int(10),
  data   text,
  PRIMARY KEY (id)
);
*/

require_once 'HTTP/Session.php';

HTTP_Session::useTransSID(false);
HTTP_Session::useCookies(false);

// enter your DSN
HTTP_Session::setContainer('MDB2', array('dsn'   => 'mysql://root:password@localhost/database',
                                         'table' => 'sessiondata'));

/*
// using an existing MDB2 connection
HTTP_Session::setContainer('MDB2', array('dsn'   => &$db,
                                         'table' => 'sessiondata'));
*/

HTTP_Session::start('s');
HTTP_Session::setExpire(time() + 60);   // set expire to 60 seconds
HTTP_Session::setIdle(time() + 5);      // set idle to 5 seconds

if (HTTP_Session::isExpired()) {
    //HTTP_Session::replicate('sessiondata_backup');    // Replicate data of current session to specified table
    HTTP_Session::destroy();
}

if (HTTP_Session::isIdle()) {
    //HTTP_Session::replicate('sessiondata_backup');    // Replicate data of current session to specified table
    HTTP_Session::destroy();
}

HTTP_Session::updateIdle();
?>
Prev | HTTP_Session | Next
Introduction | PEAR Manual | HTTP_Session2


HTTP_Session2

HTTP_Session2

The HTTP_Session2 package provides an Object-oriented interface to the session_* family functions. It's a PHP5 port of the HTTP_Session package.

HTTP_Session2 provides extra features such as database storage for session data using the DB and MDB2 package. It also introduces new methods, such as isNew(), useCookies(), setExpire(), setIdle(), isExpired(), isIdled() and others.

Table of Contents
  • Introduction -- An introduction to HTTP_Session2
  • Using a database container -- How to store session data in a database with HTTP_Session2
  • Making a session persistent -- This example illustrates how to make a session persist over multiple browser sessions using a so called "session cookie".
Prev | HTTP | Next
Database container | PEAR Manual | Introduction


Introduction

Introduction

Introduction – An introduction to HTTP_Session2

Overview

This package provides access to session-state values as well as session-level settings and lifetime management methods.

Based on the standart PHP session handling mechanism HTTP_Session2 provides more advanced features such as database containers, idle and expire timeouts and more.

A few examples

Setting options and detecting a new session

<?php
HTTP_Session2::useCookies(false);
HTTP_Session2::start('MySessionID');
HTTP_Session2::set('variable', 'The string');
if (HTTP_Session2::isNew()) {
    echo 'new session was created with the current request';
    $visitors++; // Increase visitors count
}
// continue
?>

Setting timeouts

<?php
HTTP_Session2::start();
HTTP_Session2::setExpire(time() + 60 * 60); // expires in one hour
HTTP_Session2::setIdle(time() + 10 * 60);   // idles in ten minutes

// the session expired
if (HTTP_Session2::isExpired()) {
    echo 'Your session has expired!';
    HTTP_Session2::destroy();
}

// the session is idle
if (HTTP_Session2::isIdle()) {
    echo "You've been idle for too long!";
    HTTP_Session2::destroy();
}

HTTP_Session2::updateIdle();
?>

For a more comprehensive example of persistent sessions, please check the cookie section.

Prev | HTTP_Session2 | Next
HTTP_Session2 | PEAR Manual | Using a database container


Using a database container

Using a database container

Using a database container – How to store session data in a database with HTTP_Session2

Overview

HTTP_Session lets you store the session data in a database making use of the DB and MDB2 packages.

Example

Using MDB2 to store session data in a database

<?php
/* create the following table in your database
CREATE TABLE sessiondata (
    id     varchar(32) NOT NULL,
    expiry int(10),
    data   text,
    PRIMARY KEY (id)
);
*/

require_once 'HTTP/Session2.php';

HTTP_Session2::useTransSID(false);
HTTP_Session2::useCookies(false);

// enter your DSN
HTTP_Session2::setContainer('MDB2',
    array('dsn' => 'mysql://root:password@localhost/database',
        'table' => 'sessiondata'));

/*
// using an existing MDB2 connection
HTTP_Session2::setContainer('MDB2',
    array('dsn'   => &$db, 'table' => 'sessiondata'));
*/

HTTP_Session2::start('s');
HTTP_Session2::setExpire(time() + 60); // set expire to 60 seconds
HTTP_Session2::setIdle(time() + 5);    // set idle to 5 seconds

if (HTTP_Session2::isExpired()) {
    HTTP_Session2::destroy();
}

if (HTTP_Session2::isIdle()) {
    HTTP_Session2::destroy();
}

HTTP_Session2::updateIdle();
?>
Prev | HTTP_Session2 | Next
Introduction | PEAR Manual | Making a session persistent


Making a session persistent

Making a session persistent

Making a session persistent – This example illustrates how to make a session persist over multiple browser sessions using a so called "session cookie".

Explanation

When you create a session it needs to be referenced using a sessionID. This sessionID is generally saved either into a cookie or passed along in the URI.

To remember the sessionID across browser sessions, the cookie method is favoured.

To extend the lifetime of this cookie (the standard is that it's only valid until the browser is closed) we use PHP's session_set_cookie_params().

Example

Use of session_set_cookie_params

<?php
require_once 'HTTP/Session2.php';

/**
 * set cookie params
 */
session_set_cookie_params(60*60*24, // expire in 24 hours
    '/',                            // path
    '.example.org',                 // domain
    false,                          // "secure only"
    true);                          // only over http

HTTP_Session2::useCookies(true);

HTTP_Session2::start('s');
HTTP_Session2::setExpire(60*60*24); // set expire in 24 hours
HTTP_Session2::setIdle(60*60);      // set idle to 1 hour

if (HTTP_Session2::isExpired()) {
    HTTP_Session2::destroy();
}

if (HTTP_Session2::isIdle()) {
    HTTP_Session2::destroy();
}

HTTP_Session2::updateIdle();
?>
Prev | HTTP_Session2 | Next
Using a database container | PEAR Manual | HTTP_Upload


HTTP_Upload

HTTP_Upload

Easy and secure managment of files submitted via HTML forms.

Table of Contents
  • Introduction
  • Examples
  • Extensive information about uploaded files
  • Internationalized Error Messages
Prev | HTTP | Next
Making a session persistent | PEAR Manual | Introduction


Introduction

Introduction

This package provides an advanced system for managing uploads of files via HTML <input type="file" /> fields. Features include:

  • Handling of multiple file uploads at a time

  • Safe file copying/moving from temporary directories

  • Upload validaton mechanisms

  • Extensive information about uploaded files

  • Renaming uploaded files

  • Internationalized error messages

Prev | HTTP_Upload | Next
HTTP_Upload | PEAR Manual | Examples


Examples

Examples

In the following examples it is assumed that you are using an HTML form field <input type="file" name="f" /> in order to upload files. For example:

HTML form for simple file upload

The following form can be used in order to test the single file upload example.

<?php
// sample code from below goes here
?>
<html>
 <head>
 </head>
 <body>
  <form name="fileuploadexample" method="post" enctype="multipart/form-data"
   action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
   <input type="file" name="f" />
   <input type="submit" name="submit" value="Submit" />
  </form>
 </body>
</html>

Simple file upload

The following code looks at the request and checks if a valid file was uploaded through the form. If that is the case, the file is moved to the subdirectory uploads.

<?php
require_once "HTTP/Upload.php";

$upload = new HTTP_Upload("en");
$file = $upload->getFiles("f");

if ($file->isValid()) {
    $moved = $file->moveTo('uploads/');
    if (!PEAR::isError($moved)) {
        echo 'File was moved to uploads/' . $file->getProp('name');
    } else {
        echo $moved->getMessage();
    }
} elseif ($file->isMissing()) {
    echo "No file was provided.";
} elseif ($file->isError()) {
    echo $file->errorMsg();
}
?>
Note: Internally, HTTP_Upload_File::moveTo() calls $file->setName('safe'); which replaces special characters in the name with an underscore. You should always use $file->getProp('name') after moving to retrieve the new filename.

HTML form for multiple file upload

The following form can be used in order to test the multiple file upload example.

<?php
// sample code from below goes here
?>
<html>
 <head>
 </head>
 <body>
  <form name="fileuploadexample2" method="post" enctype="multipart/form-data"
   action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
   <input type="file" name="f1" />
   <input type="file" name="f2" />
   <input type="submit" name="submit" value="Submit" />
  </form>
 </body>
</html>

Multiple files, more extensive checks

Multiple files can uploaded by replacing the name of the form field (f) with f[] and creating multiple <input /> fields with this name.

<?php
$upload = new HTTP_Upload("en");
$files = $upload->getFiles();

foreach($files as $file){
    if (PEAR::isError($file)) {
        echo $file->getMessage();
    }

    if ($file->isValid()) {
        $file->setName("uniq");
        $dest_name = $file->moveTo("uploads/");

        if (PEAR::isError($dest_name)) {
            echo $dest_name->getMessage();
        }

        $real = $file->getProp("real");

    } elseif ($file->isMissing()) {
        echo "No file was provided.";
    } elseif ($file->isError()) {
        echo $file->errorMsg();
    }

    print_r($file->getProp());
}
?>
Prev | HTTP_Upload | Next
Introduction | PEAR Manual | Extensive information about uploaded files


Extensive information about uploaded files

Extensive information about uploaded files

HTTP_Upload provides extensive information about uploaded files via the getProp() method:

mixed HTTP_Upload_File::getProp ( [name] )

If no value for name is provided, then this method will return an array containing all available information about the uploaded file. Otherwise the information identified by the value of this parameter will be returned as a string.

The list of possible values is determined by the contents of the $_FILES array, but is customized for the purposes of HTTP_Upload. Here are the possible properties:

  • 'name': destination file name

  • 'tmp_name': temporary uploaded file name (assigned by PHP)

  • 'form_name': name of the HTML form that submitted the uploaded file

  • 'type': Mime type of the file

  • 'size': size of the file

  • 'error': if there was an error on upload, this contains a string representing the kind of error. The errorCode() method can be used to retrieve a localized error message from this property.

Extensive information via getProp()

<?php
require_once "HTTP/Upload.php";

$upload = new HTTP_Upload("en");
$file = $upload->getFiles("f");

if ($file->isValid()) {
    echo "<pre>";
    print_r($file->getProp());
    echo "</pre>";

    printf("The uploaded file has the extension %s.", $file->getProp("ext"));
}
?>
Prev | HTTP_Upload | Next
Examples | PEAR Manual | Internationalized Error Messages


Internationalized Error Messages

Internationalized Error Messages

Another handy feature of HTTP_Upload is support for internationalized error messages. This means that if an error (like an invalid file upload) is detected, the programmer can choose in which the language the error messages should be returned by HTTP_Upload.

The first parameter of the constructor method for HTTP_Upload determines the language to be used. This is illustrated in the following example:

Example

<?php
// German error messages
$language = "de";

require_once "HTTP/Upload.php";

$upload = new HTTP_Upload($language);
$file = $upload->getFiles("f");

if ($file->isValid()) {
    $moved = $file->moveTo("uploads/");
    if (!PEAR::isError($moved)) {
        echo "File was moved to uploads/";
    } else {
        // This will print a german error message
        echo "An error was detected: " . $moved->getMessage() . "<br />";
    }
}
?>
Prev | HTTP_Upload | Next
Extensive information about uploaded files | PEAR Manual | Images


Images

Images

Provides Packages for working with images

Table of Contents
  • Image_Barcode
  • Image_Canvas
  • Image_Graph
  • Image_Text
  • Image_Transform
Prev | PEAR Packages | Next
Internationalized Error Messages | PEAR Manual | Image_Barcode


Image_Barcode

Image_Barcode

Table of Contents
  • Introduction
  • Using Image_Barcode
  • Simple example
Prev | Images | Next
Images | PEAR Manual | Introduction


Introduction

Introduction

Image_Barcode lets you create barcode representations of strings. The package supports multiple drivers, letting you create barcodes of the following type:

  • Code 39

  • Code 128

  • EAN 13

  • INT 25

  • PostNet

  • UPCA

Prev | Image_Barcode | Next
Image_Barcode | PEAR Manual | Using Image_Barcode


Using Image_Barcode

Using Image_Barcode

Creating a barcode is as simple as calling the classes static draw() method after including Image/Barcode.php.

The method has four parameters: The first is the string that shall be converted into barcode representation. The second parameter determines which driver/type should be used; it is one of: Code39, code128, ean13, int25, postnet or upca.

Note: The case difference between Code39 and code128 has no reason and makes no sense, but is kept because of backward compatibility.

The third parameter of draw() determines the type of the image that is generated; one of jpg, png and gif.

By default, the image generated by the barcode driver is directly output to the browser. If you do not want this, pass false as fourth parameter and draw() will return the GD image resource object; allowing you to do further things with it.

Prev | Image_Barcode | Next
Introduction | PEAR Manual | Simple example


Simple example

Simple example

<?php
require_once 'Image/Barcode.php';
Image_Barcode::draw('1234', 'int25', 'png');
?>

As with all PEAR packages, installing the package also installs some more examples in the docs/Image_Barcode directory of your PEAR installation.

Prev | Image_Barcode | Next
Using Image_Barcode | PEAR Manual | Image_Canvas


Image_Canvas

Image_Canvas

This package provides a common interface to image drawing, making image source code independent on the library used. It includes output drivers for JPEG and PNG (using the GD library) as well as for PDF and SVG.

A list of the supported drawing functions is available on an external site.

Table of Contents
  • Example -- Usage example for Image_Canvas
Prev | Images | Next
Simple example | PEAR Manual | Example


Example

Example

Example – Usage example for Image_Canvas

Example

Generation of a sample image in PNG format

<?php
require_once 'Image/Canvas.php';

// change the output format with the first parameter of factory()
$Canvas =& Image_Canvas::factory('png', array('width' => 400, 'height' => 300));

$Canvas->setLineColor('black');
$Canvas->rectangle(array('x0' => 0, 'y0' => 0, 'x1' => 399, 'y1' => 299));

$Canvas->setGradientFill(array('direction' => 'horizontal', 'start' => 'red', 'end' => 'blue'));
$Canvas->setLineColor('black');
$Canvas->ellipse(array('x' => 199, 'y' => 149, 'rx' => 50, 'ry' => 50));

$Canvas->setFont(array('name' => 'Arial', 'size' => 12));
$Canvas->addText(array('x' => 0, 'y' => 0, 'text' => 'Demonstration of what Image_Canvas do!'));

$Canvas->setFont(array('name' => 'Times New Roman', 'size' => 12));
$Canvas->addText(array('x' => 399, 'y' => 20, 'text' => 'This does not demonstrate what is does!', 'alignment' => array('horizontal' => 'right')));

$Canvas->setFont(array('name' => 'Courier New', 'size' => 7, 'angle' => 270));
$Canvas->addText(array('x' => 350, 'y' => 50, 'text' => 'True, but it\'s all independent of the format!', 'alignment' => array('horizontal' => 'right')));

$Canvas->setFont(array('name' => 'Garamond', 'size' => 10));
$Canvas->addText(array('x' => 199, 'y' => 295, 'text' => '[Changing format is done by changing 3 letters in the source]', 'alignment' => array('horizontal' => 'center', 'vertical' => 'bottom')));

$Canvas->addVertex(array('x' => 50, 'y' => 200));
$Canvas->addVertex(array('x' => 100, 'y' => 200));
$Canvas->addVertex(array('x' => 100, 'y' => 250));
$Canvas->setFillColor('red@0.2');
$Canvas->polygon(array('connect' => true));

$Canvas->image(array('x' => 398, 'y' => 298, 'filename' => './pear-icon.png', 'alignment' => array('horizontal' => 'right', 'vertical' => 'bottom')));

$Canvas->show();
?>
Prev | Image_Canvas | Next
Image_Canvas | PEAR Manual | Image_Graph


Image_Graph

Image_Graph

Due to the fact that the Image_Graph is currently in development phase, there is no documentation available in the manual. Amongst others a "Getting Started Guide" is available on an external site.

Extensive example code is available on an external site.

Article on PHPBuilder : More about PEAR's Image_Graph by Ian Gilfillan.

Prev | Images | Next
Example | PEAR Manual | Image_Text


Image_Text

Image_Text

Table of Contents
  • Class Summary Image_Text -- Image_Text - Advanced text manipulations in images
  • constructor Image_Text::Image_Text -- Constructor
  • Image_Text::autoMeasurize -- Auto measurize text
  • Image_Text::display -- Display the image (send it to the browser).
  • Image_Text::getImg -- Return the image ressource.
  • Image_Text::init -- Initialiaze the Image_Text object.
  • Image_Text::measurize -- Measurize text into the text box
  • Image_Text::render -- Render the text in the canvas using the given options.
  • Image_Text::save -- Save image canvas.
  • Image_Text::set -- Set options
  • Image_Text::setColor -- Set a color
  • Image_Text::setColors -- Set the color-set
  • Package Image_Text Constants -- Constants defined in and used by Image_Text
Prev | Images | Next
Image_Graph | PEAR Manual | Class Summary Image_Text


Class Summary Image_Text

Class Summary Image_Text

Class Summary Image_Text – Image_Text - Advanced text manipulations in images

Image_Text - Advanced text manipulations in images

Image_Text provides advanced text manipulation facilities for GD2 image generation with PHP. Simply add text clippings to your images, let the class automatically determine lines, rotate text boxes around their center or top left corner. These are only a couple of features Image_Text provides.

Class Trees for Image_Text

  • Image_Text

Prev | Image_Text | Next
Image_Text | PEAR Manual | constructor Image_Text::Image_Text


constructor Image_Text::Image_Text

constructor Image_Text::Image_Text

constructor Image_Text::Image_Text() – Constructor

Synopsis

require_once 'ImageText.php';

void constructor Image_Text::Image_Text ( string $text , array $options = null )

Description

Set the text and options. This initializes a new Image_Text object. You must set your text here. Optinally you can set all options here using the $options parameter. If you finished switching all options you have to call the init() method first befor doing anything further! See Image_Text::set() for further information.

Parameter

string $text

Text to print.

array $options

Options.

Throws

throws no exceptions thrown

See

see Image_Text::set(), Image_Text::init()

Note

This function can not be called statically.

Prev | Image_Text | Next
Class Summary Image_Text | PEAR Manual | Image_Text::autoMeasurize


Image_Text::autoMeasurize

Image_Text::autoMeasurize

Image_Text::autoMeasurize() – Auto measurize text

Synopsis

require_once 'ImageText.php';

int Image_Text::autoMeasurize ( int $start = false , int $end = false )

Description

Automatically determines the greatest possible font size to fit the text into the text box. This method may be very resource intensive on your webserver. A good tweaking point are the $start and $end parameters, which specify the range of font sizes to search through. Anyway, the results should be cached if possible. You can optionally set $start and $end here as a parameter or the settings of the options array are used.

Parameter

integer $start

Fontsize to start testing with.

integer $end

Fontsize to end testing with.

Return value

returns Fontsize measured or PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::measurize()

Note

This function can not be called statically.

Prev | Image_Text | Next
constructor Image_Text::Image_Text | PEAR Manual | Image_Text::display


Image_Text::display

Image_Text::display

Image_Text::display() – Display the image (send it to the browser).

Synopsis

require_once 'ImageText.php';

bool Image_Text::display ( bool $save = false , bool $free = false )

Description

This will output the image to the users browser. You can use the standard IMAGETYPE_* constants to determine which image type will be generated. Optionally you can save your image to a destination you set in the options.

Parameter

boolean $save

Save or not the image on printout.

boolean $free

Free the image on exit.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::save()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::autoMeasurize | PEAR Manual | Image_Text::getImg


Image_Text::getImg

Image_Text::getImg

Image_Text::getImg() – Return the image ressource.

Synopsis

require_once 'ImageText.php';

resource& Image_Text::getImg ( )

Description

Get the image canvas.

Return value

returns Used image resource

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::display | PEAR Manual | Image_Text::init


Image_Text::init

Image_Text::init

Image_Text::init() – Initialiaze the Image_Text object.

Synopsis

require_once 'ImageText.php';

bool Image_Text::init ( )

Description

This method has to be called after setting the options for your Image_Text object. It initializes the canvas, normalizes some data and checks important options. Be shure to check the initialization after you switched some options. The set() method may force you to reinitialize the object.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::set()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::getImg | PEAR Manual | Image_Text::measurize


Image_Text::measurize

Image_Text::measurize

Image_Text::measurize() – Measurize text into the text box

Synopsis

require_once 'ImageText.php';

array Image_Text::measurize ( bool $force = false )

Description

This method makes your text fit into the defined textbox by measurizing the lines for your given font-size. You can do this manually before rendering (or use even Image_Text::autoMeasurize()) or the renderer will do measurizing automatically.

Parameter

boolean $force

Optionally, default is FALSE, set TRUE to force measurizing.

Return value

returns Array of measured lines or PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::autoMeasurize()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::init | PEAR Manual | Image_Text::render


Image_Text::render

Image_Text::render

Image_Text::render() – Render the text in the canvas using the given options.

Synopsis

require_once 'ImageText.php';

bool Image_Text::render ( bool $force = false )

Description

This renders the measurized text or automatically measures it first. The $force parameter can be used to switch of measurizing problems (this may cause your text being rendered outside a given text box or destroy your image completely).

Parameter

boolean $force

Optional, initially FALSE, set TRUE to silence measurize errors.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::measurize | PEAR Manual | Image_Text::save


Image_Text::save

Image_Text::save

Image_Text::save() – Save image canvas.

Synopsis

require_once 'ImageText.php';

bool Image_Text::save ( string $destFile = false )

Description

Saves the image to a given destination. You can leave out the destination file path, if you have the option for that set correctly. Saving is possible with the save() method, too.

Parameter

string $destFile

The destination to save to (optional, uses options value else).

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::display()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::render | PEAR Manual | Image_Text::set


Image_Text::set

Image_Text::set

Image_Text::set() – Set options

Synopsis

require_once 'ImageText.php';

bool Image_Text::set ( mixed $option , mixed $value = null )

Description

Set a single or multiple options. It may happen that you have to reinitialize the Image_Text object after changing options.

Possible options to set
Option Description
x

This sets the top left coordinates (using x/y) or the center point coordinates (using cx/cy) for your text box. The values from cx/cy will overwrite x/y.

y
cx
cy
canvas

You can set different values as a canvas:

  • A gd image resource.

  • An array with 'width' and 'height'.

  • Nothing (the canvas will be measured after the real text size).

antialias

This is usually true. Set it to false to switch antialiasing off.

width

The width and height for your text box.

height
halign

Alignment of your text inside the textbox. Use alignment constants to define vertical and horizontal alignment.

valign
angle

The angle to rotate your text box.

color

An array of color values. Colors will be rotated in the mode you choose (linewise or paragraphwise). Can be in the following formats:

  • String representing HTML style hex couples (+ unusual alpha couple in the first place, optional).

  • Array of int values using 'r', 'g', 'b' and optionally 'a' as keys.

color_mode

The color rotation mode for your color sets. Does only apply if you defined multiple colors. Use 'line' or 'paragraph'.

background_color

Defines the background color. Use NULL if you would like to have the background transparent. Default is #000000.

enable_alpha

If the alpha channel should be enabled. Automatically enabled when background_color is set to NULL. Default is FALSE.

font_path

Location of the font to use.

font_file
font_size

The font size to render text in (will be overwriten if you use automeasurize).

line_spacing

Measure for the line spacing to use. Default is 0.5.

min_font_size

Automeasurize settings. Try to keep this area as small as possible to get better performance.

max_font_size
max_lines

The maximum number of lines to render. Default is 100.

image_type

The type of image (use image type constants). Is default set to PNG.

dest_file

The destination to (optionally) save your file.

Parameter

mixed $option

A single option name or the options array.

mixed $value

Option value if $option is string.

Return value

returns True on success, otherwise PEAR_Error.

Throws

throws no exceptions thrown

See

see Image_Text::Image_Text()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::save | PEAR Manual | Image_Text::setColor


Image_Text::setColor

Image_Text::setColor

Image_Text::setColor() – Set a color

Synopsis

require_once 'ImageText.php';

bool Image_Text::setColor ( mixed $color , mixed $id = 0 )

Description

This method is used to set a color at a specific color ID inside the color cycle.

The following colors syntaxes are understood by this method:

  • "#ffff00" hexadecimal format (HTML style), with and without #.

  • "#08ffff00" hexadecimal format (HTML style) with alpha channel (08), with and without #.

  • array with 'r','g','b' and (optionally) 'a' keys, using int values.

Parameter

mixed $color

Color value.

mixed $id

ID (in the color array) to set color to.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::setColors(), Image_Text::set()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::set | PEAR Manual | Image_Text::setColors


Image_Text::setColors

Image_Text::setColors

Image_Text::setColors() – Set the color-set

Synopsis

require_once 'ImageText.php';

bool Image_Text::setColors ( mixed $colors )

Description

Using this method you can set multiple colors for your text. Use a simple numeric array to determine their order and give it to this function. Multiple colors will be cycled by the options specified 'color_mode' option. The given array will overwrite the existing color settings!

The following colors syntaxes are understood by this method:

  • "#ffff00" hexadecimal format (HTML style), with and without #.

  • "#08ffff00" hexadecimal format (HTML style) with alpha channel (08), with and without #.

  • array with 'r','g','b' and (optionally) 'a' keys, using int values.

  • a GD color special color (tiled,...).

A single color or an array of colors are allowed here.

Parameter

mixed $colors

Single color or array of colors.

Return value

returns True on success, otherwise PEAR::Error.

Throws

throws no exceptions thrown

See

see Image_Text::setColor(), Image_Text::set()

Note

This function can not be called statically.

Prev | Image_Text | Next
Image_Text::setColor | PEAR Manual | Package Image_Text Constants


Package Image_Text Constants

Package Image_Text Constants

Package Image_Text Constants – Constants defined in and used by Image_Text

All Constants

Constants defined in ImageText.php

Constants defined in ImageText.php
Name | Value | Line Number
IMAGE_TEXT_ALIGN_BOTTOM | "bottom",true | 56
IMAGE_TEXT_ALIGN_CENTER | "center",true | 43
IMAGE_TEXT_ALIGN_JUSTIFY | "justify",true | 61
IMAGE_TEXT_ALIGN_LEFT | "left",true | 35
IMAGE_TEXT_ALIGN_MIDDLE | "middle",true | 52
IMAGE_TEXT_ALIGN_RIGHT | "right",true | 39
IMAGE_TEXT_ALIGN_TOP | "top",true | 48
IMAGE_TEXT_REGEX_HTMLCOLOR | ,true"/^/^[#|]([a-f0-9]{2})?([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})$/i" | 30
Prev | Image_Text | Next
Image_Text::setColors | PEAR Manual | Image_Transform


Image_Transform

Image_Transform

Image_Transform main use case is to create thumbnails of images.

Table of Contents
  • General usage
  • Drivers
  • Scaling images
  • Saving
  • Other methods
Prev | Images | Next
Package Image_Text Constants | PEAR Manual | General usage


General usage

General usage

The first step to do when using Image_Transform is to create an Image_Transform_Driver instance via the static factory() method. Just pass the driver name and you've got your object.

Note: You may omit the driver name. In that case, Image_Transform checks for Imagick2, GD and Imlib and uses whatever driver is found first.

Now you can load() your image by passing the filename to this function. Use one of the scaling methods and then save().

You may not execute several scaling functions in a row without saving in between.

Scaling an image down

<?php
require_once 'Image/Transform.php';

//create transform driver object
$it = Image_Transform::factory('GD');

//load the original file
$it->load('beach-large.jpg');

//scale it to 150px
$it->scaleMaxLength(150);

//save it into a different file
$it->save('beach-150px.jpg');
?>

The example above did not do any error checking. Principially, any method may return a PEAR_Error object. Either you check each return value or - in PHP 5 - set the global PEAR error handler to throw exceptions as soon as an error occurs. This may interfere with other errors that are expected and can be hidden, so be careful with this option (especially when using other packages).

Scaling an image and checking for all possible errors

<?php
require_once 'Image/Transform.php';

//create transform driver object
$it = Image_Transform::factory('GD');
if (PEAR::isError($it)) {
    die($it->getMessage());
}

//load the original file
$ret = $it->load('beach-large.jpg');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}

//scale it to 150px
$ret = $it->scaleByLength(150);
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}

//save it into a different file
$ret = $it->save('beach-150px.jpg');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
?>
Prev | Image_Transform | Next
Image_Transform | PEAR Manual | Drivers


Drivers

Drivers

The Image_Transform package is useless without a driver that encapsulates some graphic libraries' methods. As of April 2008, the package has the following drivers you can install and use:

  • Image_Transform_Driver_GD - uses methods of the GD 2 extension

  • Image_Transform_Driver_Imagick2 - for imagick PECL extension version < 2.0

  • Image_Transform_Driver_Imagick3 - for imagick PECL extension version >= 2.0

  • Image_Transform_Driver_Imlib - uses PHP imlib extension

  • Image_Transform_Driver_IM - Imagick binary executables (if you don't have the extension)

  • Image_Transform_Driver_NetPBM - uses the binary executable pnmscale of the NetPBM software package.

Prev | Image_Transform | Next
General usage | PEAR Manual | Scaling images


Scaling images

Scaling images

Image_Transform brings you a lot of methods to scale images. Most of them call the basic resizing method with different parameters, but still have their right to exist because they make your life convenient. Here is a short list:

  • resize - generic resizing method. Pass any size, percentage string (with %) or a scaling factor for both x and y values. Keep it 0 to keep that size. Does not necessarily keep the aspect ratio.

  • scaleByX - scale the image by resizing the width of the image to the given pixel size. Preserves aspect ratio.

  • scaleByY - scale the image by resizing the height of the image to the given pixel size. Preserves aspect ratio.

  • scale - generig scaling function. Pass a pixel value, percentage (with %) or scaling factor (<1). Keeps aspect ratio.

  • scaleByPercentage - scales by the given percentage.

  • scaleByFactor - same as scaleByPercentage(), just that the numbers are factor 100 smaller.

  • scaleByLength - scale so that the longest size has the desired size.

  • fit - scale the image so that it fits into the given box (width and height). Nothing is done if the image is already smaller or equal than the box size.

  • fitX - scale the image so that the width is the given size. If the width is already smaller, nothing is done.

  • fitY - scale the image so that the height is the given size. If the height is already smaller, nothing is done.

Prev | Image_Transform | Next
Drivers | PEAR Manual | Saving


Saving

Saving

The save() method requires at least one parameter, the filename as which the scaled image is to be saved as. With only one parameter, the type of the new image is the same as the original type.

Note: File extensions are not appended if left out.

The second parameter can be the extension of the file type you want to save the image as, for example png or jpg.

In case of an error - for example if the driver does not support to write the file type - a PEAR_Error object is returned.

Instead of saving, you can directly put out the image to the browser using display().

Prev | Image_Transform | Next
Scaling images | PEAR Manual | Other methods


Other methods

Other methods

Driver support for transformation methods
Method | GD | Imagick2 | Imagick3 | Imlib | IM | NetPBM
_resize() | yes | yes | yes | yes | yes | yes
save() | yes | yes | yes | yes | yes | yes
display() | yes | yes | yes | yes | yes | yes
free() | yes | yes | yes | yes | yes | yes
addText() | yes | yes | yes | yes | yes | yes
addDropShadow() | - | - | - | - | - | -
addBorder() | yes | - | - | - | - | -
crop() | yes | yes | yes | yes | yes | yes
canvasResize() | - | - | - | - | - | -
fitOnCanvas() | - | - | - | - | - | -
flip() | yes | yes | yes | yes | yes | yes
gamma() | yes | yes | yes | - | yes | yes
greyscale() | yes | - | yes | - | yes | yes
mirror() | yes | yes | yes | yes | yes | yes
normalize() | - | - | - | - | - | -
rotate() | yes | yes | yes | yes | yes | yes
Prev | Image_Transform | Next
Saving | PEAR Manual | Internationalization


Internationalization

Internationalization

Provides packages for internationalization and localization.

Table of Contents
  • I18Nv2
  • Translation2
Prev | PEAR Packages | Next
Other methods | PEAR Manual | I18Nv2


I18Nv2

I18Nv2

Table of Contents
  • Class Summary I18Nv2 -- I18Nv2 - Internationalization v2
  • Intro -- Introduction to I18Nv2
  • Examples -- Usage example for I18Nv2
  • I18Nv2 Constants -- Constants defined in and used by I18Nv2
  • I18Nv2::setLocale -- Set locale
  • I18Nv2::lastLocale -- Get current/prior locale
  • I18Nv2::getInfo -- Get several locale specific information
  • I18Nv2::autoConv -- Automatically transform output between character sets
  • I18Nv2::createLocale -- Create an I18Nv2_Locale object
  • I18Nv2::createNegotiator -- Create an I18Nv2_Negotiator object
  • I18Nv2::langs2locales -- Transform languages to locales
  • I18Nv2::locales2langs -- Transform locales to languages
  • Class Summary I18Nv2_Locale -- I18Nv2_Locale
  • I18Nv2_Locale::I18Nv2_Locale -- Constructor
  • I18Nv2_Locale::initialize -- Initialize
  • I18Nv2_Locale::loadExtension -- Loads corresponding locale extension
  • I18Nv2_Locale::setLocale -- Set locale
  • I18Nv2_Locale::setDefaults -- Set defaults
  • I18Nv2_Locale::setCustomFormat -- Set custom format
  • I18Nv2_Locale::setCurrencyFormat -- Set currency format
  • I18Nv2_Locale::setDateFormat -- Set date format
  • I18Nv2_Locale::setNumberFormat -- Set number format
  • I18Nv2_Locale::setTimeFormat -- Set time format
  • I18Nv2_Locale::formatDate -- Format a date
  • I18Nv2_Locale::formatTime -- Format a time
  • I18Nv2_Locale::formatNumber -- Format a number
  • I18Nv2_Locale::formatCurrency -- Format currency
  • I18Nv2_Locale::date -- Get local date
  • I18Nv2_Locale::time -- Get local time
  • I18Nv2_Locale::dayName -- Get local day name
  • I18Nv2_Locale::monthName -- Get local month name
  • Class Summary I18Nv2_Negotiator -- I18Nv2_Negotiator
  • I18Nv2_Negotiator::I18Nv2_Negotiator -- Constructor
  • I18Nv2_Negotiator::getCharsetMatch -- Get character set match
  • I18Nv2_Negotiator::getCountryMatch -- Get country match
  • I18Nv2_Negotiator::getLanguageMatch -- Get language match
  • I18Nv2_Negotiator::getLocaleMatch -- Get locale match
  • I18Nv2_Negotiator::getVariantInfo -- Return variant info for passed parameter.
  • I18Nv2_Negotiator::singleI18NCountry -- Create the Country helper object
  • I18Nv2_Negotiator::singleI18NLanguage -- Create the Language helper object
  • Class Summary I18Nv2_Country -- I18Nv2_Country
  • I18Nv2_Country::I18Nv2_Country -- Constructor
  • I18Nv2_Country::getAllCodes -- Get all codes
  • I18Nv2_Country::getName -- Get country name
  • I18Nv2_Country::isValidCode -- Check if country code is valid
  • Class Summary I18Nv2_Language -- I18Nv2_Language
  • I18Nv2_Language::I18Nv2_Language -- Constructor
  • I18Nv2_Language::getAllCodes -- Get all codes
  • I18Nv2_Language::getName -- Return name of the language for language code
  • I18Nv2_Language::isValidCode -- Check if language code is valid
Prev | Internationalization | Next
Internationalization | PEAR Manual | Class Summary I18Nv2


Class Summary I18Nv2

Class Summary I18Nv2

Class Summary I18Nv2 – I18Nv2 - Internationalization v2

I18Nv2 - Internationalization v2

The static I18Nv2 class currently provides routines for unified (ment as OS independent) locale setting, retrieving locale specific information like the "thousands separator" and automatic characterset conversion for output.

This documentation is outdated and needs an overhaul.

Prev | I18Nv2 | Next
I18Nv2 | PEAR Manual | Intro


Intro

Intro

Intro – Introduction to I18Nv2

Preface

The work on I18Nv2 has actually started as a refactoring of I18N, but after some time I figured out that too many BC breaking changes were applied, so the release of a new major version was suggested.

Differences to I18N

I18N was modeled after Java OO practice and it provides a bunch of classes for each formatting action (numbers, currencies, dates).

I18Nv2 takes another approach and provides all formatting functionality within one class, which is I18Nv2_Locale.

I18Nv2_Locale is based upon PHPs builtin functionality of setlocale() , localeconv () and iconv related functions, while I18N completely depends on user contributed formatting rules.

I wouldn't say I18Nv2's approach is the better one, because it depends on the internationalization capabilities of the underlying operating system, but it's simpler and faster - though it is in need of user contributed date and time formatting rules.

I18N's translation functionality was dropped in favour of the new and shiny Translation2.

I18Nv2 still provides an HTTP negotiator to reveal the users preferred language/locale and charset.

I18Nv2 has translated lists of ISO country and language names for about 50 different languages. See I18Nv2_Country and I18Nv2_Language.

Prev | I18Nv2 | Next
Class Summary I18Nv2 | PEAR Manual | Examples


Examples

Examples

Examples – Usage example for I18Nv2

API Documentation

Please see PEARs API Documentation for details on the API provided by I18Nv2.

Setting a locale

Because Un*x and Windows use different locale codes, PHPs setLocale() is not easily portable - I18Nv2::setLocale() attempts to provide this portability.

With I18Nv2 you can use standard locale codes like 'en_US' on both, Linux and Windows, though the list is far not complete yet, so if you stumble over a not covered locale (I18Nv2::$locales in I18Nv2::_main()), just drop a mail to the maintainer with the missing locale and its corresponding Win32 code.

I18Nv2::setLocale()

<?php
require_once 'I18Nv2.php';

foreach (array('en_US', 'de', 'fr_CN') as $locale) {
    if (!$syslocale = I18Nv2::setLocale($locale)) {
        echo "Locale '$locale' not available!\n";
    } else {
        echo "Systems locale for '$locale': '$syslocale'\n";
    }
}
?>

Retrieving locale conventions

I18Nv2 holds locale conventions returned by localeConv() stored statically, so they are easily accessible through I18Nv2::getInfo(). Have a look at the documentation of PHPs localeConv() for all available information.

I18Nv2::getInfo()

<?php
require_once 'I18Nv2.php';

I18Nv2::setLocale('fr');

$dec_point = I18Nv2::getInfo('decimal_point');
echo "The decimal point for the french locale is '$dec_point'.\n";
echo "I18Nv2::getInfo() called without parameter returns all available information:\n";
print_r(I18Nv2::getInfo());
?>

Automatically transform output character set

I18Nv2 provides an easy way to utilize the ob_iconv_handler() through I18Nv2::autoConv().

I18Nv2::autoConv()

<?php
require_once 'I18Nv2.php';

// Writing a shell app that should also display nicely in a DOS box
if (I18Nv2_WIN) {
    I18Nv2::autoConv('CP850');
}

// output some latin1 stuff
echo "äüöß\n";
?>

Using I18Nv2_Locale

I18Nv2_Locale is a formatter object that provides functionality to format dates, times, numbers and currencies in locale dependent conventions.

I18Nv2_Locale

<?php
require_once 'I18Nv2.php';

$locale = &I18Nv2::createLocale('de_AT');

echo "Format a currency value of 2000: ",
    $locale->formatCurrency(2000, I18Nv2_CURRENCY_INTERNATIONAL), "\n";

echo "Format todays date:              ",
    $locale->formatDate(null, I18Nv2_DATETIME_FULL), "\n";

echo "Format current time:             ",
    $locale->formatTime(null, I18Nv2_DATETIME_SHORT), "\n";
?>

Using I18Nv2_Negotiator

I18Nv2 provides a language, charset and locale negotiator for HTTP.

I18Nv2_Negotiator

<?php
require_once 'I18Nv2/Negotiator.php';

$_SERVER['HTTP_ACCEPT_LANGUAGE'] = 'en-US,en-GB,en;q=0.5,de';
$_SERVER['HTTP_ACCEPT_CHARSET']  = 'utf-8,iso-8859-1;q=0.5';

$neg = &new I18Nv2_Negotiator;

echo "User agents preferred language:                  ",
    $lang = $neg->getLanguageMatch(), "\n";

echo "User agents preferred country for language '$lang': ",
    $neg->getCountryMatch($lang), "\n";

echo "User agents preferred locale:                    ",
    $neg->getLocaleMatch(), "\n";

echo "User agents preferred charset:                   ",
    $neg->getCharsetMatch(), "\n";
?>

Using I18Nv2_Language

I18Nv2 provides translated lists of ISO language names.

I18Nv2_Language

<?php
require_once 'I18Nv2/Language.php';

$lang = &new I18Nv2_Language('it', 'iso-8859-1');

echo "Italian name for English: ",
    $lang->getName('en'), "\n";

echo "Italian name for French:  ",
    $lang->getName('fr'), "\n";
?>

Using I18Nv2_Country

I18Nv2 provides translated lists of ISO country names.

I18Nv2_Country

<?php
require_once 'I18Nv2/Country.php';

$country = &new I18Nv2_Country('de', 'iso-8859-1');

echo "German name for United States: ",
    $country->getName('us'), "\n";

echo "German name for Italia:        ",
    $country->getName('it'), "\n";
?>

Using I18Nv2_Country

I18Nv2 provides decorated classes for country and language lists.

I18Nv2_DecoratedList

<?php
require_once 'I18Nv2/Country.php';
require_once 'I18Nv2/DecoratedList/HtmlSelect.php';
require_once 'I18Nv2/DecoratedList/HtmlEntities.php';

$c = &new I18Nv2_Country('it', 'iso-8859-1');
$e = &new I18Nv2_DecoratedList_HtmlEntities($c);
$s = &new I18Nv2_DecoratedList_HtmlSelect($e);

// set some attributes
$s->attributes['select']['name'] = 'CountrySelect';
$s->attributes['select']['onchange'] = 'this.form.submit()';

// set a selected entry
$s->selected['DE'] = true;

// print a HTML safe select box
echo $s->getAllCodes();
?>

I18Nv2_CommonList::toDecoratedList()

<?php
require_once 'I18Nv2/Country.php';

$c = &new I18Nv2_Country('it', 'iso-8859-1');
$s = &$c->toDecoratedList('HtmlSelect');

// set some attributes
$s->attributes['select']['name'] = 'CountrySelect';
$s->attributes['select']['onchange'] = 'this.form.submit()';

// set a selected entry
$s->selected['IT'] = true;

// print a HTML select box
echo $s->getAllCodes();
?>
Prev | I18Nv2 | Next
Intro | PEAR Manual | I18Nv2 Constants


I18Nv2 Constants

I18Nv2 Constants

I18Nv2 Constants – Constants defined in and used by I18Nv2

All Constants

Constants defined in Locale.php

Constants defined in I18Nv2/Locale.php
Name | Value
I18Nv2_CURRENCY | 20
I18Nv2_CURRENCY_INTERNATIONAL | 22
I18Nv2_CURRENCY_LOCAL | 21
I18Nv2_DATETIME | 30
I18Nv2_DATETIME_DEFAULT | 32
I18Nv2_DATETIME_FULL | 35
I18Nv2_DATETIME_LONG | 34
I18Nv2_DATETIME_MEDIUM | 33
I18Nv2_DATETIME_SHORT | 31
I18Nv2_NUMBER | 10
I18Nv2_NUMBER_FLOAT | 11
I18Nv2_NUMBER_INTEGER | 12
Prev | I18Nv2 | Next
Examples | PEAR Manual | I18Nv2::setLocale


I18Nv2::setLocale

I18Nv2::setLocale

I18Nv2::setLocale() – Set locale

Synopsis

require_once 'I18Nv2.php';

mixed I18Nv2::setLocale ( string $locale , int $cat = LC_ALL )

Description

Set environment to the specified locale.

Set a locale:

<?php
1  require_once 'I18Nv2.php';
2  I18Nv2::setLocale('en_GB');
?>

Parameter

string $locale

a valid locale like en_US or de_DE

integer $cat

the locale category - usually LC_ALL

Return value

Returns string used system locale or false on failure.

Note

This function should be called statically.

See

See also
I18Nv2::setLocale() example,
I18Nv2::getInfo(),
I18Nv2::lastLocale(),
PHPs setlocale().

Prev | I18Nv2 | Next
I18Nv2 Constants | PEAR Manual | I18Nv2::lastLocale


I18Nv2::lastLocale

I18Nv2::lastLocale

I18Nv2::lastLocale() – Get current/prior locale

Synopsis

require_once 'I18Nv2.php';

string I18Nv2::lastLocale ( int $prior = 0 , bool $full = false )

Description

Retrieve kinda history of locales that have been already set.

This only works, if I18Nv2::setLocale() has already been called.

Parameter

integer $prior

if 0, the current otherwise n prior to the current locale

boolean $full

whether to return the array with locale, language and actually used system locale

Return value

Returns mixed prior locale.

Note

This function should be called statically.

See

See also I18Nv2::setLocale().

Prev | I18Nv2 | Next
I18Nv2::setLocale | PEAR Manual | I18Nv2::getInfo


I18Nv2::getInfo

I18Nv2::getInfo

I18Nv2::getInfo() – Get several locale specific information

Synopsis

require_once 'I18Nv2.php';

mixed I18Nv2::getInfo ( string $part = null )

Description

Get several locale specific information like thousands separator. The provided information debends on the local libc implementation and thus is not always reliable - especially on Microsoft Windows.

Retrieving specific locale information:

<?php
1  require_once 'I18Nv2.php';
2  $locale = I18Nv2::setLocale('en_US');
3  $thsep  = I18Nv2::getInfo('thousands_separator');
4  $point  = I18Nv2::getInfo('decimal_point');
?>

Parameter

string$part

specific part of locale information

Return value

Returns mixed locale specific information or array all available locale specific information if called without parameter.

Note

This function should be called statically.

See

See also I18Nv2::setLocale(), PHPs localeconv().

Prev | I18Nv2 | Next
I18Nv2::lastLocale | PEAR Manual | I18Nv2::autoConv


I18Nv2::autoConv

I18Nv2::autoConv

I18Nv2::autoConv() – Automatically transform output between character sets

Synopsis

require_once 'I18Nv2.php';

 mixed I18Nv2::autoConv (
 string $ocs = 'UTF-8'
  , string $ics = 'ISO-8859-1'
)

Description

This method utilizes ob_iconv_handler(), so you should call it at the beginning of your script (prior to any output).

<?php
1   require_once 'I18Nv2.php';
2   I18Nv2::autoConv('iso-8859-1', 'utf-8');
3   // ...
?>

Parameter

string $ocs

desired output character set

string $ics

current intput character set

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns PEAR_Error if output buffering couldn't be started.

Note

This function should be called statically.

See

See also PHPs ob_iconv_handler().

Prev | I18Nv2 | Next
I18Nv2::getInfo | PEAR Manual | I18Nv2::createLocale


I18Nv2::createLocale

I18Nv2::createLocale

I18Nv2::createLocale() – Create an I18Nv2_Locale object

Synopsis

require_once 'I18Nv2.php';

object I18Nv2_Locale &I18Nv2::createLocale ( string $locale = null )

Description

Create a new I18Nv2_Locale object with the specified locale.

Parameter

string $locale

a locale like en_US or de_DE

Return value

Returns new object I18Nv2_Locale.

Note

This function should be called statically.

See

See also I18Nv2_Locale.

Prev | I18Nv2 | Next
I18Nv2::autoConv | PEAR Manual | I18Nv2::createNegotiator


I18Nv2::createNegotiator

I18Nv2::createNegotiator

I18Nv2::createNegotiator() – Create an I18Nv2_Negotiator object

Synopsis

require_once 'I18Nv2.php';

object I18Nv2_Negotiator &I18Nv2::createNegotiator ( string $defLang = 'en' , string $defCharset = 'iso-8859-1' )

Description

Create a new I18Nv2_Negotiator object with the specified default language and default character set.

Parameter

string $defLang

default language

string $defCharset

default character set

Return value

Returns new object I18Nv2_Negotiator.

Note

This function should be called statically.

See

See also I18Nv2_Negotiator.

Prev | I18Nv2 | Next
I18Nv2::createLocale | PEAR Manual | I18Nv2::langs2locales


I18Nv2::langs2locales

I18Nv2::langs2locales

I18Nv2::langs2locales() – Transform languages to locales

Synopsis

require_once 'I18Nv2.php';

array I18Nv2::langs2locales ( array $languages )

Description

Transforms language codes like en-US and de-DE to locale codes like en_US and de_DE.

Parameter

array $languages

array of language codes

Return value

Returns array transformed language codes as locale codes.

Note

This function should be called statically.

See

See also I18Nv2::locales2langs().

Prev | I18Nv2 | Next
I18Nv2::createNegotiator | PEAR Manual | I18Nv2::locales2langs


I18Nv2::locales2langs

I18Nv2::locales2langs

I18Nv2::locales2langs() – Transform locales to languages

Synopsis

require_once '/I18Nv2.php';

array I18Nv2::locales2langs ( array $locales )

Description

Transforms locale codes like en_US and de_DE to language codes like en-US and de-DE.

Parameter

array $locales

array of locale codes

Return value

Returns array transformed loclae codes as language codes.

Note

This function should be called statically.

See

See also I18Nv2::langs2locales().

Prev | I18Nv2 | Next
I18Nv2::langs2locales | PEAR Manual | Class Summary I18Nv2_Locale


Class Summary I18Nv2_Locale

Class Summary I18Nv2_Locale

Class Summary I18Nv2_Locale – I18Nv2_Locale

I18Nv2_Locale

Represents a specific locale and provides routines for formatting date and time, numbers and currency.

Prev | I18Nv2 | Next
I18Nv2::locales2langs | PEAR Manual | I18Nv2_Locale::I18Nv2_Locale


I18Nv2_Locale::I18Nv2_Locale

I18Nv2_Locale::I18Nv2_Locale

I18Nv2_Locale::I18Nv2_Locale() – Constructor

Synopsis

require_once 'I18Nv2/Locale.php';

object I18Nv2_Locale::I18Nv2_Locale ( string $locale = null )

Description

Instantiate a new I18Nv2_Locale object with the specified locale.

Parameter

string $locale

the desired locale like en_US or de_DE

Return value

Returns new object I18Nv2_Locale.

Prev | I18Nv2 | Next
Class Summary I18Nv2_Locale | PEAR Manual | I18Nv2_Locale::initialize


I18Nv2_Locale::initialize

I18Nv2_Locale::initialize

I18Nv2_Locale::initialize() – Initialize

Synopsis

require_once 'I18Nv2/Locale.php';

void I18Nv2_Locale::initialize ( )

Description

Initializes the I18Nv2_Locale object.

This method gets aumatically called by the constructor.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::I18Nv2_Locale | PEAR Manual | I18Nv2_Locale::loadExtension


I18Nv2_Locale::loadExtension

I18Nv2_Locale::loadExtension

I18Nv2_Locale::loadExtension() – Loads corresponding locale extension

Synopsis

require_once 'I18Nv2/Locale.php';

void I18Nv2_Locale::loadExtension ( )

Description

Load available locale extensions.

This method gets called autmatically by the constructor.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::initialize | PEAR Manual | I18Nv2_Locale::setLocale


I18Nv2_Locale::setLocale

I18Nv2_Locale::setLocale

I18Nv2_Locale::setLocale() – Set locale

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::setLocale ( string $locale )

Description

Transforms the I18Nv2_Locale object to the specified locale.

Parameter

string $locale

the locale like en_US or de_DE

Return value

Returns TRUE on success, PEAR_Error on failure.

Returns a PEAR_Error if the supplied locale was invalid.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::loadExtension | PEAR Manual | I18Nv2_Locale::setDefaults


I18Nv2_Locale::setDefaults

I18Nv2_Locale::setDefaults

I18Nv2_Locale::setDefaults() – Set defaults

Synopsis

require_once 'I18Nv2/Locale.php';

void I18Nv2_Locale::setDefaults ( )

Description

Reset used formats to the default values.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setLocale | PEAR Manual | I18Nv2_Locale::setCustomFormat


I18Nv2_Locale::setCustomFormat

I18Nv2_Locale::setCustomFormat

I18Nv2_Locale::setCustomFormat() – Set custom format

Synopsis

require_once 'I18Nv2/Locale.php';

void I18Nv2_Locale::setCustomFormat ( mixed $type = null , mixed $format = null )

Description

Set a custom format.

If $format is omitted, the custom format for $type will be discarded - if both vars are omitted all custom formats will be discarded.

Parameter

mixed $type

the I18Nv2 format category for which to set the custom format

mixed $format

the custom format

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setDefaults | PEAR Manual | I18Nv2_Locale::setCurrencyFormat


I18Nv2_Locale::setCurrencyFormat

I18Nv2_Locale::setCurrencyFormat

I18Nv2_Locale::setCurrencyFormat() – Set currency format

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::setCurrencyFormat ( int $format , bool $custom = false )

Description

Set the currency format to use.

Either I18Nv2_CURRENCY_LOCAL, I18Nv2_CURRENCY_INTERNATIONAL or a custom currency format.

Parameter

integer $format

a I18Nv2_CURRENCY constant

boolean $custom

whether to use a defined custom format

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setCustomFormat | PEAR Manual | I18Nv2_Locale::setDateFormat


I18Nv2_Locale::setDateFormat

I18Nv2_Locale::setDateFormat

I18Nv2_Locale::setDateFormat() – Set date format

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::setDateFormat ( int $format , bool $custom = false )

Description

Set the date format to use.

Either a I18Nv2_DATETIME constant or a custom date format.

Parameter

integer $format

a I18Nv2_DATETIME constant

boolean $custom

whether to use a defined custom format

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setCurrencyFormat | PEAR Manual | I18Nv2_Locale::setNumberFormat


I18Nv2_Locale::setNumberFormat

I18Nv2_Locale::setNumberFormat

I18Nv2_Locale::setNumberFormat() – Set number format

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::setNumberFormat ( int $format , bool $custom = false )

Description

Set the number format to use.

Either a I18Nv2_NUMBER constant or a custom number format.

Parameter

integer $format

a I18Nv2_NUMBER constant

boolean $custom

whether to use a defined custom format

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setDateFormat | PEAR Manual | I18Nv2_Locale::setTimeFormat


I18Nv2_Locale::setTimeFormat

I18Nv2_Locale::setTimeFormat

I18Nv2_Locale::setTimeFormat() – Set time format

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::setTimeFormat ( int $format , bool $custom = false )

Description

Set a time format to use.

Either a I18Nv2_DATETIME constant or a custom time format.

Parameter

integer $format

a I18Nv2_DATETIME constant

boolean $custom

whether to use a defined custom format

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setNumberFormat | PEAR Manual | I18Nv2_Locale::formatDate


I18Nv2_Locale::formatDate

I18Nv2_Locale::formatDate

I18Nv2_Locale::formatDate() – Format a date

Synopsis

require_once 'I18Nv2/Locale.php';

string I18Nv2_Locale::formatDate ( int $timestamp = null )

Description

Format a date corresponding to the current locale.

Parameter

integer $timestamp

timestamp which should be formatted

Return value

Returns string formatted date.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::setTimeFormat | PEAR Manual | I18Nv2_Locale::formatTime


I18Nv2_Locale::formatTime

I18Nv2_Locale::formatTime

I18Nv2_Locale::formatTime() – Format a time

Synopsis

require_once 'I18Nv2/Locale.php';

string I18Nv2_Locale::formatTime ( int $timestamp = null )

Description

Format a time corresponding to the current locale.

Parameter

integer $timestamp

timestamp which should be formatted

Return value

Returns string formatted time.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::formatDate | PEAR Manual | I18Nv2_Locale::formatNumber


I18Nv2_Locale::formatNumber

I18Nv2_Locale::formatNumber

I18Nv2_Locale::formatNumber() – Format a number

Synopsis

require_once 'I18Nv2/Locale.php';

string I18Nv2_Locale::formatNumber ( numeric $value )

Description

Format a number corresponding to the current locale.

Parameter

numeric $value

numeric value which should be formatted

Return value

Returns string formatted number.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::formatTime | PEAR Manual | I18Nv2_Locale::formatCurrency


I18Nv2_Locale::formatCurrency

I18Nv2_Locale::formatCurrency

I18Nv2_Locale::formatCurrency() – Format currency

Synopsis

require_once 'I18Nv2/Locale.php';

string I18Nv2_Locale::formatCurrency ( numeric $value )

Description

Format a currecy value corresponding to the current locale.

Parameter

numeric $value

numeric value which should be formatted

Return value

Returns string formatted currency value.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::formatNumber | PEAR Manual | I18Nv2_Locale::date


I18Nv2_Locale::date

I18Nv2_Locale::date

I18Nv2_Locale::date() – Get local date

Synopsis

require_once 'I18Nv2/Locale.php';

string I18Nv2_Locale::date ( int $timestamp = null )

Description

Get the local date as returned by strftime('%x').

Parameter

integer $timestamp

timestamp which should be formatted

Return value

Returns string local date.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::formatCurrency | PEAR Manual | I18Nv2_Locale::time


I18Nv2_Locale::time

I18Nv2_Locale::time

I18Nv2_Locale::time() – Get local time

Synopsis

require_once 'I18Nv2/Locale.php';

string I18Nv2_Locale::time ( int $timestamp = null )

Description

Get the local textual representation of a time as returned by strftime('%X').

Parameter

integer $timestamp

timestamp which should be formatted

Return value

Returns string formatted time.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::date | PEAR Manual | I18Nv2_Locale::dayName


I18Nv2_Locale::dayName

I18Nv2_Locale::dayName

I18Nv2_Locale::dayName() – Get local day name

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::dayName ( int $weekday , bool $short = false )

Description

Get the local textual representation of a weekday.

Parameter

integer $weekday

numerical representation of weekday (0 = Sunday, 1 = Monday, ...)

boolean $short

whether to return the abbreviation

Return value

Returns string name of weekday on success or PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::time | PEAR Manual | I18Nv2_Locale::monthName


I18Nv2_Locale::monthName

I18Nv2_Locale::monthName

I18Nv2_Locale::monthName() – Get local month name

Synopsis

require_once 'I18Nv2/Locale.php';

mixed I18Nv2_Locale::monthName ( int $month , bool $short = false )

Description

Get the local textual representation of a month.

Parameter

integer $month

numerical representation of month (0 = January, 1 = February, ...)

boolean $short

whether to return the abbreviation

Return value

Returns string name of month on success or PEAR_Error on failure.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Locale::dayName | PEAR Manual | Class Summary I18Nv2_Negotiator


Class Summary I18Nv2_Negotiator

Class Summary I18Nv2_Negotiator

Class Summary I18Nv2_Negotiator – I18Nv2_Negotiator

I18Nv2_Negotiator

Provides basic negotiation of user preferred locale, language and characterset.

Prev | I18Nv2 | Next
I18Nv2_Locale::monthName | PEAR Manual | I18Nv2_Negotiator::I18Nv2_Negotiator


I18Nv2_Negotiator::I18Nv2_Negotiator

I18Nv2_Negotiator::I18Nv2_Negotiator

I18Nv2_Negotiator::I18Nv2_Negotiator() – Constructor

Synopsis

require_once 'I18N/Negotiator.php';

object I18Nv2_Negotiator I18Nv2_Negotiator::I18Nv2_Negotiator ( string $defaultLanguage = 'en' , string $defaultCharset = 'iso-8859-1' , string $defaultCountry = '' )

Description

Find language code, country code, charset code, and dialect or variant of locale setting in HTTP request headers.

Parameter

string $defaultLanguage

default language

string $defaultCharset

default character set

string $defaultCountry

default country

Return value

Returns object I18Nv2_Negotiator.

Prev | I18Nv2 | Next
Class Summary I18Nv2_Negotiator | PEAR Manual | I18Nv2_Negotiator::getCharsetMatch


I18Nv2_Negotiator::getCharsetMatch

I18Nv2_Negotiator::getCharsetMatch

I18Nv2_Negotiator::getCharsetMatch() – Get character set match

Synopsis

require_once 'I18Nv2/Negotiator.php';

string I18Nv2_Negotiator::getCharsetMatch ( array $charsets = null )

Description

Get a matching character set.

Parameter

array $charsets

array of character sets

Return value

Returns string matched character set.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::I18Nv2_Negotiator | PEAR Manual | I18Nv2_Negotiator::getCountryMatch


I18Nv2_Negotiator::getCountryMatch

I18Nv2_Negotiator::getCountryMatch

I18Nv2_Negotiator::getCountryMatch() – Get country match

Synopsis

require_once 'I18Nv2/Negotiator.php';

string I18Nv2_Negotiator::getCountryMatch ( string $lang , array $countries = null )

Description

Get a matching country code.

Parameter

string $lang

language code

array $countries

array of country codes

Return value

Returns string matching country.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::getCharsetMatch | PEAR Manual | I18Nv2_Negotiator::getLanguageMatch


I18Nv2_Negotiator::getLanguageMatch

I18Nv2_Negotiator::getLanguageMatch

I18Nv2_Negotiator::getLanguageMatch() – Get language match

Synopsis

require_once 'I18Nv2/Negotiator.php';

string I18Nv2_Negotiator::getLanguageMatch ( array $langs = null )

Description

Get a matching language code.

Parameter

array $langs

array of language codes

Return value

Returns string matching language code.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::getCountryMatch | PEAR Manual | I18Nv2_Negotiator::getLocaleMatch


I18Nv2_Negotiator::getLocaleMatch

I18Nv2_Negotiator::getLocaleMatch

I18Nv2_Negotiator::getLocaleMatch() – Get locale match

Synopsis

require_once 'I18Nv2/Negotiator.php';

string I18Nv2_Negotiator::getLocaleMatch ( array $langs = null , array $countries = null )

Description

Get a matching locale code.

This method is a combination of I18Nv2::getLanguageMatch() and I18Nv2::getCountryMatch()

Parameter

array $langs

array of language codes

array $countries

array of country codes

Return value

Returns string matching locale code.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::getLanguageMatch | PEAR Manual | I18Nv2_Negotiator::getVariantInfo


I18Nv2_Negotiator::getVariantInfo

I18Nv2_Negotiator::getVariantInfo

I18Nv2_Negotiator::getVariantInfo() – Return variant info for passed parameter.

Synopsis

require_once '/Negotiator.php';

string I18Nv2_Negotiator::getVariantInfo ( string $lang )

Description

This package is not documented yet.

Parameter

string $lang

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::getLocaleMatch | PEAR Manual | I18Nv2_Negotiator::singleI18NCountry


I18Nv2_Negotiator::singleI18NCountry

I18Nv2_Negotiator::singleI18NCountry

I18Nv2_Negotiator::singleI18NCountry() – Create the Country helper object

Synopsis

require_once 'I18Nv2/Negotiator.php';

object &I18Nv2_Negotiator::singleI18NCountry ( )

Description

Singleton for I18Nv2_Country.

Return value

Returns object I18Nv2_Country.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::getVariantInfo | PEAR Manual | I18Nv2_Negotiator::singleI18NLanguage


I18Nv2_Negotiator::singleI18NLanguage

I18Nv2_Negotiator::singleI18NLanguage

I18Nv2_Negotiator::singleI18NLanguage() – Create the Language helper object

Synopsis

require_once 'I18Nv2/Negotiator.php';

object &I18Nv2_Negotiator::singleI18NLanguage ( )

Description

Singleton for I18Nv2_Language.

Return value

Returns object I18Nv2_Language.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::singleI18NCountry | PEAR Manual | Class Summary I18Nv2_Country


Class Summary I18Nv2_Country

Class Summary I18Nv2_Country

Class Summary I18Nv2_Country – I18Nv2_Country

I18Nv2_Country

List of two letter country code to country name mapping.

Prev | I18Nv2 | Next
I18Nv2_Negotiator::singleI18NLanguage | PEAR Manual | I18Nv2_Country::I18Nv2_Country


I18Nv2_Country::I18Nv2_Country

I18Nv2_Country::I18Nv2_Country

I18Nv2_Country::I18Nv2_Country() – Constructor

Synopsis

require_once 'I18Nv2/Country.php';

object I18Nv2_Country I18Nv2_Country::I18Nv2_Country ( )

Description

Instantiate a new I18Nv2_Country object.

Return value

Returns object I18Nv2_Country.

Prev | I18Nv2 | Next
Class Summary I18Nv2_Country | PEAR Manual | I18Nv2_Country::getAllCodes


I18Nv2_Country::getAllCodes

I18Nv2_Country::getAllCodes

I18Nv2_Country::getAllCodes() – Get all codes

Synopsis

require_once 'I18Nv2/Country.php';

array I18Nv2_Country::getAllCodes ( )

Description

Get all country codes as associative array indexed by their two letter codes.

Return value

Returns array all country codes.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Country::I18Nv2_Country | PEAR Manual | I18Nv2_Country::getName


I18Nv2_Country::getName

I18Nv2_Country::getName

I18Nv2_Country::getName() – Get country name

Synopsis

require_once 'I18Nv2/Country.php';

string I18Nv2_Country::getName ( string $code )

Description

Get the corresponding country name of the supplied two letter country code.

Parameter

string $code

two letter country code

Return value

Returns string country name.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Country::getAllCodes | PEAR Manual | I18Nv2_Country::isValidCode


I18Nv2_Country::isValidCode

I18Nv2_Country::isValidCode

I18Nv2_Country::isValidCode() – Check if country code is valid

Synopsis

require_once 'I18Nv2/Country.php';

bool I18Nv2_Country::isValidCode ( string $code )

Description

Check if the supplied two letter country code is valid.

Parameter

string $code

two letter country code

Return value

Returns boolean whether the two letter country code is valid.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Country::getName | PEAR Manual | Class Summary I18Nv2_Language


Class Summary I18Nv2_Language

Class Summary I18Nv2_Language

Class Summary I18Nv2_Language – I18Nv2_Language

I18Nv2_Language

List of ISO-639-1 two letter resp. ISO-639-2 three letter language code to language name mapping.

Prev | I18Nv2 | Next
I18Nv2_Country::isValidCode | PEAR Manual | I18Nv2_Language::I18Nv2_Language


I18Nv2_Language::I18Nv2_Language

I18Nv2_Language::I18Nv2_Language

I18Nv2_Language::I18Nv2_Language() – Constructor

Synopsis

require_once 'I18Nv2/Language.php';

object object I18Nv2_Language I18Nv2_Language::I18Nv2_Language ( bool $threeLetters = false )

Description

Instantiate a new I18Nv2_Language object.

Parameter

boolean $threeLetters

whether to use ISO-639-2 three letters or ISO-639-1 two letters language code format.

Return value

Returns new object I18Nv2_Language object.

Prev | I18Nv2 | Next
Class Summary I18Nv2_Language | PEAR Manual | I18Nv2_Language::getAllCodes


I18Nv2_Language::getAllCodes

I18Nv2_Language::getAllCodes

I18Nv2_Language::getAllCodes() – Get all codes

Synopsis

require_once 'I18Nv2/Language.php';

array I18Nv2_Language::getAllCodes ( )

Description

Get all language codes as associative array indexed by their two/three letter codes.

Return value

Returns array all language codes.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Language::I18Nv2_Language | PEAR Manual | I18Nv2_Language::getName


I18Nv2_Language::getName

I18Nv2_Language::getName

I18Nv2_Language::getName() – Return name of the language for language code

Synopsis

require_once 'I18Nv2/Language.php';

string I18Nv2_Language::getName ( string $code )

Description

Get the language name for the two/three letter language code.

Parameter

string $code

two/three letter language code

Return value

Returns string name of the language.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Language::getAllCodes | PEAR Manual | I18Nv2_Language::isValidCode


I18Nv2_Language::isValidCode

I18Nv2_Language::isValidCode

I18Nv2_Language::isValidCode() – Check if language code is valid

Synopsis

require_once 'I18Nv2/Language.php';

boolean I18Nv2_Language::isValidCode ( string $code )

Description

Check if the supplied two/three letter language code is valid.

Parameter

string $code

two/three letter language code

Return value

Returns boolean whether the two/three letter language code is valid.

Note

This function can not be called statically.

Prev | I18Nv2 | Next
I18Nv2_Language::getName | PEAR Manual | Translation2


Translation2

Translation2

Table of Contents
  • Class Summary Translation2 -- Translation2 class
  • Introduction -- Usage of Translation2
  • Admin Introduction -- Usage of Translation2_Admin
  • Containers Overview -- Overview of the different Translation2 containers
  • constructor Translation2::Translation2 -- Constructor
  • Translation2::factory -- Return an instanciated Translation2 object
  • Translation2::get -- Get translated string
  • Translation2::getDecorator -- Return an instance of a decorator
  • Translation2::getLang -- get lang info
  • Translation2::getLangs -- get langs
  • Translation2::getPage -- Get an entire group of strings
  • Translation2::getRaw -- Get translated string (as-is)
  • Translation2::getRawPage -- Get the array of strings in a page
  • Translation2::getStringID -- Get the stringID for a given string
  • Translation2::replaceEmptyStringsWithKeys -- Replace the array values with their keys when empty
  • Translation2::setCharset -- Set the charset used to get/store the translations
  • Translation2::setLang -- Set default lang
  • Translation2::setPageID -- Set default page
  • Translation2::setParams -- Set parameters for next string
  • Class Summary Translation2_Admin -- Administration utilities for translation string management
  • Translation2_Admin::addLang -- Prepare the storage container for a new lang.
  • Translation2_Admin::updateLang -- Update the language details.
  • Translation2_Admin::removeLang -- Remove the language from the langsAvail table and drop the strings table.
  • Translation2_Admin::add -- add a new translation
  • Translation2_Admin::remove -- remove a translated string
  • Translation2_Admin::update -- Update an existing translation.
  • Translation2_Admin::removePage -- remove all the translated strings in a page/group
  • Translation2_Admin::cleanCache -- Clear the cache. Use with the CacheLiteFunction decorator only.
  • Translation2_Admin::getPageNames -- Get a list of all the pageIDs in any table.
  • Translation2_Admin::getAdminDecorator -- Return an instance of an admin decorator
  • Class Summary Translation2_Decorator -- Decorates a Translation2 class.
  • Class Summary Translation2_Decorator_CacheLiteFunction -- Decorator to cache fetched data using Cache_Lite_Function class
  • Class Summary Translation2_Decorator_CacheMemory -- Decorator to cache fetched data in memory
  • Class Summary Translation2_Decorator_DefaultText -- Decorator to provide a fallback text for empty strings.
  • Class Summary Translation2_Decorator_ErrorText -- Decorator to provide a fallback error_text message for empty strings.
  • Class Summary Translation2_Decorator_Lang -- Decorator to provide a fallback language for empty strings.
  • Class Summary Translation2_Decorator_Iconv -- Decorator to switch from/to different encodings.
  • Class Summary Translation2_Decorator_SpecialChars -- Decorator to replace special chars with the matching html entities.
  • Class Summary Translation2_Decorator_UTF8 -- Decorator to convert UTF-8 strings to ISO-8859-1
  • Package Translation2 Constants -- Constants defined in and used by Translation2
Prev | Internationalization | Next
I18Nv2_Language::isValidCode | PEAR Manual | Class Summary Translation2


Class Summary Translation2

Class Summary Translation2

Class Summary Translation2 – Translation2 class

Translation2 class

Class for multilingual applications management

Class Trees for Translation2

  • Translation2

Classes that extend Translation2
Class | Summary
Translation2_Admin | Administration utilities for translation string management
Prev | Translation2 | Next
Translation2 | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Usage of Translation2

What is Translation2?

Translation2 is a class for multilingual applications management. It provides an easy way to retrieve all the strings for a multilingual site from a data source (i.e. db). The API is designed to be clean, simple to use, yet powerful and extensible. A Translation2_Admin class is provided to easily manage translations (add/remove a language, add/remove a string).

The following containers (data source drivers) are provided:

  • PEAR::DB

  • PEAR::MDB

  • PEAR::MDB2

  • gettext

  • PEAR::DB_DataObject (experimental, used by PEAR:: HTML_Template_Flexy)

  • XML

Some decorator classes will help in various tasks. They can be layered/stacked one on top of the other, in any number. This approach should suit everyone's needs. Currently, the following decorators are provided:

  • CacheLiteFunction (for fast file-based caching)

  • CacheMemory (for memory-based caching)

  • DefaultText (to replace empty strings with their keys or a default text)

  • ErrorText (to replace empty strings with an "error_text" fallback message)

  • Iconv (to switch from/to different encodings)

  • Lang (resort to fallback languages for empty strings)

  • SpecialChars (replace html entities with their hex codes)

  • UTF-8 (convert UTF-8 strings to ISO-8859-1)

Setup

Translation2 can use different storage containers. Have a look in the /docs/examples dir of the package for some example setups (gettext ini files, SQL DDLs, PHP configuration files, etc).

Usage example

This simple example will show how you can instanciate a Translation2 object and use it to retrieve your translated strings from a db, using the MDB2 driver:

<?php
// set the parameters to connect to your db
$dbinfo = array(
    'hostspec' => 'host',
    'database' => 'dbname',
    'phptype'  => 'mysql',
    'username' => 'user',
    'password' => 'pwd'
);

define('TABLE_PREFIX', 'mytable_');

// tell Translation2 about your db-tables structure,
// if it's different from the default one.
// NB: the default db structure is:
//
// Table "langs" (available languages and meta info)
// +----+------+------+----------+------------+
// | ID | name | meta | encoding | error_text |
// +----+------+------+----------+------------+
//
// Table "strings" (translations)
// +----+---------+----+----+----+-----+
// | ID | page_id | en | de | it | ... |
// +----+---------+----+----+----+-----+
// You can have one table per translation, instead
// of one table for all the languages
//
$params = array(
    'langs_avail_table' => TABLE_PREFIX.'langs_avail',
    'lang_id_col'     => 'ID',
    'lang_name_col'   => 'name',
    'lang_meta_col'   => 'meta',
    'lang_errmsg_col' => 'error_text',
    'strings_tables'  => array(
                            'en' => TABLE_PREFIX.'i18n',
                            'it' => TABLE_PREFIX.'i18n',
                            'de' => TABLE_PREFIX.'i18n'
                         ),
    'string_id_col'      => 'ID',
    'string_page_id_col' => 'pageID',
    'string_text_col'    => '%s'  //'%s' will be replaced by the lang code
);

$driver = 'MDB2';

require_once 'Translation2.php';
$tr =& Translation2::factory($driver, $dbinfo, $params);

//always check for errors. In this examples, error checking is omitted
//to make the example concise.
if (PEAR::isError($tr)) {
    //deal with it
}

// you can set the charset that the database must use, for instance 'utf8'
$tr->setCharset('iso-8859-1');

// set primary language
$tr->setLang('it');

// set the group of strings you want to fetch from
$tr->setPageID('defaultGroup');

// add a Lang decorator to provide a fallback language
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'en');

// add another Lang decorator to provide another fallback language,
// in case some strings are not translated in Italian or English
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'de');

// fetch the string with the 'test' stringID
echo $tr->get('test');

// fetch a string not translated into Italian (test fallback language)
echo $tr->get('only_english');

// fetch the whole group of strings, without resorting to the fallback lang
// and without any "decoration"
$rawPage = $tr->getRawPage();
print_r($rawPage);

// fetch the whole group of strings, but applying the decorators
$page = $tr->getPage();
print_r($page);

// you can force the lang and the group of the string you're requesting
echo $tr->get('month_01', 'calendar', 'it');

// the same is true for getRawPage() and getPage()
$page = $tr->getPage('calendar', 'de');
print_r($page);
?>

As you can see, the main methods are get(), getPage() and getRawPage(). The full syntax is

<?php
get($stringID, $pageID, $langID);
?>

but if you set the pageID and the langID beforehand, you won't need to specify them at each get() invocation.

NB: you have to check for errors at least on the first invocation of one of these methods, since the db connection is only estabilished at this point, so the chances of failures are higher here.

Extracting language info

Now let's see how we can extract some meta info from the db:

<?php
$tr->getLang();     // no langID => get current lang
$tr->getLang('it'); // same as above, if the current lang is Italian

// the first parameter is the lang code,
// with the second parameter you can filter the info you need
$tr->getLang('it', 'error_text');
$tr->getLang('en', 'name');
$tr->getLang('de', 'meta');
$tr->getLang('de', 'encoding');
?>

Using decorators

Translation2 uses decorators to filter/change the retrieved strings. You can have a chain of decorators (filters), and you can also add yours.

<?php
$tr =& Translation2::factory($driver, $dbinfo, $params);
$tr->setLang('en');
$tr->setPageID('calendar');

// add a memory-based cache decorator, to do some basic prefetching and
// reduce the load on the db
$tr = & $tr->getDecorator('CacheMemory');

// add a file-based cache decorator, to cache the query results through pages
$tr =& $tr->getDecorator('CacheLiteFunction');
$tr->setOption('cacheDir', 'cache/');
$tr->setOption('lifeTime', 3600*24);

// add a fallback lang decorator
$tr = & $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'it');

// add a special chars decorator to replace special characters with the html entity
$tr = & $tr->getDecorator('SpecialChars');
// control the charset to use
$tr->setOption('charset', 'ISO-8859-2');

// add a UTF-8 decorator to automatically decode UTF-8 strings
$tr = & $tr->getDecorator('UTF8');

// add a default text decorator to deal with empty strings
$tr = & $tr->getDecorator('DefaultText');
// replace the empty string with its stringID
echo $tr->get('emptyString');
// use a custom fallback text
echo $tr->get('emptyString', 'stringGroup', 'en', 'show this default text');
?>

Getting the stringID from a string

The getStringID() method is the reverse of get(). If you want to translate a string to another language, but you don't know the associated stringID, you can retrieve it with this method:

<?php
$tr->setLang('it');

// translate the Italian string "gennaio" into the English "january"
$stringID = $tr->getStringID('gennaio', 'calendar');
echo $translatedString = $tr->get($stringID, 'calendar', 'en');
?>

Parameter substitution

Translation2 can handle parametric strings, and replace them with parameters passed at runtime (they can be numeric or associative arrays).

<?php
// "hello_user" = "hello &&user&&, today is &&weekday&&, &&day&&th &&month&& &&year&&"

$tr->setParams(array(
    0         => '',
    'user'    => 'Joe',
    'day'     => '15',
    'month'   => $tr->get('month_01', 'calendar', 'en'),
    'year'    => '2004',
    'weekday' => $tr->get('day_5', 'calendar', 'en')
));

echo $tr->get('hello_user');
// the above line will print "hello Joe, today is Friday, 15th January 2004"
?>

Getting the translations from multiple "pages"

If your site structure is organized in sections, like a header, a body and a footer, you may use those units as "pages" (or groups of translations), and then fetch them one by one:

<?php
$header_trans = $tr->getPage('header');
$body_trans   = $tr->getPage('body');
$footer_trans = $tr->getPage('footer');
?>

If you want them all in a single result, just merge them into a single array:

<?php
$translations = array_merge(
    $tr->getPage('header'),
    $tr->getPage('body'),
    $tr->getPage('footer')
);
?>
Prev | Translation2 | Next
Class Summary Translation2 | PEAR Manual | Admin Introduction


Admin Introduction

Admin Introduction

Admin Introduction – Usage of Translation2_Admin

What is Translation2_Admin?

Translation2_Admin is a class meant to help with translation management (add/remove a language, add/remove a string).

Setup

Translation2 can use different storage containers. Have a look in the /docs/examples dir of the package for some example setups (gettext ini files, SQL DDLs, PHP configuration files, etc).

Adding a new language

This simple example will show how you can add a new language [addLang()], using the MDB2 driver:

<?php
// set the parameters to connect to your db
$dbinfo = array(
    'hostspec' => 'host',
    'database' => 'dbname',
    'phptype'  => 'mysql',
    'username' => 'user',
    'password' => 'pwd'
);

// tell Translation2 about your db-tables structure,
// if it's different from the default one.
$params = array(
    'langs_avail_table' => 'langs_avail',
    'lang_id_col'       => 'id',
    'lang_name_col'     => 'name',
    'lang_meta_col'     => 'meta',
    'lang_errmsg_col'   => 'error_text',
    'lang_encoding_col' => 'encoding',
    'strings_tables'    => array(
                            'it' => 'i18n',
                            'de' => 'i18n'
                         ),
    //OR, if you use only one table,
    //'strings_default_table' => 'i18n',
    'string_id_col'      => 'id',
    'string_page_id_col' => 'page_id',
    'string_page_id_col_length' => 50, // db field size
    'string_text_col'    => '%s'  //'%s' will be replaced by the lang code
);

$driver = 'MDB2';

require_once 'Translation2/Admin.php';
$tr =& Translation2_Admin::factory($driver, $dbinfo, $params);

// set some info about the new lang
$newLang = array(
    'lang_id'    => 'en',
    'table_name' => 'i18n',
    'name'       => 'english',
    'meta'       => 'some meta info',
    'error_text' => 'not available',
    'encoding'   => 'iso-8859-1',
);

$tr->addLang($newLang);
?>

That's it. If you specified a new table, it will be created, if you used the same table name as the one of your other translations, it will be ALTERed to host the new language too.

Updating a language

This simple example will show how you can update an existing language [updateLang()]:

<?php
// set some info about the new lang
$langData = array(
    'lang_id'    => 'en',
    'table_name' => 'i18n',
    'name'       => 'English',
    'meta'       => 'some updated meta info',
    'error_text' => 'this text is not available in English',
    'encoding'   => 'iso-8859-15',
);

$tr->updateLang($langData);
?>

Removing an existing language

If you want to remove all the translated strings and the info for a certain language, all you have to do is

<?php
$tr->removeLang('fr');
?>

removeLang() can accept a 2nd parameter ($force ): if you want to remove the whole strings table (regardless it being used for other languages as well), you can do it this way:

<?php
$tr->removeLang('fr', true);
?>

Be warned it won't do any check, so you're responsible for what you do ;-)

Adding new translations

Now let's see how we can add() a new translation for a new or an existing string.

<?php
$stringArray = array(
    'en' => 'sample',
    'it' => 'esempio',
);

// add the English and Italian translations associated to
// the 'smallTest' stringID and to the 'testGroup' pageID

$tr->add('smallTest', 'testGroup', $stringArray);
?>

Remove a translation

You can remove() the translations for a certain stringID:

<?php
$tr->remove('smallTest', 'testGroup');
?>
Prev | Translation2 | Next
Introduction | PEAR Manual | Containers Overview


Containers Overview

Containers Overview

Containers Overview – Overview of the different Translation2 containers

Summary

Translation2 supports different storage drivers; this page is meant to highlight the differences among them.

PEAR::DB, PEAR::MDB, PEAR::MDB2

Translation2 can work with any of these database abstraction layers, just pass the appropriate connection options. These three containers are absolutely identical in what they do and in how they work (wrt Translation2, of course).

<?php
// connection options
$dbinfo = array(
    'hostspec' => 'host',
    'database' => 'dbname',
    'phptype'  => 'mysql',
    'username' => 'user',
    'password' => 'pwd'
);
//select the preferred driver
$driver = 'MDB2'; //switch to 'DB' or 'MDB' as needed

require_once 'Translation2.php';
$tr =& Translation2::factory($driver, $dbinfo, $params);
?>

If your table definition is different from the default one, you need to specify it in the $params array.

DB_DataObject

The dataobjectsimple container is the natural choice for those using DB_DataObject, as it is tightly tied to the DAO. This storage driver can use all databases supported by the PEAR::DB abstraction layer to fetch data.

For this container, you can't specify a custom table definition, since this feature is not supported yet. You must create a table with the following structure:

// meta data etc. not supported
table: translations
id // not null primary key autoincrement..
string_id // translation id
page // indexed varchar eg. (mytemplate.html)
lang // index varchar (eg. en|fr|.....)
translation // the translated value in language lang.

Here's the MySQL query that can be used to create the table:

create table translations (
id int(11) auto_increment not null primary key,
string_id int(11), page varchar(128),
lang varchar(10), translation text
);
alter table translations add index page (page);
alter table translations add index lang (lang);
alter table translations add index string_id (string_id);

then just run the dataobjects createtables script.

Gettext

This is a wrapper around the gettext base functions, and thanks to File_Gettext you can retrieve an entire domain or write to an existing/new domain without calling the command line compiler utility.

The gettext container requires PEAR::File_Gettext and PEAR::I18Nv2 0.9.1 or newer, make sure you have them installed.

The construction parameters are a bit different from the db ones. To make things as simple as possible, the domain definitions and the available language list are read from two INI files.

langs.ini example:

; If one does not specify the source encoding, ISO-8859-1 is assumed
; Beware that gettext can choke on bad encodings!

[en]
name = English
encoding = iso-8859-1

[de]
name = Deutsch
encoding = iso-8859-1

[it]
name = italiano
encoding = iso-8859-1

domains.ini example:

messages = /path/to/locale
2nddomain = /path/to/locale
3rddomain = /path/to/locale

Sample code to use Translation2 with the gettext container:

<?php
require_once 'Translation2.php';

$params = array(
    'prefetch'          => false,
    'langs_avail_file'  => 'path/to/langs.ini',
    'domains_path_file' => 'path/to/domains.ini',
    'default_domain'    => 'messages',
    //'file_type'       => 'po',
);

// Better set prefetch to FALSE for the gettext container, so we don't need
// to read in the whole MO file with File_Gettext on every request.
$tr =& Translation2::factory('gettext', $params);

$tr->setLang('en');

// Note that, if there is no translation available for a string, the gettext
// container will return the string ID!  This behaviour emulates native gettext.
echo $tr->get('mystring');

print_r($tr->getPage('3rddomain'));
?>

XML

The XML container requires PEAR::XML_Serializer 0.13.0 or newer, make sure you have it installed.

<?php
$driver = 'XML';
$options = array(
    'filename'         => 'i18n.xml',
    'save_on_shutdown' => true, //set to FALSE to save in real time
);
require_once 'Translation2.php';
$tr =& Translation2::factory($driver, $options);
?>
Prev | Translation2 | Next
Admin Introduction | PEAR Manual | constructor Translation2::Translation2


constructor Translation2::Translation2

constructor Translation2::Translation2

constructor Translation2::Translation2() – Constructor

Synopsis

require_once 'Translation2.php';

void constructor Translation2::Translation2 ( string $storageDriver , mixed $options = '' , array $params = array() )

Description

This constructor is deprecated in favour of the factory() method.

Note

This function can not be called statically.

Prev | Translation2 | Next
Containers Overview | PEAR Manual | Translation2::factory


Translation2::factory

Translation2::factory

Translation2::factory() – Return an instanciated Translation2 object

Synopsis

require_once 'Translation2.php';

void Translation2::factory ( string $storageDriver , mixed $options = '' , array $params = array() )

Description

This is the Translation2 factory

Parameter

string $storageDriver

Type of the storage driver ('db', 'mdb', 'mdb2', 'gettext', 'dataobjectsimple')

mixed $options

Additional options for the storage driver (example: if you are using DB as the storage driver, you have to pass the dsn string here)

array $params

Array of parameters for the adapter class (i.e. you can set here the mappings between your table/field names and the ones used by this class)

Note

This function can not be called statically.

Prev | Translation2 | Next
constructor Translation2::Translation2 | PEAR Manual | Translation2::get


Translation2::get

Translation2::get

Translation2::get() – Get translated string

Synopsis

require_once 'Translation2.php';

string Translation2::get ( string $stringID , string $pageID = TRANSLATION2_DEFAULT_PAGEID , string $langID = null , string $defaultText = '' )

Description

Fetch the string from the container. If the string is empty and the DefaultText decorator is used, then return the $defaultText.

Parameter

string $stringID

string $pageID

string $langID

string $defaultText

Text to display when the string is empty. NB: This parameter is only used in the DefaultText decorator

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::factory | PEAR Manual | Translation2::getDecorator


Translation2::getDecorator

Translation2::getDecorator

Translation2::getDecorator() – Return an instance of a decorator

Synopsis

require_once 'Translation2.php';

object Decorator& Translation2::getDecorator ( string $decorator , object [optional] 1 )

Description

This method is used to get a decorator instance. A decorator can be seen as a filter, i.e. something that can change or handle the values of the objects/vars that pass through.

Parameter

string $decorator

Name of the decorator

object $obj [optional]

Object to decorate (the default object being $this)

Return value

returns object Reference of a Translation2_Decorator subclass

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::get | PEAR Manual | Translation2::getLang


Translation2::getLang

Translation2::getLang

Translation2::getLang() – get lang info

Synopsis

require_once 'Translation2.php';

mixed Translation2::getLang ( string $langID = null , string $format = 'name' )

Description

Get some extra information about the language (its full name, the localized error text, ...)

Parameter

string $langID

string $format

['name', 'meta', 'error_text', 'array']

Return value

returns [string | array], depending on $format

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::getDecorator | PEAR Manual | Translation2::getLangs


Translation2::getLangs

Translation2::getLangs

Translation2::getLangs() – get langs

Synopsis

require_once 'Translation2.php';

array Translation2::getLangs ( string $format = 'name' )

Description

Get some extra information about the languages (their full names, the localized error text, their codes...)

Parameter

string $format

['ids', 'names', 'array']

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::getLang | PEAR Manual | Translation2::getPage


Translation2::getPage

Translation2::getPage

Translation2::getPage() – Get an entire group of strings

Synopsis

require_once 'Translation2.php';

array Translation2::getPage ( string $pageID = TRANSLATION2_DEFAULT_PAGEID , string $langID = null )

Description

Same as getRawPage(), but resort to fallback language and replace parameters when needed.

NB: in Translation2 lingo, a "page" is just a logical "group of strings", it doesn't have to be a "phisical" (HTML or whatever) page.

Parameter

string $pageID

string $langID

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::getLangs | PEAR Manual | Translation2::getRaw


Translation2::getRaw

Translation2::getRaw

Translation2::getRaw() – Get translated string (as-is)

Synopsis

require_once 'Translation2.php';

string Translation2::getRaw ( string $stringID , string $pageID = TRANSLATION2_DEFAULT_PAGEID , string $langID = null , string $defaultText = '' )

Description

Fetch the string from the container. If the string is empty return $defaultText.

Parameter

string $stringID

string $pageID

string $langID

string $defaultText

Text to display when the string is empty

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::getPage | PEAR Manual | Translation2::getRawPage


Translation2::getRawPage

Translation2::getRawPage

Translation2::getRawPage() – Get the array of strings in a page

Synopsis

require_once 'Translation2.php';

array Translation2::getRawPage ( string $pageID = TRANSLATION2_DEFAULT_PAGEID , string $langID = null )

Description

Fetch the page (aka 'group of strings') from the container, without applying any formatting and without replacing the parameters.

Parameter

string $pageID

string $langID

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::getRaw | PEAR Manual | Translation2::getStringID


Translation2::getStringID

Translation2::getStringID

Translation2::getStringID() – Get the stringID for a given string

Synopsis

require_once 'Translation2.php';

string Translation2::getStringID ( string $string , mixed $pageID = TRANSLATION2_DEFAULT_PAGEID )

Description

Get the stringID of the string passed as parameter

Parameter

string $string

This is NOT the stringID, this is a real string. The method will return its matching stringID.

mixed $pageID

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::getRawPage | PEAR Manual | Translation2::replaceEmptyStringsWithKeys


Translation2::replaceEmptyStringsWithKeys

Translation2::replaceEmptyStringsWithKeys

Translation2::replaceEmptyStringsWithKeys() – Replace the array values with their keys when empty

Synopsis

require_once 'Translation2.php';

array Translation2::replaceEmptyStringsWithKeys ( array $strings )

Description

Replace the array values with their keys when empty, just like gettext would do.

Parameter

array $strings array of strings (e.g. as returned by getPage())

Prev | Translation2 | Next
Translation2::getStringID | PEAR Manual | Translation2::setCharset


Translation2::setCharset

Translation2::setCharset

Translation2::setCharset() – Set the charset used to get/store the translations

Synopsis

require_once 'Translation2.php';

mixed Translation2::setCharset ( string $charset )

Description

Set the charset that shall be used when retrieving strings. Currently only used by the MDB2 container.

Parameter

string $charset charset name to pass to the container (for instance, 'utf8')

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::replaceEmptyStringsWithKeys | PEAR Manual | Translation2::setLang


Translation2::setLang

Translation2::setLang

Translation2::setLang() – Set default lang

Synopsis

require_once 'Translation2.php';

void Translation2::setLang ( string $langID )

Description

Set the language that shall be used when retrieving strings.

Parameter

string $langID language code (for instance, 'en' or 'it')

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::setCharset | PEAR Manual | Translation2::setPageID


Translation2::setPageID

Translation2::setPageID

Translation2::setPageID() – Set default page

Synopsis

require_once 'Translation2.php';

void Translation2::setPageID ( mixed $pageID = null , string $langID )

Description

Set the page (aka 'group of strings') that shall be used when retrieving strings. If you set it, you don't have to state it in each get() call.

Parameter

string $pageID

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::setLang | PEAR Manual | Translation2::setParams


Translation2::setParams

Translation2::setParams

Translation2::setParams() – Set parameters for next string

Synopsis

require_once 'Translation2.php';

void Translation2::setParams ( params $params = null )

Description

Set the replacement for the parameters in the string(s). Parameter delimiters are customizable.

Parameter

array $params

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2::setPageID | PEAR Manual | Class Summary Translation2_Admin


Class Summary Translation2_Admin

Class Summary Translation2_Admin

Class Summary Translation2_Admin – Administration utilities for translation string management

Administration utilities for translation string management

This package is not documented yet.

Class Trees for Translation2_Admin

  • Translation2

    • Translation2_Admin

Translation2_Admin Inherited Methods

Inherited from Translation2
Method Name | Summary
Constructor Translation2::Translation2() | Constructor (deprecated in favour of factory())
Factory Translation2::factory() | Return a Translation2 instanciated object
Translation2::get() | Get translated string
Translation2::getDecorator() | Return an instance of a decorator
Translation2::getLang() | get language info
Translation2::getLangs() | get available languages
Translation2::getPage() | Same as getRawPage(), but resort to fallback language and replace parameters when needed
Translation2::getRaw() | Get translated string (as-is)
Translation2::getRawPage() | Get the array of strings in a page
Translation2::setCharset() | Set the correct charset in the database
Translation2::setLang() | Set default lang
Translation2::setPageID() | Set default page
Translation2::setParams() | Set parameters for next string
Translation2::getStringID() | Get the stringID for a given string
Prev | Translation2 | Next
Translation2::setParams | PEAR Manual | Translation2_Admin::addLang


Translation2_Admin::addLang

Translation2_Admin::addLang

Translation2_Admin::addLang() – Prepare the storage container for a new lang.

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::addLang ( array $langData , array $options )

Description

If the langsAvail table doesn't exist yet, it is created.

Parameter

array $langData

array(
'lang_id' => 'en',
'table_name' => 'i18n',
'name' => 'english',
'meta' => 'some meta info',
'error_text' => 'not available',
'encoding' => 'iso-8859-1',
);
array $options

array(
'charset' => 'latin1',
'collation' => 'latin1_bin',
);

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Class Summary Translation2_Admin | PEAR Manual | Translation2_Admin::updateLang


Translation2_Admin::updateLang

Translation2_Admin::updateLang

Translation2_Admin::updateLang() – Update the language details.

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::updateLang ( array $langData )

Description

Update the language details.

Parameter

array $langData

array(
'lang_id' => 'en',
'table_name' => 'i18n',
'name' => 'english',
'meta' => 'some new meta info',
'error_text' => 'text not available',
'encoding' => 'iso-8859-15',
);

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::addLang | PEAR Manual | Translation2_Admin::removeLang


Translation2_Admin::removeLang

Translation2_Admin::removeLang

Translation2_Admin::removeLang() – Remove the language from the langsAvail table and drop the strings table.

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::removeLang ( string $langID = null , boolean $force = false )

Description

If the strings table holds other languages and $force ==FALSE, then only the lang column is dropped. If $force ==TRUE, the whole table is dropped without any check

Parameter

string $langID

Code of the language to remove

boolean $force

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::updateLang | PEAR Manual | Translation2_Admin::add


Translation2_Admin::add

Translation2_Admin::add

Translation2_Admin::add() – add a new translation

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::add ( string $stringID , string $pageID = null , array $stringArray )

Description

Add a new translated string (or a set of translated strings) for a given stringID . For instance, to add the English, Spanish and Italian translations for the stringID 'example', use the following code:

<?php
$stringArray = array(

    'en' => 'example',

    'es' => 'ejemplo',

    'it' => 'esempio',

);

$tr->add('example', 'mypage', $stringArray);
?>

Parameter

string $stringID

identificator for the string

string $pageID

destination pageID, i.e. the group of strings where this string belongs to.

array $stringArray

Associative array with string translations.

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::removeLang | PEAR Manual | Translation2_Admin::remove


Translation2_Admin::remove

Translation2_Admin::remove

Translation2_Admin::remove() – remove a translated string

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::remove ( string $stringID , string $pageID = null )

Description

Remove all the translations for the given stringID + pageID pair.

Parameter

string $stringID

string $pageID

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::add | PEAR Manual | Translation2_Admin::update


Translation2_Admin::update

Translation2_Admin::update

Translation2_Admin::update() – Update an existing translation.

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::update ( string $stringID , string $pageID , array $stringArray )

Description

Update the language details.

Parameter

string $stringID

ID of the string to translate

string $pageID

ID of the page (or group) the string to translate belongs to

array $stringArray

Associative array with string translations:

array(
'en' => 'sample',
'it' => 'esempio',
);

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::remove | PEAR Manual | Translation2_Admin::removePage


Translation2_Admin::removePage

Translation2_Admin::removePage

Translation2_Admin::removePage() – remove all the translated strings in a page/group

Synopsis

require_once 'Admin.php';

mixed Translation2_Admin::removePage ( string $pageID = null )

Description

Remove all the translations for the given pageID .

Parameter

string $pageID

page/group ID

Return value

returns true on success, PEAR_Error on failure

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::update | PEAR Manual | Translation2_Admin::cleanCache


Translation2_Admin::cleanCache

Translation2_Admin::cleanCache

Translation2_Admin::cleanCache() – Clear the cache. Use with the CacheLiteFunction decorator only.

Synopsis

require_once 'Admin.php';

void Translation2_Admin::cleanCache ( )

Description

If you use the CacheLiteFunction decorator, you may want to invalidate the cache after a change in the data base.

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::removePage | PEAR Manual | Translation2_Admin::getPageNames


Translation2_Admin::getPageNames

Translation2_Admin::getPageNames

Translation2_Admin::getPageNames() – Get a list of all the pageIDs in any table.

Synopsis

require_once 'Admin.php';

array Translation2_Admin::getPageNames ( )

Description

Get a list of all the pageIDs in any table.

Return value

returns array of pageIDs

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::cleanCache | PEAR Manual | Translation2_Admin::getAdminDecorator


Translation2_Admin::getAdminDecorator

Translation2_Admin::getAdminDecorator

Translation2_Admin::getAdminDecorator() – Return an instance of an admin decorator

Synopsis

require_once 'Translation2/Admin.php';

object Decorator& Translation2_Admin::getAdminDecorator ( string $decorator , object [optional] 1 )

Description

This method is used to get a decorator instance. A decorator can be seen as a filter, i.e. something that can change or handle the values of the objects/vars that pass through.

Parameter

string $decorator

Name of the decorator

object $obj [optional]

Object to decorate (the default object being $this)

Return value

returns object Reference of a Translation2_Admin_Decorator subclass

Note

This function can not be called statically.

Prev | Translation2 | Next
Translation2_Admin::getPageNames | PEAR Manual | Class Summary Translation2_Decorator


Class Summary Translation2_Decorator

Class Summary Translation2_Decorator

Class Summary Translation2_Decorator – Decorates a Translation2 class.

Decorates a Translation2 class.

Create a subclass of this class for your own "decoration". The base class acts as a proxy to these methods:

  • get()

  • getDecorator()

  • getLang()

  • getLangs()

  • getPage()

  • getRaw()

  • getRawPage()

  • getStringID()

  • replaceEmptyStringsWithKeys()

  • setCharset()

  • setContainerOptions() [protected]

  • setLang()

  • setOption()

  • setOptions() [protected]

  • setPageID()

  • setParams()

  • translate()

If you want to "decorate" any of these methods, you have to override them in your custom Decorator.

Class Trees for Translation2_Decorator

  • Translation2_Decorator

Classes that extend Translation2_Decorator
Class | Summary
Translation2_Decorator_CacheLiteFunction | Decorator to cache fetched data using Cache_Lite_Function class
Translation2_Decorator_CacheMemory | Decorator to cache fetched data in memory
Translation2_Decorator_DefaultText | Decorator to provide a fallback text for empty strings.
Translation2_Decorator_ErrorText | Decorator to provide an error_text message for empty strings.
Translation2_Decorator_Iconv | Decorator to switch from/to different encodings.
Translation2_Decorator_Lang | Decorator to provide a fallback language for empty strings.
Translation2_Decorator_SpecialChars | Decorator to replace special chars with the matching html entities.
Translation2_Decorator_UTF8 | Decorator to convert UTF-8 strings to ISO-8859-1
Prev | Translation2 | Next
Translation2_Admin::getAdminDecorator | PEAR Manual | Class Summary Translation2_Decorator_CacheLiteFunction


Class Summary Translation2_Decorator_CacheLiteFunction

Class Summary Translation2_Decorator_CacheLiteFunction

Class Summary Translation2_Decorator_CacheLiteFunction – Decorator to cache fetched data using Cache_Lite_Function class

Cache_Lite_Function Decorator Example

This decorator provides a very efficient cache layer. It requires PEAR::Cache_Lite. It supports all the main options supported by Cache_Lite:

  • lifeTime [integer]

  • cacheDir [string]

  • fileLocking [boolean]

  • caching [boolean]

If you need to pass an option directly to the Cache_Lite object, you can use setCacheOption().

<?php
$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('CacheLiteFunction');
$tr->setOption('cacheDir', '/var/tmp/');
$tr->setOption('lifeTime', 3600*24*7); //one week

//change a custom Cache_Lite option
$tr->setCacheOption($name, $value);
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator | PEAR Manual | Class Summary Translation2_Decorator_CacheMemory


Class Summary Translation2_Decorator_CacheMemory

Class Summary Translation2_Decorator_CacheMemory

Class Summary Translation2_Decorator_CacheMemory – Decorator to cache fetched data in memory

CacheMemory Decorator Example

This decorator provides a memory cache layer. It does NOT persist through requests, only in the current execution of the script. You can turn off prefetch if you want small network load (but it will increase the number of queries to the database)

<?php
$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('CacheMemory');
$tr->setOption('prefetch', true); //default value is true
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_CacheLiteFunction | PEAR Manual | Class Summary Translation2_Decorator_DefaultText


Class Summary Translation2_Decorator_DefaultText

Class Summary Translation2_Decorator_DefaultText

Class Summary Translation2_Decorator_DefaultText – Decorator to provide a fallback text for empty strings.

DefaultText Decorator Example

When the fetched string is empty, it replaces it with the 4th parameter of the get() method, i.e. $defaultText . If the defaultText parameter is empty too, then return "$emptyPostfix.$outputString.$emptyPrefix", the three variables being class properties you can set to a custom string.

When getPage() is called, all the empty strings in the page are replaced by their stringID value.

<?php
$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('DefaultText');

// %stringID% will be replaced with the stringID
// %pageID_url% will be replaced with the pageID
// %stringID_url% will replaced with a urlencoded stringID
// %url% will be replaced with the targeted url
$tr->outputString = '%stringID%<a href="%url%">(T)</a>'; //default: '%stringID%'
$tr->url = '#';           //same as default
$tr->emptyPrefix  = '[';  //default: empty string
$tr->emptyPostfix = ']';  //default: empty string
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_CacheMemory | PEAR Manual | Class Summary Translation2_Decorator_ErrorText


Class Summary Translation2_Decorator_ErrorText

Class Summary Translation2_Decorator_ErrorText

Class Summary Translation2_Decorator_ErrorText – Decorator to provide a fallback error_text message for empty strings.

ErrorText Decorator Example

When the fetched string is empty, it replaces it with the contents of the "error_text" column of the langs_avail table

<?php
$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('ErrorText');
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_DefaultText | PEAR Manual | Class Summary Translation2_Decorator_Lang


Class Summary Translation2_Decorator_Lang

Class Summary Translation2_Decorator_Lang

Class Summary Translation2_Decorator_Lang – Decorator to provide a fallback language for empty strings.

Lang Decorator Example

This decorator is very useful when you want to provide a fallback language for empty strings. It is stackable, so you can have more than one default language. Use setOption() with the fallbackLang parameter to specify the fallback language of the current decorator.

<?php
$tr = new Translation2($driver, $dbinfo, $params);

//set English as the main language
$tr->setLang('en');

//set Italian as the first fallback language
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'it');

//set Spanish as the second fallback language
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'es');
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_ErrorText | PEAR Manual | Class Summary Translation2_Decorator_Iconv


Class Summary Translation2_Decorator_Iconv

Class Summary Translation2_Decorator_Iconv

Class Summary Translation2_Decorator_Iconv – Decorator to switch from/to different encodings.

Iconv Decorator Example

Use setOption() with the encoding parameter to specify the target encoding of the current decorator.

<?php
$tr = new Translation2($driver, $dbinfo, $params);

//set Hungarian as the main language
$tr->setLang('hu');

//encode all the strings using the ISO-8859-2 charset
$tr =& $tr->getDecorator('Iconv');
$tr->setOption('encoding', 'ISO-8859-2');
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_Lang | PEAR Manual | Class Summary Translation2_Decorator_SpecialChars


Class Summary Translation2_Decorator_SpecialChars

Class Summary Translation2_Decorator_SpecialChars

Class Summary Translation2_Decorator_SpecialChars – Decorator to replace special chars with the matching html entities.

SpecialChars Decorator Example

This decorator replaces special chars with the matching html entities. Use setOption() with the charset parameter to specify the target charset of the current decorator (the default is 'ISO-8859-1'):

<?php
$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('SpecialChars');
$tr->setOption('charset', 'UTF-8');
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_Iconv | PEAR Manual | Class Summary Translation2_Decorator_UTF8


Class Summary Translation2_Decorator_UTF8

Class Summary Translation2_Decorator_UTF8

Class Summary Translation2_Decorator_UTF8 – Decorator to convert UTF-8 strings to ISO-8859-1

UTF-8 Decorator Example

This decorator calls utf8_decode() on each string

<?php
$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('UTF8');
?>
Prev | Translation2 | Next
Class Summary Translation2_Decorator_SpecialChars | PEAR Manual | Package Translation2 Constants


Package Translation2 Constants

Package Translation2 Constants

Package Translation2 Constants – Constants defined in and used by Translation2

All Constants

Constants defined in DecoratorCacheMemory.php

Constants defined in DecoratorCacheMemory.php
Name | Value | Line Number
TRANSLATION2_EMPTY_PAGEID_KEY | 'array_key_4_empty_pageID' | 34
TRANSLATION2_NULL_PAGEID_KEY | 'array_key_4_null_pageID' | 40

Constants defined in Translation2.php

Constants defined in Translation2.php
Name | Value | Line Number
TRANSLATION2_DEFAULT_PAGEID | 'translation2_default_pageID' | 38
TRANSLATION2_ERROR | -1 | 43
TRANSLATION2_ERROR_METHOD_NOT_SUPPORTED | -2 | 44
TRANSLATION2_ERROR_CANNOT_CONNECT | -3 | 45
TRANSLATION2_ERROR_CANNOT_FIND_FILE | -4 | 46
TRANSLATION2_ERROR_DOMAIN_NOT_SET | -5 | 47
TRANSLATION2_ERROR_INVALID_PATH | -6 | 48
TRANSLATION2_ERROR_CANNOT_CREATE_DIR | -7 | 49
TRANSLATION2_ERROR_CANNOT_WRITE_FILE | -8 | 50
TRANSLATION2_ERROR_UNKNOWN_LANG | -9 | 51
Prev | Translation2 | Next
Class Summary Translation2_Decorator_UTF8 | PEAR Manual | Logging


Logging

Logging

Provides Packages for logging purposes

Table of Contents
  • Log
Prev | PEAR Packages | Next
Package Translation2 Constants | PEAR Manual | Log


Log

Log

Implements both an abstraction for various logging mechanisms and the Subject end of a Subject-Observer pattern.

The full online documentation is available at the maintainer's website: http://www.indelible.org/php/Log/.

Prev | Logging | Next
Logging | PEAR Manual | Mail


Mail

Mail

Provides Packages for creating and working with electronic mails

Table of Contents
  • Mail
  • Mail_IMAP
  • Mail_Mbox
  • Mail_Mime
  • Mail_Queue
Prev | PEAR Packages | Next
Log | PEAR Manual | Mail


Mail

Mail

An interface for sending EMails

Table of Contents
  • Introduction -- How to send a mail and the mailer backends
  • Mail::factory() -- creates a mailer instance
  • Mail::send() -- sends a mail
  • RFC822 - Introduction -- email address validation
  • Mail_RFC822::parseAddressList() -- extract the parts of a list of email addresses
Prev | Mail | Next
Mail | PEAR Manual | Introduction


Introduction

Introduction

Introduction – How to send a mail and the mailer backends

How To send a mail

Mail supports different types of backends to send email. So two steps are necessary to send an email.

  • Step 1

    Create a new instance of a specific Mail-Backend with the factory() method.

  • Step 2

    Send the mail using the send() method.

The mailer backends

Mail supports three types of backends:

  • mail

    Sends a mail using PHP's built-in mail() function.

  • sendmail

    Sends a mail using a sendmail program.

  • smtp

    Sends a mail directly connecting to a smtp server.

Prev | Mail | Next
Mail | PEAR Manual | Mail::factory()


Mail::factory()

Mail::factory()

Mail::factory() – creates a mailer instance

Synopsis

require_once 'Mail.php';

object &factory ( string $backend , array $params = array() )

Description

Creates a instance of a backend-specific mailer class.

Parameter

  • string $backend - the name of the backend "mail" ,"smtp" , "sendmail"

  • array $params - a array of backend specific parameters.

    List of parameter for the backends

    • mail

      • If safe mode is disabled, $params will be passed as the fifth argument to the PHP mail() function. If $params is an array, its elements will be joined as a space-delimited string.

    • sendmail

      • $params["sendmail_path"] - The location of the sendmail program on the filesystem. Default is /usr/bin/sendmail .

      • $params["sendmail_args"] - Additional parameters to pass to the sendmail. Default is -i .

    • smtp

      • $params["host"] - The server to connect. Default is localhost .

      • $params["port"] - The port to connect. Default is 25 .

      • $params["auth"] - Whether or not to use SMTP authentication. Default is FALSE.

      • $params["username"] - The username to use for SMTP authentication.

      • $params["password"] - The password to use for SMTP authentication.

      • $params["localhost"] - The value to give when sending EHLO or HELO. Default is localhost

      • $params["timeout"] - The SMTP connection timeout. Default is NULL (no timeout).

      • $params["verp"] - Whether to use VERP or not. Default is FALSE.

      • $params["debug"] - Whether to enable SMTP debug mode or not. Default is FALSE.

      • $params["persist"] - Indicates whether or not the SMTP connection should persist over multiple calls to the send() method.

Return value

object - a specific Mail instance or a PEAR_Error object on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Unable to find class for driver xxx " | Mailer backend class was not found. | Check the $backend parameter, if correct reinstall and/or update your Mail package.

Note

This function should be called statically.

See

"Introduction"

Prev | Mail | Next
Introduction | PEAR Manual | Mail::send()


Mail::send()

Mail::send()

Mail::send() – sends a mail

Synopsis

require_once 'Mail.php';

mixed send ( mixed $recipients , array $headers , string $body )

Description

Sends a mail. The send() method is provided by the object returned from factory()

Parameter

  • mixed $recipients - an array or a string with comma separated recipients.

  • array $headers - an associative array of headers. The header name is used as key and the header value as value. If you want to override the envelope sender of the email, set the Return-Path header and that value will be used instead of the value of the From: header.

  • string $body - the body of the email.

Return value

boolean - TRUE or a PEAR_Error object on failure.

Throws

Possible PEAR_Error values
Mailer driver | Error code | Error message | Reason | Solution
sendmail NULL "No from address given." The $headers array requires at least a from entry. Add a From header:
<?php
$headers['From'] = 'mymail@example.com';
?>
sendmail | NULL | "From address specified with dangerous characters." | The from entry in the $headers array contains one ore more characters which could be non-RFC compliant. | Check the given from address for characters like: spaces or ; or & or ` (backtick).
sendmail | NULL | "sendmail [path to sendmail ] not executable" | The path to sendmail program is not correct. No sendmail executable found there. | Check the $param['sendmail_path'] entry in your Mail::factory() call. If you use another mailer then sendmail, ie. qmail, check installation of the mailer. Normally it should includes a sendmail wrapper.
sendmail | NULL | "sendmail returned error code code " | Sendmail returns a error, which must be handled by use. | See the documention of your mailer program.
smtp | PEAR_MAIL_SMTP_ERROR_CREATE | "Failed to create a Net_SMTP object" | Failure in class creation. | Reinstall/update the Net_SMTP package.
smtp | PEAR_MAIL_SMTP_ERROR_CONNECT | "Failed to connect to host:port " | Connect to SMTP server failed. | Check $param['port'] and $param['host'] entries in your Mail::factory() call.
smtp | PEAR_MAIL_SMTP_ERROR_AUTH | "method authentication failure" | Authentication failed. | Check $param['auth'] , $param['username'] and $param['password'] entries in your Mail::factory() call. Ensure to use the correct authentication method for the SMTP server.
smtp PEAR_MAIL_SMTP_ERROR_FROM "No From: address has been provided" The $headers array requires at least a from entry. Add a From header:
<?php
$headers['From'] = 'mymail@example.com';
?>
smtp | PEAR_MAIL_SMTP_ERROR_SENDER | "Failed to set sender: from " | Setting the sender address failed. | Check the RFC-compliances of the sender address and the server connnectivity.
smtp | PEAR_MAIL_SMTP_ERROR_RECIPIENT | "Failed to add recipient: recipient " | Sending of recipient address failed. | Check the RFC-compliances of the recipient address and the server connnectivity.
smtp | PEAR_MAIL_SMTP_ERROR_DATA | "Failed to send data" | Body of the mail message could not send | Check the RFC-compliances of the message body and the server connnectivity.

Note

This function can not be called statically.

Example

<?php
include('Mail.php');

$recipients = 'joe@example.com';

$headers['From']    = 'richard@example.com';
$headers['To']      = 'joe@example.com';
$headers['Subject'] = 'Test message';

$body = 'Test message';

$params['sendmail_path'] = '/usr/lib/sendmail';

// Create the mail object using the Mail::factory method
$mail_object =& Mail::factory('sendmail', $params);

$mail_object->send($recipients, $headers, $body);
?>

See

Mail::factory()

Prev | Mail | Next
Mail::factory() | PEAR Manual | RFC822 - Introduction


RFC822 - Introduction

RFC822 - Introduction

RFC822 - Introduction – email address validation

Description

This class performs email address checking according to the RFC822 specification.

Note that the class only checks for a proper format of the indicated email address. This means it is not guaranteed that the email address itself exists or is owned by the particular user. You may also want to send the user an email, and force them to respond.

Prev | Mail | Next
Mail::send() | PEAR Manual | Mail_RFC822::parseAddressList()


Mail_RFC822::parseAddressList()

Mail_RFC822::parseAddressList()

Mail_RFC822::parseAddressList() – extract the parts of a list of email addresses

Synopsis

require_once 'Mail/RFC822.php';

array parseAddressList ( string $address = '' , string $defaultDomain = 'localhost' , boolean $nestGroups = null , boolean $validate = null )

Description

Extracts the given addresses into their parts.

Parameter

  • string $address - the address(es) to validate

  • string $defaultDomain - the default domain to use in case of absence in the given email address.

  • boolean $nestGroups - whether to return the structure with groups nested for easier viewing.

  • boolean $validate - whether to validate atoms. Turn this off if you need to run addresses through before encoding the personal names, for instance.

Return value

array - a nested array of anonymous objects.

If $nestGroups set to FALSE, you can jump over the next paragraph.

Every array entry contains an object per group. This object has two attributes:

  • groupname - the name of the group
  • addresses - an array of all addresses of a group

The addresses array consists of an array of anonymous objects for each address. This object comes with the following attributes:

  • personal - the name of the address owner
  • comment - an array, an entry for each comment per address
  • mailbox - the name of the mailbox, the part before the @
  • host - the name of the server, the part after the @

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | every | The given address string is not RFC822 compliant | The error code contains a description of the error.

Note

This function can be called statically.

This class checks the string only. It does not check for the existence of an email address.

Example

Extract some addresses

<?php
$address = 'My group: "Richard" <richard@localhost>;, ted@example.com (A comment)';

$addresses = Mail_RFC822::parseAddressList($address, 'phpguru.org', TRUE);
print_r($addresses);
?>
Prev | Mail | Next
RFC822 - Introduction | PEAR Manual | Mail_IMAP


Mail_IMAP

Mail_IMAP

Mail_IMAP provides a simplified backend for working with the c-client (IMAP) extension. It serves as an OO wrapper for commonly used c-client functions. It provides structure and header parsing as well as body retrieval.

Table of Contents
  • Introduction -- Mail_IMAP provides a simplified backend for working with the c-client (IMAP) extension.
Prev | Mail | Next
Mail_RFC822::parseAddressList() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Mail_IMAP provides a simplified backend for working with the c-client (IMAP) extension.

Mail_IMAP Description

Mail_IMAP provides an object-oriented backend for working with the PHP c-client (imap) extension. The c-client extension provides functionality for connecting to IMAP, POP3 or NNTP mailboxes. Mail_IMAP acts as a wrapper for the most used c-client functions providing parsing of multipart messages, intelligent message body retrieval as well as header parsing and retrieval. Mail_IMAP is an ideal solution when a customizable webmail template is necessary. Mail_IMAP may also act as a component in an automated mailing list manager, as it can do all the dirty work of retrieving the subject line, message body, attachments or other message components.

The full online documentation is available here

Prev | Mail_IMAP | Next
Mail_IMAP | PEAR Manual | Mail_Mbox


Mail_Mbox

Mail_Mbox

Table of Contents
  • Class Summary Mail_Mbox -- Class to read mbox mail files.
  • Tutorial -- How to use Mail_Mbox
  • constructor Mail_Mbox::Mail_Mbox -- Create a new Mbox class instance.
  • Mail_Mbox::close -- Close a Mbox
  • Mail_Mbox::get -- Get a message from the mbox
  • Mail_Mbox::getDebug -- Returns the debug flag setting
  • Mail_Mbox::getTmpDir -- Returns the temporary directory
  • Mail_Mbox::hasBeenModified -- Checks if the file was modified since it has been loaded.
  • Mail_Mbox::insert -- Insert a message
  • Mail_Mbox::open -- Open the mbox file
  • Mail_Mbox::remove -- Remove a message from Mbox and save it.
  • Mail_Mbox::setDebug -- Set the debug flag
  • Mail_Mbox::setTmpDir -- Set the directory for temporary files.
  • Mail_Mbox::size -- Get number of messages in this mbox
  • Mail_Mbox::update -- Update a message
  • Mail_Mbox::_move -- Copy a file to another
  • Mail_Mbox::_process -- Process the Mbox
Prev | Mail | Next
Introduction | PEAR Manual | Class Summary Mail_Mbox


Class Summary Mail_Mbox

Class Summary Mail_Mbox

Class Summary Mail_Mbox – Class to read mbox mail files.

Reading and writing mbox files.

An mbox mail file is contains plain emails concatenated in one big file. Since each mail starts with "From ", and ends with a newline, they can be separated from each other.

This class takes a mbox filename in the constructor, generates an index where the mails start and end when calling open() and returns single mails with get(), using the positions in the index.

With the help of this class, you also can insert(), remove() and update() messages in the mbox file. When calling one of this methods, the class checks if the file has been modified since the index was created - changing the file with the wrong positions in the index would very likely corrupt it. This check is not done when retrieving single messages via get(), as this would slow down the process if you retrieve thousands of mails. You can, however, call hasBeenModified() before using get() to check for modification yourself. If the method returns true, you should close() and re-open() the file.

If something strange happens and you don't know why, activate debugging with setDebug(true). You also can modify the temporary directory in which changed mboxes are stored when adding/removing/modifying by using setTmpDir('/path/')

Class Tree for Mail_Mbox

  • PEAR

    • Mail_Mbox

Prev | Mail_Mbox | Next
Mail_Mbox | PEAR Manual | Tutorial


Tutorial

Tutorial

Tutorial – How to use Mail_Mbox

How to use Mail_Mbox

Before you can do anything with the mbox file, you need to create an instance of the Mail_Mbox class and open() it.

<?php
require_once 'Mail/Mbox.php';
$mbox = new Mail_Mbox('/path/to/mbox');
$mbox->open();
//do more here
?>

After opening the file, you can retrieve single messages via get(). The size() method helps you to determine the number of messages:

<?php
//... initialisation
for ($n = 0; $n < $mbox->size(); $n++) {
    $message = $mbox->get($n);
    //do something with the message text
}
?>

If you're done working with the file, close() it.

<?php
//... other code
$mbox->close();
?>

Also have a look at the Mail_Mbox examples directory in /path/to/pear/docs/Mail_Mbox/examples/.

Prev | Mail_Mbox | Next
Class Summary Mail_Mbox | PEAR Manual | constructor Mail_Mbox::Mail_Mbox


constructor Mail_Mbox::Mail_Mbox

constructor Mail_Mbox::Mail_Mbox

constructor Mail_Mbox::Mail_Mbox() – Create a new Mbox class instance.

Synopsis

require_once '/Mbox.php';

void constructor Mail_Mbox::Mail_Mbox ( string $file )

Description

After creating a new instance, you should use open() to open an mbox file.

Parameter

string $file

Filename to open.

Prev | Mail_Mbox | Next
Tutorial | PEAR Manual | Mail_Mbox::close


Mail_Mbox::close

Mail_Mbox::close

Mail_Mbox::close() – Close a Mbox

Synopsis

require_once '/Mbox.php';

mixed Mail_Mbox::close ( )

Description

Close the Mbox file opened by open().

Return value

returns true on success, else PEAR_Error

Prev | Mail_Mbox | Next
constructor Mail_Mbox::Mail_Mbox | PEAR Manual | Mail_Mbox::get


Mail_Mbox::get

Mail_Mbox::get

Mail_Mbox::get() – Get a message from the mbox

Synopsis

require_once '/Mbox.php';

string Mail_Mbox::get ( int $message )

Description

Returns the full email message at the given position.

Note: Message number start from 0.

Parameter

integer $message

The number of the message to retrieve.

Return value

returns Return the message, or PEAR_Error on error.

Prev | Mail_Mbox | Next
Mail_Mbox::close | PEAR Manual | Mail_Mbox::getDebug


Mail_Mbox::getDebug

Mail_Mbox::getDebug

Mail_Mbox::getDebug() – Returns the debug flag setting

Synopsis

require_once '/Mbox.php';

boolean Mail_Mbox::getDebug ( )

Description

Returns true if debugging is enabled.

Return value

returns true if debug is enabled.

Prev | Mail_Mbox | Next
Mail_Mbox::get | PEAR Manual | Mail_Mbox::getTmpDir


Mail_Mbox::getTmpDir

Mail_Mbox::getTmpDir

Mail_Mbox::getTmpDir() – Returns the temporary directory

Synopsis

require_once '/Mbox.php';

string Mail_Mbox::getTmpDir ( )

Description

Returns the temporary directory.

Return value

returns The temporary directory.

Prev | Mail_Mbox | Next
Mail_Mbox::getDebug | PEAR Manual | Mail_Mbox::hasBeenModified


Mail_Mbox::hasBeenModified

Mail_Mbox::hasBeenModified

Mail_Mbox::hasBeenModified() – Checks if the file was modified since it has been loaded.

Synopsis

require_once '/Mbox.php';

boolean Mail_Mbox::hasBeenModified ( )

Description

Checks if the mbox file has been modified since opening. If this is true, the file needs to be re-opened.

Return value

returns True if it has been modified.

Prev | Mail_Mbox | Next
Mail_Mbox::getTmpDir | PEAR Manual | Mail_Mbox::insert


Mail_Mbox::insert

Mail_Mbox::insert

Mail_Mbox::insert() – Insert a message

Synopsis

require_once '/Mbox.php';

mixed Mail_Mbox::insert ( string $content , mixed $offset = null )

Description

Mail_Mbox will insert the message according to the specified offset. (Remember: message 3 is the fourth message). The default is to insert the message AFTER the last message (offset = null).

Note: Mail_Mbox automatically adds \n\n at end of the message.

Parameter

string $content

The content of the new message.

mixed $offset

Return value

returns Return true or the PEAR_Error object on failure.

Prev | Mail_Mbox | Next
Mail_Mbox::hasBeenModified | PEAR Manual | Mail_Mbox::open


Mail_Mbox::open

Mail_Mbox::open

Mail_Mbox::open() – Open the mbox file

Synopsis

require_once '/Mbox.php';

void Mail_Mbox::open ( )

Description

Also, this function will process the mbox file and create a cache that tells each message start and end bytes.

Prev | Mail_Mbox | Next
Mail_Mbox::insert | PEAR Manual | Mail_Mbox::remove


Mail_Mbox::remove

Mail_Mbox::remove

Mail_Mbox::remove() – Remove a message from Mbox and save it.

Synopsis

require_once '/Mbox.php';

mixed Mail_Mbox::remove ( int $message )

Description

Removes the message with the given id.

Note: Note: messages start with 0.

Parameter

integer $message

The number of the message to remove, or array of message ids to remove.

Return value

returns Return true or PEAR_Error object on failure.

Prev | Mail_Mbox | Next
Mail_Mbox::open | PEAR Manual | Mail_Mbox::setDebug


Mail_Mbox::setDebug

Mail_Mbox::setDebug

Mail_Mbox::setDebug() – Set the debug flag

Synopsis

require_once '/Mbox.php';

void Mail_Mbox::setDebug ( boolean $debug )

Description

Sets the debug flag. If debugging is enabled, you will get more output.

Parameter

boolean $debug

True if debug is on, otherwise false.

See

see Mail_Mbox::$debug

Prev | Mail_Mbox | Next
Mail_Mbox::remove | PEAR Manual | Mail_Mbox::setTmpDir


Mail_Mbox::setTmpDir

Mail_Mbox::setTmpDir

Mail_Mbox::setTmpDir() – Set the directory for temporary files.

Synopsis

require_once '/Mbox.php';

void Mail_Mbox::setTmpDir ( string $tmpdir )

Description

Sets the temporary directory in which new mbox files are stored.

Parameter

string $tmpdir

The new temporary directory.

See

see Mail_Mbox::$tmpdir

Prev | Mail_Mbox | Next
Mail_Mbox::setDebug | PEAR Manual | Mail_Mbox::size


Mail_Mbox::size

Mail_Mbox::size

Mail_Mbox::size() – Get number of messages in this mbox

Synopsis

require_once '/Mbox.php';

int Mail_Mbox::size ( )

Description

Returns the number of messages in the mbox file.

Return value

returns Number of messages on Mbox (starting on 1, 0 if no message exists).

Prev | Mail_Mbox | Next
Mail_Mbox::setTmpDir | PEAR Manual | Mail_Mbox::update


Mail_Mbox::update

Mail_Mbox::update

Mail_Mbox::update() – Update a message

Synopsis

require_once '/Mbox.php';

mixed Mail_Mbox::update ( int $message , string $content )

Description

Replaces a given message with the text passed to this method.

Note: Mail_Mbox auto adds \n\n at end of the message
Note: messages start with 0.

Parameter

integer $message

The number of the Message to update.

string $content

The new content of the Message.

Return value

returns Return true if all is ok, otherwise PEAR_Error

Prev | Mail_Mbox | Next
Mail_Mbox::size | PEAR Manual | Mail_Mbox::_move


Mail_Mbox::_move

Mail_Mbox::_move

Mail_Mbox::_move() – Copy a file to another

Synopsis

require_once '/Mbox.php';

void Mail_Mbox::_move ( string $ftempname , string $filename )

Description

Used internally to copy the content of the temp file to the mbox file.

Parameter

string $ftempname

Source file - will be removed

string $filename

Output file

Prev | Mail_Mbox | Next
Mail_Mbox::update | PEAR Manual | Mail_Mbox::_process


Mail_Mbox::_process

Mail_Mbox::_process

Mail_Mbox::_process() – Process the Mbox

Synopsis

require_once '/Mbox.php';

void Mail_Mbox::_process ( )

Description

  • Get start bytes and end bytes of each messages.

Prev | Mail_Mbox | Next
Mail_Mbox::_move | PEAR Manual | Mail_Mime


Mail_Mime

Mail_Mime

A Package to enable easy creation of complex multipart emails. If you look for a simple API for creating such emails, then Mail_Mime class will probably suffice. Else you can use Mail_mimePart, which gives you better control about MIME creation.

Mail_mimeDecode provides a API for decode MIME data.

Table of Contents
  • Mail_Mime - Example -- generation and sending of a MIME mail
  • Mail_mimeDecode - Example -- decode an email
  • Mail_Mime::Mail_Mime() -- creates a new instance
  • Mail_Mime::addAttachment() -- add attachment
  • Mail_Mime::addHTMLImage() -- add image to message
  • Mail_Mime::get() -- build the message
  • Mail_Mime::headers() -- build the header lines
  • Mail_Mime::setHTMLBody() -- set HTML part
  • Mail_Mime::setTxtBody() -- set plain text part
  • Mail_mimePart::Mail_mimePart() -- constructor
  • Mail_mimePart::addsubpart() -- add sub part to a MIME part
  • Mail_mimePart::encode() -- encode a mail
  • Mail_mimeDecode::Mail_mimeDecode() -- constructor
  • Mail_mimeDecode::decode() -- perform decoding
  • Mail_mimeDecode::uudecode() -- decode of UU-coded data
  • Mail_mimeDecode::getXML() -- create XML representation of MIME parts
Prev | Mail | Next
Mail_Mbox::_process | PEAR Manual | Mail_Mime - Example


Mail_Mime - Example

Mail_Mime - Example

Mail_Mime - Example – generation and sending of a MIME mail

Example

<?php
include('Mail.php');
include('Mail/mime.php');

$text = 'Text version of email';
$html = '<html><body>HTML version of email</body></html>';
$file = '/home/richard/example.php';
$crlf = "\n";
$hdrs = array(
              'From'    => 'you@yourdomain.com',
              'Subject' => 'Test mime message'
              );

$mime = new Mail_mime($crlf);

$mime->setTXTBody($text);
$mime->setHTMLBody($html);
$mime->addAttachment($file, 'text/plain');

//do not ever try to call these lines in reverse order
$body = $mime->get();
$hdrs = $mime->headers($hdrs);

$mail =& Mail::factory('mail');
$mail->send('postmaster@localhost', $hdrs, $body);
?>
Prev | Mail_Mime | Next
Mail_Mime | PEAR Manual | Mail_mimeDecode - Example


Mail_mimeDecode - Example

Mail_mimeDecode - Example

Mail_mimeDecode - Example – decode an email

Example

Decode an email

<?php
require_once 'Mail/mimeDecode.php';
...
$params['include_bodies'] = true;
$params['decode_bodies']  = true;
$params['decode_headers'] = true;

$decoder = new Mail_mimeDecode($input);
$structure = $decoder->decode($params);
?>

This example calls the decode function statically (ie no object, straight function call) and then passes the structure to the getXML() function.

<?php

...
$params['include_bodies'] = true;
$params['decode_bodies']  = false;
$params['decode_headers'] = true;
$params['input']          = $input;
$params['crlf']           = "\r\n";

$structure = Mail_mimeDecode::decode($params);
$xml = Mail_mimeDecode::getXML($structure);

?>
Prev | Mail_Mime | Next
Mail_Mime - Example | PEAR Manual | Mail_Mime::Mail_Mime()


Mail_Mime::Mail_Mime()

Mail_Mime::Mail_Mime()

Mail_Mime::Mail_Mime() – creates a new instance

Synopsis

require_once 'Mail/mime.php';

Mail_mime Mail_mime ( string $crlf = "\r\n" )

Description

Creates a new instance of Mail_Mime

Parameter

  • string $crlf - the type of line end to use.

Note

Normally, it is not necessary to set the $crlf parameter. But, if you want to send the generated MIME message using Mail then you have to set $crlf to "\n"

Prev | Mail_Mime | Next
Mail_mimeDecode - Example | PEAR Manual | Mail_Mime::addAttachment()


Mail_Mime::addAttachment()

Mail_Mime::addAttachment()

Mail_Mime::addAttachment() – add attachment

Synopsis

require_once 'Mail/mime.php';

boolean addAttachment ( string $file , string $c_type = 'application/octet-stream' , string $name = '' , boolean $isfile = true , string $encoding = 'base64' )

Description

Adds an attachment to a message.

Parameter

  • string $file - The file name or the data itself

  • string $c_type - The content type of the image or file.

  • string $name - The suggested file name for the data. Only used, if $file contains data.

  • boolean $isfile - Whether $file is a file name or not.

  • string $encoding - Type of transfer encoding to use for the file data. Defaults is "base64". For text based files (eg. scripts/html etc.) this could be given as "quoted-printable".

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "File is not readable file_name " | The file was not found or the script has not enough rights to access the file. | Check the file name and path. Check user and file permissions.
NULL | "Could not open file_name " | The file is already opened and exclusivly locked by another application. | In the most cases a program opens the file for writing. addAttachment() does no file locking, so this problem is not caused by competitive callings of this function.

Note

This function can not be called statically.

Prev | Mail_Mime | Next
Mail_Mime::Mail_Mime() | PEAR Manual | Mail_Mime::addHTMLImage()


Mail_Mime::addHTMLImage()

Mail_Mime::addHTMLImage()

Mail_Mime::addHTMLImage() – add image to message

Synopsis

require_once 'Mail/mime.php';

boolean addHTMLImage ( string $file , string $c_type = 'application/octet-stream' , string $name = '' , boolean $isfile = true )

Description

If sending an HTML message with embedded images, use this function to add the image.

Parameter

  • string $file - The image file name or the image data itself

  • string $c_type - The content type of the image or file.

  • string $name - The filename of the image. Only used, if $file contains the image data.

  • boolean $isfile - Whether $file is a filename or not.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "File is not readable file_name " | The file was not found or the script has not enough rights to access the file. | Check the file name and path. Check user and file permissions.
NULL | "Could not open file_name " | The file is already opened and exclusivly locked by another application. | In the most cases a programm opens the file for writing. addHTMLImage() does no file locking, so this problem is not caused by competitve callings of this function.

Note

This function can not be called statically.

See

Mail_Mime::setHTMLBody()

Prev | Mail_Mime | Next
Mail_Mime::addAttachment() | PEAR Manual | Mail_Mime::get()


Mail_Mime::get()

Mail_Mime::get()

Mail_Mime::get() – build the message

Synopsis

require_once 'Mail/mime.php';

string &get ( array $param = null )

Description

This function should be called once you have added the text/html/images/attachments. It builds the message and returns it. It does not send it. To send what this function returns (in conjunction with the headers() -function) you would need to use the Mail::send()-function

Parameter

  • array $param - An associative array of parameters. These parameters affect the way the message is built.

    • $param["text_encoding"] - Type of encoding to use for the plain text part of the email. Default is "7bit".

    • $param["html_encoding"] - Type of encoding for the HTML part of the email. Default is "quoted-printable".

    • $param["7bit_wrap"] - Number of characters after which text is wrapped. SMTP stipulates maximum line length of 1000 characters including CRLF. Default is 998 (CRLF is appended to make up to 1000).

    • $param["head_charset"] - The character set to use for the headers. Default is "iso-8859-1".

    • $param["text_charset"] - The character set to use for the plain text part of the email. Default is "iso-8859-1".

    • $param["html_charset"] - The character set to use for the HTML part of the email. Default is "iso-8859-1".

Return value

string - the body of the message

Note

This function can not be called statically.

Mail_Mime::get() has to be called before Mail_Mime::headers().

See

Mail_Mime::headers()

Prev | Mail_Mime | Next
Mail_Mime::addHTMLImage() | PEAR Manual | Mail_Mime::headers()


Mail_Mime::headers()

Mail_Mime::headers()

Mail_Mime::headers() – build the header lines

Synopsis

require_once 'Mail/mime.php';

array &headers ( array $headerEx = null , boolean $overwrite = false )

Description

Returns an array with the headers needed to prepend to the email (MIME-Version and Content-Type). Please note that the function get() has to be called before calling headers().

Parameter

  • array $headerEx - Additional headers, the format of the argument is $array["header-name"] = "header-value"

  • boolean $overwrite - Overwrite already existing headers. When FALSE, the values already set are kept.

Return value

array - an associative array with the mime headers and the additional headers. The return value can directly passed to the second parameter of Mail::send().

Note

This function can not be called statically.

Mail_Mime::headers() has to be called after Mail_Mime::get().

See

Mail_Mime::get()

Prev | Mail_Mime | Next
Mail_Mime::get() | PEAR Manual | Mail_Mime::setHTMLBody()


Mail_Mime::setHTMLBody()

Mail_Mime::setHTMLBody()

Mail_Mime::setHTMLBody() – set HTML part

Synopsis

require_once 'Mail/mime.php';

boolean setHTMLBody ( string $data , boolean $isfile = false )

Description

Sets the HTML part of a message

Parameter

  • string $data - The text to set or, if $isfile is TRUE a valid filename. An URL as argument is not allowed.

  • boolean $isfile - If TRUE, the content of given file $data is used as message text.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "File is not readable file_name " | The file was not found or the script has not enough rights to access the file. | Check the file name and path. Check user and file permissions.
NULL | "Could not open file_name " | The file is already opened and exclusivly locked by another application. | In the most cases a programm opens the file for writing. setHTMLBody() does no file locking, so this problem is not caused by competitve callings of this function.

Note

This function can not be called statically.

See

Mail_Mime::setTxtBody()

Prev | Mail_Mime | Next
Mail_Mime::headers() | PEAR Manual | Mail_Mime::setTxtBody()


Mail_Mime::setTxtBody()

Mail_Mime::setTxtBody()

Mail_Mime::setTxtBody() – set plain text part

Synopsis

require_once 'Mail/mime.php';

boolean setTxtBody ( string $data , boolean $isfile = false )

Description

Sets the plain text part of a message

Parameter

  • string $data - The text to set or, if $isfile is TRUE a valid filename. An URL as argument is not allowed.

  • boolean $isfile - If TRUE, the content of given file $data is used as message text.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "File is not readable file_name " | The file was not found or the script has not enough rights to access the file. | Check the file name and path. Check user and file permissions.
NULL | "Could not open file_name " | The file is already opened and exclusivly locked by another application. | In the most cases a programm opens the file for writing. setTxtBody() does no file locking, so this problem is not caused by competitve callings of this function.

Note

This function can not be called statically.

See

Mail_Mime::setHTMLBody()

Prev | Mail_Mime | Next
Mail_Mime::setHTMLBody() | PEAR Manual | Mail_mimePart::Mail_mimePart()


Mail_mimePart::Mail_mimePart()

Mail_mimePart::Mail_mimePart()

Mail_mimePart::Mail_mimePart() – constructor

Synopsis

require_once 'Mail/mimePart.php';

Mail_mimePart Mail_mimePart ( string $body = '' , array $params = array() )

Description

Create a new Mail_mimePart object.

Parameter

  • string $body - The body of the mime part if any. Default is an empty string.

  • array $params - An associative array of parameters:

    • $params["content_type"] - The content type for this part ie. multipart/mixed

    • $params["encoding"] - The encoding to use ie. 7bit , 8bit , base64 or quoted-printable

    • $params["cid"] - content ID to apply

    • $params["disposition"] - Content disposition inline or attachment

    • $params["dfilename"] - Optional filename parameter for content disposition

    • $params["description"] - Content description

    • $params["charset"] - Character set to use

    Default is an empty array.

Note

This function can be called statically.

Prev | Mail_Mime | Next
Mail_Mime::setTxtBody() | PEAR Manual | Mail_mimePart::addsubpart()


Mail_mimePart::addsubpart()

Mail_mimePart::addsubpart()

Mail_mimePart::addsubpart() – add sub part to a MIME part

Synopsis

require_once 'Mail/mimePart.php';

resource &addSubPart ( string $body , array $params )

Description

Adds a sub part to the current MIME part and returns a reference to it

Parameter

  • string - the body of the sub part

  • array - the parameter for the sub part. See constructor for the possible values.

Return value

resource - a reference to the added part

Note

This function can not be called statically.

Example

Add two attachments to a mail

<?php
include 'Mail/mimePart.php';

...

$params['content_type'] = 'multipart/mixed';
$email = new Mail_mimePart('', $params);

// Here we add a text part to the multipart we have
// already. Assume $body contains plain text.

$params['content_type'] = 'text/plain';
$params['encoding']     = '7bit';
$text = $email->addSubPart($body, $params);

// Now add an attachment. Assume $contents is
// the contents of the attachment

$params['content_type'] = 'application/zip';
$params['encoding']     = 'base64';
$params['disposition']  = 'attachment';
$params['dfilename']    = 'example.zip';
$attach =& $email->addSubPart($contents, $params);

// Now build the email. Note that the encode
// function returns an associative array containing two
// elements, body and headers. You will need to add extra
// headers, (eg. Mime-Version) before sending.

$email = $email->encode();
$email['headers']['Mime-Version'] = '1.0';

...
?>
Prev | Mail_Mime | Next
Mail_mimePart::Mail_mimePart() | PEAR Manual | Mail_mimePart::encode()


Mail_mimePart::encode()

Mail_mimePart::encode()

Mail_mimePart::encode() – encode a mail

Synopsis

require_once 'Mail/mimePart.php';

array encode ( )

Description

Encodes and returns the email

Return value

array - an associative array containing two elements, body and headers. The headers element is itself an indexed array.

The key names are

  • 'headers' - an array with the mail headers
  • 'body' - a string with the mail body

Note

This function can not be called statically.

Prev | Mail_Mime | Next
Mail_mimePart::addsubpart() | PEAR Manual | Mail_mimeDecode::Mail_mimeDecode()


Mail_mimeDecode::Mail_mimeDecode()

Mail_mimeDecode::Mail_mimeDecode()

Mail_mimeDecode::Mail_mimeDecode() – constructor

Synopsis

require_once 'Mail/mimeDecode.php';

void Mail_mimeDecode ( string $input )

Description

Create a new Mail_mimeDecode object.

Parameter

  • string $input - the input to decode

Note

This function can be called statically.

Prev | Mail_Mime | Next
Mail_mimePart::encode() | PEAR Manual | Mail_mimeDecode::decode()


Mail_mimeDecode::decode()

Mail_mimeDecode::decode()

Mail_mimeDecode::decode() – perform decoding

Synopsis

require_once 'Mail/mimeDecode.php';

object decode ( array $args = null )

Description

This function performs the decoding and returns a structure containing the message data.

Parameter

  • array $args - an array with the function arguments

    • boolean $args['include_bodies'] - whether to include the bodies in the returned structure.

    • boolean $args['decode_bodies'] - whether to decode the returned bodies.

    • boolean $args['decode_headers'] - whether to decode the headers (RFC2047).

    • string $args['input'] - if and only if called statically, this should be used to specify the input to be decoded.

    • string $args['crlf'] - if and only if called statically, this should be used to specify the line ending type.

Return value

object -

  • array $return->headers - an associative array of the headers. The keys of the array are the header names (lowercased) whilst the values are the header values (original case). If there are multiple headers with the same name (eg. Received: ) then the value is a numerically indexed array of each of the header values. If the parameter decode_headers is specified as TRUE, the headers will be decoded according to RFC 2047.

  • string $return->ctype_primary - the first part of the content type (ie. before the forward slash). Eg. if the content type is multipart/mixed , ctype_primary would be "multipart" .

  • string $return->ctype_secondary - the second part of the content type. Eg. If the content type is multipart/mixed , ctype_secondary would be "mixed" .

  • array $return->ctype_parameters - if the content type header has any parameters (eg. boundary="=_hudfhdsalfhds8fy8329hfj ") then they will be in this associative array. Keys are the parameter name (eg. boundary ) whilst the values are the parameter values (eg. =_hudfhdsalfhds8fy8329hfj ).

  • string $return->disposition - if the Content-Disposition header is present, its value will be given here. This is usually either "inline" or "attachment" .

  • array $return->d_parameters - if any parameters are given with the Content-Disposition header, they will be given here in an associative array, keys being the parameter names and values being the parameter values. "name" and "filename" are two common examples here.

  • array $return->body - if the include_bodies parameter is given when instanciating the class, (either statically or via a concrete instance), then this will be present if the part in question has a body. MIME parts with content type multipart/* generally do not not have bodies, instead consisting of subparts. If the parameter decode_bodies is specified as TRUE then the body will be decoded.

  • array $return->parts - if a MIME part consists of subparts, then this array will be present consisting of objects with the same properties as described here.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | " Called statically and no input given " | You called the function statically and forgot to fill $args['input'] | Fill $args['input'] with the content to decode or do not call the function statically.
NULL | every other | See the error message. | The input or parts of the input does not complies to the MIME standard.

Note

This function can be called statically.

Prev | Mail_Mime | Next
Mail_mimeDecode::Mail_mimeDecode() | PEAR Manual | Mail_mimeDecode::uudecode()


Mail_mimeDecode::uudecode()

Mail_mimeDecode::uudecode()

Mail_mimeDecode::uudecode() – decode of UU-coded data

Synopsis

require_once 'Mail/mimeDecode.php';

array &uudecode ( string $input )

Description

Decodes UU-coded data. 'Unix-to-Unix'-Encoding is used to send binary files (eg. programs, graphics) over 7bit-ASCII-only media, like email.

Parameter

  • string $input - data to decode

Return value

array - the decoded data

  • string $return[]['filename'] - the name of the UUencoded file.

  • string $return[]['fileperm'] - the file permissions of the UUencoded file, if given. The format is unix-styled, ie. "0666" or "666" .

  • string $return[]['filedata'] - the decoded content of the UUencoded file.

Note

This function can be called statically.

Prev | Mail_Mime | Next
Mail_mimeDecode::decode() | PEAR Manual | Mail_mimeDecode::getXML()


Mail_mimeDecode::getXML()

Mail_mimeDecode::getXML()

Mail_mimeDecode::getXML() – create XML representation of MIME parts

Synopsis

require_once 'Mail/mimeDecode.php';

string getXML ( array $decoded )

Description

getXML() converts the returned array from decode () into a valid XML document.

Parameter

  • array $decode - the array from decode().

Return value

string - the XML document

Note

This function can be called statically.

Example

Create a XML representation

<?php
...
$output = $obj->decode();
$xml    = Mail_mimeDecode::getXML($output);
...
?>
Prev | Mail_Mime | Next
Mail_mimeDecode::uudecode() | PEAR Manual | Mail_Queue


Mail_Queue

Mail_Queue

Table of Contents
  • Class Summary Mail_Queue -- Mail_Queue - base class for mail queue managment.
  • Tutorial -- A tutorial for Mail_Queue
  • constructor Mail_Queue::Mail_Queue -- Mail_Queue constructor
  • Mail_Queue::deleteMail -- Delete a mail from queue.
  • Mail_Queue::factorySendMail -- Creates the necessary Mail object.
  • Mail_Queue::get -- Get next mail from queue.
  • Mail_Queue::put -- Put a new mail into queue.
  • Mail_Queue::sendMail -- Sends mail object returned by Mail_Queue::get()
  • Mail_Queue::sendMailById -- Send a specific mail.
  • Mail_Queue::sendMailsInQueue -- Send mails from queue.
Prev | Mail | Next
Mail_mimeDecode::getXML() | PEAR Manual | Class Summary Mail_Queue


Class Summary Mail_Queue

Class Summary Mail_Queue

Class Summary Mail_Queue – Mail_Queue - base class for mail queue managment.

Mail_Queue - base class for mail queue managment.

This class allows you to queue mails for later delivery.

Class Trees for Mail_Queue

  • Pear

  • Mail_Queue

Prev | Mail_Queue | Next
Mail_Queue | PEAR Manual | Tutorial


Tutorial

Tutorial

Tutorial – A tutorial for Mail_Queue

Mail_Queue usage with a simple example

We are using the db-container for the example and a mysql database. You need to create some tables in the mysql-database to store the messages:

mysql.sql

CREATE TABLE mail_queue (
  id bigint(20) NOT NULL default '0',
  create_time datetime NOT NULL default '0000-00-00 00:00:00',
  time_to_send datetime NOT NULL default '0000-00-00 00:00:00',
  sent_time datetime default NULL,
  id_user bigint(20) NOT NULL default '0',
  ip varchar(20) NOT NULL default 'unknown',
  sender varchar(50) NOT NULL default '',
  recipient text NOT NULL,
  headers text NOT NULL,
  body longtext NOT NULL,
  try_sent tinyint(4) NOT NULL default '0',
  delete_after_send tinyint(1) NOT NULL default '1',
  PRIMARY KEY  (id),
  KEY id (id),
  KEY time_to_send (time_to_send),
  KEY id_user (id_user)
);

First you need to define some options. As you need them two times (once for adding messages, once for sending the messages) its always good to add them to a config-file. Let's call it config.php

config.php

<?php

require_once "Mail/Queue.php";

// options for storing the messages
// type is the container used, currently there are 'creole', 'db', 'mdb' and 'mdb2' available
$db_options['type']       = 'mdb2';
// the others are the options for the used container
// here are some for db
$db_options['dsn']        = 'mysql://user:password@host/database';
$db_options['mail_table'] = 'mail_queue';

// here are the options for sending the messages themselves
// these are the options needed for the Mail-Class, especially used for Mail::factory()
$mail_options['driver']    = 'smtp';
$mail_options['host']      = 'your_server_smtp.com';
$mail_options['port']      = 25;
$mail_options['localhost'] = 'localhost'; //optional Mail_smtp parameter
$mail_options['auth']      = false;
$mail_options['username']  = '';
$mail_options['password']  = '';

?>

So we are done configuring it, now let's use it. First we need to construct a mail-message and add it to the queue:

add_message.php

<?php
include './config.php';
/* we use the db_options and mail_options here */
$mail_queue =& new Mail_Queue($db_options, $mail_options);

$from = 'user@server.com';
$to = "user2@server.com";
$message = 'Hi! This is test message!! :)';

$hdrs = array( 'From'    => $from,
               'To'      => $to,
               'Subject' => "test message body"  );

/* we use Mail_mime() to construct a valid mail */
$mime =& new Mail_mime();
$mime->setTXTBody($message);
$body = $mime->get();
$hdrs = $mime->headers($hdrs);

/* Put message to queue */
$mail_queue->put($from, $to, $hdrs, $body);

?>

NB: the first time you call put(), PEAR::DB and PEAR::MDB2 will create a new table to keep the sequence number, so make sure the db user you are using has "CREATE TABLE" privileges. Or you can create the table separately, calling the createSequence() method of PEAR::DB or PEAR::MDB2 (you should also be aware that the two DBAL will create a table with a different field name: "id" for DB, "sequence" for MDB2).

Ok, now we've used the simple way to add a message ... there are more advanced options, please check docs of the put-function for these. Now we need to send the messages. This is most often done by using a cron-job which regularly runs a script to send the messages. Here is a simple script to achieve this:

send_messages.php

<?php
include './config.php';

/* How many mails could we send each time the script is called */
$max_amount_mails = 50;

/* we use the db_options and mail_options from the config again  */
$mail_queue =& new Mail_Queue($db_options, $mail_options);

/* really sending the messages */
$mail_queue->sendMailsInQueue($max_amount_mails);
?>

We are done. Now run the last script regularly and add your mails to the queue as needed.

Since Mail_Queue v.1.1, the preload() method doesn't preload ALL the mails in memory, but just a few of them each time. When the buffer is empty, it is filled again automatically. You can set the size of the buffer via the new setBufferSize() method.

You can also send the stored emails one by one. Here is a simple script to achieve this:

send_messages_one_by_one.php

<?php
// set the internal buffer size according your
// memory resources (the number indicates how
// many emails can stay in the buffer at any
// given time)

$mail_queue->setBufferSize(20);

//set the queue size (i.e. the number of mails to send)
$limit = 50;
$mail_queue->container->setOption($limit);

// loop through the stored emails and send them
while ($mail = $mail_queue->get()) {
    $result = $mail_queue->sendMail($mail);
}
?>
Prev | Mail_Queue | Next
Class Summary Mail_Queue | PEAR Manual | constructor Mail_Queue::Mail_Queue


constructor Mail_Queue::Mail_Queue

constructor Mail_Queue::Mail_Queue

constructor Mail_Queue::Mail_Queue() – Mail_Queue constructor

Synopsis

require_once 'Mail/Queue.php';

mixed constructor Mail_Queue::Mail_Queue ( array $container_options , array $mail_options )

Description

Creates a new mail queue object to store mails in, fetch mails from and send mails with.

Parameter

array $container_options

Array of container (mail storage) options. See tutorial for details.

array $mail_options

Array of mailer options. See tutorial for details.

<?php

require_once 'Mail/Queue.php';

$container_options = array(
    'type'        => 'db',
    'database'    => 'dbname',
    'phptype'     => 'mysql',
    'username'    => 'root',
    'password'    => '',
    'mail_table'  => 'mail_queue',
);
//optionally, a 'dns' string can be provided instead of db parameters.
//look at DB::connect() method or at DB or MDB docs for details.
//you could also use mdb container instead db
$mail_options = array(
    'driver'   => 'smtp',
    'host'     => 'your_smtp_server.com',
    'port'     => 25,
    'auth'     => false,
    'username' => '',
    'password' => '',
);

$mail_queue =& new Mail_Queue($container_options, $mail_options);

* *****************************************************************
* // TO ADD AN EMAIL TO THE QUEUE
* *****************************************************************
$from             = 'user@server.com';
$from_name        = 'admin';
$recipient        = 'recipient@other_server.com';
$recipient_name   = 'recipient';
$message          = 'Test message';
$from_params      = empty($from_name) ? '<'.$from.'>' : '"'.$from_name.'" <'.$from.'>';
$recipient_params = empty($recipient_name) ? '<'.$recipient.'>' : '"'.$recipient_name.'" <'.$recipient.'>';
$hdrs = array(
    'From'    => $from_params,
    'To'      => $recipient_params,
    'Subject' => 'test message body',
);
$mime =& new Mail_mime();
$mime->setTXTBody($message);
$body = $mime->get();
$hdrs = $mime->headers($hdrs);

// Put message to queue
$mail_queue->put($from, $recipient, $hdrs, $body);

// Also you could put this msg in more advanced mode
$seconds_to_send = 3600;
$delete_after_send = false;
$id_user = 7;
$mail_queue->put( $from, $recipient, $hdrs, $body, $seconds_to_send, $delete_after_send, $id_user );

// TO SEND EMAILS IN THE QUEUE

// How many mails could we send each time
$max_ammount_mails = 50;
$mail_queue =& new Mail_Queue($container_options, $mail_options);
$mail_queue->sendMailsInQueue($max_ammount_mails);

?>

Return value

returnsTrue on success else pear error class.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Tutorial | PEAR Manual | Mail_Queue::deleteMail


Mail_Queue::deleteMail

Mail_Queue::deleteMail

Mail_Queue::deleteMail() – Delete a mail from queue.

Synopsis

require_once 'Mail/Queue.php';

boolean Mail_Queue::deleteMail ( integer $id )

Description

Deletes a mail from the queue by identifier.

Parameter

integer $id

Mail identifier.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
constructor Mail_Queue::Mail_Queue | PEAR Manual | Mail_Queue::factorySendMail


Mail_Queue::factorySendMail

Mail_Queue::factorySendMail

Mail_Queue::factorySendMail() – Creates the necessary Mail object.

Synopsis

require_once 'Mail/Queue.php';

void Mail_Queue::factorySendMail ( )

Description

Creates the necessary Mail object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Mail_Queue::deleteMail | PEAR Manual | Mail_Queue::get


Mail_Queue::get

Mail_Queue::get

Mail_Queue::get() – Get next mail from queue.

Synopsis

require_once 'Mail/Queue.php';

object Mail_Queue_Container::get ( )

Description

Get next mail from queue. The emails are preloaded into an internal memory buffer to speed up the process. Since Mail_Queue v.1.1, the preload() method doesn't preload ALL the mails in memory, but just a few of them each time. When the buffer is empty, it is filled again automatically. You can set the size of the buffer via the setBufferSize() method.

Return value

returnsMail_Queue_Body object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Mail_Queue::factorySendMail | PEAR Manual | Mail_Queue::put


Mail_Queue::put

Mail_Queue::put

Mail_Queue::put() – Put a new mail into queue.

Synopsis

require_once 'Mail/Queue.php';

int Mail_Queue::put ( string $from , string $to , array $hdrs , array $body , integer $sec_to_send = 0 , bool $delete_after_send = true , integer $id_user = MAILQUEUE_SYSTEM )

Description

Injects a new mail into the mail queue.

Parameter

string $from

Sender e-mail address.

string $to

Recipient e-mail address.

array $hdrs

Array of mail headers as returned by Mail_Mime::headers().

array $body

Mail body array as returned by Mail_Mime::get().

mixed $sec_to_send

Optional - Seconds to pass before delivery is attempted.

mixed $delete_after_send

Optional - Whether or not to delete the mail after delivery.

integer $id_user

Optional - user ID. Stored in queue and readable from mail body object with getIdUser() at a later point.

Return value

returns ID of the record where this mail has been put or Mail_Queue_Error on error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Mail_Queue::get | PEAR Manual | Mail_Queue::sendMail


Mail_Queue::sendMail

Mail_Queue::sendMail

Mail_Queue::sendMail() – Sends mail object returned by Mail_Queue::get()

Synopsis

require_once 'Mail/Queue.php';

mixed Mail_Queue::sendMail ( object MailBody $mail )

Description

Sends mail object returned by Mail_Queue::get().

Parameter

object MailBody $mail

Mail object.

Return value

returns True on success else pear error class

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Mail_Queue::put | PEAR Manual | Mail_Queue::sendMailById


Mail_Queue::sendMailById

Mail_Queue::sendMailById

Mail_Queue::sendMailById() – Send a specific mail.

Synopsis

require_once 'Mail/Queue.php';

bool Mail_Queue::sendMailById ( integer $id )

Description

Sends a single mail from the queue specified by $id. Note: The queue entry will not be deleted automatically after delivery!

Parameter

integer $id

Mail identifier

Return value

returns True on success else false

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Mail_Queue::sendMail | PEAR Manual | Mail_Queue::sendMailsInQueue


Mail_Queue::sendMailsInQueue

Mail_Queue::sendMailsInQueue

Mail_Queue::sendMailsInQueue() – Send mails from queue.

Synopsis

require_once 'Mail/Queue.php';

mixed Mail_Queue::sendMailsInQueue ( integer $limit = MAILQUEUE_ALL , integer $offset = MAILQUEUE_START , integer $try = MAILQUEUE_TRY )

Description

Sends mails remaining in queue.

Parameter

integer $limit

Optional - maximum number of mails to send.

integer $offset

Optional - skip $offset mails and start sending from there.

integer $try

Optional - count of tries before mail returns to queue for later delivery.

Return value

returnsTrue on success else Mail_Queue_Error object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Mail_Queue | Next
Mail_Queue::sendMailById | PEAR Manual | Math


Math

Math

Provides Packages for mathematical purposes

Table of Contents
  • Math_Complex
  • Math_TrigOp
Prev | PEAR Packages | Next
Mail_Queue::sendMailsInQueue | PEAR Manual | Math_Complex


Math_Complex

Math_Complex

Table of Contents
  • Class Summary Math_Complex -- Math_Complex: class to represent an manipulate complex numbers (z = a + b*i)
  • constructor Math_Complex::Math_Complex -- Constructor for Math_Complex
  • Math_Complex::abs -- Returns the magnitude (also referred as norm) of the number
  • Math_Complex::abs2 -- Returns the square of the magnitude of the number
  • Math_Complex::angle -- Returns the angle (argument) associated with the complex number Alias of Math_Complex::arg()
  • Math_Complex::arg -- Returns the argument of the complex number
  • Math_Complex::getIm -- Returns the imaginary part of the complex number
  • Math_Complex::getReal -- Returns the real part of the complex number
  • Math_Complex::norm -- Returns the norm of the number Alias of Math_Complex::abs()
  • Math_Complex::toString -- Simple string representation of the number
  • Class Summary Math_ComplexOp -- Math_ComplexOp: static class to operate on Math_Complex objects
  • Math_ComplexOp::acos -- Calculates the inverse cosine of a complex number: z = acos(c1)
  • Math_ComplexOp::acosh -- Calculates the inverse hyperbolic cosine of a complex number: z = acosh(c1)
  • Math_ComplexOp::acot -- Calculates the inverse cotangent of a complex number: z = acot(c1)
  • Math_ComplexOp::acoth -- Calculates the inverse hyperbolic cotangent of a complex number: z = acoth(c1)
  • Math_ComplexOp::acsc -- Calculates the inverse cosecant of a complex number: z = acsc(c1)
  • Math_ComplexOp::acsch -- Calculates the inverse hyperbolic cosecant of a complex number: z = acsch(c1)
  • Math_ComplexOp::add -- Returns the sum of two complex numbers: z = c1 + c2
  • Math_ComplexOp::areEqual -- Determines if is c1 == c2:
  • Math_ComplexOp::asec -- Calculates the inverse secant of a complex number: z = asec(c1)
  • Math_ComplexOp::asech -- Calculates the inverse hyperbolic secant of a complex number: z = asech(c1)
  • Math_ComplexOp::asin -- Calculates the inverse sine of a complex number: z = asin(c1)
  • Math_ComplexOp::asinAlt -- Calculates the inverse sine of a complex number: z = asinAlt(c1) Uses an alternative algorithm
  • Math_ComplexOp::asinh -- Calculates the inverse hyperbolic sine of a complex number: z = asinh(c1)
  • Math_ComplexOp::asinReal -- Calculates the complex inverse sine of a real number: z = asinReal(r):
  • Math_ComplexOp::atan -- Calculates the inverse tangent of a complex number: z = atan(c1):
  • Math_ComplexOp::atanh -- Calculates the inverse hyperbolic tangent of a complex number: z = atanh(c1)
  • Math_ComplexOp::conjugate -- Calculates the conjugate of a complex number: z = conj(c1)
  • Math_ComplexOp::cos -- Calculates the cosine of a complex number: z = cos(c1)
  • Math_ComplexOp::cosh -- Calculates the hyperbolic cosine of a complex number: z = cosh(c1)
  • Math_ComplexOp::cot -- Calculates the cotangent of a complex number: z = cot(c1)
  • Math_ComplexOp::coth -- Calculates the hyperbolic cotangent of a complex number: z = coth(c1)
  • Math_ComplexOp::createFromPolar -- Converts a polar complex z = r*exp(theta*i) to z = a + b*i
  • Math_ComplexOp::csc -- Calculates the cosecant of a complex number: z = csc(c1)
  • Math_ComplexOp::csch -- Calculates the hyperbolic cosecant of a complex number: z = csch(c1)
  • Math_ComplexOp::div -- Returns the division of two complex numbers: z = c1 * c2
  • Math_ComplexOp::exp -- Calculates the exponential of a complex number: z = exp(c1)
  • Math_ComplexOp::inverse -- Calculates the inverse of a complex number: z = 1/c1
  • Math_ComplexOp::isComplex -- Checks if a given object is an instance of PEAR::Math_Complex
  • Math_ComplexOp::log -- Calculates the logarithm (base 2) of a complex number: z = log(c1)
  • Math_ComplexOp::log10 -- Calculates the logarithm (base 10) of a complex number: z = log10(c1)
  • Math_ComplexOp::logBase -- Returns the logarithm of base c2 of the complex number c1
  • Math_ComplexOp::mult -- Returns the product of two complex numbers: z = c1 * c2
  • Math_ComplexOp::multIm -- Returns the product of a complex number and an imaginary number if: x = b + c*i, y = a*i; then: z = x * y = multIm(x, a)
  • Math_ComplexOp::multReal -- Multiplies a complex number by a real number: z = realnumber * c1
  • Math_ComplexOp::negative -- Calculates the negative of a complex number: z = -c1
  • Math_ComplexOp::pow -- Returns the complex power of two complex numbers: z = c1^c2
  • Math_ComplexOp::powReal -- Returns the exponentiation of a complex numbers to a real power: z = c1^(real)
  • Math_ComplexOp::sec -- Calculates the secant of a complex number: z = sec(c1)
  • Math_ComplexOp::sech -- Calculates the hyperbolic secant of a complex number: z = sech(c1)
  • Math_ComplexOp::sin -- Calculates the sine of a complex number: z = sin(c1)
  • Math_ComplexOp::sinh -- Calculates the hyperbolic sine of a complex number: z = sinh(c1)
  • Math_ComplexOp::sqrt -- Calculates the complex square root of a complex number: z = sqrt(c1)
  • Math_ComplexOp::sqrtReal -- Calculates the complex square root of a real number: z = sqrt(realnumber)
  • Math_ComplexOp::sub -- Returns the difference of two complex numbers: z = c1 - c2
  • Math_ComplexOp::tan -- Calculates the tangent of a complex number: z = tan(c1)
  • Math_ComplexOp::tanh -- Calculates the hyperbolic tangent of a complex number: z = tanh(c1)
Prev | Math | Next
Math | PEAR Manual | Class Summary Math_Complex


Class Summary Math_Complex

Class Summary Math_Complex

Class Summary Math_Complex – Math_Complex: class to represent an manipulate complex numbers (z = a + b*i)

Math_Complex: class to represent an manipulate complex numbers (z = a + b*i)

Originally this class was part of NumPHP (Numeric PHP package)

Class Trees for Math_Complex

  • Math_Complex

Prev | Math_Complex | Next
Math_Complex | PEAR Manual | constructor Math_Complex::Math_Complex


constructor Math_Complex::Math_Complex

constructor Math_Complex::Math_Complex

constructor Math_Complex::Math_Complex() – Constructor for Math_Complex

Synopsis

require_once '/Complex.php';

object Math_Complex constructor Math_Complex::Math_Complex ( float $real , float $im )

Description

This package is not documented yet.

Parameter

float $real

Real part of the number

float $im

Imaginary part of the number

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Class Summary Math_Complex | PEAR Manual | Math_Complex::abs


Math_Complex::abs

Math_Complex::abs

Math_Complex::abs() – Returns the magnitude (also referred as norm) of the number

Synopsis

require_once '/Complex.php';

float Math_Complex::abs ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
constructor Math_Complex::Math_Complex | PEAR Manual | Math_Complex::abs2


Math_Complex::abs2

Math_Complex::abs2

Math_Complex::abs2() – Returns the square of the magnitude of the number

Synopsis

require_once '/Complex.php';

float Math_Complex::abs2 ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::abs | PEAR Manual | Math_Complex::angle


Math_Complex::angle

Math_Complex::angle

Math_Complex::angle() – Returns the angle (argument) associated with the complex number Alias of Math_Complex::arg()

Synopsis

require_once '/Complex.php';

mixed Math_Complex::angle ( )

Description

This package is not documented yet.

Return value

returns A float on success, a PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::abs2 | PEAR Manual | Math_Complex::arg


Math_Complex::arg

Math_Complex::arg

Math_Complex::arg() – Returns the argument of the complex number

Synopsis

require_once '/Complex.php';

float|PEAR_Error Math_Complex::arg ( )

Description

This package is not documented yet.

Return value

returns A floating point number on success, a PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::angle | PEAR Manual | Math_Complex::getIm


Math_Complex::getIm

Math_Complex::getIm

Math_Complex::getIm() – Returns the imaginary part of the complex number

Synopsis

require_once '/Complex.php';

float Math_Complex::getIm ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::arg | PEAR Manual | Math_Complex::getReal


Math_Complex::getReal

Math_Complex::getReal

Math_Complex::getReal() – Returns the real part of the complex number

Synopsis

require_once '/Complex.php';

float Math_Complex::getReal ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::getIm | PEAR Manual | Math_Complex::norm


Math_Complex::norm

Math_Complex::norm

Math_Complex::norm() – Returns the norm of the number Alias of Math_Complex::abs()

Synopsis

require_once '/Complex.php';

float Math_Complex::norm ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::getReal | PEAR Manual | Math_Complex::toString


Math_Complex::toString

Math_Complex::toString

Math_Complex::toString() – Simple string representation of the number

Synopsis

require_once '/Complex.php';

string Math_Complex::toString ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Math_Complex | Next
Math_Complex::norm | PEAR Manual | Class Summary Math_ComplexOp


Class Summary Math_ComplexOp

Class Summary Math_ComplexOp

Class Summary Math_ComplexOp – Math_ComplexOp: static class to operate on Math_Complex objects

Math_ComplexOp: static class to operate on Math_Complex objects

Originally this class was part of NumPHP (Numeric PHP package)

Class Trees for Math_ComplexOp

  • Math_ComplexOp

Prev | Math_Complex | Next
Math_Complex::toString | PEAR Manual | Math_ComplexOp::acos


Math_ComplexOp::acos

Math_ComplexOp::acos

Math_ComplexOp::acos() – Calculates the inverse cosine of a complex number: z = acos(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::acos ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Class Summary Math_ComplexOp | PEAR Manual | Math_ComplexOp::acosh


Math_ComplexOp::acosh

Math_ComplexOp::acosh

Math_ComplexOp::acosh() – Calculates the inverse hyperbolic cosine of a complex number: z = acosh(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::acosh ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::acos | PEAR Manual | Math_ComplexOp::acot


Math_ComplexOp::acot

Math_ComplexOp::acot

Math_ComplexOp::acot() – Calculates the inverse cotangent of a complex number: z = acot(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::acot ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::acosh | PEAR Manual | Math_ComplexOp::acoth


Math_ComplexOp::acoth

Math_ComplexOp::acoth

Math_ComplexOp::acoth() – Calculates the inverse hyperbolic cotangent of a complex number: z = acoth(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::acoth ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::acot | PEAR Manual | Math_ComplexOp::acsc


Math_ComplexOp::acsc

Math_ComplexOp::acsc

Math_ComplexOp::acsc() – Calculates the inverse cosecant of a complex number: z = acsc(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::acsc ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::acoth | PEAR Manual | Math_ComplexOp::acsch


Math_ComplexOp::acsch

Math_ComplexOp::acsch

Math_ComplexOp::acsch() – Calculates the inverse hyperbolic cosecant of a complex number: z = acsch(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::acsch ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::acsc | PEAR Manual | Math_ComplexOp::add


Math_ComplexOp::add

Math_ComplexOp::add

Math_ComplexOp::add() – Returns the sum of two complex numbers: z = c1 + c2

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::add ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::acsch | PEAR Manual | Math_ComplexOp::areEqual


Math_ComplexOp::areEqual

Math_ComplexOp::areEqual

Math_ComplexOp::areEqual() – Determines if is c1 == c2:

Synopsis

require_once '/ComplexOp.php';

boolean|PEAR_Error& Math_ComplexOp::areEqual ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns True if $c1 == $c2, False if $c1 != $c2, PEAR_Error object on error

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::add | PEAR Manual | Math_ComplexOp::asec


Math_ComplexOp::asec

Math_ComplexOp::asec

Math_ComplexOp::asec() – Calculates the inverse secant of a complex number: z = asec(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::asec ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::areEqual | PEAR Manual | Math_ComplexOp::asech


Math_ComplexOp::asech

Math_ComplexOp::asech

Math_ComplexOp::asech() – Calculates the inverse hyperbolic secant of a complex number: z = asech(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::asech ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::asec | PEAR Manual | Math_ComplexOp::asin


Math_ComplexOp::asin

Math_ComplexOp::asin

Math_ComplexOp::asin() – Calculates the inverse sine of a complex number: z = asin(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::asin ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::asech | PEAR Manual | Math_ComplexOp::asinAlt


Math_ComplexOp::asinAlt

Math_ComplexOp::asinAlt

Math_ComplexOp::asinAlt() – Calculates the inverse sine of a complex number: z = asinAlt(c1) Uses an alternative algorithm

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::asinAlt ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::asin | PEAR Manual | Math_ComplexOp::asinh


Math_ComplexOp::asinh

Math_ComplexOp::asinh

Math_ComplexOp::asinh() – Calculates the inverse hyperbolic sine of a complex number: z = asinh(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::asinh ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::asinAlt | PEAR Manual | Math_ComplexOp::asinReal


Math_ComplexOp::asinReal

Math_ComplexOp::asinReal

Math_ComplexOp::asinReal() – Calculates the complex inverse sine of a real number: z = asinReal(r):

Synopsis

require_once '/ComplexOp.php';

Math_Complex & Math_ComplexOp::asinReal ( float $r )

Description

This package is not documented yet.

Parameter

float $r

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::asinh | PEAR Manual | Math_ComplexOp::atan


Math_ComplexOp::atan

Math_ComplexOp::atan

Math_ComplexOp::atan() – Calculates the inverse tangent of a complex number: z = atan(c1):

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::atan ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::asinReal | PEAR Manual | Math_ComplexOp::atanh


Math_ComplexOp::atanh

Math_ComplexOp::atanh

Math_ComplexOp::atanh() – Calculates the inverse hyperbolic tangent of a complex number: z = atanh(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::atanh ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::atan | PEAR Manual | Math_ComplexOp::conjugate


Math_ComplexOp::conjugate

Math_ComplexOp::conjugate

Math_ComplexOp::conjugate() – Calculates the conjugate of a complex number: z = conj(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::conjugate ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::atanh | PEAR Manual | Math_ComplexOp::cos


Math_ComplexOp::cos

Math_ComplexOp::cos

Math_ComplexOp::cos() – Calculates the cosine of a complex number: z = cos(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::cos ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::conjugate | PEAR Manual | Math_ComplexOp::cosh


Math_ComplexOp::cosh

Math_ComplexOp::cosh

Math_ComplexOp::cosh() – Calculates the hyperbolic cosine of a complex number: z = cosh(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::cosh ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::cos | PEAR Manual | Math_ComplexOp::cot


Math_ComplexOp::cot

Math_ComplexOp::cot

Math_ComplexOp::cot() – Calculates the cotangent of a complex number: z = cot(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::cot ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::cosh | PEAR Manual | Math_ComplexOp::coth


Math_ComplexOp::coth

Math_ComplexOp::coth

Math_ComplexOp::coth() – Calculates the hyperbolic cotangent of a complex number: z = coth(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::coth ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::cot | PEAR Manual | Math_ComplexOp::createFromPolar


Math_ComplexOp::createFromPolar

Math_ComplexOp::createFromPolar

Math_ComplexOp::createFromPolar() – Converts a polar complex z = r*exp(theta*i) to z = a + b*i

Synopsis

require_once '/ComplexOp.php';

Math_Complex & Math_ComplexOp::createFromPolar ( float $r , float $theta )

Description

This package is not documented yet.

Parameter

float $r

float $theta

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::coth | PEAR Manual | Math_ComplexOp::csc


Math_ComplexOp::csc

Math_ComplexOp::csc

Math_ComplexOp::csc() – Calculates the cosecant of a complex number: z = csc(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::csc ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::createFromPolar | PEAR Manual | Math_ComplexOp::csch


Math_ComplexOp::csch

Math_ComplexOp::csch

Math_ComplexOp::csch() – Calculates the hyperbolic cosecant of a complex number: z = csch(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::csch ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::csc | PEAR Manual | Math_ComplexOp::div


Math_ComplexOp::div

Math_ComplexOp::div

Math_ComplexOp::div() – Returns the division of two complex numbers: z = c1 * c2

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::div ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::csch | PEAR Manual | Math_ComplexOp::exp


Math_ComplexOp::exp

Math_ComplexOp::exp

Math_ComplexOp::exp() – Calculates the exponential of a complex number: z = exp(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::exp ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::div | PEAR Manual | Math_ComplexOp::inverse


Math_ComplexOp::inverse

Math_ComplexOp::inverse

Math_ComplexOp::inverse() – Calculates the inverse of a complex number: z = 1/c1

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::inverse ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::exp | PEAR Manual | Math_ComplexOp::isComplex


Math_ComplexOp::isComplex

Math_ComplexOp::isComplex

Math_ComplexOp::isComplex() – Checks if a given object is an instance of PEAR::Math_Complex

Synopsis

require_once '/ComplexOp.php';

boolean Math_ComplexOp::isComplex ( mixed &$c1 )

Description

This package is not documented yet.

Parameter

mixed &$c1

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::inverse | PEAR Manual | Math_ComplexOp::log


Math_ComplexOp::log

Math_ComplexOp::log

Math_ComplexOp::log() – Calculates the logarithm (base 2) of a complex number: z = log(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::log ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::isComplex | PEAR Manual | Math_ComplexOp::log10


Math_ComplexOp::log10

Math_ComplexOp::log10

Math_ComplexOp::log10() – Calculates the logarithm (base 10) of a complex number: z = log10(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::log10 ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::log | PEAR Manual | Math_ComplexOp::logBase


Math_ComplexOp::logBase

Math_ComplexOp::logBase

Math_ComplexOp::logBase() – Returns the logarithm of base c2 of the complex number c1

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::logBase ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::log10 | PEAR Manual | Math_ComplexOp::mult


Math_ComplexOp::mult

Math_ComplexOp::mult

Math_ComplexOp::mult() – Returns the product of two complex numbers: z = c1 * c2

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::mult ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::logBase | PEAR Manual | Math_ComplexOp::multIm


Math_ComplexOp::multIm

Math_ComplexOp::multIm

Math_ComplexOp::multIm() – Returns the product of a complex number and an imaginary number if: x = b + c*i, y = a*i; then: z = x * y = multIm(x, a)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::multIm ( Math_Complex $c1 , float $im )

Description

This package is not documented yet.

Parameter

Math_Complex $c1

float $im

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::mult | PEAR Manual | Math_ComplexOp::multReal


Math_ComplexOp::multReal

Math_ComplexOp::multReal

Math_ComplexOp::multReal() – Multiplies a complex number by a real number: z = realnumber * c1

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::multReal ( Math_Complex &$c1 , float $real )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

float $real

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::multIm | PEAR Manual | Math_ComplexOp::negative


Math_ComplexOp::negative

Math_ComplexOp::negative

Math_ComplexOp::negative() – Calculates the negative of a complex number: z = -c1

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::negative ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::multReal | PEAR Manual | Math_ComplexOp::pow


Math_ComplexOp::pow

Math_ComplexOp::pow

Math_ComplexOp::pow() – Returns the complex power of two complex numbers: z = c1^c2

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::pow ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::negative | PEAR Manual | Math_ComplexOp::powReal


Math_ComplexOp::powReal

Math_ComplexOp::powReal

Math_ComplexOp::powReal() – Returns the exponentiation of a complex numbers to a real power: z = c1^(real)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::powReal ( Math_Complex $c1 , float $real )

Description

This package is not documented yet.

Parameter

Math_Complex $c1

float $real

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::pow | PEAR Manual | Math_ComplexOp::sec


Math_ComplexOp::sec

Math_ComplexOp::sec

Math_ComplexOp::sec() – Calculates the secant of a complex number: z = sec(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::sec ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::powReal | PEAR Manual | Math_ComplexOp::sech


Math_ComplexOp::sech

Math_ComplexOp::sech

Math_ComplexOp::sech() – Calculates the hyperbolic secant of a complex number: z = sech(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::sech ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sec | PEAR Manual | Math_ComplexOp::sin


Math_ComplexOp::sin

Math_ComplexOp::sin

Math_ComplexOp::sin() – Calculates the sine of a complex number: z = sin(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::sin ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sech | PEAR Manual | Math_ComplexOp::sinh


Math_ComplexOp::sinh

Math_ComplexOp::sinh

Math_ComplexOp::sinh() – Calculates the hyperbolic sine of a complex number: z = sinh(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::sinh ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sin | PEAR Manual | Math_ComplexOp::sqrt


Math_ComplexOp::sqrt

Math_ComplexOp::sqrt

Math_ComplexOp::sqrt() – Calculates the complex square root of a complex number: z = sqrt(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::sqrt ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sinh | PEAR Manual | Math_ComplexOp::sqrtReal


Math_ComplexOp::sqrtReal

Math_ComplexOp::sqrtReal

Math_ComplexOp::sqrtReal() – Calculates the complex square root of a real number: z = sqrt(realnumber)

Synopsis

require_once '/ComplexOp.php';

Math_Complex & Math_ComplexOp::sqrtReal ( float $realnum )

Description

This package is not documented yet.

Parameter

float $realnum

A float

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sqrt | PEAR Manual | Math_ComplexOp::sub


Math_ComplexOp::sub

Math_ComplexOp::sub

Math_ComplexOp::sub() – Returns the difference of two complex numbers: z = c1 - c2

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::sub ( Math_Complex &$c1 , Math_Complex &$c2 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Math_Complex &$c2

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sqrtReal | PEAR Manual | Math_ComplexOp::tan


Math_ComplexOp::tan

Math_ComplexOp::tan

Math_ComplexOp::tan() – Calculates the tangent of a complex number: z = tan(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::tan ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::sub | PEAR Manual | Math_ComplexOp::tanh


Math_ComplexOp::tanh

Math_ComplexOp::tanh

Math_ComplexOp::tanh() – Calculates the hyperbolic tangent of a complex number: z = tanh(c1)

Synopsis

require_once '/ComplexOp.php';

Math_Complex |PEAR_Error & Math_ComplexOp::tanh ( Math_Complex &$c1 )

Description

This package is not documented yet.

Parameter

Math_Complex &$c1

Return value

returns A valid Math_Complex number on success, PEAR_Error otherwise

Throws

No exceptions thrown.

Note

This function can be called statically.

Prev | Math_Complex | Next
Math_ComplexOp::tan | PEAR Manual | Math_TrigOp


Math_TrigOp

Math_TrigOp

Table of Contents
  • Math_TrigOp::acoth -- Calculates the inverse hyperbolic cotangent of the parameter
  • Math_TrigOp::acsch -- Calculates the inverse hyperbolic cosecant of the parameter
  • Math_TrigOp::asech -- Calculates the inverse hyperbolic secant of the parameter
  • Math_TrigOp::cot -- Calculates the cotangent of the parameter
  • Math_TrigOp::coth -- Calculates the hyperbolic cotangent of the parameter
  • Math_TrigOp::csc -- Calculates the cosecant of the parameter
  • Math_TrigOp::csch -- Calculates the hyperbolic cosecant of the parameter
  • Math_TrigOp::sec -- Calculates the secant of the parameter
  • Math_TrigOp::sech -- Calculates the hyperbolic secant of the parameter
  • Class Summary Math_TrigOp -- Math_TrigOp: static class implementing supplementary trigonometric functions
Prev | Math | Next
Math_ComplexOp::tanh | PEAR Manual | Math_TrigOp::acoth


Math_TrigOp::acoth

Math_TrigOp::acoth

Math_TrigOp::acoth() – Calculates the inverse hyperbolic cotangent of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::acoth ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp | PEAR Manual | Math_TrigOp::acsch


Math_TrigOp::acsch

Math_TrigOp::acsch

Math_TrigOp::acsch() – Calculates the inverse hyperbolic cosecant of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::acsch ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::acoth | PEAR Manual | Math_TrigOp::asech


Math_TrigOp::asech

Math_TrigOp::asech

Math_TrigOp::asech() – Calculates the inverse hyperbolic secant of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::asech ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::acsch | PEAR Manual | Math_TrigOp::cot


Math_TrigOp::cot

Math_TrigOp::cot

Math_TrigOp::cot() – Calculates the cotangent of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::cot ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::asech | PEAR Manual | Math_TrigOp::coth


Math_TrigOp::coth

Math_TrigOp::coth

Math_TrigOp::coth() – Calculates the hyperbolic cotangent of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::coth ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::cot | PEAR Manual | Math_TrigOp::csc


Math_TrigOp::csc

Math_TrigOp::csc

Math_TrigOp::csc() – Calculates the cosecant of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::csc ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::coth | PEAR Manual | Math_TrigOp::csch


Math_TrigOp::csch

Math_TrigOp::csch

Math_TrigOp::csch() – Calculates the hyperbolic cosecant of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::csch ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::csc | PEAR Manual | Math_TrigOp::sec


Math_TrigOp::sec

Math_TrigOp::sec

Math_TrigOp::sec() – Calculates the secant of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::sec ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::csch | PEAR Manual | Math_TrigOp::sech


Math_TrigOp::sech

Math_TrigOp::sech

Math_TrigOp::sech() – Calculates the hyperbolic secant of the parameter

Synopsis

require_once 'TrigOp.php';

mixed Math_TrigOp::sech ( float $x )

Description

This package is not documented yet.

Parameter

float $x

Return value

return A floating point on success, PEAR_Error object otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Math_TrigOp | Next
Math_TrigOp::sec | PEAR Manual | Class Summary Math_TrigOp


Class Summary Math_TrigOp

Class Summary Math_TrigOp

Class Summary Math_TrigOp – Math_TrigOp: static class implementing supplementary trigonometric functions

Math_TrigOp: static class implementing supplementary trigonometric functions

Static class implementing supplementary trigonometric functions

Class Trees for Math_TrigOp

  • Math_TrigOp

Prev | Math_TrigOp | Next
Math_TrigOp::sech | PEAR Manual | Networking


Networking

Networking

Provides Packages for network-related working

Table of Contents
  • Net_CheckIP
  • Net_DNS
  • Net_DNSBL
  • Net_Finger
  • Net_FTP
  • Net_GameServerQuery
  • Net_Geo
  • Net_GeoIP
  • Net_IPv4
  • Net_IPv6
  • Net_LDAP
  • Net_LDAP2
  • Net_MAC
  • Net_NNTP
  • Net_Ping
  • Net_POP3
  • Net_Portscan
  • Net_Server
  • Net_SmartIrc
  • Net_SMTP
  • Net_Socket
  • Net_Traceroute
  • Net_URL
  • Net_Whois
  • Net_Wifi
  • URI_Template
Prev | PEAR Packages | Next
Class Summary Math_TrigOp | PEAR Manual | Net_CheckIP


Net_CheckIP

Net_CheckIP

Package to check the correct syntax of an IPv4 address.

Table of Contents
  • Net_CheckIP::check_ip() -- Validation of IPv4 addresses
Prev | Networking | Next
Networking | PEAR Manual | Net_CheckIP::check_ip()


Net_CheckIP::check_ip()

Net_CheckIP::check_ip()

Net_CheckIP::check_ip() – Validation of IPv4 addresses

Synopsis

require_once 'Net/CheckIP.php';

boolean Net_CheckIP::check_ip ( string $ip )

Description

This function can validate if a given string has a valid IPv4 syntax.

Parameter

  • string $ip - the IP address to check

Return value

boolean - TRUE, if syntax is valid

Note

This function can be called statically.

Example

Using check_ip()

<?php
require_once "Net_CheckIP/CheckIP.php";

if (Net_CheckIP::check_ip("your_ip_goes_here")) {
    // Syntax of the IP is ok
}
?>
Prev | Net_CheckIP | Next
Net_CheckIP | PEAR Manual | Net_DNS


Net_DNS

Net_DNS

Provides methods for parsing and manipulating DNS packets as returned from DNS servers and provides communication methods for sending and receiving DNS packets.

Table of Contents
  • Introduction -- General purpose DNS querying and packet parsing
  • Class Summary Net_DNS -- DNS Packet manipulation class
  • Class Summary Net_DNS_Resolver -- Provides a resolver implementation to handle DNS queries
  • Net_DNS_Resolver::query() -- Queries a nameserver and returns a response
  • Net_DNS_Resolver::rawQuery() -- Queries a nameserver and returns a response
  • Net_DNS_Resolver::axfr() -- Performs a zone transfer from a nameserver
  • Class Summary Net_DNS_Packet -- Provides an object abstraction of a DNS packet
  • Class Summary Net_DNS_RR -- Provides resource record parsing and creation
  • Examples -- DNS Updates -- RFC 2136 DNS Updates
Prev | Networking | Next
Net_CheckIP::check_ip() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – General purpose DNS querying and packet parsing

Contributors

  • Eric Kilfoil

  • Sara Golemon

  • Thomas V.V. Cox

  • PEAR End-Users - Thanks

Description

The Net_DNS class provides DNS packet manipulation methods and the ability to send and receive packets to/from nameservers. Any type of DNS packet can be created, including RFC 2136 style DNS UPDATE packets.

The current list of supported RR types are:

  • A

  • AAAA

  • A

  • CNAME

  • HINFO

  • MX

  • NAPTR

  • NS

  • PTR

  • SOA

  • SRV

  • TSIG

  • TXT

Prev | Net_DNS | Next
Net_DNS | PEAR Manual | Class Summary Net_DNS


Class Summary Net_DNS

Class Summary Net_DNS

Class Summary Net_DNS – DNS Packet manipulation class

DNS Packet manipulation class

This class includes sub-classses that provide methods for creating, parsing, sending, and receving DNS nameserver packets.

This class is only a container class and generally should never be constructed. It contains constants defined in RFC 1035 with methods for converting between the integer and the name values of such constants.

For information on sending a basic query to a nameserver for a specific record, see Net_DNS_Resolver::query().

Prev | Net_DNS | Next
Introduction | PEAR Manual | Class Summary Net_DNS_Resolver


Class Summary Net_DNS_Resolver

Class Summary Net_DNS_Resolver

Class Summary Net_DNS_Resolver – Provides a resolver implementation to handle DNS queries

Net_DNS_Resolver

The resolver class a high level interface for communicating with DNS servers. It uses the UNIX system stub resolver configuration files (if available) to configure the resolver. The resolver can also be configured manually by overriding the system configuration. This is done by setting the appropriate values in the Net_DNS_Resolver object. See Net_DNS_Resolver::query() for more information on the resolver configuration.

Prev | Net_DNS | Next
Class Summary Net_DNS | PEAR Manual | Net_DNS_Resolver::query()


Net_DNS_Resolver::query()

Net_DNS_Resolver::query()

Net_DNS_Resolver::query() – Queries a nameserver and returns a response

Synopsis

require_once('Net/DNS.php');

Net_DNS_Packet Net_DNS_Resolver::query ( string $hostname , string $type = 'A' , string $class = 'IN' )

Description

  • hostname - The name to lookup (eg. www.php.net)

  • type - The record type to query

  • class - The zone class to query

Constructs a DNS query packet and forwards the query to a nameserver configured in the system stub resolver (ie. /etc/resolv.conf). When a response is received from the DNS server, a fully populated Net_DNS_Packet object is returned that represents the response.

The resolver object contains many properties that control that behaviour of the resolver. Some of these settings are automatically read from the system resolver configuration if available. On Linux/UNIX based systems, this includes /etc/resolv.conf as well as various environment variables. This configuration is done at the time of object instantiation and can be overridden by setting the appropriate object properties.

This function will only return a Net_DNS_Packet if the ANSWER section contains resource records. Specifically, if the ANCOUNT variable in the DNS packet header is 0, query() will return 0 (note: 0, not FALSE). If you are expecting a packet without resource records in the ANSWER section, use Net_DNS_Resolver::rawQuery(). This is useful when doing manual recursion.

For a description of the returned RR data object, see Net_DNS_RR.

Resolver Configuration Object Properties:

  • array $nameservers

    An array of nameserver IP addresses that should be queried.

  • int $port

    The port on which nameservers should be queried. The default is 53.

  • array $domain

    The domain in which the resolver client host resides.

  • array $searchlist

    An array of strings containingg domains to apply to unqualified hosts passed to the resolver.

  • int $retry

    The number of seconds between retransmission of unaswered queries

  • int $retrans

    The number of times unanswered requests should be retried

  • int $recurse

    Sets the value of the RD (recursion desired) bit in the header. If the RD bit is set to 0, the server will not perform recursion on the request.

  • int $usevc

    Whether or not to use TCP (Virtual Circuits) instead of UDP If set to 0, UDP will be used unless TCP is required. TCP is required for questions or responses greater than 512 bytes.

  • int $debug

    If set to TRUE (non-zero), debugging code will be displayed as the resolver makes the request.

Environment Variables:

  • RES_NAMESERVERS

    Space separated list of nameserver IP addresses to query

  • RES_SEARCHLIST

    Space separated list of domain names to add to unqualified search requests.

  • LOCALDOMAIN

    The name of the domain

  • RES_OPTIONS

    A space separated list of options formatted as:

    optionname:value

    If the value is ommited, the value defaults to 1 (true). [optionname] corresponds to an object property.

Example

Using Net_DNS_Resolver::query()

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();
$response = $resolver->query('example.com');
if ($response) {
  foreach ($response->answer as $rr) {
    $rr->display();
  }
}
?>

Output:

example.com.            129808  IN      A       192.0.34.166

The following example shows a DNS query for an MX record. Note that the IP address for the mail exchanger listed within the zone is returned with the response in the additional section. The second exchanger (that is not inside this zone) is not listed. To receive this address, you must perform another query specifically for the A record using the returned hostname.

Using Net_DNS_Resolver::query() to look up an MX record

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();
$response = $resolver->query('php.net', 'MX');
if ($response) {
  foreach ($response->answer as $rr) {
    $rr->display();
  }
  if (count($response->additional)) {
    foreach ($response->additional as $rr) {
      $rr->display();
    }
  }
}
?>

Output:

php.net.                86121   IN      MX      15 smtp.osuosl.org.
php.net.                86121   IN      MX      5 osu1.php.net.
osu1.php.net.           86121   IN      A       140.211.166.39

The next example shows a more complex query with debugging information enabled. Note that the usevc option is set to TRUE. This forces the resolver to use TCP instead of UDP. This can be seen in the debug output on the send_tcp() line.

Using Net_DNS_Resolver::query() with specific nameservers and options

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();
$resolver->debug = 1; // Turn on debugging output to show the query
$resolver->usevc = 1; // Force the use of TCP instead of UDP
$resolver->nameservers = array(              // Set the IP addresses
                           '198.41.0.4',     // of the nameservers
                           '192.228.79.201'  // to query.
                           );
$response = $resolver->query('example.com');
if (! $response) {
  echo "\n";
  echo "ANCOUNT is 0, therefore the query() 'failed'\n";
  echo "See Net_DNS_Resolver::rawQuery() to receive this packet\n";
}
?>

Output:

;; query(example.com, A, IN)
;; send_tcp(198.41.0.4:53)
;; sending 29 bytes
;; received 517 bytes
;; HEADER SECTION
;; id = 58298
;; qr = 1    opcode = QUERY    aa = 0    tc = 0    rd = 1
;; ra = 0    rcode  = NOERROR
;; qdcount = 1  ancount = 0  nscount = 13  arcount = 15

;; QUESTION SECTION (1 record)
;;
;example.com.   IN      A

;; ANSWER SECTION (0 records)

;; AUTHORITY SECTION (13 records)
com.            172800  IN      NS      A.GTLD-SERVERS.NET.
com.            172800  IN      NS      G.GTLD-SERVERS.NET.
com.            172800  IN      NS      H.GTLD-SERVERS.NET.
com.            172800  IN      NS      C.GTLD-SERVERS.NET.
com.            172800  IN      NS      I.GTLD-SERVERS.NET.
com.            172800  IN      NS      B.GTLD-SERVERS.NET.
com.            172800  IN      NS      D.GTLD-SERVERS.NET.
com.            172800  IN      NS      L.GTLD-SERVERS.NET.
com.            172800  IN      NS      F.GTLD-SERVERS.NET.
com.            172800  IN      NS      J.GTLD-SERVERS.NET.
com.            172800  IN      NS      K.GTLD-SERVERS.NET.
com.            172800  IN      NS      E.GTLD-SERVERS.NET.
com.            172800  IN      NS      M.GTLD-SERVERS.NET.

;; ADDITIONAL SECTION (15 records)
A.GTLD-SERVERS.NET.     172800  IN      AAAA    2001:503:a83e::2:30
A.GTLD-SERVERS.NET.     172800  IN      A       192.5.6.30
G.GTLD-SERVERS.NET.     172800  IN      A       192.42.93.30
H.GTLD-SERVERS.NET.     172800  IN      A       192.54.112.30
C.GTLD-SERVERS.NET.     172800  IN      A       192.26.92.30
I.GTLD-SERVERS.NET.     172800  IN      A       192.43.172.30
B.GTLD-SERVERS.NET.     172800  IN      AAAA    2001:503:231d::2:30
B.GTLD-SERVERS.NET.     172800  IN      A       192.33.14.30
D.GTLD-SERVERS.NET.     172800  IN      A       192.31.80.30
L.GTLD-SERVERS.NET.     172800  IN      A       192.41.162.30
F.GTLD-SERVERS.NET.     172800  IN      A       192.35.51.30
J.GTLD-SERVERS.NET.     172800  IN      A       192.48.79.30
K.GTLD-SERVERS.NET.     172800  IN      A       192.52.178.30
E.GTLD-SERVERS.NET.     172800  IN      A       192.12.94.30
M.GTLD-SERVERS.NET.     172800  IN      A       192.55.83.30

ANCOUNT is 0, therefore the query() 'failed'
See Net_DNS_Resolver::rawQuery() to receive this packet

Note

This function can not be called statically.

Prev | Net_DNS | Next
Class Summary Net_DNS_Resolver | PEAR Manual | Net_DNS_Resolver::rawQuery()


Net_DNS_Resolver::rawQuery()

Net_DNS_Resolver::rawQuery()

Net_DNS_Resolver::rawQuery() – Queries a nameserver and returns a response

Synopsis

require_once('Net/DNS.php');

Net_DNS_Packet Net_DNS_Resolver::rawQuery ( string $hostname , string $type = 'A' , string $class = 'IN' )

Description

  • hostname - The name to lookup (eg. www.php.net)

  • type - The record type to query

  • class - The zone class to query

The Net_DNS_Resolver::rawQuery() function performs a DNS query similar to the Net_DNS_Resolver::query() function; however, rawQuery() will return any response from the nameserver. This is useful when the response packet may or may not contain any resource records in the "ANSWER" section.

rawQuery() uses the same resolver configuration used by Net_DNS_Resolver::query().

For a description of the returned RR data object, see Net_DNS_RR.

Example

Using Net_DNS_Resolver::rawQuery()

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();
$response = $resolver->rawQuery('example.com');
if ($response) {
  if (count($response->answer)) {
    foreach ($response->answer as $rr) {
      $rr->display();
    }
  }
}
?>

Output:

example.com.            129808  IN      A       192.0.34.166

Note

This function can not be called statically.

Prev | Net_DNS | Next
Net_DNS_Resolver::query() | PEAR Manual | Net_DNS_Resolver::axfr()


Net_DNS_Resolver::axfr()

Net_DNS_Resolver::axfr()

Net_DNS_Resolver::axfr() – Performs a zone transfer from a nameserver

Synopsis

require_once('Net/DNS.php');

Net_DNS_Packet Net_DNS_Resolver::axfr ( string $dname , string $class = 'IN' , boolean $old = FALSE )

Description

  • dname - The domain name (zone name) to transfer

  • class - The zone class to transfer

  • old - Only used for backwards compatibility with previous version of Net_DNS

axfr() attempts a zone transfer from the nameservers
specified in the Net_DNS_Resolver->nameservers array.
Net_DNS_Resolver::axfr() uses the same
resolver configuration as the Net_DNS_Resolver::query()
method.

Most public nameservers will not allow a zone transfer by default. A zone transfer will provide a full list of DNS resource records inside of a zone file. A zone transfer will always use TCP instead of UDP queries.

For a description of the returned RR data object, see Net_DNS_RR.

Example

Failed Net_DNS_Resolver::axfr() query

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();
$resolver->debug = 1;
$response = $resolver->axfr('example.com');
print_r($response);
if (count($response) == 0) {
  echo "\n";
  echo "AXFR Failed\n";
}
?>

Output:

;; axfr_start(example.com, IN)
;; query(example.com, AXFR, IN)
;; axfr_start(192.168.0.254:53)
;; sending 29 bytes
;; read_tcp: expecting 2 bytes
;; read_tcp: received 2 bytes
;; read_tcp: expecting 29 bytes
;; read_tcp: received 29 bytes
;; received 29bytes
;; HEADER SECTION
;; id = 29190
;; qr = 1    opcode = QUERY    aa = 0    tc = 0    rd = 1
;; ra = 1    rcode  = NOTAUTH
;; qdcount = 1  ancount = 0  nscount = 0  arcount = 0

;; QUESTION SECTION (1 record)
;;
;example.com.   IN      AXFR

;; ANSWER SECTION (0 records)

;; AUTHORITY SECTION (0 records)

;; ADDITIONAL SECTION (0 records)
Array
(
)

AXFR Failed

In the following example, debugging has been turned on and the nameserver has been configured to allow zone transfers. The most important item of note in this example is the SOA record at the beginning and end of the returned records. When a name server sends a zone transfer, the first record sent is the SOA record. The zone transfer is considered complete when the name server sends the SOA record again. This behaviour can be seen in the debug output. The resulting array returned by axfr() does not return the final SOA record.

Succesful Net_DNS_Resolver::axfr() query

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();
$resolver->debug = 1;
$response = $resolver->axfr('my.example.com');
echo "\n\nThe following resource records were returned from the nameserver:\n";
if (count($response)) {
  foreach ($response as $rr) {
    $rr->display();
  }
}
?>

Output:

;; axfr_start(my.example.com, IN)
;; query(my.example.com, AXFR, IN)
;; axfr_start(192.168.0.254:53)
;; sending 32 bytes
;; read_tcp: expecting 2 bytes
;; read_tcp: received 2 bytes
;; read_tcp: expecting 262 bytes
;; read_tcp: received 262 bytes
;; received 262bytes
;; HEADER SECTION
;; id = 21220
;; qr = 1    opcode = QUERY    aa = 1    tc = 0    rd = 0
;; ra = 1    rcode  = NOERROR
;; qdcount = 1  ancount = 10  nscount = 0  arcount = 0

;; QUESTION SECTION (1 record)
;;
;my.example.com.        IN      AXFR

;; ANSWER SECTION (10 records)
my.example.com.         300     IN      SOA     ns1.my.example.com. hostmaster.my.example.com. 103 3600 1800 2592000 300
my.example.com.         300     IN      NS      ns1.my.example.com.
my.example.com.         300     IN      MX      10 mx1.my.example.com.
my.example.com.         300     IN      MX      20 mx2.my.example.com.
my.example.com.         300     IN      A       192.168.0.1
mx1.my.example.com.     300     IN      A       192.168.0.2
mx2.my.example.com.     300     IN      A       192.168.0.3
server.my.example.com.  300     IN      CNAME   www.my.example.com.
www.my.example.com.     300     IN      A       192.168.0.1
my.example.com.         300     IN      SOA     ns1.my.example.com. hostmaster.my.example.com. 103 3600 1800 2592000 300

;; AUTHORITY SECTION (0 records)

;; ADDITIONAL SECTION (0 records)

The following resource records were returned from the nameserver:
my.example.com.         300     IN      SOA     ns1.my.example.com. hostmaster.my.example.com. 103 3600 1800 2592000 300
my.example.com.         300     IN      NS      ns1.my.example.com.
my.example.com.         300     IN      MX      10 mx1.my.example.com.
my.example.com.         300     IN      MX      20 mx2.my.example.com.
my.example.com.         300     IN      A       192.168.0.1
mx1.my.example.com.     300     IN      A       192.168.0.2
mx2.my.example.com.     300     IN      A       192.168.0.3
server.my.example.com.  300     IN      CNAME   www.my.example.com.
www.my.example.com.     300     IN      A       192.168.0.1

Note

This function can not be called statically.

Prev | Net_DNS | Next
Net_DNS_Resolver::rawQuery() | PEAR Manual | Class Summary Net_DNS_Packet


Class Summary Net_DNS_Packet

Class Summary Net_DNS_Packet

Class Summary Net_DNS_Packet – Provides an object abstraction of a DNS packet

Net_DNS_Packet

The Net_DNS_Packet class provides methods for creating a DNS packet suitable for sending to a nameserver. It also provides the methods of parsing a response from a nameserver into a Net_DNS_Packet object.

A standard DNS packet is made up of five main pieces:

  • Header

  • Question Section

  • Answer Section

  • Authority Section

  • Additional Section

Net_DNS defines the DNS packet header as a Net_DNS_Header object. Net_DNS_Question defines the question section of a packet object. The remaining three sections should be arrays of Net_DNS_RR objects.

Prev | Net_DNS | Next
Net_DNS_Resolver::axfr() | PEAR Manual | Class Summary Net_DNS_RR


Class Summary Net_DNS_RR

Class Summary Net_DNS_RR

Class Summary Net_DNS_RR – Provides resource record parsing and creation

Net_DNS_RR

The Net_DNS_RR class provides methods of parsing resource records returned by a nameserver, creation of resource record objects to be sent to a nameserver, and the ability to access each component of an RR as an object property.

Each resource record object MUST contain the following properties:

  • name - The DNS name of the RR

  • type - The RR type

  • class - The RR class (normally IN)

  • ttl - The RR time to live

  • rdlength - The amount of data (in bytes) of the rdata section

  • rdata - The data (uncompressed) of the right hand side of the RR

If type is a supported RR type, it will automatically be decompressed and/or decoded into its appropriate property values. The values inside of an RR object will vary based on the type of RR.

Supported RR types:

  • A

    • string address - IPv4 style address

  • AAAA

    • string address - IPv6 style address

  • CNAME

    • string cname - The canonical name of the queried host

  • HINFO

    • string cpu - The host CPU type

    • string os - Type host operating system

  • MX

    • integer preference - The MX preference (lower takes priority

    • string exchange - The name of the mail exchange host

  • NAPTR

    • unknown order - unknown

    • unknown preference - unknown

    • unknown flags - unknown

    • unknown services - unknown

    • unknown regex - unknown

    • unknown replacement - unknown

  • NS

    • string nsdname - The name of the NS record nameserver

  • PTR

    • string ptrdname - The name for the queried IP address

  • SOA

    • string mname - Master nameserver hostname as specified in the SOA record - not neccessarily accurate

    • string rname - Email address of the person responsible for the zone - not neccessarily accurate

    • string serial - The serial number (version number) of the retrieved zone

    • string refresh - The length of time before the zone should be refresed

    • string retry - The length of time between retries for slave servers to refresh the zone

    • string expire - The length of time before slave servers should consider the data invalid without refreshing the zone data.

    • string minimum - The default TTL for RRs inside of the zone that are not otherwise specified.

  • SRV

    • unknown preference - unknown

    • unknown weight - unknown

    • unknown port - unknown

    • unknown target - unknown

  • TSIG

    • integer time_signed - The time the signature has was created

    • integer fudge - The time offset that is acceptable between the client and the server

    • integer mac_size - The size of the following signature data

    • string/binary mac - The data containing the has sent by the client/server

    • integer original_id - The ID sent to or received from the server identifying this query.

    • integer error - The value of the error calculating or verifying the signature.

    • integer other_len - The amount of data (in bytes) additional to the signature

    • string other_data - Additional data required by the nameserver for the signature.

    • string key - The key shared by the client and the server to validate authorization.

  • TXT

    • string text - The text defined in the record

Prev | Net_DNS | Next
Class Summary Net_DNS_Packet | PEAR Manual | Examples -- DNS Updates


Examples -- DNS Updates

Examples -- DNS Updates

Examples -- DNS Updates – RFC 2136 DNS Updates

RFC 2136 DNS Updates

By constructing a specially formatted DNS packet and sending it to a nameserver, a dynamic DNS update can be performed very easily. RFC 2136 defines some variations of a DNS packet that are used by Net_DNS to request an update. The nameserver must first be configured to accept DNS updates, a key must be established between the client and server, and most importantly, the PHP mhash extension must be included for processing the MD5 digest of the key.

The format of the DNS packet is very specific and requires in-depth knowledge of how DNS updates work. Net_DNS currently does not support any abstraction of these specially formatted packets. Packets must currently be crafted and sent manually. The full formatting of update packets can be found in RFC 2136.

For a complete listing of all of the fields that are available for DNS updates, please review RFC2136 (http://www.ietf.org/rfc/rfc2136.txt). The following examples show the simplest forms of a DNS update.

Sending a dynamic DNS update packet to a nameserver

<?php
require_once 'Net/DNS.php';

$resolver = new Net_DNS_Resolver();

// We should only send the request to the master server
// accepting DNS updates for the zone.
$resolver->nameservers = array('192.168.0.254');

// We must manually construct the DNS packet for a DNS update
// First we must instantiate the packet object
$packet = new Net_DNS_Packet();

// Create the header for the update packet.  Most of the defaults are
// acceptable, but we must set the header OPCODE to "UPDATE"
$packet->header = new Net_DNS_Header();
$packet->header->id = $resolver->nextid();
$packet->header->qr = 0;
$packet->header->opcode = "UPDATE";

// As specified in RFC2136, the question section becomes the "ZONE" section.
// This specifies the zone for which we are requesting a change.  This
// reflects the zone configuration as specified in the nameserver
// configuration.
$packet->question[0] = new Net_DNS_Question('example.com', "SOA", "IN");

// The "ANSWER" section of the packet becomes the "PREREQUISITE" section of
// the packet. Section 2.4 of RFC2136 defines the possible values for this
// section.  As show below, without any prerequisites the nameserver will
// attempt to perform the update unconditionally.
$packet->answer = array();

// The AUTHORITY section becomes the "UPDATE" section of the DNS packet.  The
// UPDATE section is a collection of resource record updates that should be
// modified in one form or another.  RRs can be deleted or added based on the
// values passed in the RR object.  These values are specified in RFC2136 but
// are summarized here:
//
// Adding an RR
// A complete RR object with a non-zero TTL is considered an addition.
//
// Deleting an RR
// A complete RR object with a zero TTL is considered an deletion. An RR that
// matches (exactly) with all values except for the TTL will be removed.
//
// Deleting an RRset
// A complete RR object with a zero TTL and a type of ANY is considered a
// deletion of all RRs with the specified name and type. An RR that matches
// (exactly) with all values except for the TTL and the TYPE will be removed.
//
// Deleting all RRsets for a name
// A complete RR object with a zero TTL, a type of ANY, and a class of ANY is
// considered a deletion of all RRs with the specified name. Any RR that
// matches the name section of the query will be removed.
//
// The following specification will delete the RR that has a name of
// "example.com", class of "IN", type of "A", and an address of
// "192.0.34.166".
$rrDelete =& Net_DNS_RR::factory("example.com. 0 IN A 192.0.34.166");
//
// The following specification will add an RR that has a name of example.com,
// a TTL of 1 hour, a class of "IN", type of "A", and an address of
// "192.0.34.155").  Note that the only difference between this RR and the
// previous RR is the value of the TTL.
$rrAdd =& Net_DNS_RR::factory("example.com. 3600 IN A 192.0.34.166");
//
// The RR modifications are added to the authority (UPDATE) section of the DNS
// packet.
$packet->authority[0] = $rrDelete;
$packet->authority[1] = $rrAdd;
//
// The signature must be present in any packet sent to a nameserver that
// requires authentication.  The TSIG RR is added to the additional section of
// the DNS packet.
$tsig =& Net_DNS_RR::factory("keyname.as.specified.in.server. TSIG ThisIsMyKey");
$packet->additional = array($tsig);
// Net_DNS does not automatically calculate the number of records stored in
// each section.  This calculation must be done manually.
$packet->header->qdcount = count($packet->question);
$packet->header->ancount = count($packet->answer);
$packet->header->nscount = count($packet->authority);
$packet->header->arcount = count($packet->additional);
//
// After creating your packet, you must send it to the name server for
// processing.  DNS updates must use the send_tcp() method:
$response = $resolver->send_tcp($packet, $packet->data());
//
// The response from the server will vary.  If the update was successfuly, the
// server will have a response code of "NOERROR".  Any other error types will
// be reported in the response packet's header "rcode" variable.
if ($response->header->rcode != "NOERROR") {
  return($response->header->rcode);
}

?>
Prev | Net_DNS | Next
Class Summary Net_DNS_RR | PEAR Manual | Net_DNSBL


Net_DNSBL

Net_DNSBL

Net_DNSBL checks if a given Host or URL is listed on an DNS-based Blackhole List (DNSBL, Real-time Blackhole List or RBL) or Spam URI Realtime Blocklist (SURBL)

Table of Contents
  • Introduction -- Introduction to Net_DNSBL
Prev | Networking | Next
Examples -- DNS Updates | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Net_DNSBL

Description

PEAR::Net_DNSBL provides an easy way to check if a given Host or URL is listed on an DNS-based Blackhole List (DNSBL, Real-time Blackhole List or RBL) or Spam URI Realtime Blocklist (SURBL).

Please not that this currently only works with IPv4 IPs.

Usage

Let's start with a simple example to check if the remote host is listed in two blacklists:

<?php
require_once 'Net/DNSBL.php';
$dnsbl = new Net_DNSBL();
$remoteIP = $_SERVER['REMOTE_ADDR'];
$remoteIP = '81.70.69.193';
$dnsbl->setBlacklists(array('sbl-xbl.spamhaus.org', 'bl.spamcop.net'));
if ($dnsbl->isListed($remoteIP)) {
    // do something
}
?>

This example shows how to check if an URL is listed in a SURBL:

<?php
require_once 'Net/DNSBL/SURBL.php';
$surbl = new Net_DNSBL_SURBL();
if ($surbl->isListed('http://test.multi.surbl.org/')) {
    // do something
}
?>

An example how to extract URLS from a text can be found on http://www.phpfreaks.com/quickcode/Extract_All_URLs_on_a_Page/15.php and be used this way:

<?php
foreach ($extracted_urls as $surbl_check_url) {
    if ($surbl->isListed($surbl_check_url)) {
        // do something
        break;
    }
}
?>

Let's get some details, if our host is listed:

<?php
require_once 'Net/DNSBL.php';
$dnsbl = new Net_DNSBL();
$dnsbl->setBlacklists(array('sbl-xbl.spamhaus.org', 'bl.spamcop.net'));
if ($dnsbl->isListed($_SERVER['REMOTE_ADDR'])) {
   var_dump($dnsbl->getDetails($_SERVER['REMOTE_ADDR']));
   var_dump($dnsbl->getTxt($_SERVER['REMOTE_ADDR']));
   var_dump($dnsbl->getListingBl($_SERVER['REMOTE_ADDR']));
   var_dump($dnsbl->getListingRecord($_SERVER['REMOTE_ADDR']);
}
?>
Prev | Net_DNSBL | Next
Net_DNSBL | PEAR Manual | Net_Finger


Net_Finger

Net_Finger

Finger is a service providing information about a user of a server. The finger-protocol is deactivated on the most Internet servers due to security reasons. So it makes especially sense for intranets and local host administration.

The output of the finger command depends on the system and less standarized, because the output should be easy to read for humans and not for machines.

Table of Contents
  • Net_Finger::query() -- does a finger query
Prev | Networking | Next
Introduction | PEAR Manual | Net_Finger::query()


Net_Finger::query()

Net_Finger::query()

Net_Finger::query() – does a finger query

Synopsis

require_once 'Net/Finger.php';

string Net_Finger::query ( string $server , string $query )

Description

Execute a finger query on a server

Parameter

  • string $server - The name of the server or the IP-adress

  • string $query - The finger object to look up

Return value

string - the data from the finger request.

Throws

The returned PEAR_Error object in case of an error is unspecific, so you can ignore the error code and/or message. The reason for a failure could be a failed connection to the server or the server did not run a finger service.

Note: You will not get a PEAR_Error, if the query fails due to a not existing finger object. This can be only done by checking the data returned by query().

Note

This function can be called statically.

Example

Using query()

<?php

$server = "localhost" ; // or IP adress to use
$query  = "ralph" ;     // Username to look up

$data = Net_Finger::query( $server, $query) ;
echo $data ;

?>
Prev | Net_Finger | Next
Net_Finger | PEAR Manual | Net_FTP


Net_FTP

Net_FTP

Net_FTP provides comfortable communication with FTP-Servers. It mainly provides an OO wrapper to PHP's integrated FTP functions, adding some missing features like recursive up- and downloading of complete folders, as well as deleting. The options for generating directory listings were also extended to feature well structured listing of directories and/or files.

Table of Contents
  • Constants -- predefined constants
  • Net_FTP::Net_FTP() -- constructor
  • Net_FTP::connect() -- connects to a given FTP server
  • Net_FTP::disconnect() -- disconnects from the FTP server
  • Net_FTP::login() -- logs into the FTP server you are connected to
  • Net_FTP::cd() -- changes the directory on the server.
  • Net_FTP::pwd() -- returns the directory on the server you are currently in.
  • Net_FTP::mkdir() -- creates a new directory.
  • Net_FTP::execute() -- executes a command on the server.
  • Net_FTP::mdtm() -- returns the last modification date of a file.
  • Net_FTP::size() -- returns the size in bytes of a file.
  • Net_FTP::ls() -- returns the listing of a directory in a specified way.
  • Net_FTP::rm() -- deletes a file or directory.
  • Net_FTP::get() -- download a file to the computer your script runs on.
  • Net_FTP::put() -- upload a file to the FTP server.
  • Net_FTP::getRecursive() -- download a whole directory to the computer your script runs on.
  • Net_FTP::putRecursive() -- upload a whole directory to the FTP server.
  • Net_FTP::checkFileExtension() -- check extensions.ini for the transfermode of a specific file.
Prev | Networking | Next
Net_Finger::query() | PEAR Manual | Constants


Constants

Constants

Constants – predefined constants

NET_FTP_FILES_ONLY

Makes Net_FTP::ls() return a structures array of files (no directories) in a directory.

NET_FTP_DIRS_ONLY

Makes Net_FTP::ls() return a structures array of directories (no files) in a directory.

NET_FTP_DIRS_FILES

Makes Net_FTP::ls() return a structures array of directories and files in a directory.

NET_FTP_RAWLIST

Makes Net_FTP::ls() return an unstructred array as returned by the PHP function ftp_raw_list().

Prev | Net_FTP | Next
Net_FTP | PEAR Manual | Net_FTP::Net_FTP()


Net_FTP::Net_FTP()

Net_FTP::Net_FTP()

Net_FTP::Net_FTP() – constructor

Synopsis

require_once 'Net/FTP.php';

object Net_FTP::Net_FTP ( string $host = null , int $port = null )

Description

Create a new object for communication with FTP servers.

Parameter

  • string $host = null - The host to connect to ( either an IP address or a domain name).

  • int $port = null - The port to connect to on the server.

Return value

object - the new Net_FTP object.

Note

This function can not be called statically.

Example

Using Net_FTP()

<?php

  require_once 'Net/FTP.php';

  $test = new Net_FTP('ftp.mydomain.com', 21);

?>
Prev | Net_FTP | Next
Constants | PEAR Manual | Net_FTP::connect()


Net_FTP::connect()

Net_FTP::connect()

Net_FTP::connect() – connects to a given FTP server

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::connect ( string $host = null , int $port = null )

Description

Create a new object for communication with FTP servers.

Parameter

  • string $host = null - The host to connect to ( either an IP address or a domain name). This parameter can be left out, if it has been set in the constructor or manually!

  • int $port = null - The port to connect to on the server. This parameter can be left out, if it has been set in the constructor or manually!

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Connection failed" will be returned if the connection fails.

Note

This function can not be called statically.

Example

Using connect()

<?php

    $test->connect('192.168.0.1', 21);

?>
Prev | Net_FTP | Next
Net_FTP::Net_FTP() | PEAR Manual | Net_FTP::disconnect()


Net_FTP::disconnect()

Net_FTP::disconnect()

Net_FTP::disconnect() – disconnects from the FTP server

Synopsis

require_once 'Net/FTP.php';

void Net_FTP::disconnect ( )

Description

Disconnect from the FTP server you're connected to.

Return value

void

Note

This function can not be called statically.

Example

Using disconnect()

<?php

    $test->disconnect();

?>
Prev | Net_FTP | Next
Net_FTP::connect() | PEAR Manual | Net_FTP::login()


Net_FTP::login()

Net_FTP::login()

Net_FTP::login() – logs into the FTP server you are connected to

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::login ( string $username = null , int $password = null )

Description

Does the login on the FTP server you are connected to. for that you first have to connect to a FTP server before logging in. Username and Password can either be set by the parameters or manually before (using the set-methods).

Parameter

  • string $username = null - The username to be used for login to. This parameter can be left out, if it has been set manually!

  • int $password = null - The password to use for login. This parameter can be left out, if it has been set manually!

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Login failed" will be returned if the login fails.

Note

This function can not be called statically.

Example

Using login()

<?php

    $test->login('myuser', 'mypass');

?>
Prev | Net_FTP | Next
Net_FTP::disconnect() | PEAR Manual | Net_FTP::cd()


Net_FTP::cd()

Net_FTP::cd()

Net_FTP::cd() – changes the directory on the server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::cd ( string $directory )

Description

Changes the directory on the FTP server you are logged in. The parameter can either be an absolute path (e.g. '/home/mydir') or a relative one (e.g. 'mydir').

Parameter

  • string $directory - The directory you want to change to. This can either be an absolute path (e.g. '/home/mydir') or a relative one (e.g. 'mydir').

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Directory change failed" will be returned if the operation fails.

Note

This function can not be called statically.

Example

Using cd()

<?php

    $test->cd('../mydir');

?>
Prev | Net_FTP | Next
Net_FTP::login() | PEAR Manual | Net_FTP::pwd()


Net_FTP::pwd()

Net_FTP::pwd()

Net_FTP::pwd() – returns the directory on the server you are currently in.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::pwd ( )

Description

Returns the directory currently selected on the server.

Return value

mixed - path (absolute) as string on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Could not determine the actual path" will be returned if the operation fails.

Note

This function can not be called statically.

Example

Using pwd()

<?php

  echo $test->pwd();

?>
Prev | Net_FTP | Next
Net_FTP::cd() | PEAR Manual | Net_FTP::mkdir()


Net_FTP::mkdir()

Net_FTP::mkdir()

Net_FTP::mkdir() – creates a new directory.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::mkdir ( string $directory , bool $recursive = false )

Description

Creates a new directory on the FTP server. You can give this function either a relative or an absolute path as the first parameter. The second (optional) parameter lets you create directories recursively (meaning you can create './my/new/dir' even if '/my' doesn't exist. All 3 directories would be created ).

Parameter

  • string $directory - The directory you want to create. This can either be an absolute path (e.g. '/home/mydir') or a relative one (e.g. 'mydir').

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is specific. There is only one errornumber which may occur. The message given by this error will contain the directory where the error occurred in "Creation of '$dir' failed". operation fails.

Note

This function can not be called statically.

Example

Using mkdir()

<?php

  $test->mkdir('../mydir');

?>
Prev | Net_FTP | Next
Net_FTP::pwd() | PEAR Manual | Net_FTP::execute()


Net_FTP::execute()

Net_FTP::execute()

Net_FTP::execute() – executes a command on the server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::execute ( string $command )

Description

Executes a given command on the server (the SITE EXEC command is added by the method).

Parameter

  • string $command - The command to be executed (without SITE EXEC).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is specific. There is only one errornumber which may occur. The message given by this error will contain the directory where the error occurred in "Execution of command '$command' failed". operation fails.

Note

This function can not be called statically.

Example

Using execute()

<?php

    $test->execute($myCommand);

?>
Prev | Net_FTP | Next
Net_FTP::mkdir() | PEAR Manual | Net_FTP::mdtm()


Net_FTP::mdtm()

Net_FTP::mdtm()

Net_FTP::mdtm() – returns the last modification date of a file.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::mdtm ( string $file , string $format = null )

Description

gives you the last modification-date of a file either as a unix timestamp or in a formated date.

Parameter

  • string $file - The file to check.

    string $format - A date()-function styled format-string.

Return value

mixed - the last modification date on success, otherwise PEAR::Error.

Throws

Several errors may be returned by mdtm. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Filename '$file' seems to be a directory. | The filename you gave the method does not reference a regular-file but a directory. | Specify a correct filenamepath (eg. /my/file/path/foo.html, ../foo.html).
Could not get last-modification-date of '$file'. The last-modification date could not be determined by PHP. Reasons for this may be that your FTP-server does not support the used command or that you gave the function a non existent file as reference.

  • check the given file for existence

  • contact the FTP server's admin
Date-format failed on timestamp '$res'. | The given format-string was not well formated. | Check the documentation of the PHP function date().

Note

This function can not be called statically.

Example

Using mdtm()

<?php

  var_dump($test->mdtm('/foo/bar'));

  // returns the last modification time in german timeformat
  var_dump($test->mdtm('/foo/bar', 'd.m.Y, H:i'));

?>
Prev | Net_FTP | Next
Net_FTP::execute() | PEAR Manual | Net_FTP::size()


Net_FTP::size()

Net_FTP::size()

Net_FTP::size() – returns the size in bytes of a file.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::size ( string $file )

Description

gives you the size of a file bytes.

Parameter

  • string $file - The file to check.

Return value

mixed - the size of the given file on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Connection failed" will be returned if the connection fails.

Note

This function can not be called statically.

Example

Using size()

<?php

    var_dump($test->size('/foo/bar'));

?>
Prev | Net_FTP | Next
Net_FTP::mdtm() | PEAR Manual | Net_FTP::ls()


Net_FTP::ls()

Net_FTP::ls()

Net_FTP::ls() – returns the listing of a directory in a specified way.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::ls ( string $dir = null , string $mode = NET_FTP_DIRS_FILES )

Description

this function gives you a listing of either the files / directories / both or an unformated array (like the PHP function ftp_rawlist()).

Parameter

  • string $dir = null - The directory to list. You can either use a relative or an absolute path. This optional parameter will be set to the current path.

  • int $mode = - A constant representing the nodes list (directories, files, both or a ram directory listing). This parameter is determined by the constants (see: Constants). This parameter is optional and will be set for listing directories and files structured in an array.

Return value

mixed - a directory listing in the form you determine on success, otherwise PEAR::Error.

Throws

Several errors may be returned by ls. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Raw directory-list in wrong format. | The format given by the server on PHP function ftp_rawlist()was wrong. Check if the directory you wanted to be listed is correct and you have access to listing it. | Specify a correct directory path (eg. /my/file/path/, ../) and check (maybe change) the rights on it.
Could not get last-modification-date of '$file'. The last-modification date could not be determined by PHP. Reasons for this might be that your FTP-server does not support the used command or that you gave the function a non existent file as reference.

  • check the given file for existence

  • contact the FTP server's admin
Date-format failed on timestamp '$res'. | The given format-string was not well formated. | Check the documentation of the PHP function date().

Note

This function can not be called statically.

Example

Using ls()

<?php

  var_dump($test->ls('/foo/bar'));

?>
Prev | Net_FTP | Next
Net_FTP::size() | PEAR Manual | Net_FTP::rm()


Net_FTP::rm()

Net_FTP::rm()

Net_FTP::rm() – deletes a file or directory.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::rm ( string $path = null , string $recursive = false )

Description

This method deletes a file or a directory.

Parameter

  • string $path = null - The file or directory to delete. In case you set the second parameter to true, directories will be deleted even if not empty. All files and directories inside will be deleted.

  • $recursive = false - This parameter determines, whether a directory is deleted only if it's empty (standard) or if all included files and directories will be deleted with it ($recursive = true).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by rm. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Could not delete file '$file'. | The file named $file (complete path) could not be deleted. | Either the file does not exist or you do not have the permission to delete it. So check if the file exists and you have permissions on it.
Directory name '$dir' is invalid, has to end with '/' | You entered a directory for deletion ($recursive = true) without ending '/'. | Correct your parameter.
Could not delete directory '$dir'. | The directory $dir could not be deleted. | Maybe the directory is not empty ($recursive = false) or you do not have the permission to delete the directory.

Note

This function can not be called statically.

Example

Using rm()

<?php

    var_dump($test->rm('/foo/bar/', true));

?>
Prev | Net_FTP | Next
Net_FTP::ls() | PEAR Manual | Net_FTP::get()


Net_FTP::get()

Net_FTP::get()

Net_FTP::get() – download a file to the computer your script runs on.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::get ( string $remote_file , string $local_file , bool $overwrite = false , int $mode = null )

Description

This downloads a file from the FTP server to the computer your script runs on.

Parameter

  • string $remote_file - The file you'd like to download. This could either be an absolute or relative path to a file (not a directory! see: Net_FTP::getRecursive()).

  • string $local_file - The destination you'd like to download the file to (including filename, not directory!). You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)

  • bool $overwrite = false - Whether to overwrite the local file if it exists, or not. if not set the file will not be overwritten.

  • int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. if not specified, the class will try to determine the mode from the file extension (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by get. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Local file '$local_file' exists and may not be overwriten. | The local file you specified exists and you did not specify to overwrite it. | Set parameter $overwrite = true.
Local file '$file' is not writeable. Can not overwrite. | You specified to overwrite the localfile. This did not work. | Maybe you don't have the permission to overwrite the file. Check the filepermissions.
File '$remote_file' could not be downloaded to '$local_file'. | The download of the remote file failed. | This may have several reasons: Maybe the remote file does not exist or the local directory you wanted to download to does not exist or is not writeable.

Note

This function can not be called statically.

Example

Using get()

<?php

    var_dump($test->get('foo/bar.zip', '/tmp/downloaded.zip', true, FTP_BINARY));

?>
Prev | Net_FTP | Next
Net_FTP::rm() | PEAR Manual | Net_FTP::put()


Net_FTP::put()

Net_FTP::put()

Net_FTP::put() – upload a file to the FTP server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::put ( string $local_file , string $remote_file , bool $overwrite = false , int $mode = null )

Description

This uploads a file to the FTP server from the computer your script runs on.

Parameter

  • string $local_file - The source file you'd like to upload. You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)

  • string $remote_file - The path (including filename) you'd like to upload to. This could either be an absolute or relative path to a file (not a directory! see: Net_FTP::putRecursive()).

  • bool $overwrite = false - Whether to overwrite the remote file, if it exists or not. If not set the file will not be overwritten.

  • int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. If not specified, the class will try to determine the mode from the file extension (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by put. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Local file '$local_file' does not exist. | The local file you specified does not exist. | Correct the local file path.
Remote file '$remote_file' exists and may not be overwriten. | The specified remote file exists but may not be overwritten. | Maybe you don't have the permission to overwrite the file. Check the filepermissions.
File '$local_file' could not be uploaded to '$remote_file'. | The upload of the local file failed. | This may have several reasons: Maybe the local file does not exist or the remote directory you wanted to upload to does not exist or is not writeable.

Note

This function can not be called statically.

Example

Using put()

<?php

  var_dump($test->put('/tmp/downloaded.zip', 'foo/bar.zip', true, FTP_BINARY));

?>
Prev | Net_FTP | Next
Net_FTP::get() | PEAR Manual | Net_FTP::getRecursive()


Net_FTP::getRecursive()

Net_FTP::getRecursive()

Net_FTP::getRecursive() – download a whole directory to the computer your script runs on.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::getRecursive ( string $remote_path , string $local_path , bool $overwrite = false , int $mode = null )

Description

This downloads a whole directory from the FTP server to the computer your script runs on.

Parameter

  • string $remote_path - The directory you'd like to download. This could either be an absolute or relative path to a directory (path has to end with '/').

  • string $local_path - The destination you'd like to download the directory to. You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)

  • bool $overwrite = false - Whether to overwrite the local files if they exist, or not. if not set the directory will not be overwritten.

  • int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. if not specified, the class will try to determine the mode from the file extensions (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by getRecursive. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Given remote-path '$remote_path' seems not to be a directory. | The path you specified on the FTP sever seems not to be a valid directory node. | Maybe your path does not end with '/' or the directory does not exist.
Given local-path '$local_path' seems not to be a directory. | The path you specified on the local host seems not to be a valid directory node. | Maybe your path does not end with '/' or the directory does not exist.
Could not create dir '$local_path'. | The given directory could not be created. | Check your permissions on the source-directory.
Could not create dir '$local_path'. | The given directory could not be created. | Check your permissions on the source-directory.

Note

This function can not be called statically.

Example

Using getRecursive()

<?php

    var_dump($test->getRecursive('foo/', '/tmp/foo/', true));

?>
Prev | Net_FTP | Next
Net_FTP::put() | PEAR Manual | Net_FTP::putRecursive()


Net_FTP::putRecursive()

Net_FTP::putRecursive()

Net_FTP::putRecursive() – upload a whole directory to the FTP server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::putrecursive ( string $local_path , string $remote_path , bool $overwrite = false , int $mode = null )

Description

This uploads a whole directory to the FTP server from the computer your script runs on.

Parameter

  • string $local_path - The source directory you'd like to upload. You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)

  • string $remote_path - The path you'd like to upload to. This could either be an absolute or relative path to a directory.

  • bool $overwrite = false - Whether to overwrite the remote directory if it exists, or not. If not set the directory will not be overwritten.

  • int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. If not specified, the class will try to determine the mode from the file extensions (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by putRecursive. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message | Description | Solution
Given local-path '$local_path' seems not to be a directory. | The local path you have specified does not seem to be a directory. | Correct the local directory path. (Does it end with '/'?)
Given remote-path '$remote_path' seems not to be a directory. | The remote path you have specified does not seem to be a directory. | Correct the local directory path. (Does it end with '/'?)

Note

This function can not be called statically.

Example

Using putRecursive()

<?php

  var_dump($test->putRecursive('/tmp/foo/', 'foo/', true));

?>
Prev | Net_FTP | Next
Net_FTP::getRecursive() | PEAR Manual | Net_FTP::checkFileExtension()


Net_FTP::checkFileExtension()

Net_FTP::checkFileExtension()

Net_FTP::checkFileExtension() – check extensions.ini for the transfermode of a specific file.

Synopsis

require_once 'Net/FTP.php';

integer Net_FTP::checkfileextension ( string $filename )

Description

This method checks a given filename for its proper transfermode (using extensions.ini). If the file extension can not be found, the class falls back to the standard transfer mode (attribute).

Parameter

  • string $filename - The filename to check extension for.

Return value

int - either FTP_ASCII or FTP_BINARY.

Throws

No errors. Always a filetransfermode should be returned.

Note

This function can not be called statically.

Example

Using checkFileExtension()

<?php

    var_dump($test->checkfileextension('foo/bar.zip'));

?>
Prev | Net_FTP | Next
Net_FTP::putRecursive() | PEAR Manual | Net_GameServerQuery


Net_GameServerQuery

Net_GameServerQuery

An object for querying game servers and returning normalised output

Table of Contents
  • Introduction -- Provides a common API to query game servers
Prev | Networking | Next
Net_FTP::checkFileExtension() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Provides a common API to query game servers

Net_GameServerQuery Description

Net_GameServerQuery provides an common API to query game servers.

The full online documentation is available here

Prev | Net_GameServerQuery | Next
Net_GameServerQuery | PEAR Manual | Net_Geo


Net_Geo

Net_Geo

Package for polling Netgeo service retrieving the geographical location of IPs or addresses.

Table of Contents
  • Net_Geo - Example -- tracking down the remote client IP
  • Net_Geo::Net_Geo() -- constructor
  • Net_Geo::getRecord() -- get geographical information about IP
Prev | Networking | Next
Introduction | PEAR Manual | Net_Geo - Example


Net_Geo - Example

Net_Geo - Example

Net_Geo - Example – tracking down the remote client IP

Example

<?php

require_once('Net/Geo.php');

// new Net_Geo object
$net_geo = new Net_Geo();

// fetch the client's IP
$ip = $_SERVER['REMOTE_ADDR'];

// fetch information array from net_geo
$results = $net_geo->getRecord($ip);

// output
echo "Single IP results:<br />";
echo "<pre>";
print_r($results);
echo "</pre>";

// example array of multiple IPs
$arr_ips = array
(
  gethostbyname("www.google.com"),
  gethostbyname("www.heise.de"),
  gethostbyname("www.college.ch")
);

// fetch information array from net_geo
$results = $net_geo->getRecord($arr_ips);

// output
echo "Multiple IP results:<br />";
echo "<pre>";
print_r($results);
echo "</pre>";

?>
Prev | Net_Geo | Next
Net_Geo | PEAR Manual | Net_Geo::Net_Geo()


Net_Geo::Net_Geo()

Net_Geo::Net_Geo()

Net_Geo::Net_Geo() – constructor

Synopsis

require_once('Net/Geo.php');

 bool Net_Geo() (
 string $applicationName = ''
  , string $alternateServerUrl = ''
)

Description

Create a new object for IP-based geographical information retrieval.

Parameter

  • string $applicationName - Optional application name to use in UserAgent when polling Netgeo

  • string $alternateServerUrl - URL to Netgeo service script, will be set to "http://netgeo.caida.org/perl/netgeo.cgi" unless changed

Return value

boolean - Will always return true

Note

This function can not be called statically.

Prev | Net_Geo | Next
Net_Geo - Example | PEAR Manual | Net_Geo::getRecord()


Net_Geo::getRecord()

Net_Geo::getRecord()

Net_Geo::getRecord() – get geographical information about IP

Synopsis

require_once('Net/Geo.php');

array getRecord() ( mixed $target )

Description

Get geographical information about a list of targets or a single target. Error messages or "OK" are written to element STATUS of the returned array.

Parameter

  • mixed $target - A single IP or an array of IPs.

Return value

array - Informative array about geographical location of target(s)

Throws

STATUS Error Codes
Error code | Error message | Reason | Solution
string "OK" | "No error occured." | Target was resolved properly. | NULL
const INPUT_ERROR | "User input is unusable target " | The target given cannot be used. | Check target parameter: A string with a single domain or IP, or a one-dimensional array with domain or IP in every element
const NETGEO_HTTP_ERROR | "Netgeo unreachable" | A connection to the Netgeo service could not be established. | Check http://netgeo.caida.org/perl/netgeo.cgi (the default server URL used). If the script moved, use the parameter $alternateServerUrl in Net_Geo().

Note

This function can not be called statically.

Prev | Net_Geo | Next
Net_Geo::Net_Geo() | PEAR Manual | Net_GeoIP


Net_GeoIP

Net_GeoIP

Library to perform geo-location lookups of IP addresses.

This package is built on top of MaxMind's GeoIP databases to accurately determine the geographic location of an IP address. MaxMind offers both free and non-free database. Please refer to their website for specific instructures on obtaining both database types.

Table of Contents
  • Net_GeoIP::getInstance() -- method to get an instance and avoid re-parsing the database
  • Net_GeoIP::lookupCountryName() -- returns full country name for specified IP address
  • Net_GeoIP::lookupCountryCode() -- returns 2-letter country code (e.g. CA) for specified IP address
  • Net_GeoIP::lookupRegion() -- returns the region for given IP address.
  • Net_GeoIP::lookupLocation() -- returns the location record for specified IP address
  • Net_GeoIP::lookupOrg() -- returns the name of the organization or ISP for the given IP address.
Prev | Networking | Next
Net_Geo::getRecord() | PEAR Manual | Net_GeoIP::getInstance()


Net_GeoIP::getInstance()

Net_GeoIP::getInstance()

Net_GeoIP::getInstance() – method to get an instance and avoid re-parsing the database

Synopsis

require_once "Net/GeoIP.php";

object getInstance() ( string $filename [, int $flags] )

Description

This method is an implementation of the so-called singleton pattern and is the preferred way to create instances of Net_GeoIP.

Creating an instance of Net_GeoIP

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat", Net_GeoIP::SHARED_MEMORY);
?>

Multiple Instances

If you want to use multiple databases in one application, you will need to create an instance of Net_GeoIP for each database. Using the singleton getInstance() method will make sure that at any given point exactly one object for each database exists, which saves on overhead of setting up database segments.

Parameter

  • string $filename - Name of (and path to) the database file

  • int $flags - Flags that control the class behaviour. This parameter can be one of the following class constants:

    • Net_GeoIp::SHARED_MEMORY - use SHMOP to share a database among multiple PHP instances.

      Note: Only one Net_GeoIP instance can use shared memory at a time.
      If you are using Net_GeoIP::SHARED_MEMORY (shmop) you can only use Net_GeoIP::SHARED_MEMORY for one (1) instance (i.e. for one database). Any subsequent attempts to instantiate using SHARED_MEMORY will read the same shared memory block already initialized, and therefore will cause problems since the expected database format won't match the database in the shared memory block.
      Note that there is no easy way to flag "nice errors" to prevent attempts to create new instances using Net_GeoIP::SHARED_MEMORY flag and it is also not posible (in a safe way) to allow new instances to overwrite the shared memory block.
      In short, is you are using multiple databases, use the Net_GeoIP::SHARED_MEMORY flag with care.

    • Net_GeoIp::MEMORY_CACHE - store the full contents of the database in memory for current script.

      This is useful if you access the database several times in a script.

    • Net_GeoIp::STANDARD - standard no-cache version. This is also the default value if this parameter is ommitted.

Prev | Net_GeoIP | Next
Net_GeoIP | PEAR Manual | Net_GeoIP::lookupCountryName()


Net_GeoIP::lookupCountryName()

Net_GeoIP::lookupCountryName()

Net_GeoIP::lookupCountryName() – returns full country name for specified IP address

Synopsis

require_once "Net/GeoIP.php";

string lookupCountryName() ( string $addr )

Description

This method returns the full country name for the given IP address. It works with both the free and the non-free databases.

Looking up the country name

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    echo $geoip->lookupCountryName($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

  • string $addr - IP address

    Note: Lookups on Hostnames
     Note that this PHP API does NOT support lookups on hostnames. This is so that the public API can be kept simple and so that the lookup functions don't need to try name lookups if IP lookup fails (which would be the only way to keep the API simple and support name-based lookups).
    If you do not know the IP address, you can convert an name to IP very simply using PHP native functions or other libraries:
    <?php
    $geoip    ->lookupCountryName(gethostbyname("example.com"));
    ?>
    Or, if you don't know whether an address is a name or IP address, use application-level logic:
    <?php
    if (ip2long($ip_or_name) === false) {
            $ip = gethostbyname($ip_or_name);
    } else {
            $ip = $ip_or_name;
    }

    $country = $geoip->lookupCountryName($ip);
    ?>

Throws

This method sthrow an exception if the IP address is invalid or if the database type is incorrect.

Prev | Net_GeoIP | Next
Net_GeoIP::getInstance() | PEAR Manual | Net_GeoIP::lookupCountryCode()


Net_GeoIP::lookupCountryCode()

Net_GeoIP::lookupCountryCode()

Net_GeoIP::lookupCountryCode() – returns 2-letter country code (e.g. "CA") for specified IP address

Synopsis

require_once "Net/GeoIP.php";

string lookupCountryCode() ( string $addr )

Description

This method returns the 2-letter country code for the given IP address. It works with both the free and the non-free databases.

Looking up the country code

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    echo $geoip->lookupCountryCode($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

  • string $addr - IP address

    Note: Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid or if the database type is incorrect.

Prev | Net_GeoIP | Next
Net_GeoIP::lookupCountryName() | PEAR Manual | Net_GeoIP::lookupRegion()


Net_GeoIP::lookupRegion()

Net_GeoIP::lookupRegion()

Net_GeoIP::lookupRegion() – returns the region for given IP address.

Synopsis

require_once "Net/GeoIP.php";

array lookupRegion() ( string $addr )

Description

This method returns an array containing the country code and the region for the specified IP address. It works only with a non-free Region database.

Looking up the region

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    list($country_code, $region) = $geoip->lookupRegion($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

  • string $addr - IP address

    Note: Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid.

Prev | Net_GeoIP | Next
Net_GeoIP::lookupCountryCode() | PEAR Manual | Net_GeoIP::lookupLocation()


Net_GeoIP::lookupLocation()

Net_GeoIP::lookupLocation()

Net_GeoIP::lookupLocation() – returns the location record for specified IP address

Synopsis

require_once "Net/GeoIP.php";

object lookupLocation() ( string $addr )

Description

This method returns an instance of Net_GeoIP_Location for the specified IP address. It works only with a non-free City database.

Looking up the location record

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    $location = $geoip->lookupLocation($_SERVER['REMOTE_ADDR']);

    var_dump($location);

    printf("City: %s, %s\nLatitude: %s, Longitude: %s\n",
           $location->city, $location->region,
           $location->latitude, $location->longitude);

} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

  • string $addr - IP address

    Note: Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid.

Prev | Net_GeoIP | Next
Net_GeoIP::lookupRegion() | PEAR Manual | Net_GeoIP::lookupOrg()


Net_GeoIP::lookupOrg()

Net_GeoIP::lookupOrg()

Net_GeoIP::lookupOrg() – returns the name of the organization or ISP for the given IP address.

Synopsis

require_once "Net/GeoIP.php";

string lookupOrg() ( string $addr )

Description

This method returns the name of the organization or of the ISP which has registered the IP address range that contains the specified IP address. It works only with a non-free Organization/ISP database.

Looking up organization name

<?php
require_once "Net/GeoIP.php";

$geoip = Net_GeoIP::getInstance("/path/to/geoipdb.dat");

try {
    echo $geoip->lookupOrg($_SERVER['REMOTE_ADDR']);
} catch (Exception $e) {
    // Handle exception
}
?>

Parameter

  • string $addr - IP address

    Note: Hostnames are not supported. More information.

Throws

This method throws an exception if the IP address is invalid or the database type is wrong.

Prev | Net_GeoIP | Next
Net_GeoIP::lookupLocation() | PEAR Manual | Net_IPv4


Net_IPv4

Net_IPv4

Provides several methods for working with IP addresses and netmasks.

Table of Contents
  • Net_IPv4::atoh() -- Converts a dot-quad formatted IP address into a hexadecimal string
  • Net_IPv4::htoa() -- Converts a hexadecimal string into a dot-quad formatted IP address
  • Net_IPv4::ip2double() -- Converts an IP address to a PHP double.
  • Net_IPv4::validateIP() -- Validate the syntax of the given IP adress.
  • Net_IPv4::validateNetmask() -- Validate the syntax of the given netmask.
  • Net_IPv4::parseAddress() -- Parse a CIDR address (address/netmask combination).
  • Net_IPv4::calculate() -- Calculates network information based on an IP address and netmask.
  • Net_IPv4::ipInNetwork() -- Determines whether or not the supplied IP is within the supplied network.
Prev | Networking | Next
Net_GeoIP::lookupOrg() | PEAR Manual | Net_IPv4::atoh()


Net_IPv4::atoh()

Net_IPv4::atoh()

Net_IPv4::atoh() – Converts a dot-quad formatted IP address into a hexadecimal string

Synopsis

require_once 'Net/IPv4.php';

mixed atoh ( string $addr )

Description

Converts a dot-quad formatted IP address into a hexadecimal string - for example "192.168.1.0" to "c0a80100". Returns FALSE if the string given is no valid IP adress.

Note

This function can be called statically.

Prev | Net_IPv4 | Next
Net_IPv4 | PEAR Manual | Net_IPv4::htoa()


Net_IPv4::htoa()

Net_IPv4::htoa()

Net_IPv4::htoa() – Converts a hexadecimal string into a dot-quad formatted IP address

Synopsis

require_once 'Net/IPv4.php';

mixed htoa ( string $addr )

Description

Converts hexadecimal string to a dot-quad formatted IP address - for example "c0a80100" to "192.168.1.0". Returns FALSE if the hexadecimal string is no valid IP adress.

Note

This function can be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::atoh() | PEAR Manual | Net_IPv4::ip2double()


Net_IPv4::ip2double()

Net_IPv4::ip2double()

Net_IPv4::ip2double() – Converts an IP address to a PHP double.

Synopsis

require_once 'Net/IPv4.php';

float ip2double ( string $ip_addr )

Description

Converts an IP address to a PHP double - for example "192.168.1.0" to "3232235776". A double is, in contrast to ip2long's integer, not signed and may be more comfortable when presented to the user. It can still be reconverted with PHP's long2ip().

Note

This function can be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::htoa() | PEAR Manual | Net_IPv4::validateIP()


Net_IPv4::validateIP()

Net_IPv4::validateIP()

Net_IPv4::validateIP() – Validate the syntax of the given IP adress.

Synopsis

require_once 'Net/IPv4.php';

bool validateIP ( string $ip_addr )

Description

Validates the syntax of an IP address in dot-quad format. Returns true if address is valid, false if not.

Note

This function can be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::ip2double() | PEAR Manual | Net_IPv4::validateNetmask()


Net_IPv4::validateNetmask()

Net_IPv4::validateNetmask()

Net_IPv4::validateNetmask() – Validate the syntax of the given netmask.

Synopsis

require_once 'Net/IPv4.php';

bool validateNetmask ( string $netmask )

Description

Validates the syntax of a dot-quad formatted netmask. Returns true if netmask is valid, false if not.

Note

This function can be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::validateIP() | PEAR Manual | Net_IPv4::parseAddress()


Net_IPv4::parseAddress()

Net_IPv4::parseAddress()

Net_IPv4::parseAddress() – Parse a CIDR address (address/netmask combination).

Synopsis

require_once('Net/IPv4.php');

bool parseAddress ( string $address )

Description

Parses a Classless Inter-Domain Routing address (e.g. 192.168.1.0/24) and stores information in the object variables network, ip, netmask, broadcast, long and bitmask.

Example

How to get netmask and broadcast from CIDR address

<?php

require('Net/IPv4.php');

$cidr = '192.168.0.50/16';
$net = Net_IPv4::parseAddress($cidr);
echo $net->network;   // 192.168.0.0
echo $net->ip;        // 192.168.0.50
echo $net->broadcast; // 192.168.255.255
echo $net->bitmask;   // 16
echo $net->long;      // 3232235520 (long/double version of 192.168.0.50)
echo $net->netmask;   // 255.255.0.0

?>

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::validateNetmask() | PEAR Manual | Net_IPv4::calculate()


Net_IPv4::calculate()

Net_IPv4::calculate()

Net_IPv4::calculate() – Calculates network information based on an IP address and netmask.

Synopsis

require_once 'Net/IPv4.php';

mixed calculate ( )

Description

Fully populates the object properties based on the IP address and netmask/bitmask properties. Once these two fields are populated, calculate() will perform calculations to determine the network and broadcast address of the network.

Example

Calculating broadcast and network address

<?php

require 'Net/IPv4.php';

// create IPv4 object
$ip_calc = new Net_IPv4();

// set variables
$ip_calc->ip = "192.168.1.10";
$ip_calc->netmask = "255.255.255.0";

/* alternative method with numerical values:
$ip_calc->long = 3232235786;
$ip_calc->bitmask = 24;
*/

// calculate
$error = $ip_calc->calculate();
if (!is_object($error))
{
  // if returned true, output
  echo "Your network address: ".$ip_calc->network."<br />";
  echo "Your broadcast address: ".$ip_calc->broadcast."<br />";
}
else
{
  // otherwise handle error
  echo "An error occured: ".$error->getMessage();
}

?>

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::parseAddress() | PEAR Manual | Net_IPv4::ipInNetwork()


Net_IPv4::ipInNetwork()

Net_IPv4::ipInNetwork()

Net_IPv4::ipInNetwork() – Determines whether or not the supplied IP is within the supplied network.

Synopsis

require_once 'Net/IPv4.php';

bool validateIP ( string $ip_addr , string $cidr_block )

Description

Determines whether or not the supplied IP address is within the supplied network.

Example

Checking if a IP adress is contained in a network

<?php

require 'Net/IPv4.php';

$ip   = '10.11.12.13';
$net1 = '10.0.0.1/8';
$net2 = '127.0.0.1/8';

echo Net_IPv4::ipInNetwork($ip, $net1) // bool(true)
echo Net_IPv4::ipInNetwork($ip, $net2) // bool(false)
?>

Note

This function can be called statically.

Prev | Net_IPv4 | Next
Net_IPv4::calculate() | PEAR Manual | Net_IPv6


Net_IPv6

Net_IPv6

Provides function to work with the 'Internet Protocol v6'

Table of Contents
  • Net_IPv6::checkIPv6() -- Validation of IPv6 addresses
  • Net_IPv6::compress() -- compress an IPv6 address
  • Net_IPv6::uncompress() -- Uncompresses an IPv6 address
  • Net_IPv6::getAddressType() -- Returns the type of an IP address
  • Net_IPv6::getNetmask() -- Calculates the network prefix
  • Net_IPv6::isInNetmask() -- Checks if an IP is in a specific address space
  • Net_IPv6::removeNetmaskSpec() -- Removes the Netmask length specification
  • Net_IPv6::splitV64() -- splits an IPv6 address in it IPv6 and IPv4 part
Prev | Networking | Next
Net_IPv4::ipInNetwork() | PEAR Manual | Net_IPv6::checkIPv6()


Net_IPv6::checkIPv6()

Net_IPv6::checkIPv6()

Net_IPv6::checkIPv6() – Validation of IPv6 addresses

Synopsis

require_once 'Net/IPv6.php';

boolean Net_IPv6::checkIPv6 ( string $ip )

Description

Checks an IP for IPv6 compatibility.

Parameter

  • string $ip - the IP address to check

Return value

boolean - TRUE, if syntax is valid

Note

This function can be called statically.

Prev | Net_IPv6 | Next
Net_IPv6 | PEAR Manual | Net_IPv6::compress()


Net_IPv6::compress()

Net_IPv6::compress()

Net_IPv6::compress() – compress an IPv6 address

Synopsis

require_once 'Net/IPv6.php';

string Net_IPv6::compress ( string $ip )

Description

Compresses an IPv6 address. RFC 2373 allows you to compress zeros in an address to '::'. This function expects an valid IPv6 address and compresses successive zeros to '::'

FF01:0:0:0:0:0:0:101 -> FF01::101
      0:0:0:0:0:0:0:1      -> ::1

Parameter

  • string $ip - the IP address to compress

Return value

string - the compressed IP is an IPv6 address

Note

This function can be called statically.

Prev | Net_IPv6 | Next
Net_IPv6::checkIPv6() | PEAR Manual | Net_IPv6::uncompress()


Net_IPv6::uncompress()

Net_IPv6::uncompress()

Net_IPv6::uncompress() – Uncompresses an IPv6 address

Synopsis

require_once 'Net/IPv6.php';

string Net_IPv6::uncompress ( string $ip )

Description

Uncompresses an IPv6 address. RFC 2373 allows you to compress zeros in an address to '::'. This function expects an valid IPv6 address and expands the '::' to the required zeros.

FF01::101	->  FF01:0:0:0:0:0:0:101
      ::1       ->  0:0:0:0:0:0:0:1

Parameter

  • string $ip - the IP address to uncompress

Return value

string - the uncompressed IP is an IPv6 address

Note

This function can be called statically.

Prev | Net_IPv6 | Next
Net_IPv6::compress() | PEAR Manual | Net_IPv6::getAddressType()


Net_IPv6::getAddressType()

Net_IPv6::getAddressType()

Net_IPv6::getAddressType() – Returns the type of an IP address

Synopsis

require_once 'Net/IPv6.php';

int Net_IPv6::getAddressType ( string $ip )

Description

RFC 1883, Section 2.3 describes several types of addresses in the IPv6 addresse space. This methods tries to find the type of address for the given IP.

Several address types are markers for reserved spaces and as consequence a subject to change.

Parameter

  • string $ip - the IP address in Hex format, compressed IPs are allowed

Return value

int - the addresstype

The type can be one of this constants:

  • NET_IPV6_MULTICAST

  • NET_IPV6_UNICAST_PROVIDER

  • NET_IPV6_LOCAL_LINK

  • NET_IPV6_LOCAL_SITE

  • NET_IPV6_UNKNOWN_TYPE

  • NET_IPV6_RESERVED_UNICAST_GEOGRAPHIC

  • NET_IPV6_RESERVED_IPX

  • NET_IPV6_RESERVED

  • NET_IPV6_RESERVED_NSAP

  • NET_IPV6_UNASSIGNED

Note

This function can be called statically.

Method available since: Release 1.1.0

Prev | Net_IPv6 | Next
Net_IPv6::uncompress() | PEAR Manual | Net_IPv6::getNetmask()


Net_IPv6::getNetmask()

Net_IPv6::getNetmask()

Net_IPv6::getNetmask() – Calculates the network prefix

Synopsis

require_once 'Net/IPv6.php';

string Net_IPv6::getNetmask ( string $ip , int $bits = null )

Description

Calculates the network prefix based on the netmask bits.

Parameter

  • string $ip - the IP address in Hex format, compressed IPs are allowed

  • int $bits - if the number of netmask bits is not part of the IP, you must provide the mumber of bits

Return value

string - the network prefix

Note

This function can be called statically.

Method available since: Release 1.1.0

Prev | Net_IPv6 | Next
Net_IPv6::getAddressType() | PEAR Manual | Net_IPv6::isInNetmask()


Net_IPv6::isInNetmask()

Net_IPv6::isInNetmask()

Net_IPv6::isInNetmask() – Checks if an IP is in a specific address space

Synopsis

require_once 'Net/IPv6.php';

boolean Net_IPv6::isInNetmask ( string $ip , string $netmask , int $bits = null )

Description

Checks if an (compressed) IP is in a specific address space. If the IP does not contain the number of netmask bits (for example: F8000::FFFF/16), then you have to use the $bits parameter.

Parameter

  • string $ip - the IP address in Hex format, compressed IPs are allowed

  • string $netmask - the netmask (for example: F800::)

  • int $bits - if the number of netmask bits is not part of the IP, you must provide the mumber of bits

Return value

boolean - TRUE, if the IP is in the address space.

Note

This function can be called statically.

Method available since: Release 1.1.0

Prev | Net_IPv6 | Next
Net_IPv6::getNetmask() | PEAR Manual | Net_IPv6::removeNetmaskSpec()


Net_IPv6::removeNetmaskSpec()

Net_IPv6::removeNetmaskSpec()

Net_IPv6::removeNetmaskSpec() – Removes the Netmask length specification

Synopsis

require_once 'Net/IPv6.php';

string Net_IPv6::removeNetmaskSpec ( string $ip )

Description

Removes a possible existing netmask length specification in an IP addresse.

Parameter

  • string $ip - the IP address in Hex format, compressed IPs are allowed

Return value

string - the IP without netmask length specification.

Note

This function can be called statically.

Method available since: Release 1.1.0

Prev | Net_IPv6 | Next
Net_IPv6::isInNetmask() | PEAR Manual | Net_IPv6::splitV64()


Net_IPv6::splitV64()

Net_IPv6::splitV64()

Net_IPv6::splitV64() – splits an IPv6 address in it IPv6 and IPv4 part

Synopsis

require_once 'Net/IPv6.php';

array Net_IPv6::splitV64 ( string $ip )

Description

Splits an IPv6 address into the IPv6 and a possible IPv4-formated part. RFC 2373 allows you to note the last two parts of an IPv6 address in the IPv4 address format.

0:0:0:0:0:0:13.1.68.3
     0:0:0:0:0:FFFF:129.144.52.38

Parameter

  • string $ip - the IP address to split

Return value

array - key [0] contains the IPv6 part, key [1] the IPv4 formated part

Note

This function can be called statically.

Prev | Net_IPv6 | Next
Net_IPv6::removeNetmaskSpec() | PEAR Manual | Net_LDAP


Net_LDAP

Net_LDAP

Net_LDAP allows you to query and manipulate the data stored in directory servers using PHP in an object-oriented way.

Detailed usage examples are available at: /your/pear/path/docs/Net_LDAP/examples/

Please note, that as of 2009-05-28 Net_LDAP2, which is superseding Net_LDAP, has become stable. Please use Net_LDAP2 instead.

Table of Contents
  • Introduction -- What Net_LDAP is and general information
  • Error handling -- How handling errors works in Net_LDAP
  • Configuration and connecting -- How to configure Net_LDAP and connect to an LDAP server
  • Search -- Searching entries
  • Fetching entries -- Retrieving entries directly or from a searchresult
  • Attributes -- Reading/adding/changing/deleting attributes from entries
  • Managing entries -- Adding/renaming/moving/deleting entries
  • LDAP filters -- Introduction to and usage of LDAP filters
  • LDIF files -- Converting between Net_LDAP_Entries and LDIF files
Prev | Networking | Next
Net_IPv6::splitV64() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What Net_LDAP is and general information

Welcome to Net_LDAP!

Net_LDAP is a clone of Perls Net::LDAP package. PEAR Net_LDAP for PHP does, besides some own features, provide most of Perl Net::LDAP methods. Net_LDAP allows you to query and manipulate the data stored in directory servers using PHP in an object-oriented way. A directory server is a database server providing a hierarchical database and is usually queried using the LDAP protocol.

Classes of Net_LDAP

The following table gives you a short overview which classes are available in Net_LDAP and what they can be used for. Their relations will be explained too.

Classes of Net_LDAP
Class name | Description
Net_LDAP | This is the main class. It enables you to connect and bind to a LDAP-server and to run ldap-querys like searching and manipulating entries. Most common, you will run a search using a LDAP-Filter and will get a Net_LDAP_Search-object. You may also fetch an entry directly, which gives you a Net_LDAP_Entry-object.
Net_LDAP_Search | Objects of this class are returned from search querys. You can use this object to retrieve informations about a search result, like how much entries you have found for the provided filter. You can retrieve the found entries as Net_LDAP_Entry-objects in various forms: sorted, consecutively starting from the end or beginning or unsorted at once.
Net_LDAP_Entry | Objects of this kind are either produced by casting fresh entries manually, by retrieving the result of a LDAP-search or by fetching an entry directly. It gives you the possibility to read and/or manipulate the attributes of an entry which describes the characteristic of the specific object.
Net_LDAP_Util | The utility class contains only static methods, so you should not need to make an instance of it. It features some helpful methods, some of them are used internally by Net_LDAP but may be used externally from you as well. The most methods deal with escaping issues, since LDAP has some metacharacters with special meaning so that they usually need to be properly escaped.
Net_LDAP_Filter | You are free to give LDAP-Filters on your own to the Net_LDAP->search() method, however this has some drawbacks (including escaping issues). For this reason, you can use the Net_LDAP_Filter class to easily build and combine your filters. LDAP filters are extensively explained at the chapter LDAP filters.
Net_LDAP_Error | This is a error class. Most methods of Net_LDAP will return a object of this class if something went wrong. You can use this object to identify errors and to get detailed knowledge on what went wrong. See Errorhandling for more information.
Net_LDAP_LDIF | LDIF files are human readable, plain text files containing directory data and/or change commands, much like an SQL file. Unlike SQL files, it is data centric, not action centric. Net_LDAP_LDIF enables you to convert between Net_LDAP_Entry-objects and LDIF files. Please note, that Net_LDAP_LDIF has a little different error handling explained later.
Prev | Net_LDAP | Next
Net_LDAP | PEAR Manual | Error handling


Error handling

Error handling

Error handling – How handling errors works in Net_LDAP

Error handling

Nearly all of Net_LDAPs methods return a Net_LDAP_Error object if something went wrong. You always should check for errors after you performed an action to be sure that your application doesn't do things you don't want it to do.

Handling errors is an easy task, you just have to test the return value as shown below. If an error occured, you can halt the script for example. In other cases, you may just log the error, but what exactly happens depends on your specific situation, of course.

You can use the getMessage() method of the error object to retrieve the error message explaining the problem and getCode() to get the error code which is usually the LDAP-Error code (see Table below) and may be used for automated reaction on errors.

Dealing with errors

<?php
// Perform an arbitrary action:
$result = $ldap->search($searchbase, $filter, $options);

// Check, if an error occured and do something.
// Here we use die() to show the message of the error.
if (PEAR::isError($result)) {
    die($result->getMessage());
}
?>
Error codes Net_LDAP
Error code | Description
0x00 | LDAP_SUCCESS
0x01 | LDAP_OPERATIONS_ERROR
0x02 | LDAP_PROTOCOL_ERROR
0x03 | LDAP_TIMELIMIT_EXCEEDED
0x04 | LDAP_SIZELIMIT_EXCEEDED
0x05 | LDAP_COMPARE_FALSE
0x06 | LDAP_COMPARE_TRUE
0x07 | LDAP_AUTH_METHOD_NOT_SUPPORTED
0x08 | LDAP_STRONG_AUTH_REQUIRED
0x09 | LDAP_PARTIAL_RESULTS
0x0a | LDAP_REFERRAL
0x0b | LDAP_ADMINLIMIT_EXCEEDED
0x0c | LDAP_UNAVAILABLE_CRITICAL_EXTENSION
0x0d | LDAP_CONFIDENTIALITY_REQUIRED
0x0e | LDAP_SASL_BIND_INPROGRESS
0x10 | LDAP_NO_SUCH_ATTRIBUTE
0x11 | LDAP_UNDEFINED_TYPE
0x12 | LDAP_INAPPROPRIATE_MATCHING
0x13 | LDAP_CONSTRAINT_VIOLATION
0x14 | LDAP_TYPE_OR_VALUE_EXISTS
0x15 | LDAP_INVALID_SYNTAX
0x20 | LDAP_NO_SUCH_OBJECT
0x21 | LDAP_ALIAS_PROBLEM
0x22 | LDAP_INVALID_DN_SYNTAX
0x23 | LDAP_IS_LEAF
0x24 | LDAP_ALIAS_DEREF_PROBLEM
0x30 | LDAP_INAPPROPRIATE_AUTH
0x31 | LDAP_INVALID_CREDENTIALS
0x32 | LDAP_INSUFFICIENT_ACCESS
0x33 | LDAP_BUSY
0x34 | LDAP_UNAVAILABLE
0x35 | LDAP_UNWILLING_TO_PERFORM
0x36 | LDAP_LOOP_DETECT
0x3C | LDAP_SORT_CONTROL_MISSING
0x3D | LDAP_INDEX_RANGE_ERROR
0x40 | LDAP_NAMING_VIOLATION
0x41 | LDAP_OBJECT_CLASS_VIOLATION
0x42 | LDAP_NOT_ALLOWED_ON_NONLEAF
0x43 | LDAP_NOT_ALLOWED_ON_RDN
0x44 | LDAP_ALREADY_EXISTS
0x45 | LDAP_NO_OBJECT_CLASS_MODS
0x46 | LDAP_RESULTS_TOO_LARGE
0x47 | LDAP_AFFECTS_MULTIPLE_DSAS
0x50 | LDAP_OTHER
0x51 | LDAP_SERVER_DOWN
0x52 | LDAP_LOCAL_ERROR
0x53 | LDAP_ENCODING_ERROR
0x54 | LDAP_DECODING_ERROR
0x55 | LDAP_TIMEOUT
0x56 | LDAP_AUTH_UNKNOWN
0x57 | LDAP_FILTER_ERROR
0x58 | LDAP_USER_CANCELLED
0x59 | LDAP_PARAM_ERROR
0x5a | LDAP_NO_MEMORY
0x5b | LDAP_CONNECT_ERROR
0x5c | LDAP_NOT_SUPPORTED
0x5d | LDAP_CONTROL_NOT_FOUND
0x5e | LDAP_NO_RESULTS_RETURNED
0x5f | LDAP_MORE_RESULTS_TO_RETURN
0x60 | LDAP_CLIENT_LOOP
0x61 | LDAP_REFERRAL_LIMIT_EXCEEDED
1000 | Unknown Net_LDAP Error
Prev | Net_LDAP | Next
Introduction | PEAR Manual | Configuration and connecting


Configuration and connecting

Configuration and connecting

Configuration and connecting – How to configure Net_LDAP and connect to an LDAP server

Connecting to an LDAP server

To connect to an LDAP server, you should use Net_LDAP's static connect() method. It takes one parameter, an array full of configuration options, and either returns a Net_LDAP object if connecting works, or a Net_LDAP_Error object in case of a failure.

The following table lists all configuration options. If the default value for an option fits your needs, you don't need add it to your configuration array.

Possible configuration options
Name | Description | Default
host | LDAP server name to connect to. You can provide several hosts in an array in which case the hosts are tried from left to right. | localhost
port | Port on the server | 389
version | LDAP version | 3
starttls | TLS is started after connecting | false
binddn | The distinguished name to bind as (username) | (none)
bindpw | Password for the binddn | (none)
basedn | LDAP base name (root directory) | (none)
options | Array of additional ldap options as key-value pairs | array()
filter | Default search filter (string or preferably Net_LDAP_Filter object). See LDAP filters | (objectClass=*)
scope | Default search scope, see Search | sub

Connecting to an LDAP server

<?php
// Inclusion of the Net_LDAP package:
require_once 'Net/LDAP.php';

// The configuration array:
$config = array (
    'binddn'    => 'cn=admin,ou=users,dc=example,dc=org',
    'bindpw'    => 'password',
    'basedn'    => 'dc=example,dc=org',
    'host'      => 'ldap.example.org'
);

// Connecting using the configuration:
$ldap = Net_LDAP::connect($config);

// Testing for connection error
if (PEAR::isError($ldap)) {
    die('Could not connect to LDAP-server: '.$ldap->getMessage());
}
?>
Prev | Net_LDAP | Next
Error handling | PEAR Manual | Search


Search

Search

Search – Searching entries

A short note on DNs

It may be possible that restricted characters (",", "+", """, "\", "<", ">", ";", "#", "=", space or a hexpair) are used in attributes or values inside the DN. You should have a look to the APIdoc of Net_LDAP2_Util::escape_dn_value(), Net_LDAP2_Util::unescape_dn_value(), Net_LDAP2_Util::ldap_explode_dn() and Net_LDAP2_Util::canonical_dn(). These functions can be used to safely handle DNs.

Searching some entries

After connecting to the server, you can use Net_LDAP's search() method to search the directory. The method takes three parameters:

  • $base is the base search DN. If kept null, the default base DN configured when connecting is used.

  • $filter is the query filter that determines which results are returned. It is either a string (experts use only) or better a Net_LDAP_Filter-object. Net_LDAP_Filter automatically deals with LDAP-Filter escaping issues. LDAP filters are extensively explained at the chapter LDAP filters.

  • $params is an array of configuration options for the current query.

    Possible configuration parameters
    Name | Description | Default
    scope The scope used for searching:

    • base - Just one entry

    • sub - The whole tree

    • one - Immediately below $base

            sub
    sizelimit | Number of entries returned at maximum | 0 (no limit)
    timelimit | Seconds to spent for searching | 0 (no limit)
    attrsonly | If true, only attribute names are returned | false
    attributes | Array of attribute names, which the entry should contain. It is good practice to limit this to just the ones you need. | array() (all attributes)

The search() method will return either a Net_LDAP_Search object or a Net_LDAP_Error. You can use the Net_LDAP_Search-object to trigger further actions like counting how many entries where found or to retrieve the found entries.

Making a search query

<?php
// Building a very basic filter
// we want to find all Entries whose surnames start with "Joe":
$filter = Net_LDAP_Filter::create('sn', 'begins',  'Joe');

// We define a custom searchbase here. If you pass NULL, the basedn provided
// in the Net_LDAP configuration will be used. This is often not what you want.
$searchbase = 'ou=addressbook,dc=example,dc=org';

// Some options:
// We search all subtrees beneath 'ou=addressbook,dc=example,dc=org'
// and we select the attribute 'sn'. It is a good practice to limit the
// requested attributes to only those you actually want to use later.
// However, note that it is faster to select unneeded attributes than
// refetching an entry later to just get those attributes.
$options = array(
    'scope' => 'sub',
    'attributes' => array('sn')
);

// Perform the search!
$search = $ldap->search($searchbase, $filter, $options);

// Test for search errors:
if (PEAR::isError($search)) {
    die($search->getMessage() . "\n");
}

// Say how many entries we have found:
echo "Found " . $search->count() . " entries!";
?>
Prev | Net_LDAP | Next
Configuration and connecting | PEAR Manual | Fetching entries


Fetching entries

Fetching entries

Fetching entries – Retrieving entries directly or from a searchresult

Retrieving entries directly

You can retrieve directory entries in several ways, either directly or from a performed search request. If you want to fetch an entry directly, you need to know its absolute distinguished name (DN). To directly fetch an known entry from the directory server, you use Net_LDAP's getEntry() method. It takes two parameters: The DN of the entry and the attributes you want to read from the entry. It returns a Net_LDAP_Entry object if fetching worked, or a Net_LDAP_Error object in case of a failure.

You may also check if the entry exists in the server before you fetch it. This can be achieved by Net_LDAP's dnExists() which takes the DN to test and returns either true or false.

Fetching an entry directly

<?php
// Defining the DN we want to fetch;
// we want to select the given- and the surname
$dn = 'cn=admin,o=example,dc=org';
$entry = $ldap->getEntry($dn, array('gn', 'sn'));

// Error checking is important!
if (Net_LDAP::isError($entry)) {
    die('Could not fetch entry: '.$entry->getMessage());
}
?>

Retrieving entries from a searchresult

The second way to retrieve entries is from a searchresult. As described in chapter "Search", you access the entries of a search result through the Net_LDAP_Search-object resulting from Net_LDAP's search() method. Each of the following methods return a Net_LDAP_Error-object if something goes wrong, so remember to test for errors! You have several ways to read the entries:

Possible ways to fetch entries
Method of Net_LDAP_Search | Description
entries() | This returns the entries at once unsorted.
as_struct() | This returns all entries as multidimensional array instead of Net_LDAP_Entry-objects. The array keys of the first dimension are the DNs and the value is an array containing all attributes. The array keys of the second level are the attributes names; the value of the second level is an array containing all the attributes values. Note, that even if there are no or just one value, an array is present.
sorted() | Use this if you want to get the entries at once but sorted. You can sort by several attributes which can contain multiple values. You can of course sort ascending (default) or descending - just pass the PHP constant SORT_ASC or SORT_DESC as second parameter.
sorted_as_struct() | Like as_struct(), this returns the entries as multidimensional array, but in this case sorted. For parameters, see sorted()
shiftEntry() | This returns one entry from the beginning of the search result. Since this returns FALSE if all entries are fetched, shiftEntry() is perfectly appropriate to get used inside a while-loop. Take care not to mix shiftEntry() and popEntry()!
popEntry() | Exactly the same as shiftEntry, but returns the entry from the end of the searchresult. Again, be sure to not mix shiftEntry() and popEntry()!

To directly fetch an known entry from the directory server, you use Net_LDAP's getEntry() method. It takes two parameters: The DN of the entry and the attributes you want to read from the entry. It returns a Net_LDAP_Entry object if fetching worked, or a Net_LDAP_Error object in case of a failure.

You may also check if the entry exists in the server before you fetch it. This can be achieved by Net_LDAP's dnExists() which takes the DN to test and returns either true or false.

Fetching all entries from searchresult

<?php
// return all entries:
$entry = $search->entries();
?>

Fetching all entries from searchresult: sorted

<?php
// return sorted by first 'sn' then 'gn', but descending:
$entry = $search->sorted(array('sn', 'gn'), SORT_DESC);
?>

Fetching entries one by one inside a while loop

<?php
// return entries one by one:
while ( $entry = $search->shiftEntry() ) {
    // do something, like printing the DN of the entry;
    // in a real case, dont forget to test for errors!
    echo "ENTRY: " . $entry->dn();
}
?>
Prev | Net_LDAP | Next
Search | PEAR Manual | Attributes


Attributes

Attributes

Attributes – Reading/adding/changing/deleting attributes from entries

Reading attributes

Reading attribute values depends on the selection of those attributes at search time. You can only access attributes that where selected! You can read attribute values using either Net_LDAP_Entry's getValues() or getValue() method. getValue() will return an array where the keys are the attributes names. If you use getValues() you may pass an option:

  • 'single': only the first value is returned as string

  • 'all': all values including the value count are returned in an array

  • 'default': in all other cases an attribute value with a single value is returned as string, if it has multiple values it is returned as an array (without value count)

Reading attributes

<?php
// read Surename, singlevalued
$surename = $entry->getValue('sn', 'single');

// read mail adress which may be multivalued
$mail = $entry->getValue('mail', 'all');
?>

If you want to read the distinguished name of an Entry (DN), you must use a different method: dn()

Reading an entries DN

<?php
$dn = $entry->dn();
?>

Regular expressions on attributes

PEAR::Net_LDAP has the unique feature to apply a regular expression match directly against attributes, so you do not need to manually fetch all values and run the regex against them. Instead, you can use Net_LDAP_Entry's preg_match() function. The behavior of this function is the same as PHPs preg_match(), but the $matches array is slightly different. It features one dimension more, since it may match for several attribute values if the attribute is multivalued. If you pass $matches, be sure to do it via REFERENCE, because otherwise $matches remains empty. preg_match() returns true or false, depending on match.

Performing preg_match on attribute values

<?php
// Look, if the user has an emailadress for 'example', if so,
// we want to display the tld:
// (be sure to pass $matches as reference!)
$matches = array();
if ( $entry->preg_match('mail', '/example\.(.+)/', &$matches) ) {
    // print every TLD found for 'example':
    foreach ($matches as $match) {
        echo $match[1];
    }
}
?>

General information regarding attribute changing

It is important to know how attribute changing works. Modifications to an entry through the Net_LDAP_Entry-object are local only. After you have made all changes and want to transfer them to the directory server, you must call update() of the Net_LDAP_Entry object. This will return either TRUE or an Net_LDAP_Error. Another good information is, that you must select attributes at search time if you want to add/change/delete attribute values. Otherwise Net_LDAP will most likely fail silently giving you the wrong assumtion that everything was okay - Net_LDAP needs knowledge of the attributes it should work with!

Modification of attributes is also possible through Net_LDAP's modify() method. This method will call the methods described here on the Net_LDAP_Entry object given, and directly calls an update() after that, thus performing the changes directly on the server. The parameter is an complex array describing the changes to be performed. It is considered for more advanced users, because it is more compact, so please refer to the latest API documentation for more information.

Adding attributes

Adding attrbiute values to an entry is an easy task. You just need to call add()! The parameter is an array whose keys are the attribute names and values the attributes values. If only one attribute value should be added, the second level may be a string. If the attribute doesn't exist so far, it will be added, if it exists, the attributes values will be added.

Adding attributes

<?php
// Adding several attributes:
$result = $entry->add(
    array(
        'sn'   => 'Doe',
        'gn'   => array('John'),
        'mail' => array('john@doe.org', 'j.doe@example.org')
    )
);
?>

Changing attributes

Changing values is with the replace() method as easy as adding values. However, you have to be a little more careful. The expected parameter is an array describing the new absolute state of the named attributes. This means, if you specify a NULL value for an attribute, this attribute will get deleted! You may specify single values as string too. The keys of the array are expected to be the attributes names.

Changing attributes

<?php
// Changing several attributes:
// 'sn' is changed to "Smith", 'gn' gets deleted and mail will
// be changed to te two new adresses
$result = $entry->replace(
    array(
        'sn'   => 'Smith',
        'gn'   => null,
        'mail' => array('smith@example.org', 'smith@example.de')
    )
);
?>

Deleting attributes

Using the delete() method you are able to delete specific attributes values as well as delete a whole attribute. You need to specify the attribute names as array keys, the array values are the values you want to delete. If you want to delete whole attributes, specify them as single level array. Special care must be taken not to delete the whole entry which will be the case if the parameter array is omitted or set to NULL! Also, don't mix syntax modes. If you want to delete whole attributes you can't delete specific values from another attribute in the same function call.

Deleting attributes

<?php
// Delete the whole entry:
$result = $entry->delete();

// Delete the whole telephone number attribute:
$result = $entry->delete('telephoneNumber');

// Delete one specific mail attributes value:
$result = $entry->delete( array('mail' => 'j.doe@example.org') );

// Delete mail and telephone attributes as a whole:
$result = $entry->delete( array('mail', 'telephoneNumber') );

// Delete two specific mail adresses:
$result = $entry->delete( array('mail' => array('smith@example.org', 'smith@example.de')) );
?>

Changing Objectclasses

Object classes describe the attribute set of an entry with this objectclass set. The entry stores the objectclass in a special attribute named "objectClass", and of course you may alter that attribute like any other attribute.

However, special care must be taken if changing this attribute since most directory servers impose rules on the other attributes the object class define. For example, it is usually not possible to delete an objectclass if some of the attributes the class describes are still in use by the entry. This should be not much of a problem with optional attributes, but sometimes objectclasses have mandatory attributes set. Also structural objectclasses can only be added when creating new entrys. Because of the internal architecture of Net_LDAP it is currently not possible to resolve those cases.

To add or remove objectclasses with mandatory attributes or new structural object classes, you need to delete the old entry from the directory server and add the new one with the new objectclass and attributes as fresh entry.

Changing complex objectclasses

<?php
// Let's assume that the objectclass myClass enforce the attribute "fooattr"
// Take care that you have all attributes requested, otherwise the new
// entry will not have all attributes set!
$entry->add(array(
    'objectClass'   => 'myClass',
    'fooatrr'       => 'foo',
    'someotherattr' => array('bar', 'baz')
    ));

// Calling $entry->update() now will not succeed under some circumstances!
// We construct a fresh entry object which is in fact a copy of the already
// existing entry with all changes already applied (the local copy).
// It is important, that at fetching time of $entry all attributes where selected!
// Only the selected attributes will get copied.
$changed_entry = Net_LDAP_Entry::createFresh($entry->dn(), $entry->getValues());

// Now delete the old entry and add the new one:
$ldap->delete($entry);
$ldap->add($changed_entry);
?>
Prev | Net_LDAP | Next
Fetching entries | PEAR Manual | Managing entries


Managing entries

Managing entries

Managing entries – Adding/renaming/moving/deleting entries

Adding (fresh or old) entries to the directory

Adding new entries is performed in two ways. First, you need to establish a fresh Net_LDAP_Entry object. After that, you can add that entry like you would add already-existent entries using Net_LDAP's add() method.

Adding a fresh entry

<?php
// Build a new fresh entry:
$dn         = 'cn=new-admin,o=example,dc=org';
$attributes = array(
    'cn'              => 'new-admin',
    'mail'            => array('new-admin@exaple.org', 'n.admin@example.de'),
    'telephoneNumber' => '1234567890'
);
$entry = Net_LDAP_Entry::createFresh($dn, $attributes);

// Add the entry to the directory:
$ldap->add($entry);
?>

Renaming or moving entries

Renaming and/or moving an entry is an operation on the DN of an entry. Moving an entry means, to rename a DN in such a way, that the entry becomes a new base-DN. You can rename or move an entry, if you call the dn() method of the entry you want to relocate. Alternatively, you may call Net_LDAP's move() method that also ca handle only DNs. Remember that you must call the entires update() method to carry out the move/rename. Net_LDAP's move() will move the entry immediately. If you use an entryobject togehter with Net_LDAP's move(), you are able to perform cross directory moves.

Moving an entry using Net_LDAP_Entry

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap->getEntry($dn);

$entry->dn($newdn);
?>

Moving an entry using Net_LDAP and Net_LDAP_Entry

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap->getEntry($dn);

$ldap->move($entry, $newdn);
?>

Renaming an entry using Net_LDAP and DNs

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin2,o=new-example,dc=org';

$ldap->move($dn, $newdn);
?>

Performing a cross directory move

<?php
// $ldap_src is the source ldap and $ldap_tgt the target
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap_src->getEntry($dn);

$ldap_src->move($entry, $newdn, $ldap_tgt);
?>

Deleting entries

Deleting entries is performed using Net_LDAP's delete() method. Just pass the Net_LDAP_Entry object or the DN of the entry you want to delete. In the case that the DN contains subentrys, you need to pass TRUE as second parameter which will make delete() delete recursive.

A second way exist: You may simply call delete() from the Net_LDAP_Entry you want to delete. Don't forget that you must call update() to carry out the delete in this case.

Deleting an entry

<?php
$dn  = 'cn=new-admin,o=example,dc=org';
$ldap->delete($dn);
?>

Deleting an entry using a Net_LDAP_Entry object

<?php
$entry->delete();
$entry->update();
?>
Prev | Net_LDAP | Next
Attributes | PEAR Manual | LDAP filters


LDAP filters

LDAP filters

LDAP filters – Introduction to and usage of LDAP filters

What are LDAP filters?

LDAP filters are defined in RFC 2254 and can be compared to the WHERE clause in SQL select statements - they filter the data returned from some search request - in this case the entries returned from the directory server. With Net_LDAP, you may use plain strings as filters, or preferably, the Net_LDAP_Filter class which mostly releases you of the burden to escape yourself and to remember all the various special characters needed for constructing and combining filters.

Where and how to use filters is described in chapter Search.

Some LDIF filter basics

Although you should preferably use the Net_LDAP_Filter class to construct your LDAP filters, some theory may be interesting and helpful in understanding how to construct LDAP filters and what they are capable of.

Basic LDAP filters are composed of an "[attribute][operator][value]" pair enclosed by round brackets. There are several comparison operators available: "=" (equal), ">" (greater), "<" (less), ">=" (greater or equal), "<=" (less or equal) and "=~" (phonetical similar). The exact match behavior is defined by the attribute syntax of the attribute to which the filter should apply.

Some basic string filters

<?php
// Filter entries whose first name is 'Benedikt':
$filter = '(givenName=Benedikt)';

// Filter entries which have an employeenumber higher or equal than 1424:
$filter = '(employeeNumber>=1424)';

// Filter entries whose first name sounds similar to "Stephane"
// This should also find "Stephen" and "Stefan" (depending on implementation)
$filter = '(givenName=~Stephane)';
?>

The value part of the basic filter construct could also include a special character: "*". The star acts as placeholder for none, one or several characters at that position. "V*lue" would therefore match against "Value", "Vlue", "VaaAaAalue" and so on. There are some special named combinations using the star, but they work exactly the same way:

Special named placeholder combinations
Name | Filter | Description
present | (attr=*) | Also refered to as "any". Finds any entry containing any (unless empty) value for the named attribute.
begins | (attr=value*) | value starts with some fixed string
ends | (attr=*value) | value ends with some fixed string
contains | (attr=*value*) | value contains some fixed string

Combining string filters

Basic filters can be combined using the three logical operators "&" (and), "|" (or) and "!" (not). Note, that the smallest filter component, the basic filter enclosed in round brackets, remains isolated: instead of just adding another "[attribute][operator][value]" pair into the brackets, a new bracket level is introduced that contains all filter components that should be combined. Note also, that the logical operator does stand in front of all filter components, not between them as common in programming languages.

Combining string filters

<?php
// Search all 'Benedikt's with phone number 1234567890
    $filter = '(&(givenName=Benedikt)(telephoneNumber=1234567890))';

    // Search the same, but exclude person "Benedikt Foobar"
    // Note that the "not" is a logical operator and thus needs its own
    // surrounding bracket. This explains nicely, that each bracket level
    // is evaluated independently from surrounding brackets.
    $filter = '(&(givenName=Benedikt)(telephoneNumber=1234567890)(!(sureName=Foobar)))';
?>

The Net_LDAP_Filter class

As you will read below, there are some special characters inside the LDAP filter definition and thus must be escaped. These are mainly the special characters used directly by the filter syntax like braces and the logical operators. Despite those, there are some other cases which need special threatment. Nearly all of this cases are hidden through the Net_LDAP_Filter class so you should only consider using string filters if you need to or you know what you are doing. If you need a filter string, you may also use Net_LDAP_Filters toString() function after building the filter.

The filter class has two different usage models: one for constructing basic filters and another to combine them logically. This has to do with the syntax of LDAP filters you may read below.

Creating filters

For creating basic filter components, you need to use the create() factory method. There, you combine three items: an attribute to filter for, a matching rule for comparison and a value that is beeing compared with the servers entries. The given value is automatically escaped, so you need take care if you want to use the star placeholder. In this case, you need to pass FALSE as fourth parameter to create() which causes value to be threaten as-is. This of course also means, that you need to escape the parts of the value that may contain restricted characters yourself using Net_LDAP_Util::escape_filter_value(). To learn what characters are restricted, refer to RFC 2254 or the documentation of Net_LDAP_Util::escape_filter_value(); otherwise its safe to always escape.

The matching rules partly follow the basic filter matching rules described above, but are enhanced to make your life easier:

create()s matching rules
Rule | Description
equals | One of attributes values is exactly value. Please note that case sensitiviness depends on the matching rule defined in the attributes schema syntax.
begins | One of attributes values must begin with value
ends | One of attributes values must end with value
contains | One of attributes values must contain value
present | any | The attribute can contain any value but must be existent
greater | The attributes value is greater than value
less | The attributes value is less than value
greaterOrEqual | The attributes value is greater or equal than value
lessOrEqual | The attributes value is less or equal than value
approx | One of attributes values sounds similar to value. The matching behavior depends on the server implementation.

Creating LDAP filters

<?php
// Filter entries whose first name is 'Benedikt':
$filter = Net_LDAP_Filter::create('givenName', 'equals', 'Benedikt');

// Filter entries whose first name starts with 'Steph':
$filter = Net_LDAP_Filter::create('givenName', 'begins', 'Steph');

// Filter entries containing 'Lone*'; matching the star character.
// The automatic escaping of $value will conveniently escape the star for us.
$filter = Net_LDAP_Filter::create('givenName', 'contains', 'Lone*');

// Filter entries containing 'Foo[something]Bar'; not matching the star character.
// For this to work, we need to disable automatic escaping of $value by passing
// false as fourth parameter. This however implies, that we take care of
// proper escaping, which is showed in the example.
$escaped_values = Net_LDAP_Util::escape_filter_value(array('Foo', 'Bar'));
$foo =& $escaped_values[0];
$bar =& $escaped_values[1];
$filter = Net_LDAP_Filter::create('givenName', 'contains', "$foo*$bar", false);

// Filter entries whose first name sounds similar to "Stephane"
// This should also find "Stephen" and "Stefan" (depending on implementation)
$filter = '(givenName=~Stephane)';
?>

Combining filters

Although the filters can be used stand alone, they can be combined to match sophisticated search requiremets. This is done by using the combine() to combine several present Net_LDAP_Filter objects using a logical operator. The execption is the not operator since it only allows one filter object to be negated.

combine()s operators
Rule | Description
and | All filter components must evaluate to true for the combined filter to be true
or | At least one filter component must evaluate to true for the combined filter to be true
not | The result of the filter component is inversed (true becomes false and vice versa). Note that this operator only accepts one filter object.

Combining LDAP filters

<?php
// Create some test filters
$filter_benedikt = Net_LDAP_Filter::create('givenName', 'equals', 'Benedikt');
$filter_steph    = Net_LDAP_Filter::create('givenName', 'begins', 'Steph');
$filter_foobar   = Net_LDAP_Filter::create('sureName', 'equals', 'Foobar');
$filter_height   = Net_LDAP_Filter::create('personHeight', 'greater', '175');

// Negate 'foobar' filter.
// This filters every entry whose sure name is not 'Foobar'
$filter_not_foobar = Net_LDAP_Filter::combine('not', $filter_foobar);

// Build a 'and' combination to be able to search for people whose
// first names start with 'Steph' and who are are taller than 175
// except those whose surname is 'Foobar'
$filter_stephs_tall = Net_LDAP_Filter::combine('and',
    array($filter_steph, $filter_height, $filter_not_foobar));

// In any case, add every person whose first name is
// 'Benedikt' to the search result.
$filter_add_benedikt = Net_LDAP_Filter::combine('or', array($filter_benedikt, $filter_stephs_tall));
?>

Advanced features

You may need some advanced functionality if you have to deal with string representation of filters.

Advanced methods
Method | Description
parse() | Takes an filter string and parses it into a Net_LDAP_Filter object. It also verifies, that the filter syntax is correct.
printMe() | In PERLs interface, this method is called "print" but due to language constraints, we cannot use that name. Prints the string representation of this filter object to standard output or to an optional filehandle passed as parameter.
toString() | Returns the string representation of the filter object.
Prev | Net_LDAP | Next
Managing entries | PEAR Manual | LDIF files


LDIF files

LDIF files

LDIF files – Converting between Net_LDAP_Entries and LDIF files

Avaible since

LDIF support was added to Net_LDAP in release 1.1.0a1.

What are LDIF files?

LDIF files are in detail described at RFC 2849. Shortly, they contain directory data in an plain text, human readable kind, much like a SQL file does. However, unlike SQL files LDIF files are mostly data based, not action based. There are two different LDIF file contents, which can be mixed freely - content and change files. The first and most often used one is the LDIF content file:

Example LDIF content file

#
# This is a content LDIF file.
# It contains one single entry featuring several
# attributes and one comment (this one).
# attr1, attr4 and cn are single valued, the others are
# multivalued. objectclass is a special case, LDAP servers
# will interpret this operational attribute to define the
# classes the object will belong to and thus, which attributes
# it may contain. the OCL-attribute is usually multivalued.
#
version: 1
dn: cn=test1,ou=example,dc=cno
objectclass: someobjectclass
attr1: 12345
attr2: 1234
attr2: baz
attr3: foo
attr3: bar
attr4: brrrzztt
cn: test1

LDIF files could describe not only the data an entry contains, but also various changes to the entry itself. If such an LDIF file would then be given to a LDAP server, he would interpret those changes instead just importing the data. Note in the example below, that even though LDIF content and LDIF change files could be mixed freely, this is not true for individual entries: a specific entry may be either describing content or changes, but not both.

Example LDIF change file

#
# This is a content+change LDIF file.
# It does contain the (shortened) entry from the example above to show
# that LDIF files can contain multiple entry modes.
# The second entry is a change entry. In this case, some
# operations will be done on the entries attributes.
#
version: 1
dn: cn=test1,ou=example,dc=cno
objectclass: someobjectclass
attr1: 12345
cn: test1

# Delete attr1, replace values of attr2 and add new attribute attr42
# The attribute "changetype" is special: it says, what to do with
# this entries dataset. It could also be "delete" or "add" to delete
# a whole entry or to add a completely fresh one. "modrdn" will
# move the entry to a new location once the LDIF file is imported.
dn: cn=test2,ou=example,dc=cno
changetype: modify
delete: attr1
-
replace: attr2
attr2: 123456_newtest
-
add: attr42
attr42: the answer

Error handling when using Net_LDAP_LDIF

Before we can start using Net_LDAP_LDIF we must say some short words about how error handling works. Net_LDAP_LDIF was designed to have mostly the same API as the original PERL Net::LDAP::LDIF has. Because of this, the methods of Net_LDAP_LDIF do not return a Net_LDAP_Error object. You must use the error() method that will return a Net_LDAP_Error object in case of failure or true in case everything was ok. In LDIF reading mode, you can additionally use error_lines() to get knowledge about where in the input file the error occured.

Construction and options

Regardless if you want to read or write a LDIF file, you always have to use the constructor of Net_LDAP_LDIF to initialize your access to the LDIF file. You need to pass at least one parameter to Net_LDAP_LDIF(): the path of the file that should be read or written. You may pass the open mode as second parameter. The possible file open modes are "r" (read), "w" (write, clears the file first) and "a" (append to the end). In case you omit the open mode, read mode is assumed. The third optional parameter is an associative array containing one or several of the following options:

Possible configuration options
Name | Description | Default
encode | Some DN values in LDIF cannot be written verbatim and have to be encoded in some way. Possible values are: "none", "canonical" and "base64" (RFC default) | base64
onerror | What should be done on errors? "undef" will let error handling in your hands, in this case you use error() and error_lines() to process errors manually. "die" aborts the script printing the error - this is sometimes useful for CLI scripts. "warn" just prints out the error but continues like "undef" would. | undef
change | Turning this to "1" (true) will tell Net_LDAP_LDIF to write change sets instead of content files. | false
lowercase | Set this to true to convert attribute names to lowercase when writing. | 0
sort | If true, sort attribute names when writing entries according to the rule: objectclass first then all other attributes alphabetically sorted by attribute name | 0
version | Set the LDIF version to write to the resulting LDIF file. According to RFC 2849 currently the only legal value for this option is 1 currently. | 1
wrap | Number of columns where output line wrapping shall occur. Setting it to 40 or lower inhibits wrapping. Useful for better human readability of the resulting file. | 78

For advanced users: instead of passing a file path, you also may pass an already initialized file handle. In this case, the mode parameter will be ignored. You may use this, if you want to mix LDIF content and LDIF change mode by using two Net_LDAP_LDIF instances to write to the same filehandle, but it could be very useful in other cases too. To initialize the second instance of Net_LDAP_LDIF, you can use handle() to get the filehandle from the first instance.

Reading a LDIF file into Net_LDAP_Entry-objects

One of the two modes how Net_LDAP_LDIF can be used is to read a LDIF file and parse its contents into an array of Net_LDAP_Entry objects. This is done using the read_entry()-method which will return the next entry. If you want to fetch all entries, you use the eof() to detect the end of the input file:

Parsing a LDIF file into Net_LDAP_Entry objects

<?php
// open some LDIF file for reading
$ldif = new Net_LDAP_LDIF('somefile.ldif', 'r');
if ($ldif->error()) {
    $error_o = $ldif->error(); // get Net_LDAP_Error object on error
            die('ERROR: '.$error_o->getMessage());
}

// parse the entries of the LDIF file into objects
 do {
    $entry = $ldif->read_entry();
    if ($ldif->error()) {
        // in case of error, print error.
        // here we use the shorthand parameter, so error()
        // returns a string instead of a Net_LDAP_Object
        die('ERROR AT INPUT LINE '.$ldif->error_lines().': '.$ldif->error(true));
    } else {
        // No error: do something with the entry
        // Here we just print the entries DN
        echo 'sucessfully parsed '.$entry->dn();
    }
} while (!$ldif->eof());

// We should call done() once we are finished
$ldif->done();
?>

Writing Net_LDAP_Entry objects to a LDIF content file

Writing an LDIF file is very easy too. Just pass the entries you want to have written to the write_entry()-method. Beware, that if you have opened the file in "w" write mode this will clear any previous data of that file. Use "a" (append) if you just want add data.

Writing entries

<?php
// Assume we have some valid Net_LDAP_Entry objects inside $entries
        // $entries = array( ... );

        // open some file for writing
        $ldif = new Net_LDAP_LDIF('somewritefile.ldif', 'w');
        if ($ldif->error()) die('ERROR: '.$error_o->getMessage());

        // write the data and check for error
        // you could pass one single Net_LDAP_Entry object or
        // several objects inside an array
        $ldif->write_entry($entries);
        if ($ldif->error()) die('WRITE ERROR: '.$error_o->getMessage());
?>

Writing Net_LDAP_Entry objects to a LDIF change file

The process of writing changes is exactly the same like writing entry contents. However there are two differences: Firstly you need to pass the "changes" option and secondly, the entries you want to write need changes. Entries not containing changes will silently be ignored since there is nothing to write.

Writing entry changes

<?php
// cast some test data and three entries
        $testattrs = array(
                'attr1' => '1234',
                'attr2' => 'foo',
                'attr3' => array('bar', 'baz')
            );
        $entries = array(
                Net_LDAP_Entry::createFresh('cn=foo,dc=example,dc=cno',
                    array_merge(array('cn' => 'foo'), $testattrs)),
                Net_LDAP_Entry::createFresh('cn=bar,dc=example,dc=cno',
                    array_merge(array('cn' => 'bar'), $testattrs)),
                Net_LDAP_Entry::createFresh('cn=baz,dc=example,dc=cno',
                    array_merge(array('cn' => 'baz'), $testattrs))
            );

        // make some changes to the first and the last entry
        $entries[0]->add(array('someattr' => 'added'));
        $entries[0]->replace(array('attr1' => 'replaced'));
        $entries[2]->delete(array('attr2'));
        $entries[2]->delete(array('attr3' => 'bar'));

        // open some file for writing, but in change mode
        $ldif = new Net_LDAP_LDIF('somewritefile.ldif', 'w', array('change' => true));
        if ($ldif->error()) die('ERROR: '.$error_o->getMessage());

        // write the data and check for error
        // you could pass one single Net_LDAP_Entry object or
        // several objects inside an array
        $ldif->write_entry($entries);
        if ($ldif->error()) die('WRITE ERROR: '.$error_o->getMessage());

        // Now, only two entries are contained in the LDIF file,
        // cn=foo,dc=example,dc=cno and cn=baz,dc=example,dc=cno.
        // cn=bar,dc=example,dc=cno had no changes and was skipped.
?>

Resulting LDIF change file

version: 1
dn: cn=foo,dc=example,dc=cno
changetype: modify
add: someattr
someattr: added
-
replace: attr1
attr1: replaced
-

dn: cn=baz,dc=example,dc=cno
changetype: modify
delete: attr2
-
delete: attr3
attr3: bar
-

Fetching LDIF data

Sometimes you are interested in the lines inside the LDIF file. For those cases you can use the current_lines() and next_lines() methods. They work in the current context, which may be confusing: current_lines() will always return the lines that have built up the current Net_LDAP_Entry object when called current_entry() after read_entry() has been called. next_lines() will always return the lines, that will build up the next entry from the current point of view, meaning "relative to the entry that was just been read". However, you can override this by activating the "force" parameter of next_lines() which allows you to loop over all entries. current_entry() behaves exactly like current_lines().

If you think, that the lines you have read would be better in form of an Net_LDAP_Entry object, use the parseLines() method to parse those lines into an entry. This is a good way if you need just a few specific entries of a large LDIF file.

Reading LDIF lines

<?php
// open some LDIF file for reading
// (error checking code is ommitted in this example for
//  better readability - in production, test for errors!)
$ldif = new Net_LDAP_LDIF('somefile.ldif', 'r');

// since nothing has been read until now, this will
// return an empty array
$empty_array = $ldif->current_lines();

// so let's read the first entries data
$first_entry_lines = $ldif->next_lines();

// if we call it again, we will not read ahead to the
// second entry - we again read the first one!
$first_entry_lines_again = $ldif->next_lines();

// If we call current_lines() now, we haven't read ahead
// like we learned from the last statement.
$empty_array_again = $ldif->current_lines();

// If we want to shift, we must use
// the read_entry() method, which will read ahead.
$first_entry = $ldif->read_entry();

// Now, current_lines() returns the lines of the
// first entry and next_lines() the lines of the second:
$first_entry_lines  = $ldif->current_lines();
$second_entry_lines = $ldif->next_lines();

// There is another way to shift the lines which is faster if
// you are just interested in the LDIFs content - you
// need to pass the "force" parameter to next_lines():
$third_entry_lines  = $ldif->next_lines(true);
$fourth_entry_lines = $ldif->next_lines(true);
$fifth_entry_lines  = $ldif->next_lines(true);

// If you want to convert the lines to an Net_LDAP_Entry,
// you may do so anytime by using parseLines()
$fourth_entry = $ldif->parseLines($fourth_entry_lines);

// Since we shifted manually only the lines,
// current_lines() will return the lines that built up the
// last (e.g. the first entry) Net_LDAP_Entry object:
$first_entry_lines  = $ldif->current_lines();

// If we decide to read the next entry, we can do that:
$sixth_entry = $ldif->read_entry();

// current_lines() is shifted now:
$sixth_entry_lines = $ldif->current_lines();
?>
Prev | Net_LDAP | Next
LDAP filters | PEAR Manual | Net_LDAP2


Net_LDAP2

Net_LDAP2

Net_LDAP2 allows you to query and manipulate the data stored in directory servers using PHP in an object-oriented way.

Detailed usage examples are available at: /your/pear/path/docs/Net_LDAP2/examples/

Table of Contents
  • Introduction -- What Net_LDAP2 is and general information
  • Error handling -- How handling errors works in Net_LDAP2
  • Configuration and connecting -- How to configure Net_LDAP2 and connect to an LDAP server
  • Search -- Searching entries
  • Fetching entries -- Retrieving entries directly or from a searchresult
  • Attributes -- Reading/adding/changing/deleting attributes from entries
  • Managing entries -- Adding/renaming/moving/deleting entries
  • LDAP filters -- Introduction to and usage of LDAP filters
  • LDIF files -- Converting between Net_LDAP2_Entries and LDIF files
  • Schema caching -- How to enable schema caching
Prev | Networking | Next
LDIF files | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What Net_LDAP2 is and general information

Welcome to Net_LDAP2!

Net_LDAP2 is a clone of Perls Net::LDAP package. PEAR Net_LDAP2 for PHP does, besides some own features, provide most of Perl Net::LDAP methods. Net_LDAP2 allows you to query and manipulate the data stored in directory servers using PHP in an object-oriented way. A directory server is a database server providing a hierarchical database and is usually queried using the LDAP protocol.

Net_LDAP2 is intendet as replacement of Net_LDAP.

Classes of the Net_LDAP2 package

The following table gives you a short overview which classes are available in Net_LDAP2 and what they can be used for. Their relations will be explained too.

Classes of Net_LDAP2
Class name | Description
Net_LDAP2 | This is the main class. It enables you to connect and bind to a LDAP-server and to run ldap-querys like searching and manipulating entries. Most common, you will run a search using a LDAP-Filter and will get a Net_LDAP2_Search-object. You may also fetch an entry directly, which gives you a Net_LDAP2_Entry-object.
Net_LDAP2_Search | Objects of this class are returned from search querys. You can use this object to retrieve informations about a search result, like how much entries you have found for the provided filter. You can retrieve the found entries as Net_LDAP2_Entry-objects in various forms: sorted, consecutively starting from the end or beginning or unsorted at once.
Net_LDAP2_Entry | Objects of this kind are either produced by casting fresh entries manually, by retrieving the result of a LDAP-search or by fetching an entry directly. It gives you the possibility to read and/or manipulate the attributes of an entry which describes the characteristic of the specific object.
Net_LDAP2_Util | The utility class contains only static methods, so you should not need to make an instance of it. It features some helpful methods, some of them are used internally by Net_LDAP2 but may be used externally from you as well. The most methods deal with escaping issues, since LDAP has some metacharacters with special meaning so that they usually need to be properly escaped.
Net_LDAP2_Filter | You are free to give LDAP-Filters on your own to the Net_LDAP2->search() method, however this has some drawbacks (including escaping issues). For this reason, you can use the Net_LDAP2_Filter class to easily build and combine your filters. LDAP filters are extensively explained at the chapter LDAP filters.
Net_LDAP2_Error | This is a error class. Most methods of Net_LDAP2 will return a object of this class if something went wrong. You can use this object to identify errors and to get detailed knowledge on what went wrong. See Errorhandling for more information.
Net_LDAP2_LDIF | LDIF files are human readable, plain text files containing directory data and/or change commands, much like an SQL file. Unlike SQL files, it is data centric, not action centric. Net_LDAP2_LDIF enables you to convert between Net_LDAP2_Entry-objects and LDIF files. Please note, that Net_LDAP2_LDIF has a little different error handling explained later.
Net_LDAP2_SimpleFileSchemaCache | Net_LDAP2 features a schema caching facility. This class implements a simple file based cache that allows Net_LDAP2 to store the schema data that get fetched from LDAP inside a file to accelerate schema access. Caching the schema can gain some performance, especially with slow servers or connections. You may use this cache class for example to store the schema object in a linux tmpfs which will result in caching the schema in the computers memory, enabling nearly instant access. This cache also features a cache ageing mechanism. Please see Schema caching for more information.
Prev | Net_LDAP2 | Next
Net_LDAP2 | PEAR Manual | Error handling


Error handling

Error handling

Error handling – How handling errors works in Net_LDAP2

Error handling

Nearly all of Net_LDAPs methods return a Net_LDAP2_Error object if something went wrong. You always should check for errors after you performed an action to be sure that your application doesn't do things you don't want it to do.

Handling errors is an easy task, you just have to test the return value as shown below. If an error occured, you can halt the script for example. In other cases, you may just log the error, but what exactly happens depends on your specific situation, of course.

You can use the getMessage() method of the error object to retrieve the error message explaining the problem and getCode() to get the error code which is usually the LDAP-Error code (see Table below) and may be used for automated reaction on errors.

Dealing with errors

<?php
// Perform an arbitrary action:
$result = $ldap->search($searchbase, $filter, $options);

// Check, if an error occured and do something.
// Here we use die() to show the message of the error.
if (PEAR::isError($result)) {
    die($result->getMessage());
}
?>
Error codes Net_LDAP2
Error code | Description
0x00 | LDAP_SUCCESS
0x01 | LDAP_OPERATIONS_ERROR
0x02 | LDAP_PROTOCOL_ERROR
0x03 | LDAP_TIMELIMIT_EXCEEDED
0x04 | LDAP_SIZELIMIT_EXCEEDED
0x05 | LDAP_COMPARE_FALSE
0x06 | LDAP_COMPARE_TRUE
0x07 | LDAP_AUTH_METHOD_NOT_SUPPORTED
0x08 | LDAP_STRONG_AUTH_REQUIRED
0x09 | LDAP_PARTIAL_RESULTS
0x0a | LDAP_REFERRAL
0x0b | LDAP_ADMINLIMIT_EXCEEDED
0x0c | LDAP_UNAVAILABLE_CRITICAL_EXTENSION
0x0d | LDAP_CONFIDENTIALITY_REQUIRED
0x0e | LDAP_SASL_BIND_INPROGRESS
0x10 | LDAP_NO_SUCH_ATTRIBUTE
0x11 | LDAP_UNDEFINED_TYPE
0x12 | LDAP_INAPPROPRIATE_MATCHING
0x13 | LDAP_CONSTRAINT_VIOLATION
0x14 | LDAP_TYPE_OR_VALUE_EXISTS
0x15 | LDAP_INVALID_SYNTAX
0x20 | LDAP_NO_SUCH_OBJECT
0x21 | LDAP_ALIAS_PROBLEM
0x22 | LDAP_INVALID_DN_SYNTAX
0x23 | LDAP_IS_LEAF
0x24 | LDAP_ALIAS_DEREF_PROBLEM
0x30 | LDAP_INAPPROPRIATE_AUTH
0x31 | LDAP_INVALID_CREDENTIALS
0x32 | LDAP_INSUFFICIENT_ACCESS
0x33 | LDAP_BUSY
0x34 | LDAP_UNAVAILABLE
0x35 | LDAP_UNWILLING_TO_PERFORM
0x36 | LDAP_LOOP_DETECT
0x3C | LDAP_SORT_CONTROL_MISSING
0x3D | LDAP_INDEX_RANGE_ERROR
0x40 | LDAP_NAMING_VIOLATION
0x41 | LDAP_OBJECT_CLASS_VIOLATION
0x42 | LDAP_NOT_ALLOWED_ON_NONLEAF
0x43 | LDAP_NOT_ALLOWED_ON_RDN
0x44 | LDAP_ALREADY_EXISTS
0x45 | LDAP_NO_OBJECT_CLASS_MODS
0x46 | LDAP_RESULTS_TOO_LARGE
0x47 | LDAP_AFFECTS_MULTIPLE_DSAS
0x50 | LDAP_OTHER
0x51 | LDAP_SERVER_DOWN
0x52 | LDAP_LOCAL_ERROR
0x53 | LDAP_ENCODING_ERROR
0x54 | LDAP_DECODING_ERROR
0x55 | LDAP_TIMEOUT
0x56 | LDAP_AUTH_UNKNOWN
0x57 | LDAP_FILTER_ERROR
0x58 | LDAP_USER_CANCELLED
0x59 | LDAP_PARAM_ERROR
0x5a | LDAP_NO_MEMORY
0x5b | LDAP_CONNECT_ERROR
0x5c | LDAP_NOT_SUPPORTED
0x5d | LDAP_CONTROL_NOT_FOUND
0x5e | LDAP_NO_RESULTS_RETURNED
0x5f | LDAP_MORE_RESULTS_TO_RETURN
0x60 | LDAP_CLIENT_LOOP
0x61 | LDAP_REFERRAL_LIMIT_EXCEEDED
1000 | Unknown Net_LDAP2 Error
Prev | Net_LDAP2 | Next
Introduction | PEAR Manual | Configuration and connecting


Configuration and connecting

Configuration and connecting

Configuration and connecting – How to configure Net_LDAP2 and connect to an LDAP server

Connecting to an LDAP server

To connect to an LDAP server, you should use Net_LDAP2's static connect() method. It takes one parameter, an array full of configuration options, and either returns a Net_LDAP2 object if connecting works, or a Net_LDAP2_Error object in case of a failure.

The following table lists all configuration options. If the default value for an option fits your needs, you don't need add it to your configuration array.

Possible configuration options
Name | Description | Default
host | LDAP server name to connect to. You can provide several hosts in an array in which case the hosts are tried from left to right. | localhost
port | Port on the server | 389
version | LDAP version | 3
starttls | TLS is started after connecting | false
binddn | The distinguished name to bind as (username) | (none)
bindpw | Password for the binddn | (none)
basedn | LDAP base name (root directory) | (none)
options | Array of additional ldap options as key-value pairs | array()
filter | Default search filter (string or preferably Net_LDAP2_Filter object). See LDAP filters | (objectClass=*)
scope | Default search scope, see Search | sub

Connecting to an LDAP server

<?php
// Inclusion of the Net_LDAP2 package:
require_once 'Net/LDAP.php';

// The configuration array:
$config = array (
    'binddn'    => 'cn=admin,ou=users,dc=example,dc=org',
    'bindpw'    => 'password',
    'basedn'    => 'dc=example,dc=org',
    'host'      => 'ldap.example.org'
);

// Connecting using the configuration:
$ldap = Net_LDAP2::connect($config);

// Testing for connection error
if (PEAR::isError($ldap)) {
    die('Could not connect to LDAP-server: '.$ldap->getMessage());
}
?>
Prev | Net_LDAP2 | Next
Error handling | PEAR Manual | Search


Search

Search

Search – Searching entries

A short note on DNs

It may be possible that restricted characters (",", "+", """, "\", "<", ">", ";", "#", "=", space or a hexpair) are used in attributes or values inside the DN. You should have a look to the APIdoc of Net_LDAP2_Util::escape_dn_value(), Net_LDAP2_Util::unescape_dn_value(), Net_LDAP2_Util::ldap_explode_dn() and Net_LDAP2_Util::canonical_dn(). These functions can be used to safely handle DNs.

Searching some entries

After connecting to the server, you can use Net_LDAP2's search() method to search the directory. The method takes three parameters:

  • $base is the base search DN. If kept null, the default base DN configured when connecting is used.

  • $filter is the query filter that determines which results are returned. It is either a string (experts use only) or better a Net_LDAP2_Filter-object. Net_LDAP2_Filter automatically deals with LDAP-Filter escaping issues. LDAP filters are extensively explained at the chapter LDAP filters.

  • $params is an array of configuration options for the current query.

    Possible configuration parameters
    Name | Description | Default
    scope The scope used for searching:

    • base - Just one entry

    • sub - The whole tree

    • one - Immediately below $base

            sub
    sizelimit | Number of entries returned at maximum | 0 (no limit)
    timelimit | Seconds to spent for searching | 0 (no limit)
    attrsonly | If true, only attribute names are returned | false
    attributes | Array of attribute names, which the entry should contain. It is good practice to limit this to just the ones you need. | array() (all attributes)

The search() method will return either a Net_LDAP2_Search object or a Net_LDAP2_Error. You can use the Net_LDAP2_Search-object to trigger further actions like counting how many entries where found or to retrieve the found entries.

Making a search query

<?php
// Building a very basic filter
// we want to find all Entries whose surnames start with "Joe":
$filter = Net_LDAP2_Filter::create('sn', 'begins',  'Joe');

// We define a custom searchbase here. If you pass NULL, the basedn provided
// in the Net_LDAP2 configuration will be used. This is often not what you want.
$searchbase = 'ou=addressbook,dc=example,dc=org';

// Some options:
// We search all subtrees beneath 'ou=addressbook,dc=example,dc=org'
// and we select the attribute 'sn'. It is a good practice to limit the
// requested attributes to only those you actually want to use later.
// However, note that it is faster to select unneeded attributes than
// refetching an entry later to just get those attributes.
$options = array(
    'scope' => 'sub',
    'attributes' => array('sn')
);

// Perform the search!
$search = $ldap->search($searchbase, $filter, $options);

// Test for search errors:
if (PEAR::isError($search)) {
    die($search->getMessage() . "\n");
}

// Say how many entries we have found:
echo "Found " . $search->count() . " entries!";
?>
Prev | Net_LDAP2 | Next
Configuration and connecting | PEAR Manual | Fetching entries


Fetching entries

Fetching entries

Fetching entries – Retrieving entries directly or from a searchresult

Retrieving entries directly

You can retrieve directory entries in several ways, either directly or from a performed search request. If you want to fetch an entry directly, you need to know its absolute distinguished name (DN). To directly fetch an known entry from the directory server, you use Net_LDAP2's getEntry() method. It takes two parameters: The DN of the entry and the attributes you want to read from the entry. It returns a Net_LDAP2_Entry object if fetching worked, or a Net_LDAP2_Error object in case of a failure.

You may also check if the entry exists in the server before you fetch it. This can be achieved by Net_LDAP2's dnExists() which takes the DN to test and returns either true or false.

Fetching an entry directly

<?php
// Defining the DN we want to fetch;
// we want to select the given- and the surname
$dn = 'cn=admin,o=example,dc=org';
$entry = $ldap->getEntry($dn, array('gn', 'sn'));

// Error checking is important!
if (Net_LDAP2::isError($entry)) {
    die('Could not fetch entry: '.$entry->getMessage());
}
?>

Retrieving entries from a searchresult

The second way to retrieve entries is from a searchresult. As described in chapter "Search", you access the entries of a search result through the Net_LDAP2_Search-object resulting from Net_LDAP2's search() method. Each of the following methods return a Net_LDAP2_Error-object if something goes wrong, so remember to test for errors! You have several ways to read the entries:

Possible ways to fetch entries
Method of Net_LDAP2_Search | Description
entries() | This returns the entries at once unsorted.
as_struct() | This returns all entries as multidimensional array instead of Net_LDAP2_Entry-objects. The array keys of the first dimension are the DNs and the value is an array containing all attributes. The array keys of the second level are the attributes names; the value of the second level is an array containing all the attributes values. Note, that even if there are no or just one value, an array is present.
sorted() | Use this if you want to get the entries at once but sorted. You can sort by several attributes which can contain multiple values. You can of course sort ascending (default) or descending - just pass the PHP constant SORT_ASC or SORT_DESC as second parameter.
sorted_as_struct() | Like as_struct(), this returns the entries as multidimensional array, but in this case sorted. For parameters, see sorted()
shiftEntry() | This returns one entry from the beginning of the search result. Since this returns FALSE if all entries are fetched, shiftEntry() is perfectly appropriate to get used inside a while-loop. Take care not to mix shiftEntry() and popEntry()!
popEntry() | Exactly the same as shiftEntry, but returns the entry from the end of the searchresult. Again, be sure to not mix shiftEntry() and popEntry()!

To directly fetch an known entry from the directory server, you use Net_LDAP2's getEntry() method. It takes two parameters: The DN of the entry and the attributes you want to read from the entry. It returns a Net_LDAP2_Entry object if fetching worked, or a Net_LDAP2_Error object in case of a failure.

You may also check if the entry exists in the server before you fetch it. This can be achieved by Net_LDAP2's dnExists() which takes the DN to test and returns either true or false.

Fetching all entries from searchresult

<?php
// return all entries:
$entry = $search->entries();
?>

Fetching all entries from searchresult: sorted

<?php
// return sorted by first 'sn' then 'gn', but descending:
$entry = $search->sorted(array('sn', 'gn'), SORT_DESC);
?>

Fetching entries one by one inside a while loop

<?php
// return entries one by one:
while ( $entry = $search->shiftEntry() ) {
    // do something, like printing the DN of the entry;
    // in a real case, dont forget to test for errors!
    echo "ENTRY: " . $entry->dn();
}
?>

Retrieving entries via iteration (foreach)

Since Net_LDAP2 you are able to use PHPs Standard Library (SPL) to iterate over search results. This is done easily by just using the Net_LDAP2_Search search result object inside an foreach loop similar to an array. You may optionally retrieve the DN of each entry by the same mechanism you use to retrieve the key of an associative array.

Fetching entries via foreach()

<?php
foreach ($search as $dn => $entry) {
    // do something:
    $sn = $entry->getValue('sn', 'single');
    echo "Fetched DN: $dn; Surname: $sn";
}
?>
Prev | Net_LDAP2 | Next
Search | PEAR Manual | Attributes


Attributes

Attributes

Attributes – Reading/adding/changing/deleting attributes from entries

Reading attributes

Reading attribute values depends on the selection of those attributes at search time. You can only access attributes that where selected! You can read attribute values using either Net_LDAP2_Entry's getValues() or getValue() method. getValue() will return an array where the keys are the attributes names. If you use getValues() you may pass an option:

  • 'single': only the first value is returned as string

  • 'all': all values including the value count are returned in an array

  • 'default': in all other cases an attribute value with a single value is returned as string, if it has multiple values it is returned as an array (without value count)

Reading attributes

<?php
// read Surename, singlevalued
$surename = $entry->getValue('sn', 'single');

// read mail adress which may be multivalued
$mail = $entry->getValue('mail', 'all');
?>

If you want to read the distinguished name of an Entry (DN), you must use a different method: dn()

Reading an entries DN

<?php
$dn = $entry->dn();
?>

Regular expressions on attributes

PEAR::Net_LDAP2 has the unique feature to apply a regular expression match directly against attributes, so you do not need to manually fetch all values and run the regex against them. Instead, you can use Net_LDAP2_Entry's preg_match() function. The behavior of this function is the same as PHPs preg_match(), but the $matches array is slightly different. It features one dimension more, since it may match for several attribute values if the attribute is multivalued. If you pass $matches, be sure to do it via REFERENCE, because otherwise $matches remains empty. preg_match() returns true or false, depending on match.

Performing preg_match on attribute values

<?php
// Look, if the user has an emailadress for 'example', if so,
// we want to display the tld:
// (be sure to pass $matches as reference!)
$matches = array();
if ( $entry->preg_match('mail', '/example\.(.+)/', &$matches) ) {
    // print every TLD found for 'example':
    foreach ($matches as $match) {
        echo $match[1];
    }
}
?>

General information regarding attribute changing

It is important to know how attribute changing works. Modifications to an entry through the Net_LDAP2_Entry-object are local only. After you have made all changes and want to transfer them to the directory server, you must call update() of the Net_LDAP2_Entry object. This will return either TRUE or an Net_LDAP2_Error. Another good information is, that you must select attributes at search time if you want to add/change/delete attribute values. Otherwise Net_LDAP2 will most likely fail silently giving you the wrong assumtion that everything was okay - Net_LDAP2 needs knowledge of the attributes it should work with!

Modification of attributes is also possible through Net_LDAP2's modify() method. This method will call the methods described here on the Net_LDAP2_Entry object given, and directly calls an update() after that, thus performing the changes directly on the server. The parameter is an complex array describing the changes to be performed. It is considered for more advanced users, because it is more compact, so please refer to the latest API documentation for more information.

Adding attributes

Adding attrbiute values to an entry is an easy task. You just need to call add()! The parameter is an array whose keys are the attribute names and values the attributes values. If only one attribute value should be added, the second level may be a string. If the attribute doesn't exist so far, it will be added, if it exists, the attributes values will be added.

Adding attributes

<?php
// Adding several attributes:
$result = $entry->add(
    array(
        'sn'   => 'Doe',
        'gn'   => array('John'),
        'mail' => array('john@doe.org', 'j.doe@example.org')
    )
);
?>

Changing attributes

Changing values is with the replace() method as easy as adding values. However, you have to be a little more careful. The expected parameter is an array describing the new absolute state of the named attributes. This means, if you specify a NULL value for an attribute, this attribute will get deleted! You may specify single values as string too. The keys of the array are expected to be the attributes names.

Changing attributes

<?php
// Changing several attributes:
// 'sn' is changed to "Smith", 'gn' gets deleted and mail will
// be changed to te two new adresses
$result = $entry->replace(
    array(
        'sn'   => 'Smith',
        'gn'   => null,
        'mail' => array('smith@example.org', 'smith@example.de')
    )
);
?>

Deleting attributes

Using the delete() method you are able to delete specific attributes values as well as delete a whole attribute. You need to specify the attribute names as array keys, the array values are the values you want to delete. If you want to delete whole attributes, specify them as single level array. Special care must be taken not to delete the whole entry which will be the case if the parameter array is omitted or set to NULL! Also, don't mix syntax modes. If you want to delete whole attributes you can't delete specific values from another attribute in the same function call.

Deleting attributes

<?php
// Delete the whole entry:
$result = $entry->delete();

// Delete the whole telephone number attribute:
$result = $entry->delete('telephoneNumber');

// Delete one specific mail attributes value:
$result = $entry->delete( array('mail' => 'j.doe@example.org') );

// Delete mail and telephone attributes as a whole:
$result = $entry->delete( array('mail', 'telephoneNumber') );

// Delete two specific mail adresses:
$result = $entry->delete( array('mail' => array('smith@example.org', 'smith@example.de')) );
?>

Changing Objectclasses

Object classes describe the attribute set of an entry with this objectclass set. The entry stores the objectclass in a special attribute named "objectClass", and of course you may alter that attribute like any other attribute.

However, special care must be taken if changing this attribute since most directory servers impose rules on the other attributes the object class define. For example, it is usually not possible to delete an objectclass if some of the attributes the class describes are still in use by the entry. This should be not much of a problem with optional attributes, but sometimes objectclasses have mandatory attributes set. Also structural objectclasses can only be added when creating new entrys. Because of the internal architecture of Net_LDAP2 it is currently not possible to resolve those cases.

To add or remove objectclasses with mandatory attributes or new structural object classes, you need to delete the old entry from the directory server and add the new one with the new objectclass and attributes as fresh entry.

Changing complex objectclasses

<?php
// Let's assume that the objectclass myClass enforce the attribute "fooattr"
// Take care that you have all attributes requested, otherwise the new
// entry will not have all attributes set!
$entry->add(array(
    'objectClass'   => 'myClass',
    'fooatrr'       => 'foo',
    'someotherattr' => array('bar', 'baz')
    ));

// Calling $entry->update() now will not succeed under some circumstances!
// We construct a fresh entry object which is in fact a copy of the already
// existing entry with all changes already applied (the local copy).
// It is important, that at fetching time of $entry all attributes where selected!
// Only the selected attributes will get copied.
$changed_entry = Net_LDAP2_Entry::createFresh($entry->dn(), $entry->getValues());

// Now delete the old entry and add the new one:
$ldap->delete($entry);
$ldap->add($changed_entry);
?>
Prev | Net_LDAP2 | Next
Fetching entries | PEAR Manual | Managing entries


Managing entries

Managing entries

Managing entries – Adding/renaming/moving/deleting entries

Adding (fresh or old) entries to the directory

Adding new entries is performed in two ways. First, you need to establish a fresh Net_LDAP2_Entry object. After that, you can add that entry like you would add already-existent entries using Net_LDAP2's add() method.

Adding a fresh entry

<?php
// Build a new fresh entry:
$dn         = 'cn=new-admin,o=example,dc=org';
$attributes = array(
    'cn'              => 'new-admin',
    'mail'            => array('new-admin@exaple.org', 'n.admin@example.de'),
    'telephoneNumber' => '1234567890'
);
$entry = Net_LDAP2_Entry::createFresh($dn, $attributes);

// Add the entry to the directory:
$ldap->add($entry);
?>

Renaming or moving entries

Renaming and/or moving an entry is an operation on the DN of an entry. Moving an entry means, to rename a DN in such a way, that the entry becomes a new base-DN. You can rename or move an entry, if you call the dn() method of the entry you want to relocate. Alternatively, you may call Net_LDAP2's move() method that also ca handle only DNs. Remember that you must call the entires update() method to carry out the move/rename. Net_LDAP2's move() will move the entry immediately. If you use an entryobject togehter with Net_LDAP2's move(), you are able to perform cross directory moves.

Moving an entry using Net_LDAP2_Entry

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap->getEntry($dn);

$entry->dn($newdn);
?>

Moving an entry using Net_LDAP2 and Net_LDAP2_Entry

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap->getEntry($dn);

$ldap->move($entry, $newdn);
?>

Renaming an entry using Net_LDAP2 and DNs

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin2,o=new-example,dc=org';

$ldap->move($dn, $newdn);
?>

Performing a cross directory move

<?php
// $ldap_src is the source ldap and $ldap_tgt the target
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap_src->getEntry($dn);

$ldap_src->move($entry, $newdn, $ldap_tgt);
?>

Deleting entries

Deleting entries is performed using Net_LDAP2's delete() method. Just pass the Net_LDAP2_Entry object or the DN of the entry you want to delete. In the case that the DN contains subentrys, you need to pass TRUE as second parameter which will make delete() delete recursive.

A second way exist: You may simply call delete() from the Net_LDAP2_Entry you want to delete. Don't forget that you must call update() to carry out the delete in this case.

Deleting an entry

<?php
$dn  = 'cn=new-admin,o=example,dc=org';
$ldap->delete($dn);
?>

Deleting an entry using a Net_LDAP2_Entry object

<?php
$entry->delete();
$entry->update();
?>
Prev | Net_LDAP2 | Next
Attributes | PEAR Manual | LDAP filters


LDAP filters

LDAP filters

LDAP filters – Introduction to and usage of LDAP filters

What are LDAP filters?

LDAP filters are defined in RFC 2254 and can be compared to the WHERE clause in SQL select statements - they filter the data returned from some search request - in this case the entries returned from the directory server. With Net_LDAP2, you may use plain strings as filters, or preferably, the Net_LDAP2_Filter class which mostly releases you of the burden to escape yourself and to remember all the various special characters needed for constructing and combining filters.

Where and how to use filters is described in chapter Search.

Some LDIF filter basics

Although you should preferably use the Net_LDAP2_Filter class to construct your LDAP filters, some theory may be interesting and helpful in understanding how to construct LDAP filters and what they are capable of.

Basic LDAP filters are composed of an "[attribute][operator][value]" pair enclosed by round brackets. There are several comparison operators available: "=" (equal), ">" (greater), "<" (less), ">=" (greater or equal), "<=" (less or equal) and "=~" (phonetical similar). The exact match behavior is defined by the attribute syntax of the attribute to which the filter should apply.

Some basic string filters

<?php
// Filter entries whose first name is 'Benedikt':
$filter = '(givenName=Benedikt)';

// Filter entries which have an employeenumber higher or equal than 1424:
$filter = '(employeeNumber>=1424)';

// Filter entries whose first name sounds similar to "Stephane"
// This should also find "Stephen" and "Stefan" (depending on implementation)
$filter = '(givenName=~Stephane)';
?>

The value part of the basic filter construct could also include a special character: "*". The star acts as placeholder for none, one or several characters at that position. "V*lue" would therefore match against "Value", "Vlue", "VaaAaAalue" and so on. There are some special named combinations using the star, but they work exactly the same way:

Special named placeholder combinations
Name | Filter | Description
present | (attr=*) | Also refered to as "any". Finds any entry containing any (unless empty) value for the named attribute.
begins | (attr=value*) | value starts with some fixed string
ends | (attr=*value) | value ends with some fixed string
contains | (attr=*value*) | value contains some fixed string

Combining string filters

Basic filters can be combined using the three logical operators "&" (and), "|" (or) and "!" (not). Note, that the smallest filter component, the basic filter enclosed in round brackets, remains isolated: instead of just adding another "[attribute][operator][value]" pair into the brackets, a new bracket level is introduced that contains all filter components that should be combined. Note also, that the logical operator does stand in front of all filter components, not between them as common in programming languages.

Combining string filters

<?php
// Search all 'Benedikt's with phone number 1234567890
    $filter = '(&(givenName=Benedikt)(telephoneNumber=1234567890))';

    // Search the same, but exclude person "Benedikt Foobar"
    // Note that the "not" is a logical operator and thus needs its own
    // surrounding bracket. This explains nicely, that each bracket level
    // is evaluated independently from surrounding brackets.
    $filter = '(&(givenName=Benedikt)(telephoneNumber=1234567890)(!(sureName=Foobar)))';
?>

The Net_LDAP2_Filter class

As you will read below, there are some special characters inside the LDAP filter definition and thus must be escaped. These are mainly the special characters used directly by the filter syntax like braces and the logical operators. Despite those, there are some other cases which need special threatment. Nearly all of this cases are hidden through the Net_LDAP2_Filter class so you should only consider using string filters if you need to or you know what you are doing. If you need a filter string, you may also use Net_LDAP2_Filters toString() function after building the filter.

The filter class has two different usage models: one for constructing basic filters and another to combine them logically. This has to do with the syntax of LDAP filters you may read below.

Creating filters

For creating basic filter components, you need to use the create() factory method. There, you combine three items: an attribute to filter for, a matching rule for comparison and a value that is beeing compared with the servers entries. The given value is automatically escaped, so you need take care if you want to use the star placeholder. In this case, you need to pass FALSE as fourth parameter to create() which causes value to be threaten as-is. This of course also means, that you need to escape the parts of the value that may contain restricted characters yourself using Net_LDAP2_Util::escape_filter_value(). To learn what characters are restricted, refer to RFC 2254 or the documentation of Net_LDAP2_Util::escape_filter_value(); otherwise its safe to always escape.

The matching rules partly follow the basic filter matching rules described above, but are enhanced to make your life easier:

create()s matching rules
Rule | Description
equals | One of attributes values is exactly value. Please note that case sensitiviness depends on the matching rule defined in the attributes schema syntax.
begins | One of attributes values must begin with value
ends | One of attributes values must end with value
contains | One of attributes values must contain value
present | any | The attribute can contain any value but must be existent
greater | The attributes value is greater than value
less | The attributes value is less than value
greaterOrEqual | The attributes value is greater or equal than value
lessOrEqual | The attributes value is less or equal than value
approx | One of attributes values sounds similar to value. The matching behavior depends on the server implementation.

Creating LDAP filters

<?php
// Filter entries whose first name is 'Benedikt':
$filter = Net_LDAP2_Filter::create('givenName', 'equals', 'Benedikt');

// Filter entries whose first name starts with 'Steph':
$filter = Net_LDAP2_Filter::create('givenName', 'begins', 'Steph');

// Filter entries containing 'Lone*'; matching the star character.
// The automatic escaping of $value will conveniently escape the star for us.
$filter = Net_LDAP2_Filter::create('givenName', 'contains', 'Lone*');

// Filter entries containing 'Foo[something]Bar'; not matching the star character.
// For this to work, we need to disable automatic escaping of $value by passing
// false as fourth parameter. This however implies, that we take care of
// proper escaping, which is showed in the example.
$escaped_values = Net_LDAP2_Util::escape_filter_value(array('Foo', 'Bar'));
$foo =& $escaped_values[0];
$bar =& $escaped_values[1];
$filter = Net_LDAP2_Filter::create('givenName', 'contains', "$foo*$bar", false);

// Filter entries whose first name sounds similar to "Stephane"
// This should also find "Stephen" and "Stefan" (depending on implementation)
$filter = '(givenName=~Stephane)';
?>

Combining filters

Although the filters can be used stand alone, they can be combined to match sophisticated search requiremets. This is done by using the combine() to combine several present Net_LDAP2_Filter objects using a logical operator. The execption is the not operator since it only allows one filter object to be negated.

combine()s operators
Rule | Description
and | All filter components must evaluate to true for the combined filter to be true
or | At least one filter component must evaluate to true for the combined filter to be true
not | The result of the filter component is inversed (true becomes false and vice versa). Note that this operator only accepts one filter object.

Combining LDAP filters

<?php
// Create some test filters
$filter_benedikt = Net_LDAP2_Filter::create('givenName', 'equals', 'Benedikt');
$filter_steph    = Net_LDAP2_Filter::create('givenName', 'begins', 'Steph');
$filter_foobar   = Net_LDAP2_Filter::create('sureName', 'equals', 'Foobar');
$filter_height   = Net_LDAP2_Filter::create('personHeight', 'greater', '175');

// Negate 'foobar' filter.
// This filters every entry whose sure name is not 'Foobar'
$filter_not_foobar = Net_LDAP2_Filter::combine('not', $filter_foobar);

// Build a 'and' combination to be able to search for people whose
// first names start with 'Steph' and who are are taller than 175
// except those whose surname is 'Foobar'
$filter_stephs_tall = Net_LDAP2_Filter::combine('and',
    array($filter_steph, $filter_height, $filter_not_foobar));

// In any case, add every person whose first name is
// 'Benedikt' to the search result.
$filter_add_benedikt = Net_LDAP2_Filter::combine('or', array($filter_benedikt, $filter_stephs_tall));
?>

Advanced features

You may need some advanced functionality if you have to deal with string representation of filters.

Advanced methods
Method | Description
parse() | Takes an filter string and parses it into a Net_LDAP2_Filter object. It also verifies, that the filter syntax is correct.
printMe() | In PERLs interface, this method is called "print" but due to language constraints, we cannot use that name. Prints the string representation of this filter object to standard output or to an optional filehandle passed as parameter.
toString() | Returns the string representation of the filter object.
Prev | Net_LDAP2 | Next
Managing entries | PEAR Manual | LDIF files


LDIF files

LDIF files

LDIF files – Converting between Net_LDAP2_Entries and LDIF files

Avaible since

LDIF support was added to Net_LDAP2 in release 1.1.0a1.

What are LDIF files?

LDIF files are in detail described at RFC 2849. Shortly, they contain directory data in an plain text, human readable kind, much like a SQL file does. However, unlike SQL files LDIF files are mostly data based, not action based. There are two different LDIF file contents, which can be mixed freely - content and change files. The first and most often used one is the LDIF content file:

Example LDIF content file

#
# This is a content LDIF file.
# It contains one single entry featuring several
# attributes and one comment (this one).
# attr1, attr4 and cn are single valued, the others are
# multivalued. objectclass is a special case, LDAP servers
# will interpret this operational attribute to define the
# classes the object will belong to and thus, which attributes
# it may contain. the OCL-attribute is usually multivalued.
#
version: 1
dn: cn=test1,ou=example,dc=cno
objectclass: someobjectclass
attr1: 12345
attr2: 1234
attr2: baz
attr3: foo
attr3: bar
attr4: brrrzztt
cn: test1

LDIF files could describe not only the data an entry contains, but also various changes to the entry itself. If such an LDIF file would then be given to a LDAP server, he would interpret those changes instead just importing the data. Note in the example below, that even though LDIF content and LDIF change files could be mixed freely, this is not true for individual entries: a specific entry may be either describing content or changes, but not both.

Example LDIF change file

#
# This is a content+change LDIF file.
# It does contain the (shortened) entry from the example above to show
# that LDIF files can contain multiple entry modes.
# The second entry is a change entry. In this case, some
# operations will be done on the entries attributes.
#
version: 1
dn: cn=test1,ou=example,dc=cno
objectclass: someobjectclass
attr1: 12345
cn: test1

# Delete attr1, replace values of attr2 and add new attribute attr42
# The attribute "changetype" is special: it says, what to do with
# this entries dataset. It could also be "delete" or "add" to delete
# a whole entry or to add a completely fresh one. "modrdn" will
# move the entry to a new location once the LDIF file is imported.
dn: cn=test2,ou=example,dc=cno
changetype: modify
delete: attr1
-
replace: attr2
attr2: 123456_newtest
-
add: attr42
attr42: the answer

Error handling when using Net_LDAP2_LDIF

Before we can start using Net_LDAP2_LDIF we must say some short words about how error handling works. Net_LDAP2_LDIF was designed to have mostly the same API as the original PERL Net::LDAP::LDIF has. Because of this, the methods of Net_LDAP2_LDIF do not return a Net_LDAP2_Error object. You must use the error() method that will return a Net_LDAP2_Error object in case of failure or true in case everything was ok. In LDIF reading mode, you can additionally use error_lines() to get knowledge about where in the input file the error occured.

Construction and options

Regardless if you want to read or write a LDIF file, you always have to use the constructor of Net_LDAP2_LDIF to initialize your access to the LDIF file. You need to pass at least one parameter to Net_LDAP2_LDIF(): the path of the file that should be read or written. You may pass the open mode as second parameter. The possible file open modes are "r" (read), "w" (write, clears the file first) and "a" (append to the end). In case you omit the open mode, read mode is assumed. The third optional parameter is an associative array containing one or several of the following options:

Possible configuration options
Name | Description | Default
encode | Some DN values in LDIF cannot be written verbatim and have to be encoded in some way. Possible values are: "none", "canonical" and "base64" (RFC default) | base64
onerror | What should be done on errors? "undef" will let error handling in your hands, in this case you use error() and error_lines() to process errors manually. "die" aborts the script printing the error - this is sometimes useful for CLI scripts. "warn" just prints out the error but continues like "undef" would. | undef
change | Turning this to "1" (true) will tell Net_LDAP2_LDIF to write change sets instead of content files. | false
lowercase | Set this to true to convert attribute names to lowercase when writing. | 0
sort | If true, sort attribute names when writing entries according to the rule: objectclass first then all other attributes alphabetically sorted by attribute name | 0
version | Set the LDIF version to write to the resulting LDIF file. According to RFC 2849 currently the only legal value for this option is 1 currently. | 1
wrap | Number of columns where output line wrapping shall occur. Setting it to 40 or lower inhibits wrapping. Useful for better human readability of the resulting file. | 78
raw | Using this option, you are able to tell Net_LDAP2_LDIF which attributes to treat as binary data. If you pass in entries having a valid LDAP connection (eg from some Net_LDAP2->search() operation) this additionally will be detected by automatic checks against the schema. | empty

For advanced users: instead of passing a file path, you also may pass an already initialized file handle. In this case, the mode parameter will be ignored. You may use this, if you want to mix LDIF content and LDIF change mode by using two Net_LDAP2_LDIF instances to write to the same filehandle, but it could be very useful in other cases too. To initialize the second instance of Net_LDAP2_LDIF, you can use handle() to get the filehandle from the first instance.

Reading a LDIF file into Net_LDAP2_Entry-objects

One of the two modes how Net_LDAP2_LDIF can be used is to read a LDIF file and parse its contents into an array of Net_LDAP2_Entry objects. This is done using the read_entry()-method which will return the next entry. If you want to fetch all entries, you use the eof() to detect the end of the input file:

Parsing a LDIF file into Net_LDAP2_Entry objects

<?php
// open some LDIF file for reading
$ldif = new Net_LDAP2_LDIF('somefile.ldif', 'r');
if ($ldif->error()) {
    $error_o = $ldif->error(); // get Net_LDAP2_Error object on error
            die('ERROR: '.$error_o->getMessage());
}

// parse the entries of the LDIF file into objects
 do {
    $entry = $ldif->read_entry();
    if ($ldif->error()) {
        // in case of error, print error.
        // here we use the shorthand parameter, so error()
        // returns a string instead of a Net_LDAP2_Object
        die('ERROR AT INPUT LINE '.$ldif->error_lines().': '.$ldif->error(true));
    } else {
        // No error: do something with the entry
        // Here we just print the entries DN
        echo 'sucessfully parsed '.$entry->dn();
    }
} while (!$ldif->eof());

// We should call done() once we are finished
$ldif->done();
?>

Writing Net_LDAP2_Entry objects to a LDIF content file

Writing an LDIF file is very easy too. Just pass the entries you want to have written to the write_entry()-method. Beware, that if you have opened the file in "w" write mode this will clear any previous data of that file. Use "a" (append) if you just want add data.

Writing entries

<?php
// Assume we have some valid Net_LDAP2_Entry objects inside $entries
        // $entries = array( ... );

        // open some file for writing
        $ldif = new Net_LDAP2_LDIF('somewritefile.ldif', 'w');
        if ($ldif->error()) die('ERROR: '.$error_o->getMessage());

        // write the data and check for error
        // you could pass one single Net_LDAP2_Entry object or
        // several objects inside an array
        $ldif->write_entry($entries);
        if ($ldif->error()) die('WRITE ERROR: '.$error_o->getMessage());
?>

Writing Net_LDAP2_Entry objects to a LDIF change file

The process of writing changes is exactly the same like writing entry contents. However there are two differences: Firstly you need to pass the "changes" option and secondly, the entries you want to write need changes. Entries not containing changes will silently be ignored since there is nothing to write.

Writing entry changes

<?php
// cast some test data and three entries
        $testattrs = array(
                'attr1' => '1234',
                'attr2' => 'foo',
                'attr3' => array('bar', 'baz')
            );
        $entries = array(
                Net_LDAP2_Entry::createFresh('cn=foo,dc=example,dc=cno',
                    array_merge(array('cn' => 'foo'), $testattrs)),
                Net_LDAP2_Entry::createFresh('cn=bar,dc=example,dc=cno',
                    array_merge(array('cn' => 'bar'), $testattrs)),
                Net_LDAP2_Entry::createFresh('cn=baz,dc=example,dc=cno',
                    array_merge(array('cn' => 'baz'), $testattrs))
            );

        // make some changes to the first and the last entry
        $entries[0]->add(array('someattr' => 'added'));
        $entries[0]->replace(array('attr1' => 'replaced'));
        $entries[2]->delete(array('attr2'));
        $entries[2]->delete(array('attr3' => 'bar'));

        // open some file for writing, but in change mode
        $ldif = new Net_LDAP2_LDIF('somewritefile.ldif', 'w', array('change' => true));
        if ($ldif->error()) die('ERROR: '.$error_o->getMessage());

        // write the data and check for error
        // you could pass one single Net_LDAP2_Entry object or
        // several objects inside an array
        $ldif->write_entry($entries);
        if ($ldif->error()) die('WRITE ERROR: '.$error_o->getMessage());

        // Now, only two entries are contained in the LDIF file,
        // cn=foo,dc=example,dc=cno and cn=baz,dc=example,dc=cno.
        // cn=bar,dc=example,dc=cno had no changes and was skipped.
?>

Resulting LDIF change file

version: 1
dn: cn=foo,dc=example,dc=cno
changetype: modify
add: someattr
someattr: added
-
replace: attr1
attr1: replaced
-

dn: cn=baz,dc=example,dc=cno
changetype: modify
delete: attr2
-
delete: attr3
attr3: bar
-

Fetching LDIF data

Sometimes you are interested in the lines inside the LDIF file. For those cases you can use the current_lines() and next_lines() methods. They work in the current context, which may be confusing: current_lines() will always return the lines that have built up the current Net_LDAP2_Entry object when called current_entry() after read_entry() has been called. next_lines() will always return the lines, that will build up the next entry from the current point of view, meaning "relative to the entry that was just been read". However, you can override this by activating the "force" parameter of next_lines() which allows you to loop over all entries. current_entry() behaves exactly like current_lines().

If you think, that the lines you have read would be better in form of an Net_LDAP2_Entry object, use the parseLines() method to parse those lines into an entry. This is a good way if you need just a few specific entries of a large LDIF file.

Reading LDIF lines

<?php
// open some LDIF file for reading
// (error checking code is ommitted in this example for
//  better readability - in production, test for errors!)
$ldif = new Net_LDAP2_LDIF('somefile.ldif', 'r');

// since nothing has been read until now, this will
// return an empty array
$empty_array = $ldif->current_lines();

// so let's read the first entries data
$first_entry_lines = $ldif->next_lines();

// if we call it again, we will not read ahead to the
// second entry - we again read the first one!
$first_entry_lines_again = $ldif->next_lines();

// If we call current_lines() now, we haven't read ahead
// like we learned from the last statement.
$empty_array_again = $ldif->current_lines();

// If we want to shift, we must use
// the read_entry() method, which will read ahead.
$first_entry = $ldif->read_entry();

// Now, current_lines() returns the lines of the
// first entry and next_lines() the lines of the second:
$first_entry_lines  = $ldif->current_lines();
$second_entry_lines = $ldif->next_lines();

// There is another way to shift the lines which is faster if
// you are just interested in the LDIFs content - you
// need to pass the "force" parameter to next_lines():
$third_entry_lines  = $ldif->next_lines(true);
$fourth_entry_lines = $ldif->next_lines(true);
$fifth_entry_lines  = $ldif->next_lines(true);

// If you want to convert the lines to an Net_LDAP2_Entry,
// you may do so anytime by using parseLines()
$fourth_entry = $ldif->parseLines($fourth_entry_lines);

// Since we shifted manually only the lines,
// current_lines() will return the lines that built up the
// last (e.g. the first entry) Net_LDAP2_Entry object:
$first_entry_lines  = $ldif->current_lines();

// If we decide to read the next entry, we can do that:
$sixth_entry = $ldif->read_entry();

// current_lines() is shifted now:
$sixth_entry_lines = $ldif->current_lines();
?>
Prev | Net_LDAP2 | Next
LDAP filters | PEAR Manual | Schema caching


Schema caching

Schema caching

Schema caching – How to enable schema caching

Net_LDAP2s schema caching facility

Net_LDAP2 features an easy schema caching facility. Caching the schema can gain some performance, especially with slow servers or connections. The facility works with an plugin object that must be passed to Net_LDAP2s registerSchemaCache() method. The cache object can be registered (or unregistered) at any time, but of course it is the best time right after initializing Net_LDAP2.

Enabling/disabling Net_LDAP2s schema caching facility

<?php
// registering a valid schema cache object is enough to enable the caching facility:
$ldap->registerSchemaCache($myCacheObject);

// unregistering is easy too: just supply null as schema cache object:
$ldap->registerSchemaCache(null);
?>

The object that gets passed to registerSchemaCache() must implement the Net_LDAP2_SchemaCache interface which demands two methods. Initialisation of the cache object is dependent on the class itself but should be handled inside the cache class constructor, however this may vary. Please refer to the cache class documentation for those details.

Net_LDAP2_SchemaCache interface methods
Method | Parameter | Return value | Description
loadSchema() | none | Net_LDAP2_Schema, Net_LDAP2_Error or false | Returns the cached schema object. Net_LDAP2 will consider anything returned invalid, except a valid Net_LDAP2_Schema object. In case you return a Net_LDAP2_Error, this error will be routed to the return of the $ldap->schema() call. If you return something else, Net_LDAP2 will fetch a fresh Schema object from the LDAP server and tries to cache it via store(). You may also want to implement a cache aging mechanism here too.
storeSchema() | Net_LDAP2_Schema object | true or (in special cases) Net_LDAP2_Error | Stores a schema object in the cache. This method will be called, if Net_LDAP2 has fetched a fresh schema object from LDAP and wants to init or refresh the cache. In case of errors you may return a Net_LDAP2_Error which will be routet to the client. Note that doing this prevents, that the schema object fetched from LDAP will be given back to the client, so only return errors if storing of the cache is something crucial (e.g. for doing something else with it). Normaly you dont want to give back errors in which case Net_LDAP2 needs to fetch the schema once per script run and use the error functionality of loadSchema().

Packaged schema cache classes

As of Net_LDAP2 2.0.0, there is one default schema caching class: Net_LDAP2_SimpleFileSchemaCache to make your life a little easier. Caching to files should also be the most commonly used case.

This cache class is built to be flexible yet simple to use and may serve as example to write own caching classes. This cache stores the schema object in a flat file. The path is freely configurable. It also servers a cache aging mechanism that can be used to invalidate the cached schema after some time so it will be refreshed regularly.

To use this cache, you firstly need to initialize and configure a fresh cache object. Then the cache must be registered with the Net_LDAP2 instance. After that, Net_LDAP2 will use the cache.

Initializing the SimpleFileSchemaCache

<?php
$myCacheConfig = array(
        'path'    => '/tmp/Net_LDAP_Schema.cache',
        'max_age' => 1200
);
$myCacheObject = new Net_LDAP2_SimpleFileSchemaCache($myCacheConfig);
$ldap->registerSchemaCache($myCacheObject);
?>

Net_LDAP2_SimpleFileSchemaCache config options
Option | Mandatory? | Default | Description
path | No | /tmp/Net_LDAP_Schema.cache | The full path to the cache file. To improve the caches performance under linux, you can place the cache file in a tmpfs mounted directory. This will put the file in the computers memory instead on disk, enabling nearly instant access.
max_age | No | 1200 | Maximum cache age in seconds. The age of the cache is determined by the files last change time. If max_age is reached, Net_LDAP2 will fetch a fresh Net_LDAP2_Schema object which is then stored in the cache file again.

Writing own schema cache classes

However this is basicly an easy task, this is beyond the scope of this manual. If you want to write your own custom schema cache, please refer to the detailed example at /your/pear/path/docs/Net_LDAP2/examples/schema_cache.php as well as the source/APIdoc of the interface Net_LDAP2_SchemaCache.

Prev | Net_LDAP2 | Next
LDIF files | PEAR Manual | Net_MAC


Net_MAC

Net_MAC

This package validates and cleanly formats Media Access Control (MAC) addresses. The Net_MAC class can also import a list of MAC address vendors and store them in a database which the class can then use to identify vendors of any MAC address.

Table of Contents
  • Constants -- Predefined Constants
  • Net_MAC::check() -- Validates Media Access Control (MAC) addresses
  • Net_MAC::format() -- Cleanly formats Media Access Control (MAC) addresses
  • Net_MAC::__construct() -- Constructor
  • setMAC() -- Sets the MAC address in the object
  • importVendors() -- Import a manufacturers' file to the database or to an array
  • findVendor() -- Finds the vendor of the MAC address stored in the object
  • Net_MAC_Exception -- Exception class for Net_MAC package
Prev | Networking | Next
Schema caching | PEAR Manual | Constants


Constants

Constants

Constants – Predefined Constants

NET_MAC_LINE_MAXLENGTH

Constant to represent the maximum length of a line in the manufacturers file.

NET_MAC_ERROR_OK

Error constant: signifies no problem (OK)

NET_MAC_ERROR_BADOPT

Error constant: signifies a bad option being passed to a function

NET_MAC_ERROR_BADDATA

Error constant: signifies bad data being passed to a function

NET_MAC_ERROR_BADDB

Error constant: signifies a bad database connection

NET_MAC_ERROR_BADFILE

Error constant: signifies a bad manufacturers file

Prev | Net_MAC | Next
Net_MAC | PEAR Manual | Net_MAC::check()


Net_MAC::check()

Net_MAC::check()

Net_MAC::check() – Validates Media Access Control (MAC) addresses

Synopsis

require_once 'Net/MAC.php';

string Net_MAC::check ( string $input , string $delimiter=':' )

Description

This function will check a MAC address to make sure it is valid.

Parameter

  • string $input - The string containing the MAC Address

  • string $delimiter - The string representing the delimiter to use when checking the MAC Address

Return value

boolean - TRUE if the MAC address is valid, FALSE otherwise

Note

This function should be called statically.

Example

Using check()

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

$mac = Net_MAC::check($macaddr);
if ($mac) {
    echo "$macaddr is valid";
}
else {
    echo "$macaddr is invalid";
}
?>

This would output the following:

ab:cd:ef:00:11:22 is valid

Using check() to get a MAC address with a different delimiter

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

$mac = Net_MAC::check($macaddr, '-');
if ($mac) {
    echo "$macaddr is valid";
}
else {
    echo "$macaddr is invalid";
}
?>

This would output the following:

AB:CD:EF:00:11:22 is invalid

since the delimiter '-' was not used in the provided MAC address.

Prev | Net_MAC | Next
Constants | PEAR Manual | Net_MAC::format()


Net_MAC::format()

Net_MAC::format()

Net_MAC::format() – Cleanly formats Media Access Control (MAC) addresses

Synopsis

require_once 'Net/MAC.php';

string Net_MAC::format ( string $input , string $delimiter=':' , boolean $uppercase = true )

Description

This function will format a MAC address into XX:XX:XX:XX:XX:XX format from whatever format is passed to the function. The delimiter (':' in the example above) will be replaced with whatever string is passed to the $delimiter parameter (default ':').

Parameter

  • string $input - The string containing the MAC Address

  • string $delimiter - The string representing the delimiter to use when formatting the MAC Address

  • string $uppercase - If set to TRUE (default), the alpha characters in the hexadecimal values in the MAC Address will be returned in uppercase. If FALSE, the alpha characters in the hexadecimal values will be returned in lowercase.

Return value

string - The formatted MAC Address or FALSE if the syntax of the MAC address is invalid

Note

This function should be called statically.

Example

Using format()

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

if (!Net_MAC::check($macaddr)) {
    echo "$macaddr is invalid";
    exit;
}

$mac = Net_MAC::format($macaddr);
if ($mac) {
    echo "$mac";
}
else {
    echo "$macaddr could not be formatted";
}
?>

This would output the following:

AB:CD:EF:00:11:22

Using format() to get a MAC address with a different delimiter

<?php
require_once "Net/MAC.php";

$macaddr = 'AB:CD:EF:00:11:22';

if (!Net_MAC::check($macaddr)) {
    echo "$macaddr is invalid";
    exit;
}

$mac = Net_MAC::format($macaddr, '-');
if ($mac) {
    echo "$mac";
}
else {
    echo "$macaddr could not be formatted";
}
?>

This would output the following:

AB-CD-EF-00-11-22

Using format() to get a MAC address with all capital alpha characters

<?php
require_once "Net/MAC.php";

$macaddr = 'ab:cd:ef:00:11:22';

if (!Net_MAC::check($macaddr)) {
    echo "$macaddr is invalid";
    exit;
}

$mac = Net_MAC::format($macaddr, '', true);
if ($mac) {
    echo "$mac";
}
else {
    echo "$macaddr could not be formatted";
}
?>

This would output the following:

ABCDEF001122

See

Net_MAC::check(),

Prev | Net_MAC | Next
Net_MAC::check() | PEAR Manual | Net_MAC::__construct()


Net_MAC::__construct()

Net_MAC::__construct()

Net_MAC::__construct() – Constructor

Synopsis

require_once 'Net/MAC.php';

Net_MAC::__construct ( object $db , array $options )

Description

This is the constructor that will create and populate a valid Net_MAC object.

Parameter

  • object $db - This parameter must be a valid MDB2 object.

  • array $options - An array of options to use with the database in retrieving MAC address vendors. The associative array should have key/value pairs as follows:

    Net_MAC::__construct() options
    Option | Description
    tablename | The name of the table where MAC address vendor information lives
    macaddrcol | The name of the column containing the MAC address prefixes
    vendorcol | The name of the column containing the vendor name
    desccol | The name of the column containing any extra descriptive information derived from the vendor list

Return value

void - No return value. A Net_MAC_Exception Exception object will be thrown if there is an error during construction

Note

The constructor can throw exceptions on error, so the constructor should always be called from inside a try/catch block.

Example

Instantiating a Net_MAC object

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}
?>

Throws

throws Net_MAC_Exception

See

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

Prev | Net_MAC | Next
Net_MAC::format() | PEAR Manual | setMAC()


setMAC()

setMAC()

setMAC() – Sets the MAC address in the object

Synopsis

require_once 'Net/MAC.php';

mixed setMAC ( string $macaddr , string $delimiter = ':' )

Description

This method will set the MAC address in the object given the passed MAC address and the MAC address delimiter. This method also makes use of the check() method to make sure that the MAC address is valid.

Parameter

  • string $macaddr - The string representing the MAC address

  • string $delimiter - The string representing the delimiter to use when verifying the MAC Address

Return value

boolean - Returns TRUE if the MAC address is set correctly, FALSE otherwise (i.e. the MAC address is not valid).

Note

This function can not be called statically.

Example

Using setMAC()

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}

$nmh->setMAC('00:11:22:33:44:55');
?>

See

Net_MAC::__construct()

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

Prev | Net_MAC | Next
Net_MAC::__construct() | PEAR Manual | importVendors()


importVendors()

importVendors()

importVendors() – Import a manufacturers' file to the database or to an array

Synopsis

require_once 'Net/MAC.php';

mixed importVendors ( string $file , boolean $doReturn = false )

Description

This method will parse a manufacturers' file, such as the one from http://anonsvn.wireshark.org/wireshark/trunk/manuf, containing a list of MAC address prefix-to-vendor relationships. If the $doReturn parameter is FALSE, then the data will be imported into the database defined by the factory of this class. However, if $doReturn is TRUE, then the return will be an associative array with the key being the MAC address prefix and the data being an associative array with the keys 'vendor' and 'description'.

Parameter

  • string $file - The filename or URL of the manufacturers' file to parse

  • string $doReturn - If TRUE, an array will be returned, if FALSE, the data will be imported into the database.

Return value

mixed - If $doReturn is TRUE, the method will return an array. Otherwise, the method will return TRUE on success. A Net_MAC_Exception Exception object will be thrown on failure in either case.

Note

This function can not be called statically.

This method can throw exceptions on error, so the method should always be called from inside a try/catch block.

Example

Using importVendors() with a URL

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}

try {
  $nmh->importVendors('http://anonsvn.wireshark.org/wireshark/trunk/manuf');
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}
?>

This would output an error only if there is an error importing the file from the URL.

Using importVendors() with a file, returning an array

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

$nmh =& Net_MAC::factory($dbh, $dboptions);
if (PEAR::isError($nmh)){
  echo 'Net_MAC Error: '.$nmh->getMessage();
}

$vendorArr = $nmh->importVendors('./manuf')
if (PEAR::isError(!$vendorArr)) {
  echo 'Net_MAC: ' . $err->getUserInfo();
  exit;
}

print_r($vendorArr);
?>

This would output the entire list of MAC address vendors on success and an error message on failure.

Throws

throws Net_MAC_Exception

See

Net_MAC::__construct()

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

Prev | Net_MAC | Next
setMAC() | PEAR Manual | findVendor()


findVendor()

findVendor()

findVendor() – Finds the vendor of the MAC address stored in the object

Synopsis

require_once 'Net/MAC.php';

mixed findVendor ( string $getDescription = false , string $macList = null )

Description

This method will search through the database to find a vendor that matches the MAC address stored in the class using setMac(). If the $macList parameter is set, the method will use the array stored in $macList as the data source to find the MAC vendor instead of the database. The array would have to be an array with the same characteristics as one returned from the importVendors() method when using the $doReturn parameter.

Parameter

  • string $getDescription - If set to TRUE, the return value will be an array with keys 'vendor' and 'description'. Normally the method will simply return the vendor name.

  • string $macList - An optional list of MAC-to-vendor relationships to search instead of using the database.

Return value

mixed - Returns an associative array if $getDescription is TRUE, returns a string with the vendor name if $getDescription is FALSE. If the MAC vendor cannot be found in the vendor list, FALSE is returned.

Note

This function can not be called statically.

Example

Using findVendor()

<?php
require_once 'Net/MAC.php';
require_once 'MDB2.php';

$db_type = 'pgsql';
$db_host = 'localhost';
$db_user = 'username';
$db_name = 'dbname';
$db_pass = 'password';

$dsn = "$db_type://$db_user:$db_pass@$db_host/$db_name";

$dbh =& MDB2::factory($dsn);

if (MDB2::isError($dbh)) {
  echo "MDB2 Error: ".$dbh->getUserInfo();
}

$dboptions = array('tablename' => 'macvendors',
           'macaddrcol' => 'macaddr',
           'vendorcol' => 'vendor',
           'desccol' => 'description');

try {
  $nmh =& new Net_MAC($dbh, $dboptions);
} catch (Net_MAC_Exception $e) {
  echo 'Net_MAC Error: ' . $e->getMessage();
  exit;
}

$nmh->setMAC('00:11:22:33:44:55');
$result = $nmh->findVendor(true);
if (is_array($result)) {
  foreach($result as $key => $value) {
    echo "$key: $value<br>\n";
  }
}
else {
  echo $result;
}
?>

This would output the following:

vendor: Cimsys

description: CIMSYS Inc

See

Net_MAC::__construct()

MDB2::factory()

MDB2::isError()

PEAR_Error::getUserInfo()

Prev | Net_MAC | Next
importVendors() | PEAR Manual | Net_MAC_Exception


Net_MAC_Exception

Net_MAC_Exception

Net_MAC_Exception – Exception class for Net_MAC package

Net_MAC_Exception

This class is a simple derivation of the PEAR_Exception class and simply exists for the use of throwing exceptions for this class.

Prev | Net_MAC | Next
findVendor() | PEAR Manual | Net_NNTP


Net_NNTP

Net_NNTP

Implementation of the NNTP protocol

Note: The Net_NNTP class is considered deprecated as of v0.10.x; Net_NNTP_Client should be used instead in new applications. A 'backport' of Net_NNTP_Client has replaced Net_NNTP to maintain backward compatibility, but this is temporary and will only last for some time.
Table of Contents
  • Net_NNTP_Client
  • Net_NNTP
  • Net_NNTP_Header
  • Net_NNTP_Message
  • Net_NNTP_Protocol_Client
Prev | Networking | Next
Net_MAC_Exception | PEAR Manual | Net_NNTP_Client


Net_NNTP_Client

Net_NNTP_Client

Table of Contents
  • Constants -- predefined constants
  • Net_NNTP_Client::authenticate() -- Authenticate
  • Net_NNTP_Client::connect() -- Connects to a NNTP-server
  • Net_NNTP_Client::connectAuthenticated() -- Connect and authenticate to a NNTP-server
  • Net_NNTP_Client::count() -- Get the number of articles in the current newsgroup
  • Net_NNTP_Client::getDescriptions()
  • Net_NNTP_Client::first() -- Get the number of the first article in the current newsgroup
  • Net_NNTP_Client::getArticle() -- Fetch an article from the NNTP-server
  • Net_NNTP_Client::getArticleRaw() -- Fetch an article from the NNTP-server
  • Net_NNTP_Client::getGroupArticles() -- $newsgroup
  • Net_NNTP_Client::getBodyRaw() -- Fetch the body of an article from the NNTP-server
  • Net_NNTP_Client::getDate() -- Get date from NNTP-server
  • Net_NNTP_Client::getGroups() -- Fetch list of avaible newsgroups
  • Net_NNTP_Client::getHeader() -- Fetch the header of an article from the NNTP-server
  • Net_NNTP_Client::getHeaderRaw() -- fetch message header
  • Net_NNTP_Client::getNewGroups() -- $time
  • Net_NNTP_Client::getNewNews() -- $time
  • Net_NNTP_Client::getOverview() -- Fetch newsgroup overview
  • Net_NNTP_Client::getReferencesOverview() -- $first
  • Net_NNTP_Client::group() -- $user
  • Net_NNTP_Client::isConnected() -- Connected?
  • Net_NNTP_Client::last() -- Get the number of the last article in the current newsgroup
  • Net_NNTP_Client::post() -- $newsgroups
  • Net_NNTP_Client::quit() -- Close the connection to the NNTP-server
  • Net_NNTP_Client::selectGroup() -- select a newsgroup

NNTP client implementation

Prev | Net_NNTP | Next
Net_NNTP | PEAR Manual | Constants


Constants

Constants

Constants – predefined constants

NET_NNTP_PROTOCOL_DEFAULT_HOST

default NNTP hostname: localhost

NET_NNTP_PROTOCOL_DEFAULT_PORT

default NNTP port: 119

NET_NNTP_AUTHORIGINAL

authentication provided by the NNTP-server

NET_NNTP_AUTHSIMPLE

authentication provided by the NNTP-server

NET_NNTP_AUTHGENERIC

authentication provided by the NNTP-server

Prev | Net_NNTP_Client | Next
Net_NNTP_Client | PEAR Manual | Net_NNTP_Client::authenticate()


Net_NNTP_Client::authenticate()

Net_NNTP_Client::authenticate()

Net_NNTP_Client :: () – Authenticate

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::authenticate ( string $$user , string $$pass [, integer $$authmode = NET_NNTP_AUTHORIGINAL ] )

Description

Authenticate on an already open connection

Parameter

  • $user - Username to authenticate with

  • $pass - Password to authenticate with

  • $authmode - Type of authentication. Default=NET_NNTP_AUTHORIGINAL

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

See

Net_NNTP_Client::connectAuthenticated

Prev | Net_NNTP_Client | Next
Constants | PEAR Manual | Net_NNTP_Client::connect()


Net_NNTP_Client::connect()

Net_NNTP_Client::connect()

Net_NNTP_Client::connect() – Connects to a NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

boolean Net_NNTP_Client::connect ( string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST , integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT )

Description

Connect to a specific NNTP-server

Parameter

  • $host - Hostname of the NNTP-server. Default=NET_NNTP_PROTOCOL_DEFAULT_HOST

  • $port - Port, where the NNTP-server listens. Default=NET_NNTP_PROTOCOL_DEFAULT_PORT

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
NULL "Could not connect to NNTP-server $host" or "Not connected" The connection couldn't be established because

  • wrong hostname/ip-address or port

  • the host itself isn't linked to a network

  • a firewall doesn't allow access

 Check for server name, the connection to the net and possible firewalls on client or server side.

Note

This function can not be called statically.

See

Net_NNTP::quit(), Net_NNTP::pepareConnection()

Example

Using connect()

<?php
require_once 'Net/NNTP/Client.php';

$nntp = new Net_NNTP_Client();
$ret = $nntp->connect('news.php.net');
if( PEAR::isError($ret)) {
    // handle error
} else {
    // success
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::authenticate() | PEAR Manual | Net_NNTP_Client::connectAuthenticated()


Net_NNTP_Client::connectAuthenticated()

Net_NNTP_Client::connectAuthenticated()

Net_NNTP_Client::connectAuthenticated() – Connect and authenticate to a NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

boolean Net_NNTP_Client::connectAuthenticated ( integer $user = null , integer $pass = null , string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST , integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT , integer $authmode = NET_NNTP_AUTHORIGINAL )

Description

Connect and authenticate to a specific NNTP-server

This function is deprecated. That means that future versions of this package may not support it anymore.

Parameter

  • $user - Username to authenticate

  • $pass - Password to authenticate

  • $host - Hostname of the NNTP-server. Default=NET_NNTP_PROTOCOL_DEFAULT_HOST

  • $port - Port, where the NNTP-server listens. Default=NET_NNTP_PROTOCOL_DEFAULT_PORT

  • $authmode - Type of authentication. Default=NET_NNTP_AUTHORIGINAL

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
NULL "Could not connect to NNTP-server $host" or "Not connected" The connection couldn't be established because

  • wrong hostname/ip-address or port

  • the host itself isn't linked to a network

  • a firewall doesn't allow access

 Check for server name, the connection to the net and possible firewalls on client or server side.

Note

since 0.3

This function can not be called statically.

See

Net_NNTP_Client::connect() Net_NNTP_Client::quit(),

Example

Using connectauthenticated()

<?php
require_once 'Net/NNTP/Client.php';

$nntp = new Net_NNTP_Client();
$ret = $nntp->connectAuthenticated('news.php.net');
if( PEAR::isError($ret)) {
    // handle error
} else {
    // success
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::connect() | PEAR Manual | Net_NNTP_Client::count()


Net_NNTP_Client::count()

Net_NNTP_Client::count()

Net_NNTP_Client :: () – Get the number of articles in the current newsgroup

Synopsis

require_once 'Net/NNTP/Client.php';

public integer Net_NNTP_Client::count ( void )

Description

Retrieves the number of articles in the current newsgroup.

Return value

integer - number of articles in newsgroup

Note

since 0.3

This function can not be called statically.

Example

Using count()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "number of articles: ".$nntp->count();
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::connectAuthenticated() | PEAR Manual | Net_NNTP_Client::getDescriptions()


Net_NNTP_Client::getDescriptions()

Net_NNTP_Client::getDescriptions()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getDescriptions ( void )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::count() | PEAR Manual | Net_NNTP_Client::first()


Net_NNTP_Client::first()

Net_NNTP_Client::first()

Net_NNTP_Client :: () – Get the number of the first article in the current newsgroup

Synopsis

require_once 'Net/NNTP/Client.php';

public integer Net_NNTP_Client::first ( void )

Description

Retrieves the number of the first article in the current newsgroup.

Return value

integer - lowest article number in newsgroup

Note

since 0.3

This function can not be called statically.

Example

Using first()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "lowest message number: ".$nntp->first();
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getDescriptions() | PEAR Manual | Net_NNTP_Client::getArticle()


Net_NNTP_Client::getArticle()

Net_NNTP_Client::getArticle()

Net_NNTP_Client::getArticle() – Fetch an article from the NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

mixed Net_NNTP_Client::getArticle ( string $article )

Description

This function is currently not documented.

See

Net_NNTP_Client::getArticleRaw()

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::first() | PEAR Manual | Net_NNTP_Client::getArticleRaw()


Net_NNTP_Client::getArticleRaw()

Net_NNTP_Client::getArticleRaw()

Net_NNTP_Client::getArticleRaw() – Fetch an article from the NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

mixed Net_NNTP_Client::getArticleRaw ( string $article , boolean $implode = false )

Description

Returns the whole article from the currently selected newsgroup

Parameter

  • string $article - article number or Message-ID of the article to fetch

    boolean $implode - Determines if the resulting array is to be imploded into a string.

Return value

array/string - If message exists the message or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article |

Note

since 0.3

This function can not be called statically.

See

Net_NNTP_Client::getArticle() , Net_NNTP_Client::getHeaderRaw() , Net_NNTP_Client::getBodyRaw()

Example

Using getArticleRaw()

<?php
...
$article = $nntp->getArticleRaw($msg_id);
if( PEAR::isError($article)) {
    // handle error
} else {
    // success
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getArticle() | PEAR Manual | Net_NNTP_Client::getGroupArticles()


Net_NNTP_Client::getGroupArticles()

Net_NNTP_Client::getGroupArticles()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getGroupArticles ( string $$newsgroup )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getArticleRaw() | PEAR Manual | Net_NNTP_Client::getBodyRaw()


Net_NNTP_Client::getBodyRaw()

Net_NNTP_Client::getBodyRaw()

Net_NNTP_Client::getBodyRaw() – Fetch the body of an article from the NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

mixed Net_NNTP_Client::getBodyRaw ( string $article , boolean $implode = false )

Description

Returns the whole body of an article from the currently selected newsgroup

Parameter

  • string $article - article number or Message-ID of the article to fetch

    boolean $implode - Determines if the resulting array is to be imploded into a string.

Return value

string/array - If message exists the body or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article |

Note

since 0.3

This function can not be called statically.

Note: getBody() makes no converting of the body content to any character set. You get the content 'as is'.

See

Net_NNTP_Client::getHeaderRaw() , Net_NNTP_Client::getArticleRaw()

Example

Using getBodyRaw()

<?php
...

$body = $nntp->getBodyRaw($msgId);
if( PEAR::isError($body)) {
    // handle error
} else {
    // success - print body
    echo $body;
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getGroupArticles() | PEAR Manual | Net_NNTP_Client::getDate()


Net_NNTP_Client::getDate()

Net_NNTP_Client::getDate()

Net_NNTP_Client::getDate() – Get date from NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

mixed Net_NNTP_Client::getDate ( integer $format = 1 )

Description

Retrieves the date from the NNTP-server.

Parameter

  • $format - Tetermines which format to return.

Return value

$format | returns
0 | timestamp
1 array - a hash with the date

  • $date['y'] Year

  • $date['m'] Month

  • $date['d'] Day

Note

since 0.3

This function can not be called statically.

Example

Using getDate()

<?php
...
$date = $nntp->getDate();
echo "Date: ".$date['m']."-".$date['d']."-".$date['y'];
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getBodyRaw() | PEAR Manual | Net_NNTP_Client::getGroups()


Net_NNTP_Client::getGroups()

Net_NNTP_Client::getGroups()

Net_NNTP_Client::getGroups() – Fetch list of avaible newsgroups

Synopsis

require_once 'Net/NNTP/Client.php';

array Net_NNTP_Client::getGroups ( )

Description

Returns a list of all avaible newsgroups

Return value

array - a two dimensional, nested array indicated by the name of the newsgroup, every entry contains information about the newsgroup:

  • $groups[newsgroup_name]['group'] Name of the newsgroup

  • $groups[newsgroup_name]['last'] Number of the last article

  • $groups[newsgroup_name]['first'] Number of the first article

  • $groups[newsgroup_name]['posting'] values: y - yes, n - no, m - moderated)

Note

This function can not be called statically.

Especially public news server can provide more then 30.000 newsgroup. So this function may runs longer then the maximum execution time set in the php.ini.

See

Net_NNTP_Client::selectGroup()

Example

Using getGroups()

<?php
...
$ret = $nntp->connect('news.php.net');
if( PEAR::isError($ret)) {
    // handle error
} else {
    // success
    $groups = $nntp->getGroups();
    // Print a list of avaible newsgroups
    foreach($groups as $group) {
        echo $group['group'].'<br>';
    }
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getDate() | PEAR Manual | Net_NNTP_Client::getHeader()


Net_NNTP_Client::getHeader()

Net_NNTP_Client::getHeader()

Net_NNTP_Client::getHeader() – Fetch the header of an article from the NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

object Net_NNTP_Client::getHeader ( string $article )

Description

This function is currently not documented.

See

Net_NNTP_Client::getHeaderRaw()

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getGroups() | PEAR Manual | Net_NNTP_Client::getHeaderRaw()


Net_NNTP_Client::getHeaderRaw()

Net_NNTP_Client::getHeaderRaw()

Net_NNTP_Client::getHeaderRaw() – fetch message header

Synopsis

require_once 'Net/NNTP/Client.php';

string Net_NNTP_Client::getHeaderRaw ( string $article , boolean $implode = false )

Description

Returns the whole header of an article in the currently selected newsgroup

Parameter

  • string $article - article number or Message-ID of the article to fetch

    boolean $implode - Determines if the resulting array is to be imploded into a string.

Return value

array/string - If message exists the header or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article |

Note

since 0.3

This function can not be called statically.

See

Net_NNTP_Client::getHeader() , Net_NNTP_Client::getArticleRaw() , Net_NNTP_Client::getBodyRaw()

Example

Using getHeaderRaw()

<?php
...

$headers = $nntp->getHeaderRaw($msgId);
if( PEAR::isError($headers)) {
    // handle error
} else {
    // success - split the string into a array
    $headersArray = explode( "\n", $headers);
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getHeader() | PEAR Manual | Net_NNTP_Client::getNewGroups()


Net_NNTP_Client::getNewGroups()

Net_NNTP_Client::getNewGroups()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getNewGroups ( mixed $$time )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getHeaderRaw() | PEAR Manual | Net_NNTP_Client::getNewNews()


Net_NNTP_Client::getNewNews()

Net_NNTP_Client::getNewNews()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getNewNews ( mixed $$time [, string $$pass ] )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getNewGroups() | PEAR Manual | Net_NNTP_Client::getOverview()


Net_NNTP_Client::getOverview()

Net_NNTP_Client::getOverview()

Net_NNTP_Client::getOverview() – Fetch newsgroup overview

Synopsis

require_once 'Net/NNTP/Client.php';

array Net_NNTP_Client::getOverview ( string $first , string $last )

Description

Returns (a certain range of) the overview of the currently selected newsgroup. selected newsgroup

Parameter

  • $first - first article number, start of the range

  • $last - last article number, end of the range

Return value

array - a nested array indicated by the message id of the article, every entry contains the header as array

<?php
$msgs[message_id][headername] = headercontent
?>

Note

This function can not be called statically.

Be careful with choosing the range. It could requires some time to get a huge number of message headers.

See

Net_NNTP_Client::getOverviewFormat()

Example

Using getOverview()

<?php
...
$ret = $nntp->connect('news.php.net');
if( PEAR::isError($ret)) {
 // handle error
} else {
 // print the last 10 messages
 $data = $nntp->selectGroup('php.pear.dev');
 $msgs = $nntp->getOverview( $data['last'] - 10, $data[last]);

 foreach($msgs as $msg) {
    // print subjects
    echo $msg['subject'].'<br>';
 }
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getNewNews() | PEAR Manual | Net_NNTP_Client::getReferencesOverview()


Net_NNTP_Client::getReferencesOverview()

Net_NNTP_Client::getReferencesOverview()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getReferencesOverview ( integer $$first , integer $$last )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getOverview() | PEAR Manual | Net_NNTP_Client::group()


Net_NNTP_Client::group()

Net_NNTP_Client::group()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::group ( string $$user , string $$pass [, integer $$authmode = NET_NNTP_AUTHORIGINAL ] )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::getReferencesOverview() | PEAR Manual | Net_NNTP_Client::isConnected()


Net_NNTP_Client::isConnected()

Net_NNTP_Client::isConnected()

Net_NNTP_Client :: () – Connected?

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::isConnected ( void )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::group() | PEAR Manual | Net_NNTP_Client::last()


Net_NNTP_Client::last()

Net_NNTP_Client::last()

Net_NNTP_Client :: () – Get the number of the last article in the current newsgroup

Synopsis

require_once 'Net/NNTP/Client.php';

public integer Net_NNTP_Client::last ( void )

Description

Retrieves the number of the last article in the current newsgroup.

Return value

integer - highest article number in newsgroup

Note

since 0.3

This function can not be called statically.

Example

Using last()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "highest message number: ".$nntp->last();
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::isConnected() | PEAR Manual | Net_NNTP_Client::post()


Net_NNTP_Client::post()

Net_NNTP_Client::post()

Net_NNTP_Client :: () –

Synopsis

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::post ( string $$newsgroups , string $$subject , string $$body , string $$from [, integer $$additional = '' ] )

This method is currently not documented.

This function is EXPERIMENTAL. That means, that the behaviour of this function, the function name, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this function at your own risk.

Description

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::last() | PEAR Manual | Net_NNTP_Client::quit()


Net_NNTP_Client::quit()

Net_NNTP_Client::quit()

Net_NNTP_Client :: () – Close the connection to the NNTP-server

Synopsis

require_once 'Net/NNTP/Client.php';

public void Net_NNTP_Client::post ( void )

Description

Close the connection to the NNTP-server

Note

This function can not be called statically.

See

Net_NNTP_Client::connect

Prev | Net_NNTP_Client | Next
Net_NNTP_Client::post() | PEAR Manual | Net_NNTP_Client::selectGroup()


Net_NNTP_Client::selectGroup()

Net_NNTP_Client::selectGroup()

Net_NNTP_Client::selectGroup() – select a newsgroup

Synopsis

require_once 'Net/NNTP/Client.php';

array Net_NNTP_Client::selectGroup ( string $newsgroup )

Description

Selects a specific newsgroup on the NNTP-server

Parameter

  • string $newsgroup - Name of the newsgroup to access

Return value

array - If the newsgroup exists, an array is returned:

Key | Value
'count' | Number of articles in the group
'first' | The first article number in the group
'last' | The last article number in the group
'group' | Groupname

otherwise a PEAR_Error is returned on fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article |

Note

This function can not be called statically.

See

Net_NNTP_Client::connect() , Net_NNTP_Client::getGroups()

Example

Using selectGroup()

<?php
...
$ret = $nntp->connect('news.php.net');
if( PEAR::isError($ret)) {
    // handle error
} else {
    // success
    $data = $nntp->selectGroup('php.pear.dev');
    // Print the count of articles
    echo "Count: ", $data['last'] - $data['first'];
}
?>
Prev | Net_NNTP_Client | Next
Net_NNTP_Client::quit() | PEAR Manual | Net_NNTP


Net_NNTP

Net_NNTP

Table of Contents
  • Constants -- predefined constants
  • Net_NNTP::command() -- send a command to a newsserver
  • Net_NNTP::connect() -- Connects to a newsserver
  • Net_NNTP::connectAuthenticated() -- Connects and authenticates to a newsserver
  • Net_NNTP::date() -- get date from news server
  • Net_NNTP::first() -- get lowest message number
  • Net_NNTP::getArticle() -- fetch an article from a new server
  • Net_NNTP::getArticleRaw() -- fetch an article from a new server
  • Net_NNTP::getBody() -- fetch the body of an article
  • Net_NNTP::getBodyRaw() -- fetch the body of an article
  • Net_NNTP::getDate() -- get date from news server
  • Net_NNTP::getGroups() -- fetch list of avaible newsgroups
  • Net_NNTP::getHeaderRaw() -- fetch message header
  • Net_NNTP::getHeaders() -- fetch message headers
  • Net_NNTP::getOverview() -- fetch a number of message headers
  • Net_NNTP::getOverviewFmt() -- fetch the name of message headers
  • Net_NNTP::getOverviewFormat() -- fetch the name of message headers
  • Net_NNTP::isConnected() -- check connection status
  • Net_NNTP::last() -- get highest message number
  • Net_NNTP::max() -- get highest message number
  • Net_NNTP::min() -- get lowest message number
  • Net_NNTP::post() -- post a message
  • Net_NNTP::prepareConnection() -- connects to a newsgroup on a newsserver
  • Net_NNTP::quit() -- disconnect from a newsserver
  • Net_NNTP::selectGroup() -- select a newsgroup
  • Net_NNTP::setDebug() -- setting debug mode
  • Net_NNTP::splitHeaders() -- fetch message headers into in array

This function is deprecated. That means that future versions of this package may not support it anymore.

The historical Net_NNTP class

Prev | Net_NNTP | Next
Net_NNTP_Client::selectGroup() | PEAR Manual | Constants


Constants

Constants

Constants – predefined constants

NET_NNTP_PROTOCOL_DEFAULT_HOST

default NNTP hostname: localhost

NET_NNTP_PROTOCOL_DEFAULT_PORT

default NNTP port: 119

NET_NNTP_AUTHORIGINAL

authentication provided by the NNTP-server

NET_NNTP_AUTHSIMPLE

authentication provided by the NNTP-server

NET_NNTP_AUTHGENERIC

authentication provided by the NNTP-server

PEAR_NNTP_ALL

deprecated (never used)

PEAR_NNTP_LIST

deprecated (never used)

PEAR_NNTP_NAMES

deprecated (never used)

PEAR_NNTP_AUTHORIGINAL

deprecated (use NET_NNTP_AUTHORIGINAL instead)

PEAR_NNTP_AUTHSIMPLE

deprecated (use NET_NNTP_AUTHSIMPLE instead)

PEAR_NNTP_AUTHGENERIC

deprecated (use NET_NNTP_AUTHGENERIC instead)

Prev | Net_NNTP | Next
Net_NNTP | PEAR Manual | Net_NNTP::command()


Net_NNTP::command()

Net_NNTP::command()

Net_NNTP::command() – send a command to a newsserver

Synopsis

require_once 'Net/NNTP.php';

string Net_NNTP::command ( string $cmd , boolean $auth )

Description

Command() sends a string command to a newsserver. So you can send customized and/ or non-standard commands to the newsserver.

Parameter

  • string $cmd - the command to send

  • boolean $auth - if TRUE, an auth request is issued before the command

Return value

string - the unprocessed server response

Note

This function can not be called statically.

Command() does no checks on the given command and/ or proccesses the server response. So you should know what are you doing.

Example

Using command()

<?php
...
$response = $nntp->command("ARTICLE 1004853");
?>
Prev | Net_NNTP | Next
Constants | PEAR Manual | Net_NNTP::connect()


Net_NNTP::connect()

Net_NNTP::connect()

Net_NNTP::connect() – Connects to a newsserver

Synopsis

require_once 'Net/NNTP.php';

boolean Net_NNTP::connect ( string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST , integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT )

Description

Connect to a specific newsserver

Parameter

  • $host - Hostname of the newsserver

  • $port - Port, where the newsserver listens

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
NULL "Could not connect to NNTP-server $host" or "Not connected" The connection couldn't be established because

  • wrong server name or adress

  • the host itself isn't link to a network

  • a firewall doesn't allow an access

 Check for server name, the connection to the net and possible firewalls on client or server side

Note

This function can not be called statically.

See

Net_NNTP::quit(), Net_NNTP::pepareConnection()

Example

Using connect()

<?php
require_once "Net/NNTP.php";

$nntp = new Net_NNTP;
$ret = $nntp->connect("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
}
?>
Prev | Net_NNTP | Next
Net_NNTP::command() | PEAR Manual | Net_NNTP::connectAuthenticated()


Net_NNTP::connectAuthenticated()

Net_NNTP::connectAuthenticated()

Net_NNTP::connectAuthenticated() – Connects and authenticates to a newsserver

Synopsis

require_once 'Net/NNTP.php';

boolean Net_NNTP::connectAuthenticated ( integer $user = null , integer $pass = null , string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST , integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT , integer $authmode = NET_NNTP_AUTHORIGINAL )

Description

Connect and authenticate to a specific newsserver

Parameter

  • $user - Username to authenticate

  • $pass - Password to authenticate

  • $host - Hostname of the NNTP-server

  • $port - Port, where the newsserver listens

  • $authmode - Type of authentication, at the moment only NET_NNTP_AUTHORIGINAL

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
NULL "Could not connect to NNTP-server $nntpserver" or "Not connected" The connection couldn't be established because

  • wrong server name or adress

  • the host itself isn't link to a network

  • a firewall doesn't allow an access

 Check for server name, the connection to the net and possible firewalls on client or server side

Note

since 0.3

This function can not be called statically.

See

Net_NNTP::connect() Net_NNTP::quit(),

Example

Using connectauthenticated()

<?php
require_once "Net/NNTP.php";

$nntp = new Net_NNTP;
$ret = $nntp->connectAuthenticated("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
}
?>
Prev | Net_NNTP | Next
Net_NNTP::connect() | PEAR Manual | Net_NNTP::date()


Net_NNTP::date()

Net_NNTP::date()

Net_NNTP::date() – get date from news server

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::date ( )

Description

This function is deprecated. That means that future versions of this package may not support it anymore.

Retrieves the date from the news server

Return value

array - a hash with the date

  • $date['y'] Year

  • $date['m'] Month

  • $date['d'] Day

Note

This function can not be called statically.

Example

Using date()

<?php
...
$date = $nntp->date();
echo "Date: ".$date['m']."-".$date['d']."-".$date['y'];
?>
Prev | Net_NNTP | Next
Net_NNTP::connectAuthenticated() | PEAR Manual | Net_NNTP::first()


Net_NNTP::first()

Net_NNTP::first()

Net_NNTP::first() – get lowest message number

Synopsis

require_once 'Net/NNTP.php';

integer Net_NNTP::first ( )

Description

Retrieves the lowest message number in the current selected newsgroup

Return value

integer - lowest message number

Note

since 0.3

This function can not be called statically.

Example

Using first()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "lowest message number: ".$nntp->first();
?>
Prev | Net_NNTP | Next
Net_NNTP::date() | PEAR Manual | Net_NNTP::getArticle()


Net_NNTP::getArticle()

Net_NNTP::getArticle()

Net_NNTP::getArticle() – fetch an article from a new server

Synopsis

require_once 'Net/NNTP.php';

mixed Net_NNTP::getArticle ( string $articleId )

Description

Returns the whole article from the current selected newsgroup

This function is deprecated. That means that future versions of this package may not support it anymore.

Consider this method deprecated and subject to changes - use Net_NNTP::getArticleRaw() instead.

Parameter

  • string $articleID - Message-ID of the message number to fetch

Return value

string - If message exists the message as string or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

This function can not be called statically.

See

Net_NNTP::getHeaders() , Net_NNTP::getBody() , Net_NNTP::getOverview()

Example

Using getArticle()

<?php
...
$article = $nntp->getArticle($msg_id);
if( PEAR::isError($article)) {
 // handle error
} else {
 // success
}
?>
Prev | Net_NNTP | Next
Net_NNTP::first() | PEAR Manual | Net_NNTP::getArticleRaw()


Net_NNTP::getArticleRaw()

Net_NNTP::getArticleRaw()

Net_NNTP::getArticleRaw() – fetch an article from a new server

Synopsis

require_once 'Net/NNTP.php';

mixed Net_NNTP::getArticleRaw ( string $articleId )

Description

Returns the whole article from the current selected newsgroup

Parameter

  • string $articleID - Message-ID of the message number to fetch

Return value

string - If message exists the message as string or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

since 0.3

This function can not be called statically.

See

Net_NNTP::getHeadersRaw() , Net_NNTP::getBodyRaw() , Net_NNTP::getOverview()

Example

Using getArticleRaw()

<?php
...
$article = $nntp->getArticleRaw($msg_id);
if( PEAR::isError($article)) {
 // handle error
} else {
 // success
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getArticle() | PEAR Manual | Net_NNTP::getBody()


Net_NNTP::getBody()

Net_NNTP::getBody()

Net_NNTP::getBody() – fetch the body of an article

Synopsis

require_once 'Net/NNTP.php';

string Net_NNTP::getBody ( string $articleId )

Description

Returns the whole body of an article in the current selected newsgroup from the webserver

This function is deprecated. That means that future versions of this package may not support it anymore.

Consider this method deprecated and subject to changes - use Net_NNTP::getBodyRaw() instead.

Parameter

  • string $articleId - Message-ID or Message number

Return value

string - If message exists the body as string or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

This function can not be called statically.

Note: getBody() makes no converting of the body content to any character set. You get the content 'as is'.

See

Net_NNTP::getHeaders() , Net_NNTP::splitHeaders() , Net_NNTP::getArticle() , Net_NNTP::getOverview()

Example

Using getBody()

<?php
...

$body = $nntp->getBody($msgId);
if( PEAR::isError($body)) {
 // handle error
} else {
 // success - print body
 echo $body;
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getArticleRaw() | PEAR Manual | Net_NNTP::getBodyRaw()


Net_NNTP::getBodyRaw()

Net_NNTP::getBodyRaw()

Net_NNTP::getBodyRaw() – fetch the body of an article

Synopsis

require_once 'Net/NNTP.php';

string Net_NNTP::getBodyRaw ( string $articleId )

Description

Returns the whole body of an article in the current selected newsgroup from the webserver

Parameter

  • string $articleId - Message-ID or Message number

Return value

string - If message exists the body as string or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

since 0.3

This function can not be called statically.

Note: getBody() makes no converting of the body content to any character set. You get the content 'as is'.

See

Net_NNTP::getHeaderRaw() , Net_NNTP::splitHeaders() , Net_NNTP::getArticleRaw() , Net_NNTP::getOverview()

Example

Using getBodyRaw()

<?php
...

$body = $nntp->getBodyRaw($msgId);
if( PEAR::isError($body)) {
 // handle error
} else {
 // success - print body
 echo $body;
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getBody() | PEAR Manual | Net_NNTP::getDate()


Net_NNTP::getDate()

Net_NNTP::getDate()

Net_NNTP::getDate() – get date from news server

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::getDate ( )

Description

Retrieves the date from the news server

Return value

array - a hash with the date

  • $date['y'] Year

  • $date['m'] Month

  • $date['d'] Day

Note

since 0.3

This function can not be called statically.

Example

Using getDate()

<?php
...
$date = $nntp->getDate();
echo "Date: ".$date['m']."-".$date['d']."-".$date['y'];
?>
Prev | Net_NNTP | Next
Net_NNTP::getBodyRaw() | PEAR Manual | Net_NNTP::getGroups()


Net_NNTP::getGroups()

Net_NNTP::getGroups()

Net_NNTP::getGroups() – fetch list of avaible newsgroups

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::getGroups ( string $fetch = true )

Description

Returns a list of all avaible newsgroups from the connected news server

Parameter

  • $fetch - can be irgnored, unused

Return value

array - a two dimensional, nested array indicated by the name of the newsgroup, every entry contains information about the newsgroup:

  • $groups[newsgroup_name]['group'] name of the newsgroup

  • $groups[newsgroup_name]['last'] message number of the last message

  • $groups[newsgroup_name]['first'] message number of the first message

  • $groups[newsgroup_name]['posting_allowed'] values: y - yes, n - no, m - moderated)

  • $groups[newsgroup_name]['desc'] newsgroup description

Note

This function can not be called statically.

Especially public news server can provide more then 30.000 newsgroup. So this function may runs longer then the maximum execution time set in the php.ini.

See

Net_NNTP::selectGroup()

Example

Using getGroups()

<?php
...
$ret = $nntp->connect("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
 $groups = $nntp->getGroups();
 // Print a list of avaible newsgroups
 foreach($groups as $group) {
    echo $group['group'].': '.$group['desc'].'<br>';
 }
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getDate() | PEAR Manual | Net_NNTP::getHeaderRaw()


Net_NNTP::getHeaderRaw()

Net_NNTP::getHeaderRaw()

Net_NNTP::getHeaderRaw() – fetch message header

Synopsis

require_once 'Net/NNTP.php';

string Net_NNTP::getHeaderRaw ( string $articleId )

Description

Returns all avaible header lines of a specified message in the current selected newsgroup

Parameter

  • string $articleId - Message-ID or Message number

Return value

string - If message exists the header as string or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

since 0.3

This function can not be called statically.

See

Net_NNTP::splitHeaders() , Net_NNTP::getBodyRaw() , Net_NNTP::getOverview()

Example

Using getHeaderRaw()

<?php
...

$headers = $nntp->getHeaderRaw($msgId);
if( PEAR::isError($headers)) {
 // handle error
} else {
 // success - split the string into a array
 $headersArray = explode( "\n", $headers);
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getGroups() | PEAR Manual | Net_NNTP::getHeaders()


Net_NNTP::getHeaders()

Net_NNTP::getHeaders()

Net_NNTP::getHeaders() – fetch message headers

Synopsis

require_once 'Net/NNTP.php';

string Net_NNTP::getHeaders ( string $articleId )

Description

Returns all avaible header lines of a specified message in the current selected newsgroup

This function is deprecated. That means that future versions of this package may not support it anymore.

Consider this method deprecated and subject to changes - use Net_NNTP::getHeaderRaw() instead.

Parameter

  • string $articleId - Message-ID or Message number

Return value

string - If message exists the headers as string or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

This function can not be called statically.

See

Net_NNTP::splitHeaders() , Net_NNTP::getBody() , Net_NNTP::getOverview()

Example

Using getHeaders()

<?php
...

$headers = $nntp->getHeaders($msgId);
if( PEAR::isError($headers)) {
 // handle error
} else {
 // success - split the string into a array
 $headersArray = explode( "\n", $headers);
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getHeaderRaw() | PEAR Manual | Net_NNTP::getOverview()


Net_NNTP::getOverview()

Net_NNTP::getOverview()

Net_NNTP::getOverview() – fetch a number of message headers

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::getOverview ( string $first , string $last )

Description

Returns all message headers in a certain range of the current selected newsgroup

Parameter

  • $first - start message id, start of the range

  • $last - last message id, end of the range

Return value

array - a nested array indicated by the message id of the article, every entry contains the header as array

<?php
$msgs[message_id][headername] = headercontent
?>

Note

This function can not be called statically.

Be careful with choosing the range. It could requires some time to get a huge number of message headers.

See

Net_NNTP::getOverviewFmt()

Example

Using getOverview()

<?php
...
$ret = $nntp->connect("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // print the last 10 messages
 $data = $nntp->selectGroup("php.pear.dev");
 $msgs = $nntp->getOverview( $data['last'] - 10, $data[last]);

 foreach($msgs as $msg) {
    // print subjects
    echo $msg['Subject'].'<br>';
 }
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getHeaders() | PEAR Manual | Net_NNTP::getOverviewFmt()


Net_NNTP::getOverviewFmt()

Net_NNTP::getOverviewFmt()

Net_NNTP::getOverviewFmt() – fetch the name of message headers

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::getOverviewFmt ( )

Description

Returns the name of message headers, which is provided by every message

Return value

array - list of header names

Note

This function can not be called statically.

See

Net_NNTP::getOverview()

Example

Using getOverviewFmt()

<?php
...
$tblheaders = $nntp->getOverviewFmt();
// create a table headline
echo '<table>';
echo '<tr>';
foreach($tblheaders as $th) {
   // print headernames
   echo '<th>'.$th.'</th>';
}
echo '</tr>';
... // draw the header data of messages
echo '</table>';
?>
Prev | Net_NNTP | Next
Net_NNTP::getOverview() | PEAR Manual | Net_NNTP::getOverviewFormat()


Net_NNTP::getOverviewFormat()

Net_NNTP::getOverviewFormat()

Net_NNTP::getOverviewFormat() – fetch the name of message headers

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::getOverviewFormat ( )

Description

Returns the name of message headers, which is provided by every message

Return value

array - list of header names

Note

This function can not be called statically.

See

Net_NNTP::getOverview()

Example

Using getOverviewFmt()

<?php
...
$tblheaders = $nntp->getOverviewFormat();
// create a table headline
echo '<table>';
echo '<tr>';
foreach($tblheaders as $th) {
   // print headernames
   echo '<th>'.$th.'</th>';
}
echo '</tr>';
... // draw the header data of messages
echo '</table>';
?>
Prev | Net_NNTP | Next
Net_NNTP::getOverviewFmt() | PEAR Manual | Net_NNTP::isConnected()


Net_NNTP::isConnected()

Net_NNTP::isConnected()

Net_NNTP::isConnected() – check connection status

Synopsis

require_once 'Net/NNTP.php';

boolean Net_NNTP::isConnected ( )

Description

Returns the status of the connection

Return value

boolean - TRUE, if connected

Note

This function can not be called statically.

Example

Using isConnected()

<?php
...
if(PEAR::isError($response)) {
    // something goes wrong, check if we are still connected
    if($nntp->isConnected()) {
        echo "disconnected from newsserver!"
        ...
    }
}
?>
Prev | Net_NNTP | Next
Net_NNTP::getOverviewFormat() | PEAR Manual | Net_NNTP::last()


Net_NNTP::last()

Net_NNTP::last()

Net_NNTP::last() – get highest message number

Synopsis

require_once 'Net/NNTP.php';

integer Net_NNTP::last ( )

Description

Retrieves the highest message number in the current selected newsgroup

Return value

integer - highest message number

Note

since 0.3

This function can not be called statically.

Example

Using last()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "highest message number: ".$nntp->last();
?>
Prev | Net_NNTP | Next
Net_NNTP::isConnected() | PEAR Manual | Net_NNTP::max()


Net_NNTP::max()

Net_NNTP::max()

Net_NNTP::max() – get highest message number

Synopsis

require_once 'Net/NNTP.php';

integer Net_NNTP::max ( )

Description

This function is deprecated. That means that future versions of this package may not support it anymore.

Retrieves the highest message number in the current selected newsgroup

Return value

integer - highest message number

Note

This function can not be called statically.

Example

Using max()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "highest message number: ".$nntp->max();
?>
Prev | Net_NNTP | Next
Net_NNTP::last() | PEAR Manual | Net_NNTP::min()


Net_NNTP::min()

Net_NNTP::min()

Net_NNTP::min() – get lowest message number

Synopsis

require_once 'Net/NNTP.php';

integer Net_NNTP::min ( )

Description

This function is deprecated. That means that future versions of this package may not support it anymore.

Retrieves the lowest message number in the current selected newsgroup

Return value

integer - lowest message number

Note

This function can not be called statically.

Example

Using min()

<?php
...
$nntp->selectGroup("php.pear.dev");
echo "lowest message number: ".$nntp->min();
?>
Prev | Net_NNTP | Next
Net_NNTP::max() | PEAR Manual | Net_NNTP::post()


Net_NNTP::post()

Net_NNTP::post()

Net_NNTP::post() – post a message

Synopsis

require_once 'Net/NNTP.php';

string Net_NNTP::post ( string $subject , string $newsgroup , string $from , string $body , string $additional )

Description

Post a message to a news server

Parameter

  • $subject - Subject of the message

  • $newsgroup - Post to this newsgroup

  • $from - EMail adress of sender

  • $body - Body of the message

  • $additional - String of headers to add

Return value

string - Server response

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "Not connected" | You forgot the set up a connection to a news server or the connection was already again closed. | Open a connection before using post(). Check the connection status before using post().

Note

This function can not be called statically.

post() doesn't care about character encoding of subject and body. Make sure to set correct headers, if you are using non ASCII-127 characters.

Example

Using post()

<?php
...

$subject   = "Testpost";
$newsgroup = "php.test";
$body      = "Le Mardi 12 f=E9vrier 2002, this is a test message using special french chars";
$from      = "test@example.com";
$addheader = "Content-Transfer-Encoding: quoted-printable\n".
             "Content-Type: text/plain; charset=ISO-8859-1;";

$response = $nntp->post($subject, $newsgroup, $from, $body, $addheader);
...
?>
Prev | Net_NNTP | Next
Net_NNTP::min() | PEAR Manual | Net_NNTP::prepareConnection()


Net_NNTP::prepareConnection()

Net_NNTP::prepareConnection()

Net_NNTP::prepareConnection() – connects to a newsgroup on a newsserver

Synopsis

require_once 'Net/NNTP.php';

boolean Net_NNTP::prepareConnection ( string $nntpserver , integer $port = 119 , integer $newsgroup , integer $user = null , integer $pass = null , integer $authmode = PEAR_NNTP_ORIGINAL )

Description

Connect to a specific newsserver and access the given newsgroup

This function is deprecated. That means that future versions of this package may not support it anymore.

Consider this method deprecated - use Net_NNTP::connectAuthenticated() instead.

Parameter

  • $nntpserver - Name of the newsserver to connect

  • $port - Port, where the newsserver listens

  • $newsgroup - Newsgroup to access

  • $user - Username to authenticate

  • $user - Username to authenticate

  • $pass - Password to authenticate

  • $authmode - Type of authentication, at the moment only PEAR_NNTP_AUTHORIGINAL

Return value

boolean - TRUE if successful

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL "Could not connect to NNTP-server $nntpserver" or "Not connected" The connection couldn't be established because

  • wrong server name or adress

  • the host itself isn't link to a network

  • a firewall doesn't allow an access

 Check for server name, the connection to the net and possible firewalls on client or server side
NULL | Every other message | This message is directly passed from the news server, in the most cases caused by calling a non existing newsgroup | Check the given newsgroup name

Note

This function can not be called statically.

This function is deprecated. That means that future versions of this package may not support it anymore.

Fetching data with a connection created with prepareConnection() is faster then a created connection with connect()

See

Net_NNTP::quit(), Net_NNTP::connect()

Example

Using prepareConnection()

<?php
require_once "Net/NNTP.php";

$nntp = new Net_NNTP;
$ret = $nntp->connect("news.php.net", 119, "php.pear.dev");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
}
?>
Prev | Net_NNTP | Next
Net_NNTP::post() | PEAR Manual | Net_NNTP::quit()


Net_NNTP::quit()

Net_NNTP::quit()

Net_NNTP::quit() – disconnect from a newsserver

Synopsis

require_once 'Net/NNTP.php';

void Net_NNTP::quit ( )

Description

Close connection to a newsserver

Note

This function can not be called statically.

See

Net_NNTP::connect(), Net_NNTP::prepareConnection()

Prev | Net_NNTP | Next
Net_NNTP::prepareConnection() | PEAR Manual | Net_NNTP::selectGroup()


Net_NNTP::selectGroup()

Net_NNTP::selectGroup()

Net_NNTP::selectGroup() – select a newsgroup

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::selectGroup ( string $newsgroup )

Description

Selects a specific newsgroup on the news server

Parameter

  • string $newsgroup - Name of the newsgroup to access

Return value

array - If the newsgroup exists an array containing the message number of the first (array key: ['first'] ) and the last message id (array key: ['last'] ) or a PEAR_Error, if fail.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

This function can not be called statically.

See

Net_NNTP::connect() , Net_NNTP::getGroups()

Example

Using selectGroup()

<?php
...
$ret = $nntp->connect("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
 $data = $nntp->selectGroup("php.pear.dev");
 // Print the count of articles
 echo "Count: ", $data['last'] - $data['first'];
}
?>
Prev | Net_NNTP | Next
Net_NNTP::quit() | PEAR Manual | Net_NNTP::setDebug()


Net_NNTP::setDebug()

Net_NNTP::setDebug()

Net_NNTP::setDebug() – setting debug mode

Synopsis

require_once 'Net/NNTP.php';

void Net_NNTP::setDebug ( boolean $on = true )

Description

Enables or disables debug mode for Net_NNTP

Parameter

  • boolean $on - TRUE = debug on, FALSE = debug off

Note

This function can not be called statically.

Prev | Net_NNTP | Next
Net_NNTP::selectGroup() | PEAR Manual | Net_NNTP::splitHeaders()


Net_NNTP::splitHeaders()

Net_NNTP::splitHeaders()

Net_NNTP::splitHeaders() – fetch message headers into in array

Synopsis

require_once 'Net/NNTP.php';

array Net_NNTP::splitHeaders ( string $articleId )

Description

Returns all avaible header lines of a specified message of the current selected newsgroup into an array

Parameter

  • string $articleId - Message-ID or Message number

Return value

array - if message exists the headers as array or a PEAR_Error, if fail. The array is an associative array with the header names as key.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | Different error messages | The messages are directly passed from the news server, in the most cases caused by calling a non existing article | Check the article ID or if your are still connected to the server ( Net_NNTP::isConnected())

Note

This function can not be called statically.

See

Net_NNTP::getHeaders() , Net_NNTP::getBody() , Net_NNTP::getOverview()

Example

Using splitHeaders()

<?php
...

$headers = $nntp->splitHeaders($msg_id);
if( PEAR::isError($headers)) {
 // handle error
} else {
 // success - print all headers line
 foreach($headers as $headerName => $headerValue) {
 echo $headerName.': '.$headerValue.'<br>';
 }
}
?>
Prev | Net_NNTP | Next
Net_NNTP::setDebug() | PEAR Manual | Net_NNTP_Header


Net_NNTP_Header

Net_NNTP_Header

This module is EXPERIMENTAL. That means that the behaviour of these functions, these function names, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this module at your own risk.

This package is not documented yet.

Prev | Net_NNTP | Next
Net_NNTP::splitHeaders() | PEAR Manual | Net_NNTP_Message


Net_NNTP_Message

Net_NNTP_Message

This module is EXPERIMENTAL. That means that the behaviour of these functions, these function names, in concreto ANYTHING documented here can change in a future release of this package WITHOUT NOTICE. Be warned, and use this module at your own risk.

This package is not documented yet.

Prev | Net_NNTP | Next
Net_NNTP_Header | PEAR Manual | Net_NNTP_Protocol_Client


Net_NNTP_Protocol_Client

Net_NNTP_Protocol_Client

Table of Contents
  • Constants -- predefined constants

Low level NNTP client implementation.

This package is not documented yet.

Prev | Net_NNTP | Next
Net_NNTP_Message | PEAR Manual | Constants


Constants

Constants

Constants – predefined constants

NET_NNTP_PROTOCOL_CLIENT_DEFAULT_HOST

default NNTP hostname: localhost

NET_NNTP_PROTOCOL_CLIENT_DEFAULT_PORT

default NNTP port: 119

Prev | Net_NNTP_Protocol_Client | Next
Net_NNTP_Protocol_Client | PEAR Manual | Net_Ping


Net_Ping

Net_Ping

API for the Ping command

Table of Contents
  • Net_Ping::Net_Ping() -- constructor
  • Net_Ping::ping() -- executes a ping command
  • Net_Ping::setArgs() -- set arguments for a ping command
Prev | Networking | Next
Constants | PEAR Manual | Net_Ping::Net_Ping()


Net_Ping::Net_Ping()

Net_Ping::Net_Ping()

Net_Ping::Net_Ping() – constructor

Synopsis

require_once 'Net/Ping.php';

void Net_Ping::Net_Ping ( )

Description

Please use Net_Ping::factory() instead of using this constructor directly.

Prev | Net_Ping | Next
Net_Ping | PEAR Manual | Net_Ping::ping()


Net_Ping::ping()

Net_Ping::ping()

Net_Ping::ping() – executes a ping command

Synopsis

require_once 'Net/Ping.php';

string Net_Ping::ping ( string host )

Description

Executes a ping command

Parameter

  • string $host - the name of the server or the IP-adress

Return value

string - the return message of the ping command

Note

This function can not be called statically.

Example

Sending a ping request

<?php
require_once "Net/Ping.php";
$ping = Net_Ping::factory();
if (PEAR::isError($ping)) {
    echo $ping->getMessage();
} else {
    $ping->setArgs(array('count' => 2));
    var_dump($ping->ping('example.com'));
}
?>
Prev | Net_Ping | Next
Net_Ping::Net_Ping() | PEAR Manual | Net_Ping::setArgs()


Net_Ping::setArgs()

Net_Ping::setArgs()

Net_Ping::setArgs() – set arguments for a ping command

Synopsis

require_once 'Net/Ping.php';

boolean Net_Ping::setArgs ( array $args )

Description

Set the arguments for a ping command

Parameter

  • array $args - an array of the arguments to set

    possible array keys
    Key name | Description | NOT supported on
    "count" | Number of ping packages to send
    "quiet" | Level of output verbosity | Windows
    "iface" | FreeBSD, Linux, Windows
    "ttl"
    "timeout" | Time to wait for a ACK of a ping package
    "size" | Size of a ping package | FreeBSD, Darwin, Linux, Windows

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | PING_INVALID_ARGUMENTS | A not supported argument was given | Check typing of argument (key name) and OS-support of the argument.

Note

This function can not be called statically.

Prev | Net_Ping | Next
Net_Ping::ping() | PEAR Manual | Net_POP3


Net_POP3

Net_POP3

Provides a POP3 class to access POP3 server.

Table of Contents
  • Introduction to Net_POP3
  • Net_POP3::Net_POP3() -- Constructor
  • Net_POP3::connect() -- Connection to POP3 server
  • Net_POP3::deleteMsg() -- Marks a message for deletion
  • Net_POP3::disconnect() -- Disconnection to POP3 server
  • Net_POP3::getBody() -- Returns the body of the message
  • Net_POP3::getListing() -- Listing message in maildrop
  • Net_POP3::getMsg() -- Returns the entire message
  • Net_POP3::getParsedHeaders() -- Returns the parsed headers of the specified message
  • Net_POP3::getRawHeaders() -- Returns the raw headers of the specified message
  • Net_POP3::getSize() -- Returns the size of the maildrop
  • Net_POP3::login() -- Performs the login procedure
  • Net_POP3::numMsg() -- number of messages in this maildrop
Prev | Networking | Next
Net_Ping::setArgs() | PEAR Manual | Introduction to Net_POP3


Introduction to Net_POP3

Introduction to Net_POP3

Introduction to Net_POP3 –

About Net_POP3

Provides a POP3 class to access POP3 servers. Supports all POP3 commands including UIDL listings and APOP authentication.

Note: Usage of this class compared to native PHP extensions such as IMAP is slow and may be feature deficient. If available you are STRONGLY recommended to use the PHP extensions.

Usage example for Net_POP3

Usage

<?php
include 'Net/POP3.php';

$pop3 =& new Net_POP3();

/*
 * Connect to localhost on usual port
 * If not given, defaults are localhost:110
 */
$pop3->connect('localhost', 110);

/*
 * Login using username/password. APOP will
 * be tried first if supported, then basic.
 */
$pop3->login('richard', 'Alien3');

/*
 * Get the raw headers of message 1
 */
echo '<h2>getRawHeaders()</h2>';
echo '<pre>' . htmlspecialchars($pop3->getRawHeaders(1)) . '</pre>';

/*
 * Get structured headers of message 1
 */
echo '<h2>getParsedHeaders()</h2> <pre>';
print_r($pop3->getParsedHeaders(1));
echo '</pre>';

/*
 * Get body of message 1
 */
echo '<h2>getBody()</h2>';
echo '<pre>' . htmlspecialchars($pop3->getBody(1)) . '</pre>';

/*
 * Get number of messages in maildrop
 */
echo '<h2>getNumMsg</h2>';
echo '<pre>' . $pop3->numMsg() . '</pre>';

/*
 * Get entire message
 */
echo '<h2>getMsg()</h2>';
echo '<pre>' . htmlspecialchars($pop3->getMsg(1)) . '</pre>';

/*
 * Get listing details of the maildrop
 */
echo '<h2>getListing()</h2>';
echo '<pre>';
print_r($pop3->getListing());
echo '</pre>';

/*
 * Get size of maildrop
 */
echo '<h2>getSize()</h2>';
echo '<pre>' . $pop3->getSize() . '</pre>';

$pop3->disconnect();
?>
Prev | Net_POP3 | Next
Net_POP3 | PEAR Manual | Net_POP3::Net_POP3()


Net_POP3::Net_POP3()

Net_POP3::Net_POP3()

Net_POP3::Net_POP3() – Constructor

Synopsis

require_once 'Net/POP3.php';

Net_POP3::Net_POP3 ( )

Description

Constructor. Sets up the object variables, and instantiates the socket object.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Introduction to Net_POP3 | PEAR Manual | Net_POP3::connect()


Net_POP3::connect()

Net_POP3::connect()

Net_POP3::connect() – Connection to POP3 server

Synopsis

require_once 'Net/POP3.php';

boolean Net_POP3::connect ( string $host , integer $port )

Description

Connects to the given host on the given port. Also looks for the timestamp in the greeting needed for APOP authentication.

Parameter

  • string $host - Hostname/IP address to connect to

  • integer $port - Port to use to connect to on host

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::Net_POP3() | PEAR Manual | Net_POP3::deleteMsg()


Net_POP3::deleteMsg()

Net_POP3::deleteMsg()

Net_POP3::deleteMsg() – Marks a message for deletion

Synopsis

require_once 'Net/POP3.php';

boolean Net_POP3::deleteMsg ( integer $msg_id )

Description

Marks a message for deletion. Only will be deleted if the disconnect() method is called.

Parameter

  • integer $msg_id - Message to delete

Return value

mixed - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::connect() | PEAR Manual | Net_POP3::disconnect()


Net_POP3::disconnect()

Net_POP3::disconnect()

Net_POP3::disconnect() – Disconnection to POP3 server

Synopsis

require_once 'Net/POP3.php';

boolean Net_POP3::disconnect ( )

Description

Disconnect function. Sends the QUIT command and closes the socket.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::deleteMsg() | PEAR Manual | Net_POP3::getBody()


Net_POP3::getBody()

Net_POP3::getBody()

Net_POP3::getBody() – Returns the body of the message

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::getBody ( integer $msg_id )

Description

Returns the body of the message with given message number.

Parameter

  • integer $msg_id - Message number

Return value

mixed - Either message body or FALSE on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::disconnect() | PEAR Manual | Net_POP3::getListing()


Net_POP3::getListing()

Net_POP3::getListing()

Net_POP3::getListing() – Listing message in maildrop

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::getListing ( integer $msg_id )

Description

Listing message in maildrop. Combination of LIST/UIDL commands, returns an array of data.

Parameter

  • integer $msg_id - Optional message number

Return value

mixed - Array of data or false on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::getBody() | PEAR Manual | Net_POP3::getMsg()


Net_POP3::getMsg()

Net_POP3::getMsg()

Net_POP3::getMsg() – Returns the entire message

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::getMsg ( integer $msg_id )

Description

Returns the entire message with given message number.

Parameter

  • integer $msg_id - Message number

Return value

mixed - Either entire message or FALSE on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::getListing() | PEAR Manual | Net_POP3::getParsedHeaders()


Net_POP3::getParsedHeaders()

Net_POP3::getParsedHeaders()

Net_POP3::getParsedHeaders() – Returns the parsed headers of the specified message

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::getParsedHeaders ( integer $msg_id )

Description

Returns the headers of the specified message in an associative array. Array keys are the header names, array values are the header values. In the case of multiple headers having the same names, eg Received:, the array value will be an indexed array of all the header values.

Parameter

  • integer $msg_id - Message number

Return value

mixed - Either array of headers or FALSE on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::getMsg() | PEAR Manual | Net_POP3::getRawHeaders()


Net_POP3::getRawHeaders()

Net_POP3::getRawHeaders()

Net_POP3::getRawHeaders() – Returns the raw headers of the specified message

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::getRawHeaders ( integer $msg_id )

Description

Returns the raw headers of the specified message.

Parameter

  • integer $msg_id - Message number

Return value

strings - Either raw headers or FALSE on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::getParsedHeaders() | PEAR Manual | Net_POP3::getSize()


Net_POP3::getSize()

Net_POP3::getSize()

Net_POP3::getSize() – Returns the size of the maildrop

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::getSize ( )

Description

Returns the size of the maildrop.

Return value

mixed - Either size of maildrop or FALSE on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::getRawHeaders() | PEAR Manual | Net_POP3::login()


Net_POP3::login()

Net_POP3::login()

Net_POP3::login() – Performs the login procedure

Synopsis

require_once 'Net/POP3.php';

boolean Net_POP3::login ( string $user string $pass boolean $apop )

Description

Performs the login procedure. If there is a timestamp stored, APOP will be tried first, then basic USER/PASS.

Parameter

  • string $user - Username to use

  • string $pass - Password to use

  • boolean $apop - Whether to try APOP first

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::getSize() | PEAR Manual | Net_POP3::numMsg()


Net_POP3::numMsg()

Net_POP3::numMsg()

Net_POP3::numMsg() – number of messages in this maildrop

Synopsis

require_once 'Net/POP3.php';

mixed Net_POP3::numMsg ( )

Description

Returns number of messages in this maildrop.

Return value

mixed - Either number of messages or FALSE on error.

Note

This function can not be called statically.

Prev | Net_POP3 | Next
Net_POP3::login() | PEAR Manual | Net_Portscan


Net_Portscan

Net_Portscan

Provides an API for scanning ports

Table of Contents
  • Net_Portscan::checkPort() -- check for available service
  • Net_Portscan::checkPortRange() -- check for available services
  • Net_Portscan::getPort() -- port number of a service
  • Net_Portscan::getService() -- name of the service
Prev | Networking | Next
Net_POP3::numMsg() | PEAR Manual | Net_Portscan::checkPort()


Net_Portscan::checkPort()

Net_Portscan::checkPort()

Net_Portscan::checkPort() – check for available service

Synopsis

require_once 'Net/Portscan.php';

boolean Net_Portscan::checkPort ( string $host , integer $port , integer $timeout = 30 )

Description

This function checks if there is a service available at the specified port on the specified machine.

Parameter

  • string $host - address of the host to check

  • string $port - port to check

  • string $timeout - time in seconds to wait for response from host

    Important: If you run into timeout problems despite setting this parameter to a reasonably high value, you need to make sure that the configuration directive default_socket_timeout in the php.ini configuration file does not force the maximum timeout down to a lower value.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can be called statically.

Example

Using checkPort

<?php
require_once "Net_Portscan/Portscan.php";

if (Net_Portscan::checkPort("localhost", 80) == NET_PORTSCAN_SERVICE_FOUND) {
    echo "There is a service on localhost on port 80 (" . Net_Portscan::getService(80) . ").\n";
}
?>
Prev | Net_Portscan | Next
Net_Portscan | PEAR Manual | Net_Portscan::checkPortRange()


Net_Portscan::checkPortRange()

Net_Portscan::checkPortRange()

Net_Portscan::checkPortRange() – check for available services

Synopsis

require_once 'Net/Portscan.php';

array Net_Portscan::checkPortRange ( string $host , integer $minPort , integer $maxPort , integer $timeout = 30 )

Description

This function checks if there are services available at the specified ports on the specified machine.

Parameter

  • string $host - address of the host to check

  • string $minPort - lowest port to test to check

  • string $maxPort - highest port to test to check

  • string $timeout - time in seconds to wait for every response from host

    Important: If you run into timeout problems despite setting this parameter to a reasonably high value, you need to make sure that the configuration directive default_socket_timeout in the php.ini configuration file does not force the maximum timeout down to a lower value.

Return value

array - An associative array containing the scanning results for each port.

Note

This function can be called statically.

Example

Using checkPortRange

<?php
require_once "Net_Portscan/Portscan.php";

echo "Scanning localhost ports 70-90\n";
$result = Net_Portscan::checkPortRange("localhost", 70, 90);

foreach ($result as $port => $element) {
    if ($element == NET_PORTSCAN_SERVICE_FOUND) {
        echo "A service has been found on port " . $port . ".\n";
    } else {
        echo "No service has been found on port " . $port . ".\n";
    }
}
?>
Prev | Net_Portscan | Next
Net_Portscan::checkPort() | PEAR Manual | Net_Portscan::getPort()


Net_Portscan::getPort()

Net_Portscan::getPort()

Net_Portscan::getPort() – port number of a service

Synopsis

require_once 'Net/Portscan.php';

integer Net_Portscan::getPort ( string $service , string $protocol = 'tcp' )

Description

This function returns the port which corresponds to service for the specified protocol as per /etc/services.

Parameter

  • string $service - name of the service to check

  • string $protocol - access protocol

Return value

integer - port number of the service

Note

This function can be called statically.

The port number is retrieved from the machine where Net_Portscan is executed, not from the remote host, which you possibly used in Net_Portscan::checkPort().

Prev | Net_Portscan | Next
Net_Portscan::checkPortRange() | PEAR Manual | Net_Portscan::getService()


Net_Portscan::getService()

Net_Portscan::getService()

Net_Portscan::getService() – name of the service

Synopsis

require_once 'Net/Portscan.php';

string Net_Portscan::checkPortRange ( integer $port , string $protocol = 'tcp' )

Description

This function returns the service associated with port for the specified protocol as per '/etc/services'.

Parameter

  • integer $port - port to check

  • string $protocol - access protocol

Return value

string - name of service running on the port

Note

This function can be called statically.

The name of the service is retrieved from the machine where Net_Portscan is executed, not from the remote host, which you possibly used in Net_Portscan::checkPort().

Prev | Net_Portscan | Next
Net_Portscan::getPort() | PEAR Manual | Net_Server


Net_Server

Net_Server

Generic server package for creating daemons.

Table of Contents
  • Introduction -- Introduction to Net_Server
  • Example -- using Net_Server
  • Class Summary Net_Server -- PHP socket server base class
  • Net_Server::create -- create a new server
  • Class Summary Net_Server_Driver -- Base class for all drivers
  • Net_Server_Driver::getLastSocketError -- return string for last socket error
  • Net_Server_Driver::setCallbackObject -- register a callback object, that is used to handle all events
  • Net_Server_Driver::setDebugMode -- set debug mode
  • Class Summary Net_Server_Driver_Fork -- Forking server class.
  • Net_Server_Driver_Fork::broadcastData -- send data to all clients
  • Net_Server_Driver_Fork::closeConnection -- close the current connection
  • Net_Server_Driver_Fork::getClientInfo -- get current information about a client
  • Net_Server_Driver_Fork::getClients -- get current amount of clients
  • Net_Server_Driver_Fork::isConnected -- check, whether a client is still connected
  • Net_Server_Driver_Fork::sendData -- send data to a client
  • Net_Server_Driver_Fork::serviceRequest -- service the current request
  • Net_Server_Driver_Fork::setMaxClients -- set maximum amount of simultaneous connections
  • Net_Server_Driver_Fork::shutDown -- shutdown server
  • Net_Server_Driver_Fork::start -- start the server
  • Class Summary Net_Server_Driver_Sequential -- Sequential server class.
  • Net_Server_Driver_Sequential::acceptConnection -- accept a new connection
  • Net_Server_Driver_Sequential::broadcastData -- send data to all clients
  • Net_Server_Driver_Sequential::closeConnection -- close connection to a client
  • Net_Server_Driver_Sequential::getClientInfo -- get current information about a client
  • Net_Server_Driver_Sequential::getClients -- get current amount of clients
  • Net_Server_Driver_Sequential::isConnected -- check, whether a client is still connected
  • Net_Server_Driver_Sequential::sendData -- send data to a client
  • Net_Server_Driver_Sequential::setMaxClients -- set maximum amount of simultaneous connections
  • Net_Server_Driver_Sequential::shutDown -- shutdown server
  • Net_Server_Driver_Sequential::start -- start the server
  • Class Summary Net_Server_Handler -- Base class for all handlers
  • Net_Server_Handler::onClose -- onClose handler
  • Net_Server_Handler::onConnect -- onConnect handler
  • Net_Server_Handler::onConnectionRefused -- onConnectionRefused handler
  • Net_Server_Handler::onIdle -- onIdle handler
  • Net_Server_Handler::onReceiveData -- onReceiveData handler
  • Net_Server_Handler::onShutdown -- onShutdown handler
  • Net_Server_Handler::onStart -- onStart handler
  • Net_Server_Handler::setServerReference -- set a reference to the server object
  • Package Net_Server Constants -- Constants defined in and used by Net_Server
Prev | Networking | Next
Net_Portscan::getService() | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Net_Server

Introduction to Net_Server

Net_Server provides an interface to create daemon application based on the sockets extension of PHP 4. In order to use Net_Server you need a PHP version greater or equal PHP 4.2, it is meant to be used with PHP-CLI.

Net_Server uses a driver based architecture that allows you to switch the drivers for your daemons. Currently a forking and a non-forking driver are available, others will follow.

As Net_Server provides an abstraction layer for the sockets extension, you do not need internal knowledge about the PHP functions. All you have to do is implement callback functions for events in your daemon, like handling new connections or incoming data.

Prev | Net_Server | Next
Net_Server | PEAR Manual | Example


Example

Example

Example – using Net_Server

Creating a simple daemon

The following example shows, how easy it is to build a forking server that receives data and sends it back to the user.

Creating a simple talkback daemon

#!/usr/local/bin/php
<?php
    // server base class
    require_once 'Net/Server.php';

    // base class for the handler
    require_once 'Net/Server/Handler.php';

/**
 * simple example that implements a talkback.
 *
 * Normally this should be a bit more code and in a separate file
 */
class Net_Server_Handler_Talkback extends Net_Server_Handler
{
   /**
    * If the user sends data, send it back to him
    *
    * @access   public
    * @param    integer $clientId
    * @param    string  $data
    */
    function    onReceiveData( $clientId = 0, $data = "" )
    {
        $this->_server->sendData( $clientId, "You said: $data" );
    }
}

    // create a server that forks new processes
    $server  = &Net_Server::create('fork', 'localhost', 9090);

    $handler = &new Net_Server_Handler_Talkback;

    // hand over the object that handles server events
    $server->setCallbackObject($handler);

    // start the server
    $server->start();
?>
Prev | Net_Server | Next
Introduction | PEAR Manual | Class Summary Net_Server


Class Summary Net_Server

Class Summary Net_Server

Class Summary Net_Server – PHP socket server base class

PHP socket server base class

This class must only be used to create a new server using the static method 'create()'.

To handle the events that happen while the server is running you have to create a new class that handles all events.

1     require_once 'myHandler.php';
2      require_once 'Net/Server.php';
3
4      $server = &
Net_Server
::
create
('fork', 'localhost', 9090);
5
6      $handler = &new myHandler;
7
8      $server->setCallbackObject($handler);
9
10     $server->start();

See Server/Handler.php for a baseclass that you can use to implement new handlers.

Class Trees for Net_Server

  • Net_Server

Prev | Net_Server | Next
Example | PEAR Manual | Net_Server::create


Net_Server::create

Net_Server::create

Net_Server::create() – create a new server

Synopsis

require_once 'Server.php';

void& Net_Server::create ( string $type , string $host , integer $port )

Description

Currently two types of servers are supported:

  • 'sequential', creates a server where one process handles all request from all clients sequentially

  • 'fork', creates a server where a new process is forked for each client that connects to the server. This only works on *NIX

Parameter

string $type

type of the server

string $host

hostname

integer $port

port

Throws

throws no exceptions thrown

static

static

Note

This function can not be called statically.

Prev | Net_Server | Next
Class Summary Net_Server | PEAR Manual | Class Summary Net_Server_Driver


Class Summary Net_Server_Driver

Class Summary Net_Server_Driver

Class Summary Net_Server_Driver – Base class for all drivers

Base class for all drivers

This package is not documented yet.

Class Trees for Net_Server_Driver

  • PEAR

    • Net_Server_Driver

Classes that extend Net_Server_Driver
Class | Summary
Net_Server_Driver_Fork | Forking server class.
Net_Server_Driver_Sequential | Sequential server class.
Prev | Net_Server | Next
Net_Server::create | PEAR Manual | Net_Server_Driver::getLastSocketError


Net_Server_Driver::getLastSocketError

Net_Server_Driver::getLastSocketError

Net_Server_Driver::getLastSocketError() – return string for last socket error

Synopsis

require_once 'ServerDriver.php';

string Net_Server_Driver::getLastSocketError ( mixed &$fd )

Description

This package is not documented yet.

Parameter

mixed &$fd

Return value

returns last error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Class Summary Net_Server_Driver | PEAR Manual | Net_Server_Driver::setCallbackObject


Net_Server_Driver::setCallbackObject

Net_Server_Driver::setCallbackObject

Net_Server_Driver::setCallbackObject() – register a callback object, that is used to handle all events

Synopsis

require_once 'ServerDriver.php';

void Net_Server_Driver::setCallbackObject ( object &$object )

Description

This package is not documented yet.

Parameter

object &$object

callback object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver::getLastSocketError | PEAR Manual | Net_Server_Driver::setDebugMode


Net_Server_Driver::setDebugMode

Net_Server_Driver::setDebugMode

Net_Server_Driver::setDebugMode() – set debug mode

Synopsis

require_once 'ServerDriver.php';

void Net_Server_Driver::setDebugMode ( mixed $debug , string $dest = "stdout" )

Description

This package is not documented yet.

Parameter

mixed $debug

[text|htmlFALSE]

string $dest

destination of debug message (stdout to output or filename if log should be written)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver::setCallbackObject | PEAR Manual | Class Summary Net_Server_Driver_Fork


Class Summary Net_Server_Driver_Fork

Class Summary Net_Server_Driver_Fork

Class Summary Net_Server_Driver_Fork – Forking server class.

Forking server class.

This class will fork a new process for each connection. This allows you to build servers, where communication between the clients is no issue.

Events that can be handled:

  • onStart

  • onConnect

  • onClose

  • onReceiveData

Class Trees for Net_Server_Driver_Fork

  • PEAR

    • Net_Server_Driver

      • Net_Server_Driver_Fork

Net_Server_Driver_Fork Inherited Methods

Inherited from Net_Server_Driver
Method Name | Summary
Net_Server_Driver::getLastSocketError() | return string for last socket error
Net_Server_Driver::setCallbackObject() | register a callback object, that is used to handle all events
Net_Server_Driver::setDebugMode() | set debug mode
Prev | Net_Server | Next
Net_Server_Driver::setDebugMode | PEAR Manual | Net_Server_Driver_Fork::broadcastData


Net_Server_Driver_Fork::broadcastData

Net_Server_Driver_Fork::broadcastData

Net_Server_Driver_Fork::broadcastData() – send data to all clients

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::broadcastData ( string $data , array $exclude = array() )

Description

This package is not documented yet.

Parameter

string $data

data to send

array $exclude

client ids to exclude

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Class Summary Net_Server_Driver_Fork | PEAR Manual | Net_Server_Driver_Fork::closeConnection


Net_Server_Driver_Fork::closeConnection

Net_Server_Driver_Fork::closeConnection

Net_Server_Driver_Fork::closeConnection() – close the current connection

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::closeConnection ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::broadcastData | PEAR Manual | Net_Server_Driver_Fork::getClientInfo


Net_Server_Driver_Fork::getClientInfo

Net_Server_Driver_Fork::getClientInfo

Net_Server_Driver_Fork::getClientInfo() – get current information about a client

Synopsis

require_once 'ServerDriverFork.php';

array Net_Server_Driver_Fork::getClientInfo ( )

Description

This package is not documented yet.

Return value

returns information about the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::closeConnection | PEAR Manual | Net_Server_Driver_Fork::getClients


Net_Server_Driver_Fork::getClients

Net_Server_Driver_Fork::getClients

Net_Server_Driver_Fork::getClients() – get current amount of clients

Synopsis

require_once 'ServerDriverFork.php';

PEAR_Error Net_Server_Driver_Fork::getClients ( )

Description

not possible with forking

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::getClientInfo | PEAR Manual | Net_Server_Driver_Fork::isConnected


Net_Server_Driver_Fork::isConnected

Net_Server_Driver_Fork::isConnected

Net_Server_Driver_Fork::isConnected() – check, whether a client is still connected

Synopsis

require_once 'ServerDriverFork.php';

boolean Net_Server_Driver_Fork::isConnected ( integer $id )

Description

This package is not documented yet.

Parameter

integer $id

client id

Return value

returns true if client is connected, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::getClients | PEAR Manual | Net_Server_Driver_Fork::sendData


Net_Server_Driver_Fork::sendData

Net_Server_Driver_Fork::sendData

Net_Server_Driver_Fork::sendData() – send data to a client

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::sendData ( string $data , boolean $debugData = true )

Description

This package is not documented yet.

Parameter

string $data

data to send

boolean $debugData

flag to indicate whether data that is written to socket should also be sent as debug message

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::isConnected | PEAR Manual | Net_Server_Driver_Fork::serviceRequest


Net_Server_Driver_Fork::serviceRequest

Net_Server_Driver_Fork::serviceRequest

Net_Server_Driver_Fork::serviceRequest() – service the current request

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::serviceRequest ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::sendData | PEAR Manual | Net_Server_Driver_Fork::setMaxClients


Net_Server_Driver_Fork::setMaxClients

Net_Server_Driver_Fork::setMaxClients

Net_Server_Driver_Fork::setMaxClients() – set maximum amount of simultaneous connections

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::setMaxClients ( int $maxClients )

Description

this is not possible as each client gets its own process

Parameter

integer $maxClients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::serviceRequest | PEAR Manual | Net_Server_Driver_Fork::shutDown


Net_Server_Driver_Fork::shutDown

Net_Server_Driver_Fork::shutDown

Net_Server_Driver_Fork::shutDown() – shutdown server

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::shutDown ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::setMaxClients | PEAR Manual | Net_Server_Driver_Fork::start


Net_Server_Driver_Fork::start

Net_Server_Driver_Fork::start

Net_Server_Driver_Fork::start() – start the server

Synopsis

require_once 'ServerDriverFork.php';

void Net_Server_Driver_Fork::start ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Fork::shutDown | PEAR Manual | Class Summary Net_Server_Driver_Sequential


Class Summary Net_Server_Driver_Sequential

Class Summary Net_Server_Driver_Sequential

Class Summary Net_Server_Driver_Sequential – Sequential server class.

Sequential server class.

This class will handles all connections in one server process. This allows you to build servers, where communication between the clients is easy. The drawback is that clients are served sequentially (hence the name). If you send large blocks of data to a client, the others will have to wait. For servers where communication between clients is not needed, use Net_Server_Fork instead.

Events that can be handled:

  • onStart

  • onConnect

  • onConnectionRefused

  • onClose

  • onIdle

  • onReceiveData

  • onShutdown

Class Trees for Net_Server_Driver_Sequential

  • PEAR

    • Net_Server_Driver

      • Net_Server_Driver_Sequential

Net_Server_Driver_Sequential Inherited Methods

Inherited from Net_Server_Driver
Method Name | Summary
Net_Server_Driver::getLastSocketError() | return string for last socket error
Net_Server_Driver::setCallbackObject() | register a callback object, that is used to handle all events
Net_Server_Driver::setDebugMode() | set debug mode
Prev | Net_Server | Next
Net_Server_Driver_Fork::start | PEAR Manual | Net_Server_Driver_Sequential::acceptConnection


Net_Server_Driver_Sequential::acceptConnection

Net_Server_Driver_Sequential::acceptConnection

Net_Server_Driver_Sequential::acceptConnection() – accept a new connection

Synopsis

require_once 'ServerDriverSequential.php';

int Net_Server_Driver_Sequential::acceptConnection ( resource &$socket )

Description

This package is not documented yet.

Parameter

resource &$socket

socket that received the new connection

Return value

returns internal ID of the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Class Summary Net_Server_Driver_Sequential | PEAR Manual | Net_Server_Driver_Sequential::broadcastData


Net_Server_Driver_Sequential::broadcastData

Net_Server_Driver_Sequential::broadcastData

Net_Server_Driver_Sequential::broadcastData() – send data to all clients

Synopsis

require_once 'ServerDriverSequential.php';

void Net_Server_Driver_Sequential::broadcastData ( string $data , array $exclude = array() )

Description

This package is not documented yet.

Parameter

string $data

data to send

array $exclude

client ids to exclude

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::acceptConnection | PEAR Manual | Net_Server_Driver_Sequential::closeConnection


Net_Server_Driver_Sequential::closeConnection

Net_Server_Driver_Sequential::closeConnection

Net_Server_Driver_Sequential::closeConnection() – close connection to a client

Synopsis

require_once 'ServerDriverSequential.php';

void Net_Server_Driver_Sequential::closeConnection ( mixed $id = 0 , int $clientID )

Description

This package is not documented yet.

Parameter

mixed $id

integer $clientID

internal ID of the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::broadcastData | PEAR Manual | Net_Server_Driver_Sequential::getClientInfo


Net_Server_Driver_Sequential::getClientInfo

Net_Server_Driver_Sequential::getClientInfo

Net_Server_Driver_Sequential::getClientInfo() – get current information about a client

Synopsis

require_once 'ServerDriverSequential.php';

array Net_Server_Driver_Sequential::getClientInfo ( int $clientId )

Description

This package is not documented yet.

Parameter

integer $clientId

ID of the client

Return value

returns information about the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::closeConnection | PEAR Manual | Net_Server_Driver_Sequential::getClients


Net_Server_Driver_Sequential::getClients

Net_Server_Driver_Sequential::getClients

Net_Server_Driver_Sequential::getClients() – get current amount of clients

Synopsis

require_once 'ServerDriverSequential.php';

int Net_Server_Driver_Sequential::getClients ( )

Description

This package is not documented yet.

Return value

returns amount of clients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::getClientInfo | PEAR Manual | Net_Server_Driver_Sequential::isConnected


Net_Server_Driver_Sequential::isConnected

Net_Server_Driver_Sequential::isConnected

Net_Server_Driver_Sequential::isConnected() – check, whether a client is still connected

Synopsis

require_once 'ServerDriverSequential.php';

boolean Net_Server_Driver_Sequential::isConnected ( integer $id )

Description

This package is not documented yet.

Parameter

integer $id

client id

Return value

returns true if client is connected, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::getClients | PEAR Manual | Net_Server_Driver_Sequential::sendData


Net_Server_Driver_Sequential::sendData

Net_Server_Driver_Sequential::sendData

Net_Server_Driver_Sequential::sendData() – send data to a client

Synopsis

require_once 'ServerDriverSequential.php';

void Net_Server_Driver_Sequential::sendData ( int $clientId , string $data , boolean $debugData = true )

Description

This package is not documented yet.

Parameter

integer $clientId

ID of the client

string $data

data to send

boolean $debugData

flag to indicate whether data that is written to socket should also be sent as debug message

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::isConnected | PEAR Manual | Net_Server_Driver_Sequential::setMaxClients


Net_Server_Driver_Sequential::setMaxClients

Net_Server_Driver_Sequential::setMaxClients

Net_Server_Driver_Sequential::setMaxClients() – set maximum amount of simultaneous connections

Synopsis

require_once 'ServerDriverSequential.php';

void Net_Server_Driver_Sequential::setMaxClients ( int $maxClients )

Description

This package is not documented yet.

Parameter

integer $maxClients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::sendData | PEAR Manual | Net_Server_Driver_Sequential::shutDown


Net_Server_Driver_Sequential::shutDown

Net_Server_Driver_Sequential::shutDown

Net_Server_Driver_Sequential::shutDown() – shutdown server

Synopsis

require_once 'ServerDriverSequential.php';

void Net_Server_Driver_Sequential::shutDown ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::setMaxClients | PEAR Manual | Net_Server_Driver_Sequential::start


Net_Server_Driver_Sequential::start

Net_Server_Driver_Sequential::start

Net_Server_Driver_Sequential::start() – start the server

Synopsis

require_once 'ServerDriverSequential.php';

void Net_Server_Driver_Sequential::start ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Driver_Sequential::shutDown | PEAR Manual | Class Summary Net_Server_Handler


Class Summary Net_Server_Handler

Class Summary Net_Server_Handler

Class Summary Net_Server_Handler – Base class for all handlers

Base class for all handlers

This package is not documented yet.

Class Trees for Net_Server_Handler

  • Net_Server_Handler

Prev | Net_Server | Next
Net_Server_Driver_Sequential::start | PEAR Manual | Net_Server_Handler::onClose


Net_Server_Handler::onClose

Net_Server_Handler::onClose

Net_Server_Handler::onClose() – onClose handler

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::onClose ( integer $clientId = 0 )

Description

This handler is called, when a client disconnects from the server Available in:

  • Net_Server_Sequential

  • Net_Server_Fork

Parameter

integer $clientId

unique id of the client, in Net_Server_Fork, this is always 0

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Class Summary Net_Server_Handler | PEAR Manual | Net_Server_Handler::onConnect


Net_Server_Handler::onConnect

Net_Server_Handler::onConnect

Net_Server_Handler::onConnect() – onConnect handler

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::onConnect ( integer $clientId = 0 )

Description

This handler is called, when a new client connects Available in:

  • Net_Server_Sequential

  • Net_Server_Fork

Parameter

integer $clientId

unique id of the client, in Net_Server_Fork, this is always 0

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onClose | PEAR Manual | Net_Server_Handler::onConnectionRefused


Net_Server_Handler::onConnectionRefused

Net_Server_Handler::onConnectionRefused

Net_Server_Handler::onConnectionRefused() – onConnectionRefused handler

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::onConnectionRefused ( integer $clientId = 0 )

Description

This handler is called, when a new client tries to connect but is not allowed to Available in:

  • Net_Server_Sequential

Parameter

integer $clientId

unique id of the client

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onConnect | PEAR Manual | Net_Server_Handler::onIdle


Net_Server_Handler::onIdle

Net_Server_Handler::onIdle

Net_Server_Handler::onIdle() – onIdle handler

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::onIdle ( )

Description

This handler is called whenever the server is idle (has nothing to do), and that for a given number of seconds (timeout). Currently, only the sequential driver supports this handler.

The timeout can be specified by passing the desired number of seconds to setIdleTimeout(). By default, the timeout is set to NULL, which means that the handler is deactivated.

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onConnectionRefused | PEAR Manual | Net_Server_Handler::onReceiveData


Net_Server_Handler::onReceiveData

Net_Server_Handler::onReceiveData

Net_Server_Handler::onReceiveData() – onReceiveData handler

Synopsis

require_once 'ServerHandler.php';

 void      Net_Server_Handler::onReceiveData (
 integer  $clientId = 0
  , string  $data = ""
)

Description

This handler is called, when a client sends data to the server Available in:

  • Net_Server_Sequential

  • Net_Server_Fork

Parameter

integer $clientId

unique id of the client, in Net_Server_Fork, this is always 0

string $data

data that the client sent

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onIdle | PEAR Manual | Net_Server_Handler::onShutdown


Net_Server_Handler::onShutdown

Net_Server_Handler::onShutdown

Net_Server_Handler::onShutdown() – onShutdown handler

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::onShutdown ( )

Description

This handler is called, when the server is stopped. Available in:

  • Net_Server_Sequential

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onReceiveData | PEAR Manual | Net_Server_Handler::onStart


Net_Server_Handler::onStart

Net_Server_Handler::onStart

Net_Server_Handler::onStart() – onStart handler

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::onStart ( )

Description

This handler is called, when the server starts. Available in:

  • Net_Server_Sequential

  • Net_Server_Fork

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onShutdown | PEAR Manual | Net_Server_Handler::setServerReference


Net_Server_Handler::setServerReference

Net_Server_Handler::setServerReference

Net_Server_Handler::setServerReference() – set a reference to the server object

Synopsis

require_once 'ServerHandler.php';

void Net_Server_Handler::setServerReference ( object Net_Server_* &$server )

Description

This is done automatically when the handler is passed over to the server

Parameter

object Net_Server_*; &$server

object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Server | Next
Net_Server_Handler::onStart | PEAR Manual | Package Net_Server Constants


Package Net_Server Constants

Package Net_Server Constants

Package Net_Server Constants – Constants defined in and used by Net_Server

All Constants

Constants defined in Server.php

Constants defined in Server.php
Name | Value | Line Number
NET_SERVER_ERROR_DRIVER_CORRUPT | 52 | 39
NET_SERVER_ERROR_NOT_SUPPORTED | 53 | 44
NET_SERVER_ERROR_PCNTL_REQUIRED | 54 | 49
NET_SERVER_ERROR_UNKNOWN_DRIVER | 51 | 34
Prev | Net_Server | Next
Net_Server_Handler::setServerReference | PEAR Manual | Net_SmartIrc


Net_SmartIrc

Net_SmartIrc

Net_SmartIRC is a PHP class for communication with IRC networks, which conforms to the RFC 2812 (IRC protocol). It's an API that handles all IRC protocol messages. This class is designed for creating IRC bots, chats and show irc related info on webpages.

Table of Contents
  • Introduction -- Net_SmartIRC is a PHP class for communication with IRC networks, which conforms to the RFC 2812 (IRC protocol).
Prev | Networking | Next
Package Net_Server Constants | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Net_SmartIRC is a PHP class for communication with IRC networks, which conforms to the RFC 2812 (IRC protocol).

Net_SmartIRC Description

Net_SmartIRC is a PHP class for communication with IRC networks, which conforms to the RFC 2812 (IRC protocol). It's an API that handles all IRC protocol messages. This class is designed for creating IRC bots, chats and show irc related info on webpages.

The full online documentation is available here

Prev | Net_SmartIrc | Next
Net_SmartIrc | PEAR Manual | Net_SMTP


Net_SMTP

Net_SMTP

Table of Contents
  • Class Summary Net_SMTP -- Provides an implementation of the SMTP protocol using PEAR's Net_Socket:: class.
  • Introduction and Guide -- Provides an implementation of the SMTP protocol
  • constructor Net_SMTP::Net_SMTP -- Instantiates a new Net_SMTP object, overriding any networkings with parameters that are passed in.
  • Net_SMTP::auth -- Attempt to do SMTP authentication.
  • Net_SMTP::connect -- Attempt to connect to the SMTP server.
  • Net_SMTP::data -- Send the DATA command to start message body
  • Net_SMTP::disconnect -- Attempt to disconnect from the SMTP server.
  • Net_SMTP::getResponse -- Return a 2-tuple containing the last response from the SMTP server.
  • Net_SMTP::helo -- Send the HELO command.
  • Net_SMTP::identifySender -- Backwards-compatibility method.identifySender()'s functionality is now handled internally.
  • Net_SMTP::mailFrom -- Send the MAIL FROM: command.
  • Net_SMTP::noop -- Send the NOOP command.
  • Net_SMTP::quotedata -- Quote the data so that it meets SMTP standards.
  • Net_SMTP::rcptTo -- Send the RCPT TO: command.
  • Net_SMTP::rset -- Send the RSET command.
  • Net_SMTP::saml_from -- Send the SAML FROM: command.
  • Net_SMTP::send_from -- Send the SEND FROM: command.
  • Net_SMTP::setDebug -- Set the value of the debugging flag.
  • Net_SMTP::soml_from -- Send the SOML FROM: command.
  • Net_SMTP::vrfy -- Send the VRFY command.
Prev | Networking | Next
Introduction | PEAR Manual | Class Summary Net_SMTP


Class Summary Net_SMTP

Class Summary Net_SMTP

Class Summary Net_SMTP – Provides an implementation of the SMTP protocol using PEAR's Net_Socket:: class.

Provides an implementation of the SMTP protocol using PEAR's Net_Socket:: class.

This package implements the Simple Mail Transfer Protocol (SMTP), Internet's standard host-to-host mail transport protocol, using the Net_Socket:: class for the server connection. The SMTP provides mechanisms for the transmission of mail.

Class Trees for Net_SMTP

  • Net_SMTP

Prev | Net_SMTP | Next
Net_SMTP | PEAR Manual | Introduction and Guide


Introduction and Guide

Introduction and Guide

Introduction and Guide – Provides an implementation of the SMTP protocol

Net_SMTP Introduction and Guide

The Net_SMTP package supports the SMTP authentication standard (as defined by RFC-2554). Net_SMTP supports several authentication methods like DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN.

Dependencies

The PEAR_Error Class

The Net_SMTP package uses the PEAR_Error class for all of its error handling.

The Net_Socket Package

The Net_Socket package is used as the basis for all network communications.

The Auth_SASL Package

The Auth_SASL package is an optional dependency. If it is available, the Net_SMTP package will be able to support the DIGEST-MD5 and CRAM-MD5 SMTP authentication methods. Otherwise, only the LOGIN and PLAIN methods will be available.

Error Handling

All of the Net_SMTP class's public methods return a PEAR_Error object if an error occurs. The standard way to check for a PEAR_Error object is by using PEAR::isError()

SMTP Authentication

The Net_SMTP package supports the SMTP authentication standard (as defined by RFC-2554). The Net_SMTP package supports the following authentication methods, in order of preference:

DIGEST-MD5

The DIGEST-MD5 authentication method uses RSA Data Security Inc.'s MD5 Message Digest algorithm. It is considered the most secure method of SMTP authentication.

Note: The DIGEST-MD5 authentication method is only supported if the AUTH_SASL package is available.

CRAM-MD5

The CRAM-MD5 authentication method has been superseded by the DIGEST-MD5 method in terms of security. It is provided here for compatibility with older SMTP servers that may not support the newer DIGEST-MD5 algorithm.

Note: The CRAM-MD5 authentication method is only supported if the AUTH_SASL package is available.

LOGIN

The LOGIN authentication method encrypts the user's password using the Base64 encoding scheme. Because decrypting a Base64-encoded string is trivial, LOGIN is not considered a secure authentication method and should be avoided.

PLAIN

The PLAIN authentication method sends the user's password in plain text. This method of authentication is not secure and should be avoided.

Secure Connections

If secure socket transports have been enabled in PHP, it is possible to establish a secure connection to the remote SMTP server:

<?php
$smtp = new Net_SMTP('ssl://mail.example.com', 465);
?>

This example connects to mail.example.com on port 465 (a common SMTPS port) using the ssl:// transport.

Data Quoting

By default, all outbound string data is quoted in accordance with SMTP standards. This means that all native Unix (\n) and Mac (\r) line endings are converted to Internet-standard CRLF (\r\n) line endings. Also, because the SMTP protocol uses a single leading period (.) to signal an end to the message data, single leading periods in the original data string are "doubled" (e.g. "..").

These string transformation can be expensive when large blocks of data are involved. For example, the Net_SMTP package is not aware of MIME parts (it just sees the MIME message as one big string of characters), so it is not able to skip non-text attachments when searching for characters that may need to be quoted.

Because of this, it is possible to extend the Net_SMTP class in order to implement your own custom quoting routine. Just create a new class based on the Net_SMTP class and reimplement the quotedata() method:

<?php
require 'Net/SMTP.php';

class Net_SMTP_custom extends Net_SMTP
{
    function quotedata($data)
    {
        /* Perform custom data quoting */
    }
}
?>

Note that the $data parameter will be passed to the quotedata() function by reference. This means that you can operate directly on $data. It also the overhead of copying a large $data string to and from the quotedata() method.

Debugging

The Net_SMTP package contains built-in debugging output routines (disabled by default). Debugging output must be explicitly enabled via the setDebug() method:

<?php
$smtp->setDebug(true);
?>

The debugging messages will be sent to the standard output stream.

Examples

The following script demonstrates how a simple email message can be sent using the Net_SMTP package:

<?php
require 'Net/SMTP.php';

$host = 'mail.example.com';
$from = 'user@example.com';
$rcpt = array('recipient1@example.com', 'recipient2@example.com');
$subj = "Subject: Test Message\n";
$body = "Body Line 1\nBody Line 2";

/* Create a new Net_SMTP object. */
if (! ($smtp = new Net_SMTP($host))) {
    die("Unable to instantiate Net_SMTP object\n");
}

/* Connect to the SMTP server. */
if (PEAR::isError($e = $smtp->connect())) {
    die($e->getMessage() . "\n");
}

/* Send the 'MAIL FROM:' SMTP command. */
if (PEAR::isError($smtp->mailFrom($from))) {
    die("Unable to set sender to <$from>\n");
}

/* Address the message to each of the recipients. */
foreach ($rcpt as $to) {
    if (PEAR::isError($res = $smtp->rcptTo($to))) {
        die("Unable to add recipient <$to>: " . $res->getMessage() . "\n");
    }
}

/* Set the body of the message. */
if (PEAR::isError($smtp->data($subj . "\r\n" . $body))) {
    die("Unable to send data\n");
}

/* Disconnect from the SMTP server. */
$smtp->disconnect();
?>
Prev | Net_SMTP | Next
Class Summary Net_SMTP | PEAR Manual | constructor Net_SMTP::Net_SMTP


constructor Net_SMTP::Net_SMTP

constructor Net_SMTP::Net_SMTP

constructor Net_SMTP::Net_SMTP() – Instantiates a new Net_SMTP object, overriding any networkings with parameters that are passed in.

Synopsis

require_once 'NET/SMTP.php';

void constructor Net_SMTP::Net_SMTP ( string $host = null , int $port = null , string $localhost = null )

Description

Constructor,Instantiates a new Net_SMTP object.

Parameter

string $host

The server to connect to.

integer $port

The port to connect to.

string $localhost

The value to give when sending EHLO or HELO.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Introduction and Guide | PEAR Manual | Net_SMTP::auth


Net_SMTP::auth

Net_SMTP::auth

Net_SMTP::auth() – Attempt to do SMTP authentication.

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::auth ( string $uid , string $pwd , string $method = '' )

Description

This function initializes an authentication session using the supported methods. These are, in order of preference: Digest-MD5,CRAMMD5,LOGIN, and PLAIN.

Parameter

string $uid

The userid to authenticate as.

string $pwd

The password to authenticate with.

string $method

The requested authentication method.If none is specified, the best supported method will be used.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
constructor Net_SMTP::Net_SMTP | PEAR Manual | Net_SMTP::connect


Net_SMTP::connect

Net_SMTP::connect

Net_SMTP::connect() – Attempt to connect to the SMTP server.

Synopsis

require_once 'NET/SMTP.php';

mixed Net_SMTP::connect ( int $timeout = null )

Description

Attempt to establish a connection with the SMTP server

Parameter

integer $timeout

The timeout value (in seconds) for thesocket connection.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::auth | PEAR Manual | Net_SMTP::data


Net_SMTP::data

Net_SMTP::data

Net_SMTP::data() – Send the DATA command to start message body

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::data ( string $data )

Description

This function sends the message body with the DATA command and terminates the message session.

Parameter

string $data

The message body to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::connect | PEAR Manual | Net_SMTP::disconnect


Net_SMTP::disconnect

Net_SMTP::disconnect

Net_SMTP::disconnect() – Attempt to disconnect from the SMTP server.

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::disconnect ( )

Description

Attempt to close the connection with the SMTP server.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::data | PEAR Manual | Net_SMTP::getResponse


Net_SMTP::getResponse

Net_SMTP::getResponse

Net_SMTP::getResponse() – Return a 2-tuple containing the last response from the SMTP server.

Synopsis

require_once 'NET/SMTP.php';

array Net_SMTP::getResponse ( )

Description

Return a two-element array containing the last response from the SMPT server.

Return value

returns A two-element array: the first element contains the response code as an integer and the second element contains the response's arguments as a string.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::disconnect | PEAR Manual | Net_SMTP::helo


Net_SMTP::helo

Net_SMTP::helo

Net_SMTP::helo() – Send the HELO command.

Synopsis

require_once 'NET/SMTP.php';

mixed Net_SMTP::helo ( string $domain )

Description

Send the HELO command which is the first part of a mail-sending SMTP transaction where the Internet extender first tries to send mail.

Parameter

string $domain

The domain name to say we are.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::getResponse | PEAR Manual | Net_SMTP::identifySender


Net_SMTP::identifySender

Net_SMTP::identifySender

Net_SMTP::identifySender() – Backwards-compatibility method.identifySender()'s functionality is now handled internally.

Synopsis

require_once 'NET/SMTP.php';

booleanNet_SMTP::identifySender ( )

Description

Backwards-compatibility method.identifySender()'s functionality is now handled internally.

Return value

returns This method always return true.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::helo | PEAR Manual | Net_SMTP::mailFrom


Net_SMTP::mailFrom

Net_SMTP::mailFrom

Net_SMTP::mailFrom() – Send the MAIL FROM: command.

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::mailFrom ( string $sender )

Description

Send the MAIL FROM: command

Parameter

string $sender

The sender (reverse path) to set.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::identifySender | PEAR Manual | Net_SMTP::noop


Net_SMTP::noop

Net_SMTP::noop

Net_SMTP::noop() – Send the NOOP command.

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::noop ( )

Description

Send the NOOP command.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::mailFrom | PEAR Manual | Net_SMTP::quotedata


Net_SMTP::quotedata

Net_SMTP::quotedata

Net_SMTP::quotedata() – Quote the data so that it meets SMTP standards.

Synopsis

require_once 'NET/SMTP.php';

void Net_SMTP::quotedata ( string &$data )

Description

This is provided as a separate public function to facilitate easier overloading for the cases where it is desirable to customize the quoting behavior.

Parameter

string &$data

The message text to quote. The string must be passed by reference, and the text will be modified in place.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::noop | PEAR Manual | Net_SMTP::rcptTo


Net_SMTP::rcptTo

Net_SMTP::rcptTo

Net_SMTP::rcptTo() – Send the RCPT TO: command.

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::rcptTo ( string $recipient )

Description

sends the RCPT TO SMTP protocol command

Parameter

string $recipient

The recipient (forward path) to add.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::quotedata | PEAR Manual | Net_SMTP::rset


Net_SMTP::rset

Net_SMTP::rset

Net_SMTP::rset() – Send the RSET command.

Synopsis

require_once 'NET/SMTP.php';

mixed Net_SMTP::rset ( )

Description

Sends the RSET SMTP protocol command.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::rcptTo | PEAR Manual | Net_SMTP::saml_from


Net_SMTP::saml_from

Net_SMTP::saml_from

Net_SMTP::saml_from() – Send the SAML FROM: command.

Synopsis

require_once 'NET/SMTP.php';

mixedNet_SMTP::saml_from ( string $path )

Description

Sends the SAML FROM SMTP protocol command.

Parameter

string $path

The reverse path to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::rset | PEAR Manual | Net_SMTP::send_from


Net_SMTP::send_from

Net_SMTP::send_from

Net_SMTP::send_from() – Send the SEND FROM: command.

Synopsis

require_once 'NET/SMTP.php';

mixed Net_SMTP::send_from ( string $path )

Description

Sends the SEND FROM SMTP protocol command.

Parameter

string $path

The reverse path to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::saml_from | PEAR Manual | Net_SMTP::setDebug


Net_SMTP::setDebug

Net_SMTP::setDebug

Net_SMTP::setDebug() – Set the value of the debugging flag.

Synopsis

require_once 'NET/SMTP.php';

voidNet_SMTP::setDebug ( boolean $debug )

Description

Set the value of the debugging flag.

Parameter

boolean $debug

New value for the debugging flag.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::send_from | PEAR Manual | Net_SMTP::soml_from


Net_SMTP::soml_from

Net_SMTP::soml_from

Net_SMTP::soml_from() – Send the SOML FROM: command.

Synopsis

require_once 'NET/SMTP.php';

mixed Net_SMTP::soml_from ( string $path )

Description

Sends the SOML FROM: SMTP protocol command.

Parameter

string $path

The reverse path to send.

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::setDebug | PEAR Manual | Net_SMTP::vrfy


Net_SMTP::vrfy

Net_SMTP::vrfy

Net_SMTP::vrfy() – Send the VRFY command.

Synopsis

require_once 'NET/SMTP.php';

mixed Net_SMTP::vrfy ( string $string )

Description

Sends the VRFY SMTP protocol command.

Parameter

string $string

The string to verify

Return value

returns Returns a PEAR_Error with an error message on any kind of failure, or true on success.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_SMTP | Next
Net_SMTP::soml_from | PEAR Manual | Net_Socket


Net_Socket

Net_Socket

Net_Socket provides a generic API for communication over TCP/IP-sockets.

Table of Contents
  • Net_Socket::connect() -- connects to a server
  • Net_Socket::disconnect() -- disconnects from a server
  • Net_Socket::eof() -- test for end-of-file
  • Net_Socket::gets() -- retrieve a string
  • Net_Socket::getStatus() -- retrieve information about a connection
  • Net_Socket::isBlocking() -- check for blocking mode
  • Net_Socket::read() -- retrieve data
  • Net_Socket::readAll() -- retrieve data until connection closes
  • Net_Socket::readByte() -- read a byte
  • Net_Socket::readInt() -- read an integer
  • Net_Socket::readIPAddress() -- read an IP-address
  • Net_Socket::readLine() -- retrieve data until line end
  • Net_Socket::readString() -- read a string
  • Net_Socket::readWord() -- read a word
  • Net_Socket::setBlocking() -- sets blocking mode
  • Net_Socket::setTimeout() -- sets timeout
  • Net_Socket::write() -- write data
  • Net_Socket::writeLine() -- write data including EOL
  • Example -- using Net_Socket
Prev | Networking | Next
Net_SMTP::vrfy | PEAR Manual | Net_Socket::connect()


Net_Socket::connect()

Net_Socket::connect()

Net_Socket::connect() – connects to a server

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::connect ( string $addr , integer $port , boolean $persistent = null , integer $timeout = null , array $options = null )

Description

Connect to the specified port. If called when the socket is already connected, it disconnects and connects again.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
every every The connection could not be established because

  • wrong server name or adress

  • the host itself is not link to a network

  • a firewall does not allow an access

 Check for server name, the connection to the net and possible firewalls on client or server side

Note

This function can not be called statically.

See

Net_Socket::disconnect()

Prev | Net_Socket | Next
Net_Socket | PEAR Manual | Net_Socket::disconnect()


Net_Socket::disconnect()

Net_Socket::disconnect()

Net_Socket::disconnect() – disconnects from a server

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::disconnect ( )

Description

Disconnects froms server, closes the socket.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | The connection to close was not open or is already closed. | Ensure a successfull call of connect()

Note

This function can not be called statically.

See

Net_Socket::connect()

Prev | Net_Socket | Next
Net_Socket::connect() | PEAR Manual | Net_Socket::eof()


Net_Socket::eof()

Net_Socket::eof()

Net_Socket::eof() – test for end-of-file

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::eof ( )

Description

Test for the end of data transmission.

Return value

boolean - TRUE, if no more data avaible or connection is closed

Note

This function can not be called statically.

Prev | Net_Socket | Next
Net_Socket::disconnect() | PEAR Manual | Net_Socket::gets()


Net_Socket::gets()

Net_Socket::gets()

Net_Socket::gets() – retrieve a string

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::gets ( integer $size )

Description

Returns a string containing data from the socket connection

Parameter

  • integer $size - maximum number of chars to recieve

Return value

string - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read()

Prev | Net_Socket | Next
Net_Socket::eof() | PEAR Manual | Net_Socket::getStatus()


Net_Socket::getStatus()

Net_Socket::getStatus()

Net_Socket::getStatus() – retrieve information about a connection

Synopsis

require_once 'Net/Socket.php';

array Net_Socket::getStatus ( )

Description

Returns information about an existing socket resource.

Return value

array - the data as array or a PEAR_Error

The content of the array is:

  • boolean 'timed_out' - the socket timed out waiting for data

  • boolean 'blocked' - blocking mode

  • boolean 'eof' - indicates EOF event

  • integer 'unread_bytes' - number of bytes left in the socket buffer

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

Prev | Net_Socket | Next
Net_Socket::gets() | PEAR Manual | Net_Socket::isBlocking()


Net_Socket::isBlocking()

Net_Socket::isBlocking()

Net_Socket::isBlocking() – check for blocking mode

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::isBlocking ( )

Description

Find out if the socket is in blocking mode.

Return value

boolean - if TRUE, the connection is in blocking mode

Note

This function can not be called statically.

See

Net_Socket::setBlocking()

Prev | Net_Socket | Next
Net_Socket::getStatus() | PEAR Manual | Net_Socket::read()


Net_Socket::read()

Net_Socket::read()

Net_Socket::read() – retrieve data

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::read ( integer $size )

Description

Read a specified amount of data. This is guaranteed to return, and has the added benefit of getting everything in one fread() chunk; if you know the size of the data you're getting beforehand, this is definitely the way to go.

Parameter

  • integer $size - maximum number of chars to recieve

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read()

Prev | Net_Socket | Next
Net_Socket::isBlocking() | PEAR Manual | Net_Socket::readAll()


Net_Socket::readAll()

Net_Socket::readAll()

Net_Socket::readAll() – retrieve data until connection closes

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::readAll ( )

Description

Read until the socket closes.

This function will not exit, if the socket is in blocking mode until the socket closes.

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read()

Prev | Net_Socket | Next
Net_Socket::read() | PEAR Manual | Net_Socket::readByte()


Net_Socket::readByte()

Net_Socket::readByte()

Net_Socket::readByte() – read a byte

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::readByte ( )

Description

Read a byte from the socket

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read() , Net_Socket::readWord() , Net_Socket::readInt() , Net_Socket::readString() , Net_Socket::readIPAddress()

Prev | Net_Socket | Next
Net_Socket::readAll() | PEAR Manual | Net_Socket::readInt()


Net_Socket::readInt()

Net_Socket::readInt()

Net_Socket::readInt() – read an integer

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::readInt ( )

Description

Read an integer from the socket.

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read() , Net_Socket::readByte() , Net_Socket::readWord() , Net_Socket::readString() , Net_Socket::readIPAddress()

Prev | Net_Socket | Next
Net_Socket::readByte() | PEAR Manual | Net_Socket::readIPAddress()


Net_Socket::readIPAddress()

Net_Socket::readIPAddress()

Net_Socket::readIPAddress() – read an IP-address

Synopsis

require_once 'Net/Socket.php';

string Net_Socket::readIPAddress ( )

Description

Reads a IP from the socket. The function expects an integer which will converted to a IP address. This function only works with IPv4 addresses.

Return value

string - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read() , Net_Socket::readByte() , Net_Socket::readWord() , Net_Socket::readInt() , Net_Socket::readString()

Prev | Net_Socket | Next
Net_Socket::readInt() | PEAR Manual | Net_Socket::readLine()


Net_Socket::readLine()

Net_Socket::readLine()

Net_Socket::readLine() – retrieve data until line end

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::readLine ( )

Description

Read until either the end of the socket or a newline, whichever comes first. Strips the trailing newline from the returned data.

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read()

Prev | Net_Socket | Next
Net_Socket::readIPAddress() | PEAR Manual | Net_Socket::readString()


Net_Socket::readString()

Net_Socket::readString()

Net_Socket::readString() – read a string

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::readString ( )

Description

Read a zeroterminated string ("\x00") from the socket.

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::read() , Net_Socket::readByte() , Net_Socket::readWord() , Net_Socket::readInt() , Net_Socket::readIPAddress()

Prev | Net_Socket | Next
Net_Socket::readLine() | PEAR Manual | Net_Socket::readWord()


Net_Socket::readWord()

Net_Socket::readWord()

Net_Socket::readWord() – read a word

Synopsis

require_once 'Net/Socket.php';

mixed Net_Socket::readWord ( )

Description

Read a word from the socket.

Return value

mixed - the data or a PEAR_Error

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

Note: "Word" means not a word in literary sense. A word is a statement of size for data.

See

Net_Socket::read() , Net_Socket::readByte() , Net_Socket::readInt() , Net_Socket::readString() , Net_Socket::readIPAddress()

Prev | Net_Socket | Next
Net_Socket::readString() | PEAR Manual | Net_Socket::setBlocking()


Net_Socket::setBlocking()

Net_Socket::setBlocking()

Net_Socket::setBlocking() – sets blocking mode

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::setBlocking ( boolean $mode )

Description

Sets whether the socket connection should be blocking or not. A read call to a non-blocking socket will return immediately if there is no data available, whereas it will block until there is data for blocking sockets.

Parameter

  • boolean $mode - TRUE for blocking sockets, FALSE for non blocking

Return value

  • boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::isBlocking()

Prev | Net_Socket | Next
Net_Socket::readWord() | PEAR Manual | Net_Socket::setTimeout()


Net_Socket::setTimeout()

Net_Socket::setTimeout()

Net_Socket::setTimeout() – sets timeout

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::setTimeout ( integer $seconds , integer $microseconds )

Description

Sets the timeout value on socket descriptor, expressed in the sum of seconds and microseconds.

Parameter

  • integer $seconds - seconds part

  • integer $microseconds - microseconds part

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

Prev | Net_Socket | Next
Net_Socket::setBlocking() | PEAR Manual | Net_Socket::write()


Net_Socket::write()

Net_Socket::write()

Net_Socket::write() – write data

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::write ( string $data )

Description

Write data to a socket connection

Parameter

  • string $data - the data to write

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::writeLine()

Prev | Net_Socket | Next
Net_Socket::setTimeout() | PEAR Manual | Net_Socket::writeLine()


Net_Socket::writeLine()

Net_Socket::writeLine()

Net_Socket::writeLine() – write data including EOL

Synopsis

require_once 'Net/Socket.php';

boolean Net_Socket::writeLine ( string $data )

Description

Write a line of data to a socket connection, followed by a trailing "\r\n".

Parameter

  • string $data - the data to write

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
NULL | "not connected" | There is no open connection. | You must establish a connection before ( Net_Socket::connect()).

Note

This function can not be called statically.

See

Net_Socket::write()

Prev | Net_Socket | Next
Net_Socket::write() | PEAR Manual | Example


Example

Example

Example – using Net_Socket

Example

Sending and recieving data

<?php
$socket = new Net_Socket() ;

// open connection
$socket->connect("http://www.example.com", 80, true, 30);

// Send data including linebreak
$socket->writeLine("String with data");

// receive data until linebreak
$result = $socket->readLine();

// receive a number of data
$result = $socket->read(512);

// close connection
$socket->disconnect();
?>
Prev | Net_Socket | Next
Net_Socket::writeLine() | PEAR Manual | Net_Traceroute


Net_Traceroute

Net_Traceroute

Table of Contents
  • Class Summary Net_Traceroute -- Wrapper class for traceroute calls
  • Net_Traceroute::factory -- Factory for Net_Traceroute
  • Net_Traceroute::setArgs -- Set the arguments array
  • Net_Traceroute::traceroute -- Execute traceroute
  • Class Summary Net_Traceroute_Result -- Container class for Net_Traceroute results
  • Net_Traceroute_Result::factory -- Factory for Net_Traceroute_Result
  • Net_Traceroute_Result::getHops -- Returns hops from parsed result
  • Net_Traceroute_Result::getRawData -- Returns raw data that was returned by traceroute
  • Net_Traceroute_Result::getSystemName -- Returns sysname that was "guessed" (OS on which class is running)
  • Net_Traceroute_Result::getTargetIp -- Returns the target IP from parsed result
  • Net_Traceroute_Result::getTTL -- Returns TTL from parsed result
  • Net_Traceroute_Result::getValue -- Returns a Traceroute_Result property
  • Package Net_Traceroute Constants -- Constants defined in and used by Net_Traceroute
Prev | Networking | Next
Example | PEAR Manual | Class Summary Net_Traceroute


Class Summary Net_Traceroute

Class Summary Net_Traceroute

Class Summary Net_Traceroute – Wrapper class for traceroute calls

Wrapper class for traceroute calls

This package is not documented yet.

Class Trees for Net_Traceroute

  • Net_Traceroute

Prev | Net_Traceroute | Next
Net_Traceroute | PEAR Manual | Net_Traceroute::factory


Net_Traceroute::factory

Net_Traceroute::factory

Net_Traceroute::factory() – Factory for Net_Traceroute

Synopsis

require_once '/Traceroute.php';

object Net_Traceroute Net_Traceroute::factory ( )

Description

Call this method to create a new instance of Net_Traceroute

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Class Summary Net_Traceroute | PEAR Manual | Net_Traceroute::setArgs


Net_Traceroute::setArgs

Net_Traceroute::setArgs

Net_Traceroute::setArgs() – Set the arguments array

Synopsis

require_once '/Traceroute.php';

mixed Net_Traceroute::setArgs ( array $args )

Description

This package is not documented yet.

Parameter

array $args

Hash with options

Return value

returns true or PEAR_error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute::factory | PEAR Manual | Net_Traceroute::traceroute


Net_Traceroute::traceroute

Net_Traceroute::traceroute

Net_Traceroute::traceroute() – Execute traceroute

Synopsis

require_once '/Traceroute.php';

object Net_Traceroute_Result Net_Traceroute::traceroute ( string $host )

Description

This package is not documented yet.

Parameter

string $host

hostname or IP of destination

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute::setArgs | PEAR Manual | Class Summary Net_Traceroute_Result


Class Summary Net_Traceroute_Result

Class Summary Net_Traceroute_Result

Class Summary Net_Traceroute_Result – Container class for Net_Traceroute results

Container class for Net_Traceroute results

This package is not documented yet.

Class Trees for Net_Traceroute_Result

  • Net_Traceroute_Result

Prev | Net_Traceroute | Next
Net_Traceroute::traceroute | PEAR Manual | Net_Traceroute_Result::factory


Net_Traceroute_Result::factory

Net_Traceroute_Result::factory

Net_Traceroute_Result::factory() – Factory for Net_Traceroute_Result

Synopsis

require_once '/Traceroute.php';

void Net_Traceroute_Result::factory ( array $result , string $sysname )

Description

This package is not documented yet.

Parameter

array $result

Net_Traceroute result

string $sysname

OS_Guess::sysname

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Class Summary Net_Traceroute_Result | PEAR Manual | Net_Traceroute_Result::getHops


Net_Traceroute_Result::getHops

Net_Traceroute_Result::getHops

Net_Traceroute_Result::getHops() – Returns hops from parsed result

Synopsis

require_once '/Traceroute.php';

array Net_Traceroute_Result::getHops ( )

Description

This package is not documented yet.

Return value

returns Hops

Throws

throws no exceptions thrown

See

see _hops

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute_Result::factory | PEAR Manual | Net_Traceroute_Result::getRawData


Net_Traceroute_Result::getRawData

Net_Traceroute_Result::getRawData

Net_Traceroute_Result::getRawData() – Returns raw data that was returned by traceroute

Synopsis

require_once '/Traceroute.php';

array Net_Traceroute_Result::getRawData ( )

Description

This package is not documented yet.

Return value

returns raw data

Throws

throws no exceptions thrown

See

see _raw_data

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute_Result::getHops | PEAR Manual | Net_Traceroute_Result::getSystemName


Net_Traceroute_Result::getSystemName

Net_Traceroute_Result::getSystemName

Net_Traceroute_Result::getSystemName() – Returns sysname that was "guessed" (OS on which class is running)

Synopsis

require_once '/Traceroute.php';

string Net_Traceroute_Result::getSystemName ( )

Description

This package is not documented yet.

Return value

returns OS_Guess::sysname

Throws

throws no exceptions thrown

See

see _sysname

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute_Result::getRawData | PEAR Manual | Net_Traceroute_Result::getTargetIp


Net_Traceroute_Result::getTargetIp

Net_Traceroute_Result::getTargetIp

Net_Traceroute_Result::getTargetIp() – Returns the target IP from parsed result

Synopsis

require_once '/Traceroute.php';

string Net_Traceroute_Result::getTargetIp ( )

Description

This package is not documented yet.

Return value

returns IP address

Throws

throws no exceptions thrown

See

see _target_ip

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute_Result::getSystemName | PEAR Manual | Net_Traceroute_Result::getTTL


Net_Traceroute_Result::getTTL

Net_Traceroute_Result::getTTL

Net_Traceroute_Result::getTTL() – Returns TTL from parsed result

Synopsis

require_once '/Traceroute.php';

int Net_Traceroute_Result::getTTL ( )

Description

This package is not documented yet.

Return value

returns TTL

Throws

throws no exceptions thrown

See

see _ttl

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute_Result::getTargetIp | PEAR Manual | Net_Traceroute_Result::getValue


Net_Traceroute_Result::getValue

Net_Traceroute_Result::getValue

Net_Traceroute_Result::getValue() – Returns a Traceroute_Result property

Synopsis

require_once '/Traceroute.php';

mixed Net_Traceroute_Result::getValue ( string $name )

Description

This package is not documented yet.

Parameter

string $name

property name

Return value

returns property value

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Net_Traceroute | Next
Net_Traceroute_Result::getTTL | PEAR Manual | Package Net_Traceroute Constants


Package Net_Traceroute Constants

Package Net_Traceroute Constants

Package Net_Traceroute Constants – Constants defined in and used by Net_Traceroute

All Constants

Constants defined in Traceroute.php

Constants defined in Traceroute.php
Name | Value | Line Number
NET_TRACEROUTE_CANT_LOCATE_TRACEROUTE_BINARY | 3 | 57
NET_TRACEROUTE_CANT_LOCATE_TRACEROUTE_BINARY_MSG | 'unable to locate the traceroute binary' | 51
NET_TRACEROUTE_FAILED |  | 54
NET_TRACEROUTE_FAILED_MSG | 'execution of traceroute failed' | 48
NET_TRACEROUTE_HOST_NOT_FOUND | 1 | 55
NET_TRACEROUTE_HOST_NOT_FOUND_MSG | 'unknown host' | 49
NET_TRACEROUTE_INVALID_ARGUMENTS | 2 | 56
NET_TRACEROUTE_INVALID_ARGUMENTS_MSG | 'invalid argument array' | 50
NET_TRACEROUTE_RESULT_UNSUPPORTED_BACKEND | 4 | 58
NET_TRACEROUTE_RESULT_UNSUPPORTED_BACKEND_MSG | 'Backend not Supported' | 52
Prev | Net_Traceroute | Next
Net_Traceroute_Result::getValue | PEAR Manual | Net_URL


Net_URL

Net_URL

Provides an easy parsing of URLs

Table of Contents
  • Net_URL Constructor -- Instantiating Net_URL
  • Net_URL::setOption -- Setting options with Net_URL
Prev | Networking | Next
Package Net_Traceroute Constants | PEAR Manual | Net_URL Constructor


Net_URL Constructor

Net_URL Constructor

Net_URL Constructor – Instantiating Net_URL

Synopsis

require_once 'Net/URL.php';

string Net_Whois ( string $url = null , boolean $useBrackets = true )

Description

Instantiates a new Net_URL object

Parameter

  • string $url - The url to parse. By default this is getting $_SERVER['PHP_SELF']

  • boolean $useBrackets - Whether to use sqare brackets or not when there is multiple query variable names using the same name.

Example

Using Net_URL

<?php
require_once 'Net/URL.php';
$url = new Net_URL();
print_r($url->querystring);
?>
Prev | Net_URL | Next
Net_URL | PEAR Manual | Net_URL::setOption


Net_URL::setOption

Net_URL::setOption

Net_URL::setOption – Setting options with Net_URL

Synopsis

require_once 'Net/URL.php';

string setOption ( string $optionName , string $value )

Description

Setting a Net_URL option

Parameter

List of options
Name | Description
encode_query_keys | This will encode the query keys if set to true. By default set to false.

  • string $optionName - The option name to set.

  • string $value - The value of the option to set.

Example

Using Net_URL

<?php
require_once 'Net/URL.php';
$url = new Net_URL;
$url->setOption('encode_query_keys', true);
print_r($url->querystring);
?>
Prev | Net_URL | Next
Net_URL Constructor | PEAR Manual | Net_Whois


Net_Whois

Net_Whois

Provides an API for accessing Whois services

Table of Contents
  • Net_Whois::query() -- does a whois query
Prev | Networking | Next
Net_URL::setOption | PEAR Manual | Net_Whois::query()


Net_Whois::query()

Net_Whois::query()

Net_Whois::query() – does a whois query

Synopsis

require_once 'Net/Whois.php';

string Net_Whois::query ( string $query , string $server )

Description

Executes a Whois query on a server

Parameter

  • string $query - the Whois database object to look up

  • string $server - the name of the server or its IP address

Return value

string - the data from the Whois request.

Throws

Possible PEAR_Error values
Error code | Error message | Reason | Solution
every | " Error connecting to server (Net_Socket says: Error-Message .) " | Connection to server failed | Check typing of server address and make sure the host is connected to the network.
Note: You will not get a PEAR_Error, if the query fails due to a not existing whois object. This can be only done by checking the data returned by query().

Example

Using Whois-query()

<?php
require_once "Net/Whois.php";

$server = "whois.denic.de";
$query  = "phpcrawler.de";     // get information about
                               // this domain
$whois = new Net_Whois;
$data = $whois->query($query, $server);
echo $data;
?>
Prev | Net_Whois | Next
Net_Whois | PEAR Manual | Net_Wifi


Net_Wifi

Net_Wifi

Scans for wireless networks

Table of Contents
  • Setup -- Making it work
  • Local info -- Current interface configuration
  • Scanning -- Finding wireless networks
Prev | Networking | Next
Net_Whois::query() | PEAR Manual | Setup


Setup

Setup

Setup – Making it work

Setup - Making it work

Net_Wifi uses the command line tools iwconfig and iwlist to gather information about local wireless network interfaces, and to give information about wireless networks reachable by your computer.

To work with the class, you need to make sure that both programs are found. By default, /sbin/ and /usr/sbin/ are looked up to find them when the class is instantiated. If that fails, the system's which tool is used to determine the location.

You can retrieve and set their locations with getPathIwconfig() and setPathIwconfig(), as well as getPathIwlist() and setPathIwlist().

Prev | Net_Wifi | Next
Net_Wifi | PEAR Manual | Local info


Local info

Local info

Local info – Current interface configuration

Getting local interface configuration

At first, you can get a list of network interfaces on your computer via getSupportedInterfaces(). It returns an array of strings that are the names of the network interfaces, e.g. "eth1" or "wlan0".

The full information about the state of a network interface can be retrieved with getCurrentConfig(). It returns a Net_Wifi_Config object. To just check if an interface is connected, use the isConnected() method also takes the interface name as only parameter.

A Net_Wifi_Config looks like this:

Net_Wifi_Config {
  activated     => bool(true)
  associated    => bool(true)
  ap            => string(17) "00:03:C9:44:34:2C"
  ssid          => string(4) "free"
  mode          => string(7) "managed"
  nick          => NULL
  rate          => string(2) "54"
  power         => string(2) "20"
  protocol      => string(12) "IEEE 802.11g"
  rssi          => string(3) "-37"
}

Prev | Net_Wifi | Next
Setup | PEAR Manual | Scanning


Scanning

Scanning

Scanning – Finding wireless networks

Finding wireless networks

To scan for available wireless networks in your environment, use the scan() method. It takes the network interface name as only parameter and returns an array of Net_Wifi_Cell objects.

You get an array of local wireless interfaces via the getSupportedInterfaces() method.

A cell object looks like this:

Net_Wifi_Cell {
  cell      => string(2) "01"
  mac       => string(17) "00:03:C9:44:34:2C"
  ssid      => string(8) "<hidden>"
  mode      => string(6) "master"
  channel   => int(1)
  encryption=> bool(false)
  frequency => NULL
  protocol  => string(13) "IEEE 802.11bg"
  rate      => float(54)
  rates     => array(12) {
    0   => float(1)
    1   => float(2)
    2   => float(5.5)
    3   => float(6)
  }
  rssi      => string(3) "-39"
  beacon    => int(336)
  quality   => string(6) "90/100"
}

Prev | Net_Wifi | Next
Local info | PEAR Manual | URI_Template


URI_Template

URI_Template

This package contains a parser for URI Templates as defined in the URI Template draft that is currently being proposed to the IETF.

Please note that the standardization initiative regarding URI Templates is not yet finished. Thus the API and the inner workings of this package may undergo major revisions in the future.

Table of Contents
  • Introduction -- Introduction to URI_Template
Prev | Networking | Next
Scanning | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to URI_Template

Overview

URI Templates are strings that contain embedded variables that are transformed into URIs after embedded variables are substituted.

More information about URI Templates can be found at the following locations:

  • URI Template project page

  • Constructing or Traversing URIs? on XML.com

  • DeWitt Clinton

  • Mark Nottingham

  • James Snell

In a nutshell, URI Templates allow actors to specify a certain structure for URIs in order to make it possible for other actors to fill the structure with concrete information later. Joe Gregorio has posted an example of a possible use case.

Setup

Requirements

URI_Template requires PHP 5.

Installation

The URI_Template package can be installed using the PEAR installer command pear install URI_Template.

Alternative installation methods for situations where one has no access to the pear installer command can be found in the general installation chapter.

Uninstallation

Uninstalling the package can be done with pear uninstall URI_Template.

Example

<?php
require_once "URI/Template.php";

$values = array("a" => "foo", "b" => "bar", "data" => "10,20,30",
                "points" => array(10, 20, 30), "list0" => array(),
                "str0" => "", "reserved" => ":/?#[]@!$&'()*+,;=",
                "a_b" => "baz");

$t = new URI_Template("/{-append|/|a}{-opt|data|points}{-neg|@|a}{-prefix|#|b}");
echo $t->substitute($values); /* /foo/data#bar */

$t = new URI_Template("relative/{reserved}/");
echo $t->substitute($values); /* relative/%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D/ */

$t = new URI_Template("http://example.org/{foo=%25}/");
echo $t->substitute($values); /* http://example.org/%25/ */

$t = new URI_Template("http://example.org/?{-join|&|a,data}");
echo $t->substitute($values); /* http://example.org/?a=foo&data=10%2C20%2C30 */

$t = new URI_Template("http://example.org/?d={-listjoin|,|points}&{-join|&|a,b}");
echo $t->substitute($values); /* http://example.org/?d=10,20,30&a=foo&b=bar */

$t = new URI_Template("http://example.org/?d={-listjoin|,|list0}&{-join|&|foo}");
echo $t->substitute(array()); /* http://example.org/?d=& */

$t = new URI_Template("http://example.org/?d={-listjoin|&d=|points}");
echo $t->substitute($values); /* http://example.org/?d=10&d=20&d=30 */

$t = new URI_Template("http://example.org/{a}{b}/{a_b}");
echo $t->substitute($values); /* http://example.org/foobar/baz */

$t = new URI_Template("http://example.org/{a}{-prefix|/-/|a}/");
echo $t->substitute($values); /* http://example.org/foo/-/foo/ */
?>
Prev | URI_Template | Next
URI_Template | PEAR Manual | Numbers


Numbers

Numbers

Provides Packages for working with numbers

Table of Contents
  • Numbers_Roman
Prev | PEAR Packages | Next
Introduction | PEAR Manual | Numbers_Roman


Numbers_Roman

Numbers_Roman

Numbers_Roman provides methods to convert Arabic numbers like 23 into Roman numerals like XXIII and back.

Table of Contents
  • Converting Arabic to Roman Numerals
  • Converting Roman Numerals to Arabic numbers
Prev | Numbers | Next
Numbers | PEAR Manual | Converting Arabic to Roman Numerals


Converting Arabic to Roman Numerals

Converting Arabic to Roman Numerals

Note: Both class methods are static; you do not need to instantiate an object.

The static method toNumeral does exactly this. It can be used for numbers from 1 to 5 999 999. Using it to convert higher numbers works, but does not produce historically correct results.

The second parameter $uppercase determines if the letters should be UPPERCASE (default) or not. Parameter number 3 sets if HTML code for overscores shall be generated; this is necessary for numbers greater than 3999. If the parameter is set to false, letters will be prefixed with an underscore _.

Converting Arabic numbers to Roman numerals

<?php
require_once 'Numbers/Roman.php';

echo Numbers_Roman::toNumeral(23);
//returns: XXIII

echo Numbers_Roman::toNumeral(23, false);
//returns: xxiii
?>
Prev | Numbers_Roman | Next
Numbers_Roman | PEAR Manual | Converting Roman Numerals to Arabic numbers


Converting Roman Numerals to Arabic numbers

Converting Roman Numerals to Arabic numbers

Using the static method toNumber you can convert Roman numerals like XLII to Arabic numbers like 42. Letters prefixed with an underscore represent numbers larger than 1000.

Conversion Table: Roman letter to Arabic number
Roman | Arabic
I | 1
V | 5
X | 10
L | 50
C | 100
D | 500
M | 1000
S, _V | 5000
R, _X | 10 000
P, _L | 50 000
Q, _C | 100 000
O, _D | 500 000
N, _M | 1 000 000

Converting Roman numerals to Arabic numbers

<?php
require_once 'Numbers/Roman.php';

echo Numbers_Roman::toNumber('XLII');
//returns: 42
?>
Prev | Numbers_Roman | Next
Converting Arabic to Roman Numerals | PEAR Manual | PEAR


PEAR

PEAR

Provides Packages to work with/get info from the PEAR core

Table of Contents
  • PEAR_Frontend_Gtk
  • PEAR_Frontend_Gtk2
  • PEAR_Info
  • PEAR_PackageFileManager
  • PEAR_PackageUpdate
  • PEAR_Size
Prev | PEAR Packages | Next
Converting Roman Numerals to Arabic numbers | PEAR Manual | PEAR_Frontend_Gtk


PEAR_Frontend_Gtk

PEAR_Frontend_Gtk

PEAR_Frontend_Gtk is a PHP-Gtk1 based frontend for PEAR. It allows you to view, install and uninstall packages from different channels.

You can start the program with pear -G if the package is installed.

Prev | PEAR | Next
PEAR | PEAR Manual | PEAR_Frontend_Gtk2


PEAR_Frontend_Gtk2

PEAR_Frontend_Gtk2

PEAR_Frontend_Gtk2 is a PHP-Gtk2 based frontend for PEAR. It allows you to view, install and uninstall packages from different channels.

Since PEAR 1.4.6, you can start the program with pear -G if the package is installed.

Note: The program requires the php-gtk extension that is not a PEAR/PECL package and can be obtained from http://gtk.php.net/.
Prev | PEAR | Next
PEAR_Frontend_Gtk | PEAR Manual | PEAR_Info


PEAR_Info

PEAR_Info

Displays Information about your current PEAR install. Akin to PHP's phpinfo().

Table of Contents
  • Summary
  • Reference guide
Prev | PEAR | Next
PEAR_Frontend_Gtk2 | PEAR Manual | Summary


Summary

Summary

Table of Contents
  • Features
  • System Requirements
  • About
Prev | PEAR_Info | Next
PEAR_Info | PEAR Manual | Features


Features

Features

  • generates a comprehensive information page for your current PEAR install.

  • the format for the page is similar to that for phpinfo() except using PEAR colors.

  • have complete PEAR Credits (based on the packages you have installed).

  • will show if there is a newer version than the one presently installed (and what its state is).

  • a default style sheet is provided by default, but render is fully customizable

  • outputs plain text instead of HTML when using the CLI mode (since version 1.8.0).

  • show list of all files PEAR searches for configs, not only the files that were actually read (since version 1.9.0).

Prev | Summary | Next
Summary | PEAR Manual | System Requirements


System Requirements

System Requirements

Mandatory resources :

  • PHP 4.3.10 or newer.

  • PEAR 1.5.4 or newer.

  • pcre extension.

Optional resources :

  • PHPUnit 3.1.4 or newer.

Prev | Summary | Next
Features | PEAR Manual | About


About

About

Table of Contents
  • FAQ -- Answers to most Frequently Asked Questions
  • News -- What is New in version ?
  • Introduction -- Introduction to PEAR_Info
Prev | Summary | Next
System Requirements | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

PEAR_Info FAQ

    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.

    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 want to display my system configuration, but this one is not detected ?

    If your system file (see command pear config-show) does not exists, or is locate in another directory, then you should give this information on PEAR_Info class constructor.

    <?php
    // @link http://pear.php.net/bugs/bug.php?id=12878
    //       Search for pear.conf inside /etc/pear/

    require_once 'PEAR/Info.php';

    $pear_dir  = '';
    $user_file = '';
    $syst_file = '/etc/pear/pear.conf';

    $info = new PEAR_Info($pear_dir, $user_file, $syst_file);
    $info->display();
    ?>
    I want to change the look an feel (colors) of PEAR_Info output ?

    First copy the default stylesheet named pearinfo.css (locate in {data_dir}/PEAR_Info : see command pear config-show) as a pattern. Then second, change colors and whatever you want until you keep all CSS selectors.

    See for example the blue layout pattern skin locate in package installation under name {doc_dir}/PEAR_Info/examples/blueskin.css.

    Last, as {doc_dir}/PEAR_Info/examples/pear_info2.php script, set the new stylesheet with PEAR_Info::setStyleSheet.

    <?php
    require_once 'PEAR/Info.php';

    $info = new PEAR_Info();
    $info->setStyleSheet(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'blueskin.css');
    $info->display();
    ?>
    I want to display packages from all my channels ?

    By default PEAR_Info display only informations from pear.php.net channel.

    To remove this limit, give as option to the class constructor an empty channels list, as below :

    <?php
    require_once 'PEAR/Info.php';

    $pear_dir  = '';
    $user_file = '';
    $syst_file = '/opt/lampp/etc/pear.conf';
    $options   = array('channels' => array() );

    $info = new PEAR_Info($pear_dir, $user_file, $syst_file, $options);
    $info->display();
    ?>
    Note: If you want to filter package listing from a channel list, then give the full qualified list; something like :
    <?php
    $options     = array('channels' => array('pear.php.net', 'pear.phpunit.de', '__uri') );
    ?>

    I want to check if a package is installed or not ?

    With static method PEAR_Info::packageInstalled, you can check installation of a package from all channels declared, and also filter by version.

    <?php
    require_once 'PEAR/Info.php';

    $inst = PEAR_Info::packageInstalled('Role_Web', '1.1.0', 'pearified');
    if (    $inst === false) {
        echo     'sorry it seems that "pearified/Role_Web" package is not installed'
               . ' or version is less than 1.1.0';
    }
    ?>
    Prev | About | Next
About | PEAR Manual | News


News

News

News – What is New in version ?

Version 1.0.x

  • Initial PEAR public release occured at end of April 2003.

  • Moved output of the PEAR_Info to PEAR_Info::show()

  • Local PEAR logo copy included

  • Added PEAR Configuration section to the output

Version 1.5.x

  • Allows Off-Line viewing

  • Shows *all* installed packages, whether in PEAR or not

  • You can now specify a custom PEAR config file

Version 1.6.x

  • Added static method, PEAR_Info::packageInstalled(). Allows to check if a package is installed or not.

Version 1.7.x

  • Easy change look and feel with a simple CSS file

  • Show packages dependencies list

  • HTML page output is XHTML compliant

  • Introduce a full and flexible configuration system to show only information you want

  • Show channel list

  • Show maintainer inactive status in Credits page

  • Support REST 1.0 protocol

  • Drop support of package xml 1.0

  • Credits page is now customizable with PEAR_INFO_CREDITS_* constant

  • You may have a standalone html page (default behavior) with PEAR_INFO_FULLPAGE, or part of it

  • Removed support of PEAR 1.3.x

  • Upgrade requirement to PHP 4.3.0 and PEAR 1.5.4 (to avoid security vulnerability)

  • Coding Standard fixes (errors/warnings) following recommandation by PHP_CodeSniffer

Version 1.8.x

  • PEAR_Info is also available now on command line (CLI), and display a text report as phpinfo() did.

Version 1.9.x

  • Beautify Html output with some additional links

  • Show list of all files PEAR searches for configs, not only the files that were actually read. Render of alternative configuration file found/notfound is allowed by CSS selectors.

  • fix encoding character in credits page for Sérgio Carvalho and Stig Sæther Bakken

  • improve render and display index only when there are packages (in main page)

    improve render and did not display maintainers empty list (in credits page)

  • add a counter of installed packages for each channel (in main page)

Prev | About | Next
FAQ | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to PEAR_Info

Introduction to PEAR_Info

PEAR_Info obtains and displays information about your current PEAR Install. The PEAR_Info page features an A-Z index for easy searching, aswell as anchors for each package in the form of pkg_Package_Name (i.e. url.tld/pearinfo.php#pkg_PEAR_Info) PEAR_Info also features a full 'PEAR Credits' page, with information about the authors of the packages you currently have installed. PEAR_Info will also display any later versions that are available from PEAR to help keep you up to date.

Using PEAR_Info

<?php
require_once 'PEAR/Info.php';

/*
If you need to set a http_proxy value at run-time that is not set in
your user or system pear configuration file, you can use the
following, this must be called BEFORE instantiating the PEAR_Info object
*/

PEAR_Info::setProxy('your.proxy.here');

/*
Optional pear_dir variable, allows you to choose where your PEAR
install is, in case it's not found
*/

$pear_dir = "/path/to/your/pear/files";

/*
Instantiate PEAR_Info object
*/

$info = new PEAR_Info($pear_dir);

/*
Show PEAR_Info output
*/

$info->display();
?>

PEAR_Info options

The output may be customized by passing one or more of the following constants bitwise values summed together in the optional options hash parameter. One can also combine the respective constants or bitwise values together with the or operator.

General page options
Name | Value | Description
PEAR_INFO_GENERAL | 1 | The configuration file location, PEAR logo and current install version.
PEAR_INFO_CREDITS | 2 | A link to PEAR Credits page. See also PEAR_INFO_CREDITS_* constants.
PEAR_INFO_CONFIGURATION | 4 | All PEAR settings (keys and values).
PEAR_INFO_CHANNELS | 8 | List available channels
PEAR_INFO_PACKAGES | 4080 | All package informations. See all others PEAR_INFO_PACKAGES_* constants.
PEAR_INFO_PACKAGES_CHANNEL | 2048 | Show the package channel
PEAR_INFO_PACKAGES_SUMMARY | 1024 | A short description of the package
PEAR_INFO_PACKAGES_VERSION | 512 | Package version with state and release date.
PEAR_INFO_PACKAGES_LICENSE | 256 | License of the package release
PEAR_INFO_PACKAGES_DESCRIPTION | 128 | A long description of the package
PEAR_INFO_PACKAGES_DEPENDENCIES | 64 | Show package dependency list
PEAR_INFO_PACKAGES_XML | 32 | Tell what PEAR packager and package xml version (1.0 or 2.0) was used to build and install the package.
PEAR_INFO_PACKAGES_UPDATE | 16 | Show the latest version available. Displayed only if different than current install version.
PEAR_INFO_ALL | 4095 | Shows all of the above. This is the default value.

Credits page options
Name | Value | Description
PEAR_INFO_CREDITS_ALL | 61440 | All credits informations. See all others PEAR_INFO_CREDITS_* constants.
PEAR_INFO_CREDITS_GROUP | 4096 | Show PEAR Group members list
PEAR_INFO_CREDITS_DOCS | 8192 | Show PEAR Documentation Team list
PEAR_INFO_CREDITS_WEBSITE | 16384 | Show PEAR Website Team list
PEAR_INFO_CREDITS_PACKAGES | 32768 | Show authors (and roles) of package maintainers

Common options
Name | Value | Description
PEAR_INFO_FULLPAGE | 65536 | Indicates that a complete stand-alone HTML page needs to be printed including the information indicated by the other flags. This is the default value.

Customize PEAR_Info output

<?php
require_once 'PEAR/Info.php';

/*
Optional resume option, allows you to choose what information to display.
Here we will display a quick list of package (version only) group by channel.
*/

$options = array('resume' => PEAR_INFO_FULLPAGE |
    PEAR_INFO_GENERAL | PEAR_INFO_CHANNELS | PEAR_INFO_PACKAGES_VERSION,
    'channels' => array()
);

/*
Instantiate PEAR_Info object, using PEAR default install configuration
*/

$info = new PEAR_Info('', '', '', $options);

/*
Set you own presentation size and colors, with a simple style sheet.
*/

$css_file = "/path/to/your/file.css";
$info->setStyleSheet($css_file);

/*
Show PEAR_Info output
*/

$info->display();
?>
Prev | About | Next
News | PEAR Manual | Reference guide


Reference guide

Reference guide

Table of Contents
  • constructor PEAR_Info::PEAR_Info -- PHP 4 style constructor (ZE1)
  • PEAR_Info::display -- Displays PEAR_Info output
  • PEAR_Info::getMembers -- Returns a members list depending of its category (group, docs, website)
  • PEAR_Info::getStyleSheet -- Returns the custom style sheet to use for presentation
  • PEAR_Info::packageInstalled -- Check if a package is installed
  • PEAR_Info::pearImage -- Display the PEAR logo
  • PEAR_Info::setProxy -- Sets PEAR HTTP Proxy Server Address
  • PEAR_Info::setStyleSheet -- Sets the custom style sheet to use your own styles
  • PEAR_Info::show -- Shows PEAR_Info output
  • PEAR_Info::toHtml -- Returns PEAR_Info output (html code)
Prev | PEAR_Info | Next
Introduction | PEAR Manual | constructor PEAR_Info::PEAR_Info


constructor PEAR_Info::PEAR_Info

constructor PEAR_Info::PEAR_Info

constructor PEAR_Info::PEAR_Info() – PHP 4 style constructor (ZE1)

Synopsis

require_once 'PEAR/Info.php';

void constructor PEAR_Info::PEAR_Info ( string $pear_dir = '' , string $user_file = '' , string $system_file = '' , array $options = null )

Description

Important: $user_file , $system_file and $options parameters are available since version 1.7.0RC1, allowing to define more easily the PEAR configuration files, and choose what information to display akin to PHP's phpinfo().

Parameter

string $pear_dir

(optional) The PEAR base install directory

string $user_file

(optional) file to read PEAR user-defined options from

string $system_file

(optional) file to read PEAR system-wide defaults from

array $options

(optional) configure PEAR information output

Throws

throws no exceptions thrown

Since

since version 1.0.1 (2003-04-24)

Note

This function can not be called statically.

Example

<?php
require_once 'PEAR/Info.php';

// Display only PEAR version and logo, reference to config file, list of channels
// and quick list of packages (with only version info) installed thru channels
// pear, __uri, pecl.
$options = array('resume' =>  PEAR_INFO_GENERAL | PEAR_INFO_CHANNELS | PEAR_INFO_PACKAGES_VERSION,
    'channels' => array('pear.php.net', '__uri', 'pecl.php_net')
);

// Give PEAR install directory where to find pear.ini or pearsys.ini files
$info = new PEAR_Info('c:\wamp\php', '', '', $options);

$info->display();

?>
Prev | Reference guide | Next
Reference guide | PEAR Manual | PEAR_Info::display


PEAR_Info::display

PEAR_Info::display

PEAR_Info::display() – Displays PEAR_Info output

Synopsis

require_once 'PEAR/Info.php';

void PEAR_Info::display ( )

Description

Displays PEAR_Info output depending of style applied (style sheet).

Throws

throws no exceptions thrown

Since

since version 1.7.0RC1 (2007-07-01)

Note

This function can not be called statically.

See

PEAR_Info::setStyleSheet()

Prev | Reference guide | Next
constructor PEAR_Info::PEAR_Info | PEAR Manual | PEAR_Info::getMembers


PEAR_Info::getMembers

PEAR_Info::getMembers

PEAR_Info::getMembers() – Returns a members list depending of its category (group, docs, website)

Synopsis

require_once 'PEAR/Info.php';

array PEAR_Info::getMembers ( string $group = 'all' , bool $sort = true )

Description

Retrieve the members list of PEAR group, PEAR doc team, or PEAR website team

Parameter

string $group

(optional) Member list category. Either president, group, docs or website

boolean $sort

(optional) Return a member list sorted in alphabetic order

Throws

throws no exceptions thrown

Since

since version 1.7.0RC3 (2007-07-10)

Note

This function can not be called statically.

Prev | Reference guide | Next
PEAR_Info::display | PEAR Manual | PEAR_Info::getStyleSheet


PEAR_Info::getStyleSheet

PEAR_Info::getStyleSheet

PEAR_Info::getStyleSheet() – Returns the custom style sheet to use for presentation

Synopsis

require_once 'PEAR/Info.php';

string PEAR_Info::getStyleSheet ( boolean $content = true )

Description

Default behavior is to return css string contents. Sets $content parameter to FALSE will return css filename reference (defined by setStyleSheet function). Easy for a <link rel="stylesheet" type="text/css" href="" /> html tag integration (see example below).

Parameter

boolean $content

(optional) Either return css filename or string contents

Throws

throws no exceptions thrown

Since

since version 1.7.0RC1 (2007-07-01)

Note

This function can not be called statically.

Return value

string - returns css filename or css string contents

Example

<?php
// require the PEAR_Info file
require_once 'PEAR/Info.php';

class PEAR_Info3 extends PEAR_Info
{
    function PEAR_Info3($pear_dir = '', $user_file = '', $system_file = '')
    {
        $this->__construct($pear_dir, $user_file, $system_file);
    }

    function toHtml()
    {
        $styles = basename($this->getStyleSheet(false));

        $body = $this->info;

        $html = <<<HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" >
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="author" content="Laurent Laville" />
<title>My PEAR_Info()</title>
<link rel="stylesheet" type="text/css" href="$styles" />
</head>
<body>

<div id="header">
<h1>Laurent-Laville.org</h1>
</div>

<div id="footer">
</div>

<div id="contents">
$body
</div>

</body>
</html>
HTML;
        return $html;
    }
}

// Create PEAR_Info object
$info = new PEAR_Info3();

// set your own styles, rather than use the default stylesheet
$info->setStyleSheet(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'pearinfo3.css');

// Display PEAR_Info output
$info->display();
?>
Prev | Reference guide | Next
PEAR_Info::getMembers | PEAR Manual | PEAR_Info::packageInstalled


PEAR_Info::packageInstalled

PEAR_Info::packageInstalled

PEAR_Info::packageInstalled() – Check if a package is installed

Synopsis

require_once 'PEAR/Info.php';

boolean PEAR_Info::packageInstalled ( string $name , string $version = null , string $channel = null , string $user_file = '' , string $system_file = '' )

Description

Simple function to check if a package is installed under user or system PEAR installation. Minimal version and channel info are supported.

Parameter

string $name

Package name

string $version

(optional) The minimal version that should be installed

string $channel

(optional) The package channel distribution

string $user_file

(optional) file to read PEAR user-defined options from

string $system_file

(optional) file to read PEAR system-wide defaults from

Since

since version 1.6.0 (2005-01-03)

Throws

throws no exceptions thrown

Note

This function should be called statically.

Example

<?php
require_once 'PEAR/Info.php';

$res = PEAR_Info::packageInstalled('Role_Web', '1.1.0', 'pearified');
if ($res) {
    print "Package pearified/Role_Web 1.1.0 or greater is installed \n";
} else {
    print "Package pearified/Role_Web is not yet installed \n";
}

$res = PEAR_Info::packageInstalled('PEAR_PackageFileManager');
if ($res) {
    print "Package pear/PEAR_PackageFileManager is installed \n";
} else {
    print "Package pear/PEAR_PackageFileManager is not yet installed \n";
}
?>
Prev | Reference guide | Next
PEAR_Info::getStyleSheet | PEAR Manual | PEAR_Info::pearImage


PEAR_Info::pearImage

PEAR_Info::pearImage

PEAR_Info::pearImage() – Display the PEAR logo

Synopsis

require_once 'PEAR/Info.php';

void PEAR_Info::pearImage ( )

Description

Display the PEAR logo (gif image) on browser output

Throws

throws no exceptions thrown

Since

since version 1.0.1 (2003-04-24)

Note

This function can not be called statically.

Prev | Reference guide | Next
PEAR_Info::packageInstalled | PEAR Manual | PEAR_Info::setProxy


PEAR_Info::setProxy

PEAR_Info::setProxy

PEAR_Info::setProxy() – Sets PEAR HTTP Proxy Server Address

Synopsis

require_once 'PEAR/Info.php';

boolean PEAR_Info::setProxy ( string $proxy )

Description

Sets http_proxy config setting at runtime.

Note: Since version 1.7.0RC1, it become unnecessary, unless you don't want to use the http_proxy config setting of your PEAR config file.

Parameter

string $proxy

PEAR HTTP Proxy Server Address

Since

since version 1.0.6 (2003-05-11)

Throws

throws no exceptions thrown

Note

This function should be called statically.

Return value

boolean - TRUE if the http proxy server address was set successfully, FALSE otherwise.

Prev | Reference guide | Next
PEAR_Info::pearImage | PEAR Manual | PEAR_Info::setStyleSheet


PEAR_Info::setStyleSheet

PEAR_Info::setStyleSheet

PEAR_Info::setStyleSheet() – Sets the custom style sheet to use your own styles

Synopsis

require_once 'PEAR/Info.php';

boolean PEAR_Info::setStyleSheet ( string $css = null )

Description

Sets the custom style sheet (colors, sizes) to applied to PEAR_Info output. If you don't give any parameter, you'll then apply again the default style.

Parameter

string $css

(optional) File to read user-defined styles from

Throws

throws no exceptions thrown

Since

since version 1.7.0RC1 (2007-07-01)

Note

This function can not be called statically.

Tip

If you don't want to have any style applied, then build an empty style sheet (css file) and give it as function parameter (See example below).

Return value

boolean - TRUE if custom styles, FALSE if default styles applied.

Example

<?php
// require the PEAR_Info file
require_once 'PEAR/Info.php';

// Create PEAR_Info object
$info = new PEAR_Info();

// set your own styles, rather than use the default stylesheet
$info->setStyleSheet(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'blueskin.css');

// don't use any style (empty.css is an empty file)
//$info->setStyleSheet(dirname(__FILE__) . DIRECTORY_SEPARATOR . 'empty.css');

// Display PEAR_Info output
$info->display();
?>
Prev | Reference guide | Next
PEAR_Info::setProxy | PEAR Manual | PEAR_Info::show


PEAR_Info::show

PEAR_Info::show

PEAR_Info::show() – Shows PEAR_Info output

Synopsis

require_once 'PEAR/Info.php';

void PEAR_Info::show ( )

Description

Displays PEAR_Info output depending of style applied (style sheet).

Deprecated

deprecated use display() instead

Throws

throws no exceptions thrown

Since

since version 1.0.1 (2003-04-24)

Note

This function can not be called statically.

See

PEAR_Info::setStyleSheet()

Prev | Reference guide | Next
PEAR_Info::setStyleSheet | PEAR Manual | PEAR_Info::toHtml


PEAR_Info::toHtml

PEAR_Info::toHtml

PEAR_Info::toHtml() – Returns PEAR_Info output (html code)

Synopsis

require_once 'PEAR/Info.php';

string PEAR_Info::toHtml ( )

Description

Returns html code. This code is XHTML 1.1 compliant since version 1.7.0

Throws

throws no exceptions thrown

Since

since version 1.7.0RC1 (2007-07-01)

Note

This function can not be called statically.

See

PEAR_Info::setStyleSheet() , PEAR_Info::getStyleSheet()

Prev | Reference guide | Next
PEAR_Info::show | PEAR Manual | PEAR_PackageFileManager


PEAR_PackageFileManager

PEAR_PackageFileManager

Table of Contents
  • Class Summary PEAR_PackageFileManager -- PEAR :: PackageFileManager updates the <filelist></filelist> section of a PEAR package.xml file to reflect the current files in preparation for a release.
  • constructor PEAR_PackageFileManager::PEAR_PackageFileManager -- Does nothing, use setOptions
  • PEAR_PackageFileManager::addConfigureOption -- Add an install-time configuration option for building of source
  • PEAR_PackageFileManager::addDependency -- Add a dependency on another package, or an extension/php
  • PEAR_PackageFileManager::addMaintainer -- Add a maintainer to the list of maintainers.
  • PEAR_PackageFileManager::addPlatformException -- Add an install-time platform conditional install for a file
  • PEAR_PackageFileManager::addGlobalReplacement -- Add a replacement option for all files
  • PEAR_PackageFileManager::addReplacement -- Add a replacement option for a file
  • PEAR_PackageFileManager::addRole -- Add an extension/role mapping to the role mapping option
  • PEAR_PackageFileManager::detectDependencies -- use PHP_CompatInfo to auto-detect PHP and extension dependencies.
  • PEAR_PackageFileManager::debugPackageFile -- ALWAYS use this to test output before overwriting your package.xml!!
  • PEAR_PackageFileManager::getWarnings -- Retrieve the list of warnings
  • PEAR_PackageFileManager::isIncludeable -- calls http://www.php.net/file_exists for each value in include_path,
  • PEAR_PackageFileManager::pushWarning -- Store a warning on the warning stack
  • PEAR_PackageFileManager::raiseError -- Utility function to shorten error generation code
  • PEAR_PackageFileManager::setOptions -- Set package.xml generation options
  • PEAR_PackageFileManager::writePackageFile -- Writes the package.xml file out with the newly created <release></release> tag
  • Class Summary PEAR_PackageFileManager_CVS -- Generate a file list from a CVS checkout
  • PEAR_PackageFileManager_CVS::dirList -- Return a list of all files in the CVS repository
  • Class Summary PEAR_PackageFileManager_File -- Retrieve the files from a directory listing
  • constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File -- Set up the File filelist generator
  • PEAR_PackageFileManager_File::dirList -- Retrieve a listing of every file in $directory and all subdirectories.
  • PEAR_PackageFileManager_File::getFileList -- Generate the <filelist></filelist> section of the package file.
  • Class Summary PEAR_PackageFileManager_XMLOutput -- Class for XML output
  • Package PEAR_PackageFileManager Constants -- Constants defined in and used by PEAR_PackageFileManager
  • Package PEAR_PackageFileManager Global Variables -- Global Variables defined in and used by PEAR_PackageFileManager
Prev | PEAR | Next
PEAR_Info::toHtml | PEAR Manual | Class Summary PEAR_PackageFileManager


Class Summary PEAR_PackageFileManager

Class Summary PEAR_PackageFileManager

Class Summary PEAR_PackageFileManager – PEAR :: PackageFileManager updates the <filelist></filelist> section of a PEAR package.xml file to reflect the current files in preparation for a release.

PEAR :: PackageFileManager updates the <filelist></filelist> section of a PEAR package.xml file to reflect the current files in preparation for a release.

The PEAR_PackageFileManager class uses a plugin system to generate the list of files in a package. This allows both standard recursive directory parsing (plugin type file) and more intelligent options such as the CVS browser PEAR_PackageFileManager_Cvs, which grabs all files in a local CVS checkout to create the list, ignoring any other local files.

Other options include specifying roles for file extensions (all .php files are role="php", for example), roles for directories (all directories named "tests" are given role="tests" by default), and exceptions. Exceptions are specific pathnames with * and ? wildcards that match a default role, but should have another. For example, perhaps a debug.tpl template would normally be data, but should be included in the docs role. Along these lines, to exclude files entirely, use the ignore option.

Required options for a release include version, baseinstalldir, state, and packagedirectory (the full path to the local location of the package to create a package.xml file for)

Example usage:

1      <?php
   2      require_once('PEAR/PackageFileManager.php');
   3      $packagexml = new
PEAR_PackageFileManager
;
   4      $e = $packagexml->
setOptions
(
   5      array('baseinstalldir' => 'PhpDocumentor',
   6       'version' => '1.2.1',
   7       'packagedirectory' => 'C:/Web Pages/chiara/phpdoc2/',
   8       'state' => 'stable',
   9       'filelistgenerator' => 'cvs', // generate from cvs, use file for directory
   10      'notes' => 'We\'ve implemented many new and exciting features',
   11      'ignore' => array('TODO', 'tests/'), // ignore TODO, all files in tests/
   12      'installexceptions' => array('phpdoc' => '/*'), // baseinstalldir ="/" for phpdoc
   13      'dir_roles' => array('tutorials' => 'doc'),
   14      'exceptions' => array('README' => 'doc', // README would be data, now is doc
   15                            'PHPLICENSE.txt' => 'doc'))); // same for the license
   16     if (PEAR::isError($e)) {
   17         echo $e->getMessage();
   18         die();
   19     }
   20     $e = $test->
addPlatformException
('pear-phpdoc.bat', 'windows');
   21     if (PEAR::isError($e)) {
   22         echo $e->getMessage();
   23         exit;
   24     }
   25     $packagexml->
addRole
('pkg', 'doc'); // add a new role mapping
   26     if (PEAR::isError($e)) {
   27         echo $e->getMessage();
   28         exit;
   29     }
   30     // replace @PHP-BIN@ in this file with the path to php executable!  pretty neat
   31     $e = $test->
addReplacement
('pear-phpdoc', 'pear-config', '@PHP-BIN@', 'php_bin');
   32     if (PEAR::isError($e)) {
   33         echo $e->getMessage();
   34         exit;
   35     }
   36     $e = $test->
addReplacement
('pear-phpdoc.bat', 'pear-config', '@PHP-BIN@', 'php_bin');
   37     if (PEAR::isError($e)) {
   38         echo $e->getMessage();
   39         exit;
   40     }
   41     // note use of
debugPackageFile()
- this is VERY important
   42     if (isset($_GET['make']) || $_SERVER['argv'][1] == 'make') {
   43         $e = $packagexml->
writePackageFile
();
   44     } else {
   45         $e = $packagexml->
debugPackageFile
();
   46     }
   47     if (PEAR::isError($e)) {
   48         echo $e->getMessage();
   49         die();
   50     }
   51     ?>

In addition, a package.xml file can now be generated from scratch, with the usage of new options package, summary, description, and the use of the addMaintainer() method

Class Trees for PEAR_PackageFileManager

  • PEAR_PackageFileManager

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager | PEAR Manual | constructor PEAR_PackageFileManager::PEAR_PackageFileManager


constructor PEAR_PackageFileManager::PEAR_PackageFileManager

constructor PEAR_PackageFileManager::PEAR_PackageFileManager

constructor PEAR_PackageFileManager::PEAR_PackageFileManager() – Does nothing, use setOptions

Synopsis

require_once 'PEAR/PackageFileManager.php';

void constructor PEAR_PackageFileManager::PEAR_PackageFileManager ( )

Description

The constructor is not used in order to be able to return a PEAR_Error from setOptions

Throws

throws no exceptions thrown

See

see PEAR_PackageFileManager::setOptions()

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
Class Summary PEAR_PackageFileManager | PEAR Manual | PEAR_PackageFileManager::addConfigureOption


PEAR_PackageFileManager::addConfigureOption

PEAR_PackageFileManager::addConfigureOption

PEAR_PackageFileManager::addConfigureOption() – Add an install-time configuration option for building of source

Synopsis

require_once 'PEAR/PackageFileManager.php';

void|PEAR_Error PEAR_PackageFileManager::addConfigureOption ( string $name , string $prompt , string $default = null )

Description

This option is only useful to PECL projects that are built upon installation

Parameter

string $name

name of the option

string $prompt

prompt to display to the user

string $default

default value

Throws

throws PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
constructor PEAR_PackageFileManager::PEAR_PackageFileManager | PEAR Manual | PEAR_PackageFileManager::addDependency


PEAR_PackageFileManager::addDependency

PEAR_PackageFileManager::addDependency

PEAR_PackageFileManager::addDependency() – Add a dependency on another package, or an extension/php

Synopsis

require_once 'PEAR/PackageFileManager.php';

void|PEAR_Error PEAR_PackageFileManager::addDependency ( string $name , string $version = false , string $operator = 'ge' , string $type = 'pkg' , boolean $optional = false )

Description

This will overwrite an existing dependency if it is found. In other words, if a dependency on PHP 4.1.0 exists, and addDependency('php', '4.3.0', 'ge', 'php') is called, the existing dependency on PHP 4.1.0 will be overwritten with the new one on PHP 4.3.0

Parameter

string $name

Dependency element name

string $version

Dependency version

string $operator

A specific operator for the version, this can be one of: 'has', 'not', 'lt', 'le', 'eq', 'ne', 'ge', or 'gt'

string $type

Dependency type. This can be one of: 'pkg', 'ext', 'php', 'prog', 'os', 'sapi', or 'zend'

boolean $optional

TRUE if dependency is optional

Throws

throws PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS

throws PEAR_PACKAGEFILEMANAGER_PHP_NOT_PACKAGE

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addConfigureOption | PEAR Manual | PEAR_PackageFileManager::addMaintainer


PEAR_PackageFileManager::addMaintainer

PEAR_PackageFileManager::addMaintainer

PEAR_PackageFileManager::addMaintainer() – Add a maintainer to the list of maintainers.

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::addMaintainer ( string $handle , lead|developer|contributor|helper $role , string $name , string $email )

Description

Every maintainer must have a valid account at pear.php.net. The first parameter is the account name (for instance, cellog is the handle for Greg Beaver at pear.php.net). Every maintainer has one of four possible roles:

  • lead: the primary maintainer

  • developer: an important developer on the project

  • contributor: self-explanatory

  • helper: ditto

Finally, specify the name and email of the maintainer

Parameter

string $handle

username on pear.php.net of maintainer

lead|developer|contributor|helper $role

role of maintainer

string $name

full name of maintainer

string $email

email address of maintainer

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addDependency | PEAR Manual | PEAR_PackageFileManager::addPlatformException


PEAR_PackageFileManager::addPlatformException

PEAR_PackageFileManager::addPlatformException

PEAR_PackageFileManager::addPlatformException() – Add an install-time platform conditional install for a file

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::addPlatformException ( string $path , string $platform )

Description

The format of the platform string must be OS-version-cpu-extra if any more specific information is needed, and the OS must be in lower case as in "windows." The match is performed using a regular expression, but uses * and ? wildcards instead of .* and .?. Note that hpux/aix/irix/linux are all exclusive. To select non-windows, use an expression like (*ix|*ux|darwin). If using PEAR 1.3.2 and newer, use !windows.

This information is based on eyeing the source for OS/Guess.php, so if you are unsure of what to do, read that file.

Parameter

string $path

relative path of file (relative to packagedirectory option)

string $platform

platform descriptor string

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addMaintainer | PEAR Manual | PEAR_PackageFileManager::addGlobalReplacement


PEAR_PackageFileManager::addGlobalReplacement

PEAR_PackageFileManager::addGlobalReplacement

PEAR_PackageFileManager::addGlobalReplacement() – Add a replacement option for all files

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::addglobalreplacement ( string $type , string $from , string $to )

Description

This sets an install-time complex search-and-replace function allowing the setting of platform-specific variables in all installed files.

if $type is php-const, then $to must be the name of a PHP Constant. If $type is pear-config, then $to must be the name of a PEAR config variable accessible through a PEAR_Config::get() method. If type is package-info, then $to must be the name of a section from the package.xml file used to install this file.

Parameter

string $type

variable type, either php-const, pear-config or package-info

string $from

text to replace in the source file

string $to

variable name to use for replacement

Throws

throws PEAR_PACKAGEFILEMANAGER_INVALID_REPLACETYPE

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addPlatformException | PEAR Manual | PEAR_PackageFileManager::addReplacement


PEAR_PackageFileManager::addReplacement

PEAR_PackageFileManager::addReplacement

PEAR_PackageFileManager::addReplacement() – Add a replacement option for a file

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::addReplacement ( string $path , string $type , string $from , string $to )

Description

This sets an install-time complex search-and-replace function allowing the setting of platform-specific variables in an installed file.

if $type is php-const, then $to must be the name of a PHP Constant. If $type is pear-config, then $to must be the name of a PEAR config variable accessible through a PEAR_Config::get() method. If type is package-info, then $to must be the name of a section from the package.xml file used to install this file.

Parameter

string $path

relative path of file (relative to packagedirectory option)

string $type

variable type, either php-const, pear-config or package-info

string $from

text to replace in the source file

string $to

variable name to use for replacement

Throws

throws PEAR_PACKAGEFILEMANAGER_INVALID_REPLACETYPE

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addGlobalReplacement | PEAR Manual | PEAR_PackageFileManager::addRole


PEAR_PackageFileManager::addRole

PEAR_PackageFileManager::addRole

PEAR_PackageFileManager::addRole() – Add an extension/role mapping to the role mapping option

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::addRole ( string $extension , string $role )

Description

Roles influence both where a file is installed and how it is installed. Files with role="data" are in a completely different directory hierarchy from the program files of role="php"

In PEAR 1.3b2, these roles are

  • php (most common)

  • data

  • doc

  • test

  • script (gives the file an executable attribute)

  • src

Parameter

string $extension

file extension

string $role

role

Throws

throws PEAR_PACKAGEFILEMANAGER_INVALID_ROLE

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addReplacement | PEAR Manual | PEAR_PackageFileManager::detectDependencies


PEAR_PackageFileManager::detectDependencies

PEAR_PackageFileManager::detectDependencies

PEAR_PackageFileManager::detectDependencies() – use PHP_CompatInfo to auto-detect PHP and extension dependencies.

Synopsis

require_once 'PEAR/PackageFileManager.php';

void|PEAR_Error PEAR_PackageFileManager::detectDependencies ( )

Description

Use addDependency() to add package dependencies

Throws

throws PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS

throws PEAR_PACKAGEFILEMANAGER_PHP_COMPAT_NOT_INSTALLED

throws PEAR_PACKAGEFILEMANAGER_NO_PHPCOMPATINFO

See

see PEAR_PackageFileManager::addDependency()

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::addRole | PEAR Manual | PEAR_PackageFileManager::debugPackageFile


PEAR_PackageFileManager::debugPackageFile

PEAR_PackageFileManager::debugPackageFile

PEAR_PackageFileManager::debugPackageFile() – ALWAYS use this to test output before overwriting your package.xml!!

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::debugPackageFile ( )

Description

This method instructs writePackageFile() to simply print the package.xml to output, either command-line or web-friendly (this is automatic based on the existence of $_SERVER['PATH_TRANSLATED']

Throws

throws no exceptions thrown

See

see PEAR_PackageFileManager::writePackageFile() - calls with the debug parameter set based on whether it is called from the command-line or web interface

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::detectDependencies | PEAR Manual | PEAR_PackageFileManager::getWarnings


PEAR_PackageFileManager::getWarnings

PEAR_PackageFileManager::getWarnings

PEAR_PackageFileManager::getWarnings() – Retrieve the list of warnings

Synopsis

require_once 'PEAR/PackageFileManager.php';

array PEAR_PackageFileManager::getWarnings ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::debugPackageFile | PEAR Manual | PEAR_PackageFileManager::isIncludeable


PEAR_PackageFileManager::isIncludeable

PEAR_PackageFileManager::isIncludeable

PEAR_PackageFileManager::isIncludeable() – calls http://www.php.net/file_exists for each value in include_path,

Synopsis

require_once 'PEAR/PackageFileManager.php';

boolean PEAR_PackageFileManager::isIncludeable ( string $filename )

Description

then calls http://www.php.net/is_readable when it finds the file

Parameter

string $filename

Throws

throws no exceptions thrown

static

static

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::getWarnings | PEAR Manual | PEAR_PackageFileManager::pushWarning


PEAR_PackageFileManager::pushWarning

PEAR_PackageFileManager::pushWarning

PEAR_PackageFileManager::pushWarning() – Store a warning on the warning stack

Synopsis

require_once 'PEAR/PackageFileManager.php';

void PEAR_PackageFileManager::pushWarning ( mixed $code , mixed $info )

Description

This package is not documented yet.

Parameter

mixed $code

mixed $info

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::isIncludeable | PEAR Manual | PEAR_PackageFileManager::raiseError


PEAR_PackageFileManager::raiseError

PEAR_PackageFileManager::raiseError

PEAR_PackageFileManager::raiseError() – Utility function to shorten error generation code

Synopsis

require_once 'PEAR/PackageFileManager.php';

PEAR_Error PEAR_PackageFileManager::raiseError ( mixed $code , mixed $i1 = '' , mixed $i2 = '' )

Description

1     function
raiseError
($code, $i1 = '', $i2 = '')
2         {
3             return PEAR::raiseError('PEAR_PackageFileManager Error: ' .
4
sprintf
($GLOBALS['_PEAR_PACKAGEFILEMANAGER_ERRORS'][$this->_options['lang']][$code],
5                         $i1, $i2), $code);
6         }

Parameter

mixed $code

mixed $i1

mixed $i2

Throws

throws no exceptions thrown

static

static

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::pushWarning | PEAR Manual | PEAR_PackageFileManager::setOptions


PEAR_PackageFileManager::setOptions

PEAR_PackageFileManager::setOptions

PEAR_PackageFileManager::setOptions() – Set package.xml generation options

Synopsis

require_once 'PEAR/PackageFileManager.php';

void|PEAR_Error PEAR_PackageFileManager::setOptions ( array $options = array() )

Description

The options array is indexed as follows:

1      $options = array('option_name' => <optionvalue>);

The documentation below simplifies this description through the use of option_name without quotes

Configuration options:

  • lang: lang controls the language in which error messages are displayed. There are currently only English error messages, but any contributed will be added over time. Possible values: en (default)

  • packagefile: the name of the packagefile, defaults to package.xml

  • pathtopackagefile: the path to an existing package file to read in, if different from the packagedirectory

  • packagedirectory: the path to the base directory of the package. For package PEAR_PackageFileManager, this path is /path/to/pearcvs/pear/PEAR_PackageFileManager where /path/to/pearcvs is a local path on your hard drive

  • outputdirectory: the path in which to place the generated package.xml by default, this is ignored, and the package.xml is created in the packagedirectory

  • filelistgenerator: the <filelist> section plugin which will be used. In this release, there are two generator plugins, file and cvs. For details, see the docs for these plugins

  • usergeneratordir: For advanced users. If you write your own filelist generator plugin, use this option to tell PEAR_PackageFileManager where to find the file that contains it. If the plugin is named foo, the class must be named PEAR_PackageFileManager_Foo no matter where it is located. By default, the Foo plugin is located in PEAR/PackageFileManager/Foo.php. If you pass /path/to/foo in this option, setOptions will look for PEAR_PackageFileManager_Foo in /path/to/foo/Foo.php

  • doctype: Specifies the DTD of the package.xml file. Default is http://pear.php.net/dtd/package-1.0

  • pearcommonclass: Specifies the name of the class to instantiate, default is PEAR_Common, but users can override this with a custom class that implements PEAR_Common's method interface

  • changelogoldtonew: True if the ChangeLog should list from oldest entry to newest. Set to false if you would like new entries first

  • simpleoutput: True if the package.xml should not contain md5sum or <provides /> for readability

  • addhiddenfiles: True if you wish to add hidden files/directories that begin with . like .bashrc. This is only used by the File generator. The CVS generator will use all files in CVS regardless of format

package.xml simple options:

  • baseinstalldir: The base directory to install this package in. For package PEAR_PackageFileManager, this is "PEAR", for package PEAR, this is "/"

  • license: The license this release is released under. Default is PHP License if left unspecified

  • notes: Release notes, any text describing what makes this release unique

  • changelognotes: notes for the changelog, this should be more detailed than the release notes. By default, PEAR_PackageFileManager uses the notes option for the changelog as well

  • version: The version number for this release. Remember the convention for numbering: initial alpha is between 0 and 1, add b<beta number> for beta as in 1.0b1, the integer portion of the version should specify backwards compatibility, as in 1.1 is backwards compatible with 1.0, but 2.0 is not backwards compatible with 1.10. Also note that 1.10 is a greater release version than 1.1 (think of it as "one point ten" and "one point one"). Bugfix releases should be a third decimal as in 1.0.1, 1.0.2

  • package: [optional] Package name. Use this to create a new package.xml, or overwrite an existing one from another package used as a template

  • summary: [optional] Summary of package purpose

  • description: [optional] Description of package purpose. Note that the above three options are not optional when creating a new package.xml from scratch

WARNING: all complex options that require a file path are case-sensitive

package.xml complex options:

  • cleardependencies: since version 1.3.0, this option will erase any existing dependencies in the package.xml if set to true

  • ignore: an array of filenames, directory names, or wildcard expressions specifying files to exclude entirely from the package.xml. Wildcards are operating system wildcards * and ?. file*foo.php will exclude filefoo.php, fileabrfoo.php and filewho_is_thisfoo.php. file?foo.php will exclude fileafoo.php and will not exclude fileaafoo.php. test/ will exclude all directories and subdirectories of ANY directory named test encountered in directory parsing. *test* will exclude all files and directories that contain test in their name

  • include: an array of filenames, directory names, or wildcard expressions specifying files to include in the listing. All other files will be ignored. Wildcards are in the same format as ignore

  • roles: this is an array mapping file extension to install role. This specifies default behavior that can be overridden by the exceptions option and dir_roles option. use addRole() to add a new role to the pre-existing array

  • dir_roles: this is an array mapping directory name to install role. All files in a directory whose name matches the directory will be given the install role specified. Single files can be excluded from this using the exceptions option. The directory should be a relative path from the baseinstalldir, or "/" for the baseinstalldir

  • exceptions: specify file role for specific files. This array maps all files matching the exact name of a file to a role as in "file.ext" => "role"

  • deps: dependency array. Pass in an empty array to clear all dependencies, and use addDependency() to add new ones/replace existing ones

  • maintainers: maintainers array. Pass in an empty array to clear all maintainers, and use addMaintainer() to add a new maintainer/replace existing maintainer

  • installexceptions: array mapping of specific filenames to baseinstalldir values. Use this to force the installation of a file into another directory, such as forcing a script to be in the root scripts directory so that it will be in the path. The filename must be a relative path to the packagedirectory

  • platformexceptions: array mapping of specific filenames to the platform they should be installed on. Use this to specify unix-only files or windows-only files. The format of the platform string must be OS-version-cpu-extra if any more specific information is needed, and the OS must be in lower case as in "windows." The match is performed using a regular expression, but uses * and ? wildcards instead of .* and .?. Note that hpux/aix/irix/linux are all exclusive. To select non-windows, use (*ix|*ux)

  • scriptphaseexceptions: array mapping of scripts to their install phase. This can be one of: pre-install, post-install, pre-uninstall, post-uninstall, pre-build, post-build, pre-setup, or post-setup

  • installas: array mapping of specific filenames to the filename they should be installed as. Use this to specify new filenames for files that should be installed. This will often be used in conjunction with platformexceptions if there are two files for different OSes that must have the same name when installed.

  • replacements: array mapping of specific filenames to complex text search-and-replace that should be performed upon install. The format is: filename => array('type' => php-const|pear-config|package-info
    'from' => text in file
    'to' => name of variable) if type is php-const, then 'to' must be the name of a PHP Constant. If type is pear-config, then 'to' must be the name of a PEAR config variable accessible through a PEAR_Config class->get() method. If type is package-info, then 'to' must be the name of a section from the package.xml file used to install this file.

  • globalreplacements: a list of replacements that should be performed on every single file. The format is the same as replacements (since 1.4.0)

  • configure_options: array specifies build options for PECL packages (you should probably use PECL_Gen instead, but it's here for completeness)

Parameter

array $options

Throws

throws PEAR_PACKAGEFILEMANAGER_NOPKGDIR

throws PEAR_PACKAGEFILEMANAGER_NOVERSION

throws PEAR_PACKAGEFILEMANAGER_NOSTATE

throws PEAR_PACKAGEFILEMANAGER_NOBASEDIR

throws PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND_ANYWHERE

throws PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND

See

see PEAR_PackageFileManager_CVS

see PEAR_PackageFileManager_File

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::raiseError | PEAR Manual | PEAR_PackageFileManager::writePackageFile


PEAR_PackageFileManager::writePackageFile

PEAR_PackageFileManager::writePackageFile

PEAR_PackageFileManager::writePackageFile() – Writes the package.xml file out with the newly created <release></release> tag

Synopsis

require_once 'PEAR/PackageFileManager.php';

void|PEAR_Error PEAR_PackageFileManager::writePackageFile ( boolean $debuginterface = null )

Description

ALWAYS use debugPackageFile() to verify that output is correct before overwriting your package.xml

Parameter

boolean $debuginterface

NULL if no debugging, TRUE if web interface, FALSE if command-line

Throws

throws PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS

throws PEAR_PACKAGEFILEMANAGER_ADD_MAINTAINERS

throws PEAR_PACKAGEFILEMANAGER_CANTWRITE_PKGFILE

throws PEAR_PACKAGEFILEMANAGER_CANTOPEN_TMPPKGFILE

throws PEAR_PACKAGEFILEMANAGER_CANTCOPY_PKGFILE

throws PEAR_PACKAGEFILEMANAGER_DEST_UNWRITABLE

See

see PEAR_PackageFileManager::debugPackageFile() - calls with the debug parameter set based on whether it is called from the command-line or web interface

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::setOptions | PEAR Manual | Class Summary PEAR_PackageFileManager_CVS


Class Summary PEAR_PackageFileManager_CVS

Class Summary PEAR_PackageFileManager_CVS

Class Summary PEAR_PackageFileManager_CVS – Generate a file list from a CVS checkout

Generate a file list from a CVS checkout

Note that this will NOT work on a repository, only on a checked out CVS module

Class Trees for PEAR_PackageFileManager_CVS

  • PEAR_PackageFileManager_File

    • PEAR_PackageFileManager_CVS

PEAR_PackageFileManager_CVS Inherited Methods

Inherited from PEAR_PackageFileManager_File
Method Name | Summary
Constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File() | Set up the File filelist generator
PEAR_PackageFileManager_File::dirList() | Retrieve a listing of every file in $directory and all subdirectories.
PEAR_PackageFileManager_File::getFileList() | Generate the <filelist></filelist> section of the package file.
Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager::writePackageFile | PEAR Manual | PEAR_PackageFileManager_CVS::dirList


PEAR_PackageFileManager_CVS::dirList

PEAR_PackageFileManager_CVS::dirList

PEAR_PackageFileManager_CVS::dirList() – Return a list of all files in the CVS repository

Synopsis

require_once 'PEAR/PackageFileManager/Cvs.php';

array PEAR_PackageFileManager_CVS::dirList ( string $directory )

Description

This function is like parent::dirList() except that instead of retrieving a regular filelist, it first retrieves a listing of all the CVS/Entries files in $directory and all of the subdirectories. Then, it reads the Entries file, and creates a listing of files that are a part of the CVS repository. No check is made to see if they have been modified, but newly added or removed files are ignored.

Parameter

string $directory

full path to the directory you want the list of

Return value

returns list of files in a directory

Throws

throws no exceptions thrown

See

see _readCVSEntries()

see _recurDirList()

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
Class Summary PEAR_PackageFileManager_CVS | PEAR Manual | Class Summary PEAR_PackageFileManager_File


Class Summary PEAR_PackageFileManager_File

Class Summary PEAR_PackageFileManager_File

Class Summary PEAR_PackageFileManager_File – Retrieve the files from a directory listing

Retrieve the files from a directory listing

This class is used to retrieve a raw directory listing. Use the PEAR_PackageFileManager_CVS class to only retrieve the contents of a cvs repository when generating the package.xml

Class Trees for PEAR_PackageFileManager_File

  • PEAR_PackageFileManager_File

Classes that extend PEAR_PackageFileManager_File
Class | Summary
PEAR_PackageFileManager_CVS | Generate a file list from a CVS checkout
Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager_CVS::dirList | PEAR Manual | constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File


constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File

constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File

constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File() – Set up the File filelist generator

Synopsis

require_once 'PEAR/PackageFileManager/File.php';

void constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File ( PEAR_PackageFileManager &$parent , array $options )

Description

'ignore' and 'include' are the only options that this class uses. See PEAR_PackageFileManager::setOptions() for more information and formatting of this option

Parameter

PEAR_PackageFileManager &$parent

array $options

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
Class Summary PEAR_PackageFileManager_File | PEAR Manual | PEAR_PackageFileManager_File::dirList


PEAR_PackageFileManager_File::dirList

PEAR_PackageFileManager_File::dirList

PEAR_PackageFileManager_File::dirList() – Retrieve a listing of every file in $directory and all subdirectories.

Synopsis

require_once 'PEAR/PackageFileManager/File.php';

array PEAR_PackageFileManager_File::dirList ( string $directory )

Description

The return format is an array of full paths to files

Parameter

string $directory

full path to the directory you want the list of

Return value

returns list of files in a directory

Throws

throws PEAR_PACKAGEFILEMANAGER_DIR_DOESNT_EXIST

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File | PEAR Manual | PEAR_PackageFileManager_File::getFileList


PEAR_PackageFileManager_File::getFileList

PEAR_PackageFileManager_File::getFileList

PEAR_PackageFileManager_File::getFileList() – Generate the <filelist></filelist> section of the package file.

Synopsis

require_once 'PEAR/PackageFileManager/File.php';

array PEAR_PackageFileManager_File::getFileList ( )

Description

This function performs the backend generation of the array containing all files in this package

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager_File::dirList | PEAR Manual | Class Summary PEAR_PackageFileManager_XMLOutput


Class Summary PEAR_PackageFileManager_XMLOutput

Class Summary PEAR_PackageFileManager_XMLOutput

Class Summary PEAR_PackageFileManager_XMLOutput – Class for XML output

Class for XML output

This package is not documented yet.

Class Trees for PEAR_PackageFileManager_XMLOutput

  • PEAR_Common

    • PEAR_PackageFileManager_XMLOutput

Prev | PEAR_PackageFileManager | Next
PEAR_PackageFileManager_File::getFileList | PEAR Manual | Package PEAR_PackageFileManager Constants


Package PEAR_PackageFileManager Constants

Package PEAR_PackageFileManager Constants

Package PEAR_PackageFileManager Constants – Constants defined in and used by PEAR_PackageFileManager

All Constants

Constants defined in PackageFileManager.php

Constants defined in PackageFileManager.php
Name | Value | Line Number
PEAR_PACKAGEFILEMANAGER_ADD_MAINTAINERS | 19 | 50
PEAR_PACKAGEFILEMANAGER_CANTCOPY_PKGFILE | 9 | 40
PEAR_PACKAGEFILEMANAGER_CANTOPEN_TMPPKGFILE | 10 | 41
PEAR_PACKAGEFILEMANAGER_CANTWRITE_PKGFILE | 7 | 38
PEAR_PACKAGEFILEMANAGER_CVS_PACKAGED | 26 | 57
PEAR_PACKAGEFILEMANAGER_DEST_UNWRITABLE | 8 | 39
PEAR_PACKAGEFILEMANAGER_DIR_DOESNT_EXIST | 13 | 44
PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND | 5 | 36
PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND_ANYWHERE | 6 | 37
PEAR_PACKAGEFILEMANAGER_IGNORED_EVERYTHING | 21 | 52
PEAR_PACKAGEFILEMANAGER_INVALID_PACKAGE | 22 | 53
PEAR_PACKAGEFILEMANAGER_INVALID_REPLACETYPE | 23 | 54
PEAR_PACKAGEFILEMANAGER_INVALID_ROLE | 24 | 55
PEAR_PACKAGEFILEMANAGER_NOBASEDIR | 4 | 35
PEAR_PACKAGEFILEMANAGER_NOCVSENTRIES | 12 | 43
PEAR_PACKAGEFILEMANAGER_NODESC | 18 | 49
PEAR_PACKAGEFILEMANAGER_NOPACKAGE | 15 | 46
PEAR_PACKAGEFILEMANAGER_NOPKGDIR | 3 | 34
PEAR_PACKAGEFILEMANAGER_NOSTATE | 1 | 32
PEAR_PACKAGEFILEMANAGER_NOSUMMARY | 17 | 48
PEAR_PACKAGEFILEMANAGER_NOVERSION | 2 | 33
PEAR_PACKAGEFILEMANAGER_NO_FILES | 20 | 51
PEAR_PACKAGEFILEMANAGER_PATH_DOESNT_EXIST | 11 | 42
PEAR_PACKAGEFILEMANAGER_PHP_NOT_PACKAGE | 25 | 56
PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS | 14 | 45
PEAR_PACKAGEFILEMANAGER_WRONG_MROLE | 16 | 47
Prev | PEAR_PackageFileManager | Next
Class Summary PEAR_PackageFileManager_XMLOutput | PEAR Manual | Package PEAR_PackageFileManager Global Variables


Package PEAR_PackageFileManager Global Variables

Package PEAR_PackageFileManager Global Variables

Package PEAR_PackageFileManager Global Variables – Global Variables defined in and used by PEAR_PackageFileManager

All Global Variables

Global Variables defined in PackageFileManager.php

Global Variables defined in PackageFileManager.php
Name Value Line Number
$GLOBALS['_PEAR_PACKAGEFILEMANAGER_ERRORS']
1     array(
2         'en' =>
3         array(
4
PEAR_PACKAGEFILEMANAGER_NOSTATE
=>
5                 'Release State (option \'state\') must by specified in PEAR_PackageFileManager setOptions (alpha|beta|stable)',
6
PEAR_PACKAGEFILEMANAGER_NOVERSION
=>
7                 'Release Version (option \'version\') must be specified in PEAR_PackageFileManager setOptions',
8
PEAR_PACKAGEFILEMANAGER_NOPKGDIR
=>
9                 'Package source base directory (option \'packagedirectory\') must be ' .
10                'specified in PEAR_PackageFileManager setOptions',
11
PEAR_PACKAGEFILEMANAGER_NOBASEDIR
=>
12                'Package install base directory (option \'baseinstalldir\') must be ' .
13                'specified in PEAR_PackageFileManager setOptions',
14
PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND
=>
15                'Base class "%s" can\'t be located',
16
PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND_ANYWHERE
=>
17                'Base class "%s" can\'t be located in default or user-specified directories',
18
PEAR_PACKAGEFILEMANAGER_CANTWRITE_PKGFILE
=>
19                'Failed to write package.xml file to destination directory',
20
PEAR_PACKAGEFILEMANAGER_DEST_UNWRITABLE
=>
21                'Destination directory "%s" is unwritable',
22
PEAR_PACKAGEFILEMANAGER_CANTCOPY_PKGFILE
=>
23                'Failed to copy package.xml.tmp file to package.xml',
24
PEAR_PACKAGEFILEMANAGER_CANTOPEN_TMPPKGFILE
=>
25                'Failed to open temporary file "%s" for writing',
26
PEAR_PACKAGEFILEMANAGER_PATH_DOESNT_EXIST
=>
27                'package.xml file path "%s" doesn\'t exist or isn\'t a directory',
28
PEAR_PACKAGEFILEMANAGER_NOCVSENTRIES
=>
29                'Directory "%s" is not a CVS directory (it must have the CVS/Entries file)',
30
PEAR_PACKAGEFILEMANAGER_DIR_DOESNT_EXIST
=>
31                'Package source base directory "%s" doesn\'t exist or isn\'t a directory',
32
PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS
=>
33                'Run $managerclass->setOptions() before any other methods',
34
PEAR_PACKAGEFILEMANAGER_NOPACKAGE
=>
35                'Package Name (option \'package\') must by specified in PEAR_PackageFileManager '.
36                'setOptions to create a new package.xml',
37
PEAR_PACKAGEFILEMANAGER_NOSUMMARY
=>
38                'Package Summary (option \'summary\') must by specified in PEAR_PackageFileManager' .
39                ' setOptions to create a new package.xml',
40
PEAR_PACKAGEFILEMANAGER_NODESC
=>
41                'Detailed Package Description (option \'description\') must be' .
42                ' specified in PEAR_PackageFileManager setOptions to create a new package.xml',
43
PEAR_PACKAGEFILEMANAGER_WRONG_MROLE
=>
44                'Maintainer role must be one of "%s", was "%s"',
45
PEAR_PACKAGEFILEMANAGER_ADD_MAINTAINERS
=>
46                'Add maintainers to a package before generating the package.xml',
47
PEAR_PACKAGEFILEMANAGER_NO_FILES
=>
48                'No files found, check the path "%s"',
49
PEAR_PACKAGEFILEMANAGER_IGNORED_EVERYTHING
=>
50                'No files left, check the path "%s" and ignore option "%s"',
51
PEAR_PACKAGEFILEMANAGER_INVALID_PACKAGE
=>
52                'Package validation failed:%s%s',
53
PEAR_PACKAGEFILEMANAGER_INVALID_REPLACETYPE
=>
54                'Replacement Type must be one of "%s", was passed "%s"',
55
PEAR_PACKAGEFILEMANAGER_INVALID_ROLE
=>
56                'Invalid file role passed to addRole, must be one of "%s", was passed "%s"',
57
PEAR_PACKAGEFILEMANAGER_PHP_NOT_PACKAGE
=>
58                'addDependency had PHP as a package, use type="php"',
59
PEAR_PACKAGEFILEMANAGER_CVS_PACKAGED
=>
60                'path "%path%" contains CVS directory',
61            ),)
 63
Prev | PEAR_PackageFileManager | Next
Package PEAR_PackageFileManager Constants | PEAR Manual | PEAR_PackageUpdate


PEAR_PackageUpdate

PEAR_PackageUpdate

Table of Contents
  • Introduction to PEAR_PackageUpdate -- A package to make adding self updating functionality to other packages or applications easy.
  • PEAR_PackageUpdate::factory -- Factory method for creating PEAR_PackageUpdate frontend instances.
  • PEAR_PackageUpdate::isIncludable -- Determines whether or not a file is includable.
  • PEAR_PackageUpdate::loadPreferences -- Loads the user's preferences from the preference file.
  • PEAR_PackageUpdate::determinePrefFile -- Returns the path to the preferences file.
  • PEAR_PackageUpdate::checkUpdate -- Checks to see if an update is available and the user has asked not to be notified about the update.
  • PEAR_PackageUpdate::getPackageInfo -- Loads the latest package information from the channel server.
  • PEAR_PackageUpdate::getPackagePreferences -- Returns the update preferences for the current package.
  • PEAR_PackageUpdate::savePreferences -- Saves the user preferences to the preference file.
  • PEAR_PackageUpdate::preferencesAllowUpdate -- Checks whether or not the user's preferences allow an update to the latest version of the package.
  • PEAR_PackageUpdate::releaseType -- Returns the release type of the most recent version of the package compared to the installed version.
  • PEAR_PackageUpdate::getInstalledRelease -- Loads the latest package information from the current installation.
  • PEAR_PackageUpdate::getLatestRelease -- Loads the latest package information from the channel server.
  • PEAR_PackageUpdate::setDontAskAgain -- Sets the user's "Don't Ask Again" preference for the package.
  • PEAR_PackageUpdate::setDontAskUntilNextRelease -- Sets the user's "Don't Ask Again Until Next Release" preference for the package.
  • PEAR_PackageUpdate::setMinimumReleaseType -- Sets the user's preference for asking about release types.
  • PEAR_PackageUpdate::setMinimumState -- Sets the user's preference for asking about release states.
  • PEAR_PackageUpdate::setPreference -- Sets the given preference to the given value.
  • PEAR_PackageUpdate::setPreferences -- Sets all preferences at once.
  • PEAR_PackageUpdate::update -- Updates the source for the package.
  • PEAR_PackageUpdate::popError -- Pops an error off the error stack.
  • PEAR_PackageUpdate::hasErrors -- Returns whether or not errors have occurred (and been captured).
Prev | PEAR | Next
Package PEAR_PackageFileManager Global Variables | PEAR Manual | Introduction to PEAR_PackageUpdate


Introduction to PEAR_PackageUpdate

Introduction to PEAR_PackageUpdate

Introduction to PEAR_PackageUpdate – A package to make adding self updating functionality to other packages or applications easy.

About PEAR::PackageUpdate

PEAR::PackageUpdate gives other packages or applications the ability to automatically keep themselves up-to-date by checking their channel server for the latest release and self-updating with the user's permission. Auto-update features help developers by reducing the number of different versions of a package which are currently used. This reduces the likely hood of bugs related to outdated versions being reported.

This package automates the update process but still allows the user to remain in control of their computer. PEAR::PackageUpdate respects a user's preferences and allows the user to decide not only if the package should be updated but also when to be alerted to new updates. The user can decide to only be notified when a new release has a certain state or release type (bug fix, feature enhancement, or major version). The user can even turn off the updating features. All of these settings are on a package-by-package basis.

PEAR::PackageUpdate is designed to be a backend for other packages which provide different interface types. For example, this package can be used to drive a PHP-GTK 2, CLI or HTML frontend.

Usage Example

<?php
   class Foo {
       function __construct()
       {
           // Try to update the package if needed.
           require_once 'PEAR/PackageUpdate.php';
           // Load the PHP-GTK 2 driver to check for updates for pear://Foo
           $ppu = PEAR_PackageUpdate::factory('Gtk2', 'Foo', 'pear');
           // Check for trouble loading the driver.
           if ($ppu !== false) {
               // See if a new version is available (respects user prefs).
               if ($ppu->checkUpdate()) {
                   // Ask for permission to update.
                   if ($ppu->presentUpdate()) {
                       if ($ppu->update()) {
                           // The update was a success. The app must be
                           // restarted.
                           $ppu->forceRestart();
                       }
                   }
               }
           }
           // ...
       }
       // ...
   }
   ?>

How to check warnings and/or errors

Rather than stop on first error/warning encountered, as it's done by other PHP4 PEAR packages, PEAR::PackageUpdate used the PEAR_ErrorStack for advanced error handling.

PEAR_ErrorStack implements error raising and handling using a stack pattern. So, to determine whether there are any errors on the stack, you should use the PEAR_PackageUpdate::hasErrors(). And to retrieve each error/warning, one by one, from the stack, you have to use the PEAR_PackageUpdate::popError().

See example below:

Usage of error levels with PEAR_PackageUpdate::hasErrors() is only available since version 0.7.0

<?php
   class Foo {
       function __construct()
       {
           // Try to update the package if needed.
           require_once 'PEAR/PackageUpdate.php';
           // Load the Cli driver to check for updates for pear://Foo
           $ppu = PEAR_PackageUpdate::factory('Cli', 'Foo', 'pear');
           // Check for trouble loading the driver.
           if ($ppu !== false) {
               // See if a new version is available (respects user prefs).
               if ($ppu->checkUpdate()) {
                   // Ask for permission to update.
                   if ($ppu->presentUpdate()) {
                       if ($ppu->update()) {
                           // The update was a success. The app must be
                           // restarted.
                           $ppu->forceRestart();
                       } else {
                           // Error handling
                           if ($ppu->hasErrors('warning')) {
                               // Warning: specifying error levels is only allowed since version 0.7.0
                               // Retrieve only first warning, not all
                               $error = $ppu->popError();
                               echo "Warning occured when trying to update: pear/Foo package\n";
                               echo "Message: " . $error['message'] ."\n";
                           }
                           if ($ppu->hasErrors()) {
                               // Retrieve only first error, not all
                               $error = $ppu->popError();
                               echo "Error occured when trying to update: pear/Foo package\n";
                               echo "Message: " . $error['message'] ."\n";
                               if (isset($error['context']) {
                                   // context is available
                                   echo "*** Context: ***\n";
                                   echo "File: " . $error['context']['file'] ."\n";
                                   echo "Line: " . $error['context']['line'] ."\n";
                                   echo "Function: " . $error['context']['function'] ."\n";
                                   echo "Class: " . $error['context']['class'] ."\n";
                               }
                               exit();
                           }
                       }
                   }
               }
           }
           // ...
       }
       // ...
   }
   ?>
Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate | PEAR Manual | PEAR_PackageUpdate::factory


PEAR_PackageUpdate::factory

PEAR_PackageUpdate::factory

PEAR_PackageUpdate::factory – Factory method for creating PEAR_PackageUpdate frontend instances.

Synopsis

require_once 'PEAR/PackageUpdate.php';

mixed PEAR_PackageUpdate::factory ( string $driver , string $packageName , string $channel , string $user_file = '' , string $system_file = '' , string $pref_file = '' )

Description

Factory method for creating PEAR_PackageUpdate frontend instances.

Parameter

string $driver

The name of a frontend driver class. Must be one of Gtk2, Cli, or Web.

string $packageName

The name of the package to be updated. Example: PEAR_PackageFileManager_Web.

string $channel

The name of the channel $packageName is hosted on. This may be a fully qualified channel name such as pear.php.net or a short channel name like pear.

string $user_file

The path to the file to read PEAR user-defined options from.

string $system_file

The path to the file to read PEAR system-wide defaults from.

string $pref_file

The path to the file to read user's preferences from.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NONEXISTENTDRIVER, when invalid driver name is used (i.e. Gtk2, Cli, Web).

Note

since 0.4.0a1

This function should be called statically.

Return value

mixed - reference to a new object or FALSE if the object could not be created (i.e. invalid driver name).

Prev | PEAR_PackageUpdate | Next
Introduction to PEAR_PackageUpdate | PEAR Manual | PEAR_PackageUpdate::isIncludable


PEAR_PackageUpdate::isIncludable

PEAR_PackageUpdate::isIncludable

PEAR_PackageUpdate::isIncludable – Determines whether or not a file is includable.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::isIncludable ( string $path )

Description

Determines whether or not a file is includable. This method is used to ensure that the driver class file can be found and included.

Parameter

string $path

The path to the file to check. The path should be a subdirectory of one of the directories in the include path.

Note

since 0.4.2

This function can be called statically.

Return value

boolean - TRUE if the file is includable, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::factory | PEAR Manual | PEAR_PackageUpdate::loadPreferences


PEAR_PackageUpdate::loadPreferences

PEAR_PackageUpdate::loadPreferences

PEAR_PackageUpdate::loadPreferences – Loads the user's preferences from the preference file.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::loadPreferences ( string $pref_file = '' )

Description

Loads the user's preferences from the preference file.

If the user is on a Windows machine, the file will be in the PEAR_CONFIG_SYSCONFIG directory and named ppurc.ini. If the user is on any other operating system, the preferences file will be stored in the user's home directory as the file .ppurc. The file contains a serialized array of preferences for each package that has been checked for updates so far.

Note: Since version 0.7.0, you could also choose another directory and name for your preference file. Use then the optional parameter $pref_file .

Parameter

string $pref_file

The path to the file to read user's preferences from.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_READACCESS, when user's preference file has no READ access right.

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_CORRUPTED, when user's preference file has invalid contents.

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDINIFILE, when user's preference file given by parameter $pref_file does not exist.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preferences were loaded successfully, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::isIncludable | PEAR Manual | PEAR_PackageUpdate::determinePrefFile


PEAR_PackageUpdate::determinePrefFile

PEAR_PackageUpdate::determinePrefFile

PEAR_PackageUpdate::determinePrefFile – Returns the path to the preferences file.

Synopsis

require_once 'PEAR/PackageUpdate.php';

string PEAR_PackageUpdate::determinePrefFile ( )

Description

Returns the path to the preferences file.

The preferences file holds information about whether or not the user would like to be notified about updates for individual packages. If the user is on a Windows machine, the file will be in the PEAR_CONFIG_SYSCONFIG directory and named ppurc.ini. If the user is on any operating system, the preferences file will be stored in the user's home directory as the file .ppurc.

Note

since 0.4.0a1

This function can be called statically.

Return value

string - The full path to the preferences file.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::loadPreferences | PEAR Manual | PEAR_PackageUpdate::checkUpdate


PEAR_PackageUpdate::checkUpdate

PEAR_PackageUpdate::checkUpdate

PEAR_PackageUpdate::checkUpdate – Checks to see if an update is available and the user has asked not to be notified about the update.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::checkUpdate ( )

Description

Checks to see if an update is available and the user has asked not to be notified about the update.

This method takes the user's preferences in consideration when determining if an update is available. If a new bug fix release is available but the user has asked not to be notified until the next major release of the package, this method will return FALSE.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if an update is available and the user has asked to be notified about the update, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::determinePrefFile | PEAR Manual | PEAR_PackageUpdate::getPackageInfo


PEAR_PackageUpdate::getPackageInfo

PEAR_PackageUpdate::getPackageInfo

PEAR_PackageUpdate::getPackageInfo – Loads the latest package information from the channel server.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::getPackageInfo ( )

Description

Loads the latest package information from the channel server.

This method contacts the packages channel server using a PEAR_Remote instance. If any errors are encountered (channel server does not host the package, bad package name, etc.) they will be pushed onto the error stack.

Note: Since version 0.5.2, protocol REST 1.0 is also supported. So we try to contact the packages channel server using a PEAR_REST instance, if this channel support the protocol, rather than default protocol XMLRPC.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NOPACKAGE, if package name was set to empty.

throws PEAR_PACKAGEUPDATE_ERROR_NOCHANNEL, if channel was set to empty.

throws PEAR_PACKAGEUPDATE_ERROR_NOINFO, when there are no information available about the package name hosted on the channel server.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the information was retrieved successfully, FALSE otherwise. Errors will be pushed onto the error stack.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::checkUpdate | PEAR Manual | PEAR_PackageUpdate::getPackagePreferences


PEAR_PackageUpdate::getPackagePreferences

PEAR_PackageUpdate::getPackagePreferences

PEAR_PackageUpdate::getPackagePreferences – Returns the update preferences for the current package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

array PEAR_PackageUpdate::getPackagePreferences ( )

Description

Returns an array of update preferences for the current package. This method is used to ensure that users are not asked about updates they do not want to be asked about.

The array returned may have up to four elements:

PEAR_PACKAGEUPDATE_PREF_NOUPDATES

if TRUE the user does not want to know about any new updates.

PEAR_PACKAGEUPDATE_PREF_NEXTRELEASE

if set, the user does not want to be asked until a version greater than the value of this element has been released.

PEAR_PACKAGEUPDATE_PREF_TYPE

if set, the user does not want to be notified unless the release is at least the given type (one of PEAR_PACKAGEUPDATE_TYPE_BUG, PEAR_PACKAGEUPDATE_TYPE_MINOR, PEAR_PACKAGEUPDATE_TYPE_MAJOR).

PEAR_PACKAGEUPDATE_PREF_STATE

if set, the user does not want to be notified unless the release has at least the given state (one of PEAR_PACKAGEUPDATE_PREF_STATE_DEVEL, PEAR_PACKAGEUPDATE_PREF_STATE_ALPHA, PEAR_PACKAGEUPDATE_PREF_STATE_BETA, PEAR_PACKAGEUPDATE_PREF_STATE_STABLE).

Note

since 0.4.0a1

This function can not be called statically.

Return value

array - an array of user preferences.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::getPackageInfo | PEAR Manual | PEAR_PackageUpdate::savePreferences


PEAR_PackageUpdate::savePreferences

PEAR_PackageUpdate::savePreferences

PEAR_PackageUpdate::savePreferences – Saves the user preferences to the preference file.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::savePreferences ( string $pref_file = '' )

Description

Saves the user's preferences to the preference file.

Parameter

string $pref_file

The path to the file to save user's preferences to.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEACCESS, when user's preference file has no WRITE access right.

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEERROR, when an I/O error occured while writing user's preference file contents.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the user's preferences were saved successfully, FALSE othewise.

See

PEAR_PackageUpdate::determinePrefFile()

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::getPackagePreferences | PEAR Manual | PEAR_PackageUpdate::preferencesAllowUpdate


PEAR_PackageUpdate::preferencesAllowUpdate

PEAR_PackageUpdate::preferencesAllowUpdate

PEAR_PackageUpdate::preferencesAllowUpdate – Checks whether or not the user's preferences allow an update to the latest version of the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::preferencesAllowUpdate ( )

Description

Checks whether or not the user's preferences allow an update to the latest version of the package. The user's preferences may define restrictions such as: don't update at all, don't update until a new version has been released (remembers the last version asked), only ask for certain states such as beta or stable, only ask for minor or higher version updates (no bug fixes), or only ask for major version updates.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the user's preferences allow an update for the latest version of the package, FALSE otherwise.

See

PEAR_PackageUpdate::getPackagePreferences()

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::savePreferences | PEAR Manual | PEAR_PackageUpdate::releaseType


PEAR_PackageUpdate::releaseType

PEAR_PackageUpdate::releaseType

PEAR_PackageUpdate::releaseType – Returns the release type of the most recent version of the package compared to the installed version.

Synopsis

require_once 'PEAR/PackageUpdate.php';

string PEAR_PackageUpdate::releaseType ( )

Description

Returns the release type of the most recent version of the package compared to the installed version. The result will be one of PEAR_PACKAGEUPDATE_TYPE_MAJOR, PEAR_PACKAGEUPDATE_TYPE_MINOR, or PEAR_PACKAGEUPDATE_TYPE_BUG.

This value is used to determine if the user's preferences allow an update for the current release.

Note

since 0.4.0a1

This function can not be called statically.

Return value

string - The release type (bug|minor|major).

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::preferencesAllowUpdate | PEAR Manual | PEAR_PackageUpdate::getInstalledRelease


PEAR_PackageUpdate::getInstalledRelease

PEAR_PackageUpdate::getInstalledRelease

PEAR_PackageUpdate::getInstalledRelease – Loads the latest package information from the current installation.

Synopsis

require_once 'PEAR/PackageUpdate.php';

mixed PEAR_PackageUpdate::getInstalledRelease ( )

Description

Loads the informations about current installed version of the package.

string version

The version of installed package name.

string license

The license this package is released under.

string summary

A short description about the package.

string description

A long description about the package.

string releasedate

The date of the release of the version installed.

string releasenotes

Description about changes on the package from previous release.

string state

The state of the package release installed (snapshot|devel|alpha|beta|stable).

array deps

The list of dependencies for this release of the package.

string xsdversion

The version of the XML package used to install this release (1.0 or 2.0).

string packagerversion

The version of the PEAR packager that was used to build this release.

Note

since 0.6.0

This function can not be called statically.

Return value

boolean - FALSE if the information was not available.

array - informations about the current installed version of the package (version, license, summary, description, releasedate, releasenotes, state, deps, xsdversion, packagerversion).

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::releaseType | PEAR Manual | PEAR_PackageUpdate::getLatestRelease


PEAR_PackageUpdate::getLatestRelease

PEAR_PackageUpdate::getLatestRelease

PEAR_PackageUpdate::getLatestRelease – Loads the latest package information from the channel server.

Synopsis

require_once 'PEAR/PackageUpdate.php';

mixed PEAR_PackageUpdate::getLatestRelease ( )

Description

Loads the informations from the channel server.

string license

The license the latest package version is released under.

string summary

A short description about the package.

string description

A long description about the package.

string releasedate

The date of the latest release available from the channel server.

string releasenotes

Description about changes on the package from previous release.

string state

The state of the package release installed (snapshot|devel|alpha|beta|stable).

array deps

The list of dependencies for this release of the package.

string version

The version of the latest release available from the channel server.

Note

since 0.6.0

This function can not be called statically.

Return value

boolean - FALSE if the information was not available.

array - informations about the current installed version of the package (license, summary, description, releasedate, releasenotes, state, deps, version).

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::getInstalledRelease | PEAR Manual | PEAR_PackageUpdate::setDontAskAgain


PEAR_PackageUpdate::setDontAskAgain

PEAR_PackageUpdate::setDontAskAgain

PEAR_PackageUpdate::setDontAskAgain – Sets the user's "Don't Ask Again" preference for the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setDontAskAgain ( boolean $dontAsk )

Description

Sets the user's "Don't Ask Again" preference to $dontAsk . If $dontAsk is TRUE the user will not be asked to update the package again.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::getLatestRelease | PEAR Manual | PEAR_PackageUpdate::setDontAskUntilNextRelease


PEAR_PackageUpdate::setDontAskUntilNextRelease

PEAR_PackageUpdate::setDontAskUntilNextRelease

PEAR_PackageUpdate::setDontAskUntilNextRelease – Sets the user's "Don't Ask Again Until Next Release" preference for the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setDontAskUntilNextRelease ( boolean $dontAsk )

Description

Sets the user's "Don't Ask Again Until Next Release" preference to $dontAsk . If $dontAsk is TRUE the user will not be asked to update the package again until a new version is released.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NOINFO, when there are no information available about the package name hosted on the channel server.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::setDontAskAgain | PEAR Manual | PEAR_PackageUpdate::setMinimumReleaseType


PEAR_PackageUpdate::setMinimumReleaseType

PEAR_PackageUpdate::setMinimumReleaseType

PEAR_PackageUpdate::setMinimumReleaseType – Sets the user's preference for asking about release types.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setMinimumReleaseType ( string $minType )

Description

Sets the user's preference for asking about minimum release types.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDTYPE, when invalid type of release is used (bug|minor|major).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::setDontAskUntilNextRelease | PEAR Manual | PEAR_PackageUpdate::setMinimumState


PEAR_PackageUpdate::setMinimumState

PEAR_PackageUpdate::setMinimumState

PEAR_PackageUpdate::setMinimumState – Sets the user's preference for asking about release states.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setMinimumState ( string $minState )

Description

Sets the user's preference for asking about minimum release state.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDSTATE, when invalid state of release is used (snapshot|devel|alpha|beta|stable).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::setMinimumReleaseType | PEAR Manual | PEAR_PackageUpdate::setPreference


PEAR_PackageUpdate::setPreference

PEAR_PackageUpdate::setPreference

PEAR_PackageUpdate::setPreference – Sets the given preference to the given value.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setPreference ( string $pref , string $value )

Description

Sets one of the given preference to the given value. Both preference and value, should have valid values.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDPREF, when invalid preference is used (PEAR_PACKAGEUPDATE_PREF_NOUPDATES, PEAR_PACKAGEUPDATE_PREF_NEXTRELEASE, PEAR_PACKAGEUPDATE_PREF_TYPE, PEAR_PACKAGEUPDATE_PREF_STATE).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::setMinimumState | PEAR Manual | PEAR_PackageUpdate::setPreferences


PEAR_PackageUpdate::setPreferences

PEAR_PackageUpdate::setPreferences

PEAR_PackageUpdate::setPreferences – Sets all preferences at once.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setPreferences ( array $preferences )

Description

Sets a group of preference with associated values, all at once. Invalid preference is ignored (no error raised).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if all the preferences were set properly, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::setPreference | PEAR Manual | PEAR_PackageUpdate::update


PEAR_PackageUpdate::update

PEAR_PackageUpdate::update

PEAR_PackageUpdate::update – Updates the source for the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::update ( )

Description

Updates your current installation with the new source for the package.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NOTINSTALLED, if the package is not already installed.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the update was successful, FALSE otherwise.

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::setPreferences | PEAR Manual | PEAR_PackageUpdate::popError


PEAR_PackageUpdate::popError

PEAR_PackageUpdate::popError

PEAR_PackageUpdate::popError – Pops an error off the error stack.

Synopsis

require_once 'PEAR/PackageUpdate.php';

array PEAR_PackageUpdate::popError ( )

Description

Pops an error off the error stack.

This method is just for collecting errors that occur while checking for updates and updating a package. The child class is responsible for displaying all errors and handling them properly. This is because the way errors are handled varies greatly depending on the driver used.

Note

since 0.4.0a1

This function can not be called statically.

Return value

array - details of an error or warning (with debug context if available).

See

PEAR_PackageUpdate::hasErrors()

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::update | PEAR Manual | PEAR_PackageUpdate::hasErrors


PEAR_PackageUpdate::hasErrors

PEAR_PackageUpdate::hasErrors

PEAR_PackageUpdate::hasErrors – Returns whether or not errors have occurred (and been captured).

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::hasErrors ( mixed $level = false )

Description

Returns whether or not errors , and or, warnings (version 0.7.0 or better) have occurred.

Parameter

mixed $level

The level of errors to pop off of the stack (warning|error). Use FALSE if you want all errors and warnings at once.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if errors(/warnings) have been captured, FALSE othewise.

See

PEAR_PackageUpdate::popError()

Prev | PEAR_PackageUpdate | Next
PEAR_PackageUpdate::popError | PEAR Manual | PEAR_Size


PEAR_Size

PEAR_Size

Find out how much disk space is consumed by an installed pear package or a number of pear packages - analagous to the unix command df.

Table of Contents
  • Summary
  • About
  • Getting started
  • Reference guide
Prev | PEAR | Next
PEAR_PackageUpdate::hasErrors | PEAR Manual | Summary


Summary

Summary

Table of Contents
  • Features
  • System Requirements
Prev | PEAR_Size | Next
PEAR_Size | PEAR Manual | Features


Features

Features

  • investigate a single PEAR package.

  • investigate a set of PEAR packages.

  • display information for all installed packages.

  • output report in CSV format.

  • print sizes in human readable format.

  • specify what type of files are to be included in the report.

  • produce a summary report.

  • sort results by file size.

  • output results in XML format.

Prev | Summary | Next
Summary | PEAR Manual | System Requirements


System Requirements

System Requirements

Mandatory resources:

  • PHP 5.1.4 or newer.

  • PEAR 1.4.0 or newer.

  • PEAR::Console_Getargs 1.3.4 or newer.

  • PEAR::Console_Table 1.1.0 or newer.

  • PEAR::HTML_Table 1.8.2 or newer.

Prev | Summary | Next
Features | PEAR Manual | About


About

About

Table of Contents
  • Introduction -- About PEAR_Size
  • Re-using PEAR_Size -- Embedding it in your own application
Prev | PEAR_Size | Next
System Requirements | PEAR Manual | Introduction


Introduction

Introduction

Introduction – About PEAR_Size

About PEAR_Size

PEAR_Size started as a php script that was born of a need to determine if there were any large pear packages installed that could be removed to free up space; it is analagous to the unix command df - this tool lists how much filespace each installed package consumes; also a subset of packages can be specified as can channels.

That script has evolved into a reusable set of classes that can be used from your own code and can render its report into HTML, XML, CSV and plain text formats. This is extensible so if required you could generate PDFs and possibly even charts of the data that is generated.

Prev | About | Next
About | PEAR Manual | Re-using PEAR_Size


Re-using PEAR_Size

Re-using PEAR_Size

Re-using PEAR_Size – Embedding it in your own application

Re-using PEAR_Size

PEAR_Size consists of several core classes plus some ancillary ones. Most important is the PEAR_Size class itself. This performs the data-gathering process and then initiates the generation of the output report (using the analyse() and generateReport() methods respectively). The format of the report is set using the setOutputDriver() method.

If writing a command-line script that will utilise the power of PEAR_Size it is best to use the PEAR_Size_CLI class and run() for parsing the details and options set at the command prompt. The usage() method is for displaying either a usage screen or some error message. This method uses the application name as defined with the setAppName() method in those screens. If you intend to embed PEAR_Size into your own application or script you can set its name with the aforementioned method and retrieve it with appName().

Prev | About | Next
Introduction | PEAR Manual | Getting started


Getting started

Getting started

Table of Contents
  • Overview -- features and usage patterns
  • The Command-Line Script -- generating PEAR_Size reports at the commandline.
  • Outputting Results -- The Output Drivers
Prev | PEAR_Size | Next
Re-using PEAR_Size | PEAR Manual | Overview


Overview

Overview

Overview – features and usage patterns

In brief

There are two ways in which you can use PEAR_Size: via the pear command line tool or integrated in a PHP script.

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

Prev | Getting started | Next
Getting started | PEAR Manual | The Command-Line Script


The Command-Line Script

The Command-Line Script

The Command-Line Script – generating PEAR_Size reports at the commandline.

Switches and options

The pear size command can be used to generate reports.

  Usage: pear size [OPTIONS] [PACKAGE]

Display information on how much space an installed PEAR package required.

  -a, --all            display information for all installed packages

  -A, --allchannels    list packages from all channels, not just the default one

  -c, --channel        specify which channel

  -C, --csv            output results in CSV format (sizes are measured in bytes).

  -h, --human-readable print sizes in human readable format (for example: 492 B 1KB 7MB)

  -H, --si             likewise, but use powers of 1000 not 1024

  -t, --type           specify what type of files are required for the report

                       by default all types are assumed

  -s, --summarise      display channel summary view

  -S, --fsort          sort by file size

  -v, --verbose        display more detailed information

      --help           display this help and exit

  -V, --version        output version information and exit

  -X, --xml            output results in XML format

  -0, --killzero       do not output zero values in verbose mode

Types:

You can specify a subset of roles/file-types to be listed in the report.

These roles are those as supported by the PEAR installer.

These are: data, doc, ext, php, script, src, test

Examples:

                $ pear size --all

                $ pear size Console_Table

                $ pear size -ttest,doc Console_Table

                $ pear size --type=test,doc,php -h Console_Table Date_Holidays

Prev | Getting started | Next
Overview | PEAR Manual | Outputting Results


Outputting Results

Outputting Results

Outputting Results – The Output Drivers

Overview

PEAR_Size has a number of output drivers which provide a means of providing reports in a range of various formats in an extensible manner - they all extend the PEAR_Size_Output_Driver class.

Four drivers are currently available for use:

  • CSV, PEAR_Size_Output_CSV. Print a comma separate values of results.

  • HTML, PEAR_Size_Output_Html. Print reports in HTML.

  • Text, PEAR_Size_Output_Text. Prints the reports in pure text - no additional formatting.

  • XML, PEAR_Size_Output_XML. Prints the reports in XML.

If these drivers are not adequate for what you require, you should consider writing your own - based on the PEAR_Size_Output_Driver class.

Prev | Getting started | Next
The Command-Line Script | PEAR Manual | Reference guide


Reference guide

Reference guide

Table of Contents
  • Command-Line version
  • Output Drivers
Prev | PEAR_Size | Next
Outputting Results | PEAR Manual | Command-Line version


Command-Line version

Command-Line version

Table of Contents
  • PEAR_Size_CLI::run -- Run the CLI version
Prev | Reference guide | Next
Reference guide | PEAR Manual | PEAR_Size_CLI::run


PEAR_Size_CLI::run

PEAR_Size_CLI::run

PEAR_Size_CLI::run() – Run the CLI version

Synopsis

require_once 'PEAR/Size/CLI.php';

integer PEAR_Size_CLI::run ( )

Description

Invokes PEAR_Size for command line scripts.

Return value

returns an integer

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Command-Line version | Next
Command-Line version | PEAR Manual | Output Drivers


Output Drivers

Output Drivers

Table of Contents
  • Overview -- The How and What of Output Drivers
  • PEAR_Size_OutputFactory::createInstance -- Create an Instance of an output driver.
  • PEAR_Size_Output_Driver::display -- Display specified text
  • PEAR_Size_Driver::generateReport -- Generate Report
  • PEAR_Size_Output_CSV::display -- Display specified text
  • PEAR_Size_Output_CSV::generateReport -- Generate CSV formatted report
  • PEAR_Size_Output_Html::display -- Display specified text
  • PEAR_Size_Output_Html::generateReport -- Generate HTML formatted report
  • PEAR_Size_Output_Text::display -- Display specified text
  • PEAR_Size_Output_Text::generateReport -- Generate plain text formatted report
  • PEAR_Size_Output_XML::display -- Display specified text
  • PEAR_Size_Output_XML::generateReport -- Generate XML formatted report
Prev | Reference guide | Next
PEAR_Size_CLI::run | PEAR Manual | Overview


Overview

Overview

Overview – The How and What of Output Drivers

In brief

Output drivers provide a means of presenting the same information in a variety of formats. The drivers that currently ship with PEAR_Size provide formatting for CVS, HTML, XML and plain text.

Below is an example of creating a driver for XML output:

<?php
$type = 'xml';
//get the factory
$factory = new PEAR_Size_OutputFactory();
//and create the driver...
$driver = $factory->createInstance($type);
?>
Prev | Output Drivers | Next
Output Drivers | PEAR Manual | PEAR_Size_OutputFactory::createInstance


PEAR_Size_OutputFactory::createInstance

PEAR_Size_OutputFactory::createInstance

PEAR_Size_OutputFactory :: createInstance() – Create an Instance of an output driver.

Synopsis

require_once 'PEAR/Size/Factory.php';

integer PEAR_Size_OutputFactory::createInstance ( )

Description

Create an instance of an output driver.

Return value

returns instance of an Output Driver.

Throws

throws an exception if specified driver could not be found.

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
Overview | PEAR Manual | PEAR_Size_Output_Driver::display


PEAR_Size_Output_Driver::display

PEAR_Size_Output_Driver::display

PEAR_Size_Output_Driver::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_Driver::display ( string $text )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

This is a base class and should not be used directly.

Prev | Output Drivers | Next
PEAR_Size_OutputFactory::createInstance | PEAR Manual | PEAR_Size_Driver::generateReport


PEAR_Size_Driver::generateReport

PEAR_Size_Driver::generateReport

PEAR_Size_Driver::generateReport() – Generate Report

Synopsis

void PEAR_Size_Driver::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

This is a base class and should not be used directly.

Prev | Output Drivers | Next
PEAR_Size_Output_Driver::display | PEAR Manual | PEAR_Size_Output_CSV::display


PEAR_Size_Output_CSV::display

PEAR_Size_Output_CSV::display

PEAR_Size_Output_CSV::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_CSV::display ( string $text )

Description

Display text in CSV (comma seperated) format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Driver::generateReport | PEAR Manual | PEAR_Size_Output_CSV::generateReport


PEAR_Size_Output_CSV::generateReport

PEAR_Size_Output_CSV::generateReport

PEAR_Size_Output_CSV::generateReport() – Generate CSV formatted report

Synopsis

void PEAR_Size_Output_CSV::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_CSV::display | PEAR Manual | PEAR_Size_Output_Html::display


PEAR_Size_Output_Html::display

PEAR_Size_Output_Html::display

PEAR_Size_Output_Html::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_Html::display ( string $text )

Description

Display text in HTML format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_CSV::generateReport | PEAR Manual | PEAR_Size_Output_Html::generateReport


PEAR_Size_Output_Html::generateReport

PEAR_Size_Output_Html::generateReport

PEAR_Size_Output_Html::generateReport() – Generate HTML formatted report

Synopsis

void PEAR_Size_Output_Html::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display report in HTML format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_Html::display | PEAR Manual | PEAR_Size_Output_Text::display


PEAR_Size_Output_Text::display

PEAR_Size_Output_Text::display

PEAR_Size_Output_Text::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_Text::display ( string $text )

Description

Display text in Text (comma seperated) format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_Html::generateReport | PEAR Manual | PEAR_Size_Output_Text::generateReport


PEAR_Size_Output_Text::generateReport

PEAR_Size_Output_Text::generateReport

PEAR_Size_Output_Text::generateReport() – Generate plain text formatted report

Synopsis

void PEAR_Size_Output_Text::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_Text::display | PEAR Manual | PEAR_Size_Output_XML::display


PEAR_Size_Output_XML::display

PEAR_Size_Output_XML::display

PEAR_Size_Output_XML::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_XML::display ( string $text )

Description

Display text in XML format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_Text::generateReport | PEAR Manual | PEAR_Size_Output_XML::generateReport


PEAR_Size_Output_XML::generateReport

PEAR_Size_Output_XML::generateReport

PEAR_Size_Output_XML::generateReport() – Generate XML formatted report

Synopsis

void PEAR_Size_Output_XML::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display report in XML.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Prev | Output Drivers | Next
PEAR_Size_Output_XML::display | PEAR Manual | PHP


PHP

PHP

Tools to help your development process.

Table of Contents
  • PHP_Archive
  • phpDocumentor
  • PHP_CodeSniffer
  • PHP_Compat
  • PHP_CompatInfo
  • PHP_FunctionCallTracer
  • PHP_UML
  • PHPUnit
  • PHPUnit2
Prev | PEAR Packages | Next
PEAR_Size_Output_XML::generateReport | PEAR Manual | PHP_Archive


PHP_Archive

PHP_Archive

The PHP_Archive package allows creation of self-contained cross-platform PHP libraries or applications, similar to Java jar files. PHP_Archive

Table of Contents
  • Introduction -- The PHP_Archive package allows creation of self-contained cross-platform PHP libraries or applications, similar to Java jar files.
Prev | PHP | Next
PHP | PEAR Manual | Introduction


Introduction

Introduction

Introduction – The PHP_Archive package allows creation of self-contained cross-platform PHP libraries or applications, similar to Java jar files.

Description

PHP_Archive provides the PHP_Archive class, and the phar:// stream wrapper. Using PHP_Archive, it is possible to create self-contained cross-platform PHP libraries and applications. The file format and principles are identical to the Phar extension, which is documented in the PHP manual. PHP_Archive is used to create go-pear.phar and install-pear-nozlib.phar, distributed with PHP since PHP version 5.1.0, and used to install the PEAR Installer itself.

The PHP_Archive class differs in approach from the Phar class in that it does not support the ArrayAccess interface for accessing internal files, and does not support iteration over contents using foreach(). However, full support for the phar:// stream wrapper, support of Phar-specific metadata setting and retrieval using PHP_Archive::getPharMetaData() and file-specific metadata using PHP_Archive::getFileMetaData(), zlib and bzip2 compression of individual files, and archive-wide SHA1/MD5 signature makes PHP_Archive just as powerful as the Phar extension for distributing phars.

The advanced Phar creation features of PHP_Archive are not yet documented, but information is available at the API documentation, and an example usage is in cvs at make-gopear-phar.php.

External Documentation

  • Phar extension documentation
Prev | PHP_Archive | Next
PHP_Archive | PEAR Manual | phpDocumentor


phpDocumentor

phpDocumentor

The phpDocumentor package provides automatic documenting of php api directly from the source.

Table of Contents
  • Introduction -- The phpDocumentor package provides automatic documenting of PHP code API directly from the source.
Prev | PHP | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – The phpDocumentor package provides automatic documenting of PHP code API directly from the source.

Description

The phpDocumentor tool is a standalone auto-documentor similar to JavaDoc written in PHP. It differs from PHPDoc in that it is MUCH faster, parses a much wider range of PHP files, and comes with many customizations including 11 HTML templates, Windows help file CHM output, PDF output, and XML DocBook output that is compatible with the markup used in this manual. In addition, it can do PHPXref source code highlighting and linking.

External Documentation

  • Documentation Creation Overview
  • Tutorial
  • Manual
  • Above docs in other formats
Prev | phpDocumentor | Next
phpDocumentor | PEAR Manual | PHP_CodeSniffer


PHP_CodeSniffer

PHP_CodeSniffer

PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP, JavaScript and CSS files to detect violations of a defined coding standard. It is an essential development tool that ensures your code remains clean and consistent. It can also help prevent some common semantic errors made by developers.

Table of Contents
  • Introduction -- Description and simple usage example
  • Requirements -- A list of software requirements
  • Usage -- Standard usage information
  • Advanced Usage -- Advanced usage information
  • Reporting -- Report types and options
  • Configuration Options -- A list of configuration options
  • Coding Standard Tutorial -- A guide to writing your own code sniffs
  • Coding Standard Class Methods -- Information about overriding coding standard class methods
  • Using the Subversion pre-commit Hook -- How to configure the Subversion pre-commit hook
  • FAQ -- Frequently asked questions
Prev | PHP | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Description and simple usage example

Description

PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP, JavaScript and CSS files to detect violations of a defined coding standard. It is an essential development tool that ensures your code remains clean and consistent. It can also help prevent some common semantic errors made by developers.

A coding standard in PHP_CodeSniffer is a collection of sniff files. Each sniff file checks one part of the coding standard only. Multiple coding standards can be used within PHP_CodeSniffer so that the one installation can be used across multiple projects. The default coding standard used by PHP_CodeSniffer is the PEAR coding standard.

Example

To check a file against the PEAR coding standard, simply specify the file's location.

Checking a file with PHP_CodeSniffer

$ phpcs /path/to/code/myfile.php

FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AFFECTING 2 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR | Missing file doc comment
 20 | ERROR | PHP keywords must be lowercase; expected "false" but found "FALSE"
 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
 51 | ERROR | Missing function doc comment
 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

Or, if you wish to check an entire directory, you can specify the directory location instead of a file.

Checking a directory with PHP_CodeSniffer

$ phpcs /path/to/code

FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR | Missing file doc comment
 20 | ERROR | PHP keywords must be lowercase; expected "false" but found "FALSE"
 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
 51 | ERROR | Missing function doc comment
 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

FILE: /path/to/code/yourfile.php
--------------------------------------------------------------------------------
FOUND 1 ERROR(S) AND 1 WARNING(S) AFFECTING 1 LINE(S)
--------------------------------------------------------------------------------
 21 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE"
 21 | WARNING | Equals sign not aligned with surrounding assignments
--------------------------------------------------------------------------------

Prev | PHP_CodeSniffer | Next
PHP_CodeSniffer | PEAR Manual | Requirements


Requirements

Requirements

Requirements – A list of software requirements

PHP_CodeSniffer

PHP_CodeSniffer requires PHP version 5.1.2 or greater.

Note: Individual sniffs may have additional requirements, such as external applications and scripts. See the Configuration Options page for a list of these requirements.

SVN pre-commit hook

The pre-commit hook requires PHP version 5.2.4 or greater due to its use of the vertical whitespace character.

Prev | PHP_CodeSniffer | Next
Introduction | PEAR Manual | Usage


Usage

Usage

Usage – Standard usage information

Getting Help from the Command Line

Running PHP_CodeSniffer with the -h or --help command line arguments will print a list of commands that PHP_CodeSniffer will respond to. The output of phpcs -h is shown below.

Usage: phpcs [-nwlsvi] [--report=<report>] [--report-file=<reportfile>]
    [--config-set key value] [--config-delete key] [--config-show]
    [--standard=<standard>] [--sniffs=<sniffs>]
    [--extensions=<extensions>] [--ignore=<patterns>]
    [--generator=<generator>] [--tab-width=<width>] <file> ...
        -n           Do not print warnings
        -w           Print both warnings and errors (on by default)
        -l           Local directory only, no recursion
        -s           Show sniff codes in all reports
        -v[v][v]     Print verbose output
        -i           Show a list of installed coding standards
        --help       Print this help message
        --version    Print version information
        <file>       One or more files and/or directories to check
        <extensions> A comma separated list of file extensions to check
                     (only valid if checking a directory)
        <patterns>   A comma separated list of patterns that are used
                     to ignore directories and files
        <sniffs>     A comma separated list of sniff codes to limit the check to
                     (all sniffs must be part of the specified standard)
        <standard>   The name of the coding standard to use
        <width>      The number of spaces each tab represents
        <generator>  The name of a doc generator to use
                     (forces doc generation instead of checking)
        <report>     Print either the "full", "xml", "checkstyle",
                     "csv", "emacs", "source" or "summary" report
                     (the "full" report is printed by default)
        <reportfile> Write the report to the specified file path
                     (report is also written to screen)
Note: The --standard command line argument is optional, even if you have more than one coding standard installed. If no coding standard is specified, PHP_CodeSniffer will default to checking against the PEAR coding standard, or the standard you have set as the default. View instructions for setting the default coding standard.

Checking Files and Folders

The simplest way of using PHP_CodeSniffer is to provide the location of a file or folder for PHP_CodeSniffer to check. If a folder is provided, PHP_CodeSniffer will check all files it finds in that folder and all its sub-folders.

Note: If you do not want sub-folders checked, use the -l command line argument to force PHP_CodeSniffer to run locally in the folders specified.

In the example below, the first command tells PHP_CodeSniffer to check the myfile.inc file for coding standard errors while the second command tells PHP_CodeSniffer to check all PHP files in the my_dir directory.

Checking a single file or folder

$ phpcs /path/to/code/myfile.inc
$ phpcs /path/to/code/my_dir

You can also specify multiple files and folders to check. The command below tells PHP_CodeSniffer to check the myfile.inc file and all files in the my_dir directory.

Checking multiple files and folders

$ phpcs /path/to/code/myfile.inc /path/to/code/my_dir

After PHP_CodeSniffer has finished processing your files, you will get an error report. The report lists both errors and warnings for all files that violated the coding standard. The output looks like this:

Sample PHP_CodeSniffer output

$ phpcs /path/to/code/myfile.php

FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR   | Missing file doc comment
 20 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE"
 47 | ERROR   | Line not indented correctly; expected 4 spaces but found 1
 47 | WARNING | Equals sign not aligned with surrounding assignments
 51 | ERROR   | Missing function doc comment
 88 | ERROR   | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

If you don't want warnings included in the output, specify the -n command line argument.

Sample PHP_CodeSniffer output with no warnings

$ phpcs -n /path/to/code/myfile.php

FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR | Missing file doc comment
 20 | ERROR | PHP keywords must be lowercase; expected "false" but found "FALSE"
 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
 51 | ERROR | Missing function doc comment
 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

Printing a Summary Report

By default, PHP_CodeSniffer will print a complete list of all errors and warnings it finds. This list can become quite long, especially when checking a large number of files at once. To print a summary report that only shows the number of errors and warnings for each file, use the --report=summary command line argument. The output will look like this:

Sample PHP_CodeSniffer summary output

$ phpcs --report=summary /path/to/code

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE                                                            ERRORS  WARNINGS
--------------------------------------------------------------------------------
/path/to/code/myfile.inc                                        5       0
/path/to/code/yourfile.inc                                      1       1
/path/to/code/ourfile.inc                                       0       2
--------------------------------------------------------------------------------
A TOTAL OF 6 ERROR(S) AND 3 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------

As with the full report, you can suppress the printing of warnings with the -n command line argument.

Sample PHP_CodeSniffer summary output with no warnings

$ phpcs -n --report=summary /path/to/code

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE                                                                      ERRORS
--------------------------------------------------------------------------------
/path/to/code/myfile.inc                                                  5
/path/to/code/yourfile.inc                                                1
--------------------------------------------------------------------------------
A TOTAL OF 6 ERROR(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------

Printing Verbose Output

By default, PHP_CodeSniffer will run quietly, only printing the report of errors and warnings at the end. If you are checking a large number of files, you may have to wait a while to see the report. If you want to know what is happening, you can turn on verbose output.

With verbose output enabled, PHP_CodeSniffer will print the file that it is checking, show you how many tokens and lines the file contains, and let you know how long it took to process. The output will look like this:

Sample PHP_CodeSniffer verbose output

$ phpcs /path/to/code/CodeSniffer -v
Registering sniffs in PEAR standard... DONE (24 sniffs registered)
Processing AbstractDocElement.php [1093 tokens in 303 lines]... DONE in < 1 second (0 errors, 1 warnings)
Processing AbstractParser.php [2360 tokens in 558 lines]... DONE in 2 seconds (0 errors, 1 warnings)
Processing ClassCommentParser.php [923 tokens in 296 lines]... DONE in < 1 second (2 errors, 0 warnings)
Processing CommentElement.php [988 tokens in 218 lines]... DONE in < 1 second (1 error, 5 warnings)
Processing FunctionCommentParser.php [525 tokens in 184 lines]... DONE in 1 second (0 errors, 6 warnings)
Processing File.php [10968 tokens in 1805 lines]... DONE in 5 seconds (0 errors, 5 warnings)
Processing Sniff.php [133 tokens in 94 lines]... DONE in < 1 second (0 errors, 0 warnings)
Processing SniffException.php [47 tokens in 36 lines]... DONE in < 1 second (1 errors, 3 warnings)

Specifying a Coding Standard

PHP_CodeSniffer can have multiple coding standards installed to allow a single installation to be used with multiple projects. When checking PHP code, PHP_CodeSniffer can be told which coding standard to use. This is done using the --standard command line argument.

The example below checks the myfile.inc file for violations of the PEAR coding standard (installed by default).

Specifying a coding standard to use

$ phpcs --standard=PEAR /path/to/code/myfile.inc
Note: Can you also tell PHP_CodeSniffer to use an external standard by specifying the full path to the standard's root directory on the command line. An external standard is one that is stored outside of PHP_CodeSniffer's Standards directory.

Specifying an external coding standard

$ phpcs --standard=/path/to/MyStandard /path/to/code/myfile.inc

Printing a List of Installed Coding Standards

PHP_CodeSniffer can print you a list of the coding standards that are installed so that you can correctly specify a coding standard to use for testing. You can print this list by specifying the -i command line argument.

Generating a list of installed coding standards

$ phpcs -i
The installed coding standards are Zend, PEAR, PHPCS, Squiz and MySource

Prev | PHP_CodeSniffer | Next
Requirements | PEAR Manual | Advanced Usage


Advanced Usage

Advanced Usage

Advanced Usage – Advanced usage information

Specifying Valid File Extensions

By default, PHP_CodeSniffer will check any file it finds with a .inc or .php extension. Sometimes, this means that PHP_CodeSniffer is not checking enough of your files. Sometimes, the opposite is true. PHP_CodeSniffer allows you to specify a list of valid file extensions using the --extensions command line argument. Extensions are separated by commas.

Checking .php files only

$ phpcs --extensions=php /path/to/code

Checking .php, .inc and .lib files only

$ phpcs --extensions=php,inc,lib /path/to/code
Note: If you have asked PHP_CodeSniffer to check a specific file rather than an entire directory, the extension of the specified file will be ignored. The file will be checked even if it has an invalid extension or no extension at all. In the following example, the main.inc file will be checked by PHP_CodeSniffer even though the --extensions command line argument specifies that only .php files should be checked.

Extension ignored when checking specific file

$ phpcs --extensions=php /path/to/code/main.inc
Note: The ignoring of file extensions for specific files is a feature of PHP_CodeSniffer and is the only way to check files without an extension. If you check an entire directory of files, all files without extensions will be ignored, so you must check each of these file separately.

Ignoring Files and Folders

Sometimes you want PHP_CodeSniffer to run over a very large number of files, but you want some files and folders to be skipped. The --ignore command line argument can be used to tell PHP_CodeSniffer to skip files and folders that match one or more patterns.

In the following example, PHP_CodeSniffer will skip all files inside the package's tests and data directories. This is useful if you are checking a PEAR package but don't want your test or data files to conform to your coding standard.

Ignoring test and data files

$ phpcs --ignore=*/tests/*,*/data/* /path/to/code

Limiting Results to Specific Sniffs

By default, PHP_CodeSniffer will ceck your code using all sniffs in the specified standard. Sometimes you may want to find all occcurances of an error to eliminate it more quickly or understand the scope of the problem. PHP_CodeSniffer allows you to specify a list of sniffs to limit results to using the --sniffs command line argument. Sniffs are separated by commas.

Checking files for two specific sniffs only

$ phpcs --sniffs=Generic.PHP.LowerCaseConstant,PEAR.WhiteSpace.ScopeIndent /path/to/code
Note: To view source codes for error messages, use the -s command line argument. This will print source codes in the full, summary and source reports.

Replacing Tabs with Spaces

Most of the sniffs written for PHP_CodeSniffer do not support the usage of tabs for indentation and alignment. You can write your own sniffs that check for tabs instead of spaces, but you can also get PHP_CodeSniffer to convert your tabs into spaces before a file is checked. This allows you to use the existing space-based sniffs on your tab-based files.

In the following example, PHP_CodeSniffer will replace all tabs in the files being checked with between 1 and 4 spaces, depending on the column the tab indents to.

Converting tabs to spaces

$ phpcs --tab-width=4 /path/to/code

Setting Configuration Options

PHP_CodeSniffer has some configuration options that can be set. Individual coding standards may also require configuration options to be set before functionality can be used. View a full list of configuration options.

To set a configuration option, use the --config-set command line argument.

Setting a configuration option

$ phpcs --config-set <option> <value>

Deleting Configuration Options

PHP_CodeSniffer allows you to delete any configuration option, reverting it to its default value. View a full list of configuration options.

To delete a configuration option, use the --config-delete command line argument.

Deleting a configuration option

$ phpcs --config-delete <option>

Viewing Configuration Options

To view the currently set configuration options, use the --config-show command line argument.

Viewing configuration options

$ phpcs --config-show
Array
(
    [default_standard] => PEAR
    [zend_ca_path] => /path/to/ZendCodeAnalyzer
)

Printing Verbose Tokeniser Output

Note: This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time.

PHP_CodeSniffer contains multiple verbosity levels. Level 2 (indicated by the command line argument -vv) will print all verbosity information for level 1 (file specific token and line counts with running times) as well as verbose tokeniser output.

The output of the PHP_CodeSniffer tokeniser shows the step-by-step creation of the scope map and the level map.

The Scope Map

The scope map is best explained with an example. For the following file:

<?php
if ($condition) {
    echo 'Condition was true';
}
?>

The scope map output is:

Sample scope map output

*** START SCOPE MAP ***
Start scope map at 1: T_IF => if
Process token 2 []: T_WHITESPACE =>
Process token 3 []: T_OPEN_PARENTHESIS => (
Process token 6 []: T_WHITESPACE =>
Process token 7 []: T_OPEN_CURLY_BRACKET => {
=> Found scope opener for 1 (T_IF)
Process token 8 [opener:7;]: T_WHITESPACE => \n
Process token 9 [opener:7;]: T_WHITESPACE =>
Process token 10 [opener:7;]: T_ECHO => echo
Process token 11 [opener:7;]: T_WHITESPACE =>
Process token 12 [opener:7;]: T_CONSTANT_ENCAPSED_STRING => 'Condition was true'
Process token 13 [opener:7;]: T_SEMICOLON => ;
Process token 14 [opener:7;]: T_WHITESPACE => \n
Process token 15 [opener:7;]: T_CLOSE_CURLY_BRACKET => }
=> Found scope closer for 1 (T_IF)
*** END SCOPE MAP ***

The scope map output above shows the following pieces of information about the file:

  • A scope token, if, was found at token 1 (note that token 0 is the open PHP tag).

  • The opener for the if statement, the open curly brace, was found at token 7.

  • The closer for the if statement, the close curly brace, was found at token 15.

  • Tokens 8 - 15 are all included in the scope set by the scope opener at token 7, the open curly brace. This indicates that these tokens are all within the if statement.

The scope map output is most useful when debugging PHP_CodeSniffer's scope map, which is critically important to the successful checking of a file, but is also useful for checking the type of a particular token. For example, if you are unsure of the token type for an opening curly brace, the scope map output shows you that the type is T_OPEN_CURLY_BRACKET and not, for example, T_OPEN_CURLY_BRACE.

The Level Map

The level map is best explained with an example. For the following file:

<?php
if ($condition) {
    echo 'Condition was true';
}
?>

The level map output is:

Sample level map output

 *** START LEVEL MAP ***
Process token 0 on line 1 [lvl:0;]: T_OPEN_TAG => <?php\n
Process token 1 on line 2 [lvl:0;]: T_IF => if
Process token 2 on line 2 [lvl:0;]: T_WHITESPACE =>
Process token 3 on line 2 [lvl:0;]: T_OPEN_PARENTHESIS => (
Process token 4 on line 2 [lvl:0;]: T_VARIABLE => $condition
Process token 5 on line 2 [lvl:0;]: T_CLOSE_PARENTHESIS => )
Process token 6 on line 2 [lvl:0;]: T_WHITESPACE =>
Process token 7 on line 2 [lvl:0;]: T_OPEN_CURLY_BRACKET => {
=> Found scope opener for 1 (T_IF)
    * level increased *
    * token 1 (T_IF) added to conditions array *
    Process token 8 on line 2 [lvl:1;conds;T_IF;]: T_WHITESPACE => \n
    Process token 9 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE =>
    Process token 10 on line 3 [lvl:1;conds;T_IF;]: T_ECHO => echo
    Process token 11 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE =>
    Process token 12 on line 3 [lvl:1;conds;T_IF;]: T_CONSTANT_ENCAPSED_STRING => 'Condition was true'
    Process token 13 on line 3 [lvl:1;conds;T_IF;]: T_SEMICOLON => ;
    Process token 14 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE => \n
    Process token 15 on line 4 [lvl:1;conds;T_IF;]: T_CLOSE_CURLY_BRACKET => }
    => Found scope closer for 7 (T_OPEN_CURLY_BRACKET)
    * token T_IF removed from conditions array *
    * level decreased *
Process token 16 on line 4 [lvl:0;]: T_WHITESPACE => \n
Process token 17 on line 5 [lvl:0;]: T_CLOSE_TAG => ?>\n
*** END LEVEL MAP ***

The level map output above shows the following pieces of information about the file:

  • A scope opener, an open curly brace, was found at token 7 and opened the scope for an if statement, defined at token 1.

  • Tokens 8 - 15 are all included in the scope set by the scope opener at token 7, the open curly brace. All these tokens are at level 1, indicating that they are enclosed in 1 scope condition, and all these tokens are enclosed in a single condition; an if statement.

The level map is most commonly used to determine indentation rules (eg. a token 4 levels deep requires 16 spaces of indentation) or to determine if a particular token is within a particular scope (eg. a function keyword is within a class scope, making it a method).

Printing Verbose Token Processing Output

Note: This feature is provided for debugging purposes only. Using this feature will dramatically increase screen output and script running time.

PHP_CodeSniffer contains multiple verbosity levels. Level 3 (indicated by the command line argument -vvv) will print all verbosity information for level 1 (file specific token and line counts with running times), level 2 (tokeniser output) as well as token processing output with sniff running times.

The token processing output is best explained with an example. For the following file:

<?php
if ($condition) {
    echo 'Condition was true';
}
?>

The token processing output is:

Sample token processing output

*** START TOKEN PROCESSING ***
Process token 0: T_OPEN_TAG => <?php\n
    Processing PEAR_Sniffs_Commenting_FileCommentSniff... DONE in 0.001 seconds
    Processing PEAR_Sniffs_Files_LineLengthSniff... DONE in 0.0004 seconds
    Processing PEAR_Sniffs_PHP_DisallowShortOpenTagSniff... DONE in 0.0001 seconds
Process token 1: T_IF => if
    Processing PEAR_Sniffs_ControlStructures_ControlSignatureSniff... DONE in 0.0008 seconds
    Processing PEAR_Sniffs_WhiteSpace_ScopeClosingBraceSniff... DONE in 0.0248 seconds
    Processing PEAR_Sniffs_WhiteSpace_ScopeIndentSniff... DONE in 0.0004 seconds
Process token 2: T_WHITESPACE =>
Process token 3: T_OPEN_PARENTHESIS => (
Process token 4: T_VARIABLE => $condition
Process token 5: T_CLOSE_PARENTHESIS => )
Process token 6: T_WHITESPACE =>
Process token 7: T_OPEN_CURLY_BRACKET => {
Process token 8: T_WHITESPACE => \n
Process token 9: T_WHITESPACE =>
Process token 10: T_ECHO => echo
Process token 11: T_WHITESPACE =>
Process token 12: T_CONSTANT_ENCAPSED_STRING => 'Condition was true'
Process token 13: T_SEMICOLON => ;
Process token 14: T_WHITESPACE => \n
Process token 15: T_CLOSE_CURLY_BRACKET => }
Process token 16: T_WHITESPACE => \n
Process token 17: T_CLOSE_TAG => ?>\n
*** END TOKEN PROCESSING ***

Every token processed is shown, along with its ID, type and contents. For each token, all sniffs that were executed on the token are displayed, along with the running time.

For example, the output above shows us that token 1, an if keyword, had 3 sniffs executed on it; the ControlSignature sniff, the ScopeClosingBrace sniff and the ScopeIndent sniff. Each was executed fairly quickly, but the slowest was the ScopeClosingBrace sniff, taking 0.0248 seconds to process that token.

The other interesting piece of information we get from the output above is that only 2 tokens in the whole file had sniffs executed on them; tokens 0 and 1. This is normal behavior for PHP_CodeSniffer as most sniffs listen for a very specific and rarely used token and then execute on it and a number of tokens following it.

For example, the ScopeIndentSniff executes on the if statement's token only, but actually checks the indentation of every line within the if statement. The sniff uses the scope map to find all tokens within the if statement.

Prev | PHP_CodeSniffer | Next
Usage | PEAR Manual | Reporting


Reporting

Reporting

Reporting – Report types and options

Printing Full and Summary Reports

Note: See the main Usage page for basic usage information about these report types, including example output.

Both the full and summary reports can additionally show information about the source of errors and warnings. Source codes can be used with the --sniffs command line argument to only show messages from a specified list of sources. To include source codes in the report, use the -s command line argument.

Sample PHP_CodeSniffer full report with source codes

$ phpcs -s /path/to/code/myfile.php

FILE: /path/to/code/myfile.php
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR   | Missing file doc comment (PEAR.Commenting.FileComment)
 20 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE" (Generic.PHP.LowerCaseConstant)
 47 | ERROR   | Line not indented correctly; expected 4 spaces but found 1
    |         | (PEAR.WhiteSpace.ScopeIndent)
 47 | WARNING | Equals sign not aligned with surrounding assignments
    |         | (Generic.Formatting.MultipleStatementAlignment)
 51 | ERROR   | Missing function doc comment
    |         | (PEAR.Commenting.FunctionComment)
 88 | ERROR   | Line not indented correctly; expected 9 spaces but found 6
    |         | (PEAR.WhiteSpace.ScopeIndent)
--------------------------------------------------------------------------------

Sample PHP_CodeSniffer summary report with source codes

$ phpcs -s --report=summary /path/to/code

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE                                                            ERRORS  WARNINGS
--------------------------------------------------------------------------------
/path/to/code/myfile.inc                                        5       0
/path/to/code/yourfile.inc                                      1       1
/path/to/code/ourfile.inc                                       0       2
--------------------------------------------------------------------------------
A TOTAL OF 6 ERROR(S) AND 3 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------

PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
SOURCE                                                                     COUNT
--------------------------------------------------------------------------------
PEAR.WhiteSpace.ScopeIndent                                                3
PEAR.Commenting.FileComment                                                2
Generic.PHP.LowerCaseConstant                                              2
Generic.Formatting.MultipleStatementAlignment                              1
PEAR.Commenting.FunctionComment                                            1
--------------------------------------------------------------------------------
A TOTAL OF 9 SNIFF VIOLATION(S) WERE FOUND IN 5 SOURCE(S)
--------------------------------------------------------------------------------

Printing a Source Report

PHP_CodeSniffer can output a summary report showing you the most common errors detected in your files so you can target specific parts of your coding standard for improvement. To print a source report, use the --report=source command line argument. The output will look like this:

Sample PHP_CodeSniffer source output

$ phpcs --report=source /path/to/code

PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
STANDARD    CATEGORY            SNIFF                                      COUNT
--------------------------------------------------------------------------------
Generic     PHP                 Lower case constant                        4
PEAR        White space         Scope indent                               3
PEAR        Commenting          File comment                               1
--------------------------------------------------------------------------------
A TOTAL OF 8 SNIFF VIOLATION(S) WERE FOUND IN 3 SOURCE(S)
--------------------------------------------------------------------------------

To show source codes instead of friendly names, use the -s command line argument.

Sample PHP_CodeSniffer source code output

$ phpcs -s --report=source /path/to/code

PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
SOURCE                                                                     COUNT
--------------------------------------------------------------------------------
Generic.PHP.LowerCaseConstant                                              4
PEAR.WhiteSpace.ScopeIndent                                                3
PEAR.Commenting.FileComment                                                1
--------------------------------------------------------------------------------
A TOTAL OF 8 SNIFF VIOLATION(S) WERE FOUND IN 3 SOURCE(S)
--------------------------------------------------------------------------------

Printing an XML Report

PHP_CodeSniffer can output an XML report to allow you to parse the output easily and use the results in your own scripts. To print an XML report, use the --report=xml command line argument. The output will look like this:

Sample PHP_CodeSniffer XML output

$ phpcs --report=xml /path/to/code

<?xml version="1.0" encoding="UTF-8"?>
<phpcs version="1.0.0">
 <file name="/path/to/code/myfile.php" errors="4" warnings="1">
  <error line="2" column="1" source="PEAR.Commenting.FileComment">Missing file doc comment</error>
  <error line="20" column="43" source="Generic.PHP.LowerCaseConstant">PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;</error>
  <error line="47" column="1" source="PEAR.WhiteSpace.ScopeIndent">Line not indented correctly; expected 4 spaces but found 1</error>
  <warning line="47" column="20" source="Generic.Formatting.MultipleStatementAlignment">Equals sign not aligned with surrounding assignments</warning>
  <error line="51" column="4" source="PEAR.Commenting.FunctionComment">Missing function doc comment</error>
 </file>
</phpcs>

Printing a Checkstyle Report

PHP_CodeSniffer can output an XML report similar to the one produced by Checkstyle, allowing you to use the output in scripts and applications that already support Checkstyle. To print a Checkstyle report, use the --report=checkstyle command line argument. The output will look like this:

Sample PHP_CodeSniffer Checkstyle output

$ phpcs --report=checkstyle /path/to/code

<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
 <file name="/path/to/code/myfile.php">
  <error line="2" column="1" severity="error" message="Missing file doc comment" source="PEAR.Commenting.FileComment"/>
  <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;" source="Generic.PHP.LowerCaseConstant"/>
  <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1" source="PEAR.WhiteSpace.ScopeIndent"/>
  <error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments" source="Generic.Formatting.MultipleStatementAlignment"/>
  <error line="51" column="4" severity="error" message="Missing function doc comment" source="PEAR.Commenting.FunctionComment"/>
 </file>
</checkstyle>

Printing a CSV Report

PHP_CodeSniffer can output a CSV report to allow you to parse the output easily and use the results in your own scripts. To print a CSV report, use the --report=csv command line argument. The output will look like this:

Sample PHP_CodeSniffer CSV output

$ phpcs --report=csv /path/to/code

File,Line,Column,Severity,Message,Source
"/path/to/code/myfile.php",2,1,error,"Missing file doc comment",PEAR.Commenting.FileComment
"/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\"",Generic.PHP.LowerCaseConstant
"/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1",PEAR.WhiteSpace.ScopeIndent
"/path/to/code/myfile.php",47,20,warning,"Equals sign not aligned with surrounding assignments",Generic.Formatting.MultipleStatementAlignment
"/path/to/code/myfile.php",51,4,error,"Missing function doc comment",PEAR.Commenting.FunctionComment
Note: The first row of the CSV output defines the order of information. When using the CSV output, please parse this header row to determine the order correctly as the format may change over time or new information may be added.

Printing an Emacs Report

PHP_CodeSniffer can output a report in a format the compiler built into the GNU Emacs text editor can understand. This lets you use the built-in complier to run PHP_CodeSniffer on a file you are editing and navigate between errors and warnings within the file. To print an Emacs report, use the --report=emacs command line argument. The output will look like this:

Sample PHP_CodeSniffer Emacs output

$ phpcs --report=emacs /path/to/code

/path/to/code/myfile.php:2:1: error - Missing file doc comment
/path/to/code/myfile.php:20:43: error - PHP keywords must be lowercase; expected "false" but found "FALSE"
/path/to/code/myfile.php:47:1: error - Line not indented correctly; expected 4 spaces but found 1
/path/to/code/myfile.php:47:20: warning - Equals sign not aligned with surrounding assignments
/path/to/code/myfile.php:51:4: error - Missing function doc comment

To use PHP_CodeSniffer with Emacs, make sure you have installed PHP mode for Emacs. Then put the following into your .emacs file, changing PHP_CodeSniffer options as required.

Sample .emacs file

(defun my-php-hook-function ()
 (set (make-local-variable 'compile-command) (format "phpcs --report=emacs --standard=PEAR %s" (buffer-file-name))))
(add-hook 'php-mode-hook 'my-php-hook-function)

Now you can use the compile command and associated shortcuts to move between error messages within your file.

Writing a Report to a File

PHP_CodeSniffer always prints the specified report to the screen, but it can also be told to write a copy of the report to a file. When writing to a file, all internal parsing errors and verbose output PHP_CodeSniffer produces will not be included in the file. This feature is particularly useful when using report types such as XML and CSV that are often parsed by scripts or used with continuous integration software.

To write a copy of a report to a file, use the --report-file command line argument. Note that a copy of the report will also be written to the screen.

Writing a report to a file

$ phpcs --report=xml --report-file=/path/to/file.xml /path/to/code

Prev | PHP_CodeSniffer | Next
Advanced Usage | PEAR Manual | Configuration Options


Configuration Options

Configuration Options

Configuration Options – A list of configuration options

PHP_CodeSniffer Configuration Options

Setting the Default Coding Standard

By default, PHP_CodeSniffer will use the PEAR coding standard if no standard is supplied on the command line. You can change the default standard by setting the default_standard configuration option.

Setting the default standard to be the Zend coding standard

$ phpcs --config-set default_standard Zend

Setting the Default Report Format

By default, PHP_CodeSniffer will use the full report format if no format is supplied on the command line. You can change the default report format by setting the report_format configuration option.

Setting the default report format to be the summary report

$ phpcs --config-set report_format summary

Hiding Warnings by Default

By default, PHP_CodeSniffer will show both errors and warnings for your code. You can hide warnings for a single script run by using the -n command line argument, but you can also enable this by default if you prefer. To hide warnings by default, set the show_warnings configuration option to 0.

Hiding warnings by default

$ phpcs --config-set show_warnings 0
Note: When warnings are hidden by default, you can use the -w command line argument to show them for a single script run.

Setting the Default Tab Width

By default, PHP_CodeSniffer will not convert tabs to spaces in checked files. Specifying a tab width will make PHP_CodeSniffer replace tabs with spaces. You can force PHP_CodeSniffer to replace tabs with spaces by default by setting the tab_width configuration option.

Setting the default tab width to be 4 spaces

$ phpcs --config-set tab_width 4
Note: When the tab width is set by default, the replacement of tabs with spaces can be disabled for a single script run by setting the tab width to zero.

Disabling the replacement of tabs with spaces

$ phpcs --tab-width=0 /path/to/code

Squiz Coding Standard Configuration Options

Setting the Path to JSLint

The Squiz coding standard includes a sniff that will check each JavaScript file using JSLint, a JavaScript program that looks for problems in JavaScript programs. Use the jslint_path configuration option to tell the JSLint sniff where to find the tool.

Setting the path to JSLint

$ phpcs --config-set jslint_path /path/to/jslint.js

As JSLint is just JavaScript code, you also need to install Rhino to be able to execute it. Use the rhino_path configuration option to tell the JSLint sniff where to find the tool.

Setting the path to Rhino

$ phpcs --config-set rhino_path /path/to/rhino

Setting the Path to JavaScript Lint

The Squiz coding standard includes a sniff that will check each JavaScript file using JavaScript Lint, a tool that checks all your JavaScript source code for common mistakes without actually running the script or opening the web page. Use the jsl_path configuration option to tell the JavaScript Lint sniff where to find the tool.

Setting the path to JavaScript Lint

$ phpcs --config-set jsl_path /path/to/jsl

Zend Coding Standard Configuration Options

Setting the Path to the Zend Code Analyzer

The Zend coding standard includes a sniff that will check each file using the Zend Code Analyzer, a tool that comes with Zend Studio. Use the zend_ca_path configuration option to tell the Zend Code Analyzer sniff where to find the tool.

Setting the path to the Zend Code Analyzer

$ phpcs --config-set zend_ca_path /path/to/ZendCodeAnalyzer

Prev | PHP_CodeSniffer | Next
Reporting | PEAR Manual | Coding Standard Tutorial


Coding Standard Tutorial

Coding Standard Tutorial

Coding Standard Tutorial – A guide to writing your own code sniffs

Introduction

In this tutorial, we will create a new coding standard with a single sniff. Our sniff will prohibit the use of Perl style hash comments.

Creating the Coding Standard Directory

All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a single class, so we can create one very easily. Let's call our coding standard MyStandard. Run the following commands to create the coding standard directory structure:

$ mkdir MyStandard
$ mkdir MyStandard/Sniffs
Note: As this coding standard directory sits outside the main PHP_CodeSniffer directory structure, PHP_CodeSniffer will not show it as an installed standard when using the -i command line argument. If you want your standard to be shown as installed, create the MyStandard directory inside the PHP_CodeSniffer install:

$ cd /path/to/PHP_CodeSniffer/CodeSniffer/Standards
$ mkdir MyStandard
$ mkdir MyStandard/Sniffs

The MyStandard directory represents our coding standard. The Sniffs sub-directory is used to store all the sniff files for this coding standard.

Now that our directory structure is created, we need to add our class file. This file will allow PHP_CodeSniffer to ask our coding standard for information about itself, and also identify this directory as one that contains code sniffs.

$ cd MyStandard
$ touch MyStandardCodingStandard.php

The content of the MyStandardCodingStandard.php file should be the following:

<?php
/**
 * MyStandard Coding Standard.
 *
 * PHP version 5
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Your Name <you@domain.net>
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   CVS: $Id: coding-standard-tutorial.xml,v 1.9 2008/10/09 15:16:47 cweiske Exp $
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

if (class_exists('PHP_CodeSniffer_Standards_CodingStandard', true) === false) {
    throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_Standards_CodingStandard not found');
}

/**
 * MyStandard Coding Standard.
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Your Name <you@domain.net>
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class PHP_CodeSniffer_Standards_MyStandard_MyStandardCodingStandard extends PHP_CodeSniffer_Standards_CodingStandard
{

}//end class
?>
Note: The coding standard class can be left empty, as it is in this example coding standard. For information about the methods that can be overridden, see the coding standard class documentation.

Creating the Sniff

A sniff requires a single PHP file. It's name should clearly describe the standard that we are enforcing and must end with Sniff.php. For our sniff, we will name the PHP file DisallowHashCommentsSniff.php and place it into a Commenting sub-directory to categorise this sniff as relating to commenting. Run the following commands to create the category and the sniff:

$ cd Sniffs
$ mkdir Commenting
$ touch Commenting/DisallowHashCommentsSniff.php
Note: It does not matter what sub-directories you use for categorising your sniffs. Just make them descriptive enough so you can find your sniffs again later when you want to modify them.

Each sniff must implement the PHP_CodeSniffer_Sniff interface so that PHP_CodeSniffer knows that it should instantiate the sniff once it's invoked. The PHP_CodeSniffer_Sniff interface defines two methods that must be implemented; register() and process().

The register() and process() Methods

The register() method allows a sniff to subscribe to one or more token types that it wants to process. Once PHP_CodeSniffer encounters one of those tokens, it calls the process() method with the PHP_CodeSniffer_File object (a representation of the current file being checked) and the position in the stack where the token was found.

For our sniff, we are interested in single line comments. The token_get_all() method that PHP_CodeSniffer uses to acquire the tokens within a file distinguishes doc comments and normal comments as two separate token types. Therefore, we don't have to worry about doc comments interfering with our test. The register() method only needs to return one token type, T_COMMENT.

The Token Stack

A sniff can gather more information about a token by acquiring the token stack with a call to the getTokens() method on the PHP_CodeSniffer_File object. This method returns an array, and is indexed by the position where the token occurs in the token stack. Each element in the array represents a token. All tokens have a code, type and a content index in their array. The code value is a unique integer for the type of token. The type value is a string representation of the token (e.g., 'T_COMMENT' for comment tokens). The type has a corresponding globally defined integer with the same name. Finally, the content value contains the content of the token as it appears in the code.

Note: Some tokens have more indexes than those described above. Have a look in the PHP/CodeSniffer/File.php class comment for a full list of token indexes.

Reporting Errors

Once an error is detected, a sniff should indicate that an error has occurred by calling the addError() method on the PHP_CodeSniffer_File object, passing in an appropriate error message as the first argument and the position in the stack where the error was detected as the second. Alternatively, if the violation is considered not as critical as an error, the addWarning() method can be used.

DisallowHashCommentsSniff.php

We now have to write the content of our sniff. The content of the DisallowHashCommentsSniff.php file should be the following:

<?php
/**
 * This sniff prohibits the use of Perl style hash comments.
 *
 * PHP version 5
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Your Name <you@domain.net>
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   CVS: $Id: coding-standard-tutorial.xml,v 1.9 2008/10/09 15:16:47 cweiske Exp $
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

/**
 * This sniff prohibits the use of Perl style hash comments.
 *
 * An example of a hash comment is:
 *
 * <code>
 *  # This is a hash comment, which is prohibited.
 *  $hello = 'hello';
 * </code>
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Your Name <you@domain.net>
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class MyStandard_Sniffs_Commenting_DisallowHashCommentsSniff implements PHP_CodeSniffer_Sniff
{

    /**
     * Returns the token types that this sniff is interested in.
     *
     * @return array(int)
     */
    public function register()
    {
        return array(T_COMMENT);

    }//end register()

    /**
     * Processes the tokens that this sniff is interested in.
     *
     * @param PHP_CodeSniffer_File $phpcsFile The file where the token was found.
     * @param int                  $stackPtr  The position in the stack where
     *                                        the token was found.
     *
     * @return void
     */
    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
    {
        $tokens = $phpcsFile->getTokens();
        if ($tokens[$stackPtr]['content']{0} === '#') {
            $error = 'Hash comments are prohibited';
            $phpcsFile->addError($error, $stackPtr);
        }

    }//end process()

}//end class

?>
Note: By default, PHP_CodeSniffer assumes all sniffs are designed to check PHP code only. You can specify a list of tokenizers that your sniff supports, allowing it to be used on PHP code, JavaScript code, or both. You do this by setting the $supportedTokenizers member variable in your sniff. Adding the following code to your sniff will tell PHP_CodeSniffer that it can be used to check both PHP and JavaScript code:
<?php
/**
 * A list of tokenizers this sniff supports.
 *
 * @var array
 */
public $supportedTokenizers = array(
                               'PHP',
                               'JS',
                              );
?>

Results

Now that we have defined a coding standard, let's validate a file that contains hash comments.

The test file we are using has the following contents:

<?php

# Check for valid contents.
if ($obj->contentsAreValid($array)) {
    $value = $obj->getValue();

    # Value needs to be an array.
    if (is_array($value) === false) {
        # Error.
        $obj->throwError();
        exit();
    }
}

?>

When PHP_CodeSniffer is run on the file using our new coding standard, 3 errors will be reported:

$ phpcs --standard=/path/to/MyStandard Test.php

FILE: Test.php
--------------------------------------------------------------------------------
FOUND 3 ERROR(S) AND 1 WARNING(S) AFFECTING 3 LINE(S)
--------------------------------------------------------------------------------
 3 | ERROR | Hash comments are prohibited
 7 | ERROR | Hash comments are prohibited
 9 | ERROR | Hash comments are prohibited
--------------------------------------------------------------------------------
Note: Note that we pass the absolute path to our coding standard directory on the command line because our standard is not installed inside the main PHP_CodeSniffer directory structure. If you have created your standard inside PHP_CodeSniffer, you can simply pass the name of the standard:

$ phpcs --standard=MyStandard Test.php

Prev | PHP_CodeSniffer | Next
Configuration Options | PEAR Manual | Coding Standard Class Methods


Coding Standard Class Methods

Coding Standard Class Methods

Coding Standard Class Methods – Information about overriding coding standard class methods

Introduction

Every coding standard contains a class file. This file allows PHP_CodeSniffer to ask a coding standard for information about itself, and also identify a directory as one that contains code sniffs. This guide describes each of the coding standard class methods that can be overridden to provide additional information about your coding standard to PHP_CodeSniffer.

The getIncludedSniffs() Method

This method allows you to tell PHP_CodeSniffer that, besides the code sniffs you have defined in your Sniffs directory, you want to include code sniffs from other coding standards. You can include single code sniffs, whole directories of code sniffs, or an entire coding standard.

The example below includes the MultipleStatementAlignment sniff from the Generic coding standard, all code sniffs in the Functions category of the Generic coding standard, and all code sniffs defined in the PEAR coding standard.

<?php
/**
 * Return a list of external sniffs to include with this standard.
 *
 * The MyStandard coding standard uses some generic sniffs, and
 * the entire PEAR coding standard.
 *
 * @return array
 */
public function getIncludedSniffs()
{
    return array(
            'PEAR',
            'Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php',
            'Generic/Sniffs/Functions',
           );

}//end getIncludedSniffs()
?>
Note: When including an entire coding standard, you will also include any code sniffs that the standard includes from other coding standards. For example, the PEAR coding standard includes some code sniffs from the Generic coding standard, so including the entire PEAR coding standard will also include those code sniffs. This is a quick and easy way to create your own coding standard based on an existing one.

The getExcludedSniffs() Method

This method allows you to tell PHP_CodeSniffer to exclude code sniffs from your own standard or any other standard you are including using the getIncludedSniffs() method. You can exclude single code sniffs, whole directories of code sniffs, or an entire coding standard.

The example below includes the whole PEAR coding standard, except for the ControlSignature sniff.

<?php
/**
 * Return a list of external sniffs to include with this standard.
 *
 * The MyStandard coding standard uses all PEAR sniffs except one.
 *
 * @return array
 */
public function getIncludedSniffs()
{
    return array(
            'PEAR',
           );

}//end getIncludedSniffs()

/**
 * Return a list of external sniffs to exclude from this standard.
 *
 * The MyStandard coding standard uses all PEAR sniffs except one.
 *
 * @return array
 */
public function getExcludedSniffs()
{
    return array(
            'PEAR/Sniffs/ControlStructures/ControlSignatureSniff.php',
           );

}//end getExcludedSniffs()
?>
Prev | PHP_CodeSniffer | Next
Coding Standard Tutorial | PEAR Manual | Using the Subversion pre-commit Hook


Using the Subversion pre-commit Hook

Using the Subversion pre-commit Hook

Using the Subversion pre-commit Hook – How to configure the Subversion pre-commit hook

What Does the Subversion pre-commit Hook Do?

Note: The SVN pre-commit hook has different requirements than the main PHP_CodeSniffer package. See the Requirements page for more information.

A pre-commit hook is a feature available in the Subversion version control system that allows code to be validated before it is committed to the repository. The PHP_CodeSniffer pre-commit hook allows you to check code for coding standard errors and stop the commit process if errors are found. This ensures developers are not able to commit code that violates your coding standard. Instead, they are presented with the list of errors they need to correct before committing.

Sample pre-commit output

$ svn commit -m "Test" temp.php
Sending        temp.php
Transmitting file data .svn: Commit failed (details follow):
svn: 'pre-commit' hook failed with error output:

FILE: temp.php
---------------------------------------------------------------
FOUND 1 ERROR(S) AND 0 WARNING(S) AFFECTING 1 LINE(S)
---------------------------------------------------------------
 2 | ERROR | Missing file doc comment
--------------------------------------------------------------

Configuring the pre-commit Hook

Edit /path/to/PHP_CodeSniffer/scripts/phpcs-svn-pre-commit and replace @php_bin@ in the first line with the path to the PHP CLI. For example, #!@php_bin@ becomes #!/usr/bin/php.

Now ensure the path to svnlook is correct by modifying the following line, if required:

Changing the path to svnlook

define('PHP_CODESNIFFER_SVNLOOK', '/usr/bin/svnlook');

Now add the following line to your pre-commit file in the Subversion hooks directory:

Adding the pre-commit hook to the Subversion config file

/path/to/PHP_CodeSniffer/scripts/phpcs-svn-pre-commit "$REPOS" -t "$TXN" >&2 || exit 1

You can also use all the standard phpcs command line options to do things like set the standard to use, the tab width and the error report format:

Adding the pre-commit hook to the Subversion config file

/path/to/PHP_CodeSniffer/scripts/phpcs-svn-pre-commit --standard=Squiz --tab-width=4 "$REPOS" -t "$TXN" >&2 || exit 1

Prev | PHP_CodeSniffer | Next
Coding Standard Class Methods | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Frequently asked questions

Does PHP_CodeSniffer perform any code coverage or unit testing?

No. PHP_CodeSniffer is not a tool for testing that your PHP application works correctly. All PHP_CodeSniffer will do is ensure your PHP code meets the standards that you are following.

My code is fine! Why do I need PHP_CodeSniffer?

Maybe you don't, but if you want to ensure you adhere to a set of coding standards, PHP_CodeSniffer is a quick and easy way to do that. PHP_CodeSniffer is a replacement for the more manual task of checking coding standards in code reviews. With PHP_CodeSniffer, you can reserve code reviews for the checking of code correctness.

Note: Coding standards are a good thing. They will make your code easier to read and maintain, especially when multiple developers are working on the same application. Consider using coding standards if you don't already.

Does PHP_CodeSniffer parse my code to ensure it will execute?

No. PHP_CodeSniffer does not actually parse your code, and so cannot accurately tell if your code contains parse errors. PHP_CodeSniffer does know about some parse errors and will warn you if it finds code that it is unable to sniff correctly due to a suspected parse error. However, as there is no actual parsing taking place, PHP_CodeSniffer may return an incorrect number of errors when checking code that does contain parse errors.

Tip

You can easily check for parse errors in a file using the PHP command line interface and the -l (lowercase L) option.

$ php -l /path/to/code/myfile.inc
No syntax errors detected in /path/to/code/myfile.inc

I don't agree with your coding standards! Can I make PHP_CodeSniffer enforce my own?

Yes. At its core, PHP_CodeSniffer is just a framework for enforcing coding standards. We release PHP_CodeSniffer with some sample coding standards to help developers get started on projects where there is no standard defined. If you want to write your own standard, read the tutorial on creating coding standards.

How come PHP_CodeSniffer reported errors, I fixed them, now I get even more?

Sometimes, errors mask the existence of other errors, or new errors are created as you fix others. For example, PHP_CodeSniffer might tell you that an inline IF statement needs to be defined with braces. Once you make this change, PHP_CodeSniffer may report that the braces you added are not correctly aligned.

Always run PHP_CodeSniffer until you get a passing result. Once you've made the changes PHP_CodeSniffer recommends, run PHP_CodeSniffer again to ensure no new errors have been added.

Why doesn't PHP_CodeSniffer just make the changes it suggests for me?

As much as we trust PHP_CodeSniffer to check your code for coding standard errors, we don't trust any application to ever change code for us without reviewing it first. Considering you would have to check each change PHP_CodeSniffer made before releasing the source code, why not make the changes manually?

Making the changes manually ensures a couple of positive things happen:

  • Developers learn the coding standards and make less mistakes in the future.

  • Developers can ensure that PHP_CodeSniffer is working correctly.

  • Developers can decide if a coding standard doesn't fit a particular piece of code.

So if you find yourself wishing PHP_CodeSniffer would just go ahead and make those changes for you, maybe you just need to read the coding standards and adhere to them a bit better.

Note: No matter how small of a change you make, always test your code before committing it to your code repository or releasing it. Even changes suggested by PHP_CodeSniffer need to be tested, as small and insignificant as they may seem.

What does PHP_CodeSniffer use to tokenize my code?

For PHP files, PHP_CodeSniffer uses PHP's inbuilt tokenizer functions to parse your code. It then changes that output to include much more data about the file, such as matching function braces to function keywords.

For all other file types, PHP_CodeSniffer includes a custom tokenizer that either makes use of PHP's inbuilt tokenizer or emulates it. In both cases, the token array must be checked and changed manually before all the standard PHP_CodeSniffer matching rules are applied, making tokenizing a bit slower for these file types.

Prev | PHP_CodeSniffer | Next
Using the Subversion pre-commit Hook | PEAR Manual | PHP_Compat


PHP_Compat

PHP_Compat

Provides missing functionality for older versions of PHP.

Table of Contents
  • Introduction -- Purpose and simple usage example
  • Components -- List of replicated components
  • Advanced usage -- Describe techniques for advanced usage
  • PHP_Compat::loadFunction -- Load a function, or an array of functions
  • PHP_Compat::loadConstant -- Load a constant, or an array of constants
  • PHP_Compat::loadVersion -- Load all components, or all components until a given version of PHP
Prev | PHP | Next
FAQ | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Purpose and simple usage example

Description

PHP_Compat provides missing functionality in the form of functions and constants for older versions of PHP.

The replicated functions are designed to be interchangable with their native equivilants. They have the same signature, same return values and throw the same errors. Each function is unit tested to ensure accuracy.

Example

Loading a component with PHP_Compat:

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

PHP_Compat::loadFunction('file_get_contents');
?>

Or, if you don't wish to use the class, you can load it manually.

Loading a component manually:

<?php
require_once 'PHP/Compat/Function/file_put_contents.php';
?>

The function is then ready to use like you would normally.

PHP_Compat is designed for ease of use. It has no dependencies and can be used completely outside the PEAR infrastructure.

Prev | PHP_Compat | Next
PHP_Compat | PEAR Manual | Components


Components

Components

Components – List of replicated components

Functions

The following functions have been replicated:

Functions
Function | Since
array_change_key_case() | PHP 4.2.0
array_chunk() | PHP 4.2.0
array_combine() | PHP 5.0.0
array_diff_assoc() | PHP 4.3.0
array_diff_key() | PHP 5.0.2
array_diff_ukey() | PHP 5.0.2
array_intersect_assoc() | PHP 5.0.0
array_intersect_key() | PHP 5.0.2
array_intersect_uassoc() | PHP 5.0.0
array_intersect_ukey() | PHP 5.0.2
array_key_exists() | PHP 4.1.0
array_product() | PHP 5.1.0
array_search() | PHP 4.0.5
array_udiff() | PHP 5.0.0
array_udiff_assoc() | PHP 5.0.0
array_udiff_uassoc() | PHP 5.0.0
array_uintersect() | PHP 5.0.0
array_uintersect_assoc() | PHP 5.0.0
array_uintersect_uassoc() | PHP 5.0.0
array_walk_recursive() | PHP 5.0.0
call_user_func_array() | PHP 4.0.4
bcinvert() | PHP 5.2.0
bcpowmod() | PHP 5.0.0
clone() | PHP 5.0.0
constant() | PHP 4.0.4
convert_uudecode() | PHP 5.0.0
convert_uuencode() | PHP 5.0.0
debug_print_backtrace() | PHP 5.0.0
file_get_contents() | PHP 4.3.0
file_put_contents() | PHP 5.0.0
floatval() | PHP 4.2.0
fprintf() | PHP 5.0.0
fputcsv() | PHP 5.0.0
get_headers() | PHP 5.0.0
get_include_path() | PHP 4.3.0
html_entity_decode() | PHP 4.3.0
htmlspecialchars_decode() | PHP 5.1.0
http_build_query() | PHP 5.0.0
ibase_timefmt() | PHP 5.0.0
idate() | PHP 5.1.0
image_type_to_mime_type() | PHP 4.3.0
inet_ntop() | PHP 5.1.0
inet_pton() | PHP 5.1.0
ini_get_all() | PHP 4.2.0
is_a() | PHP 4.2.0
is_scalar() | PHP 4.0.5
md5_file() | PHP 4.2.0
mhash() | PHP 4.1.0
mime_content_type() | PHP 4.3.0
ob_clean() | PHP 4.2.0
ob_flush() | PHP 4.2.0
ob_get_clean() | PHP 4.3.0
ob_get_flush() | PHP 4.3.0
php_strip_whitespace() | PHP 5.0.0
property_exists() | PHP 5.1.0
pg_affected_rows() | PHP 4.2.0
pg_escape_bytea() | PHP 4.2.0
pg_unescape_bytea() | PHP 4.2.0
restore_include_path() | PHP 4.3.0
scandir() | PHP 5.0.0
set_include_path() | PHP 4.3.0
str_ireplace() | PHP 5.0.0
str_rot13() | PHP 4.2.0
str_shuffle() | PHP 4.3.0
str_split() | PHP 5.0.0
str_word_count() | PHP 4.3.0
stripos() | PHP 5.0.0
strpbrk() | PHP 5.0.0
strripos() | PHP 5.0.0
substr_compare() | PHP 5.0.0
time_sleep_until() | PHP 5.1.0
var_export() | PHP 4.2.0
version_compare() | PHP 4.1.0
vprintf() | PHP 4.1.0
vsprintf() | PHP 4.1.0

Constants

The following constants have been replicated:

Constants
File | Constants | Since
DIRECTORY_SEPARATOR | DIRECTORY_SEPARATOR | PHP 4.0.6
E_STRICT
  • E_STRICT
 PHP 5
FILE
  • FILE_USE_INCLUDE_PATH
  • FILE_IGNORE_NEW_LINES
  • FILE_SKIP_EMPTY_LINES
  • FILE_APPEND
  • FILE_NO_DEFAULT_CONTEXT
 PHP 5
PATH_SEPARATOR
  • PATH_SEPARATOR
 PHP 4.3.0
PHP_EOL
  • PHP_EOL
 PHP 5
STD
  • STDIN
  • STDOUT
  • STDERR
 PHP 4.3.0
T
  • T_ML_COMMENT
  • T_DOC_COMMENT
  • T_OLD_FUNCTION
  • T_ABSTRACT
  • T_CATCH
  • T_FINAL
  • T_INSTANCEOF
  • T_PRIVATE
  • T_PROTECTED
  • T_PUBLIC
  • T_THROW
  • T_TRY
  • T_CLONE
 PHP 5
UPLOAD_ERR
  • UPLOAD_ERR_OK
  • UPLOAD_ERR_INI_SIZE
  • UPLOAD_ERR_FORM_SIZE
  • UPLOAD_ERR_PARTIAL
  • UPLOAD_ERR_NO_FILE
 PHP 4.3.0
Prev | PHP_Compat | Next
Introduction | PEAR Manual | Advanced usage


Advanced usage

Advanced usage

Advanced usage – Describe techniques for advanced usage

Advanced usage

In order to create portable code, it's best to assume all the native functions already exist. Littering a script with calls to PHP_Compat can become messy, and increase the work required to port the code.

To solve this there are a number of approaches. The first would be adding the load statements to a file which is included at the top of every document. The second, and preferred method is to make use of php_auto_append php.ini value. This can be set in a .htaccess file, and no modifications to the actual code are required.

If phpcompat.php was the name of the file, an example entry in a .htaccess could be php_value php_auto_append phpcompat.php. The phpcompat.php file would make use of either the loadVersion or loadFunction/loadConstant methods discussed in the next page.

Prev | PHP_Compat | Next
Components | PEAR Manual | PHP_Compat::loadFunction


PHP_Compat::loadFunction

PHP_Compat::loadFunction

PHP_Compat::loadFunction() – Load a function, or an array of functions

Synopsis

require_once 'PHP/Compat.php';

mixed PHP_Compat::loadFunction ( mixed $function )

Description

Loads a function, or an array of functions.

Parameter

mixed $function

The name, or an array of names, of functions to load

Return value

mixed

  • TRUE if the function was loaded.
  • FALSE if the function was not loaded. Either unable to be included or already defined.
  • If you specified an array of functions to load, an array of TRUE/FALSE values is returned.

Example

Loading a function with the class:

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

// load file_put_contents
PHP_Compat::loadFunction('file_put_contents');

// load str_split, array_chunk and file_get_contents
PHP_Compat::loadFunction(array('str_split', 'array_chunk', 'file_get_contents'));
?>

You may also load a function without using the class.

Loading a function manually:

<?php
require_once 'PHP/Compat/Function/file_put_contents.php';
?>

Note

This function should be called statically.

Prev | PHP_Compat | Next
Advanced usage | PEAR Manual | PHP_Compat::loadConstant


PHP_Compat::loadConstant

PHP_Compat::loadConstant

PHP_Compat::loadConstant() – Load a constant, or an array of constants

Synopsis

require_once 'PHP/Compat.php';

mixed PHP_Compat::loadConstant ( mixed $constant )

Description

Loads a constant, or an array of constants.

Parameter

mixed $constant

The name, or an array of names, of constants to load

Return value

mixed

  • TRUE if the constant was loaded.
  • FALSE if the constant was not loaded. Either unable to be included or already defined.
  • If you specified an array of constants to load, an array of TRUE/FALSE values is returned.

Example

Loading a constant with the class:

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

// load E_STRICT
PHP_Compat::loadConstant('E_STRICT');

// load E_STRICT, and PATH_SEPATATOR
PHP_Compat::loadConstant(array('E_STRICT', 'PATH_SEPARATOR'));

// load the STD group of constants (STDIN, STDOUT, STDERR)
PHP_Compat::loadConstant('STD');
?>

You may also load a constant without using the class.

Loading a constant manually:

<?php
require_once 'PHP/Compat/Constant/E_STRICT.php';
?>

Note

This function should be called statically.

Prev | PHP_Compat | Next
PHP_Compat::loadFunction | PEAR Manual | PHP_Compat::loadVersion


PHP_Compat::loadVersion

PHP_Compat::loadVersion

PHP_Compat::loadVersion() – Load all components, or all components until a given version of PHP

Synopsis

require_once 'PHP/Compat.php';

array PHP_Compat::loadVersion ( string $version )

Description

Load all components, or all components until a given version of PHP.

Parameter

string $version

The version of PHP to load components until.

Return value

array

  • An associative array of boolean values. The key is the name of the component loaded. The value for whether or not the component was loaded correctly.

Example

Loading all components:

<?php
require_once 'PHP/Compat.php';
$components = PHP_Compat::loadVersion();

// To see which components were loaded
print_r($components);
?>

This example would show a long list of components which were loaded.

Loading up to a specific version:

The components loaded would be those with versions lower than, or equal to the supplied version and greater than the current PHP version.

<?php
require_once 'PHP/Compat.php';
$components = PHP_Compat::loadVersion('4.3.0');

// To see which components were loaded
print_r($components);
?>

This would output an array of components which were loaded. The output would be simular to:

Array
(
    [array_diff_assoc] => 1
    [file_get_contents] => 1
    [get_include_path] => 1
    [html_entity_decode] => 1
    [image_type_to_mime_type] => 1
    [ob_get_clean] => 1
    [ob_get_flush] => 1
    [restore_include_path] => 1
    [set_include_path] => 1
    [str_shuffle] => 1
    [str_word_count] => 1
    [FILE] => 1
    [STD] => 1
    [UPLOAD_ERR] => 1
)

Note

This function should be called statically.

Prev | PHP_Compat | Next
PHP_Compat::loadConstant | PEAR Manual | PHP_CompatInfo


PHP_CompatInfo

PHP_CompatInfo

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

Table of Contents
  • Summary
  • Getting started
  • Reference guide
Prev | PHP | Next
PHP_Compat::loadVersion | PEAR Manual | Summary


Summary

Summary

Table of Contents
  • Features
  • System Requirements
  • About
Prev | PHP_CompatInfo | Next
PHP_CompatInfo | PEAR Manual | Features


Features

Features

  • parse a single file

  • parse a folder/directory

  • parse an array (list of file)

  • ability to give a list of functions to ignore when calculating the version needed

  • ability to give a list of directories to ignore when calculating the version needed

  • ability to go recursively or not into folder to find files

  • ability to reduce or extends list of extensions to parse for PHP code

  • ability to give a list of constants to ignore when calculating the version needed. Available since version 1.2.0

  • ability to get list of functions related to a PHP version (or a subset). Available since version 1.2.0

  • ability to give a list of (related functions of) php modules/extensions to ignore when calculating the version needed. Available since version 1.4.0

  • ability to give a list of (related functions of) php versions to ignore when calculating the version needed. Available since version 1.4.0

  • ability to exclude from parsing scope, some functions, extensions, constants, based on conditionnal code. Available since version 1.7.0

  • ability to know conditional code (such as function_exists) used by php scripts. Available since version 1.7.0

Prev | Summary | Next
Summary | PEAR Manual | System Requirements


System Requirements

System Requirements

Mandatory resources :

  • PHP 4.3.10 or newer.

  • PEAR 1.5.4 or newer.

  • PEAR::Console_Table 1.0.5 or newer.

  • PEAR::Console_GetArgs 1.3.3 or newer.

  • PEAR::File_Find 1.3.0 or newer.

  • PEAR::Event_Dispatcher 1.0.0 or newer.

  • pcre extension.

  • tokenizer extension.

Optional resources :

  • PHP 5.0.0 or newer.

  • PHPUnit 3.2.0 or newer.

  • PEAR::XML_Util 1.1.4 or newer.

  • PEAR::XML_Beautifier 1.1 or newer.

  • PEAR::Console_ProgressBar 0.5.2beta or newer.

  • PEAR::Var_Dump 1.0.3 or newer.

  • PEAR::HTML_Table 1.8.2 or newer.

Prev | Summary | Next
Features | PEAR Manual | About


About

About

Table of Contents
  • FAQ -- Answers to most Frequently Asked Questions
  • News -- What is New in version ?
  • Installing PHP_CompatInfo -- two solutions: auto and manual
Prev | Summary | Next
System Requirements | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

PHP_CompatInfo FAQ

    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).

    Prev | About | Next
About | PEAR Manual | News


News

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

  • Initial PEAR public release: occured in March 2003, one month later after package proposal was launched under name PHP_Compatibility

  • Added the ability to ignore files: in PHP_CompatInfo::parseFolder() and PHP_CompatInfo::parseArray()

  • Added the ability to ignore folders: in PHP_CompatInfo::parseFolder()

  • Added the ability to ignore functions: in all public methods.

Version 0.8.x

  • Added a command line interface: with new class PHP_CompatInfo_Cli

  • Added a clone function: to PHP_CompatInfo::parseFolder() named PHP_CompatInfo::parseDir(). parseFolder() became now an alias of parseDir().

  • Added new option file_ext for parseArray: This option contains an array of file extensions to parse for PHP code. Default: php, php4, inc, phtml

  • Fixed integration with PEAR_PackageFileManager: PackageFileManager::detectDependencies() implement call to PHP_CompatInfo and allow to detect easily minimum PHP version needed.

Version 1.0.x

  • Improved PHP5 detection: one year after first PEAR public release, stable version 1.0.0 fixed some bugs and also allow PHP3 script/function detection.

Version 1.1.x

  • Added support for reporting max PHP version: came with user request 6056

  • Improved PECL detection: especially with SAPI extension.

Version 1.2.x

  • Added new option ignore_constants: to
     PHP_CompatInfo::parseArray(),
     PHP_CompatInfo::parseDir(),
     PHP_CompatInfo::parseFolder(),
     PHP_CompatInfo::parseFile(),
     PHP_CompatInfo::parseString(),

  • Load components list for a PHP version or subset: added new function PHP_CompatInfo::loadVersion() to API

Version 1.3.x

  • Improved command line interface: output is limited to 80 columns for a better render. There is also now a windows launcher (named compatinfo.bat).

  • package xml 1.0: was stopped to be generated on version 1.3.2 (september 2006)

Version 1.4.x

  • Inactive leader: Davey Shafik, initial author of this package, became inactive, and I (Laurent Laville) follow his steps as new active package leader.

  • PHP 4.3.0: is now required as a minimum to use both web and cli interfaces.

  • License upgrade: from PHP 3.0 to PHP 3.01

  • Improved PHP5 detection: with some bug fixes

Version 1.5.x

  • Improved PHP5 detection: with new data source version.xml (revision 1.8) and funclist.txt (revision 1.39).

  • Dropped support of PHP3 detection: due to content of new data source version.xml (1.8) and funclist.txt (1.39)

  • Command line interface: under windows (pci.bat) and unix (pci.php) have now unified name. Idea came from PHP_CodeSniffer package that allow to fix lot of errors/warnings of coding standard.

    Debug output of CLI gave now origin of extension (from PECL or not) and minimum extension version (rather than PHP). See example docs/examples/checkExtensions.php

Version 1.6.x

  • Improved PHP5 detection: with data source version.xml (revision 1.9) and funclist.txt (revision 1.39).

    More PHP constant are detected natively:

    • Some Core Predefined Constants ( PHP_EOL, DIRECTORY_SEPARATOR, PATH_SEPARATOR, E_STRICT )

    • Date Predefined Constants ( DATE_* )

    • CLI Specific Constants ( STD* )

    • File Upload Error Specific Constants ( UPLOAD_ERR_* )

  • Command line interface: allow now to detect version of a simple string (code without using script tags <?php ... ?>. Uses new parameter -s or --string.

  • Command line interface: allow now to print either an xml or text report (default). Uses new parameter -r or --report.

  • loadVersion() may return both function or function+constant list.

  • PHP method chaining is implemented on "Davey Shafik" request #13094.

Version 1.7.x

  • Fix CLI output render to 80 columns, on main table :

    • 29 characters for File/Path column

    • 9 characters for Version column

    • 3 characters for C column (conditional code level)

    • 12 characters for Extensions column

    • 20 characters for Constants/Tokens column

  • Fix CLI output render to 80 columns, on additionnal tables :

    • 25 characters for Option column

    • 51 characters for Value column

  • Improved detection on conditionnal code: with new options : ignore_functions_match, ignore_extensions_match, ignore_constants_match.

    That allow to implement request 12857 : add the option to locally mask exceptions.

  • Implement request 13138 : separate constants and tokens in results.

  • Implement request 13147 : add filter file extension option on parsing directory (CLI)

  • On CLI, the XML report generation is now xml compliant with a root tag (pci)

    XML format is incompatible with version 1.6.x

  • ability to know conditional code (such as function_exists) used by php scripts. A level (and details) of warning about conditional code found during parsing source code is available for all interface (including command line : with new column C)

  • On CLI text report is customizable with new --output-level switch. Path/File+Version are always given on minimum report (0), until full details (max:15 - default).

  • On CLI you may now summarize the result with new --summarize switch. Remove extra lines for all files when parsing a directory.

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:

  • Always display result on standard output. To disable this feature, see the FAQ entry package.php.php-compatinfo.faq.html.

  • 2 news output format. With the new renderer system, the Web SAPI may use the xml render (until now limited to CLI). While there is two news render: csv and html. Default output format (PHP dump array) use the array render while text is for CLI.

  • A common method to parse all data sources. The new method PHP_CompatInfo::parseData() allow to parse all data source (array, string, file, directory) with the same interface. All others PHP_CompatInfo::parse* functions become now alias of this new method (to keep backward compatibility).

  • Event-driven architecture allow multiple renderer and extending core API of PHP_CompatInfo.

  • Progress bar for long process. Ability to display simple text wait message or a progress bar when parsing directories (or lot of files) from the command line, and even on web interface.

  • Constant E_RECOVERABLE_ERROR introduced with PHP 5.2.0, is now detected.

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.

  • class dictionary $GLOBALS['_PHP_COMPATINFO_CLASS'] found into CompatInfo/class_array.php file

  • constant dictionary $GLOBALS['_PHP_COMPATINFO_CONST'] found into CompatInfo/const_array.php file

  • function dictionary $GLOBALS['_PHP_COMPATINFO_FUNCS'] found into CompatInfo/func_array.php file

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:

  • bcmath
  • calendar
  • ctype
  • date
  • dom
  • filter
  • ftp
  • gd
  • gettext
  • hash
  • iconv
  • json
  • libxml
  • mbstring
  • mysql
  • mysqli
  • openssl
  • pcre
  • pgsql
  • session
  • SimpleXML
  • SPL
  • SQLite
  • standard
  • tokenizer
  • wddx
  • xml
  • xmlreader
  • xmlwriter
  • xsl

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:

  • getVersion Minimum (and or maximal) PHP Version

  • getClasses All classes (internal or end-user defined)

  • getFunctions All functions (internal or end-user defined)

  • getExtensions All extensions (internal or external)

  • getConstants All constants (internal or end-user defined)

  • getTokens All PHP5+ tokens

  • getConditions All (warning) code conditions

  • getIgnoredFiles List of files ignored during parsing data source

  • getIgnoredFunctions List of functions (user or PHP internal) ignored during parsing data source

  • getIgnoredExtensions List of PHP extensions ignored during parsing data source

  • getIgnoredConstants List of constants (user or PHP internal) ignored during parsing data source

  • getSummary Returns only summary information when parsing a directory or multiple data sources

Prev | About | Next
FAQ | PEAR Manual | Installing PHP_CompatInfo


Installing PHP_CompatInfo

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:

    Note: 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:

    Note: 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.

Prev | About | Next
News | PEAR Manual | Getting started


Getting started

Getting started

Table of Contents
  • Overview -- features and usage patterns
  • Basic detection -- parse data source with default options
  • Advanced detection -- parse data source with additional options
  • Conditional Code Analysis -- improve accuracy detection with conditional code
  • The Command-Line Parser -- parsing data source with CLI
  • Outputting Results -- how to use the renderer system
  • Build your Extension Support List -- or how to improve detection
  • Build your Exception Rules System -- or how to fix invalid values
Prev | PHP_CompatInfo | Next
Installing PHP_CompatInfo | PEAR Manual | Overview


Overview

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.

Prev | Getting started | Next
Getting started | PEAR Manual | Basic detection


Basic detection

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

  • bcmath
  • pcre

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

  • php
  • php4
  • inc
  • phtml

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.

Caution

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

Tip

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 :

  • offset 0, give name of function conditions

  • offset 1, give name of extension conditions

  • offset 2, give name of constant conditions

Prev | Getting started | Next
Overview | PEAR Manual | Advanced detection


Advanced detection

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.

Note: 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.

Tip

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.

Prev | Getting started | Next
Basic detection | PEAR Manual | Conditional Code Analysis


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 :

  • function (cond_code = 1)

    A quick example:

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

  • extension (cond_code = 2)

    A quick example:

    <?php
    if (extension_loaded('sqlite') == false) {
            $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
            dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
        echo     'SQLite version : ' . sqlite_libversion();
    }
    ?>

  • constant (cond_code = 4)

    A quick example:

    <?php
    if (defined('DATE_RSS') {
            $date_format = DATE_RSS;
    } else {
            $date_format = 'D, j M Y H:i:s O';
    }
    // will display something like "Sat, 26 Jul 2008 16:56:24 +0200"
    echo date($date_format, mktime(0, 0, 0, 7, 26, 2008));
    ?>

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('/.*/')).

Tip

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

Caution

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

Prev | Getting started | Next
Advanced detection | PEAR Manual | The Command-Line Parser


The Command-Line Parser

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.

Tip

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)

Note: 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.

Note: 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

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

  • Files Identify each file of data source parsed.

  • Version Give the minimum version to run the file. And if there is a second number, give the max version to run source file.

  • C Show the level of conditional code found in your source file(s). From 0=none, 1=function_exists, 2=extension_loaded, 4=defined and more (its binary value). This C column is the same information given by cond_code in final hash result of Array Renderer.

  • Extensions List the PHP standard or PECL extensions required to run the source file.

  • Constants/Tokens List the PHP standard or user defined constants and PHP5+ tokens (such as: private, public, final, ...)

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 |

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

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

Prev | Getting started | Next
Conditional Code Analysis | PEAR Manual | Outputting Results


Outputting Results

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

  • Array, PHP_CompatInfo_Renderer_Array. It is similar to PHP var_export May be beautify if PEAR::Var_Dump is installed on your system.

  • Csv, PHP_CompatInfo_Renderer_Csv. Print a comma separate values of results.

  • Html, PHP_CompatInfo_Renderer_Html. Print a pretty nice table with a customizable style sheet (inline or to a separate file)

  • Null, PHP_CompatInfo_Renderer_Null. The solution to suppress display on standard output.

  • Text, PHP_CompatInfo_Renderer_Text. This renderer is usefull only with the command-line parser mode (CLI).

  • Xml, PHP_CompatInfo_Renderer_Xml. Print an XML representation of results. May be beautify if PEAR::XML_Beautifier is installed on your system.

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);
?>

Note: 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.

  • silent mode : When parsing more than one source file, PHP_CompatInfo can display status of long process. With simple wait text messages, or a progress bar if PEAR::Console_ProgressBar is available (installed on your system).

    The default mode silent On, is turn off when you specify a progress bar or a progress text with --progress or -p switches on CLI with the pci script.

    If you run the web interface, you have to turn it on manually. For example:

    <?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

    // Turn Off the silent mode, and display simple wait text messages
    $driverOptions = array('silent' => false, 'progress' => 'text');

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

    See also the docs/examples/parseDir_withCustomProgressBar.php example in the package distribution, to customize a progress bar for the CLI and pci script usage.

  • output-level allow to choose what information (condition code level, extensions, constants, tokens, version) will be shown or hidden.

    Default value is 31: that means we show all details. See the Command-Line Parser section, and -o | --output-level switch to learn more about values and corresponding behaviors.

  • summarize mode, is usefull when you parse more than one file, and don't want to see intermediate result of each file, but only the final one.

    Default is turn off.

  • verbose level, give details deep you want to have: from 0 (no extra information) to 7 (full details).

    Default level is 0. See the Command-Line Parser section, and -v | --verbose switch to learn more about values and corresponding behaviors.

Important: 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.

Caution

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.

Note: 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

  • fields-values-separated-by identify the delimiter of values when there is a list given (extensions, constants, tokens). Default is ,

  • fields-terminated-by identify the delimiter of fields (those given by the output-level directive). Default is ;

  • fields-enclosed-by identify the protect field character if content have one or more restrictive character as given by previous options. Default is "

  • lines-terminated-by identify the end-of-line character. Usefull if you want to generate a file for another platform than those who have produced the results. Default is PHP_EOL constant

Html renderer options

Html renderer have only one specific option :

  • tdwidth that give size of each column (in em css unit), even if there are not shown (see output-level value). Default is 18,4,2,7,13

    That means: File is 18 em width, Version is 4 em width, C (cond_code) is 2 em width, Extensions is 7 em width, and Constants/Tokens is 13 em width.

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 :

  • colwidth that give size of file (f), extensions (e), and constants/tokens (c) column (in character unit), even if there are not shown (see output-level value). Default is f = 29, e = 12, c = 20)

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-beautifier tell if we use the PEAR::XML_Beautifier package to beautify XML output. Default is auto (use only if available)

  • beautifier is a hash for the PEAR::XML_Beautifier package options. Default is empty array (use all XML_Beautifier package default options).

Tip

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.

Prev | Getting started | Next
The Command-Line Parser | PEAR Manual | Build your Extension Support List


Build your Extension Support List

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

Important: 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

Important: 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.

    Caution

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

    Tip

    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

    Important: 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.

Prev | Getting started | Next
Outputting Results | PEAR Manual | Build your Exception Rules System


Build your Exception Rules System

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

Important: 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

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

Note: 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.

  • $function_exceptions for the related extension functions list

  • $constant_exceptions for the related extension constants list

  • $class_exceptions for the related extension classes list

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:

  • Build your own ERS to be free to fix all errors you found without to wait a PHP Manual/PCI new version.

  • Use a directory acessible in your include_path to store result of data dictionaries corresponding to your platform, and avoid to overwrite the default PCI installation.

Prev | Getting started | Next
Build your Extension Support List | PEAR Manual | Reference guide


Reference guide

Reference guide

Table of Contents
  • PHP version history
  • Observers
  • Parsing Data Sources
  • Getting Results
  • Parser Infrastructure
  • Renderer Infrastructure
  • Array Renderer
  • Csv Renderer
  • Html Renderer
  • Null Renderer
  • Text Renderer
  • Xml Renderer
  • Command-Line version
Prev | PHP_CompatInfo | Next
Build your Exception Rules System | PEAR Manual | PHP version history


PHP version history

PHP version history

Table of Contents
  • PHP_CompatInfo::loadVersion -- Load components list
Prev | Reference guide | Next
Reference guide | PEAR Manual | PHP_CompatInfo::loadVersion


PHP_CompatInfo::loadVersion

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',

)

Prev | PHP version history | Next
PHP version history | PEAR Manual | Observers


Observers

Observers

Table of Contents
  • PHP_CompatInfo::addListener -- Registers a new listener
  • PHP_CompatInfo::removeListener -- Removes a registered listener
Prev | Reference guide | Next
PHP_CompatInfo::loadVersion | PEAR Manual | PHP_CompatInfo::addListener


PHP_CompatInfo::addListener

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);
?>
Prev | Observers | Next
Observers | PEAR Manual | PHP_CompatInfo::removeListener


PHP_CompatInfo::removeListener

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

Prev | Observers | Next
PHP_CompatInfo::addListener | PEAR Manual | Parsing Data Sources


Parsing Data Sources

Parsing Data Sources

Table of Contents
  • PHP_CompatInfo::parseArray -- Parse an Array of Files
  • PHP_CompatInfo::parseDir -- Parse a directory
  • PHP_CompatInfo::parseFolder -- Alias of parseDir
  • PHP_CompatInfo::parseFile -- Parse a single file
  • PHP_CompatInfo::parseString -- Parse a string
  • PHP_CompatInfo::parseData -- Parse a data source
Prev | Reference guide | Next
PHP_CompatInfo::removeListener | PEAR Manual | PHP_CompatInfo::parseArray


PHP_CompatInfo::parseArray

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.

Caution

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.

Prev | Parsing Data Sources | Next
Parsing Data Sources | PEAR Manual | PHP_CompatInfo::parseDir


PHP_CompatInfo::parseDir

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.

Prev | Parsing Data Sources | Next
PHP_CompatInfo::parseArray | PEAR Manual | PHP_CompatInfo::parseFolder


PHP_CompatInfo::parseFolder

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.

Prev | Parsing Data Sources | Next
PHP_CompatInfo::parseDir | PEAR Manual | PHP_CompatInfo::parseFile


PHP_CompatInfo::parseFile

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.

Prev | Parsing Data Sources | Next
PHP_CompatInfo::parseFolder | PEAR Manual | PHP_CompatInfo::parseString


PHP_CompatInfo::parseString

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.

Prev | Parsing Data Sources | Next
PHP_CompatInfo::parseFile | PEAR Manual | PHP_CompatInfo::parseData


PHP_CompatInfo::parseData

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);
?>
Prev | Parsing Data Sources | Next
PHP_CompatInfo::parseString | PEAR Manual | Getting Results


Getting Results

Getting Results

Table of Contents
  • PHP_CompatInfo::getVersion -- Returns the latest parse data source version
  • PHP_CompatInfo::getClasses -- Returns the latest parse data source classes declared
  • PHP_CompatInfo::getFunctions -- Returns the latest parse data source functions declared
  • PHP_CompatInfo::getExtensions -- Returns the latest parse data source extensions used
  • PHP_CompatInfo::getConstants -- Returns the latest parse data source constants declared
  • PHP_CompatInfo::getTokens -- Returns the latest parse data source tokens declared
  • PHP_CompatInfo::getConditions -- Returns the latest parse data source conditions
  • PHP_CompatInfo::getIgnoredFiles -- Returns list of files ignored
  • PHP_CompatInfo::getIgnoredFunctions -- Returns the latest parse data source ignored functions
  • PHP_CompatInfo::getIgnoredExtensions -- Returns the latest parse data source ignored extensions
  • PHP_CompatInfo::getIgnoredConstants -- Returns the latest parse data source ignored constants
  • PHP_CompatInfo::getSummary -- Returns the summary of parsing info
Prev | Reference guide | Next
PHP_CompatInfo::parseData | PEAR Manual | PHP_CompatInfo::getVersion


PHP_CompatInfo::getVersion

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

Prev | Getting Results | Next
Getting Results | PEAR Manual | PHP_CompatInfo::getClasses


PHP_CompatInfo::getClasses

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.

Prev | Getting Results | Next
PHP_CompatInfo::getVersion | PEAR Manual | PHP_CompatInfo::getFunctions


PHP_CompatInfo::getFunctions

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.

Prev | Getting Results | Next
PHP_CompatInfo::getClasses | PEAR Manual | PHP_CompatInfo::getExtensions


PHP_CompatInfo::getExtensions

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.

Prev | Getting Results | Next
PHP_CompatInfo::getFunctions | PEAR Manual | PHP_CompatInfo::getConstants


PHP_CompatInfo::getConstants

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.

Prev | Getting Results | Next
PHP_CompatInfo::getExtensions | PEAR Manual | PHP_CompatInfo::getTokens


PHP_CompatInfo::getTokens

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.

Prev | Getting Results | Next
PHP_CompatInfo::getConstants | PEAR Manual | PHP_CompatInfo::getConditions


PHP_CompatInfo::getConditions

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.

Prev | Getting Results | Next
PHP_CompatInfo::getTokens | PEAR Manual | PHP_CompatInfo::getIgnoredFiles


PHP_CompatInfo::getIgnoredFiles

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.

Prev | Getting Results | Next
PHP_CompatInfo::getConditions | PEAR Manual | PHP_CompatInfo::getIgnoredFunctions


PHP_CompatInfo::getIgnoredFunctions

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

Prev | Getting Results | Next
PHP_CompatInfo::getIgnoredFiles | PEAR Manual | PHP_CompatInfo::getIgnoredExtensions


PHP_CompatInfo::getIgnoredExtensions

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.

Prev | Getting Results | Next
PHP_CompatInfo::getIgnoredFunctions | PEAR Manual | PHP_CompatInfo::getIgnoredConstants


PHP_CompatInfo::getIgnoredConstants

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.

Prev | Getting Results | Next
PHP_CompatInfo::getIgnoredExtensions | PEAR Manual | PHP_CompatInfo::getSummary


PHP_CompatInfo::getSummary

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.

Prev | Getting Results | Next
PHP_CompatInfo::getIgnoredConstants | PEAR Manual | Parser Infrastructure


Parser Infrastructure

Parser Infrastructure

Table of Contents
  • constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser -- Parser Class constructor
  • PHP_CompatInfo_Parser::setOutputDriver -- Set up driver to be used
  • PHP_CompatInfo_Parser::addListener -- Registers a new listener
  • PHP_CompatInfo_Parser::removeListener -- Removes a registered listener
  • PHP_CompatInfo_Parser::notifyListeners -- Post a new notification to all listeners registered
  • PHP_CompatInfo_Parser::loadVersion -- Load components list
  • PHP_CompatInfo_Parser::getDirlist -- Returns list of directory parsed
  • PHP_CompatInfo_Parser::getFilelist -- Returns list of files parsed
  • PHP_CompatInfo_Parser::getIgnoredFiles -- Returns list of files ignored
  • PHP_CompatInfo_Parser::parseData -- Parse a data source
Prev | Reference guide | Next
PHP_CompatInfo::getSummary | PEAR Manual | constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser


constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser

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.

Prev | Parser Infrastructure | Next
Parser Infrastructure | PEAR Manual | PHP_CompatInfo_Parser::setOutputDriver


PHP_CompatInfo_Parser::setOutputDriver

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.

Prev | Parser Infrastructure | Next
constructor PHP_CompatInfo_Parser::PHP_CompatInfo_Parser | PEAR Manual | PHP_CompatInfo_Parser::addListener


PHP_CompatInfo_Parser::addListener

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

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::setOutputDriver | PEAR Manual | PHP_CompatInfo_Parser::removeListener


PHP_CompatInfo_Parser::removeListener

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

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::addListener | PEAR Manual | PHP_CompatInfo_Parser::notifyListeners


PHP_CompatInfo_Parser::notifyListeners

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.

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::removeListener | PEAR Manual | PHP_CompatInfo_Parser::loadVersion


PHP_CompatInfo_Parser::loadVersion

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.

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::notifyListeners | PEAR Manual | PHP_CompatInfo_Parser::getDirlist


PHP_CompatInfo_Parser::getDirlist

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.

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::loadVersion | PEAR Manual | PHP_CompatInfo_Parser::getFilelist


PHP_CompatInfo_Parser::getFilelist

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.

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::getDirlist | PEAR Manual | PHP_CompatInfo_Parser::getIgnoredFiles


PHP_CompatInfo_Parser::getIgnoredFiles

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.

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::getFilelist | PEAR Manual | PHP_CompatInfo_Parser::parseData


PHP_CompatInfo_Parser::parseData

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 :

  • '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.

* parseArray, parseDir|parseFolder, specific options :

  • '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.

* parseArray specific options :

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

* parseDir|parseFolder specific options :

  • 'recurse_dir' Boolean on whether to recursively find files

  • 'ignore_dirs' Contains an array of directories to ignore. Directory names are case insensitive.

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

Prev | Parser Infrastructure | Next
PHP_CompatInfo_Parser::getIgnoredFiles | PEAR Manual | Renderer Infrastructure


Renderer Infrastructure

Renderer Infrastructure

Table of Contents
  • constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer -- Base Renderer Class constructor
  • PHP_CompatInfo_Renderer::factory -- Create required instance of the Output 'driver'
  • PHP_CompatInfo_Renderer::update -- Update the current view
  • PHP_CompatInfo_Renderer::startWaitProgress -- Initialize the wait process
  • PHP_CompatInfo_Renderer::stillWaitProgress -- Update the wait message
  • PHP_CompatInfo_Renderer::endWaitProgress -- Finish the wait process
  • PHP_CompatInfo_Renderer::isIncludable -- Checks if in the include path
Prev | Reference guide | Next
PHP_CompatInfo_Parser::parseData | PEAR Manual | constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer


constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer

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.

Prev | Renderer Infrastructure | Next
Renderer Infrastructure | PEAR Manual | PHP_CompatInfo_Renderer::factory


PHP_CompatInfo_Renderer::factory

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.

Prev | Renderer Infrastructure | Next
constructor PHP_CompatInfo_Renderer::PHP_CompatInfo_Renderer | PEAR Manual | PHP_CompatInfo_Renderer::update


PHP_CompatInfo_Renderer::update

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.

Prev | Renderer Infrastructure | Next
PHP_CompatInfo_Renderer::factory | PEAR Manual | PHP_CompatInfo_Renderer::startWaitProgress


PHP_CompatInfo_Renderer::startWaitProgress

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.

Prev | Renderer Infrastructure | Next
PHP_CompatInfo_Renderer::update | PEAR Manual | PHP_CompatInfo_Renderer::stillWaitProgress


PHP_CompatInfo_Renderer::stillWaitProgress

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.

Prev | Renderer Infrastructure | Next
PHP_CompatInfo_Renderer::startWaitProgress | PEAR Manual | PHP_CompatInfo_Renderer::endWaitProgress


PHP_CompatInfo_Renderer::endWaitProgress

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.

Prev | Renderer Infrastructure | Next
PHP_CompatInfo_Renderer::stillWaitProgress | PEAR Manual | PHP_CompatInfo_Renderer::isIncludable


PHP_CompatInfo_Renderer::isIncludable

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.

Prev | Renderer Infrastructure | Next
PHP_CompatInfo_Renderer::endWaitProgress | PEAR Manual | Array Renderer


Array Renderer

Array Renderer

Table of Contents
  • constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array -- Array Renderer Class constructor
  • PHP_CompatInfo_Renderer_Array::display -- Display final results
Prev | Reference guide | Next
PHP_CompatInfo_Renderer::isIncludable | PEAR Manual | constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array


constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array

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.

Prev | Array Renderer | Next
Array Renderer | PEAR Manual | PHP_CompatInfo_Renderer_Array::display


PHP_CompatInfo_Renderer_Array::display

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.

Prev | Array Renderer | Next
constructor PHP_CompatInfo_Renderer_Array::PHP_CompatInfo_Renderer_Array | PEAR Manual | Csv Renderer


Csv Renderer

Csv Renderer

Table of Contents
  • constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv -- Csv Renderer Class constructor
  • PHP_CompatInfo_Renderer_Csv::display -- Display final results
Prev | Reference guide | Next
PHP_CompatInfo_Renderer_Array::display | PEAR Manual | constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv


constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv

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.

Prev | Csv Renderer | Next
Csv Renderer | PEAR Manual | PHP_CompatInfo_Renderer_Csv::display


PHP_CompatInfo_Renderer_Csv::display

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.

Prev | Csv Renderer | Next
constructor PHP_CompatInfo_Renderer_Csv::PHP_CompatInfo_Renderer_Csv | PEAR Manual | Html Renderer


Html Renderer

Html Renderer

Table of Contents
  • constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html -- Html Renderer Class constructor
  • PHP_CompatInfo_Renderer_Html::display -- Display final results
  • PHP_CompatInfo_Renderer_Html::getStyleSheet -- Returns the custom style sheet
  • PHP_CompatInfo_Renderer_Html::setStyleSheet -- Set a custom style sheet
  • PHP_CompatInfo_Renderer_Html::toHtml -- Returns HTML code
Prev | Reference guide | Next
PHP_CompatInfo_Renderer_Csv::display | PEAR Manual | constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html


constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html

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.

Prev | Html Renderer | Next
Html Renderer | PEAR Manual | PHP_CompatInfo_Renderer_Html::display


PHP_CompatInfo_Renderer_Html::display

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.

Prev | Html Renderer | Next
constructor PHP_CompatInfo_Renderer_Html::PHP_CompatInfo_Renderer_Html | PEAR Manual | PHP_CompatInfo_Renderer_Html::getStyleSheet


PHP_CompatInfo_Renderer_Html::getStyleSheet

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.

Prev | Html Renderer | Next
PHP_CompatInfo_Renderer_Html::display | PEAR Manual | PHP_CompatInfo_Renderer_Html::setStyleSheet


PHP_CompatInfo_Renderer_Html::setStyleSheet

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.

Prev | Html Renderer | Next
PHP_CompatInfo_Renderer_Html::getStyleSheet | PEAR Manual | PHP_CompatInfo_Renderer_Html::toHtml


PHP_CompatInfo_Renderer_Html::toHtml

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.

Prev | Html Renderer | Next
PHP_CompatInfo_Renderer_Html::setStyleSheet | PEAR Manual | Null Renderer


Null Renderer

Null Renderer

Table of Contents
  • constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null -- Null Renderer Class constructor
  • PHP_CompatInfo_Renderer_Null::display -- Consumes output events
Prev | Reference guide | Next
PHP_CompatInfo_Renderer_Html::toHtml | PEAR Manual | constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null


constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null

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.

Prev | Null Renderer | Next
Null Renderer | PEAR Manual | PHP_CompatInfo_Renderer_Null::display


PHP_CompatInfo_Renderer_Null::display

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.

Prev | Null Renderer | Next
constructor PHP_CompatInfo_Renderer_Null::PHP_CompatInfo_Renderer_Null | PEAR Manual | Text Renderer


Text Renderer

Text Renderer

Table of Contents
  • constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text -- Text Renderer Class constructor
  • PHP_CompatInfo_Renderer_Text::display -- Display final results
Prev | Reference guide | Next
PHP_CompatInfo_Renderer_Null::display | PEAR Manual | constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text


constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text

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.

Prev | Text Renderer | Next
Text Renderer | PEAR Manual | PHP_CompatInfo_Renderer_Text::display


PHP_CompatInfo_Renderer_Text::display

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.

Prev | Text Renderer | Next
constructor PHP_CompatInfo_Renderer_Text::PHP_CompatInfo_Renderer_Text | PEAR Manual | Xml Renderer


Xml Renderer

Xml Renderer

Table of Contents
  • constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml -- Xml Renderer Class constructor
  • PHP_CompatInfo_Renderer_Xml::display -- Display final results
Prev | Reference guide | Next
PHP_CompatInfo_Renderer_Text::display | PEAR Manual | constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml


constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml

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.

Prev | Xml Renderer | Next
Xml Renderer | PEAR Manual | PHP_CompatInfo_Renderer_Xml::display


PHP_CompatInfo_Renderer_Xml::display

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.

Prev | Xml Renderer | Next
constructor PHP_CompatInfo_Renderer_Xml::PHP_CompatInfo_Renderer_Xml | PEAR Manual | Command-Line version


Command-Line version

Command-Line version

Table of Contents
  • constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli -- Command-Line Class constructor
  • PHP_CompatInfo_Cli::run -- Run the CLI version
Prev | Reference guide | Next
PHP_CompatInfo_Renderer_Xml::display | PEAR Manual | constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli


constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli

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.

Prev | Command-Line version | Next
Command-Line version | PEAR Manual | PHP_CompatInfo_Cli::run


PHP_CompatInfo_Cli::run

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.

Prev | Command-Line version | Next
constructor PHP_CompatInfo_Cli::PHP_CompatInfo_Cli | PEAR Manual | PHP_FunctionCallTracer


PHP_FunctionCallTracer

PHP_FunctionCallTracer

Creates a function calls debug trace. Functions arguments, returned parameters and watched variables are reported in the same section for each function call. The trace is available as an array, or can be displayed or written in a file. Traced variables can be processed by provided user functions for displaying purposes.

Table of Contents
  • Introduction -- PHP_FunctionCallTracer creates function calls debug trace.
  • Basic Use -- Simple trace of function arguments and returned variables.
Prev | PHP | Next
PHP_CompatInfo_Cli::run | PEAR Manual | Introduction


Introduction

Introduction

Introduction – PHP_FunctionCallTracer creates function calls debug trace.

Overview

Functions arguments, returned parameters and watched variables are reported in the same section for each function call. The trace is available as an array, or can be displayed or written in a file. Traced variables can be processed by provided user functions for displaying purposes.

This package is not a replacement for full fledged PHP debuggers. It is useful for (1) remote debugging, (2) to debug a complex sequence of function calls, (3) to display non text variables in a user readable format.

  1. Remote debugging is sometimes the only option to debug a package that works fine on your system, e.g. a 32-bit OS, but breaks on a different system, e.g. a 64-bit OS, which you have no access to. A remote user who has the latter OS could run the package, then send you the trace for analysis.

  2. It is sometimes difficult not to loose track of functions calls in some live debugging sessions even with top notch PHP editor/debuggers. The trace produced by this package may come handy and is easy to use in combination with the source code to track calls and variables.

  3. Some variables native format does not always display well, typically: packed data and UTF-8 strings. They can be converted as they are being traced to a readable format by provided user functions. For example: converting binary strings to hexadecimal, or UTF-8 string to Unicode.

Prev | PHP_FunctionCallTracer | Next
PHP_FunctionCallTracer | PEAR Manual | Basic Use


Basic Use

Basic Use

Basic Use – Simple trace of function arguments and returned variables.

Overview

traceArguments() is used to trace the function arguments. There is no need to pass the function arguments to traceArguments() to trace them. Note that traceArguments() may not be used, if the function does not call any other function or if the function calls functions that are not being traced.

traceVariables() is used to trace variables within the function. The variables to trace must be passed as arguments to traceVariables(). traceVariables() may be called as many times as required to watch variables value change.

traceReturn() is used to trace the variables returned by the function. The variables to trace must be passed as arguments to traceReturn().

putTrace() is used to display the trace to the standard output or to write it into a file.

How to use PHP_FunctionCallTracer

In this example, package.php contains two classes whose methods are traced. The package is used by an application trace.php. The trace is stored into trace.txt. To generate the trace, run: #php trace.php.

The package package.php

Note that testing if PHP_FunctionCallTracer is loaded: class_exists('PHP_FunctionCallTracer', false), is optional. It is useful only if the tracing methods are meant to be left in the code. They will be called only if PHP_FunctionCallTracer is loaded.

<?php
class math {
    /**
     * tracing the arguments and the returned parameter
     *
     * note that traceReturn() calls traceArguments() by default which is fine here
     * since this method does call other methods to trace
     */
    public static function prod($x, $y)
    {
        // class_exists('PHP_FunctionCallTracer', false)
        // and PHP_FunctionCallTracer::traceArguments();
        $p = $x * $y;

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($p);
        return $p;
    }

    /**
     * tracing the arguments and the returned parameter
     *
     * traceArguments() must be called here since this method calls other methods
     * that may be traced, so that traced calls are displayed in the right order
     */
    public static function square($x)
    {
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceArguments();

        $x2 = self::prod($x, $x);

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($x2);
        return $x2;
    }
}

class geometry {
    private $pi = 3.14;

    /**
     * tracing the arguments and the returned parameter
     * another variable is traced along with the returned parameter
     */
    public function circle($r)
    {
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceArguments();

        $pi2 = 2 * $this->pi;
        $c = math::prod($r, $pi2);

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($c, $pi2);
        return $c;
    }

    /**
     * tracing the arguments, some variables and the returned parameter
     */
    public function disk($r)
    {
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceArguments();

        $r2 = math::square($r);
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceVariables($r2, $this->pi);

        $d = math::prod($r2, $this->pi);

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($d);
        return $d;
    }
}
?>

The application trace.php

<?php
/**
 * adds the path of the package if this is a raw install
 * includes the package (example) to debug and the tracer package
 */
file_exists("../../../../PHP/") and set_include_path('../../../..' . PATH_SEPARATOR . get_include_path());
require_once 'package.php';
require_once 'PHP/FunctionCallTracer.php';

/**
 * creates an instance of the class to debug and calls a few methods
 * writes the trace in a file
 */
$geometry = new geometry;
$c = $geometry->circle(2);
$d = $geometry->disk(3);

$file = dirname(__FILE__) . '/trace.txt';
PHP_FunctionCallTracer::putTrace($file, false);
?>

The trace trace.txt

Array

(

    [php_uname] => Windows NT mybox 5.1 build 2600

    [date] => Friday, 03-Aug-07 09:17:30 UTC

    [calls] => Array

        (

            [0] => Array

                (

                    [call] => Array

                        (

                            [file] => trace.php

                            [line] => 20

                            [function] => geometry->circle

                        )

                    [in] => Array

                        (

                            [file] => package.php

                            [line] => 55

                            [args] => Array

                                (

                                    [0] => 2

                                )

                        )

                    [out] => Array

                        (

                            [file] => package.php

                            [line] => 61

                            [args] => Array

                                (

                                    [0] => 12.56

                                    [1] => 6.28

                                )

                        )

                )

            [1] => Array

                (

                    [call] => Array

                        (

                            [file] => package.php

                            [line] => 58

                            [function] => math::prod

                        )

                    [in] => Array

                        (

                            [file] => package.php

                            [line] => 22

                            [args] => Array

                                (

                                    [0] => 2

                                    [1] => 6.28

                                )

                        )

                    [out] => Array

                        (

                            [file] => package.php

                            [line] => 22

                            [args] => Array

                                (

                                    [0] => 12.56

                                )

                        )

                )

            [2] => Array

                (

                    [call] => Array

                        (

                            [file] => trace.php

                            [line] => 21

                            [function] => geometry->disk

                        )

                    [in] => Array

                        (

                            [file] => package.php

                            [line] => 71

                            [args] => Array

                                (

                                    [0] => 3

                                )

                        )

                    [watches] => Array

                        (

                            [0] => Array

                                (

                                    [file] => package.php

                                    [line] => 75

                                    [args] => Array

                                        (

                                            [0] => 9

                                            [1] => 3.14

                                        )

                                )

                        )

                    [out] => Array

                        (

                            [file] => package.php

                            [line] => 80

                            [args] => Array

                                (

                                    [0] => 28.26

                                )

                        )

                )

            [3] => Array

                (

                    [call] => Array

                        (

                            [file] => package.php

                            [line] => 73

                            [function] => math::square

                        )

                    [in] => Array

                        (

                            [file] => package.php

                            [line] => 35

                            [args] => Array

                                (

                                    [0] => 3

                                )

                        )

                    [out] => Array

                        (

                            [file] => package.php

                            [line] => 40

                            [args] => Array

                                (

                                    [0] => 9

                                )

                        )

                )

            [4] => Array

                (

                    [call] => Array

                        (

                            [file] => package.php

                            [line] => 37

                            [function] => math::prod

                        )

                    [in] => Array

                        (

                            [file] => package.php

                            [line] => 22

                            [args] => Array

                                (

                                    [0] => 3

                                    [1] => 3

                                )

                        )

                    [out] => Array

                        (

                            [file] => package.php

                            [line] => 22

                            [args] => Array

                                (

                                    [0] => 9

                                )

                        )

                )

            [5] => Array

                (

                    [call] => Array

                        (

                            [file] => package.php

                            [line] => 77

                            [function] => math::prod

                        )

                    [in] => Array

                        (

                            [file] => package.php

                            [line] => 22

                            [args] => Array

                                (

                                    [0] => 9

                                    [1] => 3.14

                                )

                        )

                    [out] => Array

                        (

                            [file] => package.php

                            [line] => 22

                            [args] => Array

                                (

                                    [0] => 28.26

                                )

                        )

                )

        )

    [objects] => Array

        (

            [0] => geometry Object

                (

                    [pi:private] => 3.14

                )

            [2] => same as #0

        )

)

Prev | PHP_FunctionCallTracer | Next
Introduction | PEAR Manual | PHP_UML


PHP_UML

PHP_UML

A PHP parser coupled with an XMI generator

Table of Contents
  • Introduction -- Purpose and simple usage example
  • Command line interface -- How to run PHP_UML from the command line?
  • API -- How to use PHP_UML from its API?
  • Conversion rules -- How do PHP elements map to UML concepts?
Prev | PHP | Next
Basic Use | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Purpose and simple usage example

Description

PHP_UML is a reverse-engineering tool, and a documentation tool.

It can parse PHP files and directories, and generate:

  • An XMI file, reflecting the object structure of the code parsed; you can then import that file into a CASE tool (such as Rational Rose)

  • A full HTML API documentation, very similar to Javadoc

  • PHP code skeletons (useful if you have an existing XMI file, and want to generate the files, folders and class declarations all at once)

XMI is an OMG standard for exchanging metadata information via XML, and is commonly used as an interchange format for UML models. Many UML softwares support importing and exporting of XMI files.

Features

Like PhpDocumentor, PHP_UML can parse the following PHP elements: namespaces, classes, interfaces, properties, and functions. It can also retrieve information from the inline comments, via the docblocks: @package, @var, @param

  • @param and @var learn PHP_UML about the expected types of a parameter or a property.

  • @package learns PHP_UML about the namespace of an element (even if, from PHP 5.3, it is recommended to use the PHP namespacing instructions instead)

So the more documented your PHP code is, the more precise your XMI file, or your API documentation, will be.

At the current time, the UML/XMI standards exist in two distinct families of versions, 1.x and 2.x. PHP_UML can generate XMI in version 1.4, as well as in version 2.1. Be warned, though, that some UML tools might not interpret accurately the data contained in your XMI file. For example, the link between a UML artifact (a source file) and the classes defined inside that artifact is only available from version 2 of UML.

PHP_UML can also convert existing UML/XMI data from version 1.4 to version 2 (simple conversion).

Usage

You can use PHP_UML either from command line, or by writing a piece of code that will exploit the API.

Parsing a single file test.php, and generating its XMI file:

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

$uml = new PHP_UML();
$uml->parseFile('test.php');
$uml->generateXMI(1);             // UML version number (1 or 2)
$uml->saveXMI('test.xmi');
?>

Compatibility of XMI

Your UML/XMI code might be interpreted differently by the modeling tool you are going to use along with PHP_UML. This is particularly true for the version 2 of UML/XMI. For instance, the Eclipse plug-ins (EMF, Papyrus) only accept a particular flavour of XMI, called ecore, which is only partly compatible with the one you will get with PHP_UML.

Extension

PHP_UML is designed with evolution in mind. By choosing XMI as the pivot format for representing object oriented program structures, PHP_UML can not only interface with many design tools. It can also be transformed, through XSLT, into many other formats, like the HTML API documentation generator, included in PHP_UML.

To start your own transformation, create a folder under /Output, and create a main.xsl file inside (you can copy the one in /Output/html). Run the method PHP_UML->export(), passing the name of your format as the first parameter.

Instead of transforming XMI code, another way to create new output formats is to write a PHP class that will directly exploit the metamodel that the parser has built, exactly like the package XMI does.

If you are interested by the PHP_UML project, and want to participate, do not hesitate to contact me.

Prev | PHP_UML | Next
PHP_UML | PEAR Manual | Command line interface


Command line interface

Command line interface

Command line interface – How to run PHP_UML from the command line?

Install

The executable phpuml relies on Console::CommandLine. If you have followed the normal PEAR installation process to install PHP_UML, that dependency should have been resolved, and you should be able to run phpuml directly from the command line.

Arguments

Pass the files and/or the directories to parse as arguments:

$ phpuml /var/www/foo

Separate the different elements by a space:

$ phpuml /var/www/file1.php file2.php

By default, phpuml will recursively parse the specified files/folders, and will echo the XMI code on the screen (UML/XMI version 2).

Options

Renaming the UML model name

By default, the root package of a UML model is named default. To rename it, use the option -n:

$ phpuml /var/www/foo -n MyProject

Saving to a file

To save the XMI data in a particular place, instead of printing it on the screen, use -o:

$ phpuml /var/www/foo -n MyProject -o /var/tmp/

This will parse /var/www/foo, and save the XMI data to /var/tmp/MyProject.xmi. Use the dot to save to the current directory: -o .

The option -o also accepts a file name, instead of a directory path.

Generating PHP code or HTML API documentation

In addition to xmi, 2 output formats are also available: html, and php. They work by applying an XSL transformation to the XMI data (in UML version 2).

Use the option -f to specify which format you want phpuml to generate.

$ phpuml /var/www/foo -f html -o /var/tmp/

This will scan /var/www/foo, and create a full HTML documentation in /var/tmp/.

If you need to provide your own XMI file, instead of parsing existing files, simply pass it as argument.

$ phpuml myFile.xmi -f php -o /var/tmp/

This will read the XMI code contained in myFile.xmi, and generate the PHP code templates in /var/tmp/.

Selecting the UML/XMI version

To select which version of the UML/XMI standards you want your XMI to be written in, use the option -x:

$ phpuml /var/www/foo -x 1 -o /var/tmp/

Note that Argouml accepts XMI code only in version 1, while the Eclipse plugins (Ecore standard) only in version 2.

Converting from UML/XMI version 1 to 2

phpuml automatically converts UML/XMI data in version 1.4 to version 2.1.

$ phpuml foo1.xmi -o foo2.xmi

This will read foo1.xmi, and, if its XMI content is in version 1, converts it to version 2, and stores it in foo2.xmi. Note that this is an ad hoc conversion, inspired on what Rationale Rose, Argouml and Umbrello generate. It does not convert all of the UML entities, and it does not interpret all of the various XMI dialects.

Filtering the files to parse

By default, phpuml will parse only files with the extension .php. To modify this file pattern, use the - m selector:

$ phpuml /var/www/foo -m *.php *.txt

This will parse all php and txt files.

Other options are available (like an option to exclude certain files or directories to parse). You will discover them all by asking for help, like this:

$ phpuml -h
Prev | PHP_UML | Next
Introduction | PEAR Manual | API


API

API

API – How to use PHP_UML from its API?

Principles

PHP_UML is structured in 5 packages:

  • The main package, which contains the main class (PHP_UML) and some utility classes

  • The PHP package, where the PHP parser resides

  • The Metamodel package, which contains the data structures that PHP_UML is using to modelize the code parsed

  • The XMI package, which contains classes that can serialize a metamodel into XMI code

  • The Output package, which contains all the stuff to transform XMI into another format (like HTML)

But the only class you need to know about is PHP_UML. Since the first release of the package, the API of that class has changed a little bit, and you will find several methods doing more or less the same job.

Examples

Parsing of a single file test.php, and generation of its XMI file:

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

$uml = new PHP_UML();
$uml->setInput('test.php');
$uml->parse('foo');           // parses, and sets the name of the root package
$uml->generateXMI(1);         // generates XMI in version 1
$uml->saveXMI('test.xmi');
?>

Note that, since UML is a strong object-oriented standard, PHP_UML ignores all global functions, or global constants.

Parsing of two directories, ignoring the CSV folders, and generation of HTML documentation

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

$uml = new PHP_UML();
$uml->setInput(array('C:\Inetpub\foo', 'C:\Inetpub\libraries'));
$uml->parse();
$uml->generateXMI(2);
$uml->export('html', 'C:\Inetpub\api');
?>

Import of a XMI file, and generation of PHP code templates

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

$uml = new PHP_UML();
$uml->readXMIFile('foo.xmi');
$uml->export('php', 'C:\Inetpub\foo');
?>
Prev | PHP_UML | Next
Command line interface | PEAR Manual | Conversion rules


Conversion rules

Conversion rules

Conversion rules – How do PHP elements map to UML concepts?

Logical view

  • A PHP class (or interface) maps to an UML Class (or Interface).

  • A PHP function maps to an UML Operation.

  • A PHP property, or class constant, maps to an UML Attribute.

Packages do not exist in PHP, like they do in Java. There are two possible ways to mimic them:

  • by using the PHP namespace instruction

  • by using the docblock @package in the comment of a class (or of a file)

Note that the namespace and use instructions will be parsed only if you run PHP_UML with PHP from version 5.3.

Deployment view

  • A PHP file maps to an UML Artifact.

  • A physical folder maps to an UML Package.

Component view

In UML 1.4:

  • A class (or an interface) maps to an UML Component.

  • A logical package maps to an UML Subpackage.

In UML 2.1:

  • A class (or an interface) maps to an UML Component.

  • A logical package maps to a nesting UML Component.

Prev | PHP_UML | Next
API | PEAR Manual | PHPUnit


PHPUnit

PHPUnit

Provides a simple framework for creating a test application to automate testing of functions and classes.

Table of Contents
  • Tutorial -- A short tutorial about PHPUnit
  • PHPUnit::run() -- runs a TestSuite and returns a TestResult object.
  • PHPUnit::TestCase -- A TestCase defines the fixture to run multiple tests.
Prev | PHP | Next
Conversion rules | PEAR Manual | Tutorial


Tutorial

Tutorial

Tutorial – A short tutorial about PHPUnit

A short introduction to the test framework

PHPUnit provides a simple framework for creating a test suite to automate testing of functions and classes. PHPUnit is inspired by JUnit which was created by Kent Beck and Erich Gamma as a tool for eXtreme Programming. One of the rules of XP is to test small software components as often and early as possible, this way you will not have to fix bugs and errors in the API while setting up and testing larger applications which depend on the class. While unit testing is one of the fundimental rules in XP, you don't have to switch to XP to benefit from PHPUnit. PHPUnit stands alone as a good tool for testing classes or a set of functions and will ease your development cycle and help you to avoid endless debug sessions.

Work routine

Normally, you would write a class, do some unsystematic tests using echo() or var_dump(). After this, you use the class in your application and hope everything is ok. To benefit from PHPUnit you should rethink the flow. The best way is to do this:

  • 1. design your class/API

  • 2. create a test suite

  • 3. implement the class/API

  • 4. run the test suite

  • 5. fix failures or errors and go to #4 again

It may seem that this will require a lot of time, but this impression is wrong. Creating the test suite using PHPUnit needs only a few minutes and running the test suite only seconds.

Design a class

Let's start with a small example: a string class. First we create a bunch of functions declarations to work on a string:

---- string.php ----

<?php
class String
{
    //contains the internal data
    var $data;

    // constructor
    function String($data) {
        $this->data = $data;
    }

    // creates a deep copy of the string object
    function copy() {
    }

    // adds another string object to this class
    function add($string) {
    }

    // returns the formated string
    function toString($format) {
    }
}
?>

Creating test suite

Now we can create a test suite, which checks every function of your string class. A test suite is normal PHP class inherited from PHPUnit_TestCase containing test functions, identified by a leading 'test' in the function name. In the test function an expected value has to be compared with the result of the function to test. The result of this compare must delegate to a function of the assert*()-family, which decides if a function passes or fails the test.

---- testcase.php ----

<?php

require_once 'string.php';
require_once 'PHPUnit.php';

class StringTest extends PHPUnit_TestCase
{
    // contains the object handle of the string class
    var $abc;

    // constructor of the test suite
    function StringTest($name) {
       $this->PHPUnit_TestCase($name);
    }

    // called before the test functions will be executed
    // this function is defined in PHPUnit_TestCase and overwritten
    // here
    function setUp() {
        // create a new instance of String with the
        // string 'abc'
        $this->abc = new String("abc");
    }

    // called after the test functions are executed
    // this function is defined in PHPUnit_TestCase and overwritten
    // here
    function tearDown() {
        // delete your instance
        unset($this->abc);
    }

    // test the toString function
    function testToString() {
        $result = $this->abc->toString('contains %s');
        $expected = 'contains abc';
        $this->assertTrue($result == $expected);
    }

    // test the copy function
    function testCopy() {
      $abc2 = $this->abc->copy();
      $this->assertEquals($abc2, $this->abc);
    }

    // test the add function
    function testAdd() {
        $abc2 = new String('123');
        $this->abc->add($abc2);
        $result = $this->abc->toString("%s");
        $expected = "abc123";
        $this->assertTrue($result == $expected);
    }
  }
?>

The first test run

Now, we can run a first test. Make sure that all the paths are correct and then execute this PHP program.

---- stringtest.php ----

<?php

require_once 'testcase.php';
require_once 'PHPUnit.php';

$suite  = new PHPUnit_TestSuite("StringTest");
$result = PHPUnit::run($suite);

echo $result -> toString();
?>

If you call this script from the commandline, you will get the following output:

TestCase stringtest->testtostring() failed: expected true, actual false
TestCase stringtest->testcopy() failed: expected , actual Object
TestCase stringtest->testadd() failed: expected true, actual false

Every function fails the test, because your string functions didn't returned what we defined as the expected value.

If you want to call the script through your browser, you have to put the script in a correct html page and call $result->toHTML () instead of $result->toString().

Implementation

Ok, let's start with implementation of the our string class.

---- string.php ----

<?php
class String
{
    //contains the internal data
    var $data;

    // constructor
    function String($data) {
        $this->data = $data;
    }

    // creates a deep copy of the string object
    function copy() {
        $ret = new String($this->data);
        return $ret;
    }

    // adds another string object to this class
    function add($string) {
        $this->data = $this->data.$string->toString("%ss");
    }

    // returns the formated string
    function toString($format) {
        $ret = sprintf($format, $this->data);
        return $ret;
    }
}
?>

The implementation is complete and we can run the test again:

~>
php -f stringtest.php
TestCase stringtest->testtostring() passed
TestCase stringtest->testcopy() passed
TestCase stringtest->testadd() failed: expected true, actual false

D'oh! the last test failed! We made a typing mistake. Change line 16 in string.php to

<?php
$this->data = $this->data.$string->toString("%s");
?>

and run the test again:

~>
php -f stringtest.php
TestCase stringtest->testtostring() passed
TestCase stringtest->testcopy() passed
TestCase stringtest->testadd() passed

Everything is now OK!

Conclusion

Does it seem like a lot of work for testing three simple functions? Don't forget, this is a small example. Think about bigger, more complex API's like database abstraction or basket classes in a shop application. PHPUnit is an excellent tool to detect errors in the implementation of your class.

Often you will want to reimplement or refactor a large class which is used in several different applications. Without a test suite the likeliness of you breaking something in one of the applications that depends on your class is very high. Thanks to unit tests, you can create a test suite for your class, and then reimplement your class with the security of knowing that as long as the new class passes the tests, applications that depend on the class will work.

Prev | PHPUnit | Next
PHPUnit | PEAR Manual | PHPUnit::run()


PHPUnit::run()

PHPUnit::run()

PHPUnit::run() – runs a TestSuite and returns a TestResult object.

Synopsis

require_once 'PHPUnit.php';

object PHPUnit::run ( object $suite )

Description

Executes the given test suite

Parameter

  • object $suite - an object of PHPUnit_TestSuite

Return value

&PHPUnit_Result - A reference to a PHPUnit_Result.

Example

Using PHPUnit::run()

<?php
require_once "PHPUnit.php";
$suite  = New PHPUnit_TestSuite('Mathtest');
$result = PHPUnit::run($suite);
echo $result->toHtml();
?>
Prev | PHPUnit | Next
Tutorial | PEAR Manual | PHPUnit::TestCase


PHPUnit::TestCase

PHPUnit::TestCase

PHPUnit::TestCase – A TestCase defines the fixture to run multiple tests.

To define a TestCase

  • 1) Implement a subclass of PHPUnit_TestCase.

  • 2) Define instance variables that store the state of the fixture.

  • 3) Initialize the fixture state by overriding setUp().

  • 4) Clean-up after a test by overriding tearDown().

Each test runs in its own fixture so there can be no side effects among test runs.

PHPUnit::TestCase

<?php
    class MathTest extends PHPUnit_TestCase {
      var $fValue1;
      var $fValue2;

      function MathTest($name) {
        $this->PHPUnit_TestCase($name);
      }

      function setUp() {
        $this->fValue1 = 2;
        $this->fValue2 = 3;
      }
    }
    ?>

For each test implement a method which interacts with the fixture. Verify the expected results with assertions specified by calling assert with a boolean.

<?php
function testPass() {
      $this->assertTrue($this->fValue1 + $this->fValue2 == 5);
    }
?>
Prev | PHPUnit | Next
PHPUnit::run() | PEAR Manual | PHPUnit2


PHPUnit2

PHPUnit2

PHPUnit is a family of PEAR packages (PHPUnit2 for PHP 5, PHPUnit for PHP 4) that supports the development of object-oriented PHP applications using the concepts and methods of Agile Software Development, Extreme Programming, Test-Driven Development and Design-by-Contract Development by providing an elegant and robust framework for the creation, execution and analysis of Unit Tests.

Table of Contents
  • Summary
Prev | PHP | Next
PHPUnit::TestCase | PEAR Manual | Summary


Summary

Summary

Summary – Summary

Where to find more information

You can find more information about this package at the following url PHPUnit wiki

Prev | PHPUnit2 | Next
PHPUnit2 | PEAR Manual | QA Tools


QA Tools

QA Tools

Tools to ensure the quality of something.

Table of Contents
  • QA_Peardoc_Coverage
  • QA_Pear_PackageStatus
Prev | PEAR Packages | Next
Summary | PEAR Manual | QA_Peardoc_Coverage


QA_Peardoc_Coverage

QA_Peardoc_Coverage

Documentation coverage analysis for the PEAR packages documentation.

Daily updated pear documentation stats can be found at pear.cweiske.de/coverage/.

Table of Contents
  • Introduction -- What QA_Peardoc_Coverage is good for
  • How it works -- The global picture
  • Generating coverage analysis -- Step by step
Prev | QA Tools | Next
QA Tools | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What QA_Peardoc_Coverage is good for

About QA_Peardoc_Coverage

A great library is almost useless without documentation. PEAR has over 300 packages, automatically generated API documentation and a manual. The PEAR manual (the one you are reading) shall provide an overview on the packages and instructions about how to use them, and give an understanding about the classes in a package, and their methods. Further information about them can looked up in the API docs.

With the amount of packages PEAR provides, it's hard to keep track of the state of documentation of the packages - a tool to track this was needed. QA_Peardoc_Coverage is its incarnation.

QA_Peardoc_Coverage uses a CVS checkout of PEAR and PEARDOC to find out which packages are documented, which classes and method are mentioned in the docs, and which developers do a good job in documenting their code.

Prev | QA_Peardoc_Coverage | Next
QA_Peardoc_Coverage | PEAR Manual | How it works


How it works

How it works

How it works – The global picture

How it works

The documentation analysis report generation is split into two processes:

  1. Collect data and save it

  2. Generate different reports from saved data

This was chosen because the data collection step takes a long time (~ 1 minute), but it's needed for every single report. So if you want to generate the simple doc coverage, and the extended one, you need the same base data - you just display it in a different way.

generateCoverage() in QA_Peardoc_Coverage generates and returns the array with the computed coverage data. It can be serialized and saved, since all the Renderer classes use it as input.

Classes implementing the QA_Peardoc_Coverage_Renderer interface provide a render() method that takes the data returned by generateCoverage() and return the analysis, most times a string containing HTML code.

Prev | QA_Peardoc_Coverage | Next
Introduction | PEAR Manual | Generating coverage analysis


Generating coverage analysis

Generating coverage analysis

Generating coverage analysis – Step by step

Generating coverage analysis data

  1. Make sure you have a fresh checkout of pear and peardoc directories from cvs.php.net.

  2. Configure peardoc to generate the manual.xml in there ( autoconf, ./configure).

  3. Call genData.php with the path to peardoc's manual.xml as first, and path to the pear cvs directory as second parameter.

  4. A file called doc.dat will be generated in the current working directory.

Generating HTML reports

Once the coverage data is generated and serialized, you can generate some HTML reports. For this, the packages provides four Renderer classes that all implement the QA_Peardoc_Coverage_Renderer interface:

  • QA_Peardoc_Coverage_Renderer_DeveloperList lists all developers with the number of packages they have, the number of undocumented packages and lists the undocumented ones. The list is sorted by percentage of documented packages.

  • QA_Peardoc_Coverage_Renderer_SimplePackageList lists all categories in PEAR, the packages in them and shows which of them have docs and which not. A final summary with the total number of existing and documented packages, and a percentage number is also given.

  • QA_Peardoc_Coverage_Renderer_ExtendetPackageList is similar to the simple list, but also shows the package's classes, their documentation state and their methods and their doc state. This list can be used to check which methods aren't yet covered by your documentation.

  • QA_Peardoc_Coverage_Renderer_MissingDocsPerDeveloper generates an array of developer email => array(package names) assignments that can be used as base data to send reminder emails.

All the renderers have a examples/gen*.php file that uses the doc.dat file written by examples/genData.php. They echo the html to the console, so you should redirect it into a file.

Prev | QA_Peardoc_Coverage | Next
How it works | PEAR Manual | QA_Pear_PackageStatus


QA_Pear_PackageStatus

QA_Pear_PackageStatus

Simple little tool that walks over a checkout of PEAR's CVS directory (pear) and reports the following issues:

  • Version of package.xml

  • If the version in package.xml is missing

  • Package stability

  • Last release date

  • Time since the last release

After listing this stats for each single package, a summary of percentages is given.

Daily updated package stats can be found at pear.cweiske.de/packagestatus/.

Prev | QA Tools | Next
Generating coverage analysis | PEAR Manual | Streams


Streams

Streams

Provides Packages for streams API. For more information on stream wrappers see the PHP Manual.

Table of Contents
  • Stream_Var
Prev | PEAR Packages | Next
QA_Pear_PackageStatus | PEAR Manual | Stream_Var


Stream_Var

Stream_Var

Allows stream based access to variables.

Table of Contents
  • Introduction -- Introduction to Stream_Var
  • Example -- Example for the usage of Stream_Var
Prev | Streams | Next
Streams | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Stream_Var

Introduction to Stream_Var

Stream_Var supplies a class that can be used as a wrapper
for PHP's stream functions. This allows you to access variables
with fopen(), fclose(),
fwrite(), fread(),
opendir() and all other filesystem functions.

You may use stream_wrapper_register() to register Stream_Var as a wrapper.

Scalar variables (strings, integers, floats) are treated as files, while arrays represent directories.

Please see the PHP Manual or the example for more information on how to register streams.

Usage scenario

Stream_Var could be used in various scenarios. Imagine you are using a class that reads data from a file but you are creating the data on-the-fly and do not want to save the data before it can be processed by the class.

This is where Stream_Var can be used. Just register it as a wrapper for fopen() and pass var://GLOBAL/yourVar as a parameter to the class.

It will read from the variable as if it was a file.

Prev | Stream_Var | Next
Stream_Var | PEAR Manual | Example


Example

Example

Example – Example for the usage of Stream_Var

Registering the wrapper

The following example shows you how to register Stream_Var as a wrapper for the stream functions.

Registering Stream_Var

<?php
require_once "Stream/Var.php";
stream_wrapper_register( "var", "Stream_Var" );
?>

Accessing scalar variables

The following example show you how to
access scalar variables with fopen(),
fread(), frwite()
and fclose().

Accessing scalar variables

<?php
require_once "Stream/Var.php";
stream_wrapper_register( "var", "Stream_Var" );
$foo = "I really like tomatoes.";

echo "Content of foo: $foo<br />";

$fp = fopen('var://GLOBALS/foo','r+');

$data = fread($fp, 9);
echo "Read from stream: $data<br />";

fwrite($fp,"hate");

fclose($fp);

echo "Content of foo: $foo<br />";
?>

Accessing an array

The following example shows how to use opendir() to access an array.

Accessing an array

<?php
require_once "Stream/Var.php";
stream_wrapper_register( "var", "Stream_Var" );
$dirname = 'var://_SERVER';
$dir = opendir($dirname);
echo    "<strong>opening directory '$dirname'</strong><br><br>";

while ($entry = readdir($dir)) {
    echo "opening file $dirname/$entry<br />";
    if (!$fp = @fopen($dirname."/".$entry,"r")) {
        echo "seems to be a directory<br /><br />";
        continue;
    }

    echo "reading from $entry<br />";
    while (!feof($fp)) {
        echo fread($fp, 16);
    }
    fclose($fp);
    echo    "<br /><br />";
}
closedir($dir);
?>

More examples

If you want to take a look at some more examples, just install the package and they will be installed in the docs directory.

Prev | Stream_Var | Next
Introduction | PEAR Manual | Structures


Structures

Structures

Provides structures-related Packages

Table of Contents
  • Structures_BibTex
  • Structures_DataGrid
  • Games_Chess
  • Structures_Graph
  • Structures_LinkedList
  • Structures_Tree
Prev | PEAR Packages | Next
Example | PEAR Manual | Structures_BibTex


Structures_BibTex

Structures_BibTex

Parsing BibTex Data to an array and exporting to BibTex and RTF.

Table of Contents
  • Introduction -- Introduction to Structures_BibTex
  • Warnings -- Usage of warnings when using Structures_BibTex
  • Exporting -- Possibility to export the data using Structures_BibTex
  • Miscellaneous -- Miscellaneous methods in the class Structures_BibTex
Prev | Structures | Next
Structures | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Structures_BibTex

Overview

This package provides methods to access information stored in a BibTex file. During parsing it is possible to let the data be validated. In addition. the creation of BibTex Strings as well as RTF Strings is also supported.

A few examples

Loading a BibTex File and printing the parsed array

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo '<pre>';
print_r($bibtex->data);
echo '</pre>';
?>

Options

Options can be set either in the constructor or with the method setOption(). When setting in the constructor the options are given in an associative array. The options are:

  • stripDelimiter (default: true) Stripping the delimiter surrounding the entries.

  • validate (default: true) Validation while parsing.

  • unwrap (default: false) Unwrapping entries while parsing.

  • wordWrapWidth (default: false) If set to a number higher one that the entries are wrapped after that amount of characters.

  • wordWrapBreak (default: \n) String used to break the line (attached to the line).

  • wordWrapCut (default: 0) If set to zero the line will we wrapped at the next possible space, if set to one the line will be wrapped exactly after the given amount of characters.

  • removeCurlyBraces (default: false) If set to true Curly Braces will be removed.

Example of setting options in the constructor:

Setting options in the constructor

<?php
$bibtex = new Structures_BibTex(array('validate'=>false, 'unwrap'=>true));
?>

Example of setting options using the method setOption():

Setting options using setOption

<?php
$bibtex = new Structures_BibTex();
                $bibtex->setOption('validate', false);
                $bibtex->setOption('unwrap', true);
?>

Stored Data

The data is stored in the class variable data. This is a a list where each entry is a hash table representing one bibtex-entry. The keys of the hash table correspond to the keys used in bibtex and the values are the corresponding values. Some of these keys are:

  • cite - The key used in a LaTeX source to do the citing.

  • entryType - The type of the entry, like techreport, book and so on.

  • author - One or more authors of the entry. This entry is also a list with hash tables representing the authors as entries. The author has table is explained later.

  • title - Title of the entry.

Author

As described before the authors are stored in a list. Every entry representing one author as a has table. The hash table consits of four keys: first, von, last and jr. The keys are explained in the following list:

  • first - The first name of the author.

  • von - Some names have a 'von' part in their name. This is usually a sign of nobleness.

  • last - The last name of the author.

  • jr - Sometimes a author is the son of his father and has the same name, then the value would be jr. The same is true for the value sen but vice versa.

Adding an entry

To add an entry simply create a hash table with the needed keys and values and call the method addEntry().

Adding an entry

<?php
$bibtex                         = new Structures_BibTex();
$addarray                       = array();
$addarray['entryType']          = 'Article';
$addarray['cite']               = 'art2';
$addarray['title']              = 'Titel of the Article';
$addarray['author'][0]['first'] = 'John';
$addarray['author'][0]['last']  = 'Doe';
$addarray['author'][1]['first'] = 'Jane';
$addarray['author'][1]['last']  = 'Doe';
$bibtex->addEntry($addarray);
?>
Prev | Structures_BibTex | Next
Structures_BibTex | PEAR Manual | Warnings


Warnings

Warnings

Warnings – Usage of warnings when using Structures_BibTex

Overview

The class Structures_BibTex introduces a system to collect warnings that may happen during parsing. Warnings are things in the BibTex source which are not correct but do not cause the parser to fail. One example would be a double cite entry. These warnings should help to improve the quality of your BibTex code. Whether warnings are generated or not is controlled by the option validate. Per default warnings are generated. If you want to not generate warnings you should use the setOption() method like this.

Switching off creation of warnings

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$bibtex->setOption('validate', false);
?>

Usage

The warnings are stored in an array called warnings which is public accessible. To check is a warning exists you can use the method hasWarning(). This method returns true if there are warnings and false otherwise.

Checking for warnings

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
if ($bibtex->hasWarning()) {
    print 'There are warnings!<br />';
}
?>

Every warning itself is hash table with the following keys:

  • warning - Type of the warning

  • entry - The line that caused the warning

  • wholeentry - The whole entry in which the warning occurred

To print every warning with type and line that caused the warning you could do something like this:

Checking for warnings

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
if ($bibtex->hasWarning()) {
    foreach ($bibtex->warnings as $warning) {
        echo 'Warning: '.$warning['warning'].'<br />';
        echo 'Line: '.$warning['entry'].'<hr />';
    }
}
?>

Finally if you want to clear all warnings you can use the method clearWarnings().

Types of Warnings

The following Warnings are known:

  • WARNING_MISSING_END_BRACE - This warning is generated when the end brace in an entry is missing. Take this warning seriously!

  • WARNING_AT_IN_BRACES - A Value is delimited by Braces. Then inside a @ is not allowed.

  • WARNING_ESCAPED_DOUBLE_QUOTE_INSIDE_DOUBLE_QUOTES - A Value is delimited by double quotes. Then inside no escaped double quote is allowed.

  • WARNING_UNBALANCED_AMOUNT_OF_BRACES - The amount of braces inside a value is not equal (opening and closing). The parses fails if in the complete entry this amount is not correct. But if only on an entry it is not correct then this is only a warning. As a matter of fact of the parser does not fail but there is an unbalanced amount of braces in an entry this warning has to be generated something times two.

  • WARNING_MULTIPLE_ENTRIES - Every entry is identified by a unique string. This warning is created if there are at least two entries with the same identification.

  • WARNING_LINE_WAS_NOT_CONVERTED - This warning is created if during exporting (for example in RTF or HTML) one entry was ignored because of no matching data in the entry. At least one of the following entries have to exist in the entry to get converted: title, journal, year or authors.

  • STRING_ENTRY_NOT_YET_SUPPORTED - BibTex defines some special entry types, String is one of them and is used to define abbreviations. This is not yet supported by Structres_BibTex.

  • PREAMBLE_ENTRY_NOT_YET_SUPPORTED - BibTex defines some special entry types, Preamble is one of them and is used to define formatted code. This is not yet supported by Structres_BibTex.

  • WARNING_NOT_ALLOWED_ENTRY_TYPE - BibTex allows to define own types. This warning is genereated when a type was detected which is not part of the standard types. The allowed or standard type are defined in the class variable allowedTypes as array.

Prev | Structures_BibTex | Next
Introduction | PEAR Manual | Exporting


Exporting

Exporting

Exporting – Possibility to export the data using Structures_BibTex

Overview

The class Structures_BibTex provides some methods to export the data stored in the class. Currently the class exports the data in the following formats:

  • BibTeX - The whole data in BibTeX

  • RTF - The data with enough matching data as a short list in RTF format

  • HTML - The data with enough matching data as a short list in HTML format

Author

The default is to export the name of the author in this format: "VON LAST, JR, FIRST". The corresponding placeholder will be substituted. The placeholders have to be uppercase. The format string is defined in the class variable authorstring. Changing the ouput of the author in the entries to this format "FIRST LAST" can be done like this:

Changing author format

<?php
require_once 'Structures/BibTex.php';
$bibtex               = new Structures_BibTex();
$bibtex->authorstring = 'FIRST LAST';
?>

BibTeX

One of the basic features is of course the export in BibTeX format. This is simply done by invoking the bibTex() method.

Exporting in BibTeX format

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo 'The data in BibTeX format:<br />';
echo $bibtex->bibTex();
?>

RTF

This feature was introduced to enable some kind of import into Word. Word (of course also Open Office or kword) understands the RTF format. It is simply possible to save the output as 'somefile.rtf' and be opened in Word. This will satisfy the Windows users. To use it simply call the method rtf().

Exporting in RTF format

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo 'The data in RTF format:<br />';
echo $bibtex->rtf();
?>

The default format for every entry is first the authors, then the title bold and in double quotes, then the journal italic and finally the year. To change the default format you should override the class variable rtfstring. The default rtfstring looks like this: 'AUTHORS, "{\b TITLE}", {\i JOURNAL}, YEAR'. The string AUTHORS, TITLE, JOURNAL and YEAR are substituted with the corresponding values.

Exporting in RTF format with different RTF string

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
$bibtex->rtfstring  = 'AUTHORS, "TITLE", JOURNAL, YEAR';
echo 'The data in RTF format (but this time plain):<br />';
echo $bibtex->rtf();
?>

HTML

This feature is just a simple HTML generation. The default formatting is the same as in rtf. To use it call the method html().

Exporting in HTML format

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
echo 'The data in HTML format:<br />';
echo $bibtex->html();
?>

As with the RTF export it is possible to override the default HTML string.The default string is stored in the class variable htmlstring and looks like this: AUTHORS, "<strong>TITLE</strong>", <em>JOURNAL</em>, YEAR<br />.

Exporting in HTML format with different HTML string

<?php
require_once 'Structures/BibTex.php';
$bibtex = new Structures_BibTex();
$ret    = $bibtex->loadFile('foo.bib');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
$bibtex->parse();
$bibtex->htmlstring  = 'AUTHORS, "TITLE", JOURNAL, YEAR';
echo 'The data in HTML format (but this time plain):<br />';
echo $bibtex->html();
?>
Prev | Structures_BibTex | Next
Warnings | PEAR Manual | Miscellaneous


Miscellaneous

Miscellaneous

Miscellaneous – Miscellaneous methods in the class Structures_BibTex

Overview

On this page miscellaneous methods of the class Structures_BibTex are described. These methods include:

  • amount - The amount of BibTex entries

  • getStatistic - Statistics about BibTex entries

amount

This method simply returns the amount of BibTex entries which are currently stored in the class. The value is returned as Integer value.

getStatistic

This methods returns an array with a statistic about all error types together with the amount. The keys are the types and the values the amount in integer.

Prev | Structures_BibTex | Next
Exporting | PEAR Manual | Structures_DataGrid


Structures_DataGrid

Structures_DataGrid

Structures_DataGrid is a class for building, manipulating and rendering a tabular structure of data. It has the ability to allow you to render a datagrid in HTML format as well as many other formats such as an XML Document, an Excel Spreadsheet, an XUL Document and more.

It also offers paging and sorting functionality to limit the data that is presented. This concept is based on the .NET Framework DataGrid control and works very well with database and XML result sets.

Table of Contents
  • Introduction and Features
  • Class Structures_DataGrid
  • Class Structures_DataGrid_Column
  • DataSource drivers
  • Renderer drivers
Prev | Structures | Next
Miscellaneous | PEAR Manual | Introduction and Features


Introduction and Features

Introduction and Features

Table of Contents
  • Introduction -- What can I do with Structures_DataGrid?
  • FAQ -- Answers to most Frequently Asked Questions
  • Installation -- How to install the core and drivers packages
  • DataSources -- What is a DataSource driver?
  • Rendering the output -- What formats can I render the output?
  • Streaming -- How to stream large recordsets
  • Column Formatter -- What can I do with the column formatter?
  • Example - Quick -- Quickly retrieve data from a database table
  • Example - Complex -- How to build a datagrid using many of the features
  • Custom DataSources -- How to write your own DataSource driver.
  • Custom Renderers -- How to write your own Rendering driver.
Prev | Structures_DataGrid | Next
Structures_DataGrid | PEAR Manual | Introduction


Introduction

Introduction

Introduction – What can I do with Structures_DataGrid?

Description

Structures_DataGrid is a package with the purpose of rendering a data set into a tabular structure in a specific output format. Possible output formats are (X)HTML, XML, XUL, Excel .xls spreadsheets, CSV, or console tables.

The input data format is independent of the underlying data storage layer: It does not matter if the data has been selected from a database, has been harvested from plain text files or converted from a web service call. The data can be sorted and paged, and each cell of the table can have a custom look by using CSS for the HTML output.

Where to start

So to begin, you will want to find a datasource, commonly you might use a Database like MySQL or an XML document. You can then easily bind this datasource to the datagrid, to do so you have 3 options. The first, is to fetch your data into a 2 dimension array and pass it into the bind method. The second way is to bind a record set that is not already an array, such as a DB_DataObject or a DB_Result object. To do so, you can use the bindDataSource method by creating a DataSource object. The third way is to loop through your record set and add each record individually, this practice is the least efficient.

Note: If you bind the datagrid to a datasource that is an object such as a DB_DataObject, you do not need to fetch the data as the DataGrid will handle that for you.

Render the output

Once your datagrid has been populated with your records, you have many options on how to manipulate what is to be shown. You can sort the data, choose to show only a certain amount of data per page and also choose what format the data should be rendered into. You can render the datagrid in many formats including HTML.

Prev | Introduction and Features | Next
Introduction and Features | PEAR Manual | FAQ


FAQ

FAQ

FAQ – Answers to most Frequently Asked Questions

Description

This document is based on questions asked on PEAR general mailing list and other mailing lists and forums.

Structures_DataGrid FAQ

    I'm using the HTML_Table Renderer. How can I use multiple grids on the same page?

    The setRequestPrefix() method is the solution for this problem. Each DataGrid for the page needs such a prefix that is internally used before the GET parameters for sorting and paging. An example of the usage:

    <?php
    require_once 'Structures/DataGrid.php';

    $datagrid1 = new Structures_DataGrid();
    $datagrid2 = new Structures_DataGrid();

    $datagrid1->setRequestPrefix('trade_');
    $datagrid2->setRequestPrefix('stock_');

    $datagrid1->bind('SELECT * FROM trade', array('dsn' => DSN));
    $datagrid2->bind('SELECT * FROM stock', array('dsn' => DSN));

    $datagrid1->render();
    $datagrid2->render();
    ?>
    Note: You need to call setRequestPrefix() before calling bind().
    Which DataSource drivers are recommended?

    Currently there are five DataSource drivers that are recommended in the sense of efficiency:

    • DB_DataObject

    • DB_Table

    • DBQuery

    • MDB2

    • PDO

    These four drivers will only fetch the needed records from the database. For example, if you have a row limit of 15 records per page, they will only fetch (up to) 15 records.

    All other DataSource drivers can, of course, also be used. But there is no logic implemented (better said: implementable) to avoid fetching (or keeping in memory) unneeded records.

    I'd like to add row numbers to my DataGrid. How can I do this?

    You need a formatter for the new column that should hold the row number. The first parameter that is passed to such a formatter function contains a currRow value with the row number per page. For calculating the row number relative to the whole table, you need to take also the getCurrentRecordNumberStart() method into account.

    The following code snippet shows you how to define the formatter function and how to add the column (with # as the column label and right aligned values):

    <?php
    function formatRowNumber($params, $recordNumberStart)
    {
        return     $params['currRow'] + $recordNumberStart;
    }

    $datagrid->addColumn(
        new     Structures_DataGrid_Column(
                '#',
                null,
                null,
            array(    'style' => 'text-align: right;'),
                null,
                'formatRowNumber',
                $datagrid->getCurrentRecordNumberStart()
        ));
    ?>
    I'm using the Excel Renderer and would like to have the € sign in the resulting Excel file, but I always get only a box or some funny characters. How can I get the right € sign?

    Instead of using an encoding like ISO-8859-15, you need to use Windows-1252.

    Streaming is a nice feature. Why isn't streaming the default behaviour?

    Streaming support in Structures_DataGrid is intended to be used with large datasets. But it can also be used with very small datasets without loss of performance.

    As always, there is an exception to this rule: When you're using one of the DataSource drivers that fetch data from a database and you have queries that need a lot of time for computation of the results, you should not use streaming, as running such a complex query multiple times will need even more time, of course.

    I have used $renderer->toHtml(); with older versions of Structures_DataGrid, but this does not work anymore. How can I fix my code?

    If you just want to output the HTML code, use the following line of code:

    <?php
    $datagrid    ->render()
    ?>

    If you want to get the generated HTML code, e.g. for using it within a template, use the following line of code:

    <?php
    $html     = $datagrid->getOutput();
    ?>
    All the rows are displayed on one page. Why isn't it paging the data?

    Don't forget to pass the number of rows per page to the constructor:

    <?php
    $datagrid     =& new Structures_DataGrid(10); // 10 rows per page
    ?>
    Sorting doesn't work with MDB2 DataSource driver if I have column names in uppercase letters. Why?

    This is caused by MDB2's portability settings that are enabled by default. The MDB2_PORTABILITY_FIX_CASE setting is set to CASE_LOWER, resulting in lowercased letters for all column names. Disable this or all portability settings of MDB2 to avoid sorting problem with Structures_DataGrid.

    Prev | Introduction and Features | Next
Introduction | PEAR Manual | Installation


Installation

Installation

Installation – How to install the core and drivers packages

Introduction

If you are not familiar with PEAR, we recommend that you first read the PEAR general installation instructions

Structures_DataGrid use drivers that are provided separately. It means that installing the core package named Structures_DataGrid is not enough to get something working.

Installation steps

You will at least need one DataSource driver, for handling the input, and one Rendering driver (or Renderer), for the output.

The following commands will install the core package, as well as the MDB2 DataSource (for binding SQL queries), HTML_Table Renderer and the Pager renderer (for paging links). That should cover your most common needs.

$ pear install -o Structures_DataGrid

$ pear install -o Structures_DataGrid_DataSource_MDB2

$ pear install -o Structures_DataGrid_Renderer_HTMLTable

$ pear install -o Structures_DataGrid_Renderer_Pager
Note: If you get an error message like Failed to download pear/Structures_DataGrid within preferred state "stable", latest release is [...], you can simply append -beta to the package name, for example:

$ pear install -o Structures_DataGrid-beta

Of course, you may want to use other input/output formats, such as XML, MS Excel, DB_DataObject, XUL, etc... Just install the corresponding drivers.

Advanced installation

It is possible to install DataSource drivers or all Renderer drivers at once. The following two commands will install Structures_DataGrid and either all DataSource or all Renderer drivers at once.

$ pear install Structures_DataGrid#datasources

$ pear install Structures_DataGrid#renderers

Please note that the individual drivers will be installed only if the requirements are fulfilled. That means that the MDB2 DataSource won't be installed if you don't have MDB2 installed. The same holds for the Excel Renderer if you don't have Spreadsheet_Excel_Writer installed.

Of course, the same holds for the uninstallation. For example:

$ pear uninstall Structures_DataGrid#datasources

$ pear uninstall Structures_DataGrid#renderers

Prev | Introduction and Features | Next
FAQ | PEAR Manual | DataSources


DataSources

DataSources

DataSources – What is a DataSource driver?

Description

A DataSource has a rather self-explanatory name; however, a DataSource driver in context to the DataGrid can become a very essential key to your software. A DataSource driver will interact with your data source directly, such as a DB_DataObject or a MDB2 query and handle all of the paging and sorting code for you, resulting in very few lines of code that you will need to write.

How to use the drivers

There are two methods intended to be used for binding a DataSource driver: bind() and bindDataSource().

The bind() method is able to autodetect the right driver in many cases. For example, you can pass DB_Table or DB_DataObject instances to it. Strings can't be autodetected because they could contain CSV or XML data, for example. In such cases, you can specify the type as the third parameter in the bind() method call (e.g. 'CSV' or 'XML').

If you are building your own custom DataSource driver, using bindDataSource() is the method of choice. Just instantiate your DataSource class and pass this instance to the bindDataSource() method.

Currently available DataSource drivers

A list with the currently available DataSources can be found on the overview page.

Please also note the following FAQ entry: Which DataSource drivers are recommended?

Prev | Introduction and Features | Next
Installation | PEAR Manual | Rendering the output


Rendering the output

Rendering the output

Rendering the output – What formats can I render the output?

Description

The DataGrid offers the ability to build out your data in a grid format in an HTML table, which is the most common method due to the nature of PHP. However, the DataGrid offers many other ways of outputting the tabular data structure such as an Excel spreadsheet or an XML document.

How do I change the renderer?

To use a different renderer other than the HTML_Table renderer, you can specify the name of the renderer (e.g. 'CSV', 'Pager' or 'XML') as the first parameter of the fill(), getOutput(), and render() methods. Another possibility is to use setRenderer() method. The old way of using the third parameter of the constructor to define the renderer is deprecated since version 0.7.0.

Currently available renderers

A list with the currently available renderers can be found on the overview page.

Prev | Introduction and Features | Next
DataSources | PEAR Manual | Streaming


Streaming

Streaming

Streaming – How to stream large recordsets

Description

Large recordsets can exceed PHP's memory limit. Structures_DataGrid offers streaming support with many DataSource drivers and some Renderer drivers to avoid problems with the memory limit.

How do I use streaming?

Streaming can be enabled by calling the enableStreaming() method of the Structures_DataGrid object. An optimal parameter allows to set the number of records that should be read and written on each stream iteration. The default buffer size is 500 records.

Once streaming is enabled, only up to the number of records specified in the buffer size records will be fetched and rendered. This will be repeated until this was done for all records.

Enabling streaming with buffer size of 1,000 records

<?php
require 'Structures/DataGrid.php';

// Instantiate the DataGrid
$datagrid =& new Structures_DataGrid();

// Enable streaming and set buffer size to 1,000 records
$datagrid->enableStreaming(1000);

// ... e.g. bind(), render() calls as usual
?>

Driver support for streaming

Although streaming can be used with every DataSource driver, only the following drivers support streaming in a meaningful way: DataObject, DBQuery, DB_Table and MDB2. Streaming support is planned to be added also to the CSV and XML DataSources.

Streaming support is also compatible with every Renderer driver but can currently be used only with CSV and XML Renderers in a meaningful way. Other Renderers might be rewritten in the future for streaming support.

Prev | Introduction and Features | Next
Rendering the output | PEAR Manual | Column Formatter


Column Formatter

Column Formatter

Column Formatter – What can I do with the column formatter?

Description

The column formatter method can be a very powerful solution to a very common need. The need is to customize the output for a cell in the grid such as a link for a form element. This can be easily done by specifying a "callback" function. This function will then return the string that is needed to be printed.

Using the column formatter

<?php
require_once 'Structures/DataGrid.php';

$dg =& new Structures_DataGrid();
$result = $dg->bind('http://pear.php.net/feeds/pkg_structures_datagrid.rss');
if (PEAR::isError($result)) {
    die('An error occured while fetching the RSS information.');
}

$dg->addColumn(
    new Structures_DataGrid_Column('Release', 'title', 'title',
                                   null, null, 'printLink')
);
$dg->addColumn(
    new Structures_DataGrid_Column('Description', 'description',
                                   'description', null, null,
                                   'printDesc', array('length' => 15))
);
$dg->addColumn(
    new Structures_DataGrid_Column('Date', 'dc:date', 'dc:date')
);
$dg->render();

function printLink($params, $args = array())
{
    extract($params);
    extract($args);

    return '<a href="' . $record['link'] . '">' . $record['title'] . '</a>';
}

function printDesc($params, $args = array())
{
    extract($params);
    extract($args);

    if (strlen($record[$fieldName]) > $length) {
        return nl2br(substr($record[$fieldName], 0, $length)) . '...';
    } else {
        return nl2br($record[$fieldName]);
    }
}
?>

Each callback function needs to accept at least one parameter ($params in the example above). This parameter will contain various information:

  • 'record': An array containing the complete current record

  • 'fieldName': The field name of the current column

  • 'columnName': The column name of the current column

  • 'orderBy': The 'orderBy' argument of the current column

  • 'attribs': The attributes of the current column

  • 'currRow': The number of the current row

  • 'currCol': The number of the current column

An optional second parameter ($args in the example) allows you to pass additional information to the callback functions. In the example above, an array with length information is passed when the callback function printDesc() is called for the description column. Please note that this second parameter is only passed when you specify something in the column constructor. Therefore, it is a good practice to use $args = array() in the parameter list of your callback functions.

Prev | Introduction and Features | Next
Streaming | PEAR Manual | Example - Quick


Example - Quick

Example - Quick

Example - Quick – Quickly retrieve data from a database table

Description

Binding an SQL query

To retrieve the data that the datagrid will display you can begin by passing a simple SQL statement to the bind() method.

Using an SQL query as datasource

<?php
require 'Structures/DataGrid.php';

// Instantiate the DataGrid
$datagrid =& new Structures_DataGrid();

// Setup your database connection
$options = array('dsn' => 'mysql://user:password@host/db_name');

// Bind a basic SQL statement as datasource
$test = $datagrid->bind('SELECT * FROM my_table', $options);

// Print binding error if any
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

// Print the DataGrid with the default renderer (HTML Table)
$test = $datagrid->render();

// Print rendering error if any
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

?>

If you are familiar with the SQL language you'll certainly find many ways to adapt the above example to your needs, using more complex queries.

You can also page through your dataset with the automatic paging feature as shown below. This feature transparently adds LIMIT clauses to your SQL statement, providing optimized database access.

Automatic paging

<?php
require 'Structures/DataGrid.php';

// 10 records per page
$datagrid =& new Structures_DataGrid(10);

// Setup your datasource
$options = array('dsn' => 'mysql://user:password@host/db_name');
$test = $datagrid->bind("SELECT * FROM my_table", $options);
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

// Print the DataGrid with the default renderer (HTML Table)
$test = $datagrid->render();
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

// Print the HTML paging links
$test = $datagrid->render(DATAGRID_RENDER_PAGER);
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

?>
Prev | Introduction and Features | Next
Column Formatter | PEAR Manual | Example - Complex


Example - Complex

Example - Complex

Example - Complex – How to build a datagrid using many of the features

Description

An interface to a User Management System

This example will show you how to create an interface to a User Management System using the DB_DataObject package to handle the database aspects of this example.

User Management System Example

<?php
require_once 'Structures/DataGrid.php';
require_once 'HTML/Table.php';
require_once 'myclasses/User.php';

// Instantiate the DataObject; that's our DataSource container
$user = new User_DataObject();

// Create the DataGrid
$datagrid =& new Structures_DataGrid(20); // Display 20 records per page

// Specify how the DataGrid should be sorted by default
$datagrid->setDefaultSort(array('lname' => 'ASC'));

// Bind the DataSource container
$test = $datagrid->bind($user);
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

// Define columns
$datagrid->addColumn(new Structures_DataGrid_Column(null, null, null, array('width' => '10'), null, 'printCheckbox()'));
$datagrid->addColumn(new Structures_DataGrid_Column('Name', null, 'lname', array('width' => '40%'), null, 'printFullName()'));
$datagrid->addColumn(new Structures_DataGrid_Column('Username', 'username', 'username', array('width' => '20%')));
$datagrid->addColumn(new Structures_DataGrid_Column('Role', null, null, array('width' => '20%'), null, 'printRoleSelector()'));
$datagrid->addColumn(new Structures_DataGrid_Column('Edit', null, null, array('width' => '20%'), null, 'printEditLink()'));

// Define the Look and Feel
$tableAttribs = array(
    'width' => '100%',
    'cellspacing' => '0',
    'cellpadding' => '4',
    'class' => 'datagrid'
);
$headerAttribs = array(
    'bgcolor' => '#CCCCCC'
);
$evenRowAttribs = array(
    'bgcolor' => '#FFFFFF'
);
$oddRowAttribs = array(
    'bgcolor' => '#EEEEEE'
);
$rendererOptions = array(
    'sortIconASC' => '&uArr;',
    'sortIconDESC' => '&dArr;'
);

// Create a HTML_Table
$table = new HTML_Table($tableAttribs);
$tableHeader =& $table->getHeader();
$tableBody =& $table->getBody();

// Ask the DataGrid to fill the HTML_Table with data, using rendering options
$test = $datagrid->fill($table, $rendererOptions);
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

// Set attributes for the header row
$tableHeader->setRowAttributes(0, $headerAttribs);

// Set alternating row attributes
$tableBody->altRowAttributes(0, $evenRowAttribs, $oddRowAttribs, true);

// Output table and paging links
echo $table->toHtml();

// Display paging links
$test = $datagrid->render(DATAGRID_RENDER_PAGER);
if (PEAR::isError($test)) {
    echo $test->getMessage();
}

function printCheckbox($params)
{
    extract($params);
    return '<input type="checkbox" name="idList[]" value="' . $record['id'] . '">';
}
function printFullName($params)
{
    extract($params);
    return $record['fname'] . ' ' . $record['lname'];
}
function printRoleSelector($params)
{
    global $roleList;

    extract($params);

    $html = '<select name="role_id">';
    foreach ($roleList as $roleId => $roleName) {
        $html .= "<option value=\"$roleId\">$roleName</option>\n";
    }
    $html .= '</select>';

    return $html;
}
function printEditLink($params)
{
    extract($params);
    return '<a href="edit.php?id=' . $record['id'] . '">Edit</a>';
}
?>
Prev | Introduction and Features | Next
Example - Quick | PEAR Manual | Custom DataSources


Custom DataSources

Custom DataSources

Custom DataSources – How to write your own DataSource driver.

Introduction

Writing your own DataSource driver is the way to go when none of the existing driver suit your needs. It is actually pretty easy, and allows for great flexibility.

Of course, if you're trying to fetch data from an exotic source, writing your own driver is required. But, sometimes it's also the best way to achieve the best optimization, especially (but not only) with databases.

This document will present you the DataSource interface, and how to implement it.

Definitions

A DataSource driver is a descendent of the Structures_DataGrid_DataSource class, which implements the DataSource interface.

DataSource is a synomym for DataSource driver.

The DataSource interface consists in a set of methods that drivers must or may overload and protected properties that drivers can use, as well as recommended practices.

A DataSource container is a constant or a variable of any type (string, array, object, etc...) that either contains data or describes how to retrieve data.

Every DataSource driver is specific to, and knows how to handle, a given DataSource container type.

The DataSource interface

Properties available to drivers

array $_options - Data binding options as an associative array. You can read the content of this property but you shouldn't change it directly.

Methods that must or may be implemented in drivers

constructor ( ( void )

The constructor must set default options, if any, and call the parent constructor. This method is optional.

object bind ( mixed container , array options )

bind() is reponsible for loading a DataSource container into the driver, according to some binding options . This method is optional. It must return a PEAR_Error object in case of failure.

object count ( ( void )

count() must return the total number or records found in the container. This method is required, and is always called before fetch(). It must return a PEAR_Error object in case of failure.

object sort ( mixed sortSpec , array sortDir )

sort() must sort the data according to sortSpec and the optional sortDir . This method is required, and is always called before fetch(). It must return a PEAR_Error object in case of failure.

mixed fetch ( integer offset , integer len )

fetch() must return a 2-dimension array of data, starting from record offset , containing len records..This method is required It must return a PEAR_Error object in case of failure.

Protected methods that drivers can use

void _addDefaultOptions ( array options )

_addDefaultOptions() is used to declare the driver-specific options, if any, as well as their default values. It must be called from the constructor.

void setOptions ( array options )

setOptions() is a public method used to set options. If they ever need to change options, drivers should use this method.

A simple driver

Let's start with a very simple driver. It is rather readable and you shouldn't have much trouble understanding it. It is not extremely useful to write a custom driver for a such simple SQL query, but it should get you started.

A simple SQL adaptor

<?php
require 'Structures/DataGrid/DataSource.php';
require_once 'DB.php';

class MyDataSource extends Structures_DataGrid_DataSource {

    var $db;
    var $orderBy = '';

    function MyDataSource() {
        $dsn = 'mysql://someuser:apasswd@localhost/thedb';
        $this->db =& DB::connect($dsn);
    }

    function count() {
        $query = "SELECT COUNT(*) FROM animals WHERE species='cat'";
        return $this->db->getOne($query);
    }

    function sort($sortSpec, $sortDir = 'ASC') {
        $this->orderBy = "ORDER BY $sortSpec $sortDir";
    }

    function fetch($offset = 0, $len = null) {

        $limit = is_null($len) ? "LIMIT $offset,18446744073709551615"
                               : "LIMIT $offset,$len";

        $query  = "SELECT * FROM animals WHERE species='cat' ";
        $query .= $this->_orderBy . " $limit";

        return $this->db->getAll($query);
    }
}

?>

Testing your driver

Before going live, it is very recommended to test your driver with the dump() method.

Testing with dump()

<?php
$datasource = new MyDataSource();

$count = $datasource->count();
echo "There are $count cats in the farm\n\n";

$datasource->sort('weight');

echo "Here are the 5 lightest ones: \n";

// dump() accepts the same $offset and $len argument as fetch()
$datasource->dump(0,5);
?>

That should output a nicely formated ascii table like:

There are 23 cats in the farm.

Here are the 5 lightest ones:
+---------+---------+-----------+--------+
| name    | species | birthDate | weight |
+---------+---------+-----------+--------+
| sarge   | cat     | 20021220  | 1.8    |
| etch    | cat     | 20000509  | 2.5    |
| potato  | cat     | 19980128  | 3.8    |
| sid     | cat     | 20011101  | 4.1    |
| woody   | cat     | 19970712  | 6.0    |
+---------+---------+-----------+--------+

Using your new driver

Okay, so you have written a driver that's tailored to your needs, and tested it. It is now time to connect it to Structures_DataGrid.

For this purpose we're going to use the bindDataSource() method.

Binding a custom datasource

<?php

$datagrid =& new Structures_DataGrid();

$datasource = new MyDataSource();

$datagrid->bindDataSource($datasource);

$datagrid->render();
?>

That should output a sortable HTML table.

Of course, the usual features of Structures_DataGrid are now available to you: paging, other output formats as XML, MS-Excel, etc...

Prev | Introduction and Features | Next
Example - Complex | PEAR Manual | Custom Renderers


Custom Renderers

Custom Renderers

Custom Renderers – How to write your own Rendering driver.

Introduction

Writing your own Renderer allows you to fine tune every aspect of Structures_DataGrid output.

You may need to output the datagrid in a completely unsupported format. Then writing your own Renderer is the only option

But you may also need a unsupported variant of an existing renderer, say, for example, a very specific HTML output. In this case, you generally have two options : either writing a Rendering driver from scratch, or customizing (subclassing) an existing one.

This document will present you the Rendering driver interface, and how to implement it. You will certainly see how flexible Structures_DataGrid can become with custom Renderers, but also how easy we have to tried to make this process.

Definitions

A Rendering driver is a descendent of the Structures_DataGrid_Renderer class, which implements the Renderer interface.

Renderer is a synomym for Rendering driver.

The Renderer interface consists in a set of methods that drivers must or may overload and protected properties that drivers can use, as well as recommended practices.

A Rendering container is either an object that contain a sort of rendering engine, or a variable of any type (string, array, object, etc...) that can contain the output of a Renderer.

A Renderer with Container Support driver is specific to, and knows how to handle, a given type of Rendering container.

A driver is said to provide Container Support when it is able to handle a given type of Rendering container. Drivers with Container Support must implement the setContainer() and getContainer() public methods. They must be able to use a Rendering container provided by the user with setContainer(). They must also be able to create and intialize a Rendering container if the user does not provide any.

A driver is said to provide Output Buffering when it buffers the output that it generates, implements the flatten() method and is able to return the generated output from flatten().

A Direct Rendering driver is the simplest form of Renderer. It directs all of its output to standard output. By definition, a such driver neither provide Container support nor Output Buffering

The Renderer interface

Protected properties available to drivers

All of the following properties are read-only : drivers can access their content but must not change it directly.

array $_options -Common and driver-specific options

array $_columns - Columns fields names and labels

int $_columnsNum - Number of columns

array $_records - Records content

int $_recordsNum - Number of records in the current page

int $_totalRecordsNum - Total number of records as reported by the datasource

int $_firstRecord - First record number (starting from 1), in the current page

int $_lastRecord - Last record number (starting from 1), in the current page

int $_page - Current page number (starting from 1)

int $_pageLimit - Number of records per page

int $_pagesNum - Number of pages

string $_requestPrefix - GET/POST/Cookie parameters prefix

array $_currentSort - Fields/directions the data is currently sorted by

array $_sortableFields - Which fields the datagrid may be sorted by

Methods that must or may be implemented in drivers

All of the following methods are optional.

constructor ( ( void )

The constructor must set default options via _addDefaultOptions(), if any, and call the parent constructor.

object setContainer ( mixed container )

setContainer() is responsible for attaching a rendering container provided by the user. It must return a PEAR_Error object in case of failure.

object getContainer ( ( void )

getContainer() must return a reference to the container used by the driver. It must return a PEAR_Error object in case of failure.

void init ( ( void )

init() must initialize the rendering process. This method is also responsible for creating the container if it has not already been provided with setContainer().

void buildHeader ( array columns )

buildHeader() must build the header. $columns is a convenient reference to the $_columns property.

Protected methods that drivers can use

void _addDefaultOptions ( array options )

_addDefaultOptions() is used to declare the driver-specific options, if any, as well as their default values. It must be called from the constructor.

void setOptions ( array options )

setOptions() is a public method used to set options. If they ever need to change options, drivers should use this method.

A simple driver

Soon

Testing your driver

Soon

Using your new driver

Soon

Prev | Introduction and Features | Next
Custom DataSources | PEAR Manual | Class Structures_DataGrid


Class Structures_DataGrid

Class Structures_DataGrid

Table of Contents
  • constructor Structures_DataGrid::Structures_DataGrid -- Constructor
  • Structures_DataGrid::addColumn -- Add a column, with optional position
  • Structures_DataGrid::attachRenderer -- Attach an already instantiated Rendering driver
  • Structures_DataGrid::bind -- A simple way to add a record set to the datagrid
  • Structures_DataGrid::bindDataSource -- Bind an already instantiated DataSource driver
  • Structures_DataGrid::build -- Build the datagrid
  • Structures_DataGrid::dataSourceFactory -- Datasource driver Factory
  • Structures_DataGrid::dump -- Method used for debugging purposes only. Displays a dump of the DataGrid object.
  • Structures_DataGrid::enableStreaming -- Enable streaming support for reading from DataSources and writing with Renderers and set the buffer size (number of records)
  • Structures_DataGrid::fill -- Fill a rendering container with data
  • Structures_DataGrid::generateColumns -- Generate columns from a fields list
  • Structures_DataGrid::getColumnByField -- Find a column by field name
  • Structures_DataGrid::getColumnByName -- Find a column by name (label)
  • Structures_DataGrid::getColumnCount -- Returns the number of columns
  • Structures_DataGrid::getColumns -- Return the current columns
  • Structures_DataGrid::getCurrentPage -- Retrieves the current page number when paging is implemented
  • Structures_DataGrid::getCurrentRecordNumberEnd -- Returns the number of the last record of the current page
  • Structures_DataGrid::getCurrentRecordNumberStart -- Returns the number of the first record of the current page
  • Structures_DataGrid::getDataSource -- Get the currently loaded DataSource driver
  • Structures_DataGrid::getOutput -- Return the datagrid output
  • Structures_DataGrid::getPageCount -- Returns the total number of pages
  • Structures_DataGrid::getRecordCount -- Returns the total number of records
  • Structures_DataGrid::getRenderer -- Get the current or default Rendering driver
  • Structures_DataGrid::removeColumn -- Remove a column
  • Structures_DataGrid::render -- Render the datagrid
  • Structures_DataGrid::setCurrentPage -- Define the current page number.
  • Structures_DataGrid::setDataSourceOption -- Set a single datasource option
  • Structures_DataGrid::setDataSourceOptions -- Set multiple datasource options
  • Structures_DataGrid::setDefaultSort -- Set default sorting specification
  • Structures_DataGrid::setRenderer -- Set Renderer
  • Structures_DataGrid::setRendererOption -- Set a single renderer option
  • Structures_DataGrid::setRendererOptions -- Set multiple renderer options
  • Structures_DataGrid::setRequestPrefix -- Set the global GET/POST variables prefix
  • Structures_DataGrid::setUrlFormat -- Enable and configure URL mapping
  • Structures_DataGrid::sortRecordSet -- Sorts the records by the defined field.
Prev | Structures_DataGrid | Next
Custom Renderers | PEAR Manual | constructor Structures_DataGrid::Structures_DataGrid


constructor Structures_DataGrid::Structures_DataGrid

constructor Structures_DataGrid::Structures_DataGrid

constructor Structures_DataGrid::Structures_DataGrid() – Constructor

Synopsis

require_once 'Structures/DataGrid.php';

void constructor Structures_DataGrid::Structures_DataGrid ( string $limit = null , int $page = null , string $rendererType = null )

Description

Builds the DataGrid class. The Core functionality and Renderer are seperated for maintainability and to keep cohesion high.

Parameter

string $limit

The number of records to display per page.

integer $page

The current page viewed. In most cases, this is useless. Note: if you specify this, the "page" GET variable will be ignored.

string $rendererType

The type of renderer to use. You may prefer to use the $type argument of render() , fill() or getOutput()

Throws

throws no exceptions thrown

Examples

Instantiation

<?php
// Don't forget the ampersand
$datagrid =& new Structures_DataGrid();
?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Class Structures_DataGrid | PEAR Manual | Structures_DataGrid::addColumn


Structures_DataGrid::addColumn

Structures_DataGrid::addColumn

Structures_DataGrid::addColumn() – Add a column, with optional position

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::addColumn ( &$column , string $position = 'last' , string $relativeTo = null , object $column )

Description

This package is not documented yet.

Parameter

&$column

string $position

One of: "last", "first", "after" or "before" (default: "last")

string $relativeTo

The name (label) or field name of the relative column, if $position is "after" or "before"

object $column

The Structures_DataGrid_Column object (reference to)

Return value

returns PEAR_Error on failure, void otherwise

Throws

throws no exceptions thrown

Examples

Adding a simple column

<?php
$datagrid =& new Structures_DataGrid();
$column = new Structures_DataGrid_Column('Title', 'title', 'title', array('align' => 'center'), 'N/A', null);
$datagrid->addColumn($column);
?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
constructor Structures_DataGrid::Structures_DataGrid | PEAR Manual | Structures_DataGrid::attachRenderer


Structures_DataGrid::attachRenderer

Structures_DataGrid::attachRenderer

Structures_DataGrid::attachRenderer() – Attach an already instantiated Rendering driver

Synopsis

require_once 'Structures/DataGrid.php';

mixed& Structures_DataGrid::attachRenderer ( &$renderer , object $renderer )

Description

This package is not documented yet.

Parameter

&$renderer

object $renderer

Driver object, subclassing Structures_DataGrid_Renderer

Return value

returns Renderer instance or a PEAR_Error object

Throws

throws no exceptions thrown

See

see Structures_DataGrid::setRenderer()

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::addColumn | PEAR Manual | Structures_DataGrid::bind


Structures_DataGrid::bind

Structures_DataGrid::bind

Structures_DataGrid::bind() – A simple way to add a record set to the datagrid

Synopsis

require_once 'Structures/DataGrid.php';

bool Structures_DataGrid::bind ( mixed $container , array $options = array() , string $type = null )

Description

This package is not documented yet.

Parameter

mixed $container

The record set in any of the supported data source types

array $options

Optional. The options to be used for the data source

string $type

Optional. The data source type

Return value

returns True if successful, otherwise PEAR_Error.

Throws

throws no exceptions thrown

Examples

Bind an SQL query

<?php
// Setup your database connection
$options = array('dsn' => 'mysql://user:password@host/db_name');

// Bind a basic SQL statement as datasource
// Note: ORDER BY and LIMIT clause are automatically added
$test = $datagrid->bind('SELECT * FROM my_table', $options);

// Print binding error if any
if (PEAR::isError($test)) {
    echo $test->getMessage();
}
?>

Bind a DB_DataObject

<?php
$person = new DataObjects_Person;

$person->hair = 'red';
$person->has_glasses = 1;

$datagrid->bind($person);
?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::attachRenderer | PEAR Manual | Structures_DataGrid::bindDataSource


Structures_DataGrid::bindDataSource

Structures_DataGrid::bindDataSource

Structures_DataGrid::bindDataSource() – Bind an already instantiated DataSource driver

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::bindDataSource ( mixed &$source )

Description

This package is not documented yet.

Parameter

mixed &$source

The data source driver object

Return value

returns True if successful, otherwise PEAR_Error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::bind | PEAR Manual | Structures_DataGrid::build


Structures_DataGrid::build

Structures_DataGrid::build

Structures_DataGrid::build() – Build the datagrid

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::build ( )

Description

This package is not documented yet.

Return value

returns Either true or a PEAR_Error object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::bindDataSource | PEAR Manual | Structures_DataGrid::dataSourceFactory


Structures_DataGrid::dataSourceFactory

Structures_DataGrid::dataSourceFactory

Structures_DataGrid::dataSourceFactory() – Datasource driver Factory

Synopsis

require_once 'Structures/DataGrid.php';

Structures_DataGrid_DataSource|PEAR_Error& Structures_DataGrid::dataSourceFactory ( mixed $source , array $options = array() , string $type = null )

Description

A clever method which loads and instantiate data source drivers.

Can be called in various ways:

Detect the source type and load the appropriate driver with default options:

<?php
$driver =& Structures_DataGrid::dataSourceFactory($source);
?>

Detect the source type and load the appropriate driver with custom options:

<?php
$driver =& Structures_DataGrid::dataSourceFactory($source, $options);
?>

Load a driver for an explicit type (faster, bypasses detection routine):

<?php
$driver =& Structures_DataGrid::dataSourceFactory($source, $options, $type);
?>

Parameter

mixed $source

The data source respective to the driver

array $options

An associative array of the form: array(optionName => optionValue, ...)

string $type

The data source type constant (of the form DATAGRID_SOURCE_*)

Return value

returns driver object or PEAR_Error on failure

Throws

throws no exceptions thrown

See

see Structures_DataGrid::_detectSourceType()

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::build | PEAR Manual | Structures_DataGrid::dump


Structures_DataGrid::dump

Structures_DataGrid::dump

Structures_DataGrid::dump() – Method used for debugging purposes only. Displays a dump of the DataGrid object.

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::dump ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::dataSourceFactory | PEAR Manual | Structures_DataGrid::enableStreaming


Structures_DataGrid::enableStreaming

Structures_DataGrid::enableStreaming

Structures_DataGrid::enableStreaming() – Enable streaming support for reading from DataSources and writing with Renderers and set the buffer size (number of records)

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::enableStreaming ( integer $bufferSize = 500 )

Description

This package is not documented yet.

Parameter

integer $bufferSize

Number of records that should be buffered

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::dump | PEAR Manual | Structures_DataGrid::fill


Structures_DataGrid::fill

Structures_DataGrid::fill

Structures_DataGrid::fill() – Fill a rendering container with data

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::fill ( object &$container , array $options = array() , string $type = null )

Description

This package is not documented yet.

Parameter

object &$container

A rendering container of any of the supported types (example: an HTML_Table object, a Spreadsheet_Excel_Writer object, etc...)

array $options

Options for the corresponding rendering driver

string $type

Explicit type in case the container type can't be detected

Return value

returns Either true or a PEAR_Error object

Throws

throws no exceptions thrown

Examples

Filling a Pager object

<?php

require_once 'Pager/Pager.php';

// Create a Pager object with your own options
$pager =& Pager::factory($options);

// fill() sets the $pager object up, according to your data and settings
$datagrid->fill($pager);

// Render the paging links
echo $pager->links;

// Or a select field if you like that
echo $pager->getpageselectbox();

?>

Fill a form with sort fields

<?php
require_once 'HTML/QuickForm.php';

// Create an empty form with your settings
$form = new HTML_QuickForm('myForm', 'POST');

// Customize it, add a header, text field, etc..
$form->addElement('header', null, 'Search & Sort Form Example');
$form->addElement('text', 'my_search', 'Search for:');

// Let the datagrid add sort fields, radio style
$options = array('directionStyle' => 'radio');
$datagrid->fill($form, $options, 'HTMLSortForm');

// You must add a submit button. fill() never does this
$form->addElement('submit', null, 'Submit');

// Use the native HTML_QuickForm::display() to print your form
$form->display();

?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::enableStreaming | PEAR Manual | Structures_DataGrid::generateColumns


Structures_DataGrid::generateColumns

Structures_DataGrid::generateColumns

Structures_DataGrid::generateColumns() – Generate columns from a fields list

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::generateColumns ( array $fields = array() )

Description

This is a shortcut for adding simple columns easily, instead of creating them manually and calling addColumn() for each.

The generated columns are appended to the current column set.

Parameter

array $fields

Fields and labels. Array of the form: array(field => label, ...) The default is an empty array, which means: all fields fetched from the datasource

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::fill | PEAR Manual | Structures_DataGrid::getColumnByField


Structures_DataGrid::getColumnByField

Structures_DataGrid::getColumnByField

Structures_DataGrid::getColumnByField() – Find a column by field name

Synopsis

require_once 'Structures/DataGrid.php';

object Either& Structures_DataGrid::getColumnByField ( string $fieldName )

Description

This package is not documented yet.

Parameter

string $fieldName

The field name of the column to look for

Return value

returns the column object (reference to) or false if there is no such column

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::generateColumns | PEAR Manual | Structures_DataGrid::getColumnByName


Structures_DataGrid::getColumnByName

Structures_DataGrid::getColumnByName

Structures_DataGrid::getColumnByName() – Find a column by name (label)

Synopsis

require_once 'Structures/DataGrid.php';

object Either& Structures_DataGrid::getColumnByName ( string $name )

Description

This package is not documented yet.

Parameter

string $name

The name (label) of the column to look for

Return value

returns the column object (reference to) or false if there is no such column

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getColumnByField | PEAR Manual | Structures_DataGrid::getColumnCount


Structures_DataGrid::getColumnCount

Structures_DataGrid::getColumnCount

Structures_DataGrid::getColumnCount() – Returns the number of columns

Synopsis

require_once 'Structures/DataGrid.php';

int Structures_DataGrid::getColumnCount ( )

Description

This package is not documented yet.

Return value

returns the number of columns

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getColumnByName | PEAR Manual | Structures_DataGrid::getColumns


Structures_DataGrid::getColumns

Structures_DataGrid::getColumns

Structures_DataGrid::getColumns() – Return the current columns

Synopsis

require_once 'Structures/DataGrid.php';

array Structures_DataGrid::getColumns ( )

Description

This package is not documented yet.

Return value

returns Structures_DataGrid_Column objects (references to). This is a numerically indexed array (starting from 0).

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getColumnCount | PEAR Manual | Structures_DataGrid::getCurrentPage


Structures_DataGrid::getCurrentPage

Structures_DataGrid::getCurrentPage

Structures_DataGrid::getCurrentPage() – Retrieves the current page number when paging is implemented

Synopsis

require_once 'Structures/DataGrid.php';

int Structures_DataGrid::getCurrentPage ( )

Description

This package is not documented yet.

Return value

returns the current page number

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getColumns | PEAR Manual | Structures_DataGrid::getCurrentRecordNumberEnd


Structures_DataGrid::getCurrentRecordNumberEnd

Structures_DataGrid::getCurrentRecordNumberEnd

Structures_DataGrid::getCurrentRecordNumberEnd() – Returns the number of the last record of the current page

Synopsis

require_once 'Structures/DataGrid.php';

int Structures_DataGrid::getCurrentRecordNumberEnd ( )

Description

This package is not documented yet.

Return value

returns the number of the last record currently shown

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getCurrentPage | PEAR Manual | Structures_DataGrid::getCurrentRecordNumberStart


Structures_DataGrid::getCurrentRecordNumberStart

Structures_DataGrid::getCurrentRecordNumberStart

Structures_DataGrid::getCurrentRecordNumberStart() – Returns the number of the first record of the current page

Synopsis

require_once 'Structures/DataGrid.php';

int Structures_DataGrid::getCurrentRecordNumberStart ( )

Description

This package is not documented yet.

Return value

returns the number of the first record currently shown, or: 0 if there are no records, 1 if there is no row limit

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getCurrentRecordNumberEnd | PEAR Manual | Structures_DataGrid::getDataSource


Structures_DataGrid::getDataSource

Structures_DataGrid::getDataSource

Structures_DataGrid::getDataSource() – Get the currently loaded DataSource driver

Synopsis

require_once 'Structures/DataGrid.php';

object DataSource& Structures_DataGrid::getDataSource ( )

Description

Retrieves the DataSource object as a reference

Return value

returns object reference or null if no driver is loaded

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getCurrentRecordNumberStart | PEAR Manual | Structures_DataGrid::getOutput


Structures_DataGrid::getOutput

Structures_DataGrid::getOutput

Structures_DataGrid::getOutput() – Return the datagrid output

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::getOutput ( int $type = null , array $options = array() )

Description

This package is not documented yet.

Parameter

integer $type

Renderer type (optional)

array $options

An associative array of the form: array(optionName => optionValue, ...)

Return value

returns The datagrid output (Usually a string: HTML, CSV, etc...) or a PEAR_Error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getDataSource | PEAR Manual | Structures_DataGrid::getPageCount


Structures_DataGrid::getPageCount

Structures_DataGrid::getPageCount

Structures_DataGrid::getPageCount() – Returns the total number of pages

Synopsis

require_once 'Structures/DataGrid.php';

int Structures_DataGrid::getPageCount ( )

Description

This package is not documented yet.

Return value

returns the total number of pages or 1 if there are no records or if there is no row limit

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getOutput | PEAR Manual | Structures_DataGrid::getRecordCount


Structures_DataGrid::getRecordCount

Structures_DataGrid::getRecordCount

Structures_DataGrid::getRecordCount() – Returns the total number of records

Synopsis

require_once 'Structures/DataGrid.php';

int Structures_DataGrid::getRecordCount ( )

Description

This package is not documented yet.

Return value

returns the total number of records

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getPageCount | PEAR Manual | Structures_DataGrid::getRenderer


Structures_DataGrid::getRenderer

Structures_DataGrid::getRenderer

Structures_DataGrid::getRenderer() – Get the current or default Rendering driver

Synopsis

require_once 'Structures/DataGrid.php';

object Renderer& Structures_DataGrid::getRenderer ( )

Description

Retrieves the renderer object as a reference

Return value

returns object reference

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getRecordCount | PEAR Manual | Structures_DataGrid::removeColumn


Structures_DataGrid::removeColumn

Structures_DataGrid::removeColumn

Structures_DataGrid::removeColumn() – Remove a column

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::removeColumn ( &$column , object $column )

Description

This package is not documented yet.

Parameter

&$column

object $column

The Structures_DataGrid_Column object (reference to)

Throws

throws no exceptions thrown

Examples

Remove an unneeded column

<?php
$datagrid =& new Structures_DataGrid();

// Replace this with your database access informations:
$bindOptions['dsn'] = "mysql://foo:bar@host/world";

// The City table contains 5 fields: ID, Name, CountryCode, District and Population
$datagrid->bind("SELECT * FROM City ORDER BY Population", $bindOptions);

// We want to remove the ID field, so we retrieve a reference to the Column:
$column =& $datagrid->getColumnByField('ID');

// And we drop that column:
$datagrid->removeColumn($column);

// This will only render 4 fields: Name, CountryCode, District and Population:
$datagrid->render();
?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::getRenderer | PEAR Manual | Structures_DataGrid::render


Structures_DataGrid::render

Structures_DataGrid::render

Structures_DataGrid::render() – Render the datagrid

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::render ( mixed $renderer = null , array $options = array() )

Description

You can call this method several times with different renderers.

Parameter

mixed $renderer

Renderer type or instance (optional)

array $options

An associative array of the form: array(optionName => optionValue, ...)

Return value

returns True or PEAR_Error

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::removeColumn | PEAR Manual | Structures_DataGrid::setCurrentPage


Structures_DataGrid::setCurrentPage

Structures_DataGrid::setCurrentPage

Structures_DataGrid::setCurrentPage() – Define the current page number.

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setCurrentPage ( mixed $page )

Description

This method is used when paging is implemented

Parameter

mixed $page

The current page number (as string or int).

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::render | PEAR Manual | Structures_DataGrid::setDataSourceOption


Structures_DataGrid::setDataSourceOption

Structures_DataGrid::setDataSourceOption

Structures_DataGrid::setDataSourceOption() – Set a single datasource option

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setDataSourceOption ( string $name , mixed $value )

Description

This package is not documented yet.

Parameter

string $name

Option name

mixed $value

Option value

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setCurrentPage | PEAR Manual | Structures_DataGrid::setDataSourceOptions


Structures_DataGrid::setDataSourceOptions

Structures_DataGrid::setDataSourceOptions

Structures_DataGrid::setDataSourceOptions() – Set multiple datasource options

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setDataSourceOptions ( array $options )

Description

This package is not documented yet.

Parameter

array $options

An associative array of the form: array("option_name" => "option_value",...)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setDataSourceOption | PEAR Manual | Structures_DataGrid::setDefaultSort


Structures_DataGrid::setDefaultSort

Structures_DataGrid::setDefaultSort

Structures_DataGrid::setDefaultSort() – Set default sorting specification

Synopsis

require_once 'Structures/DataGrid.php';

mixed Structures_DataGrid::setDefaultSort ( array $sortSpec )

Description

If there is no sorting query in the HTTP request, and if the sortRecordSet() method is not called, then the specification passed to setDefaultSort() will be used.

This is especially useful if you want the data to already be sorted when a user first see the datagrid.

This method needs to be called before bind().

Parameter

array $sortSpec

Sorting specification Structure: array(fieldName => direction, ...)

Return value

returns Either true or a PEAR_Error object

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setDataSourceOptions | PEAR Manual | Structures_DataGrid::setRenderer


Structures_DataGrid::setRenderer

Structures_DataGrid::setRenderer

Structures_DataGrid::setRenderer() – Set Renderer

Synopsis

require_once 'Structures/DataGrid.php';

mixed& Structures_DataGrid::setRenderer ( string $type , array $options = array() )

Description

Defines which renderer to be used by the DataGrid based on given $type and $options. To attach an existing renderer instance, use attachRenderer() instead.

Parameter

string $type

The defined renderer string

array $options

Rendering options

Return value

returns Renderer instance or PEAR_Error

Throws

throws no exceptions thrown

See

see Structures_DataGrid::attachRenderer()

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setDefaultSort | PEAR Manual | Structures_DataGrid::setRendererOption


Structures_DataGrid::setRendererOption

Structures_DataGrid::setRendererOption

Structures_DataGrid::setRendererOption() – Set a single renderer option

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setRendererOption ( string $name , mixed $value , bool $common = false )

Description

This package is not documented yet.

Parameter

string $name

Option name

mixed $value

Option value

boolean $common

Whether to use this option for all renderers (TRUE) or only for the current one (FALSE)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setRenderer | PEAR Manual | Structures_DataGrid::setRendererOptions


Structures_DataGrid::setRendererOptions

Structures_DataGrid::setRendererOptions

Structures_DataGrid::setRendererOptions() – Set multiple renderer options

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setRendererOptions ( array $options , bool $common = false )

Description

This package is not documented yet.

Parameter

array $options

An associative array of the form: array("option_name" => "option_value",...)

boolean $common

Whether to use these options for all renderers (TRUE) or only for the current one (FALSE)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setRendererOption | PEAR Manual | Structures_DataGrid::setRequestPrefix


Structures_DataGrid::setRequestPrefix

Structures_DataGrid::setRequestPrefix

Structures_DataGrid::setRequestPrefix() – Set the global GET/POST variables prefix

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setRequestPrefix ( string $prefix )

Description

If you need to change the request variables, you can define a prefix. This is extra useful when using multiple datagrids.

This method needs to be called before bind().

Parameter

string $prefix

The prefix to use on request variables;

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setRendererOptions | PEAR Manual | Structures_DataGrid::setUrlFormat


Structures_DataGrid::setUrlFormat

Structures_DataGrid::setUrlFormat

Structures_DataGrid::setUrlFormat() – Enable and configure URL mapping

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::setUrlFormat ( mixed $format , string $prefix = null , string $scriptname = null )

Description

If this is set, it will be parsed instead of GET/POST. This is only supported on PHP5, as it depends on Net_URL_Mapper.

There are three possible placeholders, :pager, :orderBy and :direction. :page or (:orderBy and :direction) can be used alone.

It is possible to use multipe DataGrid instances on one page with different prefixes.

Instead of a format string you might also pass a Net_URL_Mapper instance to this method, in which case $prefix and $scriptname will be ignored. This instance must be properly set up, connected to url patterns, etc... This is especially useful when you've already configured URL mapping globally for your application and want Structures_DataGrid to integrate.

Parameter

mixed $format

The URL format string or a Net_URL_Mapper instance

string $prefix

Sets the url prefix

string $scriptname

Set the scriptname if mod_rewrite not available

See

see http://pear.php.net/Net_URL_Mapper

Throws

throws Net_URL_Mapper_InvalidException

Examples

configure a url format

<?php

// identical, for example /page/5/foo/ASC
$datagrid->setUrlFormat('/page/:page/:orderBy/:direction');
$datagrid->setUrlFormat('/:page/:orderBy/:direction', 'page');

// without /page, for example /5/foo/ASC
$datagrid->setUrlFormat('/:page/:orderBy/:direction');

// without paging, for example /sort/foo/ASC
$datagrid->setUrlFormat('/:orderBy/:direction', 'sort');

// with scriptname, for example /index.php/5/foo/ASC
$datagrid->setUrlFormat('/:page/:orderBy/:direction', 'page', 'index.php');

?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setRequestPrefix | PEAR Manual | Structures_DataGrid::sortRecordSet


Structures_DataGrid::sortRecordSet

Structures_DataGrid::sortRecordSet

Structures_DataGrid::sortRecordSet() – Sorts the records by the defined field.

Synopsis

require_once 'Structures/DataGrid.php';

void Structures_DataGrid::sortRecordSet ( array $sortSpec , string $direction = 'ASC' )

Description

Do not use this method if data is coming from a database as sorting is much faster coming directly from the database itself.

Parameter

array $sortSpec

Sorting specification Structure: array(fieldName => direction, ...)

string $direction

Deprecated. Put the direction(s) into $sortSpec

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid | Next
Structures_DataGrid::setUrlFormat | PEAR Manual | Class Structures_DataGrid_Column


Class Structures_DataGrid_Column

Class Structures_DataGrid_Column

Table of Contents
  • Class Summary Structures_DataGrid_Column -- Structures_DataGrid_Column Class
  • constructor Structures_DataGrid_Column::Structures_DataGrid_Column -- Constructor
  • Structures_DataGrid_Column::format -- Choose a format preset
  • Structures_DataGrid_Column::formatter -- Formatter
  • Structures_DataGrid_Column::getAttributes -- Get the column XML/HTML attributes
  • Structures_DataGrid_Column::getAutoFillValue -- Get auto fill value
  • Structures_DataGrid_Column::getDefaultDirection -- Return the default direction to order this column by
  • Structures_DataGrid_Column::getField -- Get name of the field for the column to be mapped to
  • Structures_DataGrid_Column::getLabel -- Get column label
  • Structures_DataGrid_Column::getOrderBy -- Get the field name to order the data by
  • Structures_DataGrid_Column::setAttributes -- Set the column XML/HTML attributes
  • Structures_DataGrid_Column::setAutoFillValue -- Set auto fill value
  • Structures_DataGrid_Column::setDefaultDirection -- Set the default direction to order this column by
  • Structures_DataGrid_Column::setField -- Set name of the field for the column to be mapped to
  • Structures_DataGrid_Column::setFormatter -- Set Formatter Callback
  • Structures_DataGrid_Column::setLabel -- Set column label
  • Structures_DataGrid_Column::setOrderBy -- Set the field name to order the data by
Prev | Structures_DataGrid | Next
Structures_DataGrid::sortRecordSet | PEAR Manual | Class Summary Structures_DataGrid_Column


Class Summary Structures_DataGrid_Column

Class Summary Structures_DataGrid_Column

Class Summary Structures_DataGrid_Column – Structures_DataGrid_Column Class

Structures_DataGrid_Column Class

This class represents a single column for the DataGrid.

Class Trees for Structures_DataGrid_Column

  • Structures_DataGrid_Column

Prev | Class Structures_DataGrid_Column | Next
Class Structures_DataGrid_Column | PEAR Manual | constructor Structures_DataGrid_Column::Structures_DataGrid_Column


constructor Structures_DataGrid_Column::Structures_DataGrid_Column

constructor Structures_DataGrid_Column::Structures_DataGrid_Column

constructor Structures_DataGrid_Column::Structures_DataGrid_Column() – Constructor

Synopsis

require_once 'Structures/DataGrid/Column.php';

void constructor Structures_DataGrid_Column::Structures_DataGrid_Column ( string $label , string $field = null , string $orderBy = null , array $attributes = array() , string $autoFillValue = null , mixed $formatter = null , array $formatterArgs = array() )

Description

Creates default table style settings

Parameter

string $label

The label of the column to be printed

string $field

The name of the field for the column to be mapped to

string $orderBy

The field or expression to order the data by

array $attributes

The attributes for the XML or HTML TD tag; form: array(name => value, ...)

string $autoFillValue

The value to use for the autoFill

mixed $formatter

Formatter callback. See setFormatter()

array $formatterArgs

Associative array of arguments passed as second argument to the formatter callback

Throws

throws no exceptions thrown

See

see Structures_DataGrid_Column::setFormatter()

see Structures_DataGrid::addColumn()

see http://www.php.net/manual/en/language.pseudo-types.php

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Class Summary Structures_DataGrid_Column | PEAR Manual | Structures_DataGrid_Column::format


Structures_DataGrid_Column::format

Structures_DataGrid_Column::format

Structures_DataGrid_Column::format() – Choose a format preset

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::format ( $type , mixed $type,... )

Description

EXPERIMENTAL: the behaviour of this method may change in future releases.

This method allows to associate an "automatic" predefined formatter to the column, for common needs as formatting dates, numbers, ...

The currently supported predefined formatters are :

  • dateFromTimestamp: format a UNIX timestamp according to the date()-like format string passed as second argument

  • dateFromMysql : format a MySQL DATE, DATETIME, or TIMESTAMP MySQL according to the date() like format string passed as second argument

  • number: format a number, according to the same optional 2nd, 3rd and 4th arguments that the number_format() PHP function accepts.

  • printf: format using the printf expression passed as 2nd argument.

  • printfURL: url-encode and format using the printf expression passed as 2nd argument

Parameter

$type

mixed $type,...

Predefined formatter name, followed by formatter-specific parameters

Throws

throws no exceptions thrown

Examples

Common formats

<?php

// Format UNIX timestamps as english dates:
$column->format('dateFromTimestamp', 'm/d/y');

// Format MySQL DATE, DATETIME or TIMESTAMP strings as french dates:
$column->format('dateFromMysql', 'd/m/y');

// Format numbers with 3 decimals and no thousands separator:
$column->format('number', 3, '.', '');

// Format numbers with 2 decimals:
$column->format('number', 2);

// Format using a printf expression:
$column->format('printf', 'Number of potatoes: %d');

// Format an HTML link using a printf expression with url-encoding:
$column->format('printfURL', '<a href="edit.php?key=%s">Edit</a>');

?>

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
constructor Structures_DataGrid_Column::Structures_DataGrid_Column | PEAR Manual | Structures_DataGrid_Column::formatter


Structures_DataGrid_Column::formatter

Structures_DataGrid_Column::formatter

Structures_DataGrid_Column::formatter() – Formatter

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::formatter ( $record , $row , $col )

Description

This method is not meant to be called by user-space code.

Calls a predefined function to develop custom output for the column. The defined function can accept parameters so that each cell in the column can be unique based on the record. The function will also automatically receive the record array as a parameter. All parameters passed into the function will be in one array.

Parameter

$record

$row

$col

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::format | PEAR Manual | Structures_DataGrid_Column::getAttributes


Structures_DataGrid_Column::getAttributes

Structures_DataGrid_Column::getAttributes

Structures_DataGrid_Column::getAttributes() – Get the column XML/HTML attributes

Synopsis

require_once 'Structures/DataGrid/Column.php';

array Structures_DataGrid_Column::getAttributes ( )

Description

Return the attributes applied to all cells in this column. This only makes sense for HTML or XML rendering

Return value

returns Attributes; form: array(name => value, ...)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::formatter | PEAR Manual | Structures_DataGrid_Column::getAutoFillValue


Structures_DataGrid_Column::getAutoFillValue

Structures_DataGrid_Column::getAutoFillValue

Structures_DataGrid_Column::getAutoFillValue() – Get auto fill value

Synopsis

require_once 'Structures/DataGrid/Column.php';

string Structures_DataGrid_Column::getAutoFillValue ( )

Description

Returns the value to be printed if a cell in the column is null.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::getAttributes | PEAR Manual | Structures_DataGrid_Column::getDefaultDirection


Structures_DataGrid_Column::getDefaultDirection

Structures_DataGrid_Column::getDefaultDirection

Structures_DataGrid_Column::getDefaultDirection() – Return the default direction to order this column by

Synopsis

require_once 'Structures/DataGrid/Column.php';

string Structures_DataGrid_Column::getDefaultDirection ( $str )

Description

This package is not documented yet.

Parameter

$str

Return value

returns "ASC" or "DESC"

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::getAutoFillValue | PEAR Manual | Structures_DataGrid_Column::getField


Structures_DataGrid_Column::getField

Structures_DataGrid_Column::getField

Structures_DataGrid_Column::getField() – Get name of the field for the column to be mapped to

Synopsis

require_once 'Structures/DataGrid/Column.php';

string Structures_DataGrid_Column::getField ( )

Description

Returns the name of the field for the column to be mapped to

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::getDefaultDirection | PEAR Manual | Structures_DataGrid_Column::getLabel


Structures_DataGrid_Column::getLabel

Structures_DataGrid_Column::getLabel

Structures_DataGrid_Column::getLabel() – Get column label

Synopsis

require_once 'Structures/DataGrid/Column.php';

string Structures_DataGrid_Column::getLabel ( )

Description

The label is the text rendered into the column header.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::getField | PEAR Manual | Structures_DataGrid_Column::getOrderBy


Structures_DataGrid_Column::getOrderBy

Structures_DataGrid_Column::getOrderBy

Structures_DataGrid_Column::getOrderBy() – Get the field name to order the data by

Synopsis

require_once 'Structures/DataGrid/Column.php';

string Structures_DataGrid_Column::getOrderBy ( )

Description

This package is not documented yet.

Return value

returns field name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::getLabel | PEAR Manual | Structures_DataGrid_Column::setAttributes


Structures_DataGrid_Column::setAttributes

Structures_DataGrid_Column::setAttributes

Structures_DataGrid_Column::setAttributes() – Set the column XML/HTML attributes

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::setAttributes ( array $attributes )

Description

Set the attributes to be applied to all cells in this column. This only makes sense for HTML or XML rendering

Parameter

array $attributes

form: array(name => value, ...)

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::getOrderBy | PEAR Manual | Structures_DataGrid_Column::setAutoFillValue


Structures_DataGrid_Column::setAutoFillValue

Structures_DataGrid_Column::setAutoFillValue

Structures_DataGrid_Column::setAutoFillValue() – Set auto fill value

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::setAutoFillValue ( string $str )

Description

Defines a value to be printed if a cell in the column is null.

Parameter

string $str

The value to use for the autoFill

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::setAttributes | PEAR Manual | Structures_DataGrid_Column::setDefaultDirection


Structures_DataGrid_Column::setDefaultDirection

Structures_DataGrid_Column::setDefaultDirection

Structures_DataGrid_Column::setDefaultDirection() – Set the default direction to order this column by

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::setDefaultDirection ( string $str )

Description

This package is not documented yet.

Parameter

string $str

"ASC" or "DESC"

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::setAutoFillValue | PEAR Manual | Structures_DataGrid_Column::setField


Structures_DataGrid_Column::setField

Structures_DataGrid_Column::setField

Structures_DataGrid_Column::setField() – Set name of the field for the column to be mapped to

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::setField ( string $str )

Description

Defines the name of the field for the column to be mapped to

Parameter

string $str

The name of the field for the column to be mapped to

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::setDefaultDirection | PEAR Manual | Structures_DataGrid_Column::setFormatter


Structures_DataGrid_Column::setFormatter

Structures_DataGrid_Column::setFormatter

Structures_DataGrid_Column::setFormatter() – Set Formatter Callback

Synopsis

require_once 'Structures/DataGrid/Column.php';

mixed Structures_DataGrid_Column::setFormatter ( mixed $formatter , array $arguments = array() )

Description

Define a formatting callback function with optional arguments for this column.

The callback function receives the following array as its first argument:

<?php
array(
   'record' => associative array of all fields values for this record,
   'fieldName' => the field name of this column,
   'columnName' => the label (header) of this column,
   'orderBy' => the field name to sort this column by,
   'attribs' => this column's attributes,
   'currRow' => zero-based row index,
   'currCol => zero-based column index,
 );
?>

If you pass the optional $arguments parameter to setFormatter(), the callback function will receive it as its second argument.

Parameter

mixed $formatter

Callback PHP pseudo-type (Array or String)

array $arguments

Associative array of parameters passed to as second argument to the callback function

Return value

returns PEAR_Error on failure

Throws

throws no exceptions thrown

See

see http://www.php.net/manual/en/language.pseudo-types.php

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::setField | PEAR Manual | Structures_DataGrid_Column::setLabel


Structures_DataGrid_Column::setLabel

Structures_DataGrid_Column::setLabel

Structures_DataGrid_Column::setLabel() – Set column label

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::setLabel ( string $str )

Description

The label is the text rendered into the column header.

Parameter

string $str

Column label

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::setFormatter | PEAR Manual | Structures_DataGrid_Column::setOrderBy


Structures_DataGrid_Column::setOrderBy

Structures_DataGrid_Column::setOrderBy

Structures_DataGrid_Column::setOrderBy() – Set the field name to order the data by

Synopsis

require_once 'Structures/DataGrid/Column.php';

void Structures_DataGrid_Column::setOrderBy ( string $str )

Description

This package is not documented yet.

Parameter

string $str

field name

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Class Structures_DataGrid_Column | Next
Structures_DataGrid_Column::setLabel | PEAR Manual | DataSource drivers


DataSource drivers

DataSource drivers

Table of Contents
  • Structures_DataGrid_DataSource_Array -- Array Data Source Driver
  • Structures_DataGrid_DataSource_CSV -- Comma Seperated Value (CSV) Data Source Driver
  • Structures_DataGrid_DataSource_DataObject -- PEAR::DB_DataObject Data Source Driver
  • Structures_DataGrid_DataSource_DB -- PEAR::DB Data Source Driver
  • Structures_DataGrid_DataSource_DBQuery -- PEAR::DB SQL Query Data Source Driver
  • Structures_DataGrid_DataSource_DBTable -- PEAR::DB_Table Data Source Driver
  • Structures_DataGrid_DataSource_Excel -- Excel Spreadsheet Data Source Driver
  • Structures_DataGrid_DataSource_MDB2 -- PEAR::MDB2 SQL Query Data Source Driver
  • Structures_DataGrid_DataSource_PDO -- PDO SQL Query Data Source Driver
  • Structures_DataGrid_DataSource_RSS -- RSS data source driver
  • Structures_DataGrid_DataSource_XML -- XML DataSource driver
Prev | Structures_DataGrid | Next
Structures_DataGrid_Column::setOrderBy | PEAR Manual | Structures_DataGrid_DataSource_Array


Structures_DataGrid_DataSource_Array

Structures_DataGrid_DataSource_Array

Structures_DataGrid_DataSource_Array – Array Data Source Driver

Description

This class is a data source driver for a 2D array

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | no
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
natsort | boolean | Whether the array should be sorted naturally (e.g. example1, Example2, test1, Test2) or not (e.g. Example2, Test2, example1, test1; i.e. capital letters will come first). | false
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null

General notes

This driver expects an array of the following form:

$data = array(0 => array('col0' => 'val00', 'col1' => 'val01', ...),
              1 => array('col0' => 'val10', 'col1' => 'val11', ...),
              ...
             );

The first level of this array contains one entry for each row. For every row entry an array with the data for this row is expected. Such an array contains the field names as the keys. For example, 'val01' is the value of the column with the field name 'col1' in the first row. Row numbers start with 0, not with 1.

Prev | DataSource drivers | Next
DataSource drivers | PEAR Manual | Structures_DataGrid_DataSource_CSV


Structures_DataGrid_DataSource_CSV

Structures_DataGrid_DataSource_CSV

Structures_DataGrid_DataSource_CSV – Comma Seperated Value (CSV) Data Source Driver

Description

This class is a data source driver for a CSV File. It will also support any other delimiter.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | no
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
delimiter | string | Field delimiter | ','
enclosure | string | Field enclosure | '"'
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
header | bool | Whether the CSV file (or string) contains a header row | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
natsort | boolean | Whether the array should be sorted naturally (e.g. example1, Example2, test1, Test2) or not (e.g. Example2, Test2, example1, test1; i.e. capital letters will come first). | false
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_Array | PEAR Manual | Structures_DataGrid_DataSource_DataObject


Structures_DataGrid_DataSource_DataObject

Structures_DataGrid_DataSource_DataObject

Structures_DataGrid_DataSource_DataObject – PEAR::DB_DataObject Data Source Driver

Description

This class is a data source driver for a PEAR::DB::DB_DataObject object

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | yes
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
fields_order_property | string | The name of a property that you can set within your DataObject. It will be used to set the order in which fields are displayed, as long as you're not configuring this by adding/generating columns. Also requires the fields_property to be set. | null
fields_property | string | The name of a property that you can set within your DataObject. This property is expected to contain the same kind of information as the 'fields' option. If the 'fields' option is set, this one will not be used. | 'fb_fieldsToRender'
formbuilder_integration | bool | DEPRECATED: use link_level and fields_order_property instead. For BC, Setting this to true is equivalent to setting link_level to 3 and fields_order_property to 'fb_preDefOrder'. | false
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
labels_property | string | The name of a property that you can set within your DataObject. This property should contain the same kind of information as the 'labels' option. If the 'labels' option is set, this one will not be used. | 'fb_fieldLabels'
link_keep_key | bool | Set this to true when you want to keep the original values (usually foreign keys) of fields which are being replaced by their linked values. The record will then contain additional keys with "__key" prepended. This option only makes sense with link_level higher than 0. Example: if the country_code original value is 'FR' and this is replaced by "France" from the linked country table, then setting link_keep_key to true will keep the "FR" value in country_code__key. | false
link_level | int | The maximum link display level. If equal to 0 the links will not be followed. | 0
link_property | string | The name of a property you can set within a linked DataObject. This property should contain a array of field names that will be used to display a string out of this linked DataObject. Has no effect when link_level is 0. | 'fb_linkDisplayFields'
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
raw_count | bool | If true: query all the records in order to count them. This is needed when records are grouped (GROUP BY, DISTINCT, etc..), but might be heavy. If false: perform a smart count query with DB_DataObject::count(). | false
return_objects | bool | If true, the returned records will consists of clones of the dataobject instead of associative arrays. This is especially useful when used in conjunction with the smarty renderer for example, to directly access the dataobject properties and methods from your templates. | false
sort_property | string | The name of a property that you can set within your DataObject. This property should contain an array of the form: array("field1", "field1 DESC", ...) If the data is already being sorted then this this property's content will be appended to the current ordering. | 'fb_linkOrderFields'

Examples

Bind a DB_DataObject to Structures_DataGrid

<?php
$person = new DataObjects_Person;

$person->hair = 'red';
$person->has_glasses = 1;

$datagrid->bind($person);
?>
Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_CSV | PEAR Manual | Structures_DataGrid_DataSource_DB


Structures_DataGrid_DataSource_DB

Structures_DataGrid_DataSource_DB

Structures_DataGrid_DataSource_DB – PEAR::DB Data Source Driver

Description

This class is a data source driver for the PEAR::DB::DB_Result object

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | no
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
natsort | boolean | Whether the array should be sorted naturally (e.g. example1, Example2, test1, Test2) or not (e.g. Example2, Test2, example1, test1; i.e. capital letters will come first). | false
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_DataObject | PEAR Manual | Structures_DataGrid_DataSource_DBQuery


Structures_DataGrid_DataSource_DBQuery

Structures_DataGrid_DataSource_DBQuery

Structures_DataGrid_DataSource_DBQuery – PEAR::DB SQL Query Data Source Driver

Description

This class is a data source driver for the PEAR::DB object

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | yes
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
count_query | string | Query that calculates the number of rows. See below for more information about when such a count query is needed. | ''
db_options | array | Options for the created database object. This option is only used when the 'dsn' option is given. | array()
dbc | object | A PEAR::DB instance that will be used by this driver. Either this or the 'dsn' option is required. | null
dsn | string | A PEAR::DB dsn string. The DB connection will be established by this driver. Either this or the 'dbc' option is required. | null
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null

General notes

You need to specify either a DB instance or a DB compatible dsn string as an option to use this driver.

If you use complex queries (e.g. with complex joins or with aliases), $datagrid->getRecordCount() might return a wrong result. For the case of GROUP BY, UNION, or DISTINCT in your queries, and for the case of subqueries, this driver already has special handling. However, if you observe wrong record counts, you need to specify a special query that returns only the number of records (e.g. 'SELECT COUNT(*) FROM ...') as an additional option 'count_query' to the bind() call.

You can specify an ORDER BY statement in your query. Please be aware that this sorting statement is then used in *every* query before the sorting options that come from a renderer (e.g. by clicking on the column header when using the HTML_Table renderer which is sent in the HTTP request). If you want to give a default sorting statement that is only used if there is no sorting query in the HTTP request, then use $datagrid->setDefaultSort().

Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_DB | PEAR Manual | Structures_DataGrid_DataSource_DBTable


Structures_DataGrid_DataSource_DBTable

Structures_DataGrid_DataSource_DBTable

Structures_DataGrid_DataSource_DBTable – PEAR::DB_Table Data Source Driver

Description

This class is a data source driver for the PEAR::DB_Table object

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | yes
Insert, update and delete records | yes

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
params | array | Placeholder parameters for prepare/execute | array()
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
view | string | The view from $sql array in your DB_Table object. This option is required. | null
where | string | A where clause for the SQL query. | null

General notes

If you use aliases in the select part of your view, the count() method from DB_Table and, therefore, $datagrid->getRecordCount() might return a wrong result. To avoid this, DB_Table uses a special query for counting if it is given via a view that needs to be named as '__count_' followed by the name of the view that this counting view belongs to. (For example: if you have a view named 'all', the counting view needs to be named as '__count_all'.)

To use update() and delete() methods, it is required that the indexes are properly defined in the $idx array in your DB_Table subclass. If you have, for example, created your database table yourself and did not setup the $idx array, you can use the 'primaryKey' option to define the primary key field.

Examples

Bind a DB_Table class to Structures_DataGrid

<?php
// basic guestbook class that extends DB_Table
class GuestBook_Table extends DB_Table
{
    var $col = array(
        // unique row ID
        'id' => array(
            'type'    => 'integer',
            'require' => true
        ),
        // first name
        'fname' => array(
            'type'    => 'varchar',
            'size'    => 32
        ),
        // last name
        'lname' => array(
            'type'    => 'varchar',
            'size'    => 64
        ),
        // email address
        'email' => array(
            'type'    => 'varchar',
            'size'    => 128,
            'require' => true
        ),
        // date signed
        'signdate' => array(
            'type'    => 'date',
            'require' => true
        )
    );
    var $idx = array();  // indices don't matter here
    var $sql = array(
        // multiple rows for a list
        'list' => array(
            'select' => 'id, signdate, CONCAT(fname, " ", lname) AS fullname',
            'order'  => 'signdate DESC'
        )
    );
}

// instantiate the extended DB_Table class
// (using an existing database connection and the table name 'guestbook')
$guestbook =& new GuestBook_Table($db, 'guestbook');

// Options for the bind() call
// (using the predefined query 'list' from the $sql array and a where
// condition)
$options = array('view' => 'list', 'where' => 'YEAR(signdate) = 2100');

// bind the guestbook object
// (if you don't generate any column yourself before rendering, three
// columns will be generated: id, signdate, fullname)
$test = $datagrid->bind($guestbook, $options);

// print binding error if any
if (PEAR::isError($test)) {
    echo $test->getMessage();
}
?>
Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_DBQuery | PEAR Manual | Structures_DataGrid_DataSource_Excel


Structures_DataGrid_DataSource_Excel

Structures_DataGrid_DataSource_Excel

Structures_DataGrid_DataSource_Excel – Excel Spreadsheet Data Source Driver

Description

This class is a data source driver for an Excel spreadsheet.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | no
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
header | bool | Whether the Excel file contains a header row | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
natsort | boolean | Whether the array should be sorted naturally (e.g. example1, Example2, test1, Test2) or not (e.g. Example2, Test2, example1, test1; i.e. capital letters will come first). | false
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null

General notes

Spreadsheet_Excel_Reader ("PHP-ExcelReader") is not available as a PEAR package. It is available on SourceForge.net: http://sourceforge.net/projects/phpexcelreader/

This class expects the file reader.php in the directory Spreadsheet/Excel/.

Please note that the current version (2i) of Spreadsheet_Excel_Reader contains a die() statement in the read() method in reader.php (line 171). This makes a reasonable PEAR error handling for the "file not found" error impossible.

It is therefore recommended that you replace the die() statement by something like this:

return PEAR::raiseError('The filename ' . $sFileName . ' is not readable');

This class is optimized for the changed code (but will work also with the die() in the reader class, of course), and provides then a reasonable error handling.

Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_DBTable | PEAR Manual | Structures_DataGrid_DataSource_MDB2


Structures_DataGrid_DataSource_MDB2

Structures_DataGrid_DataSource_MDB2

Structures_DataGrid_DataSource_MDB2 – PEAR::MDB2 SQL Query Data Source Driver

Description

This class is a data source driver for the PEAR::MDB2 object

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | yes
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
count_query | string | Query that calculates the number of rows. See below for more information about when such a count query is needed. | ''
db_options | array | Options for the created database object. This option is only used when the 'dsn' option is given. | array()
dbc | object | A PEAR::MDB2 instance that will be used by this driver. Either this or the 'dsn' option is required. | null
dsn | string | A PEAR::MDB2 dsn string. The MDB2 connection will be established by this driver. Either this or the 'dbc' option is required. | null
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null

General notes

You need to specify either a MDB2 instance or a MDB2 compatible dsn string as an option to use this driver.

If you use complex queries (e.g. with complex joins or with aliases), $datagrid->getRecordCount() might return a wrong result. For the case of GROUP BY, UNION, or DISTINCT in your queries, and for the case of subqueries, this driver already has special handling. However, if you observe wrong record counts, you need to specify a special query that returns only the number of records (e.g. 'SELECT COUNT(*) FROM ...') as an additional option 'count_query' to the bind() call.

You can specify an ORDER BY statement in your query. Please be aware that this sorting statement is then used in *every* query before the sorting options that come from a renderer (e.g. by clicking on the column header when using the HTML_Table renderer which is sent in the HTTP request). If you want to give a default sorting statement that is only used if there is no sorting query in the HTTP request, then use $datagrid->setDefaultSort().

Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_Excel | PEAR Manual | Structures_DataGrid_DataSource_PDO


Structures_DataGrid_DataSource_PDO

Structures_DataGrid_DataSource_PDO

Structures_DataGrid_DataSource_PDO – PDO SQL Query Data Source Driver

Description

This class is a data source driver for PHP Data Objects

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | yes
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
count_query | string | Query that calculates the number of rows. See below for more information about when such a count query is needed. | ''
db_options | array | Options for the created database object. This option is only used when the 'dsn' option is given. | array()
dbc | object | A PDO instance that will be used by this driver. Either this or the 'dsn' option is required. | null
dsn | string | A PDO dsn string. The PDO connection will be established by this driver. Either this or the 'dbc' option is required. | null
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
password | string | Password for the crated PDO connection. Only needed in conjunction with 'dsn' option. | null
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
username | string | Username for the created PDO connection. Only needed in conjunction with 'dsn' option. | null

General notes

You need to specify either a PDO instance or a PDO compatible dsn string as an option to use this driver.

If you use complex queries (e.g. with complex joins or with aliases), $datagrid->getRecordCount() might return a wrong result. For the case of GROUP BY, UNION, or DISTINCT in your queries, and for the case of subqueries, this driver already has special handling. However, if you observe wrong record counts, you need to specify a special query that returns only the number of records (e.g. 'SELECT COUNT(*) FROM ...') as an additional option 'count_query' to the bind() call.

You can specify an ORDER BY statement in your query. Please be aware that this sorting statement is then used in *every* query before the sorting options that come from a renderer (e.g. by clicking on the column header when using the HTML_Table renderer which is sent in the HTTP request). If you want to give a default sorting statement that is only used if there is no sorting query in the HTTP request, then use $datagrid->setDefaultSort().

Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_MDB2 | PEAR Manual | Structures_DataGrid_DataSource_RSS


Structures_DataGrid_DataSource_RSS

Structures_DataGrid_DataSource_RSS

Structures_DataGrid_DataSource_RSS – RSS data source driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | no
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
natsort | boolean | Whether the array should be sorted naturally (e.g. example1, Example2, test1, Test2) or not (e.g. Example2, Test2, example1, test1; i.e. capital letters will come first). | false
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_PDO | PEAR Manual | Structures_DataGrid_DataSource_XML


Structures_DataGrid_DataSource_XML

Structures_DataGrid_DataSource_XML

Structures_DataGrid_DataSource_XML – XML DataSource driver

Description

This class is a DataSource driver for XML data. It accepts strings and filenames. An XPath expression can be specified to extract a subset from the given XML data.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Multiple field sorting | no
Insert, update and delete records | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
fieldAttribute | string | Which attribute of the XML source should be used as column field name (only used if the XML source has attributes). | null
fields | array | Which data fields to fetch from the datasource. An empty array means: all fields. Form: array(field1, field2, ...) | array()
generate_columns | bool | Generate Structures_DataGrid_Column objects with labels. See the 'labels' option. DEPRECATED: use Structures_DataGrid::generateColumns() instead | false
labelAttribute | string | Which attribute of the XML source should be used as column label (only used if 'generate_columns' is true and the XML source has attributes). | null
labels | array | Data field to column label mapping. Only used when 'generate_columns' is true. Form: array(field => label, ...) DEPRECATED: use Structures_DataGrid::generateColumns() instead | array()
natsort | boolean | Whether the array should be sorted naturally (e.g. example1, Example2, test1, Test2) or not (e.g. Example2, Test2, example1, test1; i.e. capital letters will come first). | false
primaryKey | array | Name(s), or numerical index(es) of the field(s) which contain a unique record identifier (only use several fields in case of a multiple-fields primary key) | null
xpath | string | XPath to a subset of the XML data. | ''

Examples

Bind a simple XML string

<?php
$xml = <<<XML
<records>
  <record>
    <firstname>Olivier</firstname>
    <lastname>Guilyardi</lastname>
    <city>Paris</city>
    <country>France</country>
  </record>
  <record>
    <firstname>Mark</firstname>
    <lastname>Wiesemann</lastname>
    <city>Aachen</city>
    <country>Germany</country>
  </record>
</records>
XML;

// Options for the bind() call (empty in this example)
$options = array();

// Bind the XML string
$test = $datagrid->bind($xml, $options, 'XML');

// Print binding error if any
if (PEAR::isError($test)) {
    echo $test->getMessage();
}
?>

Bind a more complex XML string (using 'xpath' option)

<?php
$xml = <<<XML
<response>
  <date>today</date>
  <server>localhost</server>
  <records>
    <record>
      <firstname>Olivier</firstname>
      <lastname>Guilyardi</lastname>
      <city>Paris</city>
      <country>France</country>
    </record>
    <record>
      <firstname>Mark</firstname>
      <lastname>Wiesemann</lastname>
      <city>Aachen</city>
      <country>Germany</country>
    </record>
  </records>
</response>
XML;

// Options for the bind() call
$options = array('xpath' => '/response/records');

// Bind the XML string
$test = $datagrid->bind($xml, $options, 'XML');

// Print binding error if any
if (PEAR::isError($test)) {
    echo $test->getMessage();
}
?>
Prev | DataSource drivers | Next
Structures_DataGrid_DataSource_RSS | PEAR Manual | Renderer drivers


Renderer drivers

Renderer drivers

Table of Contents
  • Structures_DataGrid_Renderer_CheckableHTMLTable -- HTML table rendering driver with a checkbox for each row of the grid
  • Structures_DataGrid_Renderer_Console -- Console Table Rendering Driver
  • Structures_DataGrid_Renderer_CSV -- CSV Rendering Driver
  • Structures_DataGrid_Renderer_Flexy -- Flexy Rendering Driver
  • Structures_DataGrid_Renderer_HTMLEditForm -- HTML form to edit a record
  • Structures_DataGrid_Renderer_HTMLSortForm -- Multiple fields sorting form rendering driver
  • Structures_DataGrid_Renderer_HTMLTable -- HTML Table Rendering Driver
  • Structures_DataGrid_Renderer_Pager -- Pager rendering driver
  • Structures_DataGrid_Renderer_Smarty -- Smarty Rendering Driver
  • Structures_DataGrid_Renderer_XLS -- Excel Spreadsheet Rendering Driver
  • Structures_DataGrid_Renderer_XML -- XML Rendering Driver
  • Structures_DataGrid_Renderer_XUL -- XUL Rendering Driver
Prev | Structures_DataGrid | Next
Structures_DataGrid_DataSource_XML | PEAR Manual | Structures_DataGrid_Renderer_CheckableHTMLTable


Structures_DataGrid_Renderer_CheckableHTMLTable

Structures_DataGrid_Renderer_CheckableHTMLTable

Structures_DataGrid_Renderer_CheckableHTMLTable – HTML table rendering driver with a checkbox for each row of the grid

Availability

This driver is experimental and has not been officially released yet. It is only available from CVS.

Description

Driver for rendering the DataGrid as an HTML table with a checkbox for each row

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
classASC | string | A CSS class name for TH elements to define that sorting is currently ascending. | ''
classDESC | string | A CSS class name for TH elements to define that sorting is currently descending. | ''
columnAttributes | array | Column cells attributes. This is an array of the form: array(fieldName => array(attribute => value, ...) ...) This option is only used by XML/HTML based drivers. | array()
convertEntities | bool | Whether or not to convert html entities. This calls htmlspecialchars(). | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
emptyRowAttributes | array | An associative array containing the attributes for empty rows. | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
evenRowAttributes | array | An associative array containing each attribute of the even rows. | array()
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
form | object | Instance of a HTML_QuickForm object. | null
formRenderer | object | Instance of a HTML_QuickForm_Renderer_QuickHtml object. | null
headerAttributes | array | Attributes for the header row. This is an array of the form: array(attribute => value, ...) | array()
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
inputName | string | The HTML_QuickForm element name for the checkboxes. | 'checkedItems'
numberAlign | bool | Whether to right-align numeric values. | true
oddRowAttributes | array | An associative array containing each attribute of the odd rows. | array()
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
primaryKey | string | The name of the primary key. This value is used for the checkboxes. | 'id'
selfPath | string | The complete path for sorting and paging links. | $_SERVER['PHP_SELF']
sortIconASC | string | The icon to define that sorting is currently ascending. Can be text or HTML to define an image. | ''
sortIconDESC | string | The icon to define that sorting is currently descending. Can be text or HTML to define an image. | ''
sortingResetsPaging | bool | Whether sorting HTTP queries reset paging. | true

General notes

This driver puts a checkbox for each row of the table into the first column. By default, a new column with the value of the 'inputName' option is added for the checkboxes. If you want to customize this column, you can add a column yourself as it is shown in the example.

Examples

Basic usage

<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/QuickHtml.php';
require_once 'Structures/DataGrid.php';

// prepare the form and the QuickHtml renderer
$form =& new HTML_QuickForm();
$renderer =& new HTML_QuickForm_Renderer_QuickHtml();

// add action selectbox and submit button to the form
$form->addElement('select', 'action', 'choose',
                  array('delete' => 'Delete',
                        'move'   => 'Move to archive'));
$form->addElement('submit', 'submit', 'Save');

// prepare the DataGrid
$dg =& new Structures_DataGrid();
if (PEAR::isError($dg)) {
   die($dg->getMessage() . '<br />' . $dg->getDebugInfo());
}

// bind some data (e.g. via a SQL query and MDB2)
$error = $dg->bind('SELECT * FROM news',
                   array('dsn' => 'mysql://user:password@server/database'));
if (PEAR::isError($error)) {
   die($error->getMessage() . '<br />' . $error->getDebugInfo());
}

// the renderer adds an auto-generated column for the checkbox by default;
// it is also possible to add a column yourself, for example like in the
// following four lines:
$column = new Structures_DataGrid_Column('checkboxes', 'idList', null,
                                         array('width' => '10'));
$dg->addColumn($column);
$dg->generateColumns();

$rendererOptions = array('form'         => $form,
                         'formRenderer' => $renderer,
                         'inputName'    => 'idList',
                         'primaryKey'   => 'id'
                        );

// use a template string for the form
$tpl = '';

// generate the HTML table and add it to the template string
$tpl .= $dg->getOutput('CheckableHTMLTable', $rendererOptions);
if (PEAR::isError($tpl)) {
   die($tpl->getMessage() . '<br />' . $tpl->getDebugInfo());
}

// add the HTML code of the action selectbox and the submit button to the
// template string
$tpl .= $renderer->elementToHtml('action');
$tpl .= $renderer->elementToHtml('submit');

// we're now ready to output the form (toHtml() adds the <form> / </form>
// pair to the template)
echo $renderer->toHtml($tpl);

// if the form was submitted and the data is valid, show the submitted data
if ($form->isSubmitted() && $form->validate()) {
    var_dump($form->getSubmitValues());
}
?>
Prev | Renderer drivers | Next
Renderer drivers | PEAR Manual | Structures_DataGrid_Renderer_Console


Structures_DataGrid_Renderer_Console

Structures_DataGrid_Renderer_Console

Structures_DataGrid_Renderer_Console – Console Table Rendering Driver

Description

This renderer generates nicely formatted and padded ASCII tables.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_CheckableHTMLTable | PEAR Manual | Structures_DataGrid_Renderer_CSV


Structures_DataGrid_Renderer_CSV

Structures_DataGrid_Renderer_CSV

Structures_DataGrid_Renderer_CSV – CSV Rendering Driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | no
Output Buffering | yes
Direct Rendering | yes
Streaming | yes
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
delimiter | string | Field delimiter | ','
enclosure | string | Field enclosure | '"'
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
filename | string | Filename of the generated CSV file; boolean false means that no filename will be sent | false
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
lineBreak | string | The character(s) to use for line breaks | '\n'
numberAlign | bool | Whether to right-align numeric values. | true
saveToFile | boolean | Whether the output should be saved on the local filesystem. Please note that the 'filename' option must be given if this option is set to true. | false
targetEncoding | string | If set, the content will be converted from encoding to targetEncoding. A BOM will also be added, if relevant. See PHP mbstring documentation for encoding names. Tip: for Excel use 'UTF-16LE'. | ''
useQuotes | mixed | Whether or not to encapsulate the values with the enclosure value. true: always, false: never, 'auto': when needed | 'auto'
writeMode | string | The mode that is used in the internal fopen() calls. Useful e.g. when you want to append to existing file. C.p. the fopen() documentation for the allowed modes. | 'wb'
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_Console | PEAR Manual | Structures_DataGrid_Renderer_Flexy


Structures_DataGrid_Renderer_Flexy

Structures_DataGrid_Renderer_Flexy

Structures_DataGrid_Renderer_Flexy – Flexy Rendering Driver

Availability

This driver is experimental and has not been officially released yet. It is only available from CVS.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
assocColumns | bool | Whether or not to build the column header as an associate array. | true
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
columnAttributes | array | Column cells attributes. This is an array of the form: array(fieldName => array(attribute => value, ...) ...) This option is only used by XML/HTML based drivers. | array()
columnNames | array | The set of column names to use for the column header. | array()
convertEntities | bool | Whether or not to convert html entities. This calls htmlspecialchars(). | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
evenRowAttribute | string | The css class to be used for the even row listings. | 'even'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
formatter | array | The callback array for a column header formatter method. | array($this,'defaultHeaderFormatter')
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
oddRowAttribute | string | The css class to be used for odd row listings. | 'odd'
onMove | string | Name of a Javascript function to call on onClick/onSubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
pagerOptions | array | The custom options to be sent to the Pager renderer. |
resultsFormat | string | The format of the results message in sprintf format. | 'You have %s results in %s pages'
selfPath | string | The complete path for sorting and paging links. | $_SERVER['PHP_SELF']
sortingResetsPaging | bool | Whether sorting HTTP queries reset paging. | true

General notes

This driver does not support the render() method, it only is able to be attached setting the container to a current Flexy instance. Options to the renderer must also be passed using the setOptions() method.

Flexy output is buffered using the DataGrid getOutput() method.

This driver assigns the following Flexy template variables: - columnSet: array of columns' labels and sorting links - columnHeader: object of columns' labels and sorting links - recordSet: associate array of records values - numberedSet: numbered array of records values - currentPage: current page (starting from 1) - recordLimit: number of rows per page - pagesNum: number of pages - columnsNum: number of columns - recordsNum: number of records in the current page - totalRecordsNum: total number of records - firstRecord: first record number (starting from 1) - lastRecord: last record number (starting from 1)

This driver also register a Smarty custom function named getPaging that can be called from Smarty templates with {getPaging} in order to print paging links. This function accepts any of the Pager::factory() options as parameters.

Dynamic Template example, featuring sorting and paging:

<!-- Show paging links using the custom getPaging function -->
{getPaging():h}

<p>Showing records {firstRecord} to {lastRecord}
from {totalRecordsNum}, page {currentPage} of {pagesNum}</p>

<table cellspacing="0">
   <!-- Build header -->
   <tr>
       <th>
           {foreach:columnSet,column}
               <td><a href="{column[link]:h}">{column[label]:h}</a></td>
           {end:}
       </th>
   </tr>

   <!-- Build body -->
   <tr class="{getRowCSS()}" flexy:foreach="numberedSet,k,row">
       {foreach:row,field}
           <td>{field}</td>
       {end:}
   </tr>
</table>

Static Template example, featuring sorting and paging:

<table cellspacing="0">
   <!-- Build header -->
   <tr>
       <th>
           <td>
               <a href="{columnHeader.name[link]:h}">{columnHeader.field1[label]:h}</a>
           </td>
           <td>
              <a href="{columnHeader.surname[link]:h}">{columnHeader.field2[label]:h}</a>
           </td>
       </th>
   </tr>

   <!-- Build body -->
   <tr class="{getRowCSS()}" flexy:foreach="recordSet,k,row">
       <td>{row[field1]}</td>
       <td>{row[field2]}</td>
   </tr>
</table>

require_once 'HTML/Template/Flexy.php';
require_once 'Structures/DataGrid.php';
require_once 'Structures/DataGrid/Renderer/Flexy.php';

$tpl = new HTML_Template_Flexy($config['HTML_Template_Flexy']);
$dg =& new Structures_DataGrid($_GET['setPerPage'] ? $_GET['setPerPage']
                                                   : 10,$_GET['page']
                                                   ? $_GET['page'] : 1);
$dg->bind($dataObject);
$renderer = new Structures_DataGrid_Renderer_Flexy();
$renderer->setContainer($tpl);
$renderer->setOptions($config['Structures_DataGrid']);
$dg->attachRenderer($renderer);
$this->tpl->compile($template);
echo $dg->getOutput();
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_CSV | PEAR Manual | Structures_DataGrid_Renderer_HTMLEditForm


Structures_DataGrid_Renderer_HTMLEditForm

Structures_DataGrid_Renderer_HTMLEditForm

Structures_DataGrid_Renderer_HTMLEditForm – HTML form to edit a record

Availability

This driver is experimental and has not been officially released yet. It is only available from CVS.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
textSubmit | string | Label for the submit button | 'Submit'

Examples

Basic usage

<?php
require_once 'Structures/DataGrid.php';

$datagrid =& new Structures_DataGrid();
$datagrid->bind(...);  // bind your data here

$datagrid->setRenderer('HTMLEditForm');

$datagrid->render();
?>

Usage with tableless renderer and DHTMLRules

<?php
// don't forget to include the stylesheet to get a reasonable layout

require_once 'Structures/DataGrid.php';
require_once 'HTML/QuickForm/DHTMLRulesTableless.php';
require_once 'HTML/QuickForm/Renderer/Tableless.php';

$datagrid =& new Structures_DataGrid();
$datagrid->bind(...);  // bind your data here

// create the form object, using DHTMLRules
$form = new HTML_QuickForm_DHTMLRulesTableless('editform', null, null,
                                               null, null, true);
$form->removeAttribute('name');  // for XHTML validity

// to get a legend for the fieldset, we add a header element
$form->addElement('header', 'header', 'EditForm example');

// fill() makes the renderer to generate the needed form elements
$datagrid->fill($form, null, 'HTMLEditForm');

// we have to add a submit button ourselves
$form->addElement('submit', null, 'Submit');

// to show the DHTMLRules functionality, we add a required rule
// (we assume that there is an element with name 'id')
$form->addRule('id', 'Please enter the ID.', 'required', null, 'client');

// to get validation onChange/onBlur events, we need the following call
$form->getValidationScript();

// instantiate the tableless renderer and output the form
$renderer =& new HTML_QuickForm_Renderer_Tableless();
$form->accept($renderer);
echo $renderer->toHtml();
?>
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_Flexy | PEAR Manual | Structures_DataGrid_Renderer_HTMLSortForm


Structures_DataGrid_Renderer_HTMLSortForm

Structures_DataGrid_Renderer_HTMLSortForm

Structures_DataGrid_Renderer_HTMLSortForm – Multiple fields sorting form rendering driver

Description

This driver renders a form (using HTML_QuickForm) so that the user can select several fields and directions to sort the datagrid by.

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
directionStyle | string | Whether to render the direction form elements as 'select' or 'radio' elements | 'select'
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
sortFieldsNum | int | How many fields the user will be able to sort by. This has no effect if the backend does not support sorting by multiple fields. | 3
textAscending | string | Label for the ASC direction | 'Ascending'
textChoose | string | What to display in the select box when no field is selected (first option) | 'Choose...'
textDescending | string | Label for the DESC direction | 'Descending'
textSortBy | string | Label for the first field | 'Sort by:'
textSubmit | string | Label for the submit button | 'Submit'
textThenBy | string | Label for the second and following fields | 'Then by:'

Examples

Fill a form with sort fields

<?php
require_once 'HTML/QuickForm.php';

// Create an empty form with your settings
$form = new HTML_QuickForm('myForm', 'POST');

// Customize it, add a header, text field, etc..
$form->addElement('header', null, 'Search & Sort Form Example');
$form->addElement('text', 'my_search', 'Search for:');

// Let the datagrid add sort fields, radio style
$options = array('directionStyle' => 'radio');
$datagrid->fill($form, $options, 'HTMLSortForm');

// You must add a submit button. fill() never does this
$form->addElement('submit', null, 'Submit');

// Use the native HTML_QuickForm::display() to print your form
$form->display();

?>
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_HTMLEditForm | PEAR Manual | Structures_DataGrid_Renderer_HTMLTable


Structures_DataGrid_Renderer_HTMLTable

Structures_DataGrid_Renderer_HTMLTable

Structures_DataGrid_Renderer_HTMLTable – HTML Table Rendering Driver

Description

Driver for rendering the DataGrid as an HTMLTable

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
classASC | string | A CSS class name for TH elements to define that sorting is currently ascending. | ''
classDESC | string | A CSS class name for TH elements to define that sorting is currently descending. | ''
columnAttributes | array | Column cells attributes. This is an array of the form: array(fieldName => array(attribute => value, ...) ...) This option is only used by XML/HTML based drivers. | array()
convertEntities | bool | Whether or not to convert html entities. This calls htmlspecialchars(). | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
emptyRowAttributes | array | An associative array containing the attributes for empty rows. | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
evenRowAttributes | array | An associative array containing each attribute of the even rows. | array()
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
headerAttributes | array | Attributes for the header row. This is an array of the form: array(attribute => value, ...) | array()
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
oddRowAttributes | array | An associative array containing each attribute of the odd rows. | array()
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
selfPath | string | The complete path for sorting and paging links. | $_SERVER['PHP_SELF']
sortIconASC | string | The icon to define that sorting is currently ascending. Can be text or HTML to define an image. | ''
sortIconDESC | string | The icon to define that sorting is currently descending. Can be text or HTML to define an image. | ''
sortingResetsPaging | bool | Whether sorting HTTP queries reset paging. | true

Examples

Simple AJAX support using the Prototype framework

<?php
require_once 'PEAR.php';
require_once 'Structures/DataGrid.php';

$datagrid =& new Structures_DataGrid(10);

$options['dsn'] = 'mysql://username@localhost/mydatabase';
$datagrid->bind("SELECT * FROM mytable", $options);

// Set the javascript handler function for onclick events
$datagrid->setRendererOption('onMove', 'updateGrid', true);

if (isset($_GET['ajax'])) {
    // Handle table AJAX requests
    if ($_GET['ajax'] == 'table') {
        $datagrid->render();
    }
    // Handle pager AJAX requests
    if ($_GET['ajax'] == 'pager') {
        $datagrid->render('Pager');
    }
    exit();
}

// No AJAX request, render the initial content..
?>
<html>

<head>
<!-- Require the Prototype JS framework from http://www.prototypejs.org -->
<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript">
function updateGrid(info)
{
    var url = '<?php echo $_SERVER['PHP_SELF']; ?>';
    var pars = 'page=' + info.page;
    if (info.sort.length > 0) {
        pars += '&orderBy=' + info.sort[0].field + '&direction=' + info.sort[0].direction;
    }

    new Ajax.Updater( 'grid', url, { method: 'get', parameters: pars + '&ajax=table' });
    new Ajax.Updater( 'pager', url, { method: 'get', parameters: pars + '&ajax=pager' });

    // Important: return false to avoid href links
    return false;
}
</script>
</head>

<body>
Pages: <span id="pager"><?php $datagrid->render('Pager'); ?></span>
<div id="grid"><?php $datagrid->render(); ?></div>
</body>

</html>
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_HTMLSortForm | PEAR Manual | Structures_DataGrid_Renderer_Pager


Structures_DataGrid_Renderer_Pager

Structures_DataGrid_Renderer_Pager

Structures_DataGrid_Renderer_Pager – Pager rendering driver

Description

This driver provides generic paging. This driver has full container support. You can use the Structures_DataGrid::fill() method with it. It buffers output, you can use Structures_DataGrid::getOutput()

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
pagerOptions | array | Options passed to Pager::factory(). Basic defaults are: mode: Sliding, delta: 5, separator: "|", prevImg: "&lt;&lt;" (<<), nextImg: "&gt;&gt;" (>>). The extraVars and excludeVars options are populated according to the Renderer common extraVars and excludeVars options. You may also specify some variables to be added or excluded here. The totalItems, perPage, urlVar, and currentPage options are set accordingly to the data statistics reported by the DataGrid and DataSource. You may overload these values here if you know what you are doing. |
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_HTMLTable | PEAR Manual | Structures_DataGrid_Renderer_Smarty


Structures_DataGrid_Renderer_Smarty

Structures_DataGrid_Renderer_Smarty

Structures_DataGrid_Renderer_Smarty – Smarty Rendering Driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | yes

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
associative | bool | By default the column set and the records are numerically indexed arrays. By setting this option to true the keys will be field names instead. | false
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
columnAttributes | array | Column cells attributes. This is an array of the form: array(fieldName => array(attribute => value, ...) ...) This option is only used by XML/HTML based drivers. | array()
convertEntities | bool | Whether or not to convert html entities. This calls htmlspecialchars(). | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
selfPath | string | The complete path for sorting and paging links. | $_SERVER['PHP_SELF']
sortingResetsPaging | bool | Whether sorting HTTP queries reset paging. | true
varPrefix | string | Prefix for smarty variables and functions assigned by this driver. Can be used in conjunction with Structure_DataGrid::setRequestPrefix() for displaying several grids on a single page. | ''

General notes

To use this driver you need the Smarty template engine from http://smarty.php.net

This driver does not support the render() method, it is only able to:

Either fill() a Smarty object by assigning variables and registering the {getPaging} smarty function. It's up to you to call Smarty::display() after the Smarty object has been filled.

Or return all variables as a PHP array from getOutput(), for maximum flexibility, so that you can assign them the way you like to your Smarty instance.

This driver assigns the following Smarty variables:

- $columnSet:       array of columns specifications
                    structure:
                         array (
                             0 => array (
                                 'name'       => field name,
                                 'label'      => column label,
                                 'link'       => sorting link,
                                 'attributes' => attributes string,
                                 'direction'  => 'ASC', 'DESC' or '',
                                 'onclick'    => onMove call
                             ),
                             ...
                         )
- $recordSet:       array of records values
- $currentPage:     current page (starting from 1)
- $nextPage:        next page
- $previousPage:    previous page
- $recordLimit:     number of rows per page
- $pagesNum:        number of pages
- $columnsNum:      number of columns
- $recordsNum:      number of records in the current page
- $totalRecordsNum: total number of records
- $firstRecord:     first record number (starting from 1)
- $lastRecord:      last record number (starting from 1)
- $currentSort:     array with column names and the directions used for sorting
- $datagrid:        a reference that you can pass to {getPaging}

This driver registers a Smarty custom function named getPaging that can be called from Smarty templates with {getPaging} in order to print paging links. This function accepts the same parameters as the pagerOptions option of Structures_DataGrid_Renderer_Pager.

{getPaging} accepts an optional "datagrid" parameter which you can pass the $datagrid variable, to display paging for an arbitrary datagrid (useful with multiple dynamic datagrids on a single page).

Object Records : this drivers preserves object records if provided. This means that if your datasource provides objects instead of associative arrays as records, you can access their properties and methods in your smarty template, with something like: {$recordSet[col]->getSomeInformation()}.

Examples

Using the Smarty renderer

<?php
require_once 'Structures/DataGrid.php';
require_once 'Smarty.class.php';

$datagrid =& new Structures_DataGrid(10);
$options = array('dsn' => 'mysql://username@localhost/mydatabase');
$datagrid->bind("SELECT * FROM mytable", $options);

$smarty = new Smarty();
$datagrid->fill($smarty);
$smarty->display('smarty-simple.tpl');
?>

Smarty template with sorting and paging (smarty-simple.tpl)

<?php
<!-- Show paging links using the custom getPaging function -->
{getPaging prevImg="<<" nextImg=">>" separator=" | " delta="5"}

<p>Showing records {$firstRecord} to {$lastRecord}
from {$totalRecordsNum}, page {$currentPage} of {$pagesNum}</p>

<table cellspacing="0">
    <!-- Build header -->
    <tr>
        {section name=col loop=$columnSet}
            <th {$columnSet[col].attributes}>
                <!-- Check if the column is sortable -->
                {if $columnSet[col].link != ""}
                    <a href="{$columnSet[col].link}">{$columnSet[col].label}</a>
                    <!-- Show the current ordering with an arrow -->
                    {if $columnSet[col].direction == "ASC"}
                      &darr;
                    {elseif $columnSet[col].direction == "DESC"}
                      &uarr;
                    {/if}
                {else}
                    {$columnSet[col].label}
                {/if}
            </th>
        {/section}
    </tr>

    <!-- Build body -->
    {section name=row loop=$recordSet}
        <tr {if $smarty.section.row.iteration is even}bgcolor="#EEEEEE"{/if}>
            {section name=col loop=$recordSet[row]}
                <td {$columnSet[col].attributes}>{$recordSet[row][col]}</td>
            {/section}
        </tr>
    {/section}
</table>
?>
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_Pager | PEAR Manual | Structures_DataGrid_Renderer_XLS


Structures_DataGrid_Renderer_XLS

Structures_DataGrid_Renderer_XLS

Structures_DataGrid_Renderer_XLS – Excel Spreadsheet Rendering Driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | yes
Output Buffering | no
Direct Rendering | not really, see below
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
bodyFormat | mixed | The format for body cells (either 0 [= "no format"] or a Spreadsheet_Excel_Writer_Format object) Please see the NOTE ABOUT FORMATTING below. | 0
border | int | Border drawn around the whole datagrid: 0 => none, 1 => thin, 2 => thick (NOT IMPLEMENTED YET) | 0
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
filename | string | The filename of the spreadsheet | 'spreadsheet.xls'
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
headerBorder | int | Border between the header and body: 0 => none, 1 => thin, 2 => thick (NOT IMPLEMENTED YET) | 0
headerFormat | mixed | The format for header cells (either 0 [= "no format"] or a Spreadsheet_Excel_Writer_Format object) Please see the NOTE ABOUT FORMATTING below. | 0
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
sendToBrowser | bool | Should the spreadsheet be send to the browser? (true = send to browser, false = write to a file) | true
startCol | int | The Worksheet column number to start rendering at | 0
startRow | int | The Worksheet row number to start rendering at | 0
tempDir | string | A temporary directory to be used by Spreadsheet_Excel_Writer (cp. "General Notes" section). | null
version | int | If you don't pass a worksheet object to this renderer, you can set the BIFF version with this option. The only accepted value by Spreadsheet_Excel_Writer is 8 (for usage of the BIFF8 format). All other values will lead to the older format (which is needed if you get errors in Excel, e.g. about a broken file). | 8
worksheet | object | Optional reference to a Spreadsheet_Excel_Writer_Worksheet object. You can leave this to null except if your workbook contains several worksheets and you want to fill a specific one. | null

General notes

This driver does not support the flatten() method. You can not retrieve its output with DataGrid::getOutput(). You can either render it directly to the browser or save it to a file. See the "sendToBrowser" and "filename" options.

This driver has container support. You can use Structures_DataGrid::fill() with it; that's even recommended.

If PHP's safe_mode is enabled, Spreadsheet_Excel_Writer sometimes fails to generate the Excel file. You can avoid this problem by setting the 'tempDir' option to a (temporary) directory that is writable by PHP.

NOTE ABOUT FORMATTING:

You can specify some formatting with the 'headerFormat' and 'bodyFormat' options, or with setBodyFormat() and setHeaderFormat().

But beware of the following from the Spreadsheet_Excel_Writer manual: "Formats can't be created directly by a new call. You have to create a format using the addFormat() method from a Workbook, which associates your Format with this Workbook (you can't use the Format with another Workbook)."

What this means is that if you want to pass a format to this driver you have to "derive" the Format object out of the workbook used in the driver.

The easiest way to do this is:

// Create a workbook
$workbook = new Spreadsheet_Excel_Writer();

// Specify that spreadsheet must be sent the browser
$workbook->send('test.xls');

// Create your format
$format_bold =& $workbook->addFormat();
$format_bold->setBold();

// Fill the workbook, passing the format as an option
$options = array('headerFormat' => &$format_bold);
$datagrid->fill($workbook, $options);
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_Smarty | PEAR Manual | Structures_DataGrid_Renderer_XML


Structures_DataGrid_Renderer_XML

Structures_DataGrid_Renderer_XML

Structures_DataGrid_Renderer_XML – XML Rendering Driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | no
Output Buffering | yes
Direct Rendering | yes
Streaming | yes
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
columnAttributes | array | Column cells attributes. This is an array of the form: array(fieldName => array(attribute => value, ...) ...) This option is only used by XML/HTML based drivers. | array()
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fieldAttribute | string | The name of the attribute for the field name. null stands for no attribute | null
fieldTag | string | The name of the tag for each field inside a row, without brackets. The special value '{field}' is replaced by the field name. | '{field}'
filename | string | Filename of the generated XML file; boolean false means that no filename will be sent | false
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
labelAttribute | string | The name of the attribute for the column label. null stands for no attribute | null
numberAlign | bool | Whether to right-align numeric values. | true
outerTag | string | The name of the tag for the datagrid, without brackets | 'DataGrid'
rowTag | string | The name of the tag for each row, without brackets | 'Row'
saveToFile | boolean | Whether the output should be saved on the local filesystem. Please note that the 'filename' option must be given if this option is set to true. | false
useXMLDecl | bool | Whether the XML declaration string should be added to the output. The encoding attribute value will get set from the common "encoding" option. If you need to further customize the XML declaration (version, etc..), then please set "useXMLDecl" to false, and add your own declaration string. | true
writeMode | string | The mode that is used in the internal fopen() calls. Useful e.g. when you want to append to existing file. C.p. the fopen() documentation for the allowed modes. | 'wb'
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_XLS | PEAR Manual | Structures_DataGrid_Renderer_XUL


Structures_DataGrid_Renderer_XUL

Structures_DataGrid_Renderer_XUL

Structures_DataGrid_Renderer_XUL – XUL Rendering Driver

Supported operations modes

This driver supports the following operation modes:

Supported operations modes of this driver
Mode | Supported?
Container Support | no
Output Buffering | yes
Direct Rendering | no
Streaming | no
Object Preserving | no

Options

This driver accepts the following options:

Options for this driver
Option | Type | Description | Default Value
buildFooter | bool | Whether to build the footer. | true
buildHeader | bool | Whether to build the header. | true
defaultCellValue | string | What value to put by default into empty cells. | null
defaultColumnValues | array | Per-column default cell value. This is an array of the form: array(fieldName => value, ...). | array()
encoding | string | The content encoding. If the mbstring extension is present the default value is set from mb_internal_encoding(), otherwise it is ISO-8859-1. | 'ISO-8859-1'
excludeVars | array | Variables to be removed from the generated HTTP queries. | array()
extraVars | array | Variables to be added to the generated HTTP queries. | array()
fillWithEmptyRows | bool | Ensures that all pages have the same number of rows. | false
hideColumnLinks | array | By default sorting links are enabled on all columns. With this option it is possible to disable sorting links on specific columns. This is an array of the form: array(fieldName, ...). This option only affects drivers that support sorting. | array()
numberAlign | bool | Whether to right-align numeric values. | true
onMove | string | Name of a Javascript function to call on onclick/onsubmit events when the user is either paging or sorting the data. This function receives a single object argument of the form: { page: <page>, sort: [{field: <field>, direction: <direction>}, ...], data: <user_data> }. Remark: setting this option doesn't remove the href attribute, you should return false from your handler function to void it (eg: for AJAX, etc..). | null
onMoveData | string | User data passed in the "data" member of the object argument passed to onMove. No JSON serialization is performed, this is assigned as a raw string to the "data" attribute. It's up to you to add quotes, slashes, etc... | ''
selfPath | string | The complete path for sorting links | $_SERVER['PHP_SELF']

General notes

This renderer class will render a XUL listbox. For additional information on the XUL Listbox, refer to this url: http://www.xulplanet.com/references/elemref/ref_listbox.html

You have to setup your XUL document, just as you would with an HTML document. This driver will only generated the <listbox> element and content.

Examples

Using the XUL renderer

<?php
require_once 'Structures/DataGrid.php';

$datagrid =& new Structures_DataGrid(10);
$options = array('dsn' => 'mysql://username@localhost/mydatabase');
$datagrid->bind("SELECT * FROM mytable", $options);

header('Content-type: application/vnd.mozilla.xul+xml');

echo "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>\n";
echo "<?xml-stylesheet href=\"myStyle.css\" type=\"text/css\"?>\n";

echo "<window title=\"MyDataGrid\"
       xmlns=\"http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul\">\n";

$datagrid->render('XUL');

echo "</window>\n";
?>
Prev | Renderer drivers | Next
Structures_DataGrid_Renderer_XML | PEAR Manual | Games_Chess


Games_Chess

Games_Chess

Games_Chess is like a brilliant helper who can tell you anything you need to know about an abstract chess game. The only thing Games_Chess cannot do is play against you - it is not a chess engine. Games_Chess handles the logic a chessboard and parsing standard FEN (Forsyth-Edwards Notation) for describing a position as well as SAN (Standard Algebraic Notation) for describing individual moves. This package can be used as a backend driver for playing chess, or for validating and/or creating PGN files using the File_ChessPGN package (when it is completed)

Table of Contents
  • Introduction -- Basic usage of Games_Chess
Prev | Structures | Next
Structures_DataGrid_Renderer_XUL | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Basic usage of Games_Chess

What is Games_Chess?

Games_Chess provides a basic interface for validating and playing chess. Games_Chess has facilities for calculating all of the important chess rules including check, checkmate, stalemate, basic draws such as bishop+king versus king, 50 move draw, en passant pawn captures, castling, double space first pawn move and basic piece movement. In addition, Games_Chess can set up a board to a position using the Forsyth-Edwards Notation (FEN) and can output a list of moves in Standard Algebraic Notation (SAN) as well as parse any valid SAN move, no matter how obscure (Qa3xf3, for instance), as well as simple "move the piece on a3 to h3" commands.

How do I use Games_Chess?

The Games_Chess package comes with a demonstration file, which has highlighted source at This location.

The Games_Chess package provides three different drivers, one for playing a standard chess game, and two for playing interesting variant games that are popular on the Internet Chess Club (ICC).

  1. Crazyhouse. basic rules in Crazyhouse chess allow you to place pieces you have captured from your opponent on the board as new pieces for your own army. This is a wild and highly tactical game.

  2. Loser's Chess. Loser's chess is similar to checkers in that if a capture is possible, it must be executed. For this reason, most of the moves are forcing moves in this game, and it results in very fast games.

To use Games_Chess on the most basic level is simple. Here is a sample script showing the initialization of the three drivers:

<?php
require_once 'Games/Chess/Standard.php';
require_once 'Games/Chess/Crazyhouse.php';
require_once 'Games/Chess/Losers.php';
$standard = new Games_Chess_Standard;
$crazyhouse = new Games_Chess_Crazyhouse;
$losers = new Games_Chess_Losers;
?>

By default, a Games_Chess driver is created with a blank board. To set up a new starting position, use this code:

<?php
require_once 'Games/Chess/Standard.php';
$standard = new Games_Chess_Standard;
$standard->resetGame();
?>

If you wish to load a particular starting position in FEN notation, pass the FEN string to resetGame() like so:

<?php
require_once 'Games/Chess/Standard.php';
$standard = new Games_Chess_Standard;
$standard->resetGame('rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2');
?>

How to move pieces with Games_Chess

There are two basic methods for performing moves with Games_Chess, moveSAN and moveSquare. Both of these methods either return TRUE or a PEAR_Error class upon error, so the proper way to handle for a return value is:

<?php
require_once 'Games/Chess/Standard.php';
$standard = new Games_Chess_Standard;
$err = $standard->moveSAN('Nf9');
if ($standard->isError($err)) {
    echo $err->getMessage();
    die;
}
?>

Note that Games_Chess->isError() should be used as the PEAR_Error class is only loaded when needed, to help with efficiency. If this is not a concern (and it will only be for sites serving thousands of pages per second), it is simpler to set a PEAR_Error callback, which is demonstrated in the next example.

The example below demonstrates the two ways that Games_Chess should be called to make moves on the chess board, including the way to represent a placement move in the Crazyhouse variant:

<?php
require_once 'PEAR.php'; // for the PEAR_Error class
function showerror($err)
{
    echo $err->getMessage();
    exit;
}
require_once 'Games/Chess/Standard.php';
require_once 'Games/Chess/Crazyhouse.php';
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'showerror');
$standard = new Games_Chess_Standard;
$crazyhouse = new Games_Chess_Crazyhouse;
$standard->resetGame();
$crazyhouse->resetGame();

$standard->moveSAN('e4'); // 'e2' to 'e4' if using moveSquare
$standard->moveSquare('d7', 'd5'); // 'd5' if using moveSAN
$standard->moveSAN('exd5');

$crazyhouse->moveSquare('e2', 'e4'); // same as moveSAN() above
$crazyhouse->moveSAN('d5'); // save as moveSquare above
$crazyhouse->moveSAN('exd5');
$crazyhouse->moveSAN('Qxd5');
$crazyhouse->moveSAN('P@d7'); // dumb move, but demonstrates piece placement
?>

Note that if promoting a pawn, moveSquare() requires that the newly promoted piece type be passed in. Options are Q for queen, R for rook, B for bishop and N for knight.

<?php
require_once 'PEAR.php'; // for the PEAR_Error class
function showerror($err)
{
    echo $err->getMessage();
    exit;
}
require_once 'Games/Chess/Crazyhouse.php';
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'showerror');
$crazyhouse = new Games_Chess_Crazyhouse;
$crazyhouse->resetGame();
$crazyhouse->moveSAN('e4');
$crazyhouse->moveSAN('d5');
$crazyhouse->moveSAN('exd5');
$crazyhouse->moveSAN('Qxd5');
$crazyhouse->moveSAN('d3');
$crazyhouse->moveSAN('Kd7');
$crazyhouse->moveSAN('d4');
$crazyhouse->moveSAN('Ke6');
$crazyhouse->moveSAN('P@d7');
$crazyhouse->moveSAN('Qd6');
// $crazyhouse->moveSAN('d8=Q'); // normal way to do this
$crazyhouse->moveSquare('d7', 'd8', 'Q'); // using moveSquare to do this
// dumb moves, but demonstrates pawn promotion to queen
?>

Retrieving information on the game in progress

To retrieve necessary information such as the current move list, current FEN, list of captured pieces (Crazyhouse only), determine whether the game is over and so on, you'll want to use one of the following methods:

  • gameOver(). This method can be used to determine if the game has concluded, and simply returns an abbreviation of W if the white pieces have won (checkmate), B if the black pieces have won (checkmate), D if there is a draw, or false if the game is still in progress.

  • renderFen().

    This method returns a Forsyth-Edwards Notation (FEN) representation of the current game state. Note that the FEN standard does not contain a way to represent captured pieces, and so cannot be used to exactly replicate a Crazyhouse game in progress, although it can be close.

  • toArray().

    For the Standard and Loser's chess drivers, this returns an associative array of algebraic square name (a1 to h8) mapped to its contents. If the square is unoccupied, it will contain its algebraic square name (a1 will map to a1), otherwise it will contain the piece name, one of P, R, N, B, Q or K. If the piece is a white piece, it will be in upper case, like P, and if the piece is a black piece, it will be in lower case like p.

    For the Crazyhouse driver, this returns an associative array with two indices, board and captured. The board element is identical to the return for Standard/Loser's chess drivers described in the previous paragraph. The captured sub-array contains an array of this format:

    <?php
    $captured     =
        array(
                'W' =>
                array(
                        'P' => 6, // 6 black pawns captured by white
                        'R' => 0,
                        'N' => 0,
                        'B' => 0,
                        'Q' => 0,
                ),
                'B' =>
                array(
                        'P' => 4, // 4 white pawns captured by black
                        'R' => 0,
                        'N' => 0,
                        'B' => 0,
                        'Q' => 0,
                ),
        );
    ?>

    Each segment represents white's or black's pieces (W and B), and each sub-element represents the number of captured pieces of that type. In the example above, white can choose to place a pawn for up to the next 6 moves in a row, whereas black can choose to place a pawn for up to the next 4 moves in a row.

  • toMove().

    This methods simply returns the color of the pieces that have the next move. W is returned for white, B is returned for black.

Prev | Games_Chess | Next
Games_Chess | PEAR Manual | Structures_Graph


Structures_Graph

Structures_Graph

Graph datastructure manipulation library

Table of Contents
  • Introduction -- Graph datastructure manipulation library
Prev | Structures | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Graph datastructure manipulation library

Structures_Graph Description

Structures_Graph is a package for creating and manipulating graph datastructures. It allows building of directed and undirected graphs, with data and metadata stored in nodes. The library provides functions for graph traversing as well as for characteristic extraction from the graph topology.

The full online documentation is available here

Prev | Structures_Graph | Next
Structures_Graph | PEAR Manual | Structures_LinkedList


Structures_LinkedList

Structures_LinkedList

This package implements linked list structures. It supports both singly-linked lists (Structures_LinkedList_Single) and doubly-linked lists (Structures_LinkedList_Double).

Prev | Structures | Next
Introduction | PEAR Manual | Structures_Tree


Structures_Tree

Structures_Tree

Generic tree management, currently supports DB and XML as data sources

Table of Contents
  • Introduction -- Generic tree management, currently supports DB and XML as data sources
Prev | Structures | Next
Structures_LinkedList | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Generic tree management, currently supports DB and XML as data sources

Structures_Tree Description

Provides methods to read and manipulate trees, which are stored in the DB or an XML file. The trees can be stored in the DB either as nested trees. Or as simple trees ('brain dead method'), which use parentId-like structure. Currently XML data can only be read from a file and accessed. The package offers a big number of methods to access and manipulate trees. For example methods like: getRoot, getChild[ren[Ids]], getParent[s[Ids]], getPath[ById] and many more.

Unfortunately, complete documentation is not available at the moment.

Prev | Structures_Tree | Next
Structures_Tree | PEAR Manual | System


System

System

System Utilities

Table of Contents
  • System_Folders
  • System_Mount
  • System_Daemon
  • System_ProcWatch
  • System_WinDrives
Prev | PEAR Packages | Next
Introduction | PEAR Manual | System_Folders


System_Folders

System_Folders

Returns locations of system folders like home, desktop, documents and others.

Table of Contents
  • Introduction -- Get system folder locations.
  • Example -- How to use System_Folders
Prev | System | Next
System | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Get system folder locations.

Contributors

  • Christian Weiske

Description

System_Folders provides methods to get the locations of various system folders like home directory, desktop folder and "My documents". You can use it on nearly every operating system: It works on Linux, Windows and Mac OS; allowing you to write OS independent programs.

The methods return a string of the directory (with trailing slash) if the directory can be determined, and NULL if it fails or isn't available on the system. For example, the "Shared Documents" folder exists on Windows only. If you run getSharedDocuments() on a Mac or Linux, the method will return NULL.

The class does heavy use of environment variables. That means it is very likely that the methods fail when running in a php server module (e.g. apache) because there is user information available. Using them on command line (cli) scripts gives best results, as the class is meant to be used for such ones.

Available folders and their methods
Folder | Method to use | Notes
All users directory | getAllUsers() | Windows only
Application data | getAppData() |
Desktop | getDesktop() |
Documents / My Documents | getDocuments() |
Home directory | getHome() |
Programs folder (installed ones) | getPrograms() |
Temporary files | getTemp() |
Shared documents | getSharedDocuments() | Windows only
Windows directory | getWindows() | Windows only

System_Folders_Cached

On every getXXX() call, the whole procedure of looping through environment variables, checking the existence of the folders and trying some common locations is executed. So if you call the same method again and again, it will cost you the same amount of cpu cycles every time and perhaps be a slowdown in your application.

Another problem might be that some methods fail or don't return the correct path, e.g. because the user has an unusual installation or unusual preferences.

Both issues are addressed with System_Folders_Cached. It provides a cached version of the getXXX() methods, meaning that the result of the first method calls are stored locally and returned on every further call, which speeds up consecutive calls to the same method a lot.

Further, the class provides methods to set the folder locations and save this settings into an ini file. Saving them can be done with saveToFile() and they can be loaded with loadFromFile(). This allows customization of the folder locations, and persistency across sessions.

Prev | System_Folders | Next
System_Folders | PEAR Manual | Example


Example

Example

Example – How to use System_Folders

Using System_Folders

General usage

<?php
require_once 'System/Folders.php';

$sf = new System_Folders();

$arData = array(
'Username'         => $sf->getUserName(),
'Home'             => $sf->getHome(),
'Documents'        => $sf->getDocuments(),
'Shared documents' => $sf->getSharedDocuments(),
'Temp'             => $sf->getTemp(),
'Desktop'          => $sf->getDesktop(),
'AppData'          => $sf->getAppData(),
'Programs'         => $sf->getPrograms(),
'Windows'          => $sf->getWindows()
);

echo 'System: ' . $sf->getSys() . "\r\n";
var_dump($arData);
?>

At first, you need to instantitiate a new System_Folders object. The operating system is determined there, which is needed for all the other methods.

Then just use the getXXX() methods to retrieve the folder locations. Remember that they return NULL if the location can't be determined.

Using System_Folders_Cached

General usage

<?php
require_once 'System/Folders/Cached.php';
$sf = new System_Folders_Cached();

//show the path of the config file
echo 'Config file: ' . $sf->getDefaultConfigFile() . "\r\n";

//load the stored settings from last time
$err = $sf->loadFromFile();

echo 'Home:      ' . $sf->getHome() . "\r\n";
echo 'Documents: ' . $sf->getDocuments() . "\r\n";

echo "\r\n";

$doc = $sf->getDocuments();
if (file_exists($doc)) {
    echo "Setting new Documents directory\r\n";
    //Set an own documents directory
    // and save the settings for next time
    $sf->setDocuments('/strange/path/to/MyDocuments/');
    $sf->saveToFile();
    echo 'New Documents directory: ' . $sf->getDocuments() . "\r\n";
    echo "Run this program again to reset the path to default\r\n";
} else {
    //unset the path
    echo "Unsetting the documents directory\r\n";
    $sf->setDocuments(null);
    $sf->saveToFile();
    echo 'New Documents directory: ' . $sf->getDocuments() . "\r\n";
}
?>

This example displays the location of the config file (in which the folder settings are stored), shows some folder locations and sets the documents directory to a (probably non-existing) directory and saves the folder locations.

In the next program call, the documents directory is reset to the normal one and saved again.

Prev | System_Folders | Next
Introduction | PEAR Manual | System_Mount


System_Mount

System_Mount

This package allows you to mount and unmount disks and partitions listed in your file systems table (/etc/fstab), which is found on Unix/Linux based systems.

You can install this package by using pear install System_Mount. Once you have the package installed it is very easy to use.

Table of Contents
  • Introduction -- Mount and Unmount filesystems
Prev | System | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Mount and Unmount filesystems

Contributors

  • Brett Bieber

Description

System_Mount provides methods to mount and unmount filesystems and partitions listed in a system's /etc/fstab. The fstab file is common on Unix/Linux based systems and is used to list the available filesystems and partitions which users can mount into the filesystem hierarchy. Common entries include root partitions, boot partitions, as well as cdrom drives and other removable media.

The System_Mount command utilizes File_Fstab to discover entries in the /etc/fstab file, and allow easy mount/unmount operations.

Using System_Mount

General usage

<?php
require_once 'System/Mount.php';

// Create the mount class
$m = new System_Mount();

// Get an object representing the CD-ROM entry
$cdrom = $m->getEntryForPath('/media/cdrom0');

if (PEAR::isError($cdrom)) {
    die($cdrom->message."\n");
}

// Mount it
$res = $cdrom->mount();
if (PEAR::isError($res)) {
    die($res->getMessage()."\n");
}

// List its contents
print `ls {$cdrom->mountPoint}`;

// Unmount it
$cdrom->unmount();
if (PEAR::isError($res)) {
    die($res->getMessage()."\n");
}
?>

At first, you need to instantitiate a new System_Mount object.

Use the mount point for the corresponding entry in your /etc/fstab to obtain an object to mount, then check if there are any errors. If there are no errors mount the cdrom.

Prev | System_Mount | Next
System_Mount | PEAR Manual | System_Daemon


System_Daemon

System_Daemon

Allows developers to create their own daemon applications on Linux systems using nothing but PHP.

Table of Contents
  • Introduction to System_Daemon
  • What is a Daemon?
  • Why PHP?
  • Possible use cases
  • What is a Daemon?
  • How it works internally
  • System_Daemon
  • System_Daemon examples
  • Console action
  • Troubleshooting
Prev | System | Next
Introduction | PEAR Manual | Introduction to System_Daemon


Introduction to System_Daemon

Introduction to System_Daemon

Everyone knows PHP can be used to create websites. But it can also be used to create desktop applications and commandline tools. And now with a class called System_Daemon, you can even create daemons using nothing but PHP. And did I mention it was easy?

This how-to was ported from: http://kevin.vanzonneveld.net/techblog/article/create_daemons_in_php/. you can leave a comment there as well.

Prev | System_Daemon | Next
System_Daemon | PEAR Manual | What is a Daemon?


What is a Daemon?

What is a Daemon?

A daemon is a Linux program that run in the background, just like a 'Service' on Windows. It can perform all sorts of tasks that do not require direct user input. Apache is a daemon, so is MySQL. All you ever hear from them is found in somewhere in /var/log, yet they silently power over 40% of the Internet. You reading this page, would not have been possible without them. So clearly: a daemon is a powerful thing, and can be bend to do a lot of different tasks.

Prev | System_Daemon | Next
Introduction to System_Daemon | PEAR Manual | Why PHP?


Why PHP?

Why PHP?

Most daemons are written in C. It's fast & robust. But if you are in a LAMP oriented company like me, and you need to create a lot of software in PHP anyway, it makes sense:

  • Efficiency. Reuse & connect existing code Think of database connections, classes that create customers from your CRM, etc.

  • Speed. Deliver new applications very fast PHP has a lot of build in functions that speed up development greatly.

  • Continuity. Everyone knows PHP (right?) If you work in a small company: chances are there are more PHP programmers than there are C programmers. What if your C guy abandons ship?

Prev | System_Daemon | Next
What is a Daemon? | PEAR Manual | Possible use cases


Possible use cases

Possible use cases

  • Website optimization If you're running a (large) website, jobs that do heavy lifting should be taken away from the user interface and scheduled to run on the machine separately.

  • Log parser Continually scan logfiles and import critical messages in your database.

  • SMS daemon Read a database queue, and let your little daemon interface with your SMS provider. If it fails, it can easily try again later!

  • Video converter (think Youtube) Scan a queue/directory for incoming video uploads. Make some system calls to ffmpeg to finally store them as Flash video files. Surely you don't want to convert video files right after the upload, blocking the user interface that long? No: the daemon will send the uploader a mail when the conversion is done, and proceed with the next scheduled upload

Prev | System_Daemon | Next
Why PHP? | PEAR Manual | What is a Daemon?


What is a Daemon?

What is a Daemon?

Some people use cronjobs for the same Possible use cases. Crontab is fine but it only allows you to run a PHP file every minute or so.

  • What if the previous run hasn't finished yet? Overlap can seriously damage your data & cause siginificant load on your machines.

  • What if you can't afford to wait a minute for the cronjob to run? Maybe you need to trigger a process the moment a record is inserted?

  • What if you want to keep track of multiple 'runs' and store data in memory.

  • What if you need to keep your application listening (on a socket for example)

Cronjobs are a bit rude for this, they may spin out of control and don't provide a framework for logging, etc. Creating a daemon would offer more elegance & possibilities. Let's just say: there are very good reasons why a Linux OS isn't composed entirely of Cronjobs :)

Prev | System_Daemon | Next
Possible use cases | PEAR Manual | How it works internally


How it works internally

How it works internally

Nerd alert!) When a daemon program is started, it fires up a second child process, detaches it, and then the parent process dies. This is called forking. Because the parent process dies, it will give the console back and it will look like nothing has happened. But wait: the child process is still running. Even if you close your terminal, the child continues to run in memory, until it either stops, crashes or is killed. In PHP: forking can be achieved by using the Process Control Extensions. Getting a good grip on it, may take some studying though.

Prev | System_Daemon | Next
What is a Daemon? | PEAR Manual | System_Daemon


System_Daemon

System_Daemon

Because the Process Control Extensions' documentation is a bit rough, I decided to figure it out once, and then wrap my knowledge and the required code inside a PEAR class called: System_Daemon. And so now you can just:

System_Daemon Usage

<?php
    require_once "System/Daemon.php";                 // Include the Class

    System_Daemon::setOption("appName", "mydaemon");  // Minimum configuration
    System_Daemon::start();                           // Spawn Deamon!
?>

And that's all there is to it. The code after that, will run in your server's background. So next, if you create a while(true) loop around that code, the code will run indefinitely. Remember to build in a sleep(5) to ease up on system resources.

Features & Characteristics Here's a grab of System_Daemon's features:

  • Daemonize any PHP-CLI script

  • Simple syntax

  • Driver based Operating System detection

  • Unix only

  • Additional features for Debian / Ubuntu based systems like:

  • Automatically generate startup files (init.d)

  • Support for PEAR's Log package

  • Can run with PEAR (more elegance & functionality) or without PEAR (for standalone packages)

  • Default signal handlers, but optionally reroute signals to your own handlers.

  • Set options like max RAM usage

Prev | System_Daemon | Next
How it works internally | PEAR Manual | System_Daemon examples


System_Daemon examples

System_Daemon examples

Table of Contents
  • System_Daemon examples

To get the feeling how System_Daemon is used, try out the following examples.

Prev | System_Daemon | Next
System_Daemon | PEAR Manual | System_Daemon examples


System_Daemon examples

System_Daemon examples

If you run this code successfully, a daemon will be spawned and stopped directly. You should find a log enty in /var/log/simple.log

#!/usr/bin/php -q
<?php
/**
 * System_Daemon turns PHP-CLI scripts into daemons.
 *
 * PHP version 5
 *
 * @category  System
 * @package   System_Daemon
 * @author    Kevin <kevin@vanzonneveld.net>
 * @copyright 2008 Kevin van Zonneveld
 * @license   http://www.opensource.org/licenses/bsd-license.php New BSD Licence
 * @version   SVN: Release: $Id: simple.php,v 1.1 2009/02/20 16:55:07 kvz Exp $
 * @link      http://trac.plutonia.nl/projects/system_daemon
 */

/**
 * System_Daemon Example Code
 *
 * If you run this code successfully, a daemon will be spawned
 * and stopped directly. You should find a log enty in
 * /var/log/simple.log
 *
 */

// Make it possible to test in source directory
// This is for PEAR developers only
ini_set('include_path', ini_get('include_path').':..');

// Include Class
error_reporting(E_ALL);
require_once "System/Daemon.php";

// Bare minimum setup
System_Daemon::setOption("appName", "simple");
System_Daemon::setOption("authorEmail", "kevin@vanzonneveld.net");

//System_Daemon::setOption("appDir", dirname(__FILE__));
System_Daemon::log(System_Daemon::LOG_INFO, "Daemon not yet started so ".
    "this will be written on-screen");

// Spawn Deamon!
System_Daemon::start();
System_Daemon::log(System_Daemon::LOG_INFO, "Daemon: '".
    System_Daemon::getOption("appName").
    "' spawned! This will be written to ".
    System_Daemon::getOption("logLocation"));

// Your normal PHP code goes here. Only the code will run in the background
// so you can close your terminal session, and the application will
// still run.

System_Daemon::stop();
?>
Prev | System_Daemon examples | Next
System_Daemon examples | PEAR Manual | Console action


Console action

Console action

Now that we've created an example daemon, it's time to fire it up! I'm going to assume the name of your daemon is logparser. This can be changed with the statement:

<?php
    System_Daemon::setOption("appName", "logparser")
?>

But the name of the daemon is very important because it is also used in filenames (like the logfile).

Execute Just make your daemon script executable, and then execute it:

    chmod a+x ./logparser.php
    ./logparser.php

Check Your daemon has no way of communicating through your console, so check for messages in:

    tail /var/log/logparser.log

And see if it's still running:

    ps uf -C logparser.php

Kill Without the start/stop files (see below for howto), you need to:

    killall -9 logparser.php

Autch.. Let's work on those start / stop files, right?

Start / Stop files (Debian & Ubuntu only) Real daemons have an init.d file. Remember you can restart Apache with the following statement?

    /etc/init.d/apache2 restart

That's a lot better than killing. So you should be able to control your own daemon like this as well:

    /etc/init.d/logparser stop
    /etc/init.d/logparser start

Well with System_Daemon you can write autostartup files using the writeAutoRun() method, look:

<?php
    $path = System_Daemon::writeAutoRun();
?>

On success, this will return the path to the autostartup file: /etc/init.d/logparser, and you're good to go!

Run on boot Surely you want your daemon to run at system boot.. So on Debian & Ubuntu you could type:

        update-rc.d logparser defaults

Done your daemon now starts every time your server boots. Cancel it with:

        update-rc.d -f logparser remove
Prev | System_Daemon | Next
System_Daemon examples | PEAR Manual | Troubleshooting


Troubleshooting

Troubleshooting

Here are some issues you may encounter down the road.

  • Connect to MySQL after you start() the daemon. Otherwise only the parent process will have a MySQL connection, and since that dies.. It's lost and you will get a 'MySQL has gone away' error.

  • Error handling Good error handling is imperative. Daemons are often mission critical applications and you don't want an uncatched error to bring it to it's knees.

    • Reconnect to MySQL A connection may be interrupted. Think about network downtime or lock-ups when your database server makes backups. Whatever the cause: You don't want your daemon to die for this, let it try again later.

    • Write your own php error handler It should forward all the PHP errors to the log() method, so they end up in your logfile. Otherwise it's very hard to spot errors, since the daemon has no way of writing to your console anymore! See set_error_handler.

  • Monit Monit is a standalone program that can kickstart any daemon, based on your parameters. Should your daemon fail, monit will mail you and try to restart it.

I know I'm saying MySQL a lot, but you can obviously replace that with Oracle, MSSQL, PostgreSQL, etc.

Prev | System_Daemon | Next
Console action | PEAR Manual | System_ProcWatch


System_ProcWatch

System_ProcWatch

The package provides methods to monitor system process on Unix-like systems.

Table of Contents
  • Introduction and Features
  • Configuration
  • Parser Information
Prev | System | Next
Troubleshooting | PEAR Manual | Introduction and Features


Introduction and Features

Introduction and Features

Table of Contents
  • Intro -- Introduction to System::ProcWatch
  • Constants -- Constants defined in and used by System_ProcWatch
  • System_ProcWatch
  • System_ProcWatch::System_ProcWatch -- Constructor
  • System_ProcWatch::run -- Run once
  • System_ProcWatch::daemon -- Run in daemon mode
  • System_ProcWatch::setConfig -- Set configuration
Prev | System_ProcWatch | Next
System_ProcWatch | PEAR Manual | Intro


Intro

Intro

Intro – Introduction to System::ProcWatch

What is System::ProcWatch?

System::ProcWatch is a small collection of classes to ease monitoring of system processes based on the Unix program procps (ps).

To use System::ProcWatch you simply have to define a ruleset on which based System::ProcWatch operates. A rule (or job, watch) defines what actions should happen if a condition evaluates to true.

To be continued...

Shell Scripts

You can use System::ProcWatch out of the box, by utilizing the shipped shell scripts procwatch and procwatch-lint.

procwatch

The procwatch command is meant to be used for system diagnosis - run as daemon or by cron.

The usage is best described by the output of procwatch -h:

USAGE:
$ procwatch (-x|-i) <file> [-d [-s <sec>]] [-a <args>] [-p <file>]

OPTIONS:
-x | --xml= path to XML configuration file
-i | --ini= path to INI configuration file

-d | --daemon run procwatch in daemon mode
-s | --sleep= seconds to sleep in daemon mode (default=1800)

-a | --args= arguments that should be passed to ps (default=aux)
-p | --php= php file that should be included

-h | --help this help message

EXAMPLE:
$ procwatch -x /etc/procwatch.xml -d -s 3600

This command will run procwatch in daemon mode with an interval
of an hour using the configuration file '/etc/procwatch.xml'

procwatch-lint

The procwatch-lint is meant to validate procwatchs configurtation files written in XML by utilizing XML::DTD::XmlValidator.

Once again synopsis is best described by the output of procwatch-lint -h:

USAGE:
$ procwatch-lint -c <file> [-d <dtd>] [-v]

OPTIONS:
-c | --conf= path to XML configuration file
-d | --dtd= path to DTD

-v | --verbose verbose output on errors

-h | --help this help message

EXAMPLE:
procwatch-lint -c /etc/procwatch.xml

This command will validate the configuration file '/etc/procwatch.xml'
using the DTD at '/usr/share/pear/data/System_ProcWatch/procwatch-1.0.dtd'

Configuration

There are three methods to configure your System::ProcWatch application:

  • XML string/file

  • INI file

  • PHP array

Xml string/file

Configuring System::ProcWatch by XML is the preferred way. It is as simple as powerful.

Ruleset: The Root Element

The root element of an XML configuration file/string is the procwatch element. It has one implicit attribute, the version attribute, set to "1.0".

The procwatch element symbolizes our ruleset, and the childs of the root are our rules.

Rules: The Childs of the Root

The direct descendants of the root element procwatch, are the watch elements, which can occur 1 time or more often.

The watch element has one required attribute, the name attribute, which gives the watch (or job, rule) a descriptive name like "httpd-count".

Each watch element symbolizes a single rule, containing a regular expression to search for, one or more conditions to evaluate and one or more actions to be taken.

A Rule

A rule consists of three child elements:

  • pattern

  • condition

  • execute

Rule Element: pattern

The pattern element describes the perl compatible regular expression which should be evaluated against a column of the output of ps.

There is one required attribute, the match attribute, defining the column name of the output of ps in lowercase like "command" or "vsz".

This makes System::ProcWatch highliy versatile and should make it usable with any platforms procps program.

The pattern elements content solely consists of the perl compatible regular expression to match against the column defined in the match attribute. The PCRE MUST contain the start and end delimiter and MAY contain any PCRE modifiers.

Example: <pattern match="command">/sbin\/httpd/</pattern>

Rule Element: condition

The condition element defines conditions that MUST evaluate to TRUE at all so that later defined actions will be executed.

The condition element has one required and one optional attribute, the required one being type, which MUST be one of "presence" or "attr", and the optional one being attr. However, if the type attribute equals to "attr" the attr attribute MUST be present.

The attr attribute represents a column of procps' output like "user" or "%mem".

Conditions

Dependent on the content of the type attribute, syntax and behavior of the condition element differ.

A condition with type "presence" MAY be empty, thus always evaluating to true.

Child Elements of condition may be:

  • min

    Found value MUST exceed defined value.

  • max

    Found value MUST NOT exceed defined value.

  • is

    Found value MUST be equal to defined value.

  • isnot

    Found value MUST NOT be equal to defined value.

  • sum

    The sum of found values MUST NOT exceed defined sum.

You may combine them to define for instance a range from min to max.

Rule Element: execute

The execute element defines actions that should be taken if the condition applies.

It has one required attribute, the type attribute, which MUST equal to one of "shell" or "php".

Obviously the content of the execute element is executed either on the shell through shell_exec() or directly in PHP through eval().

The execute element MAY occur any times.

There are some special variables that will automagically be available in execute statements:

  • $msg

    This contains a general message, what has happened. It is quoted in single quotes for save usage and is available in shell and php executes.

  • $pids

    This contains all PIDs of the processes that have been found. They are enclosed by single quotes and parenthesis.

    Example: '(433, 444, 455, 466)'

  • $procs

    This is a serialized php array in string format containing all information gained from ps and looks like: array(array('pid' => 344, 'command' => '/usr/sbin/httpd' ...))

    It is only available in php executes and can easily be used in function callbacks:

    <execute type="php">get_procs($procs);</execute>

Example XML configuration file

XML configuration file

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE procwatch SYSTEM "/usr/share/pear/data/System_ProcWatch/procwatch-1_0.dtd">
<procwatch>
<!--

    SOME EXAMPLE CONFIGURATIONS
    ===========================

    This job looks for the count of running httpd processes by
    matching the PCRE "/httpd/" against the COMMAND column of ps.

    If there are less than 10 or more than 30 httpd processes found
    the speicified string is executed on the shell.
-->
  <watch name="httpd-count">
    <pattern match="command">/httpd/</pattern>
    <condition type="presence">
      <min>10</min>
      <max>30</max>
    </condition>
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

<!--
  This job looks for the amount of physical memory all httpd processes use
  together by matching the PCRE "/httpd/" against the COMMAND column of ps.

  It adds all %MEM columns of ps that match the pattern together and compares
  the reslut to the specified sum. If the result exceeds the sum the specified
  string is executet on the shell.
-->
  <watch name="httpd-usage">
    <pattern match="command">/httpd/</pattern>
    <condition type="attr" attr="%mem">
      <sum>5</sum>
    </condition>
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

<!--
  This job looks for zombie processes.

  It matches the PCRE "/Z/" against the STAT column of ps and executes the
  specified string on the shell if more than 0 zombies have been found.
-->
  <watch name="ZOMBIES">
    <pattern match="stat">/Z/</pattern>
    <condition type="presence">
      <max>0</max>
    </condition>
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

<!--
  This job looks for running processes.

  It matches the PCRE pattern "/R/" against the STAT column of ps and executes
  the specified string on the shell if any running processes have been found.
-->
  <watch name="running">
    <pattern match="stat">/R/</pattern>
    <condition type="presence" />
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

</procwatch>

INI file

Configuring by INI file is effectively the same except that only executes of type "shell" can be defined.

Example INI configuration file

INI configuration file

;
; Example INI file to configure System::ProcWatch
;
; Be aware that you only can define shell executes!
; For better configurability use XML configuration files.
;
[httpd]
pattern=/httpd/
match=command
condition=presence
min=10
max=50
execute="echo $msg >> /var/log/procwatch"

[zombies]
pattern=/Z/
match=stat
condition=presence
max=0
execute="kill -9 `echo $pids | sed s/[,\(\)]//g`"

[mysqld-mem]
pattern=/mysqld/
match=command
condition=attr
attr=%mem
sum=10
execute="echo $msg >> /var/log/procwatch"

PHP array

A valid array to configure System::ProcWatch may look similar to the following example.

Example PHP configuration array

PHP configuration array

<?php
$watches = array();

$watches['job1'] = array();
$watches['job1']['pattern'] = array();
$watches['job1']['condition'] = array();
$watches['job1']['execute'] = array();

$watches['job1']['pattern']['command'] = '/httpd/';
$watches['job1']['condition']['presence'] = array('min' => 10, 'max' => 100);
$watches['job1']['execute']['shell'] = array('/usr/bin/mail2admin $msg');

$watches['job2'] = array();
// ...
?>
Prev | Introduction and Features | Next
Introduction and Features | PEAR Manual | Constants


Constants

Constants

Constants – Constants defined in and used by System_ProcWatch

All Constants

Constants defined in ProcWatch.php

This constants are mostly used internally by System_ProcWatch

Constants defined in ProcWatch.php
Name
SYSTEM_PROCWATCH_IS
SYSTEM_PROCWATCH_ISNOT
SYSTEM_PROCWATCH_MAX
SYSTEM_PROCWATCH_MIN
SYSTEM_PROCWATCH_PRESENCE
SYSTEM_PROCWATCH_PRESENCE_MAX
SYSTEM_PROCWATCH_PRESENCE_MIN
SYSTEM_PROCWATCH_SUM
Prev | Introduction and Features | Next
Intro | PEAR Manual | System_ProcWatch


System_ProcWatch

System_ProcWatch

System_ProcWatch – System_ProcWatch

System_ProcWatch

Monitor processes

Usage:

<?php
1  require_once 'System/ProcWatch.php';
2  require_once 'System/ProcWatch/Config.php';
3
4  $cf =
?> System_ProcWatch_Config <?php
::
?> fromXmlFile <?php
('/etc/procwatch.xml');
5  $pw = &new
?> System_ProcWatch <?php
($cf);
6  $pw->
?> run <?php
();
?>
Prev | Introduction and Features | Next
Constants | PEAR Manual | System_ProcWatch::System_ProcWatch


System_ProcWatch::System_ProcWatch

System_ProcWatch::System_ProcWatch

System_ProcWatch::System_ProcWatch() – Constructor

Synopsis

require_once 'System/ProcWatch.php';

object &new System_ProcWatch ( array $config )

Description

Instantiate a new System_ProcWatch object configured by the supplied configuration array.

Parameter

array $config

config array from System_ProcWatch_Config

Prev | Introduction and Features | Next
System_ProcWatch | PEAR Manual | System_ProcWatch::run


System_ProcWatch::run

System_ProcWatch::run

System_ProcWatch::run() – Run once

Synopsis

void System_ProcWatch::run ( string $ps_args = 'aux' )

Description

Run once.

Parameter

string $ps_args

arguments that should be passed to ps

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Introduction and Features | Next
System_ProcWatch::System_ProcWatch | PEAR Manual | System_ProcWatch::daemon


System_ProcWatch::daemon

System_ProcWatch::daemon

System_ProcWatch::daemon() – Run in daemon mode

Synopsis

void System_ProcWatch::daemon ( int $interval , string $ps_args = 'aux' )

Description

Runs System_ProcWatch in daemon mode with the defined interval of seconds to sleep.

Parameter

integer $interval

seconds to sleep

string $ps_args

ps' arguments

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Introduction and Features | Next
System_ProcWatch::run | PEAR Manual | System_ProcWatch::setConfig


System_ProcWatch::setConfig

System_ProcWatch::setConfig

System_ProcWatch::setConfig() – Set configuration

Synopsis

void System_ProcWatch::setConfig ( array $config )

Description

Configure System_ProcWatch with an config array from System_ProcWatch_Config.

Parameter

array $config

config array from System_ProcWatch_Config

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Introduction and Features | Next
System_ProcWatch::daemon | PEAR Manual | Configuration


Configuration

Configuration

Table of Contents
  • System_ProcWatch_Config
  • System_ProcWatch_Config::fromXml -- Get config array from XML string
  • System_ProcWatch_Config::fromXmlFile -- Get config array from XML file
  • System_ProcWatch_Config::fromIniFile -- Get config array from INI file
  • System_ProcWatch_Config::fromArray -- Get config array from an array
Prev | System_ProcWatch | Next
System_ProcWatch::setConfig | PEAR Manual | System_ProcWatch_Config


System_ProcWatch_Config

System_ProcWatch_Config

System_ProcWatch_Config – System_ProcWatch_Config

System_ProcWatch_Config

Build a configuration array for System_ProcWatch

Usage:

1  $cf =
System_ProcWatch_Config
::
fromXmlFile
('/etc/procwatch.xml');
2  $pw = &new
System_ProcWatch
($cf);
Prev | Configuration | Next
Configuration | PEAR Manual | System_ProcWatch_Config::fromXml


System_ProcWatch_Config::fromXml

System_ProcWatch_Config::fromXml

System_ProcWatch_Config::fromXml() – Get config array from XML string

Synopsis

require_once 'System/ProcWatch/Config.php';

mixed System_ProcWatch_Config::fromXml ( string $xml )

Description

Parses an XML string into an config array to configure System_ProcWatch with.

Parameter

string $xml

XML string

Return value

Returns config array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if XML file does not exist or problems parsing the XML string have occured.

See

Configuration by XML file

Note

This function should be called statically.

Prev | Configuration | Next
System_ProcWatch_Config | PEAR Manual | System_ProcWatch_Config::fromXmlFile


System_ProcWatch_Config::fromXmlFile

System_ProcWatch_Config::fromXmlFile

System_ProcWatch_Config::fromXmlFile() – Get config array from XML file

Synopsis

require_once 'System/ProcWatch/Config.php';

mixed System_ProcWatch_Config::fromXmlFile ( string $file )

Description

Parses an XML file into an config array to configure System_ProcWatch with.

Parameter

string $file

path to XML file

Return value

Returns config array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if XML file does not exist, or problems parsing the XML file have occured.

See

Configuration by XML file

Note

This function should be called statically.

Prev | Configuration | Next
System_ProcWatch_Config::fromXml | PEAR Manual | System_ProcWatch_Config::fromIniFile


System_ProcWatch_Config::fromIniFile

System_ProcWatch_Config::fromIniFile

System_ProcWatch_Config::fromIniFile() – Get config array from INI file

Synopsis

require_once 'System/ProcWatch/Config.php';

mixed System_ProcWatch_Config::fromIniFile ( string $file )

Description

Parses an INI file into an array to configure System_ProcWatch with.

INI configuration file

Parameter

string $file

path to INI file

Return value

Returns config array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if INI file doesn't exist.

See

Configuration by INI file

Note

This function should be called statically.

Prev | Configuration | Next
System_ProcWatch_Config::fromXmlFile | PEAR Manual | System_ProcWatch_Config::fromArray


System_ProcWatch_Config::fromArray

System_ProcWatch_Config::fromArray

System_ProcWatch_Config::fromArray() – Get config array from an array

Synopsis

require_once 'System/ProcWatch/Config.php';

mixed System_ProcWatch_Config::fromArray ( mixed $array )

Description

This method in fact does a sanity check on the supplied config array and should only be used for testing purposes.

Parameter

array $array

config array to check

Return value

Returns the same array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if an invalid configuration array was supplied.

Note

This function should be called statically.

Prev | Configuration | Next
System_ProcWatch_Config::fromIniFile | PEAR Manual | Parser Information


Parser Information

Parser Information

Table of Contents
  • System_ProcWatch_Parser
  • System_ProcWatch_Parser::System_ProcWatch_Parser -- Constructor
  • System_ProcWatch_Parser::getParsedData -- Get parsed data
  • System_ProcWatch_Parser::fetch -- Fetch ps' data
  • System_ProcWatch_Parser::parse -- Parse
  • System_ProcWatch_Parser::getProcByPid -- Get info about a process by its PID
  • System_ProcWatch_Parser::getProcInfo -- Get information about processes
Prev | System_ProcWatch | Next
System_ProcWatch_Config::fromArray | PEAR Manual | System_ProcWatch_Parser


System_ProcWatch_Parser

System_ProcWatch_Parser

System_ProcWatch_Parser – System_ProcWatch_Parser

System_ProcWatch_Parser

Fetches output from `ps` and parses it into an associative array

Usage:

1   $ps = &new
System_ProcWatch_Parser
();
2   $pd = &$ps->
getParsedData
();
Prev | Parser Information | Next
Parser Information | PEAR Manual | System_ProcWatch_Parser::System_ProcWatch_Parser


System_ProcWatch_Parser::System_ProcWatch_Parser

System_ProcWatch_Parser::System_ProcWatch_Parser

System_ProcWatch_Parser::System_ProcWatch_Parser() – Constructor

Synopsis

require_once 'System/ProcWatch/Parser.php';

object &new System_ProcWatch_Parser ( string $ps_args = 'aux' )

Description

Instantiates a new System_ProcWatch parser object with the supplied arguments to pass to ps.

Parameter

string $ps_args

ps' arguments

Throws

Throws no exception.

Prev | Parser Information | Next
System_ProcWatch_Parser | PEAR Manual | System_ProcWatch_Parser::getParsedData


System_ProcWatch_Parser::getParsedData

System_ProcWatch_Parser::getParsedData

System_ProcWatch_Parser::getParsedData() – Get parsed data

Synopsis

array &System_ProcWatch_Parser::getParsedData ( string $ps_args = 'aux' , bool $refresh = false )

Description

This is the main method of this class. It fetches to output of ps, executed on the shell, and returns the parsed data as an 2 dimensional indexed and associatve array.

Parameter

string $ps_args

ps' arguments

boolean $refresh

whether to refresh our data

Return value

Returns array of processes parsed from ps' output.

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Parser Information | Next
System_ProcWatch_Parser::System_ProcWatch_Parser | PEAR Manual | System_ProcWatch_Parser::fetch


System_ProcWatch_Parser::fetch

System_ProcWatch_Parser::fetch

System_ProcWatch_Parser::fetch() – Fetch ps' data

Synopsis

string System_ProcWatch_Parser::fetch ( string $ps_args = '' )

Description

Fetches the output of ps, executed on the shell.

Parameter

string $ps_args

ps' arguments

Return value

Returns string ps' output.

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Parser Information | Next
System_ProcWatch_Parser::getParsedData | PEAR Manual | System_ProcWatch_Parser::parse


System_ProcWatch_Parser::parse

System_ProcWatch_Parser::parse

System_ProcWatch_Parser::parse() – Parse

Synopsis

array System_ProcWatch_Parser::parse ( string $data )

Description

Parses the output of ps.

Parameter

string $data

output of ps

Return value

Returns array of processes.

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Parser Information | Next
System_ProcWatch_Parser::fetch | PEAR Manual | System_ProcWatch_Parser::getProcByPid


System_ProcWatch_Parser::getProcByPid

System_ProcWatch_Parser::getProcByPid

System_ProcWatch_Parser::getProcByPid() – Get info about a process by its PID

Synopsis

array System_ProcWatch_Parser::getProcByPid ( int $pid )

Description

Get information about a process by its PID.

Parameter

integer $pid

the PID of the process

Return value

Returns array with information about the process with the supplied PID.

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Parser Information | Next
System_ProcWatch_Parser::parse | PEAR Manual | System_ProcWatch_Parser::getProcInfo


System_ProcWatch_Parser::getProcInfo

System_ProcWatch_Parser::getProcInfo

System_ProcWatch_Parser::getProcInfo() – Get information about processes

Synopsis

array System_ProcWatch_Parser::getProcInfo ( string $pattern , string $search )

Description

Get information about processes matching the defined search.

Parameter

string $pattern

PCRE to match for process

string $search

the ps field/column to search in

Return value

Returns array of processes matching the search.

Throws

Throws no exception.

Note

This function can not be called statically.

Prev | Parser Information | Next
System_ProcWatch_Parser::getProcByPid | PEAR Manual | System_WinDrives


System_WinDrives

System_WinDrives

Provides functions to enumerate root directories ("Drives") on Windows systems by using win32 api calls.

Table of Contents
  • Introduction -- Enumerating drives on Windows systems
  • Example -- How to use System_WinDrives
  • Constants -- Constants defined and used in System_WinDrives
  • System_WinDrives() -- Outputs short description of the method
  • System_WinDrives::getDriveList() -- Gets array with path of all drives
  • System_WinDrives::getDriveName() -- Returns the user-defined name for a drive
  • System_WinDrives::getDrivesInformation() -- Gets information about all drives
  • System_WinDrives::getDriveType() -- Gets the type of a drive
  • System_WinDrives::getReadName() -- Returns if drive names shall be read or not
  • System_WinDrives::getTypeTitle() -- Gets the readable name to a drive type
  • System_WinDrives::guessDriveList() -- Tries to guess the drive list
  • System_WinDrives::isApiAvailable() -- Checks if the API is available
  • System_WinDrives::setReadName() -- Sets the readName setting
Prev | System | Next
System_ProcWatch_Parser::getProcInfo | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Enumerating drives on Windows systems

Contributors

  • Christian Weiske

Description

System_WinDrives uses win32 api calls to get a list of all installed roots ("Drives") on the current Windows operating system (The folders "A:\" until "Z:\").

Additional to the list of drives, detail information like the name and the drive type (network, harddisk, removable etc) is given.

The win32 api functions are used to access the Windows application programming interface. This means that the extension php_w32api.dll on PHP4 and php_ffi.dll on PHP5 have to be installed to use all functions. If no dll is available, the drives are guessed, but drive types and drive names can't be determined.

Prev | System_WinDrives | Next
System_WinDrives | PEAR Manual | Example


Example

Example

Example – How to use System_WinDrives

Using System_WinDrives

General usage

<?php
require_once 'System/WinDrives.php';

//if you want to read the names, pass "true" as first parameter
//this may crash your php.exe, so it's disabled by default
$wd = new System_WinDrives(false);

echo 'API available: ';
echo $wd->isApiAvailable() ? 'yes' : 'no';
echo "\r\n";

$arInfo = $wd->getDrivesInformation();
foreach ($arInfo as $strDrive => $objInfo) {
echo $strDrive . "\r\n";
echo '   Type: ' . $objInfo->type . "\r\n";
echo '   Type title: ' .  $objInfo->typetitle . "\r\n";
echo '   Name: ' . $objInfo->name . "\r\n";
?>

At first, you need to instantitiate a new System_WinDrives object. You can pass "true" as parameter to enable hard disk names, but that can crash PHP and is disabled by default.

The next thing to do is checking if the class can be used. That depends on the available extensions (win32api on PHP4, and php_ffi on PHP5). If the isApiAvailable method returns true, everything is ok.

Now that everything is ok, you can read the driver information via getDrivesInformation and display the output.

In case the API is not available, the method tries to guess the drive list by checking if the root directories exist.

Prev | System_WinDrives | Next
Introduction | PEAR Manual | Constants


Constants

Constants

Constants – Constants defined and used in System_WinDrives

All Constants

Constants defined in System/WinDrives.php
Name | Value | Description
SYSTEM_WINDRIVE_ERROR | 1 | Drive type couldn't be determined
SYSTEM_WINDRIVE_REMOVABLE | 2 | Removable (Floppy, ZIP)
SYSTEM_WINDRIVE_FIXED | 3 | Harddisk
SYSTEM_WINDRIVE_REMOTE | 4 | Network drive
SYSTEM_WINDRIVE_CDROM | 5 | CD/DVD drive
SYSTEM_WINDRIVE_RAMDISK | 6 | Virtual disk in the RAM
Prev | System_WinDrives | Next
Example | PEAR Manual | System_WinDrives()


System_WinDrives()

System_WinDrives()

System_WinDrives() – Outputs short description of the method

Synopsis

require_once 'System/WinDrives.php';

System_WinDrives System_WinDrives ( boolean $bReadName = false )

Description

Constructor. Creates a new System_WinDrives instance.

Parameter

boolean $bReadName

If the titles/names of drives shall be read. It is disabled by default, because it might cause PHP to crash.

See

setReadName()

Prev | System_WinDrives | Next
Constants | PEAR Manual | System_WinDrives::getDriveList()


System_WinDrives::getDriveList()

System_WinDrives::getDriveList()

System_WinDrives::getDriveList() – Gets array with path of all drives

Synopsis

require_once 'System/WinDrives.php';

array System_WinDrives::getDriveList ( void )

Description

Returns an array with all drive paths (e.g. A:\, C:\).

If no API is available, the drive list is guessed. To get more data (like drive type and name), you should use getDrivesInformation().

Return value

array - array with all the drives

Example

Using myFunction()

<?php
require_once 'System/WinDrives.php';

$swd = new System_WinDrives();
$arPaths = $swd->getDriveList();
foreach ($arPaths as $strPath) {
    echo $strPath . "\r\n";//echoes things like "A:\" and "C:\"
}
?>

Output:

A:\
C:\

See

isApiAvailable()

guessDriveList()

getDrivesInformation()

Prev | System_WinDrives | Next
System_WinDrives() | PEAR Manual | System_WinDrives::getDriveName()


System_WinDrives::getDriveName()

System_WinDrives::getDriveName()

System_WinDrives::getDriveName() – Returns the user-defined name for a drive

Synopsis

require_once 'System/WinDrives.php';

string System_WinDrives::getDriveName ( string $strDrive )

Description

Returns the user-given name for the given drive. The function does not work on PHP5 and returns an empty string ''.

Parameter

string $strDrive

The drive path, whose name shall be read.

Return value

string - The drive label

Example

Using myFunction()

<?php
require_once 'System/WinDrives.php';

$swd = new System_WinDrives();
echo $swd->getDriveName('C:\\');
?>

Output:

Windrive

Prev | System_WinDrives | Next
System_WinDrives::getDriveList() | PEAR Manual | System_WinDrives::getDrivesInformation()


System_WinDrives::getDrivesInformation()

System_WinDrives::getDrivesInformation()

System_WinDrives::getDrivesInformation() – Gets information about all drives

Synopsis

require_once 'System/WinDrives.php';

array System_WinDrives::getDrivesInformation ( void )

Description

Returns an array with all pieces of information one can get for the drives.

Return value

array - Array of little objects. Key is the drive path, the value is an object with the following values: type, name and typetitle.

Example

Using myFunction()

<?php
require_once 'System/WinDrives.php';

$swd = new System_WinDrives();
$arInfo = $swd->getDrivesInformation();
foreach ($arInfo as $strPath => $objInfo) {
    echo 'Drive ' . $strPath . "\r\n";
    echo '    type: ' . $objInfo->type . '(' . $objInfo->typetitle . ")\r\n";
    echo '    name: ' . $objInfo->name . "\r\n";
}
?>

Output:

Drive A:\
    2 (Removable)
    diskette
Drive C:\
    3 Harddisk
    Windisk

Prev | System_WinDrives | Next
System_WinDrives::getDriveName() | PEAR Manual | System_WinDrives::getDriveType()


System_WinDrives::getDriveType()

System_WinDrives::getDriveType()

System_WinDrives::getDriveType() – Gets the type of a drive

Synopsis

require_once 'System/WinDrives.php';

int System_WinDrives::getDriveType ( string $strDrive )

Description

Returns the type of a drive.

Return values
Value | Constant | Meaning
1 | SYSTEM_WINDRIVE_ERROR | Non-existent drive or other error
2 | SYSTEM_WINDRIVE_REMOVABLE | Removable drive (e.g. floppy)
3 | SYSTEM_WINDRIVE_FIXED | Harddisk
4 | SYSTEM_WINDRIVE_REMOTE | Network share
5 | SYSTEM_WINDRIVE_CDROM | CD-Rom or DVD
6 | SYSTEM_WINDRIVE_RAMDISK | RAM disk

Parameter

string $strDrive

The drive that type shall be returned.

Return value

integer - the type (use the constants for comparison)

See

getTypeTitle()

Prev | System_WinDrives | Next
System_WinDrives::getDrivesInformation() | PEAR Manual | System_WinDrives::getReadName()


System_WinDrives::getReadName()

System_WinDrives::getReadName()

System_WinDrives::getReadName() – Returns if drive names shall be read or not

Synopsis

require_once 'System/WinDrives.php';

boolean System_WinDrives::getReadName ( void )

Description

Returns of drive names should be read or not.

Return value

boolean - true if they shall be read, false if not.

See

setReadName()

Prev | System_WinDrives | Next
System_WinDrives::getDriveType() | PEAR Manual | System_WinDrives::getTypeTitle()


System_WinDrives::getTypeTitle()

System_WinDrives::getTypeTitle()

System_WinDrives::getTypeTitle() – Gets the readable name to a drive type

Synopsis

require_once 'System/WinDrives.php';

string System_WinDrives::getTypeTitle ( int $nType )

Description

Gets the readable name to a drive type, e.g. "Harddisk" for the type 3 (SYSTEM_WINDRIVE_FIXED).

Parameter

string $nType

The type whose name shall be returned

Return value

string - the name for the type

Prev | System_WinDrives | Next
System_WinDrives::getReadName() | PEAR Manual | System_WinDrives::guessDriveList()


System_WinDrives::guessDriveList()

System_WinDrives::guessDriveList()

System_WinDrives::guessDriveList() – Tries to guess the drive list

Synopsis

require_once 'System/WinDrives.php';

array System_WinDrives::guessDriveList ( void )

Description

Tries to guess the drive list by brute-force checking all letters.

Return value

array - Array with all found drive paths.

Prev | System_WinDrives | Next
System_WinDrives::getTypeTitle() | PEAR Manual | System_WinDrives::isApiAvailable()


System_WinDrives::isApiAvailable()

System_WinDrives::isApiAvailable()

System_WinDrives::isApiAvailable() – Checks if the API is available

Synopsis

require_once 'System/WinDrives.php';

boolean System_WinDrives::isApiAvailable ( void )

Description

Checks if the API methods to read the drive list are available, and returns that.

They may not be available if the necessary extensions (win32api on PHP4, php_ffi on PHP5) are not installed on the system.

If the API is not available, the drive list is brute-force guessed. Drive types are not available in that case.

Return value

boolean - true if they are there, false if not.

Prev | System_WinDrives | Next
System_WinDrives::guessDriveList() | PEAR Manual | System_WinDrives::setReadName()


System_WinDrives::setReadName()

System_WinDrives::setReadName()

System_WinDrives::setReadName() – Sets the readName setting

Synopsis

require_once 'System/WinDrives.php';

System_WinDrives::setReadName ( boolean $bReadName )

Description

Set, if drive names shall be read or not. Drive name reading may crash PHP, so this is disabled by default. You can enable label reading with this method.

Parameter

boolean $bReadName

If the names shall be read or not

Prev | System_WinDrives | Next
System_WinDrives::isApiAvailable() | PEAR Manual | Text


Text

Text

Packages for text manipulation and analysis.

Table of Contents
  • Text_CAPTCHA
  • Text_CAPTCHA_Numeral
  • Text_Figlet
  • Text_Highlighter
  • Text_LanguageDetect
  • Text_Password
  • Text_Statistics
  • Text_Wiki
Prev | PEAR Packages | Next
System_WinDrives::setReadName() | PEAR Manual | Text_CAPTCHA


Text_CAPTCHA

Text_CAPTCHA

Implementation of CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart).

Table of Contents
  • Introduction
  • Example
  • Information about the CAPTCHA and inner workings
Prev | Text | Next
Text | PEAR Manual | Introduction


Introduction

Introduction

This package provides the functionality to create CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart). Features include:

  • Creating graphical CAPTCHAs using GD2

  • Pluggable driver architecture using factory pattern

  • Generic information about the CAPTCHA

The package creates CAPTCHAs; due to the stateless nature of the HTTP protocol, the logic to secure a webpage using the package must be specifically implemented. See the usage example for detailled information.

Currently, the graphical CAPTCHA driver depends on Image_Text which in turn requires TTF support to be compiled into PHP.

Prev | Text_CAPTCHA | Next
Text_CAPTCHA | PEAR Manual | Example


Example

Example

The following example implements the standard use of a CAPTCHA: Submitted form data is only evaluated when a CAPTCHA has been solved correctly.

Creating a CAPTCHA

The following code creates a CAPTCHA, provides the relevant information for the package, anhd retrieves the CAPTCHA as a PNG image.

<?php
require_once 'Text/CAPTCHA.php';

// Set CAPTCHA options (font must exist!)
$imageOptions = array(
    'font_size'        => 24,
    'font_path'        => './',
    'font_file'        => 'COUR.TTF',
    'text_color'       => '#DDFF99',
    'lines_color'      => '#CCEEDD',
    'background_color' => '#555555'
);

// Set CAPTCHA options
$options = array(
    'width' => 200,
    'height' => 80,
    'output' => 'png',
    'imageOptions' => $imageOptions
);

// Generate a new Text_CAPTCHA object, Image driver
$c = Text_CAPTCHA::factory('Image');
$retval = $c->init($options);
if (PEAR::isError($retval)) {
    printf('Error initializing CAPTCHA: %s!',
        $retval->getMessage());
    exit;
}

// Get CAPTCHA secret passphrase
$_SESSION['phrase'] = $c->getPhrase();

// Get CAPTCHA image (as PNG)
$png = $c->getCAPTCHAAsPNG();
if (PEAR::isError($png)) {
    echo 'Error generating CAPTCHA!';
    echo $png->getMessage();
    exit;
}
file_put_contents(md5(session_id()) . '.png', $png);
?>

Securing a form with a CAPTCHA

The following code implements the functionality to check whether a CAPTCHA was solved correctly or not. for this, the CAPTCHA's phrase is stored in a session variable to retain this information between requests. It is important to unset the session after solving the CAPTCHA to avoid the reuse of the session ID.

<?php
session_start();
$ok = false;
$msg = 'Please enter the text in the image in the field below!';
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    if (isset($_POST['phrase']) && is_string($_POST['phrase']) && isset($_SESSION['phrase']) &&
        strlen($_POST['phrase']) > 0 && strlen($_SESSION['phrase']) > 0 &&
        $_POST['phrase'] == $_SESSION['phrase']) {
        $msg = 'OK!';
        $ok = true;
        unset($_SESSION['phrase']);
    } else {
        $msg = 'Please try again!';
    }
    unlink(md5(session_id()) . '.png');
}
print "<p>$msg</p>";

if (!$ok) {
    // create the CAPTCHA as seen above
    // and send it to the client
}
?>

See the file CAPTCHA_test.php in the package distribution for a full, working example (GD and TTF support required).

Prev | Text_CAPTCHA | Next
Introduction | PEAR Manual | Information about the CAPTCHA and inner workings


Information about the CAPTCHA and inner workings

Information about the CAPTCHA and inner workings

Text_CAPTCHA provides information about the CAPTCHA and makes its inner workings accessible using several functions defined in the base class; the specific implementation of them is up to the driver.

  • init() is used to initialize the CAPTCHA and provide further information, like Image_Text parameters.

  • _createCAPTCHA() generates the CAPTCHA, but is called internally by init().

    getPhrase() returns the CAPTCHA's phrase.

  • _createPhrase() creates a phrase for the CAPTCHA, but is used internally.

  • getCAPTCHA() returns the CAPTCHA, the format used depends on the driver implementation.

Prev | Text_CAPTCHA | Next
Example | PEAR Manual | Text_CAPTCHA_Numeral


Text_CAPTCHA_Numeral

Text_CAPTCHA_Numeral

Implementation of mathematic operation CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart).

Table of Contents
  • Introduction
  • Example
  • Information about the Text_CAPTCHA_Numeral and inner workings
Prev | Text | Next
Information about the CAPTCHA and inner workings | PEAR Manual | Introduction


Introduction

Introduction

This package provides the functionality to create Numeral CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart). Features include:

  • Creating numerical Captchas

  • Generic information about the Text_CAPTCHA_Numeral

The package creates numeral CAPTCHAs; due to the stateless nature of the HTTP protocol, the logic to secure a webpage using the package must be specifically implemented. See the usage example for detailled information.

Prev | Text_CAPTCHA_Numeral | Next
Text_CAPTCHA_Numeral | PEAR Manual | Example


Example

Example

The following example implements the standard use of a CAPTCHA: Submitted form data is only evaluated when a CAPTCHA has been solved correctly.

Creating a Numeral CAPTCHA

This example is just to show you how to generate a simple mathematic operation with Text_CAPTCHA_Numeral.

<?php
require_once 'Text/CAPTCHA/Numeral.php';
$num       = new Text_CAPTCHA_Numeral;
$operation = $num->getOperation();

/**
 * This will print the mathematical operation
 * that has been generated by the package.
 */
print $operation;
?>

Securing a form with a Numeral CAPTCHA

This example will show you how to secure a form using the numeral captcha. It generates an operation and stores its result into a session variable.

<?php
require_once 'Text/CAPTCHA/Numeral.php';
$numcap = new Text_CAPTCHA_Numeral;

if (isset($_POST['captcha']) && isset($_SESSION['answer'])) {
    if ($_POST['captcha'] == $_SESSION['answer']) {
        $errors[] = 'Ok... You might be human...';
    } else {
        $errors[] = 'You are dumb or not human';
    }
}
    if (!empty($errors)) {
        foreach ($errors as $error) {
            print "<h1><font color='red'>$error</font></h1><br />";
        }
    }

    print '
        <form name="capter" action="index.php?page=liveExample" method="post">
         <table>
          <tr>
           <th>What is this result pilgrim?: '.$numcap->getOperation().'</th>
           <td><input type="text" value="" name="captcha" /></td>
          </tr>
          <tr>
           <th/>
           <td><input type="submit" value="Let me prove you that I am human!" /></td>
          </tr>
        </form>
    ';
    $_SESSION['answer'] = $numcap->getAnswer();
?>
Prev | Text_CAPTCHA_Numeral | Next
Introduction | PEAR Manual | Information about the Text_CAPTCHA_Numeral and inner workings


Information about the Text_CAPTCHA_Numeral and inner workings

Information about the Text_CAPTCHA_Numeral and inner workings

Text_CAPTCHA_Numeral gives you the ability to generate numerical mathematical captchas.

  • getOperation() generates the operation that is going to be shown to the end user.

    getAnswer() Gets the answer of the generated operation's answer.

Prev | Text_CAPTCHA_Numeral | Next
Example | PEAR Manual | Text_Figlet


Text_Figlet

Text_Figlet

Render text using FIGlet fonts.

Table of Contents
  • "Hello, world!" written using a FIGlet font
  • Using the Text_Figlet class
Prev | Text | Next
Information about the Text_CAPTCHA_Numeral and inner workings | PEAR Manual | "Hello, world!" written using a FIGlet font


"Hello, world!" written using a FIGlet font

With Text_Figlet you can create ASCII-art like text using FIGlet font description files (FIGlet fonts). The package supports horizontal smushing, German symbols (e.g. äöü), RTL and LTR writing directions as well as incomplete and gzipped fonts (as long as php's zlib extension is installed).

"Hello, world!" written using a FIGlet font

.
   / / / /__  / / /___       _      ______  _____/ /___/ / /
  / /_/ / _ \/ / / __ \     | | /| / / __ \/ ___/ / __  / /
 / __  /  __/ / / /_/ /     | |/ |/ / /_/ / /  / / /_/ /_/
/_/ /_/\___/_/_/\____( )    |__/|__/\____/_/  /_/\__,_(_)
                     |/
Prev | Text_Figlet | Next
Text_Figlet | PEAR Manual | Using the Text_Figlet class


Using the Text_Figlet class

Using the Text_Figlet class

Text_Figlet has only two methods you can use: loadFont() to select a FIGlet font file that will be used later on, and lineEcho() that actually returns the passed text, rendered with the previously selected font.

loadFont() takes the name/path of the FIGlet font file (*.flf or *.flf.gz) as first parameter, and the option if German characters should also be loaded as second, optional parameter (defaults to true). The method either returns true if the font could be loaded, or a PEAR_Error in case of a problem.

lineEcho() can be called (multiple times if needed) after loading the font with loadFont(). The method takes the text that should be rendered using the font as first parameter, and an optional second parameter that determines if the text should be outputted in HTML text. In this case, special characters are escaped and everything is setup so that the text will look correctly. This parameter defaults to false. You should also wrap the line into <pre> tags, since they will monospace the text. Unlike the name implies, the rendered text is not echoed but returned.

Rendering "Hello, world!" using PHP

<?php
require_once 'Text/Figlet.php';

$figlet = new Text_Figlet();
$error  = $figlet->LoadFont('slant.flf');
if (PEAR::isError($error)) {
    echo 'Error: ' . $error->getMessage() . "\n";
} else {
    echo $figlet->LineEcho('Hello, world!') . "\n";
}
?>

The Text_Figlet package already ships some fonts. They are stored in its data directory which can be found calling pear config-get data_dir, and appending Text_Figlet/fonts/ to it. It will contain the following fonts:

  • 3-d.flf

  • alligator2.flf

  • bell.flf

  • block.flf

  • contessa.flf

  • cybermedium.flf

  • isometric1.flf

  • larry3d.flf

  • script.flf

  • slant.flf

Passing one of the font names to loadFont() will automatically look them up in the Text_Figlet font data directory if they are not found.

Prev | Text_Figlet | Next
"Hello, world!" written using a FIGlet font | PEAR Manual | Text_Highlighter


Text_Highlighter

Text_Highlighter

Provides functionality to perform syntax highlighting for different file formats.

Table of Contents
  • Introduction
  • Usage
  • Output Customization
Prev | Text | Next
Using the Text_Figlet class | PEAR Manual | Introduction


Introduction

Introduction

With Text_Highlighter it is possible to create syntax highlighted versions of different file formats.

Currently, the following formats are supported:

  • ABAP

  • C++

  • CSS

  • output of diff(1)

  • DTD

  • HTML

  • Java

  • Javascript

  • MySQL

  • Perl

  • PHP

  • Python

  • Ruby

  • sh

  • SQL

  • VBScript

  • XML

There are different options for getting the results of the highlighting, through the use of renderers. The list of renderers is as follows.

  • Array

  • Console

  • HTML - using span-tags containing a CSS class name, this is the default renderer

  • HTMLTags - using simple set of tags, only B, I and U, useful for devices that support only a subset of HTML (example is an iPod)

  • JSON

  • XML

Prev | Text_Highlighter | Next
Text_Highlighter | PEAR Manual | Usage


Usage

Usage

The class Text_Highlighter contains all necessary functionality to perform the syntax highlighting except for the actual highlighting rules for the different formats. These rules are defined in subclasses of Text_Highlighter, but one must not directly instantiate these subclasses. Instead the object-oriented factory pattern is used to create a highlighter object depending on the format:

Highlighting a SQL query

<?php
require_once "Text/Highlighter.php";

$hlSQL =& Text_Highlighter::factory("SQL");
echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
?>

This code generates a highlighted version of the SQL SELECT-query that is passed to Text_Highlighter::highlight in HTML. It is possible to customize the output to e.g. instead generate output suitable for usage on a console. This is described in the section Output Customization.

In order to produce syntax highlighting for other formats, one must replace the argument value SQL of Text_Highlighter::factory with one of ABAP, CPP, CSS, DIFF, DTD, HTML, JAVA, JAVASCRIPT, MYSQL, PERL, PHP, PYTHON, RUBY, SQL, or XML.

Prev | Text_Highlighter | Next
Introduction | PEAR Manual | Output Customization


Output Customization

Output Customization

The default behaviour of Text_Highlighter is to generate a syntax highlighted HTML version of the input.

It is possible to instead generate output that is suitable for being displayed on color-capable terminals such as xterm or through less(1) by telling Text_Highlighter to use another renderer:

Using the console renderer

<?php
require_once "Text/Highlighter.php";
require_once "Text/Highlighter/Renderer/Console.php";

$hlSQL =& Text_Highlighter::factory("SQL");
$hlSQL->setRenderer(new Text_Highlighter_Renderer_Console);
echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
?>

Also it is possible to further customize the output of both the HTML- and the console-renderer by passing an associative array of options to the constructor:

Options for the HTML renderer

<?php
require_once "Text/Highlighter.php";
require_once "Text/Highlighter/Renderer/Html.php";

$renderer = new Text_Highlighter_Renderer_Html(array("numbers" => HL_NUMBERS_LI, "tabsize" => 4));

$hlJava =& Text_Highlighter::factory("JAVA");
$hlJava->setRenderer($renderer);

echo $hlJava->highlight('class JavaProgram {
    public static void main(String args[]) {
        System.out.println("Hello World!");
    }
}');
?>

The above example configures a HTML renderer with two options: The first one tells it to number the lines in the output using the <ol /> HTML tag and the second one instructs the renderer to use a tab width of 4 spaces for indentation.

The following options are applicable:

Possible options for the renderer classes
Name | Description | Available in HTML renderer | Available in console renderer | Hints
numbers | Line numbering style | yes | yes | In the console renderer, this option takes just TRUE or FALSE in order to denote if line numbers should be displayed or not. The HTML rendered accepts three different values: HL_NUMBERS_LI instructs the class to number the lines using the <ol /> HTML tag, while HL_NUMBERS_TABLE uses a two-column table with the line numbers in the first and the source code in the second column. Setting the value to FALSE turns line numbering off in the HTML renderer.
tabsize | Tab width | yes | yes |
colors | Additional colors | no | yes | An associate array of additional colors for color-enabled consoles. The key of each array entry must be the name of the color and the corresponding value must be the escape sequence for it. (Example: \033[1;31mRed.)
Prev | Text_Highlighter | Next
Usage | PEAR Manual | Text_LanguageDetect


Text_LanguageDetect

Text_LanguageDetect

Detects the language of a given piece of text.

The package attempts to detect the language of a sample of text by correlating ranked 3-gram frequencies to a table of 3-gram frequencies of known languages.

It implements a version of a technique originally proposed by Cavnar & Trenkle (1994): "N-Gram-Based Text Categorization".

Table of Contents
  • Detecting the language
  • Example
Prev | Text | Next
Output Customization | PEAR Manual | Detecting the language


Detecting the language

Detecting the language

At first, you might want to get a list of supported languages. It can be retrieved by calling getLanguages() on a Text_LanguageDetect object. It returns an array of strings that represent the languages, e.g. array('albanian', 'arabic', 'azeri').

To actually detect the language of a piece of text, use the detect() method on the Text_LanguageDetect object. It takes the text as first parameter, and an optional $limit as second parameter, determining how many (likely) languages shall be returned at most. The method returns a sorted array with the languages as key, and their score as value. If no language is detected, an empty array is returned.

To get the most likely language only, use detectSimple() which directly returns the string of the language, or null if none was detected.

Note: To detect the language correctly, the length of the input text should be at least some sentences.
Prev | Text_LanguageDetect | Next
Text_LanguageDetect | PEAR Manual | Example


Example

Example

<?php
require_once 'Text/LanguageDetect.php';
$l = new Text_LanguageDetect();

echo "Supported languages:\n";
$langs = $l->getLanguages();
if (PEAR::isError($langs)) {
    die($langs->getMessage());
}
sort($langs);
echo implode(', ', $langs) . "\n\n";

$text = <<<EOD
Hallo! Das ist ein Text in deutscher Sprache.
Mal sehen, ob die Klasse erkennt, welche Sprache das hier ist.
EOD;

$result = $l->detect($text, 4);
if (PEAR::isError($result)) {
    echo $result->getMessage(), "\n";
} else {
    print_r($result);
}
?>

The above example would give the following output:

Supported languages:
albanian, arabic, azeri, bengali, bulgarian, cebuano, croatian,
czech, danish, dutch, english, estonian, farsi, finnish, french,
german, hausa, hawaiian, hindi, hungarian, icelandic, indonesian,
italian, kazakh, kyrgyz, latin, latvian, lithuanian, macedonian,
mongolian, nepali, norwegian, pashto, pidgin, polish, portuguese,
romanian, russian, serbian, slovak, slovene, somali, spanish,
swahili, swedish, tagalog, turkish, ukrainian, urdu, uzbek,
vietnamese, welsh

Array
(
    [german] => 0.407037037037
    [dutch] => 0.288065843621
    [english] => 0.283333333333
    [danish] => 0.234526748971
)
Prev | Text_LanguageDetect | Next
Detecting the language | PEAR Manual | Text_Password


Text_Password

Text_Password

Creating passwords with PHP.

Table of Contents
  • Introduction -- Introduction to Text_Password
  • Supported types of passwords -- This part of the documentation introduces the different supported types of passwords and gives examples for their usage.
Prev | Text | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Text_Password

Introduction

Generating passwords is a very common task in web applications. This package provides an easy-to-use and intuitive API to generate

  • pronounceable passwords

  • unpronounceable passwords

  • passwords based on a given string

For the last point, multiple, simple "obfuscation" algorithms are supported.

Setup

Requirements

Text_Password requires PHP 4.2.0 or better.

Installation

The Text_Password package can be installed using the PEAR installer command pear install Text_Password.

Alternative installation methods for situations where one has no access to the pear installer command can be found in the general installation chapter.

Uninstallation

Uninstalling the package can be done with pear uninstall Text_Password.

Prev | Text_Password | Next
Text_Password | PEAR Manual | Supported types of passwords


Supported types of passwords

Supported types of passwords

Supported types of passwords – This part of the documentation introduces the different supported types of passwords and gives examples for their usage.

Pronounceable passwords

One feature of the package is the ability to create passwords that are pronounceable using the static create() method. createMultiple() can be used to create several passwords at once.

Creating a pronounceable password:

<?php
require_once "Text/Password.php";

echo "Creating pronounceable password of 10 chars....: ";
echo Text_Password::create() . "\n\n";

echo "Creating 3 different pronounceable passwords...: ";
print_r(Text_Password::createMultiple(3));
?>

Unpronounceable passwords

In addition to pronounceable passwords Text_Password can also handle passwords that are not pronounceable.

Creating a unpronounceable password:

<?php
require_once "Text/Password.php";

echo "\nCreating unpronounceable password of 8 chars with a,b,c as possible chars....:\t";
echo Text_Password::create(8, 'unpronounceable', 'a,b,c') . "\n\n";

echo "\nCreating 4 different unpronounceable passwords...:\n";
print_r(Text_Password::createMultiple(4, 10, 'unpronounceable'));

echo "\nCreating unpronounceable password of 8 chars with numeric chars:\t";
echo Text_Password::create(8, 'unpronounceable', 'numeric') . "\n\n";

echo "\nCreating unpronounceable password of 8 chars with alphanumeric chars:\t";
echo Text_Password::create(8, 'unpronounceable', 'alphanumeric') . "\n\n";
?>

Passwords based on given strings

Text_Password provides the ability to create passwords that are based on a given string. In a lot of cases this string is a existing username for a authentication system.

Creating passwords based on a given string:

<?php
require_once "Text/Password.php";

echo "\nCreating password from login 'olivier', type is 'reverse':\t";
echo Text_Password::createFromLogin('olivier', 'reverse') . "\n\n";

echo "\nCreating password from login 'olivier', type is 'rot13':\t";
echo Text_Password::createFromLogin('olivier', 'rot13') . "\n\n";

echo "\nCreating password from login 'olivier', type is 'rotx':\t";
echo Text_Password::createFromLogin('olivier', 'rotx', 13) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'rotx++':\t";
echo Text_Password::createFromLogin('olivier', 'rotx++', 13) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'rotx--':\t";
echo Text_Password::createFromLogin('olivier', 'rotx--', 13) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'xor':\t";
echo Text_Password::createFromLogin('olivier', 'xor', 5) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'ascii_rotx':\t";
echo Text_Password::createFromLogin('olivier', 'ascii_rotx', 5) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'ascii_rotx++':\t";
echo Text_Password::createFromLogin('olivier', 'ascii_rotx++', 5) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'ascii_rotx--':\t";
echo Text_Password::createFromLogin('olivier', 'ascii_rotx--', 5) . "\n\n";

echo "\nCreating password from login 'olivier', type is 'shuffle':\t";
echo Text_Password::createFromLogin('olivier', 'shuffle', 1) . "\n\n";

echo "\nCreating password from an array of login 'olivier', 'martin', 'vanhoucke', 'jansen', type is 'reverse':\n";
$logins = array('olivier', 'martin', 'vanhoucke', 'jansen');
print_r(Text_Password::createMultipleFromLogin($logins, 'reverse'));
?>

Currently the following obfuscation algorithms are supported:

  • xor

  • rotx

  • rotx++

  • rotx--

  • ascii_rotx

  • ascii_rotx++

  • ascii_rotx--

  • shuffle

  • reverse

Prev | Text_Password | Next
Introduction | PEAR Manual | Text_Statistics


Text_Statistics

Text_Statistics

computation of readability scores for text documents.

Table of Contents
  • Introduction -- computation of readability scores for text documents.
Prev | Text | Next
Supported types of passwords | PEAR Manual | Introduction


Introduction

Introduction

Introduction – computation of readability scores for text documents.

Text_Statistics Description

Text_Statistics allows for computation of readability indexes for text documents.

Text_Statistics calculates some basic readability metrics on a block of text. The number of words, the number of sentences, and the number of total syllables is counted. These statistics can be used to calculate the Flesch score for a sentence, which is a number (usually between 0 and 100) that represents the readability of the text. A basic breakdown of scores is:

90 to 100 | 5th grade
80 to 90 | 6th grade
70 to 80 | 7th grade
60 to 70 | 8th and 9th grade
50 to 60 | 10th to 12th grade (high school)
30 to 50 | college
0 to 30 | college graduate

More info can be read up on WikiPedia article

Example Text_Statistics

<?php
  require 'Text/Statistics.php';
  $block = new Text_Statistics($sometext);
  $block->flesch; // returns flesch score for $sometext
?>

see the unit tests for additional examples.

Text_Word calculates the number of syllables in a word, based off of the number of contiguous vowel groupings in the word and applying matches to detect special cases.

Example numSyllables()

<?php
 require_once 'Text/Word.php'
 $word = new Text_Word('word');
 $word->numSyllables();  // returns 1
?>
Prev | Text_Statistics | Next
Text_Statistics | PEAR Manual | Text_Wiki


Text_Wiki

Text_Wiki

Abstracts parsing and rendering rules for Wiki markup in structured plain text

Table of Contents
  • Introduction -- Abstracts parsing and rendering rules for Wiki markup in structured plain text
Prev | Text | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Abstracts parsing and rendering rules for Wiki markup in structured plain text

Text_Wiki Description

The Text_Wiki package allows you to transform text structured using Wiki rules into any defined target output format, such as XHTML, RTF, LaTeX, and so on.

The full online documentation is available here

Prev | Text_Wiki | Next
Text_Wiki | PEAR Manual | Tools and Utilities


Tools and Utilities

Tools and Utilities

Table of Contents
  • MIME_Type
  • VersionControl_SVN
Prev | PEAR Packages | Next
Introduction | PEAR Manual | MIME_Type


MIME_Type

MIME_Type

Utility class for dealing with MIME types.

MIME_Type provides methods to detect the MIME (Multipurpose Internet Mail Extension) type of files, retrieving information about MIME types and parsing them.

Table of Contents
  • Detecting MIME types -- How to determine the MIME type of a file
  • Getting infos about a MIME type -- How to get more information about a MIME type
  • Editing MIME types -- How to change things
Prev | Tools and Utilities | Next
Tools and Utilities | PEAR Manual | Detecting MIME types


Detecting MIME types

Detecting MIME types

Detecting MIME types – How to determine the MIME type of a file

Detecting the MIME type of a file

The most simple way to detect the MIME type of any file is to use MIME_Type's static autoDetect() method. It will try to determine the file's type and return it as a string. If an error occurs, a PEAR_Error object is returned.

By default, only the plain MIME type will be returned, without any comments or parameters. If you pass true as second parameter to the method, all available MIME parameters will be appended to the returned type.

Detecting the MIME type of a file

<?php
require_once 'MIME/Type.php';

$filename = '/path/to/some/file.jpg';
echo MIME_Type::autoDetect($filename);
?>

The MIME type of the given file will be echoed.

Matching a MIME type

If you want to check if a certain MIME type matches a wildcard type, use the static wildcardMatch(). It takes the wildcard as first, and the type to be checked as second parameter. It returns true if the wildcard matches the MIME type, false if not.

Matching a wildcard type

<?php
require_once 'MIME/Type.php';

$filename = '/path/to/some/file.jpg';
$type     = MIME_Type::autoDetect($filename);

if (MIME_Type::wildcardMatch('image/*', $type)) {
    echo 'File ' . $filename . ' is an image.';
} else {
    echo 'File is no image.';
}
?>
Prev | MIME_Type | Next
MIME_Type | PEAR Manual | Getting infos about a MIME type


Getting infos about a MIME type

Getting infos about a MIME type

Getting infos about a MIME type – How to get more information about a MIME type

What a MIME type can be

Using MIME_Type you can get different data about a MIME type. All methods mentioned here can be called statically.

  • getMedia() returns the main part (media part, portion before the slash) of a MIME type. It would return image for image/png.

  • getSubType() returns the subtype of the given type. For image/png, it returns png.

  • isExperimental() checks if a given MIME type is experimental. It returns true or false (e.g. text/x-vcard).

  • isVendor() determines if the given type is a vendor specific MIME type (e.g. as in application/vnd.mozilla.xul+xml).

  • isWildcard() tells you if the passed type is a wildcard type (is either */* or something/*).

Prev | MIME_Type | Next
Detecting MIME types | PEAR Manual | Editing MIME types


Editing MIME types

Editing MIME types

Editing MIME types – How to change things

Editing a MIME type

With MIME_Type, you can edit existing MIME types or create new ones from scratch. Just create a new instance of MIME_Type - with the MIME type string as only parameter, if you have one - or no parameter if you want to begin a new one.

To set or retrieve the media type (part before the slash), use the object's $media property. The same applies to the subtype, the property name is $subType.

If you are done editing your MIME type, use get() to retrieve the MIME type's string representation.

Working with parameters

To retrieve parameters, use the $parameters property. It is an array consisting of MIME_Type_Parameter objects if there are any.

You can remove any parameter by calling removeParameter() and passing the parameter's name as only parameter.

Parameters are added with addParameter(). It takes the $name, $value and an optional $comment as parameters.

Again: If you are done editing the parameters, use get() to retrieve the MIME type's string representation.

There are three static methods that help you working with parameters:

  • hasParameters() checks if the passed MIME type string has any parameters in it.

  • getParameters() returns an array of MIME_Type_Parameter objects if there are any parameters in the passed type string.

  • stripParameters() removes all parameters and comments from the given type string.

Prev | MIME_Type | Next
Getting infos about a MIME type | PEAR Manual | VersionControl_SVN


VersionControl_SVN

VersionControl_SVN

VersionControl_SVN is a simple Object-Oriented interface for the svn command-line application that makes up the core of Subversion, a free/open-source version control system.

Table of Contents
  • Introduction
  • A Simple Example
  • One Factory To Rule Them All
  • Further Reading
Prev | Tools and Utilities | Next
Editing MIME types | PEAR Manual | Introduction


Introduction

Introduction

Subversion can be used to manage trees of source code, text files, image files -- just about any collection of files.

VersionControl_SVN's features include:

  • Full support of svn subcommands.

  • Flexible error reporting provided by PEAR_ErrorStack.

  • Multi-object factory design.

  • Fully documented source code

The power of a version control system like Subversion, when accessed through VersionControl_SVN, can be extended far beyond typical "source code" repositories.

For example, what content management system (CMS) couldn't benefit from version control functionality? For many non-programmers, version control is a confusing subject to get a firm grasp on. With VersionControl_SVN, developers are now able to customize the interface to Subversion with the ease-of-use goals of their particular audience in mind. VersionControl_SVN lets you leverage the strengths of version control without burdening end-users with the learning curve of change control fundamentals.

Prev | VersionControl_SVN | Next
VersionControl_SVN | PEAR Manual | A Simple Example


A Simple Example

A Simple Example

So you've got Subversion repository set up somewhere, and you want to take a look at what's inside with a PHP script. With the VersionControl_SVN::VersionControl_SVN_List() command, you're just a few steps away.

Reading the content of a Subversion repository

<?php
require_once 'VersionControl/SVN.php';

// Setup error handling -- always a good idea!
$svnstack = &PEAR_ErrorStack::singleton('VersionControl_SVN');

// Set up runtime options.
$options = array('fetchmode' => VERSIONCONTROL_SVN_FETCHMODE_ARRAY);
// Request list class from factory
$svn = VersionControl_SVN::factory('list', $options);

// Define any switches and aguments we may need
$switches = array('username' => 'user', 'password' => 'pass');
$args = array('svn://svn.example.com/repos/TestProject');

// Run command
if ($output = $svn->run($args, $switches)) {
    print_r($output);
} else {
    if (count($errs = $svnstack->getErrors())) {
        foreach ($errs as $err) {
            echo '<br />'.$err['message']."<br />\n";
            echo "Command used: " . $err['params']['cmd'];
        }
    }
}
?>

If your example repository above happened to have the VersionControl_SVN source in it, your output would be something like this:

<?php
Array
(
    [0] => Array
        (
            [name] => docs
            [type] => D
        )

    [1] => Array
        (
            [name] => package.xml
            [type] => F
        )

    [2] => Array
        (
            [name] => SVN.php
            [type] => F
        )

    [3] => Array
        (
            [name] => SVN
            [type] => D
        )

    [4] => Array
        (
            [name] => tests
            [type] => D
        )

)
?>

Note that in the above output, directories are flagged as type D, and files are flagged as type F.

Note: For additional information in the output, try setting verbose to TRUE in your $options array.
Prev | VersionControl_SVN | Next
Introduction | PEAR Manual | One Factory To Rule Them All


One Factory To Rule Them All

One Factory To Rule Them All

Have a script that needs to utilize several VersionControl_SVN subclasses? At the expense of a little overhead, you can be sure your $svn objects are fully-loaded by using the VersionControl_SVN::factory() command keyword __ALL__.

For example, in a basic script to get the list of current files in a repository, you just need the VersionControl_SVN::VersionControl_SVN_List() subclass.

Getting the list of current files in a repository

<?php
require_once 'VersionControl/SVN.php';

// Setup error handling -- always a good idea!
$svnstack = &PEAR_ErrorStack::singleton('VersionControl_SVN');

// Set up runtime options.
$options = array('fetchmode' => VERSIONCONTROL_SVN_FETCHMODE_ARRAY);

// Request list class from factory
$svn = VersionControl_SVN::factory('list', $options);

// Define any switches and aguments we may need
$switches = array('username' => 'user', 'password' => 'pass');
$args = array('svn://svn.example.com/repos/TestProject');

// Run command
if ($output = $svn->run($args, $switches)) {
    print_r($output);
} else {
    if (count($errs = $svnstack->getErrors())) {
        foreach ($errs as $err) {
            echo '<br />'.$err['message']."<br />\n";
            echo "Command used: " . $err['params']['cmd'];
        }
    }
}
?>

However, if you need to get a recursive list of files in a repository, look up the recent log activity for those files, and view the annotated source for those files, you've got two options.

Recursively getting the list of current files in a repository

<?php
require_once 'VersionControl/SVN.php';

// Setup error handling -- always a good idea!
$svnstack = &PEAR_ErrorStack::singleton('VersionControl_SVN');

// Set up runtime options.
$options = array('fetchmode' => VERSIONCONTROL_SVN_FETCHMODE_RAW);

// METHOD ONE: Lowest Overhead
// Create svn object with subcommands we need listed out individually
$svn = VersionControl_SVN::factory(array('list', 'log', 'blame'), $options);

// Define any switches and aguments we may need
$switches = array('username' => 'user', 'password' => 'pass');
$args = array('svn://svn.example.com/repos/TestProject');

print_r($svn->list->run($args, $switches));

// Pick files out of the above output, and see who did what
$args = array('svn://svn.example.com/repos/TestProject/trunk/index.php');

echo "<pre>" . $svn->blame->run($args) . "</pre>";

// METHOD TWO: Put all available commands at your disposal
// Load up all subcommands - higher overhead, but convenient for certain occasions
$svn = VersionControl_SVN::factory('__ALL__', $options);

// Now you may run whatever you need to ...
$svn->cat->run($args, $switches);
$svn->info->run($args, $switches);
// ... and so on.
?>
Prev | VersionControl_SVN | Next
A Simple Example | PEAR Manual | Further Reading


Further Reading

Further Reading

If you are interested in learning more about Subversion, see the following:

  • Version Control with Subversion - The primary reference manual for all things related to Subversion, from general use to repository administration.

  • Subversion Website - The official Subversion website offers a FAQ, mailing list, and of course, the Subversion source code. Also included are links to GUI Subversion applications.

Prev | VersionControl_SVN | Next
One Factory To Rule Them All | PEAR Manual | Validate


Validate

Validate

Validate offers a set of packages to validate common or specific data. The main package validates the common data. Specific data are localised or thematic.

Localized validation class

  • Argentina: Validate_AR

  • Austria: Validate_AT

  • Australia : Validate_AU

  • Belgium: Validate_BE

  • Brasil: Validate_PTBR

  • Canada: Validate_CA

  • Denmark: Validate_DK

  • Finland: Validate_FI

  • France: Validate_FR

  • Germany: Validate_DE

  • Iceland: Validate_IS

  • Ireland: Validate_IE

  • Netherlands: Validate_NL

  • New Zealand: Validate_NZ

  • Poland: Validate_PL

  • Republic of India: Validate_IN

  • South Africa: Validate_ZA

  • Spain: Validate_ES

  • Switzerland: Validate_CH

  • United Kingdom: Validate_UK

  • United States: Validate_US

Thematic validation class

  • Financial: Validate_Finance

  • Credit Cards: Validate_Finance_CreditCard

  • International Standard Product Numbers : Validate_ISPN

Table of Contents
  • Validate (main package)
  • Validate features
  • Validate_AR
  • Validate_AT
  • Validate_AU
  • Validate_BE
  • Validate_CA
  • Validate_CH
  • Validate_DE
  • Validate_DK
  • Validate_ES
  • Validate_esMX
  • Validate_FI
  • Validate_FR
  • Validate_IE
  • Validate_IN
  • Validate_IS
  • Validate_NL
  • Validate_NZ
  • Validate_PL
  • Validate_ptBR
  • Validate_UK
  • Validate_US
  • Validate_ZA
  • Validate_Finance
  • Validate_Finance_CreditCard
  • Validate_ISPN
Prev | PEAR Packages | Next
Further Reading | PEAR Manual | Validate (main package)


Validate (main package)

Validate (main package)

The main package provides methods to validate various data. It includes :

  • numbers (min/max, decimal or not)

  • email (syntax, domain check)

  • string (predifined type alpha upper and/or lowercase, numeric,...)

  • date (date, options) - Options can be format (Format of the date (%d-%m-%Y) or rfc822_compliant), min (The date has to be greater than this array ($day, $month, $year) or PEAR::Date object), max (The date hast to be smaller than this array ($day, $month, $year) or PEAR::Date object)

  • uri (RFC2396)

  • possibility valid multiple data with a single method call (::multiple)

See also :

  • the api documentation

  • The page on pear.php.net

Table of Contents
  • Introduction -- Introduction to Validate
  • Email address validation -- Validation for email addresses.
  • Number validation -- Validation for numbers.
  • String validation -- Validation for strings.
Prev | Validate | Next
Validate | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Validate

Overview

With this package, one can easily validate various data. It includes numbers, email, string, date, URI and posibility valid multiple data with a single method call.

Some of above mentioned features have corresponding RFCs, in case, Validate conforms to those RFCs. For example email validation mostly covers RFC 822 or URI conforms to RFC 2396.

A few examples

Validating an email address

<?php
require_once 'Validate.php';

if (!Validate::email('johndoe@example.net')) {
    echo 'Invalid Email address';
} else {
    echo 'Its Valid!';
}
?>

Validating dates

In this example, date would first checked against desired format, and then get checked to see if it's not before "15 February 1986" or after "23 August 2008".

<?php
require_once 'Validate.php';

var_dump(
    Validate::date(
        '121202',
        array(
            'format' => '%d%m%y',
            'min' => array('15', '02', '1986'),
            'max' => array('23', '08', '2008')
        )
    )
);
?>
Prev | Validate (main package) | Next
Validate (main package) | PEAR Manual | Email address validation


Email address validation

Email address validation

Email address validation – Validation for email addresses.

Introduction to Email Address validation

This method validate email addresses against both the general format and the one described in RFC 822.

This method takes two arguments:

  • An email address.

  • An array of options (optional).

Various option are:

  • check_domain (boolean) - Check or not if the domain exists.

  • use_rfc822 (boolean) - Apply the full RFC822 grammar.

  • fullTLDValidation (boolean) - All top-level domains.

  • VALIDATE_GTLD_EMAILS (boolean) - Only generic top-level domains.

  • VALIDATE_CCTLD_EMAILS (boolean) - Only country code top-level domains.

  • VALIDATE_ITLD_EMAILS (boolean) - Only international top-level domains.

How to use Email Validation

Email Validation

The following example assumes that one wants to use RFC822 strict mode to validate email addresses.

<?php
require_once 'Validate.php';

$email = '"Doe, John" <johndoe@example.net>';
if (Validate::email($email, array('use_rfc822' => true))) {
    echo 'Valid!';
} else {
    echo $email . ' failed.';
}
?>

And the following one assumes that one wants to check if the domain exists.

<?php
require_once 'Validate.php';

$email = 'info@example.com';
if (Validate::email($email, array('check_domain' => 'true'))) {
    echo $email . ' is valid and domain exists';
}
?>
Prev | Validate (main package) | Next
Introduction | PEAR Manual | Number validation


Number validation

Number validation

Number validation – Validation for numbers.

Introduction to Number validation

This method validates numbers. Decimal or not, max and min.

This method takes two arguments:

  • A number.

  • An array of options (optional).

Various option are:

  • decimal (mixed) - Decimal chars or false when decimal not allowed. For example ",." to allow both "." and ",".

  • dec_prec (int) - Number of allowed decimals.

  • min (float) - Minimum value.

  • max (float) - Maximum value.

How to use Number Validation

Number Validation

The following example assumes that one wants to validate a number when decimals are allowed and decimal character is ".", and number of allowed decimals is 4.

<?php
require_once 'Validate.php';

if (Validate::number(8.0004, array('decimal' => '.', 'dec_prec' => 4))) {
    echo 'Valid number';
}
?>

And the following one assumes that one wants to validate a decimal number with decimal character "," or "." while it's less than "-7" and greater than "-9".

<?php
require_once 'Validate.php';

$number = '-8,1';
if (Validate::number($number,
    array('decimal' => '.,', 'min' => -9, 'max' => -7 ))) {
    echo 'Valid';
} else {
    echo 'Invalid';
}
?>
Prev | Validate (main package) | Next
Email address validation | PEAR Manual | String validation


String validation

String validation

String validation – Validation for strings.

Introduction to String validation

This method validates string using the given format.

This method takes two arguments:

  • String.

  • An array of options.

Various option are:

  • format (mixed) - Format of the string

    • VALIDATE_NUM - Number (0-9).

    • VALIDATE_SPACE - Space (\s).

    • VALIDATE_ALPHA_LOWER - Lower case alphabets (a-z).

    • VALIDATE_ALPHA_UPPER - Upper case alphabets (A-Z).

    • VALIDATE_ALPHA - Alphabets (a-Z).

    • VALIDATE_EALPHA_LOWER - Lower case letters with an accent (French, ...), umlauts (German), special characters (e.g. Skandinavian) and VALIDATE_ALPHA_LOWER.

    • VALIDATE_EALPHA_UPPER - Upper case letters with an accent (French, ...), umlauts (German), special characters (e.g. Skandinavian) and VALIDATE_ALPHA_UPPER.

    • VALIDATE_EALPHA - Letters with an accent (French, ...), umlauts (German), special characters (e.g. Skandinavian) and VALIDATE_ALPHA.

    • VALIDATE_PUNCTUATION - Punctuation .,;:&"?!', "(" and ")".

    • VALIDATE_NAME - VALIDATE_EALPHA, VALIDATE_SPACE, "'" and "-".

    • VALIDATE_STREET - VALIDATE_NUM and VALIDATE_NAME, "\./", "º" and "ª".

  • min_length (int) - Minimum length.

  • max_length (int) - Maximum length.

How to use String Validation

String Validation

The following example assumes that one wants to validate a string when only uppercase alphabets, numbers and space are allowed

<?php
require_once 'Validate.php';

if (Validate::string("1984 GEORGE ORWELL", array(
    'format' => VALIDATE_NUM . VALIDATE_SPACE . VALIDATE_ALPHA_UPPER))) {
    echo 'Valid!';
} else {
    echo 'Invalid!';
}
?>
Prev | Validate (main package) | Next
Number validation | PEAR Manual | Validate features


Validate features

Validate features

control per country

Country

Package

PostCode

SIN

Car registration

SSN

Phone

Region

bankCode

Others

Argentina

AR

Yes

Yes

Austria

AT

Yes

Yes

Australia

AU

Yes

Yes

  1. Tax file Number

  2. Australian Business Number

  3. Australian Company Number

Belgium

BE

Yes

Yes

Yes

Yes

  1. Account number

  2. TransfertMessage

Brasil

PTBR

Yes

Yes

Yes

Yes

Yes

  1. CNPJ

  2. CPF

Canada

CA

Yes

Yes

n

y

y

n

Denmark

DK

Yes

Yes

Yes

Yes

France

FR

Yes

Yes

Departements

RIB

  1. Siret

  2. Siren

Germany

DE

Yes

Yes

Iceland

IS

Yes

Yes

Yes

address

Mexico

esMX

Yes

Yes (DNI)

Yes

Yes

Netherlands

NL

Yes

Yes

Yes

Account Number

New Zealand

NZ

Yes

Yes

Region number

Account Number

IRD Number

Poland

PL

Account number

  1. NIP

  2. Pesel

  3. Regon

Republic of India

IN

Yes

Yes

Yes

State and union territory

Pan and TAN

South Africa

ZA

Yes

Yes

Yes

Spain

ES

Yes (DNI)

Switzerland

CH

Yes

Yes

  1. Swiss university's immatriculation number

United Kingdom

UK

Yes

Yes

Yes

Yes

Account Number

  1. Sort code

  2. driver licence

  3. passport

United States

US

Yes

Yes

Yes

Yes

Prev | Validate | Next
String validation | PEAR Manual | Validate_AR


Validate_AR

Validate_AR

Caution

This package is in alpha state

Package contains locale validation for Argentina such as:

  1. Postal code CPA (Código Postal Argentino)

  2. Regions - provinces of Argentina

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate features | PEAR Manual | Validate_AT


Validate_AT

Validate_AT

Caution

This package is in alpha state

Package contains locale validation for Austria such as:

  1. SSN

  2. Postal Code

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_AR | PEAR Manual | Validate_AU


Validate_AU

Validate_AU

Caution

This package is in alpha state

Package contains locale validation for Australia such as:

  1. Tax File Number

  2. Postal Code

  3. Phone Number

  4. Australian Business Number

  5. Australian Company Number

  6. Regions (States)

See also :

  • The API documentation

  • The page on pear.php.net

Table of Contents
  • Introduction -- introduction to Validate_AU
  • List of available validations -- available validation in Validate_AU
  • Package Validate_AU Constants -- Constants defined in and used by Validate_AU
  • Validate_AU::abn -- Australian Business Number (ABN).
  • Validate_AU::acn -- Validate an Australian Company Number (ACN)
  • Validate_AU::phoneNumber -- Validate a telephone number.
  • Validate_AU::postalCode -- Validate Austrialian postal codes.
  • Validate_AU::region -- Validates Australian Regional Codes
  • Validate_AU::ssn -- Social Security Number.
  • Validate_AU::tfn -- Tax File Number (TFN)
Prev | Validate | Next
Validate_AT | PEAR Manual | Introduction


Introduction

Introduction

Introduction – introduction to Validate_AU

Description

The package offers some methods to validate specific data for Australia

Usage

General usage

Every module of Validate follows the same philosophy. Propose some validation method which returns a boolean result. Some methods have some optional parameters to set stronger checks.

sample

<?php

// Include the package
require_once 'Validate/AU.php';
?>
Prev | Validate_AU | Next
Validate_AU | PEAR Manual | List of available validations


List of available validations

List of available validations

List of available validations – available validation in Validate_AU

Validate a Australian TFN / SSN

Most Australian's will have a TFN (Tax File Number) however not all, it is the closet equivalent we have to a Social Security Number. Note that this validation routine can be accessed through both Validate_AU::tfn() and Valdiate::ssn() methods.

sample

<?php

// Include the package
require_once('Validate/AU.php');

$badTFN = '23 456 782';
$result = Validate_AU::tfn($badTFN);
echo 'Test ' . $badTFN .' : <br />';
var_export($result);

echo '<br /><br />';
$goodTFN = '123 456 782';
$result = Validate_AU::tfn($goodTFN);
echo 'Test ' . $goodNationalId .' : <br />';
var_export($result);
?>

Output :

Test 23 456 782 :
false

Test 123 456 782 :
true

Validate a Australian postcode

Australian post code are 4 digit formed.

First parameter is the post code to validate.

An optional parameter for activate strong checks using a list of postcodes.

sample

<?php

// Include the package
require_once('Validate/AU.php');

$badPostCode = 'ABCD';
$result = Validate_AU::postalCode($badPostCode);
echo 'Test ' . $badPostCode .' : <br />';
var_export($result);

echo '<br /><br />';
$goodPostCode = '3000';
$result = Validate_AU::postalCode($goodPostCode);
echo 'Test ' . $goodPostCode .' : <br />';
var_export($result);
?>

Output :

Test ABCD :
false

Test 3000 :
true

sample using strong parameter

1234 appears to be a valid 4 digit postcode, however it does not appear in the official list.

<?php

// Include the package
require_once('Validate/AU.php');

$badPostCode = '1234';
$goodPostCode = '7930';

$result = Validate_AU::postalCode($badPostCode);
echo 'Test ' . $badPostCode .' : <br />';
var_export($result);

$result = Validate_AU::postalCode($badPostCode, false);
echo '<br /><br />Test ' . $badPostCode .' : <br />';
var_export($result);

$result = Validate_AU::postalCode($badPostCode, true);
echo '<br /><br />Test ' . $badPostCode .' : <br />';
var_export($result);

$result = Validate_AU::postalCode($goodPostCode, true);
echo '<br /><br />Test ' . $goodPostCode .' : <br />';
var_export($result);
?>

Output :

Test 1234 :
true

Test 1234 :
true

Test 1234 :
false

Test 7930 :
true

Validate an ABN

Validate an Australian Business Number.

sample

<?php

// Include the package
require_once('Validate/AU.php');

$badABN = '00 043 145 470';
$result = Validate_AU::abn($badABN);
echo 'Test ' . $badRegion .' : <br />';
var_export($result);

echo '<br /><br />';
$goodABN = '28 043 145 470';
$result = Validate_AU::abn($goodABN);
echo 'Test ' . $goodRegion .' : <br />';
var_export($result);
?>

Output :

Test 00 043 145 470 :
false

Test 28 043 145 470 :
true

Validate a Region / State

Validates a 2/3 region (state) code.

sample

<?php

// Include the package
require_once('Validate/AU.php');

$badRegion = 'asdf';
$result = Validate_AU::region($badVAT);
echo 'Test ' . $badRegion .' : <br />';
var_export($result);

echo '<br /><br />';
$goodRegion = 'VIC';
$result = Validate_AU::region($goodRegion);
echo 'Test ' . $goodRegion .' : <br />';
var_export($result);
?>

Output :

Test asdf :
false

Test VIC :
true

Validate a phonenumber

Validate an Australian phone number passed as first param. Second parameter can be used to specify flags that signify the type of number to be validated.

Flags can be any combination of the bitwise constants VALIDATE_AU_PHONENUMBER_* as follows:

Validate_AU Phone Number Flags
Flag | Description
"VALIDATE_AU_PHONENUMBER_STRICT" | If supplied then no spaces, parenthesis or dashes (-) will be removed.
"VALIDATE_AU_PHONENUMBER_NATIONAL" | If supplied, then valid national numbers, both landline and mobile will pass validation.
"VALIDATE_AU_PHONENUMBER_INDIAL" | If supplied, then valid indial (13/1300/1800/1900) numbers will pass validation.
"VALIDATE_AU_PHONENUMBER_INTERNATIONAL" | If supplied, then valid international syntax will pass validation. EG. +61.3 9999 9999

sample

<?php

// Include the package
require_once('Validate/AU.php');

$nationalPhone       = '03 9999 9999';
$nationalStrictPhone = '0399999999';
$indialPhone         = '1300 131 121';
$internationalSyntax = '+61.3 8779 7212';

echo 'Test ' . $goodPhone .' : <br />';
$result = Validate_AU::phoneNumber($nationalPhone); // the flag VALIDATE_AU_PHONENUMBER_NATIONAL is default
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalPhone, VALIDATE_AU_PHONENUMBER_NATIONAL | VALIDATE_AU_PHONENUMBER_STRICT);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalPhone, VALIDATE_AU_PHONENUMBER_INDIAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalPhone, VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalPhone, VALIDATE_AU_PHONENUMBER_NATIONAL | VALIDATE_AU_PHONENUMBER_INDIAL | VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result);

echo '<br /><br />';
echo 'Test ' . $nationalStrictPhone .' : <br />';
$result = Validate_AU::phoneNumber($nationalStrictPhone);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalStrictPhone, VALIDATE_AU_PHONENUMBER_NATIONAL | VALIDATE_AU_PHONENUMBER_STRICT);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalStrictPhone, VALIDATE_AU_PHONENUMBER_INDIAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalStrictPhone, VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($nationalStrictPhone, VALIDATE_AU_PHONENUMBER_NATIONAL | VALIDATE_AU_PHONENUMBER_INDIAL | VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';

echo '<br /><br />';
echo 'Test ' . $indialPhone .' : <br />';
$result = Validate_AU::phoneNumber($indialPhone);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($indialPhone, VALIDATE_AU_PHONENUMBER_INDIAL | VALIDATE_AU_PHONENUMBER_STRICT);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($indialPhone, VALIDATE_AU_PHONENUMBER_INDIAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($indialPhone, VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($indialPhone, VALIDATE_AU_PHONENUMBER_NATIONAL | VALIDATE_AU_PHONENUMBER_INDIAL | VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';
echo '<br /><br />';

echo 'Test ' . $internationalSyntax .' : <br />';
$result = Validate_AU::phoneNumber($internationalSyntax);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($internationalSyntax, VALIDATE_AU_PHONENUMBER_INTERNATIONAL | VALIDATE_AU_PHONENUMBER_STRICT);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($internationalSyntax, VALIDATE_AU_PHONENUMBER_INDIAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($internationalSyntax, VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';
$result = Validate_AU::phoneNumber($internationalSyntax, VALIDATE_AU_PHONENUMBER_NATIONAL | VALIDATE_AU_PHONENUMBER_INDIAL | VALIDATE_AU_PHONENUMBER_INTERNATIONAL);
var_export($result) . '-';

?>

Output :

Test 03 9999 9999 :
true - false - false - false - true

Test 0399999999 :
true - true - false - false - true

Test 1300 131 121 :
false - false - true - false - true

Test +61.3 8779 7212 :
false - false - true - true - true

Prev | Validate_AU | Next
Introduction | PEAR Manual | Package Validate_AU Constants


Package Validate_AU Constants

Package Validate_AU Constants

Package Validate_AU Constants – Constants defined in and used by Validate_AU

All Constants

Constants defined in Validate_AU.php

Constants defined in Validate_AU.php
Name | Value | Line Number
VALIDATE_AU_PHONENUMBER_INDIAL | 4 | 37
VALIDATE_AU_PHONENUMBER_INTERNATIONAL | 8 | 38
VALIDATE_AU_PHONENUMBER_NATIONAL | 2 | 36
VALIDATE_AU_PHONENUMBER_STRICT | 1 | 35
Prev | Validate_AU | Next
List of available validations | PEAR Manual | Validate_AU::abn


Validate_AU::abn

Validate_AU::abn

Validate_AU::abn() – Australian Business Number (ABN).

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::abn ( string $abn )

Description

Validates an ABN using a modulus calculation

Parameter

string $abn

ABN to validate

Return value

returns Returns true on success, otherwise false

Throws

throws no exceptions thrown

author

author Byron Adams <byron.adams54@gmail.com>

See

see http://www.ato.gov.au/businesses/content.asp?doc=/content/13187.htm

Note

This function can not be called statically.

Prev | Validate_AU | Next
Package Validate_AU Constants | PEAR Manual | Validate_AU::acn


Validate_AU::acn

Validate_AU::acn

Validate_AU::acn() – Validate an Australian Company Number (ACN)

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::acn ( string $acn )

Description

The ACN is a nine digit number with the last digit being a check digit calculated using a modified modulus 10 calculation.

Parameter

string $acn

ACN number to validate

Return value

returns Returns true on success, false otherwise

Throws

throws no exceptions thrown

author

author Byron Adams <byron.adams54@gmail.com>

author Daniel O'Connor <daniel.oconnor@gmail.com>

See

see http://www.asic.gov.au/asic/asic_infoco.nsf/byheadline/Australian+Company+Number+(ACN)+Check+Digit

Note

This function can not be called statically.

Prev | Validate_AU | Next
Validate_AU::abn | PEAR Manual | Validate_AU::phoneNumber


Validate_AU::phoneNumber

Validate_AU::phoneNumber

Validate_AU::phoneNumber() – Validate a telephone number.

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::phoneNumber ( string $number , int $flags = VALIDATE_AU_PHONENUMBER_NATIONAL )

Description

Note that this function supports the following notations:

  • Landline: 03 9999 9999

  • Mobile: 0400 000 000 (as above, but usually notated differently)

  • Indial: 131 812 / 1300 000 000 / 1800 000 000 / 1900 000 000

  • International: +61.3 9999 9999

For International numbers, only +61 will be valid, as this is Australia's dial code, and the format MUST be +61.3, where 3 represents the state dial code, in this case, Victoria.

Note: If the VALIDATE_AU_PHONENUMBER_STRICT flag is not supplied, then all spaces, dashes and parenthesis are removed before validation. You will have to strip these yourself if your data storage does not allow these characters.

Parameter

string $number

The telephone number

integer $flags

Can be a combination of the following flags:

  • VALIDATE_AU_PHONENUMBER_STRICT: if supplied then no spaces, parenthesis or dashes (-) will be removed.

  • VALIDATE_AU_PHONENUMBER_NATIONAL: when supplied valid national numbers (eg. 03 9999 9999) will return TRUE.

  • VALIDATE_AU_PHONENUMBER_INDIAL: when supplied valid indial numbers (eg. 13/1300/1800/1900) will return TRUE.

  • VALIDATE_AU_PHONENUMBER_INTERNATIONAL: when supplied valid international notation of Australian numbers (eg. +61.3 9999 9999) will return TRUE.

ToDo

todo Check that $flags contains a valid flag.

Throws

throws no exceptions thrown

author

author Alex Hayes <ahayes@wcg.net.au>

author Daniel O'Connor <daniel.oconnor@gmail.com>

Note

This function can not be called statically.

Prev | Validate_AU | Next
Validate_AU::acn | PEAR Manual | Validate_AU::postalCode


Validate_AU::postalCode

Validate_AU::postalCode

Validate_AU::postalCode() – Validate Austrialian postal codes.

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::postalCode ( string $postcode , bool $strong = false )

Description

This package is not documented yet.

Parameter

string $postcode

postcode to validate

boolean $strong

strong checks against a list of postcodes

Return value

returns true if postcode is ok, false otherwise

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | Validate_AU | Next
Validate_AU::phoneNumber | PEAR Manual | Validate_AU::region


Validate_AU::region

Validate_AU::region

Validate_AU::region() – Validates Australian Regional Codes

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::region ( string $region )

Description

This package is not documented yet.

Parameter

string $region

region code to validate

Return value

returns returns true on success, false otherwise

Throws

throws no exceptions thrown

See

see http://www.google.com/apis/adwords/developer/adwords_api_regions.html#Australia

author

author Byron Adams <byron.adams54@gmail.com>

Note

This function can not be called statically.

Prev | Validate_AU | Next
Validate_AU::postalCode | PEAR Manual | Validate_AU::ssn


Validate_AU::ssn

Validate_AU::ssn

Validate_AU::ssn() – Social Security Number.

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::ssn ( string $ssn )

Description

Australia does not have a social security number system, the closest equivalent is a Tax File Number

Parameter

string $ssn

ssn number to validate

Return value

returns Returns true on success, false otherwise

Throws

throws no exceptions thrown

See

see Validate_AU::tfn()

Note

This function can not be called statically.

Prev | Validate_AU | Next
Validate_AU::region | PEAR Manual | Validate_AU::tfn


Validate_AU::tfn

Validate_AU::tfn

Validate_AU::tfn() – Tax File Number (TFN)

Synopsis

require_once '/Validate/AU.php';

bool Validate_AU::tfn ( string $tfn )

Description

Australia does not have a social security number system, the closest equivalent is a Tax File Number.

Parameter

string $tfn

Tax File Number

Return value

returns Returns true on success, false otherwise

Throws

throws no exceptions thrown

author

author Byron Adams <byron.adams54@gmail.com>

See

see http://en.wikipedia.org/wiki/Tax_File_Number

Note

This function can not be called statically.

Prev | Validate_AU | Next
Validate_AU::ssn | PEAR Manual | Validate_BE


Validate_BE

Validate_BE

Caution

This package is in beta state

This package offers methods to validate specific values from Belgium

See also :

  • The API documentation

  • The page on pear.php.net

Table of Contents
  • Introduction -- Introduction to validate_BE
  • List of aivailable validations -- aivailable validation in validate_be
Prev | Validate | Next
Validate_AU::tfn | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to validate_BE

Description

The package offers some methods to validate specific data for Belgium

Usage

General usage

Every module of Validate follows the same philosophy. Propose some validation method retuning boolean result. Some methods have some optional parameters to set a stronger check.

sample

<?php

// Include the package
require_once 'Validate/BE.php';
?>
Prev | Validate_BE | Next
Validate_BE | PEAR Manual | List of aivailable validations


List of aivailable validations

List of aivailable validations

List of aivailable validations – aivailable validation in validate_be

Validate a Belgian nationalId

The belgian nationalId on the identity card of all belgian.

A check digit is the last one, computed the standard _get_control_number function.

sample

<?php

// Include the package
require_once('Validate/BE.php');

$badNationalId = '730111-361-99';
$result = Validate_BE::nationalId($badNationalId);
echo 'Test ' . $badNationalId .' : <br />';
var_export($result);

echo '<br /><br />';
$goodNationalId = '730111 361 73';
$result = Validate_BE::nationalId($goodNationalId);
echo 'Test ' . $goodNationalId .' : <br />';
var_export($result);
?>

Output :

Test 730111-361-99 :
false

Test 730111 361 73 :
true

Validate a Belgian social security number

The belgian social security number is on the SIS card of all belgian.

A check digit is the last one, computed the standard _get_control_number function.

sample

<?php

// Include the package
require_once('Validate/BE.php');

$badSsn = '72011136173';
$result = Validate_BE::ssn($badSsn);
echo 'Test ' . $badSsn .' : <br />';
var_export($result);

echo '<br /><br />';
$goodSsn = '73011136173';
$result = Validate_BE::ssn($goodSsn);
echo 'Test ' . $goodSsn .' : <br />';
var_export($result);
?>

Output :

Test 72011136173 :
false

Test 73011136173 :
true

Validate a Belgian postcode

Belgian post code are 4 digit formed.

First parameter is the post code to validate.

An optional parameter for activate strong checks using a list of postcodes.

sample

<?php

// Include the package
require_once('Validate/BE.php');

$badPostCode = 'ABCD';
$result = Validate_BE::postalCode($badPostCode);
echo 'Test ' . $badPostCode .' : <br />';
var_export($result);

echo '<br /><br />';
$goodPostCode = '7930';
$result = Validate_BE::postalCode($goodPostCode);
echo 'Test ' . $goodPostCode .' : <br />';
var_export($result);
?>

Output :

Test ABCD :
false

Test 7930 :
true

sample using strong parameter

1234 like a good post code, but don't exit in the official list.

<?php

// Include the package
require_once('Validate/BE.php');

$badPostCode = '1234';
$goodPostCode = '7930';

$result = Validate_BE::postalCode($badPostCode);
echo 'Test ' . $badPostCode .' : <br />';
var_export($result);

$result = Validate_BE::postalCode($badPostCode,false);
echo '<br /><br />Test ' . $badPostCode .' : <br />';
var_export($result);

$result = Validate_BE::postalCode($badPostCode,true);
echo '<br /><br />Test ' . $badPostCode .' : <br />';
var_export($result);

$result = Validate_BE::postalCode($goodPostCode);
echo '<br /><br />Test ' . $goodPostCode .' : <br />';
var_export($result);
?>

Output :

Test 1234 :
true

Test 1234 :
true

Test 1234 :
false

Test 7930 :
true

Validate a Belgian bank account number

Belgian bankcodes consist of

  • 3 figure number for the bank society

  • 7-figure number for the account number

  • 2-figure number for mod 97

sample

<?php

// Include the package
require_once('Validate/BE.php');
$badBankCode = '310164533227';
$result = Validate_BE::bankCode($badBankCode);
echo 'Test ' . $badBankCode .' : <br />';
var_export($result);

echo '<br /><br />';
$goodBankCode = '310164533207';
$result = Validate_BE::bankCode($goodBankCode);
echo 'Test ' . $goodBankCode .' : <br />';
var_export($result);
?>

Output :

Test 310164533227 :
false

Test 310164533207 :
true

Validate a Belgian transfert message

Belgian transfert (virement) can be done with a structured message 12 figures

  • 10-figure number for the message

  • 2-figure number for mod 97

sample

<?php

// Include the package
require_once('Validate/BE.php');

$badBankTransferMessage = '053/3140/16211';
$result = Validate_BE::bankTransferMessage($badBankTransferMessage);
echo 'Test ' . $badBankTransferMessage .' : <br />';
var_export($result);

echo '<br /><br />';
$goodBankTransferMessage = '054/3140/16211';
$result = Validate_BE::bankTransferMessage($goodBankTransferMessage);
echo 'Test ' . $goodBankTransferMessage .' : <br />';
var_export($result);
?>

Output :

Test 053/3140/16211 :
false

Test 054/3140/16211 :
true

Validate a VAT account number

Belgian VAT consist of 3-figure number.

Actually no doc was found about a checksum.

sample

<?php

// Include the package
require_once('Validate/BE.php');

$badVAT = '102.239.951';
$result = Validate_BE::vat($badVAT);
echo 'Test ' . $badVAT .' : <br />';
var_export($result);

echo '<br /><br />';
$goodVAT = '202-239-951';
$result = Validate_BE::vat($goodVAT);
echo 'Test ' . $goodVAT .' : <br />';
var_export($result);
?>

Output :

Test 102.239.951 :
false

Test 202-239-951 :
true

Validate a phonenumber

Validate a belgian phone number passed as first param second specify if it would be a mobile or a traditional line or both. "/" (slash), "-" (dash), "." (dot), and white spaces are ignored. "+" are use a exit code : 0 in Belgium.

NOTE : this validate want a BELGIAN phonenumber to return true, not a valid number to call FROM belgium

sample

<?php

// Include the package
require_once('Validate/BE.php');

$badPhone = '00 32 12 123 45 67';
$result = Validate_BE::phoneNumber($badPhone);
echo 'Test ' . $badPhone .' : <br />';
var_export($result);

echo '<br /><br />';
$goodPhone = '00 32 45 12 34 56';
$result = Validate_BE::phoneNumber($goodPhone);
echo 'Test ' . $goodPhone .' : <br />';
var_export($result);
?>

Output :

Test '00 32 12 123 45 67' :
false

Test '00 32 45 12 34 56' :
true

sample

See now with the parameter

<?php

// Include the package
require_once('Validate/BE.php');

$goodPhone = '00 32 45 12 34 56';
$mobilePhone = '00 32 485 34 56';

echo 'Test ' . $goodPhone .' : <br />';
$result = Validate_BE::phoneNumber($goodPhone);
var_export($result) . '-';
$result = Validate_BE::phoneNumber($goodPhone,VALIDATE_BE_PHONENUMBER_TYPE_ANY);
var_export($result) . '-';
$result = Validate_BE::phoneNumber($goodPhone,VALIDATE_BE_PHONENUMBER_TYPE_NORMAL);
var_export($result) . '-';
$result = Validate_BE::phoneNumber($goodPhone,VALIDATE_BE_PHONENUMBER_TYPE_MOBILE);
var_export($result) . '-';

echo '<br /><br />';
$result = Validate_BE::phoneNumber($mobilePhone);
var_export($result) . '-';
$result = Validate_BE::phoneNumber($mobilePhone,VALIDATE_BE_PHONENUMBER_TYPE_ANY);
var_export($result) . '-';
$result = Validate_BE::phoneNumber($mobilePhone,VALIDATE_BE_PHONENUMBER_TYPE_NORMAL);
var_export($result) . '-';
$result = Validate_BE::phoneNumber($mobilePhone,VALIDATE_BE_PHONENUMBER_TYPE_MOBILE);
var_export($result);

?>

Output :

Test 00 32 45 12 34 56 :
true - true - true - false

Test 00 32 485 34 56 :
false - false - false - false

Prev | Validate_BE | Next
Introduction | PEAR Manual | Validate_CA


Validate_CA

Validate_CA

Caution

This package is in alpha state

Package contains locale validation for Canada such as:

  1. Social Inurance Numbers (SIN)

  2. Regions (Provinces)

  3. Postal Codes

  4. Phone Numbers

See also:

  • the api documentation

  • The page on pear.php.net

Table of Contents
  • Introduction -- Introduction to validate_CA
  • List of aivailable validations -- available validation in validate_ca
Prev | Validate | Next
List of aivailable validations | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to validate_CA

Description

The package offers some methods to validate specific data for Canada

Usage

General usage

Every module of Validate follows the same philosophy. Propose some validation method retuning boolean result. Some methods have some optional parameters to set a stronger check.

sample

<?php

// Include the package
require_once 'Validate/CA.php';
?>
Prev | Validate_CA | Next
Validate_CA | PEAR Manual | List of aivailable validations


List of aivailable validations

List of aivailable validations

List of aivailable validations – available validation in validate_ca

Validate a canadian social security number

The canadian social security number is on the SIS card of all canadian.

A check digit is the last one, computed the standard _get_control_number function.

sample

<?php

// Include the package
require_once('Validate/CA.php');

$badSsn = '012345674';
$result = Validate_CA::ssn($badSsn);
echo 'Test ' . $badSsn .' : <br />';
var_export($result);

echo '<br /><br />';
$goodSsn = '123456782';
$result = Validate_CA::ssn($goodSsn);
echo 'Test ' . $goodSsn .' : <br />';
var_export($result);
?>

Output :

Test 012345674 :
false

Test 123456782 :
true

Validate a canadian postcode

The postal code is a six-character, uniformly structured alphanumeric code in the form of ANA NAN where "A" represents an alphabetic character and "N" represents a numeric character.

The postal code is made up of two segments:

The first, the Forward Sortation Area (FSA), is a combination of three characters (alpha - numeric - alpha).

It identifies a major geographic area in an urban or a rural location.

The third character of the FSA segment (M4B), in conjunction with the first two characters, describes an exact area of a city or town or other geographic area.

The second segment, Local Delivery Unit (LDU), is a combination of three characters (numeric - alpha - numeric).

It identifies the smallest delivery unit within a forward sortation area.

The LDU, identified by the last three characters of the postal code, allows for a final sort within an FSA.

In Urban Areas, the last three digits may indicate a specific city block (one side of a street between two intersecting streets), a single building or, in some cases, a large volume mail receiver.

In Rural Areas, the last three digits (LDU), together with the FSA, identify a specific Rural community.

First parameter of the method is the post code to validate.

An optional parameter for limite the request to a province.

sample

<?php

// Include the package
require_once('Validate/CA.php');

$badPostCode = '48103';
$result = Validate_CA::postalCode($badPostCode);
echo 'Test ' . $badPostCode .' : <br />';
var_export($result);

echo '<br /><br />';
$goodPostCode = 'H2M 2J1';
$result = Validate_CA::postalCode($goodPostCode);
echo 'Test ' . $goodPostCode .' : <br />';
var_export($result);
?>

Output :

Test 48103 :
false

Test H2M 2J1 :
true

sample using province parameter

H2M 2J1 like a good post code, but province don't exit.

<?php

// Include the package
require_once('Validate/CA.php');

$postalCode = 'H2M 2J1'; // in Montreal area

$result = Validate_CA::postalCode($postalCode);
echo 'Test ' . $postalCode .' : <br />';
var_export($result);

echo '<br /><br />';
$result = Validate_CA::postalCode($postalCode,'QC');
// QC for Montreal
echo 'Test ' . $postalCode .' in QC: <br />';
var_export($result);

echo '<br /><br />';
$result = Validate_CA::postalCode($postalCode,'AB');
// AB for Toronto
echo 'Test ' . $postalCode .' in AB: <br />';
var_export($result);

?>

Output :

Test H2M 2J1 :
true

Test H2M 2J1 in QC:
true

Test H2M 2J1 in AB:
false

Validate a phonenumber

Canada and the United States share the same numbering plan, hence you can also call Validate_US::phoneNumber()

Can allow only seven digit numbers.

Also allows the formats, (xxx) xxx-xxxx, xxx xxx-xxxx, and now x (xxx) xxx-xxxx or various combination without spaces or dashes.

sample

<?php
// Include the package
require_once('Validate/CA.php');

$phoneNumber = '467875098x';
$result = Validate_CA::phoneNumber($phoneNumber);
echo 'Test ' . $phoneNumber .' : <br />';
var_export($result);
echo '<br />';

$phoneNumber = '4678750987';
$result = Validate_CA::phoneNumber($phoneNumber);
echo 'Test ' . $phoneNumber .' : <br />';
var_export($result);

?>

Output :

Test 467875098x :
false
Test 4678750987 :
true

sample

See now with the parameter

<?php
// Include the package
require_once('Validate/CA.php');

$phoneNumber = '8750987';
$result = Validate_CA::phoneNumber($phoneNumber,false);
echo 'Test ' . $phoneNumber .' : <br />';
var_export($result);

echo '<br /><br />';
$phoneNumber = '8750987';
echo 'Test ' . $phoneNumber .' : <br />';
echo 'With $requireAreaCode false <br />';
$result = Validate_CA::phoneNumber($phoneNumber,false);
var_export($result);
echo '<br />';
echo 'With $requireAreaCode true<br />';
$result = Validate_CA::phoneNumber($phoneNumber,true);
var_export($result);

echo '<br /><br />';
$phoneNumber = '(467)8750987';
echo 'Test ' . $phoneNumber .' : <br />';
echo 'With $requireAreaCode false <br />';
$result = Validate_CA::phoneNumber($phoneNumber,false);
var_export($result);
echo '<br />';
echo 'With $requireAreaCode true<br />';
$result = Validate_CA::phoneNumber($phoneNumber,true);
var_export($result);

?>

Output :

Test 8750987 :
true

Test 8750987 :
With $requireAreaCode false
true
With $requireAreaCode true
false

Test (467)8750987 :
With $requireAreaCode false
false
With $requireAreaCode true
true

Prev | Validate_CA | Next
Introduction | PEAR Manual | Validate_CH


Validate_CH

Validate_CH

Caution

This package is in alpha state

Package contains locale validation for Switzerland such as:

  1. Social insurance number (aka SSN)

  2. Postal Codes

  3. Swiss university's immatriculation number

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
List of aivailable validations | PEAR Manual | Validate_DE


Validate_DE

Validate_DE

Caution

This package is in alpha state

Package contains locale validation for Germany such as:

  1. Postal Code

  2. Bank Code

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_CH | PEAR Manual | Validate_DK


Validate_DK

Validate_DK

Caution

This package is in alpha state

Package contains locale validation for Denmark such as:

  1. Social Security Number (CPR Nummer)

  2. Car Registration number

  3. Postal Codes

  4. Phone Numbers

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_DE | PEAR Manual | Validate_ES


Validate_ES

Validate_ES

Caution

This package is in alpha state

Package contains locale validation for Spain such as:

  1. DNI (El Documento Nacional de Indentidad a chequear)

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_DK | PEAR Manual | Validate_esMX


Validate_esMX

Validate_esMX

Caution

This package never released

Package contains locale validation for Mexico such as:

  1. DNI (El Documento Nacional de Indentidad a chequear)

  2. Postal code

  3. Region (states)

  4. Phone numbers

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_ES | PEAR Manual | Validate_FI


Validate_FI

Validate_FI

Specific validation methods for data used in Finland.

See also:

  • Latest auto-generated API documentation

  • Package information on pear.php.net

Table of Contents
  • Introduction -- introduction to Validate_FI
  • Validate_FI::postalCode -- Validate Finnish postal code
  • Validate_FI::phoneNumber -- Validate Finnish telephone number
  • Validate_FI::carLicensePlate -- Validate Finnish car license plate number
  • Validate_FI::bikeLicensePlate -- Validate Finnish motorbike license plate number
  • Validate_FI::pin -- Validate Personal Identity Number (HETU)
  • Validate_FI::finuid -- Validate Finnish Unique Identification Number (SATU)
  • Validate_FI::businessId -- Validate Finnish Business ID (Y-tunnus)
  • Validate_FI::partyId -- Validate Finnish Party Identification number (OVT-tunnus)
  • Validate_FI::vatNumber -- Validate Finnish Value Added Tax number (ALV-numero)
  • Validate_FI::bankAccount -- Validate Finnish bank account number
  • Validate_FI::refNum -- Validate Finnish bank reference number
  • Validate_FI::creditCard -- Validate credit card number
Prev | Validate | Next
Validate_esMX | PEAR Manual | Introduction


Introduction

Introduction

Introduction – introduction to Validate_FI

Description

Specific validation methods for data used in Finland.

Usage

General usage

Every module of Validate follows the same philosophy. Propose some validation method which returns a boolean result.

Some methods have some optional parameters to set stronger checks.

Sample using phoneNumber()

<?php
// Include the package
require_once 'Validate/FI.php';

// Validate Finnish telephone number
$phoneNumber = '+358 40 1234567';
if ( Validate_FI::phoneNumber($phoneNumber) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>

Output:

Valid

Prev | Validate_FI | Next
Validate_FI | PEAR Manual | Validate_FI::postalCode


Validate_FI::postalCode

Validate_FI::postalCode

Validate_FI::postalCode() – Validate Finnish postal code

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::postalCode ( string $number , bool $strong )

Description

Validate Finnish postal code.

Five digit postal code, maybe with a leading 'FI-' (XXXXX or FI-XXXXX).

An optional parameter for activate strong checks using a list of postcodes (not implemented).

Parameter

string $number

The postal code to be validated

boolean $strong

optional; strong checks (e.g. against a list of postal codes)(not implemented)

Return value

boolean - true if postal code is valid, false otherwise

Example

Using postalCode()

<?php
// Include the package
require_once 'Validate/FI.php';

$postalCode = '00100';
if ( Validate_FI::postalCode($postalCode) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Introduction | PEAR Manual | Validate_FI::phoneNumber


Validate_FI::phoneNumber

Validate_FI::phoneNumber

Validate_FI::phoneNumber() – Validate Finnish telephone number

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::phoneNumber ( string $number )

Description

Validate Finnish telephone number.

Simple check: number must be numeric when (, ), -, +, ., ' ' chars are removed and 3-20 digit number.

Parameter

string $number

The telephone number to be validated

Return value

boolean - true if telephone number is valid, false otherwise

Example

Using phoneNumber()

<?php
// Include the package
require_once 'Validate/FI.php';

$phoneNumber = '+358 40 1234567';
if ( Validate_FI::phoneNumber($phoneNumber) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::postalCode | PEAR Manual | Validate_FI::carLicensePlate


Validate_FI::carLicensePlate

Validate_FI::carLicensePlate

Validate_FI::carLicensePlate() – Validate Finnish car license plate number

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::carLicensePlate ( string $number )

Description

Validate Finnish car license plate number. Format: AAA-XXX, CD-XXXX or C-XXXXX. First or only number cannot be zero.

AAA-XXX: AAA is 2-3 letters UPPERCASE A-Z + ÅÄÖ and XXX is 1-3 numbers.

CD-XXXX: CD- and XXXX is 1-4 numbers (diplomat licence plate).

C-XXXXX: C- and XXXXX is 1-5 numbers (other tax-free diplomat licence plate).

Parameter

string $number

The license plate number to be validated

Return value

boolean - true if license plate number is valid, false otherwise

Example

Using carLicensePlate()

<?php
// Include the package
require_once 'Validate/FI.php';

$carLicensePlate = 'ABC-123';
if ( Validate_FI::carLicensePlate($carLicensePlate) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::phoneNumber | PEAR Manual | Validate_FI::bikeLicensePlate


Validate_FI::bikeLicensePlate

Validate_FI::bikeLicensePlate

Validate_FI::bikeLicensePlate() – Validate Finnish motorbike license plate number

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::bikeLicensePlate ( string $number )

Description

Validate Finnish motorbike license plate number. Format: AAAXXX. First or only number cannot be zero.

Where AAA is 2-3 letters UPPERCASE A-Z + ÅÄÖ and XXX is 1-3 numbers. Letters and numbers are actually in separate lines.

Parameter

string $number

The license plate number to be validated

Return value

boolean - true if license plate number is valid, false otherwise

Example

Using bikeLicensePlate()

<?php
// Include the package
require_once 'Validate/FI.php';

$bikeLicensePlate = 'ABC123';
if ( Validate_FI::bikeLicensePlate($bikeLicensePlate) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::carLicensePlate | PEAR Manual | Validate_FI::pin


Validate_FI::pin

Validate_FI::pin

Validate_FI::pin() – Validate Personal Identity Number (HETU)

Synopsis

require_once 'Validate/FI.php';

mixed Validate_FI::pin ( string $number , bool $info )

Description

Validate Personal Identity Number (HETU).

The Finnish PIN number (HETU) aka Social Security Number (SSN) is a 11 digit number with birthdate as ddmmyycxxxy where c is century, xxx is a three digit individual number and the last digit is a control number (y).

If xxx is odd it's a male PIN number and if even a female.

Return gender (Male or Female) and date of birth (YYYY-MM-DD) in array if PIN is valid, is available by switching $info (2nd parameter) to true.

Example: 010101-123N would be a male and born in 1st of January 1901.

Parameter

string $number

PIN number to be validated

boolean $info

optional; Return gender and date of birth on success

Return value

mixed - Returns true or false if $info = false or gender (Male or Female) and date of birth (YYYY-MM-DD) in array if PIN is valid, false otherwise

Example

Using pin() in default mode

<?php
// Include the package
require_once 'Validate/FI.php';

$pin = '010101-123N';
if ( Validate_FI::pin($pin) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>

Using pin() with $info = TRUE

<?php
// Include the package
require_once('Validate/FI.php');

$pin = '010101-123N';
if ( $userinfo = Validate_FI::pin($pin, true) ) {
    print_r($userinfo);
} else {
    print 'Not valid!';
}
?>

Output:

Array
(
    [0] => Male
    [1] => 1901-01-01
)

Prev | Validate_FI | Next
Validate_FI::bikeLicensePlate | PEAR Manual | Validate_FI::finuid


Validate_FI::finuid

Validate_FI::finuid

Validate_FI::finuid() – Validate Finnish Unique Identification Number (SATU)

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::finuid ( string $number )

Description

Validate Finnish Unique Identification Number (SATU). Format: xxxxxxxxy.

FINUID (SATU) is a 9 digit number. The last digit is a control number.

Parameter

string $number

FINUID number to be validated

Return value

boolean - true if FINUID is valid, false otherwise

Example

Using finuid()

<?php
// Include the package
require_once 'Validate/FI.php';

$finuid = '10011187H';
if ( Validate_FI::finuid($finuid) ) {{
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::pin | PEAR Manual | Validate_FI::businessId


Validate_FI::businessId

Validate_FI::businessId

Validate_FI::businessId() – Validate Finnish Business ID (Y-tunnus)

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::businessId ( string $number )

Description

Validate Finnish Business ID (Y-tunnus). Format: xxxxxxx-y.

The Finnish Business ID number (Y-tunnus) is a 9 digit number. The last digit is a control number (y).

Parameter

string $number

Business ID number to be validated

Return value

boolean - true if Business ID is valid, false otherwise

Example

Using businessId()

<?php
// Include the package
require_once 'Validate/FI.php';

$businessId = '1572860-0';
if ( Validate_FI::businessId($businessId) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::finuid | PEAR Manual | Validate_FI::partyId


Validate_FI::partyId

Validate_FI::partyId

Validate_FI::partyId() – Validate Finnish Party Identification number (OVT-tunnus)

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::partyId ( integer $number )

Description

Validate Finnish Party Identification number (OVT-tunnus).

The Finnish Party Identification number (OVT-tunnus) is a 12-17 digit number and it is generated from Business ID.

Example: 0037AAAAAAAABBBBB, 0037 indicates Finland, AAAAAAAA is the Business ID and BBBBB is optional organization number.

Parameter

integer $number

Party Identification number to be validated

Return value

boolean - true if number is valid, false otherwise

Example

Using partyId()

<?php
// Include the package
require_once 'Validate/FI.php';

$partyId = '003715728600';
if ( Validate_FI::partyId($partyId) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::businessId | PEAR Manual | Validate_FI::vatNumber


Validate_FI::vatNumber

Validate_FI::vatNumber

Validate_FI::vatNumber() – Validate Finnish Value Added Tax number (ALV-numero)

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::vatNumber ( string $number )

Description

Validate Finnish Value Added Tax number (ALV-numero). Format: FIXXXXXXXX.

The Finnish VAT number (ALV-numero) is maximum of 14 digits and is generated from Business ID.

Parameter

string $number

VAT number to be validated

Return value

boolean - true if VAT number is valid, false otherwise

Example

Using vatNumber()

<?php
// Include the package
require_once 'Validate/FI.php';

$vatNumber = 'FI15728600';
if ( Validate_FI::vatNumber($vatNumber) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::partyId | PEAR Manual | Validate_FI::bankAccount


Validate_FI::bankAccount

Validate_FI::bankAccount

Validate_FI::bankAccount() – Validate Finnish bank account number

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::bankAccount ( string $number )

Description

Validate Finnish bank account number. Format: XXXXXX-XXXXXXXX, 6 digits, - and 2-8 digits.

This method checks the bank account number according to Finnish Bank Association.

Parameter

string $number

Finnish bank account number to be validated

Return value

boolean - true if bank account is valid, false otherwise

Example

Using bankAccount()

<?php
// Include the package
require_once 'Validate/FI.php';

$bankAccount = '159030-776';
if ( Validate_FI::bankAccount($bankAccount) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::vatNumber | PEAR Manual | Validate_FI::refNum


Validate_FI::refNum

Validate_FI::refNum

Validate_FI::refNum() – Validate Finnish bank reference number

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::refNum ( string $number )

Description

Validate Finnish bank reference number.

This method checks the bank reference number according to Finnish Bank Association.

Parameter

string $number

Finnish bank reference number to be validated (spaces and dashes tolerated)

Return value

boolean - true if reference number is valid, false otherwise

Example

Using refNum()

<?php
// Include the package
require_once 'Validate/FI.php';

$refNum = '61 74354';
if ( Validate_FI::refNum($refNum) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::bankAccount | PEAR Manual | Validate_FI::creditCard


Validate_FI::creditCard

Validate_FI::creditCard

Validate_FI::creditCard() – Validate credit card number

Synopsis

require_once 'Validate/FI.php';

bool Validate_FI::creditCard ( string $number )

Description

Validate credit card number.

This method checks the credit card number according to Luhn algorithm. This method doesn't guarantee that the card is legitimate.

Parameter

string $number

credit card number to be validated (spaces and dashes tolerated)

Return value

boolean - true if credit card number is valid, false otherwise

Example

Using creditCard()

<?php
// Include the package
require_once 'Validate/FI.php';

$creditCard = '5427 0073 1297 6425';
if ( Validate_FI::creditCard($creditCard) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Prev | Validate_FI | Next
Validate_FI::refNum | PEAR Manual | Validate_FR


Validate_FR

Validate_FR

Package contains locale validation for France such as:

  1. SSN

  2. Postal Code

  3. RIB

  4. SIREN

  5. SIRET

  6. Region (Departements)

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_FI::creditCard | PEAR Manual | Validate_IE


Validate_IE

Validate_IE

Caution

This package is in beta state

Package contains locale validation for Ireland such as:

  1. Bank Account

  2. Drivers Licence Numbers

  3. IBAN

  4. Passport Numbers

  5. Phone Numbers

  6. Postal Code

  7. SSN/PPSN

  8. SWIFT Codes

See also :

  • The API Documentation

  • The page on http://pear.php.net

Table of Contents
  • Introduction -- Introduction to validate_IE
  • List of available validations -- available validation in validate_ie
Prev | Validate | Next
Validate_FR | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to validate_IE

Description

The package offers some methods to validate specific data for Ireland

Usage

General usage

Every module of Validate follows the same philosophy. Propose some validation method retuning boolean result. Some methods have some optional parameters to set a stronger check.

sample

<?php

// Include the package
require_once 'Validate/IE.php';
?>
Prev | Validate_IE | Next
Validate_IE | PEAR Manual | List of available validations


List of available validations

List of available validations

List of available validations – available validation in validate_ie

Validate an Irish PPSN number

The Personal Public Service Number (PPS No) is an identifier issued by Client Identity Services, Department of Social and Family Affairs on behalf of the Minister for Social and Family Affairs in the Republic of Ireland.

sample

<?php

// Include the package
require_once 'Validate/IE.php';

$badSsn = '012345674';
$result = Validate_IE::ssn($badSsn);
echo 'Test ' . $badSsn .' : <br />';
var_export($result);

echo '<br /><br />';
$goodSsn = '1234567W';
$result = Validate_IE::ssn($goodSsn);
echo 'Test ' . $goodSsn .' : <br />';
var_export($result);
?>

Output :

Test 012345674 :
false

Test 1234567W :
true

Validate an Irish postcode

There is no national post code system in Ireland; at present the postalCode method only validates Dublin postal districts: "Dublin 6W", or "D 4" for example.

Validate a phonenumber

Ireland has phone numbers that are built similar to US and Canadian numbers however they have a couple of distinctions.

For instance the STD [Standard Trunk Dial] prefix varies in length: Dublin has the code '01', Cork has '021', Galway 091, and so on.

The phoneNumber method takes two parameters: the first is the phone number to be tested and the second is a flag indicating whether the number should be checked for a valid prefix. This boolean flag defaults to true.

sample with area code prefix testing on by default.

<?php
// Include the package
require_once 'Validate/IE.php';

$phoneNumber = '467875098x';
$result = Validate_IE::phoneNumber($phoneNumber);
echo 'Test ' . $phoneNumber .' : <br />';
var_export($result);
echo '<br />';

$phoneNumber = '014142438';
$result = Validate_IE::phoneNumber($phoneNumber);
echo 'Test ' . $phoneNumber .' : <br />';
var_export($result);

?>

Output :

Test 467875098x :
false

Test  014142438:
true

sample

See now with the requiredAreaCode parameter being utilised.

<?php
// Include the package
require_once 'Validate/IE.php';

$phoneNumber = '87509824';
$result = Validate_IE::phoneNumber($phoneNumber,false);
echo 'Test ' . $phoneNumber .' : <br />';
var_export($result);

echo '<br /><br />';
$phoneNumber = '8750987';
echo 'Test ' . $phoneNumber .' : <br />';
echo 'With $requireAreaCode false <br />';
$result = Validate_IE::phoneNumber($phoneNumber,false);
var_export($result);
echo '<br />';
echo 'With $requireAreaCode true<br />';
$result = Validate_IE::phoneNumber($phoneNumber,true);
var_export($result);

echo '<br /><br />';
$phoneNumber = '(0915)8750987';
echo 'Test ' . $phoneNumber .' : <br />';
echo 'With $requireAreaCode false <br />';
$result = Validate_IE::phoneNumber($phoneNumber,false);
var_export($result);
echo '<br />';
echo 'With $requireAreaCode true<br />';
$result = Validate_IE::phoneNumber($phoneNumber,true);
var_export($result);

?>

Output :

Test 87509824 :
true

Test 8750987 :
With $requireAreaCode false
true
With $requireAreaCode true
false

Test (091)8750987 :
With $requireAreaCode false
false
With $requireAreaCode true
true

Prev | Validate_IE | Next
Introduction | PEAR Manual | Validate_IN


Validate_IN

Validate_IN

Caution

This package is in alpha state

Package contains locale validation for Indian such as:

  1. Permanent Account Number (PAN and TAN)

  2. State and Union Territory codes

  3. Telephone Numbers

  4. Postal (Zip) Codes

  5. Vehicle License Plate Numbers

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
List of available validations | PEAR Manual | Validate_IS


Validate_IS

Validate_IS

Caution

This package is in alpha state

Package contains locale validation for Iceland such as:

  1. SSN (Social Security Number (Icelandic: kennitala))

  2. Postal code (Icelandic: post numer)

  3. Address (Icelandic: heimilisfang)

  4. Telephone number (Icelandic: simanumer)

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_IN | PEAR Manual | Validate_NL


Validate_NL

Validate_NL

Caution

This package is in alpha state

Package contains locale validation for Netherlands such as:

  1. Social insurance number (aka SIN)

  2. Postal Code

  3. Phone Number

  4. Bank Account Number (based on 11proef)

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_IS | PEAR Manual | Validate_NZ


Validate_NZ

Validate_NZ

Caution

This package is in alpha state

Package contains locale validation for New Zealand such as:

  1. Postal Codes

  2. IRD numbers

  3. Regional codes

  4. Telephone number

  5. Bank AC

See also :

  • the api documentation

  • The page on pear.php.net

  • Developper's blog

Prev | Validate | Next
Validate_NL | PEAR Manual | Validate_PL


Validate_PL

Validate_PL

Caution

This package is in alpha state

Package contains locale validation for Poland such as: This class provides methods to validate:

  1. NIP (Polish tax identification number)

  2. Bank account numbers

  3. PESEL (Polish human identification number)

  4. REGON (Polish statistical national economy register)

See also :

  • the api documentation

  • The page on pear.php.net

  • The page about NIP and REGON

  • The page about PESEL

Prev | Validate | Next
Validate_NZ | PEAR Manual | Validate_ptBR


Validate_ptBR

Validate_ptBR

Caution

This package is in alpha state

Package contains locale validation for Brazil such as:

  1. Social Inurance Numbers (SIN)

  2. Region (brazilian states)

  3. Postal Codes

  4. Phone Numbers

  5. CNPJ

  6. CPF

  7. Vehicle's plate

See also :

  • the api documentation

  • The page on pear.php.net

  • Validate_ptBR on developper's blog

Prev | Validate | Next
Validate_PL | PEAR Manual | Validate_UK


Validate_UK

Validate_UK

Caution

This package is in alpha state

Package contains locale validation for United Kingdom such as:

  1. SSN (National Insurance/IN)

  2. Postal Code

  3. Phone Number

  4. Bank Account Number

  5. Sort Code

  6. Car registration numbers

  7. Passports

  8. Driver license

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_ptBR | PEAR Manual | Validate_US


Validate_US

Validate_US

Caution

This package is in beta state

Package contains locale validation for United States such as:

  1. Social insurance number (aka SSN)

  2. Region (state code)

  3. Postal Codes

  4. Phone Numbers

See also :

  • the api documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_UK | PEAR Manual | Validate_ZA


Validate_ZA

Validate_ZA

Caution

This package is in alpha state.

The PEAR Validate_ZA package provides users with various locale validation routines currently for , Postal Codes and Provinces.

  1. South African Identity Number

  2. Regions (Provinces)

  3. Postal Codes

See also :

  • The API documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_US | PEAR Manual | Validate_Finance


Validate_Finance

Validate_Finance

Validation class for Finance data

Package to validate Finance data.

  1. IBAN

See also :

  • The API documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_ZA | PEAR Manual | Validate_Finance_CreditCard


Validate_Finance_CreditCard

Validate_Finance_CreditCard

Validation class for Credit Card

Package to validate Credit card.

  1. Credit card number

  2. Card security code

  3. Card type (i.e. Visa, Mastercard...)

Theses methods only check the format of the data. For instance the package does NOT check if a card is a legitimate card registered with a card issuer, or if the card is reported stolen, etc...

See also :

  • The API documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_Finance | PEAR Manual | Validate_ISPN


Validate_ISPN

Validate_ISPN

Validation class for ISPN (International Standard Product Numbers)

Package contains ISPN (International Standard Product Numbers) validations such as:

  1. ISSN (International Standard Book Number)

  2. ISBN (International Standard Serial Number)

  3. ISMN (International Standard Music Number)

  4. EAN/UCC-8 number

  5. EAN/UCC-13 number

  6. EAN/UCC-14 number

  7. UCC-12 (U.P.C.) ID number

  8. SSCC (Serial Shipping Container Code)

See also :

  • The API documentation

  • The page on pear.php.net

Prev | Validate | Next
Validate_Finance_CreditCard | PEAR Manual | Web Services


Web Services

Web Services

Table of Contents
  • Services_Akismet2
  • Services_Amazon_S3
  • Services_Blogging
  • Services_Delicious
  • Services_Ebay
  • Services_GeoNames
  • Services_Google
  • Services_Technorati
  • Services_W3C_HTMLValidator
  • Services_Weather
  • Services_Yahoo
  • Services_YouTube
  • UDDI
  • XML_RPC
  • XML_RPC2
Prev | PEAR Packages | Next
Validate_ISPN | PEAR Manual | Services_Akismet2


Services_Akismet2

Services_Akismet2

PHP implementation of the Akismet REST API

Table of Contents
  • Introduction
  • Setup
  • The Comment Class
  • API Methods
  • Examples
Prev | Web Services | Next
Web Services | PEAR Manual | Introduction


Introduction

Introduction

About the Akismet API and the Services_Akismet2 package.

The Akismet API

The Akismet API is a web-service API used to filter spam from user-submitted comments. The Akismet API allows for both detecting and marking spam comments. When used correctly, the Akismet API can tremendously reduce the amount of work required to maintain user-submitted comments on a website. Often, the use of the Akismet API can reduce or eliminate the need for other spam-filtering solutions.

Services_Akismet2

Services_Akismet2 is an object-oriented implementation of the Akismet API. Services_Akismet2 supports all features of the Akismet API and provides and easy-to-use PHP 5 interface.

Services_Akismet2 is derived from the miPHP Akismet class written by Bret Kuhns for use in PHP 4. Services_Akismet2 requires PHP 5.2.1 or greater.

Prev | Services_Akismet2 | Next
Services_Akismet2 | PEAR Manual | Setup


Setup

Setup

Service Providers

Though originally created for use with the Akismet service, the Akismet API is also used by other spam-filtering services. Services_Akismet2 works with any service that uses the Akismet API. To use Services_Akismet2 with other spam-filtering service providers, specify the API server in either the constructor, or by using the setConfig() method.

For example:

<?php

require_once 'Services/Akismet2.php';

// set service provider in constructor
$akismet = new Services_Akismet2('http://example.com', 'AABBCCDDEEFF', array(
    'apiServer' => 'antispam.example.com'
));

// set service provider using setConfig() method
$akismet = new Services_Akismet2('http://example.com', 'AABBCCDDEEFF');
$akismet->setConfig('apiServer', 'antispam.example.com');

// for a service provider that uses a non-standard port (8080)
$akismet = new Services_Akismet2('http://example.com', 'AABBCCDDEEFF');
$akismet->setConfig('apiServer', 'antispam.example.com')
        ->setConfig('apiPort', 8080);

?>

Popular spam-filtering service providers using the Akismet API include:

  • Akismet, and

  • TypePad AntiSpam.

API Keys

All requests using the Akismet API must be verified using an API key. The API key is usually tied to a particular website and ensures the user is allowed to use the service (which is not free to provide). Most service providers offer API keys free of charge for personal or low-volume use, and offer licensing for commercial or high-volume applications.

Note: API keys are specific to a particular service provider. If you switch spam-filtering service providers, you will need to acquire an API key for the particular service.

The format of the API key may vary between service providers. The API key itself is specified in the constructor. A Services_Akismet2_InvalidApiKeyException will be thrown when a request is made using an invalid API key.

Testing Your API Key

After you have acquired an API key, you may want to test it. A comment with the author set to viagra-test-123 should always be detected as spam, so it is a good way to make sure things are working properly.

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author' => 'viagra-test-123',
    'user_ip'        => '127.0.0.1',
    'user_agent'     => 'just testing',
    'referrer'       => 'http://example.com'
));

$akismet = new Services_Akismet2('http://myblog.example.com', 'AABBCCDDEEFF');
if ($akismet->isSpam($comment)) {
    echo 'Everything is working properly.';
} else {
    echo 'Something\'s not right!';
}

?>
Prev | Services_Akismet2 | Next
Introduction | PEAR Manual | The Comment Class


The Comment Class

The Comment Class

Overview

The class Services_Akismet2_Comment represents a comment on a website. All Akismet API methods take a comment as the first parameter. The comment class contains content-related information such as the comment text, author name, author email and Web link; as well as server-related information such as the HTTP referer, timestamp and IP address. The accuracy provided by the Akismet API increases as more fields are included in the comment.

Required Fields

There are two required fields:

  • User Agent (the browser used to submit the comment), and

  • User IP (IP address from which the comment was submitted).

The blog URL, as referenced in the Akismet API documentation, is specified in the Services_Akismet2 constructor and does not need to be specified in the comment object.

Auto-Setting Server Fields

When checking if a comment is spam, it is possible to set the required fields, and several other server-related fields automatically. To do so, use the second parameter of the Services_Akismet2::isSpam() method. When using this parameter, usually only the content-related fields need to be specified manually.

Note: Only auto-set server-related fields on actual comments submitted in real-time. If you check comments using an external system, you run the risk of submitting your own server information as spam. Instead, save the server information in the database and set it manually using the Services_Akismet2::setField() method.

Examples

There are two ways to specify fields in the comment object: setter methods, and in the constructor. As a shortcut, Services_Akismet2 methods that require a comment also accept an array of fields. For example:

<?php

require_once 'Services/Akismet2/Comment.php';

// set in constructor
$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test User',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://myblog.example.com',
    'comment_content'      => 'Buy V1agra!'
));

// using setter methods
$comment = new Services_Akismet2_Comment();
$comment->setAuthor('Test User')
        ->setAuthorEmail('test@example.com')
        ->setAuthorUrl('http://myblog.example.com')
        ->setContent('Buy V1agra!');

// using an array as a shortcut
$akismet->isSpam(array(
    'comment_author'       => 'Test User',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://myblog.example.com',
    'comment_content'      => 'Buy V1agra!'
));

?>
Prev | Services_Akismet2 | Next
Setup | PEAR Manual | API Methods


API Methods

API Methods

Table of Contents
  • isSpam() -- Checks whether or not a comment is spam.
  • sumbitSpam() -- Submits a comment as an undetected spam to the Akismet server.
  • sumbitFalsePositive() -- Submits a comment as incorrectly detected spam to the Akismet server.

TODO

Prev | Services_Akismet2 | Next
The Comment Class | PEAR Manual | isSpam()


isSpam()

isSpam()

– Checks whether or not a comment is spam.

TODO

Prev | API Methods | Next
API Methods | PEAR Manual | sumbitSpam()


sumbitSpam()

sumbitSpam()

– Submits a comment as an undetected spam to the Akismet server.

TODO

Prev | API Methods | Next
isSpam() | PEAR Manual | sumbitFalsePositive()


sumbitFalsePositive()

sumbitFalsePositive()

– Submits a comment as incorrectly detected spam to the Akismet server.

TODO

Prev | API Methods | Next
sumbitSpam() | PEAR Manual | Examples


Examples

Examples

Note: If you are using the Akismet API, it is recommended you build a system to enter data back into the API either by submitting missed spam, or by submitting false positives. While not strictly required, passing data back using the API will allow the service to learn from its mistakes, and will ensure the service stays relevant for your needs.

Handling User-Submitted Comments

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test Author',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://example.com/',
    'comment_content'      => 'Hello, World!'
));

try {
    $apiKey  = 'AABBCCDDEEFF';
    $akismet = new Services_Akismet2('http://blog.example.com/', $apiKey);
    if ($akismet->isSpam($comment)) {
        // rather than simply ignoring the spam comment, it is recommended
        // to save the comment and mark it as spam in case the comment is a
        // false positive.
    } else {
        // save comment as normal comment
    }
} catch (Services_Akismet2_InvalidApiKeyException $keyException) {
    echo 'Invalid API key!';
} catch (Services_Akismet2_HttpException $httpException) {
    echo 'Error communicating with Akismet API server: ' .
        $httpException->getMessage();
} catch (Services_Akismet2_InvalidCommentException $commentException) {
    echo 'Specified comment is missing one or more required fields.' .
        $commentException->getMessage();
}

?>

Marking a Missed Comment as Spam

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test Author',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://example.com/',
    'comment_content'      => 'Hello, World!'
));

try {
    $apiKey  = 'AABBCCDDEEFF';
    $akismet = new Services_Akismet2('http://blog.example.com/', $apiKey);
    $akismet->submitSpam($comment);
} catch (Services_Akismet2_InvalidApiKeyException $keyException) {
    echo 'Invalid API key!';
} catch (Services_Akismet2_HttpException $httpException) {
    echo 'Error communicating with Akismet API server: ' .
        $httpException->getMessage();
} catch (Services_Akismet2_InvalidCommentException $commentException) {
    echo 'Specified comment is missing one or more required fields.' .
        $commentException->getMessage();
}

?>

Marking a Comment as a False Positive

<?php

require_once 'Services/Akismet2.php';
require_once 'Services/Akismet2/Comment.php';

$comment = new Services_Akismet2_Comment(array(
    'comment_author'       => 'Test Author',
    'comment_author_email' => 'test@example.com',
    'comment_author_url'   => 'http://example.com/',
    'comment_content'      => 'Hello, World!'
));

try {
    $apiKey  = 'AABBCCDDEEFF';
    $akismet = new Services_Akismet2('http://blog.example.com/', $apiKey);
    $akismet->submitFalsePositive($comment);
} catch (Services_Akismet2_InvalidApiKeyException $keyException) {
    echo 'Invalid API key!';
} catch (Services_Akismet2_HttpException $httpException) {
    echo 'Error communicating with Akismet API server: ' .
        $httpException->getMessage();
} catch (Services_Akismet2_InvalidCommentException $commentException) {
    echo 'Specified comment is missing one or more required fields.' .
        $commentException->getMessage();
}

?>
Prev | Services_Akismet2 | Next
sumbitFalsePositive() | PEAR Manual | Services_Amazon_S3


Services_Amazon_S3

Services_Amazon_S3

A wrapper for the AWS S3 webservices.

Table of Contents
  • Introduction to Services_Amazon_S3
  • Example #1
  • Example #2 and #3
Prev | Web Services | Next
Examples | PEAR Manual | Introduction to Services_Amazon_S3


Introduction to Services_Amazon_S3

Introduction to Services_Amazon_S3

Services_Amazon_S3 is a wrapper for AWS S3. It provides both a OO-style interface, but also an extension in order to use S3 through PHP's stream wrappers.

Prev | Services_Amazon_S3 | Next
Services_Amazon_S3 | PEAR Manual | Example #1


Example #1

Example #1

Retrieving all buckets from a S3 account

The following examples illustrates how to retrieve all buckets of a given S3 account. All you need to replace in the snippet are the $key and $secret variables.

<?php
require_once 'Services/Amazon/S3.php';

$key    = 'your key';
$secret = 'your secret';

$s3 = Services_Amazon_S3::getAccount($key, $secret);

echo '<ul>';
foreach ($s3->getBuckets() as $bucket) {
    echo "<li>{$bucket->name}</li>";
}
echo '</ul>';

?>
Prev | Services_Amazon_S3 | Next
Introduction to Services_Amazon_S3 | PEAR Manual | Example #2 and #3


Example #2 and #3

Example #2 and #3

The following examples illustrates how to retrieve all objects of a given S3 bucket. All you need to replace in the snippet are the $bucket, $key and $secret variables.

Retrieving all objects from a bucket in S3

<?php
require_once 'Services/Amazon/S3.php';

$key    = 'your key';
$secret = 'your secret';
$bucket = 'foobar';

$s3     = Services_Amazon_S3::getAccount($key, $secret);
$bucket = $s3->getBucket($bucket);

echo '<ul>';
foreach ($bucket->getObjects() as $object) {
    echo "<li>{$object->name}</li>";
}
echo '</ul>';

?>

This example details how to retrieve the meta of the objects - for example, size, mimetype, etc..

Retrieving all objects meta data from a bucket in S3

<?php
require_once 'Services/Amazon/S3.php';

$key    = 'your key';
$secret = 'your secret';
$bucket = 'foobar';

$s3     = Services_Amazon_S3::getAccount($key, $secret);
$bucket = $s3->getBucket($bucket);

echo '<ul>';
foreach ($bucket->getObjects() as $object) {
    $object->load(Services_Amazon_S3_Resource_Object::LOAD_METADATA_ONLY);

    echo "<li>{$object->name}: {$object->size} bytes ({$object->contentType})</li>";
}
echo '</ul>';

?>

The following example illustrates how to create an access URL to the objects, with a TTL (time to live, expire time).

Retrieving all objects from a bucket in S3

<?php
require_once 'Services/Amazon/S3.php';

$key    = 'your key';
$secret = 'your secret';
$bucket = 'foobar';

$s3     = Services_Amazon_S3::getAccount($key, $secret);
$bucket = $s3->getBucket($bucket);

echo '<ul>';
foreach ($bucket->getObjects() as $object) {

    $url = $object->getSignedUrl(120); // expire in 2 minutes

    echo "<li>{$object->name}";
    echo '<a href="' . $url . '">download it (link is valid for 2 minutes)</a>";
    echo "</li>";
}
echo '</ul>;

?>
Prev | Services_Amazon_S3 | Next
Example #1 | PEAR Manual | Services_Blogging


Services_Blogging

Services_Blogging

Generic driver-based package to post and read blog entries.

Table of Contents
  • Introduction to Services_Blogging
  • Connecting your blog server
  • Drivers
  • Blog posts / entries
  • Example
Prev | Web Services | Next
Example #2 and #3 | PEAR Manual | Introduction to Services_Blogging


Introduction to Services_Blogging

Introduction to Services_Blogging

Weblogs are an important part of the internet: They allow normal people to express their opinions and thoughts to their family, friends and the whole world by simply publishing some text on a server. This process is very easy and you don't need a grade in computer science to even host a blog on your own or a rented server.

One drawback of blog software is mostly their user interface: Since it is browser based, it requires you to be either online all the time while writing your blog post, or write it in a normal text editor and copy&paste it when going online. Using a text editor you cannot apply font styles to your text.. An offline tool to write blog entries would be really nice in this case.

Considering the idea of an offline tool for writing blog entries leads to the availability of access to your blog from outside the normal web interface - e.g via web services. Most blog hosters and blogging software packages have support for such a web services API, mostly via XML-RPC.

Unfortunately, there are many different of these application programming interfaces in the wild. Some of them support only posting of blog entries, other ones also allow reading. Some blog softwares support images and tags in their posts, others not. The variety is large, and so you could end up writing custom code for every blog server you want to access because of the differences in their API.

This is the point at which Services_Blogging comes into play: It provides a unified API to post and read blog entries, independent of the API supported by the server software hosting the blog. It uses a driver-based approach to communicate with different APIs out there. If a new blogging API is invented, someone just needs to write a driver for the Services_Blogging package, and everyone can access also this blogs.

As of April 2007, the package has the following drivers:

  • Blogger

  • LiveJournal

  • MetaWeblog

Prev | Services_Blogging | Next
Services_Blogging | PEAR Manual | Connecting your blog server


Connecting your blog server

Connecting your blog server

To post entries to your blog, you first need to obtain an instance of the Services_Blogging_Driver suitable for your blog. You need to either find out which API your blog system supports, or let Services_Blogging magically autodiscover those settings.

Creating a driver is done using Services_Blogging's factory() method. It requires five parameters: The driver name, username, password, server URL and the path of the API on the server.

Instantiating a driver using Services_Blogging::factory()

<?php
require_once 'Services/Blogging.php';
$bl = Services_Blogging::factory(
    'metaWeblog', //driver name
    'username',
    'password',
    'http://blog.example.com',
    '/xmlrpc.php'
);
?>

Some blog drivers don't need server and path variables, just fill in null in this case.

Autodiscovering settings

Since it can be tedious to find out which settings are needed for your own blog, this package has a feature called autodiscovery. You either can automatically detect the settings needed to create an instance of the driver needed, or let the class automatically detect and return an instance of the driver needed for your blog system.

Autodiscovering the settings of your blog can be done via Services_Blogging's discoverSettings(), passing the URL of your blog as only parameter. It returns an array with all the needed settings.

Most of the blogging softwares today support multiple blogging APIs. After getting a list of supported APIs via autodiscovery, you need to choose which one fits you best; it's usually the one supporting the most features. Services_Blogging also helps you with this task by providing a method called getBestAvailableDriver(), just passing the array of recently discovered settings to it. Now you have all data needed to instantiate the driver itself.

Auto-discovering settings

<?php
require_once 'Services/Blogging.php';

$settings = Services_Blogging::discoverSettings('http://blog.example.com');
var_dump($settings);
echo Services_Blogging::getBestAvailableDriver($settings) . "\r\n";
//go on with factory()
?>

If that all is still too much work for you, you can let do Services_Blogging everything by calling discoverDriver(), passing the URL of your blog, your username and password to it. It returns a the driver object.

Creating a driver automatically

<?php
require_once 'Services/Blogging.php';

$bl = Services_Blogging::discoverDriver(
    'http://blog.example.com',
    'username',
    'password'
);
?>
Note: The autodiscovery methods throw an exception of type Services_Blogging_Exception if something goes wrong (either autodiscovery fails because your blog software does not support it, or there is no suitable driver for your blog).
Prev | Services_Blogging | Next
Introduction to Services_Blogging | PEAR Manual | Drivers


Drivers

Drivers

Due to the difference of features in the existing blogging APIs, there are two driver classes: Services_Blogging_Driver and Services_Blogging_ExtendetDriver (which extends the first).

Drivers extending Services_Blogging_Driver do only support creating, saving and deleting posts. They are not able to list (or modify) existing posts.

Drivers extending from Services_Blogging_ExtendetDriver do have more features: Reading existing posts, get a list of recent posts, and getting a list of the titles of the recent posts.

Prev | Services_Blogging | Next
Connecting your blog server | PEAR Manual | Blog posts / entries


Blog posts / entries

Blog posts / entries

Beside the difference in features regarding reading and listing existing posts, the APIs have different support for blog post properties. While some simple APIs only allow to define the text of a post, better ones allow to set the title and other ones also support extendet properties like date, date to publish, categories and other.

Once you have the driver object for your blog, you should get a list of post properties supported by your driver. The method is getSupportedPostProperties(); it returns an array of property names. Currently, the following properties are possible:

  • title

  • content

  • publishdate

  • date

  • url

  • categories

See the API documentation of Services_Blogging_Post for the data types.

Prev | Services_Blogging | Next
Drivers | PEAR Manual | Example


Example

Example

Posting an entry

<?php
require_once 'Services/Blogging.php';

$bl = Services_Blogging::factory(
    'metaWeblog',
    'username', 'password',
    'http://blog.example.com', '/xmlrpc.php'
);

$post = $bl->createNewPost();
//$post->setId('14');
$post->title = 'Modified post title';
$post->content = "This is a modified test post by"
               . " Services_Blogging\r\n\r\nSecond line\r\nThird one";
$post->categories = array('cat1', 'cat3');

$bl->savePost($post);
$nLastPostId = $post->id;
echo 'post id: ' . $nLastPostId . "\r\n";

//$bl->deletePost(17);

var_dump($bl->getPost($nLastPostId));
var_dump($bl->getRecentPostTitles(2));
var_dump($bl->getRecentPosts());

?>
Prev | Services_Blogging | Next
Blog posts / entries | PEAR Manual | Services_Delicious


Services_Delicious

Services_Delicious

Object-oriented abstraction for del.icio.us XML API.

Table of Contents
  • Introduction -- Introduction to Services_Delicious
  • Example -- Basic examples of Services_Delicious
Prev | Web Services | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Services_Delicious

Introduction to Services_Delicious

Services_Delicious is an abstraction for the webservice of the social bookmarking site del.icio.us. del.icio.us allows you to easily add sites you like to your personal collection of links, to categorize those sites with keywords, and to share your collection not only between your own browsers and machines, but also with others.

del.icio.us is using "tags" to categorize your bookmarks and allows other users to browse bookmarks by topic.

Services_Delicious enables you to access, add and even delete your social bookmarks by using a Services_Delicious class that provides functions like getAllPosts(), addPost() or deletePost().

Prev | Services_Delicious | Next
Services_Delicious | PEAR Manual | Example


Example

Example

Example – Basic examples of Services_Delicious

Basic examples of Services_Delicious

The following examples show how to use some basic features of Services_Delicious:

Fetching your recent posts

<?php
require_once 'Services/Delicious.php';

$dlc = &new Services_Delicious($username, $password);

$posts = $dlc->getRecentPosts();
echo '<pre>';
print_r($posts);
echo '</pre>';
?>

Getting all tags that you used in your bookmarks

<?php
require_once 'Services/Delicious.php';

$dlc = &new Services_Delicious($username, $password);

$tags = $dlc->getTags();
echo '<pre>';
print_r($tags);
echo '</pre>';
?>

Adding a new bookmark

<?php
require_once 'Services/Delicious.php';

$dlc = &new Services_Delicious($username, $password);

$result = $dlc->addPost('http://pear.php.net', 'PEAR', 'The PHP Extension and Application Repository', 'php');
if (PEAR::isError($result)) {
  die($result->getMessage());
} else {
  echo 'Success';
}
?>
Prev | Services_Delicious | Next
Introduction | PEAR Manual | Services_Ebay


Services_Ebay

Services_Ebay

Object-oriented abstraction for eBay's XML API.

Table of Contents
  • Introduction -- Introduction to Services_Ebay
  • Getting started -- Getting started with the eBay webservice
  • XML encoding -- XML encoding in Services_Ebay
  • Error Handling -- Error Handling in Services_Ebay
  • Architecture -- The architecture of Services_Ebay
  • Example -- Basic example of Services_Ebay
Prev | Web Services | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Services_Ebay

Introduction to Services_Ebay

Services_Ebay is an object-oriented abstraction layer for eBay's XML API. In addition to a SOAP-service, eBay provides an API, that does not follow any standards except wrapping all webservice calls and parameters in XML. This webservice still is more powerful than eBay's SOAP server and in addition has been heavily tested by real-life applications.

eBay's webservice enables you to use all of eBay's features (except bidding on items) in your own PHP applications. The features range from adding new items to managing the transaction, payment and shipping. Currently there are about 70 method calls available, all accept a range of parameters.

Services_Ebay (as of version 0.7.0) already provides wrappers for 50 methods as well as some model classes which help you working with the results from the calls.

To use this package you will need PHP5 with cURL support enabled and should be familiar with PHP5's exception handling.

Prev | Services_Ebay | Next
Services_Ebay | PEAR Manual | Getting started


Getting started

Getting started

Getting started – Getting started with the eBay webservice

Developing eBay applications

The eBay webservice is of course not free to use by the public. To develop and test your applications, you will have to register as an eBay developer (which is free of charge). Furthermore, you will not be able to test and develop on the eBay site, before your application has been certified.

The eBay sandbox

The eBay Developers Program Sandbox is a test environment that represents a "mini" eBay site. The Sandbox provides the most important features of the eBay site, allowing you to build and test your application in a non-production environment. The eBay Sandbox supports both API testing as well as site testing via the GUI interface.

While developing your application, you will always be using the eBay sandbox, which can be accessed via web at http://sandbox.ebay.com/. This site looks and behaves like any eBay website you are being used to.

Using the sandbox

To develop applications in the sandbox you will have to register at the eBay developers program. To do this, follow these steps:

  1. Register as an eBay user:

    In order to register as an eBay developer, you'll have to be an eBay user. As eBay users are valid on all international sites, it is sufficient if you have an eBay user id for your local eBay site, like ebay.com or ebay.de.

  2. Register as an eBay developer:

    Next, you will have to register as an eBay developer at the eBay developer program. This procedure can take some time, as they require you to enter a lot of information, so you should do this carefully. If you are developing an open source application using Services_Ebay, you should apply for an Individual license.

    After the registration has been finisehd, you will recieve three keys that you will need to authenticate your eBay application: DevID, AppID and CertID. You will need these keys later so you should save them somewhere.

  3. Create one or more test users:

    As the sandbox does not share any data with the eBay sites, you will have to create new users that you can use to add items, make transactions and give feedback. You can create as many users as you need for testing purposes, just use the registration form in the sandbox.

    You will need a valid email address for each of your users, as well as a valid US address and telephone number, you can easily get on by using YellowPages. A credit card is not required, your test users will receive money from eBay they can spend in the sandbox. Of course, this is no real money, which has not use outside of the sandbox.

  4. Validate your test users:

    If you want your test users to sell items on eBay, you will need to validate them. This can be done using the ValidateTestUserRegistration() API call, which is already supported by Services_Ebay.

Authentication and Authorization

eBay's Auth&Auth process is quite complex and can be the biggest hurdle for getting started with the webservice. To make an API call the following information is required:

  • DevID (received after registration, unique per developer)

  • AppID (received after registration, unique per application)

  • CertID (received after registration, unique per application)

  • Authentication Token, unique for each user of your application

While you already are in possession of the first three tokens, you still need the last one to make an API call. If your application is used by more than one user (which is the case for web applications), eBay does not want your application to receive the usernames and passwords of your users. If a user authenticates, your application is supposed to redirect him to the eBay login page and pass an additional parameter (a so called RuName). The user will then enter his login information as he is used to on the eBay website and then authorize your application to make API calls on his behalf.

After that, eBay will redirect the user back to your application and pass a unique token, which can be used to identify this user when your application is making API calls. This technique has several advantages:

  • Single sign-on system for eBay applications

  • When your application is hacked, no passwords are revealed

  • The user only sees the login screen he is used to.

As this authentication procedure is quite complex and requires various API calls to function there is an easier way, which can be used for testing. eBay provides the so called Single-User-Tool, an HTML-based tool, which creates tokens that you can use to authenticate a user. All you need to do is submit your DevID, AppID and CertID and select whether the token will be used in the sandbox or production environment.

Getting started with Services_Ebay

Services_Ebay provides a lot of examples, which demonstrate how the API calls have to be used. After installing Services_Ebay, they will be located in the docs/ directory of your PEAR installation. In order to run the examples, you will have to supply the authentication credentials you received from eBay. The easiest way to do this, is to modify the config.php file, which is located in the examples folder.

The configuration file

<?php
// DevID, AppID and CertID
$devId  = 'HFGHSK7JKKJ82JKJFJHF84LKH86Z3JFF71KJKH';

$appId  = 'IUENVCLJEGBN62JLKKLJHD34KKJL-GDJHDGJHD';

$certId = 'GHKL67JKDJLKJGFBNMBCHGDLÖWJH241KKHJKKJ';

// Username and password, only required by some calls
// that set up the Auth&Auth mechanism
$username = 'YourTestUser';

$password = 'Secret Pass';

// Token as returned from the Single-User-Tool
$token = 'AgAAAA.......3jfiEQ**';
?>
Prev | Services_Ebay | Next
Introduction | PEAR Manual | XML encoding


XML encoding

XML encoding

XML encoding – XML encoding in Services_Ebay

XML encoding in Services_Ebay

Since mid-2005, the eBay API will only accept UTF-8 encoded XML-documents. As encoding all data to UTF-8 is tedious, Services_Ebay will take care of this for you. All you need to do is specify the encoding you want to use in your script when creating a session object.

Using ISO-8859-1 in your script

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId, 'ISO-8859-1');
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);

$item = Services_Ebay::loadModel('Item', null, $session);
$item->Category = 57882;
$item->Title = 'International Item';
$item->Description = 'This description contains Umlaut characters like Ä, ü and ß';
$item->Location = 'At my home';
$item->MinimumBid = '532.0'; $item->VisaMaster = 1;
$item->ShippingType = 1;
$item->CheckoutDetailsSpecified = 1;
$item->Country = 'US';
$item->SetShipToLocations(array('US', 'DE', 'GB'));
$item->addShippingServiceOption(1, 1, 3, 1, array('US'));

$result = $ebay->AddItem($item);
?>

The umlaut characters contained in the description of the item will be automatically converted to UTF-8 when the XML-document is created. Furthermore the result document which is returned by the eBay API will be decoded again to ISO-8859-1 so you do not have to worry about UTF-8 at all.

Of course, it is also possible to supply UTF-8 encoded data to Services_Ebay. All you have to do is change the encoding type, when creating the session object.

Using UTF-8 in your script

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId, 'UTF-8');
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);

$item = Services_Ebay::loadModel('Item', null, $session);
$item->Category = 57882;
$item->Title = 'International Item';
$item->Description = utf8_encode('This description contains Umlaut characters like Ä, ü and ß');
$item->Location = 'At my home';
$item->MinimumBid = '532.0'; $item->VisaMaster = 1;
$item->ShippingType = 1;
$item->CheckoutDetailsSpecified = 1;
$item->Country = 'US';
$item->SetShipToLocations(array('US', 'DE', 'GB'));
$item->addShippingServiceOption(1, 1, 3, 1, array('US'));

$result = $ebay->AddItem($item);
?>

In this example you are using utf8_encode() to encode the data prior to passing it to Services_Ebay. To avoid duplicated encoding, you need to set the encoding to UTF-8.

Prev | Services_Ebay | Next
Getting started | PEAR Manual | Error Handling


Error Handling

Error Handling

Error Handling – Error Handling in Services_Ebay

Exceptions in Services_Ebay

As Services_Ebay is a PHP 5 only package, it uses exception handling and the PEAR_Exception class as base class for all exceptions. Exceptions can be thrown, whenever you try to call any of the API calls provided by Services_Ebay, which means you should always nest those in a try/catch-block:

Exception handling

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);
try {
    // call a method
    echo $ebay->GeteBayOfficialTime();
} catch (Exception $e) {
    echo "Something went wrong.";
    echo $e;
}
?>

When calling a non-existent API call or passing the wrong parameters to the API, eBay will abort the API call and return an XML-document that contains error information. Services_Ebay will automatically convert this into an exception that can be easily handled by your PHP application.

Warnings in Services_Ebay

In some cases, the eBay API will still process your request, even if you passed invalid parameters and include error information in the resulting XML-document alongside the actual response of your request.

In this case, the errors will be tagged as warnings, as they were not serious errors. Services_Ebay will not convert these errors to exceptions, but only to instances of Services_Ebay_Error. These objects will be stored in the Services_Ebay_Session and can be retrieved by your application at a later point.

Handling warnings

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);
try {
    // call a method
    echo $ebay->GeteBayOfficialTime();
} catch (Exception $e) {
    // Just ignore the exception and handle them
    // with any warnings, that might have occured.
}

$errors = $session->getErrors();
if (count($errors) == 0) {
    echo "No errors or warnings.\n";
} else {
    foreach ($errors as $error) {
        printf("%s: %s (%d))\n", $error->getSeverity(), $error->getLongMessage(), $error->getCode());
    }
}
?>
Prev | Services_Ebay | Next
XML encoding | PEAR Manual | Architecture


Architecture

Architecture

Architecture – The architecture of Services_Ebay

Overview of Services_Ebay architecture

Services_Ebay consists of a lot of small classes, which keeps the used codebase small, as only the functionality that you use in your applications are loaded and parsed.

This will give you a short overview of the different types of objects that are provided and for which tasks they are used.

Services_Ebay

The Services_Ebay class is used for the following tasks:

  1. Provides factory methods.

    The Services_Ebay provides methods to load and instantiate all of the other classes, that are included in the Services_Ebay distribution. That means that this is the only class you should include and instantiate yourself. Factory methods include loadApiCall(), getSession() and loadModel().

  2. Provides constants.

    This class also defines some constants like the eBay site ids that you will need in your applications, constants include Services_Ebay::SITEID_ID, Services_Ebay::AUTH_TYPE_TOKEN or Services_Ebay::FEEDBACK_BRIEF. Whenever the eBay webservice expects an integer value in an XML tag, Services_Ebay tries to provide a matching constant.

  3. Provides static helper methods.

    The class also provides some helper methods, which can be called statically like getAvailableApiCalls().

  4. Acts as a proxy class.

    The most important usage is that Services_Ebay acts as a proxy class for the API calls, that means you can call methods on the class which will then be redirected to the appropriate call object.

Services_Ebay_Session

The Services_Ebay_Session class is used to handle the serialization and unserialization of the incoming and outgoing XML streams. Furthermore it builds the HTTP headers that are needed and manages all user authentication.

You will probably always use the session indirectly by at first passing it to the Services_Ebay object which will then use the session for making API calls.

Using the session class

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object with the instantiated session
$ebay = new Services_Ebay($session);
?>

Services_Ebay_Transport

The Services_Ebay_Transport classes are used to build up network connections to the eBay webservices and send and recieve the raw data which has been created by Services_Ebay_Session.

Theoretically there may be different transport classes, but due to bugs in PHP's stream functions and some SSL libraries, the only working transport class is Services_Ebay_Transport_Curl, which uses PHP's curl extension.

Services_Ebay_Call

The Services_Ebay_Call classes contain information about the API calls that the eBay webservice offers. Each API call is encapsulated in an object that contains information about the API call, which XML tags have to be used and what the call is expected to return.

There are two ways in which the call objects can be used:

  1. Instantiate them directly (best via the factory method of Services_Ebay), pass all parameters and invoke Services_Ebay_Call::call() while passing the session object to this method.

  2. Use Services_Ebay as a proxy object which is able to do all the work by using PHP5's new object overloading features.

It is recommended to use Services_Ebay as a proxy instead of working directly on the Call objects. Services_Ebay will instantiate the class, pass the parameters and invoke the call method on the Call object.

Services_Ebay_Model

The Services_Ebay_Model classes act as local containers for the remote data stored on the eBay server. For example, when calling Services_Ebay::getItem(), the method will return an instance of Services_Ebay_Model_Item, which contains information about the item as well as some helper methods like Services_Ebay_Model_Item::addToDescription() which encapsulates a new API call.

Currently Services_Ebay provides models for accounts, disputes (single dispute and a list of disputes), user feedback (summary and a single feedback entry), items and list of items, MyeBay, orders, preferences, search results, shipments, eBay stores, transactions and users.

Services_Ebay_Cache

The Services_Ebay_Cache classes allow you to locally cache information that you retrieved from the eBay webservice without changing anything in your scripts. After registering a cache instance for any model type, Services_Ebay will query the cache before making a time-consuming API call.

The cache classes use a very high abstraction and allow you to create new cache containers, so you could store the data in a database, shared memory or wherever you like. Currently there is only one container available, which stores the data in the local filesystem.

To determine, whether a cache is still valid an instance of Services_Ebay_Cache_ExpiryCheck is used, which allows you to build "intelligent" caches that have a shorter expiry time the nearer the end of an auction is.

Prev | Services_Ebay | Next
Error Handling | PEAR Manual | Example


Example

Example

Example – Basic example of Services_Ebay

Basic example of Services_Ebay

The following examples show how to use some basic features of Services_Ebay:

Using a proxy object

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// create new proxy object
$ebay = new Services_Ebay($session);

// call a method
echo $ebay->GeteBayOfficialTime();
?>

Working directly with a Call object

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

$call = Services_Ebay::loadAPICall('GetEbayOfficialTime');
$result = $call->call($session);

echo $result;
?>

Using the model classes

<?php
require_once 'Services/Ebay.php';

// pass some authentication data
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// get an eBay item
$item = $ebay->GetItem(4501333179, 2);

// The Seller property is an object as well
echo 'User-Id of the seller: '.$item->Seller->UserId.'<br />';

// convert the item to an array
echo '<pre>';
print_r($item->toArray());
echo '</pre>';

// Use methods of the model
$item->AddToDescription('I forgot some important information');

// Change the item
$item->Title = 'The new title of the item';

$ebay->ReviseItem($item);
?>
Prev | Services_Ebay | Next
Architecture | PEAR Manual | Services_GeoNames


Services_GeoNames

Services_GeoNames

Services_GeoNames is a PHP interface to the various webservices offered by the GeoNames project.

Table of Contents
  • Introduction -- introduction to the Services_GeoNames package
  • Getting started -- getting started with the Services_GeoNames package
  • Examples -- various code examples
Prev | Web Services | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – introduction to the Services_GeoNames package

Introduction

Services_GeoNames is a PHP interface to the various webservices offered by the GeoNames project.

The GeoNames database contains over 8,000,000 geographical names corresponding to over 6,500,000 unique features. All features are categorized into one out of nine feature classes and further subcategorized into one out of 645 feature codes. Beyond names of places in various languages, data stored include latitude, longitude, elevation, population, administrative subdivision and postal codes. All coordinates use the WGS84 system (World Geodetic System 1984).

Those data are accessible free of charge through a number of Web services and a daily database export. The Web services include direct and reverse geocoding, finding places through postal codes, finding places next to a given place, and finding Wikipedia articles about neighbouring places.

Installation

To install the package with pear just do:

$ pear install -f Services_GeoNames

And to uninstall it:

$ pear uninstall Services_GeoNames

Links

  • GeoNames project homepage

  • GeoNames API documentation.

Prev | Services_GeoNames | Next
Services_GeoNames | PEAR Manual | Getting started


Getting started

Getting started

Getting started – getting started with the Services_GeoNames package

Instanciating the Services_GeoNames class

To instanciate the main class just do:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

?>

And if you have a commercial account:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames('your_username', 'your_authtoken');

?>

Using Services_GeoNames methods

To call a webservice method, just instanciate the class as described above and call the desired method with an array of parameters, for example:

<?php

require_once 'Services/GeoNames.php';

$geonames  = new Services_GeoNames('username', 'some authtoken...');
$countries = $geonames->countryInfo(array('lang' => 'es'));
echo "List of all countries in spanish language:\n";
foreach ($countries as $country) {
    printf(" - %s (capital: %s)\n", $country->countryName, $country->capital);
}

?>

Every method take an array as single parameter, for example in the GeoNames API documentation when you see something like:

Webservice Type : REST
Url : ws.geonames.org/citiesJSON?
Parameters :
north,south,east,west : coordinates of bounding box
callback : name of javascript function (optional parameter)
lang : language of placenames and wikipedia urls (default = en)
maxRows : maximal number of rows returned (default = 10)

That means that you can call the cities() method as follows:

<?php

require_once 'Services/GeoNames.php';

$geo    = new Services_GeoNames();
$cities = $geo->cities(array(
    'north'   => 44.1,
    'south'   => -9.9,
    'east'    => -22.4,
    'west'    => 55.2,
    'lang'    => 'de',
    'maxRows' => 5,
));

?>

Note that for convenience, some methods can take a geonameId (integer) instead of the array as unique parameter, for example, the following two calls are equivalent:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

// theses two method calls are equivalent
$children = $geo->children(3175395);
$children = $geo->children(array('geonameId' => 3175395));

?>

Available methods

API methods
Method name | Parameters | Return type
children() | int geonameId or array | array
cities() | int geonameId or array | array
countryCode() | array | stdclass
countryInfo() | array | array
countrySubdivision() | array | stdclass
earthquakes() | array | array
findNearby() | array | array
findNearbyPlaceName() | array | array
findNearbyPostalCodes() | array | stdclass
findNearbyStreets() | array | array
findNearByWeather() | array | stdclass
findNearbyWikipedia() | array | array
findNearestAddress() | array | stdclass
findNearestIntersection() | array | stdclass
get() | array | stdclass
gtopo30() | array | stdclass
hierarchy() | int geonameId or array | array
neighbourhood() | array | stdclass
neighbours() | int geonameId or array | array
postalCodeCountryInfo() |  | array
postalCodeLookup() | array | array
postalCodeSearch() | array | stdclass
search() | array | array
siblings() | int geonameId or array | array
srtm3() | array | stdclass
timezone() | array | stdclass
weather() | array | array
weatherIcao() | array | stdclass
wikipediaBoundingBox() | array | array
wikipediaSearch() | array | array
Non API methods
Method name | Parameters | Return type | Description
Services_GeoNames::getSupportedEndpoints() |  | array | returns an array of all supported services endpoints (aka methods)
Services_GeoNames::getRequest() |  | HTTP_Request2 | returns the HTTP_Request2 request instance
Services_GeoNames::setRequest() | HTTP_Request2 |  | sets the HTTP_Request2 request instance

Handling exceptions

Services_GeoNames always raise either a Services_GeoNames_Exception or a Services_GeoNames_HTTPException instance, if you don't care of fine grained exceptions, you can just catch the Services_GeoNames_Exception, as it's the parent class of the Services_GeoNames_HTTPException. Here's an example of fine grained exception handling:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

// now geonames uses your url
try {
    $children = $geo->children(3175395);
} catch (Services_GeoNames_HTTPException $exc) {
    // an http error occured
    echo "HTTP error: " . $exc->getMessage();
} catch (Services_GeoNames_Exception $exc) {
    // a programming error or an api error occured
    echo "API error: " . $exc->getMessage();
}

?>

Changing the default service url and adding failover servers

If for some reason you need to change the web service url, you can do the following:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();
$geo->url = 'http://alternate.geonames.org';

// now geonames uses your url
try {
    $children = $geo->children(3175395);
} catch (Services_GeoNames_Exception $exc) {
    echo "Failed: " . $exc->getMessage();
}

?>

If you need high availability or if you are using the commercial version of the web services, Services_GeoNames allows you to specify an array of failover servers, you would just do:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();
$geo->failoverServers[] = 'http://failover1.geonames.org';
$geo->failoverServers[] = 'http://failover2.geonames.org';
$geo->failoverServers[] = 'http://failover3.geonames.org';

// now geonames will try the main url and if it fails, it will loop through
// the failovers servers you have just configured
try {
    $children = $geo->children(3175395);
} catch (Services_GeoNames_Exception $exc) {
    echo "Failed: " . $exc->getMessage();
}

?>

Customizing the http request

If you need a custom request, for example if you are behind a proxy, you can modify the Services_GeoNames request instance, for example:

<?php

require_once 'Services/GeoNames.php';
$geo = new Services_GeoNames();

// customize the http request
$geo->getRequest()->setConfig(array(
    'proxy_host' => 'localhost',
    'proxy_port' => 8118,
));

// now geonames uses your proxy
try {
    $children = $geo->children(3175395);
} catch (Services_GeoNames_Exception $exc) {
    echo "Failed: " . $exc->getMessage();
}

?>

For more infos please read the HTTP_Request2 documentation.

Prev | Services_GeoNames | Next
Introduction | PEAR Manual | Examples


Examples

Examples

Examples – various code examples

Search for all cities named Paris

<?php
require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

$cities = $geo->search(array('name_equals' => 'Paris'));
echo "List of cities named Paris:\n";
foreach($cities as $city) {
    printf(" - %s (%s)\n", $city->name, $city->countryName);
}
echo "\n";

?>

Find all postal codes near by Toulouse in a radius of 10km

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

$postalCodes = $geo->findNearbyPostalCodes(array(
    'lat'     => 43.606,
    'lng'     => 1.444,
    'radius'  => 10, // 10km
    'maxRows' => 100
));
echo "List of postal codes near by Toulouse in a radius of 10km:\n";
foreach ($postalCodes as $code) {
    printf(" - %s (%s)\n", $code->postalCode, $code->placeName);
}
echo "\n";

?>

List all countries and capitals in spanish

<?php
require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();
$countries = $geo->countryInfo(array('lang' => 'es'));
echo "List of all countries in spanish language:\n";
foreach ($countries as $country) {
    printf(" - %s (capital: %s)\n", $country->countryName, $country->capital);
}
echo "\n";

?>

List neightbours countries of France

<?php
require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

// retrieve the geonameId if we don't know it
$array     = $geo->countryInfo(array('country' => 'FR'));
$geonameId = $array[0]->geonameId;

$neighbours = $geo->neighbours(array('geonameId' => $geonameId));
echo "Neighbours of France are:\n";
foreach ($neighbours as $neighbour) {
    printf(" - %s\n", $neighbour->countryName);
}

?>
Prev | Services_GeoNames | Next
Getting started | PEAR Manual | Services_Google


Services_Google

Services_Google

Provides access to the Google SOAP Web APIs

Table of Contents
  • Introduction -- Introduction to Services_Google
  • Example -- Basic examples of Services_Google
Prev | Web Services | Next
Examples | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Services_Google

Introduction to Services_Google

Services_Google allows easy access to the Google SOAP APIs for the search engine, spelling suggestions, and cache.

In order to use this package you will need to register for an API key.

Please note that as of December 5, 2006, Google is no longer issuing new API keys for the SOAP Search API.

Services_Google enables you to search, spell checks and get cached pages from Google's cache by using a Services_Google class that provides functions like search(), spellingSuggestion() or getCachedPage().

Prev | Services_Google | Next
Services_Google | PEAR Manual | Example


Example

Example

Example – Basic examples of Services_Google

Basic examples of Services_Google

The following examples show how to use some basic features of Services_Google:

Search Google for PEAR

<?php
require_once 'Services/Google.php';

$google = new Services_Google($key);

$google->queryOptions['limit'] = 30;
$google->search("PEAR");

foreach ($google as $key => $result) {
  echo "$key]\t$result->title\n";
}
?>

Spell Checking

<?php
require_once 'Services/Google.php';

$google = new Services_Google($key);

echo $google->spellingSuggestion("wahll")."\n";
?>
Prev | Services_Google | Next
Introduction | PEAR Manual | Services_Technorati


Services_Technorati

Services_Technorati

A class for interacting with the Technorati API

Table of Contents
  • Introduction and Quick Start -- Overview of Services_Technorati
Prev | Web Services | Next
Example | PEAR Manual | Introduction and Quick Start


Introduction and Quick Start

Introduction and Quick Start

Introduction and Quick Start – Overview of Services_Technorati

Description

Technorati is a blog search engine. By indexing blogs and exploring links between them, they provide tools for monitoring online conversations taking place on and between blogs. By far the richest source of this information is through their REST-based API, to which this module provides an OO PHP interface. Full documentation for Technorati's API is available on their developers' wiki. To use the API you will need an API key.

To protect against future changes to the underlying API it is accessed using a factory method:

<?php
$tapi =& Services_Technorati::factory($api_key);
?>

The Technorati API limits you to 500 queries per day so those wishing to use it in a high-demand environment will want to employ some caching. Services_Technorati provides support for any caching system with a Cache_Lite-like API. To use a cache, you will need to create it and then pass it to the class in the factory:

<?php
$tapi =& Services_Technorati::factory($api_key, $cache_object);
?>

Once you have instantiated the object you can start passing in queries. Each call takes the form of methodName(keyParameter, options) where options is an array.

Query types and their options
Query Name | Key Parameter | Permitted Options
cosmos | url | type, limit, start, current, claim, highlight
search | query keywords | start, limit, claim
outbound | url | start
tag | tag | limit, start, format, excerptsize, topexcerptsize
topTags | - | limit, start
blogPostTags | url | limit
getInfo | username | -
blogInfo | url | -

(NB. Support for Technorati's attention. XML services is also included in accordance with the spec, but those services are currently in a state of flux so cannot be relied upon.)

The value returned from each query will be either an array representing the unserialized XML or a PEAR Error.

An example return from the blogInfo query (for 'jystewart') is:

<?php
Array
(
    [version] => 1.0
    [document] => Array
        (
            [result] => Array
                (
                    [username] => jystewart
                    [firstname] => James
                    [lastname] => Stewart
                )

            [item] => Array
                (
                    [0] => Array
                        (
                            [weblog] => Array
                                (
                                    [name] => little more than a placeholder
                                    [url] => http://james.anthropiccollective.org
                                    [rssurl] => http://james.anthropiccollective.org/index.rdf
                                    [atomurl] => http://james.anthropiccollective.org/atom.xml
                                    [inboundblogs] => 52
                                    [inboundlinks] => 82
                                    [lastupdate] => 2005-08-27 09:01:42 GMT
                                    [rank] => 7483
                                    [lat] => 0
                                    [lon] => 0
                                    [lang] => 26110
                                    [foafurl] => http://jystewart.net/foaf.rdf
                                )

                        )

                    [1] => Array
                        (
                            [weblog] => Array
                                (
                                    [name] => something approaching a photo album
                                    [url] => http://approach.anthropiccollective.org
                                    [rssurl] =>
                                    [atomurl] =>
                                    [inboundblogs] => 1
                                    [inboundlinks] => 1
                                    [lastupdate] => 2004-08-13 17:40:02 GMT
                                    [rank] => 240760
                                    [lat] => 0
                                    [lon] => 0
                                    [lang] => 0
                                )

                        )

                    [2] => Array
                        (
                            [weblog] => Array
                                (
                                    [name] => grwifi.net : wireless internet (wifi) in grand rapids, michigan
                                    [url] => http://grwifi.net
                                    [rssurl] =>
                                    [atomurl] => http://grwifi.net/atom/
                                    [inboundblogs] => 9
                                    [inboundlinks] => 11
                                    [lastupdate] => 2005-04-15 19:44:46 GMT
                                    [rank] => 50688
                                    [lat] => 0
                                    [lon] => 0
                                    [lang] => 26110
                                )

                        )

                    [3] => Array
                        (
                            [weblog] => Array
                                (
                                    [name] => a work on process
                                    [url] => http://jystewart.net/process
                                    [rssurl] => http://jystewart.net/process/feed/
                                    [atomurl] => http://jystewart.net/process/feed/atom/
                                    [inboundblogs] => 3
                                    [inboundlinks] => 3
                                    [lastupdate] => 2005-08-31 20:44:38 GMT
                                    [rank] => 132735
                                    [lat] => 0
                                    [lon] => 0
                                    [lang] => 26110
                                    [foafurl] => http://jystewart.net/foaf.rdf
                                )
                        )
                )
        )
)
?>

Full details of the XML returned by Technorati is included on the developers' wiki

Prev | Services_Technorati | Next
Services_Technorati | PEAR Manual | Services_W3C_HTMLValidator


Services_W3C_HTMLValidator

Services_W3C_HTMLValidator

This package provides a programmable interface to the W3's HTML Validation service at http://validator.w3.org/.

With this package you can use PHP to obtain usable validation results for HTML. The package utilizes the SOAP 1.2 output format of validator to populate validation result objects with true | false as well as any errors and warning messages.

See the examples included with the package for usage.

Table of Contents
  • Introduction -- Introduction to Services_W3C_HTMLValidator
  • Examples -- Using Services_W3C_HTMLValidator
Prev | Web Services | Next
Introduction and Quick Start | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Services_W3C_HTMLValidator

Overview

The package provides an object oriented interface to communicate with W3C's HTML validator by using their XML-based output interface. See the examples page for information on how to use this package to get validation results.

Setup

Installation

The Services_W3C_HTMLValidator package can be installed using the PEAR installer command pear install Services_W3C_HTMLValidator. If the installation fails due to missing dependencies, one either needs to install them manually or can make the installer fetch all dependencies automatically: pear install -a Services_W3C_HTMLValidator.

Prev | Services_W3C_HTMLValidator | Next
Services_W3C_HTMLValidator | PEAR Manual | Examples


Examples

Examples

Examples – Using Services_W3C_HTMLValidator

Getting results from the HTML Validator

The following examples demonstrate how to get validation results from an instance of the W3C HTML Validator.

Validate by URI

This is a simple example which shows how to validate a URI and return whether the page is valid or not.

<?php
require_once 'Services/W3C/HTMLValidator.php';

$v = new Services_W3C_HTMLValidator();
$u = 'http://www.unl.edu/';
$r = $v->validate($u);

if ($r->isValid()) {
    echo $u.' is valid!';
} else {
    echo $u.' is NOT valid!';
}
?>
Prev | Services_W3C_HTMLValidator | Next
Introduction | PEAR Manual | Services_Weather


Services_Weather

Services_Weather

Table of Contents
  • Class Summary Services_Weather -- PEAR::Services_Weather
  • Services_Weather::apiVersion -- For your convenience, when I come up with changes in the API...
  • Services_Weather::isError -- Checks for an error object, same as in PEAR
  • Services_Weather::service -- Factory for creating the services-objects
  • Class Summary Services_Weather_Common -- PEAR::Services_Weather_Common
  • Services_Weather_Common::calculateDewPoint -- Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
  • Services_Weather_Common::calculateHumidity -- Calculate humidity from temperature and dewpoint This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
  • Services_Weather_Common::calculateWindChill -- Calculate windchill from temperature and windspeed (enhanced formula)
  • Services_Weather_Common::convertDistance -- Convert distance between km, ft and sm
  • Services_Weather_Common::convertPressure -- Convert pressure between in, hpa, mb, mm and atm
  • Services_Weather_Common::convertSpeed -- Convert speed between mph, kmh, kt, mps and fps
  • Services_Weather_Common::convertTemperature -- Convert temperature between f and c
  • Services_Weather_Common::getUnitsFormat -- Returns the selected units format
  • Services_Weather_Common::polar2cartesian -- Convert polar coordinates to cartesian coordinates
  • Services_Weather_Common::setCache -- Enables caching the data, usage strongly recommended
  • Services_Weather_Common::setDateTimeFormat -- Changes the representation of time and dates (see http://www.php.net/date)
  • Services_Weather_Common::setHttpTimeout -- Sets the timeout in seconds for HTTP requests
  • Services_Weather_Common::setUnitsFormat -- Changes the representation of the units (standard/metric)
  • Class Summary Services_Weather_Ejse -- PEAR::Services_Weather_Ejse
  • Services_Weather_Ejse::getForecast -- Get the forecast for the next days
  • Services_Weather_Ejse::getLocation -- Returns the data for the location belonging to the ID
  • Services_Weather_Ejse::getUnits -- Returns the units for the current query
  • Services_Weather_Ejse::getWeather -- Returns the weather-data for the supplied location
  • Services_Weather_Ejse::searchLocation -- EJSE offers no search function to date, so this function is disabled.
  • Services_Weather_Ejse::searchLocationByCountry -- EJSE offers no search function to date, so this function is disabled.
  • Class Summary Services_Weather_Globalweather -- PEAR::Services_Weather_Globalweather
  • Services_Weather_Globalweather::getForecast -- GlobalWeather has no forecast per se, so this function is just for compatibility purposes.
  • Services_Weather_Globalweather::getLocation -- Returns the data for the location belonging to the ID
  • Services_Weather_Globalweather::getUnits -- Returns the units for the current query
  • Services_Weather_Globalweather::getWeather -- Returns the weather-data for the supplied location
  • Services_Weather_Globalweather::searchLocation -- Searches IDs for given location, returns array of possible locations or single ID
  • Services_Weather_Globalweather::searchLocationByCountry -- Returns IDs with location-name for a given country or all available countries, if no value was given
  • Class Summary Services_Weather_Metar -- PEAR::Services_Weather_Metar
  • Services_Weather_Metar::getForecast -- METAR has no forecast per se, so this function is just for compatibility purposes.
  • Services_Weather_Metar::getLocation -- Returns the data for the location belonging to the ID
  • Services_Weather_Metar::getUnits -- Returns the units for the current query
  • Services_Weather_Metar::getWeather -- Returns the weather-data for the supplied location
  • Services_Weather_Metar::searchAirport -- Searches the nearest airport(s) for given coordinates, returns array of IDs or single ID
  • Services_Weather_Metar::searchLocation -- Searches IDs for given location, returns array of possible locations or single ID
  • Services_Weather_Metar::searchLocationByCountry -- Returns IDs with location-name for a given country or all available countries, if no value was given
  • Services_Weather_Metar::setMetarDB -- Sets the parameters needed for connecting to the DB, where the location- search is fetching its data from. You need to build a DB with the external tool buildMetarDB first, it fetches the locations and airports from a NOAA-website.
  • Services_Weather_Metar::setMetarSource -- Sets the source, where the class tries to locate the METAR data
  • Class Summary Services_Weather_Weatherdotcom -- PEAR::Services_Weather_Weatherdotcom
  • Services_Weather_Weatherdotcom::getForecast -- Get the forecast for the next days
  • Services_Weather_Weatherdotcom::getLocation -- Returns the data for the location belonging to the ID
  • Services_Weather_Weatherdotcom::getUnits -- Returns the units for the current query
  • Services_Weather_Weatherdotcom::getWeather -- Returns the weather-data for the supplied location
  • Services_Weather_Weatherdotcom::searchLocation -- Searches IDs for given location, returns array of possible locations or single ID
  • Services_Weather_Weatherdotcom::searchLocationByCountry -- Returns only false, as weather.com offers no country listing via its XML services
  • Services_Weather_Weatherdotcom::setAccountData -- Sets the necessary account-information for weather.com, you'll receive them after registering for the XML-stream
  • Package Services_Weather Constants -- Constants defined in and used by Services_Weather
Prev | Web Services | Next
Examples | PEAR Manual | Class Summary Services_Weather


Class Summary Services_Weather

Class Summary Services_Weather

Class Summary Services_Weather – PEAR::Services_Weather

PEAR::Services_Weather

This class acts as an interface to various online weather-services.

Services_Weather searches for given locations and retrieves current weather data and, dependant on the used service, also forecasts. Up to now, SOAP services from CapeScience and EJSE, XML from weather.com and METAR from noaa.gov are supported, further services will get included, if they become available and are properly documented.

Class Trees for Services_Weather

  • Services_Weather

Prev | Services_Weather | Next
Services_Weather | PEAR Manual | Services_Weather::apiVersion


Services_Weather::apiVersion

Services_Weather::apiVersion

Services_Weather::apiVersion() – For your convenience, when I come up with changes in the API...

Synopsis

require_once '/Weather.php';

string Services_Weather::apiVersion ( )

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Class Summary Services_Weather | PEAR Manual | Services_Weather::isError


Services_Weather::isError

Services_Weather::isError

Services_Weather::isError() – Checks for an error object, same as in PEAR

Synopsis

require_once '/Weather.php';

bool Services_Weather::isError ( PEAR_Error|mixed $value )

Description

This package is not documented yet.

Parameter

PEAR_Error|mixed $value

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather::apiVersion | PEAR Manual | Services_Weather::service


Services_Weather::service

Services_Weather::service

Services_Weather::service() – Factory for creating the services-objects

Synopsis

require_once '/Weather.php';

PEAR_Error|object& Services_Weather::service ( string $service , array $options = null )

Description

Usable keys for the options array are:

  • debug enables debugging output

--- Common Options

  • cacheType defines what type of cache to use

  • cacheOptions passes cache options

  • unitsFormat use (US)-standard, metric or custom units

  • customUnitsFormat defines the customized units format

  • httpTimeout sets timeout for HTTP requests

  • dateFormat string to use for date output

  • timeFormat string to use for time output

--- EJSE Options

  • none

--- GlobalWeather Options

  • none

--- METAR Options

  • dsn String for defining the DB connection

  • dbOptions passes DB options

  • source http, ftp or file - type of data-source

  • sourcePath where to look for the source, URI or filepath

--- weather.com Options

  • partnerID You'll receive these keys after registering

  • licenseKey with the weather.com XML-service

Parameter

string $service

array $options

Throws

throws PEAR_Error

throws PEAR_Error::SERVICES_WEATHER_ERROR_SERVICE_NOT_FOUND

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather::isError | PEAR Manual | Class Summary Services_Weather_Common


Class Summary Services_Weather_Common

Class Summary Services_Weather_Common

Class Summary Services_Weather_Common – PEAR::Services_Weather_Common

PEAR::Services_Weather_Common

Parent class for weather-services. Defines common functions for unit conversions, checks for cache enabling and does other miscellaneous things.

Class Trees for Services_Weather_Common

  • Services_Weather_Common

Classes that extend Services_Weather_Common
Class | Summary
Services_Weather_Ejse | PEAR::Services_Weather_Ejse
Services_Weather_Globalweather | PEAR::Services_Weather_Globalweather
Services_Weather_Metar | PEAR::Services_Weather_Metar
Services_Weather_Weatherdotcom | PEAR::Services_Weather_Weatherdotcom
Prev | Services_Weather | Next
Services_Weather::service | PEAR Manual | Services_Weather_Common::calculateDewPoint


Services_Weather_Common::calculateDewPoint

Services_Weather_Common::calculateDewPoint

Services_Weather_Common::calculateDewPoint() – Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::calculateDewPoint ( float $temperature , float $humidity )

Description

Temperature has to be entered in deg C!

Parameter

float $temperature

float $humidity

Throws

No exceptions thrown.

See

see http://www.faqs.org/faqs/meteorology/temp-dewpoint/

Note

This function can not be called statically.

Prev | Services_Weather | Next
Class Summary Services_Weather_Common | PEAR Manual | Services_Weather_Common::calculateHumidity


Services_Weather_Common::calculateHumidity

Services_Weather_Common::calculateHumidity

Services_Weather_Common::calculateHumidity() – Calculate humidity from temperature and dewpoint This is only an approximation, there is no exact formula, this one here is called Magnus-Formula

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::calculateHumidity ( float $temperature , float $dewPoint )

Description

Temperature and dewpoint have to be entered in deg C!

Parameter

float $temperature

float $dewPoint

Throws

No exceptions thrown.

See

see http://www.faqs.org/faqs/meteorology/temp-dewpoint/

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::calculateDewPoint | PEAR Manual | Services_Weather_Common::calculateWindChill


Services_Weather_Common::calculateWindChill

Services_Weather_Common::calculateWindChill

Services_Weather_Common::calculateWindChill() – Calculate windchill from temperature and windspeed (enhanced formula)

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::calculateWindChill ( float $temperature , float $speed )

Description

Temperature has to be entered in deg F, speed in mph!

Parameter

float $temperature

float $speed

Throws

No exceptions thrown.

See

see http://www.nws.noaa.gov/om/windchill/

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::calculateHumidity | PEAR Manual | Services_Weather_Common::convertDistance


Services_Weather_Common::convertDistance

Services_Weather_Common::convertDistance

Services_Weather_Common::convertDistance() – Convert distance between km, ft and sm

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::convertDistance ( float $distance , string $from , string $to )

Description

This package is not documented yet.

Parameter

float $distance

string $from

string $to

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::calculateWindChill | PEAR Manual | Services_Weather_Common::convertPressure


Services_Weather_Common::convertPressure

Services_Weather_Common::convertPressure

Services_Weather_Common::convertPressure() – Convert pressure between in, hpa, mb, mm and atm

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::convertPressure ( float $pressure , string $from , string $to )

Description

This package is not documented yet.

Parameter

float $pressure

string $from

string $to

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::convertDistance | PEAR Manual | Services_Weather_Common::convertSpeed


Services_Weather_Common::convertSpeed

Services_Weather_Common::convertSpeed

Services_Weather_Common::convertSpeed() – Convert speed between mph, kmh, kt, mps and fps

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::convertSpeed ( float $speed , string $from , string $to )

Description

This package is not documented yet.

Parameter

float $speed

string $from

string $to

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::convertPressure | PEAR Manual | Services_Weather_Common::convertTemperature


Services_Weather_Common::convertTemperature

Services_Weather_Common::convertTemperature

Services_Weather_Common::convertTemperature() – Convert temperature between f and c

Synopsis

require_once '/Weather/Common.php';

float Services_Weather_Common::convertTemperature ( float $temperature , string $from , string $to )

Description

This package is not documented yet.

Parameter

float $temperature

string $from

string $to

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::convertSpeed | PEAR Manual | Services_Weather_Common::getUnitsFormat


Services_Weather_Common::getUnitsFormat

Services_Weather_Common::getUnitsFormat

Services_Weather_Common::getUnitsFormat() – Returns the selected units format

Synopsis

require_once '/Weather/Common.php';

array Services_Weather_Common::getUnitsFormat ( string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $unitsFormat

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::convertTemperature | PEAR Manual | Services_Weather_Common::polar2cartesian


Services_Weather_Common::polar2cartesian

Services_Weather_Common::polar2cartesian

Services_Weather_Common::polar2cartesian() – Convert polar coordinates to cartesian coordinates

Synopsis

require_once '/Weather/Common.php';

array Services_Weather_Common::polar2cartesian ( float $latitude , float $longitude )

Description

This package is not documented yet.

Parameter

float $latitude

float $longitude

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::getUnitsFormat | PEAR Manual | Services_Weather_Common::setCache


Services_Weather_Common::setCache

Services_Weather_Common::setCache

Services_Weather_Common::setCache() – Enables caching the data, usage strongly recommended

Synopsis

require_once '/Weather/Common.php';

PEAR_Error|bool Services_Weather_Common::setCache ( string $cacheType = "file" , array $cacheOptions = array() )

Description

Requires Cache to be installed

Parameter

string $cacheType

array $cacheOptions

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_CACHE_INIT_FAILED

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::polar2cartesian | PEAR Manual | Services_Weather_Common::setDateTimeFormat


Services_Weather_Common::setDateTimeFormat

Services_Weather_Common::setDateTimeFormat

Services_Weather_Common::setDateTimeFormat() – Changes the representation of time and dates (see http://www.php.net/date)

Synopsis

require_once '/Weather/Common.php';

void Services_Weather_Common::setDateTimeFormat ( string $dateFormat = "" , string $timeFormat = "" )

Description

This package is not documented yet.

Parameter

string $dateFormat

string $timeFormat

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::setCache | PEAR Manual | Services_Weather_Common::setHttpTimeout


Services_Weather_Common::setHttpTimeout

Services_Weather_Common::setHttpTimeout

Services_Weather_Common::setHttpTimeout() – Sets the timeout in seconds for HTTP requests

Synopsis

require_once '/Weather/Common.php';

void Services_Weather_Common::setHttpTimeout ( int $httpTimeout )

Description

This package is not documented yet.

Parameter

integer $httpTimeout

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::setDateTimeFormat | PEAR Manual | Services_Weather_Common::setUnitsFormat


Services_Weather_Common::setUnitsFormat

Services_Weather_Common::setUnitsFormat

Services_Weather_Common::setUnitsFormat() – Changes the representation of the units (standard/metric)

Synopsis

require_once '/Weather/Common.php';

void Services_Weather_Common::setUnitsFormat ( string $unitsFormat , array $customUnitsFormat = array() )

Description

This package is not documented yet.

Parameter

string $unitsFormat

array $customUnitsFormat

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Common::setHttpTimeout | PEAR Manual | Class Summary Services_Weather_Ejse


Class Summary Services_Weather_Ejse

Class Summary Services_Weather_Ejse

Class Summary Services_Weather_Ejse – PEAR::Services_Weather_Ejse

PEAR::Services_Weather_Ejse

This class acts as an interface to the soap service of EJSE. It retrieves current weather data and forecasts based on postal codes (ZIP).

Currently this service is only available for US territory.

For a working example, please take a look at docs/Services_Weather/examples/ejse-basic.php

Class Trees for Services_Weather_Ejse

  • Services_Weather_Common

    • Services_Weather_Ejse

Services_Weather_Ejse Inherited Methods

Inherited from Services_Weather_Common
Method Name | Summary
Services_Weather_Common::calculateDewPoint() | Calculate dewpoint from temperature and humidity. This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateHumidity() | Calculate humidity from temperature and dewpoint. This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateWindChill() | Calculate windchill from temperature and windspeed (enhanced formula)
Services_Weather_Common::convertDistance() | Convert distance between km, ft and sm
Services_Weather_Common::convertPressure() | Convert pressure between in, hpa, mb, mm and atm
Services_Weather_Common::convertSpeed() | Convert speed between mph, kmh, kt, mps and fps
Services_Weather_Common::convertTemperature() | Convert temperature between f and c
Services_Weather_Common::getUnitsFormat() | Returns the selected units format
Services_Weather_Common::polar2cartesian() | Convert polar coordinates to cartesian coordinates
Services_Weather_Common::setCache() | Enables caching the data, usage strongly recommended
Services_Weather_Common::setDateTimeFormat() | Changes the representation of time and dates (see http://www.php.net/date)
Services_Weather_Common::setHttpTimeout() | Sets the timeout in seconds for HTTP requests
Services_Weather_Common::setUnitsFormat() | Changes the representation of the units (standard/metric)
Prev | Services_Weather | Next
Services_Weather_Common::setUnitsFormat | PEAR Manual | Services_Weather_Ejse::getForecast


Services_Weather_Ejse::getForecast

Services_Weather_Ejse::getForecast

Services_Weather_Ejse::getForecast() – Get the forecast for the next days

Synopsis

require_once '/Weather/Ejse.php';

PEAR_Error|array Services_Weather_Ejse::getForecast ( mixed $id = "" , int $days = 2 , string $unitsFormat = "" , string $int )

Description

This package is not documented yet.

Parameter

mixed $id

integer $days

Values between 1 and 9

string $unitsFormat

string $int

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Class Summary Services_Weather_Ejse | PEAR Manual | Services_Weather_Ejse::getLocation


Services_Weather_Ejse::getLocation

Services_Weather_Ejse::getLocation

Services_Weather_Ejse::getLocation() – Returns the data for the location belonging to the ID

Synopsis

require_once '/Weather/Ejse.php';

PEAR_Error|array Services_Weather_Ejse::getLocation ( string $id = "" )

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Ejse::getForecast | PEAR Manual | Services_Weather_Ejse::getUnits


Services_Weather_Ejse::getUnits

Services_Weather_Ejse::getUnits

Services_Weather_Ejse::getUnits() – Returns the units for the current query

Synopsis

require_once '/Weather/Ejse.php';

array Services_Weather_Ejse::getUnits ( string $id = null , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Ejse::getLocation | PEAR Manual | Services_Weather_Ejse::getWeather


Services_Weather_Ejse::getWeather

Services_Weather_Ejse::getWeather

Services_Weather_Ejse::getWeather() – Returns the weather-data for the supplied location

Synopsis

require_once '/Weather/Ejse.php';

PEAR_Error|array Services_Weather_Ejse::getWeather ( string $id = "" , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Ejse::getUnits | PEAR Manual | Services_Weather_Ejse::searchLocation


Services_Weather_Ejse::searchLocation

Services_Weather_Ejse::searchLocation

Services_Weather_Ejse::searchLocation() – EJSE offers no search function to date, so this function is disabled.

Synopsis

require_once '/Weather/Ejse.php';

bool Services_Weather_Ejse::searchLocation ( string $location = null , bool $useFirst = null )

Description

Maybe this is the place to interface to some online postcode service...

Parameter

string $location

boolean $useFirst

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Ejse::getWeather | PEAR Manual | Services_Weather_Ejse::searchLocationByCountry


Services_Weather_Ejse::searchLocationByCountry

Services_Weather_Ejse::searchLocationByCountry

Services_Weather_Ejse::searchLocationByCountry() – EJSE offers no search function to date, so this function is disabled.

Synopsis

require_once '/Weather/Ejse.php';

bool Services_Weather_Ejse::searchLocationByCountry ( string $country = null )

Description

Maybe this is the place to interface to some online postcode service...

Parameter

string $country

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Ejse::searchLocation | PEAR Manual | Class Summary Services_Weather_Globalweather


Class Summary Services_Weather_Globalweather

Class Summary Services_Weather_Globalweather

Class Summary Services_Weather_Globalweather – PEAR::Services_Weather_Globalweather

PEAR::Services_Weather_Globalweather

This class acts as an interface to the soap service of capescience.com. It searches for given locations and retrieves current weather data.

GlobalWeather is a SOAP frontend for METAR data, provided by CapeScience. If you want to use METAR, you should try this class first, as it is much more comfortable (and also a bit faster) than the native METAR-class provided by this package.

For a working example, please take a look at docs/Services_Weather/examples/globalweather-basic.php

Class Trees for Services_Weather_Globalweather

  • Services_Weather_Common

    • Services_Weather_Globalweather

Services_Weather_Globalweather Inherited Methods

Inherited from Services_Weather_Common
Method Name | Summary
Services_Weather_Common::calculateDewPoint() | Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateHumidity() | Calculate humidity from temperature and dewpoint This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateWindChill() | Calculate windchill from temperature and windspeed (enhanced formula)
Services_Weather_Common::convertDistance() | Convert distance between km, ft and sm
Services_Weather_Common::convertPressure() | Convert pressure between in, hpa, mb, mm and atm
Services_Weather_Common::convertSpeed() | Convert speed between mph, kmh, kt, mps and fps
Services_Weather_Common::convertTemperature() | Convert temperature between f and c
Services_Weather_Common::getUnitsFormat() | Returns the selected units format
Services_Weather_Common::polar2cartesian() | Convert polar coordinates to cartesian coordinates
Services_Weather_Common::setCache() | Enables caching the data, usage strongly recommended
Services_Weather_Common::setDateTimeFormat() | Changes the representation of time and dates (see http://www.php.net/date)
Services_Weather_Common::setHttpTimeout() | Sets the timeout in seconds for HTTP requests
Services_Weather_Common::setUnitsFormat() | Changes the representation of the units (standard/metric)
Prev | Services_Weather | Next
Services_Weather_Ejse::searchLocationByCountry | PEAR Manual | Services_Weather_Globalweather::getForecast


Services_Weather_Globalweather::getForecast

Services_Weather_Globalweather::getForecast

Services_Weather_Globalweather::getForecast() – GlobalWeather has no forecast per se, so this function is just for compatibility purposes.

Synopsis

require_once '/Weather/Globalweather.php';

bool Services_Weather_Globalweather::getForecast ( mixed $id = null , int $days = null , string $unitsFormat = null , string $int )

Description

This package is not documented yet.

Parameter

mixed $id

integer $days

string $unitsFormat

string $int

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Class Summary Services_Weather_Globalweather | PEAR Manual | Services_Weather_Globalweather::getLocation


Services_Weather_Globalweather::getLocation

Services_Weather_Globalweather::getLocation

Services_Weather_Globalweather::getLocation() – Returns the data for the location belonging to the ID

Synopsis

require_once '/Weather/Globalweather.php';

PEAR_Error|array Services_Weather_Globalweather::getLocation ( string $id = "" )

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Globalweather::getForecast | PEAR Manual | Services_Weather_Globalweather::getUnits


Services_Weather_Globalweather::getUnits

Services_Weather_Globalweather::getUnits

Services_Weather_Globalweather::getUnits() – Returns the units for the current query

Synopsis

require_once '/Weather/Globalweather.php';

array Services_Weather_Globalweather::getUnits ( string $id = null , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Globalweather::getLocation | PEAR Manual | Services_Weather_Globalweather::getWeather


Services_Weather_Globalweather::getWeather

Services_Weather_Globalweather::getWeather

Services_Weather_Globalweather::getWeather() – Returns the weather-data for the supplied location

Synopsis

require_once '/Weather/Globalweather.php';

PEAR_Error|array Services_Weather_Globalweather::getWeather ( string $id = "" , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Globalweather::getUnits | PEAR Manual | Services_Weather_Globalweather::searchLocation


Services_Weather_Globalweather::searchLocation

Services_Weather_Globalweather::searchLocation

Services_Weather_Globalweather::searchLocation() – Searches IDs for given location, returns array of possible locations or single ID

Synopsis

require_once '/Weather/Globalweather.php';

PEAR_Error|array|string Services_Weather_Globalweather::searchLocation ( string $location , bool $useFirst = false )

Description

This package is not documented yet.

Parameter

string $location

boolean $useFirst

If set, first ID of result-array is returned

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_WRONG_SERVER_DATA

throws PEAR_Error::SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Globalweather::getWeather | PEAR Manual | Services_Weather_Globalweather::searchLocationByCountry


Services_Weather_Globalweather::searchLocationByCountry

Services_Weather_Globalweather::searchLocationByCountry

Services_Weather_Globalweather::searchLocationByCountry() – Returns IDs with location-name for a given country or all available countries, if no value was given

Synopsis

require_once '/Weather/Globalweather.php';

PEAR_Error|array Services_Weather_Globalweather::searchLocationByCountry ( string $country = "" )

Description

This package is not documented yet.

Parameter

string $country

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_WRONG_SERVER_DATA

throws PEAR_Error::SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Globalweather::searchLocation | PEAR Manual | Class Summary Services_Weather_Metar


Class Summary Services_Weather_Metar

Class Summary Services_Weather_Metar

Class Summary Services_Weather_Metar – PEAR::Services_Weather_Metar

PEAR::Services_Weather_Metar

This class acts as an interface to the metar service of weather.noaa.gov. It searches for locations given in ICAO notation and retrieves the current weather data.

Of course the parsing of the METAR-data has its limitations, as it follows the Federal Meteorological Handbook No.1 with modifications to accommodate for non-US reports, so if the report deviates from these standards, you won't get it parsed correctly. Anything that is not parsed, is saved in the "noparse" array-entry, returned by getWeather(), so you can do your own parsing afterwards. This limitation is specifically given for remarks, as the class is not processing everything mentioned there, but you will get the most common fields like precipitation and temperature-changes. Again, everything not parsed, goes into "noparse".

If you think, some important field is missing or not correctly parsed, please file a feature-request/bugreport at http://pear.php.net/ and be sure to provide the METAR report with a _detailed_ explanation!

For a working example, please take a look at docs/Services_Weather/examples/metar-basic.php

Class Trees for Services_Weather_Metar

  • Services_Weather_Common

    • Services_Weather_Metar

Services_Weather_Metar Inherited Methods

Inherited from Services_Weather_Common
Method Name | Summary
Services_Weather_Common::calculateDewPoint() | Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateHumidity() | Calculate humidity from temperature and dewpoint This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateWindChill() | Calculate windchill from temperature and windspeed (enhanced formula)
Services_Weather_Common::convertDistance() | Convert distance between km, ft and sm
Services_Weather_Common::convertPressure() | Convert pressure between in, hpa, mb, mm and atm
Services_Weather_Common::convertSpeed() | Convert speed between mph, kmh, kt, mps and fps
Services_Weather_Common::convertTemperature() | Convert temperature between f and c
Services_Weather_Common::getUnitsFormat() | Returns the selected units format
Services_Weather_Common::polar2cartesian() | Convert polar coordinates to cartesian coordinates
Services_Weather_Common::setCache() | Enables caching the data, usage strongly recommended
Services_Weather_Common::setDateTimeFormat() | Changes the representation of time and dates (see http://www.php.net/date)
Services_Weather_Common::setHttpTimeout() | Sets the timeout in seconds for HTTP requests
Services_Weather_Common::setUnitsFormat() | Changes the representation of the units (standard/metric)
Prev | Services_Weather | Next
Services_Weather_Globalweather::searchLocationByCountry | PEAR Manual | Services_Weather_Metar::getForecast


Services_Weather_Metar::getForecast

Services_Weather_Metar::getForecast

Services_Weather_Metar::getForecast() – METAR has no forecast per se, so this function is just for compatibility purposes.

Synopsis

require_once '/Weather/Metar.php';

bool Services_Weather_Metar::getForecast ( mixed $id = null , int $days = null , string $unitsFormat = null , string $int )

Description

This package is not documented yet.

Parameter

mixed $id

integer $days

string $unitsFormat

string $int

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Class Summary Services_Weather_Metar | PEAR Manual | Services_Weather_Metar::getLocation


Services_Weather_Metar::getLocation

Services_Weather_Metar::getLocation

Services_Weather_Metar::getLocation() – Returns the data for the location belonging to the ID

Synopsis

require_once '/Weather/Metar.php';

PEAR_Error|array Services_Weather_Metar::getLocation ( string $id = "" )

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::getForecast | PEAR Manual | Services_Weather_Metar::getUnits


Services_Weather_Metar::getUnits

Services_Weather_Metar::getUnits

Services_Weather_Metar::getUnits() – Returns the units for the current query

Synopsis

require_once '/Weather/Metar.php';

array Services_Weather_Metar::getUnits ( string $id = null , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::getLocation | PEAR Manual | Services_Weather_Metar::getWeather


Services_Weather_Metar::getWeather

Services_Weather_Metar::getWeather

Services_Weather_Metar::getWeather() – Returns the weather-data for the supplied location

Synopsis

require_once '/Weather/Metar.php';

PHP_Error|array Services_Weather_Metar::getWeather ( string $id = "" , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PHP_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::getUnits | PEAR Manual | Services_Weather_Metar::searchAirport


Services_Weather_Metar::searchAirport

Services_Weather_Metar::searchAirport

Services_Weather_Metar::searchAirport() – Searches the nearest airport(s) for given coordinates, returns array of IDs or single ID

Synopsis

require_once '/Weather/Metar.php';

PEAR_Error|array|string Services_Weather_Metar::searchAirport ( float $latitude , float $longitude , int $numResults = 1 )

Description

This package is not documented yet.

Parameter

float $latitude

float $longitude

integer $numResults

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION

throws PEAR_Error::SERVICES_WEATHER_ERROR_DB_NOT_CONNECTED

throws PEAR_Error::SERVICES_WEATHER_ERROR_INVALID_LOCATION

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::getWeather | PEAR Manual | Services_Weather_Metar::searchLocation


Services_Weather_Metar::searchLocation

Services_Weather_Metar::searchLocation

Services_Weather_Metar::searchLocation() – Searches IDs for given location, returns array of possible locations or single ID

Synopsis

require_once '/Weather/Metar.php';

PEAR_Error|array|string Services_Weather_Metar::searchLocation ( string|array $location , bool $useFirst = false )

Description

This package is not documented yet.

Parameter

string|array $location

boolean $useFirst

If set, first ID of result-array is returned

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION

throws PEAR_Error::SERVICES_WEATHER_ERROR_DB_NOT_CONNECTED

throws PEAR_Error::SERVICES_WEATHER_ERROR_INVALID_LOCATION

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::searchAirport | PEAR Manual | Services_Weather_Metar::searchLocationByCountry


Services_Weather_Metar::searchLocationByCountry

Services_Weather_Metar::searchLocationByCountry

Services_Weather_Metar::searchLocationByCountry() – Returns IDs with location-name for a given country or all available countries, if no value was given

Synopsis

require_once '/Weather/Metar.php';

PEAR_Error|array Services_Weather_Metar::searchLocationByCountry ( string $country = "" )

Description

This package is not documented yet.

Parameter

string $country

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION

throws PEAR_Error::SERVICES_WEATHER_ERROR_DB_NOT_CONNECTED

throws PEAR_Error::SERVICES_WEATHER_ERROR_WRONG_SERVER_DATA

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::searchLocation | PEAR Manual | Services_Weather_Metar::setMetarDB


Services_Weather_Metar::setMetarDB

Services_Weather_Metar::setMetarDB

Services_Weather_Metar::setMetarDB() – Sets the parameters needed for connecting to the DB, where the location- search is fetching its data from. You need to build a DB with the external tool buildMetarDB first, it fetches the locations and airports from a NOAA-website.

Synopsis

require_once '/Weather/Metar.php';

DB_Error|bool Services_Weather_Metar::setMetarDB ( string $dsn , array $dbOptions = array() )

Description

This package is not documented yet.

Parameter

string $dsn

array $dbOptions

See

see DB::parseDSN

Throws

throws DB_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::searchLocationByCountry | PEAR Manual | Services_Weather_Metar::setMetarSource


Services_Weather_Metar::setMetarSource

Services_Weather_Metar::setMetarSource

Services_Weather_Metar::setMetarSource() – Sets the source, where the class tries to locate the METAR data

Synopsis

require_once '/Weather/Metar.php';

void Services_Weather_Metar::setMetarSource ( string $source , string $sourcePath = "" )

Description

Source can be http, ftp or file. An alternate sourcepath can be provided.

Parameter

string $source

string $sourcePath

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Metar::setMetarDB | PEAR Manual | Class Summary Services_Weather_Weatherdotcom


Class Summary Services_Weather_Weatherdotcom

Class Summary Services_Weather_Weatherdotcom

Class Summary Services_Weather_Weatherdotcom – PEAR::Services_Weather_Weatherdotcom

PEAR::Services_Weather_Weatherdotcom

This class acts as an interface to the xml service of weather.com. It searches for given locations and retrieves current weather data as well as forecast for up to 10 days.

For using the weather.com xml-service please visit http://www.weather.com/services/xmloap.html and follow the link to sign up, it's free! You will receive an email where to download the SDK with the needed images and guidelines how to publish live data from weather.com. Unfortunately the guidelines are a bit harsh, that's why there's no actual data-representation in this class, just the raw data. Also weather.com demands active caching, so I'd strongly recommend enabling the caching implemented in this class. It obeys to the times as written down in the guidelines.

For a working example, please take a look at docs/Services_Weather/examples/weather.com-basic.php

Class Trees for Services_Weather_Weatherdotcom

  • Services_Weather_Common

    • Services_Weather_Weatherdotcom

Services_Weather_Weatherdotcom Inherited Methods

Inherited from Services_Weather_Common
Method Name | Summary
Services_Weather_Common::calculateDewPoint() | Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateHumidity() | Calculate humidity from temperature and dewpoint This is only an approximation, there is no exact formula, this one here is called Magnus-Formula
Services_Weather_Common::calculateWindChill() | Calculate windchill from temperature and windspeed (enhanced formula)
Services_Weather_Common::convertDistance() | Convert distance between km, ft and sm
Services_Weather_Common::convertPressure() | Convert pressure between in, hpa, mb, mm and atm
Services_Weather_Common::convertSpeed() | Convert speed between mph, kmh, kt, mps and fps
Services_Weather_Common::convertTemperature() | Convert temperature between f and c
Services_Weather_Common::getUnitsFormat() | Returns the selected units format
Services_Weather_Common::polar2cartesian() | Convert polar coordinates to cartesian coordinates
Services_Weather_Common::setCache() | Enables caching the data, usage strongly recommended
Services_Weather_Common::setDateTimeFormat() | Changes the representation of time and dates (see http://www.php.net/date)
Services_Weather_Common::setHttpTimeout() | Sets the timeout in seconds for HTTP requests
Services_Weather_Common::setUnitsFormat() | Changes the representation of the units (standard/metric)
Prev | Services_Weather | Next
Services_Weather_Metar::setMetarSource | PEAR Manual | Services_Weather_Weatherdotcom::getForecast


Services_Weather_Weatherdotcom::getForecast

Services_Weather_Weatherdotcom::getForecast

Services_Weather_Weatherdotcom::getForecast() – Get the forecast for the next days

Synopsis

require_once '/Weather/Weatherdotcom.php';

PEAR_Error|array Services_Weather_Weatherdotcom::getForecast ( string $id = "" , int $days = 2 , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

integer $days

Values between 1 and 10

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Class Summary Services_Weather_Weatherdotcom | PEAR Manual | Services_Weather_Weatherdotcom::getLocation


Services_Weather_Weatherdotcom::getLocation

Services_Weather_Weatherdotcom::getLocation

Services_Weather_Weatherdotcom::getLocation() – Returns the data for the location belonging to the ID

Synopsis

require_once '/Weather/Weatherdotcom.php';

PEAR_Error|array Services_Weather_Weatherdotcom::getLocation ( string $id = "" )

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::getForecast | PEAR Manual | Services_Weather_Weatherdotcom::getUnits


Services_Weather_Weatherdotcom::getUnits

Services_Weather_Weatherdotcom::getUnits

Services_Weather_Weatherdotcom::getUnits() – Returns the units for the current query

Synopsis

require_once '/Weather/Weatherdotcom.php';

array Services_Weather_Weatherdotcom::getUnits ( string $id = null , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::getLocation | PEAR Manual | Services_Weather_Weatherdotcom::getWeather


Services_Weather_Weatherdotcom::getWeather

Services_Weather_Weatherdotcom::getWeather

Services_Weather_Weatherdotcom::getWeather() – Returns the weather-data for the supplied location

Synopsis

require_once '/Weather/Weatherdotcom.php';

PEAR_Error|array Services_Weather_Weatherdotcom::getWeather ( string $id = "" , string $unitsFormat = "" )

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::getUnits | PEAR Manual | Services_Weather_Weatherdotcom::searchLocation


Services_Weather_Weatherdotcom::searchLocation

Services_Weather_Weatherdotcom::searchLocation

Services_Weather_Weatherdotcom::searchLocation() – Searches IDs for given location, returns array of possible locations or single ID

Synopsis

require_once '/Weather/Weatherdotcom.php';

PEAR_Error|array|string Services_Weather_Weatherdotcom::searchLocation ( string $location , bool $useFirst = false )

Description

This package is not documented yet.

Parameter

string $location

boolean $useFirst

If set, first ID of result-array is returned

Throws

throws PEAR_Error::SERVICES_WEATHER_ERROR_WRONG_SERVER_DATA

throws PEAR_Error::SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::getWeather | PEAR Manual | Services_Weather_Weatherdotcom::searchLocationByCountry


Services_Weather_Weatherdotcom::searchLocationByCountry

Services_Weather_Weatherdotcom::searchLocationByCountry

Services_Weather_Weatherdotcom::searchLocationByCountry() – Returns only false, as weather.com offers no country listing via its XML services

Synopsis

require_once '/Weather/Weatherdotcom.php';

bool Services_Weather_Weatherdotcom::searchLocationByCountry ( string $country = "" )

Description

This package is not documented yet.

Parameter

string $country

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::searchLocation | PEAR Manual | Services_Weather_Weatherdotcom::setAccountData


Services_Weather_Weatherdotcom::setAccountData

Services_Weather_Weatherdotcom::setAccountData

Services_Weather_Weatherdotcom::setAccountData() – Sets the necessary account-information for weather.com, you'll receive them after registering for the XML-stream

Synopsis

require_once '/Weather/Weatherdotcom.php';

void Services_Weather_Weatherdotcom::setAccountData ( string $partnerID , string $licenseKey )

Description

This package is not documented yet.

Parameter

string $partnerID

string $licenseKey

Throws

No exceptions thrown.

Note

This function can not be called statically.

Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::searchLocationByCountry | PEAR Manual | Package Services_Weather Constants


Package Services_Weather Constants

Package Services_Weather Constants

Package Services_Weather Constants – Constants defined in and used by Services_Weather

All Constants

Constants defined in Weather.php

Constants defined in Weather.php
Name | Value | Line Number
SERVICES_WEATHER_ERROR_CACHE_INIT_FAILED | 13 | 41
SERVICES_WEATHER_ERROR_DB_NOT_CONNECTED | 14 | 42
SERVICES_WEATHER_ERROR_INVALID_LICENSE_KEY | 102 | 51
SERVICES_WEATHER_ERROR_INVALID_LOCATION | 2 | 48
SERVICES_WEATHER_ERROR_INVALID_PARTNER_ID | 100 | 49
SERVICES_WEATHER_ERROR_INVALID_PRODUCT_CODE | 101 | 50
SERVICES_WEATHER_ERROR_NO_LOCATION | 1 | 47
SERVICES_WEATHER_ERROR_SERVICE_NOT_FOUND | 10 | 38
SERVICES_WEATHER_ERROR_UNKNOWN_ERROR |  | 46
SERVICES_WEATHER_ERROR_UNKNOWN_LOCATION | 11 | 39
SERVICES_WEATHER_ERROR_WRONG_SERVER_DATA | 12 | 40
SERVICES_WEATHER_EXPIRES_FORECAST | 7200 | 33
SERVICES_WEATHER_EXPIRES_LINKS | 43200 | 34
SERVICES_WEATHER_EXPIRES_LOCATION | 900 | 31
SERVICES_WEATHER_EXPIRES_UNITS | 900 | 30
SERVICES_WEATHER_EXPIRES_WEATHER | 1800 | 32

Constants defined in WeatherCommon.php

Constants defined in WeatherCommon.php
Name | Value | Line Number
SERVICES_WEATHER_RADIUS_EARTH | 6378.15 | 32
Prev | Services_Weather | Next
Services_Weather_Weatherdotcom::setAccountData | PEAR Manual | Services_Yahoo


Services_Yahoo

Services_Yahoo

Interface to the Yahoo! Search API.

The package provides an object oriented model to communicate with Yahoo's services via their REST-based XML interface.

Table of Contents
  • Introduction -- Introduction to Services_Yahoo
  • Examples -- Using Services_Yahoo
  • Design -- Services_Yahoo's design
Prev | Web Services | Next
Package Services_Weather Constants | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Services_Yahoo

Overview

The package provides an object oriented model to communicate with Yahoo's web services via their REST-based XML interface.

Currently the package only supports the Yahoo! Search Web Services, which is natural because Yahoo! does not expose other services via their API at the moment. Due to the modular layout of the package it is easy to add support for other services at a later point though. More information about the design of the package is available in a separate section.

Setup

Requirements

Services_Yahoo requires PHP 5 and a bunch of PEAR packages. For a complete list of dependencies please see the download page.

Installation

The Services_Yahoo package can be installed using the PEAR installer command pear install Services_Yahoo. If the installation fails due to missing dependencies, one either needs to install them manually or can make the installer fetch all dependencies automatically: pear install -a Services_Yahoo.

Alternative installation methods for situations where one has no access to the pear installer command can be found in the general installation chapter.

Uninstallation

Uninstalling the package can be done with pear uninstall Services_Yahoo.

Prev | Services_Yahoo | Next
Services_Yahoo | PEAR Manual | Examples


Examples

Examples

Examples – Using Services_Yahoo

About the examples

The following sections provide you with examples of using the different feature sets of Services_Yahoo. Currently this includes documentation for the interfaces to Yahoo! Search and Content Analysis.

All public methods in Services_Yahoo have in common that exceptions will be raised when something goes wrong. This is why try { ... } catch { } blocks are wrapped around all examples.

Note: The examples are designed to be run from a command line shell. If you would like to test them in a web browser you should replace \n with <br /> for better readability.

Speaking to Yahoo! Search

The following examples will communicate with Yahoo! Search.

Web search: Listing results

This snippet issues a search query for the term Steve Fossett to Yahoo! Search. For each result in the returned result set the title is printed.

<?php
require_once "Services/Yahoo/Search.php";

try {
    $client = Services_Yahoo_Search::factory("web");
    $results = $client->searchFor("Steve Fossett");

    echo "Number of results: " . $results->getTotalResultsReturned() . "\n\n";

    foreach ($results as $result) {
        echo $result['Title'] . "\n";
    }

} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

By default 10 results are returned per request. This number can be modified using the method setResultNumber():

<?php
require_once "Services/Yahoo/Search.php";

try {
    $client = Services_Yahoo_Search::factory("web");

    // Get 20 results per query
    $results = $client->withResults(20)->searchFor("Steve Fossett");

    /* ... */
?>

Web search: Result details

This code again queries Yahoo! Search for Steve Fossett, but this time the details of the first result in the result set are printed.

<?php
require_once "Services/Yahoo/Search.php";

try {
    $client = Services_Yahoo_Search::factory("web");
    $results = $client->searchFor("Steve Fossett");

    if ($results->getTotalResultsReturned() > 0) {
        $info = $results->current();

        echo "Title: " . $info['Title'] . "\n";
        echo "Summary: " . $info['Summary'] . "\n";
        echo "URL: " . $info['Url'] . "\n";
        echo "clickable URL: " . $info['ClickUrl'] . "\n";
        echo "Modification date: " . $info['ModificationDate'] . "\n";
        echo "Mime type: " . $info['MimeType'] . "\n";
    }

} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

Web search: Paginating results

In this example the "paginating" capabilities of Services_Yahoo are shown. Paginating means that the search results are split up into chunks of e.g. 20, which are displayed together with links to jump back and forth to other result chunks. Basically this mimicks the functionality from the bottom of official Yahoo Search Page.

TBD

Note: In order to query the Image, News, Video or Local search, one only needs to replace the argument "web" in the call of the factory() method with one of "image", "news", "video", or "local".

Using the Yahoo! Content Analysis services

The following examples will show you how to use the Content Analysis Services provided by Yahoo!.

Term Extraction Service

The Term Extraction service provides a list of significant words or phrases extracted from a larger content.

<?php
require_once "Services/Yahoo/ContentAnalysis.php";

try {
    $search = Services_Yahoo_ContentAnalysis::factory("termExtraction");
    $search->setContext("Italian sculptors and painters of the "
        . "renaissance favored the Virgin Mary for inspiration.");
    $search->setQuery("madonna");

    $results = $search->submit();

    foreach ($results as $result) {
        echo $result . "\n";
    }

} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>

It is possible to skip the call to setQuery(). The parameter set by this method is intended to help the engine with the extraction process, but it is not stricly required.

Spelling Suggestion Service

The Spelling Suggestion service provides a suggested spelling correction for a given term.

The following code queries Yahoo for a spelling suggestion for the term "madnna". The service will return exactly one result, but currently there is no way to avoid looping through the $results.

<?php
require_once "Services/Yahoo/ContentAnalysis.php";

try {
    $search = Services_Yahoo_ContentAnalysis::factory("spellingSuggestion");
    $search->setQuery("madnna");

    $results = $search->submit();

    foreach ($results as $result) {
        echo $result . "\n";
    }
} catch (Services_Yahoo_Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";

    foreach ($e->getErrors() as $error) {
        echo "* " . $error . "\n";
    }
}
?>
Prev | Services_Yahoo | Next
Introduction | PEAR Manual | Design


Design

Design

Design – Services_Yahoo's design

Overview

Services_Yahoo is split up into chunks that group similar functionality. Currently there are chunks for the interfaces to Yahoo Search and to the Content Analysis functions.

Each chunk basically contains two top-level element in the source tree: A .php file and a directory that holds the implementation of the chunk. The file is a class that contains only one method which implements that factory pattern. This method dynamically loads the right file from the related directory and returns an instance of the class that implements the desired function.

Due to this modular layout Services_Yahoo can easily be extended when Yahoo adds new functions to their API.

More information

If you would like to study the code of the package, you can do so by either downloading a release from the package homepage or by browsing the code in CVS.

Also the automatically generated API documentation should help you.

Prev | Services_Yahoo | Next
Examples | PEAR Manual | Services_YouTube


Services_YouTube

Services_YouTube

Object-oriented abstraction for YouTube API.

Table of Contents
  • Introduction -- Introduction to Services_YouTube
  • Example -- Basic examples of Services_YouTube
Prev | Web Services | Next
Design | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to Services_YouTube

Introduction to Services_YouTube

Services_YouTube is an abstraction for the webservice of YouTube APIs. Using YouTube APIs, you can easily integrate online videos from YouTube's rapidly growing repository of videos into your application. To use YouTube API and this package, create a YouTube account and create a YouTube developer profile.

YouTube APIs currently allow read-only access to key parts of the YouTube video respository and user community. Services_YouTube provides functions for YouTube APIs using O-O abstraction access.

Prev | Services_YouTube | Next
Services_YouTube | PEAR Manual | Example


Example

Example

Example – Basic examples of Services_YouTube

Basic examples of Services_YouTube

The following examples show how to use some basic features of Services_YouTube:

Retrieves the public parts of a user profile.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$user_id = "USER_ID";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$user = $youtube->getProfile($user_id);
$profile = $user->user_profile;
print "{$profile->first_name} {$profile->last_name} :({$profile->video_watch_count} Watched.)\n";
?>

Lists a user's favorite videos.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$user_id = "USER_ID";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$videos = $youtube->listFavoriteVideos($user_id);
foreach ($videos->xpath('//video') as $i => $video) {
    print "<img src='{$video->thumbnail_url}' alt='{$video->title}' />\n";
    print "<a href='{$video->url}'>URL</a><br />\n";
}
?>

Lists a user's friends.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$user_id = "USER_ID";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$users = $youtube->listFriends($user_id);
foreach ($users->xpath('//friend') as $i => $friend) {
    print "{$friend->user} : Upload: {$friend->video_upload_count}";
}
?>

Lists all videos that have the specified tag.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$tag = "test";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$videos = $youtube->listByTag($tag);
foreach ($videos->xpath('//video') as $i => $video) {
    print "<img src='{$video->thumbnail_url}' alt='{$video->title}' />\n";
    print "<a href='{$video->url}'>URL</a><br />\n";
}
?>

Lists all videos that were uploaded by the specified user.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$user_id = "USER_ID";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$videos = $youtube->listByUser($user_id);
foreach ($videos->xpath('//video') as $i => $video) {
    print "<img src='{$video->thumbnail_url}' alt='{$video->title}' />\n";
    print "<a href='{$video->url}'>URL</a><br />\n";
}
?>

Lists the most recent 25 videos that have been featured on the front page of the YouTube site.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$videos = $youtube->listFeatured();
foreach ($videos->xpath('//video') as $i => $video) {
    print "<img src='{$video->thumbnail_url}' alt='{$video->title}' />\n";
    print "<a href='{$video->url}'>URL</a><br />\n";
}
?>

Displays the details for a video.

<?php
require_once 'Services/YouTube.php';

$dev_id = "YOUR_DEV_ID";
$video_id = "VIDEO_ID";
$youtube = new Services_YouTube($dev_id, array('useCache' => true));
$video = $youtube->getDetails($video_id);
$details = $video->video_details;
print "{$details->title} : ({$details->tags}) : RATE: {$details->rating_avg} in {$detials->rating_count}";
print "<img src='{$details->thumbnail_url}' alt={$details->title}><hr /><hr />";
foreach ($details->xpath('//comment') as $i => $comment) {
    print "{$comment->author} : {$comment->text}<hr />";
}
?>
Prev | Services_YouTube | Next
Introduction | PEAR Manual | UDDI


UDDI

UDDI

UDDI implementation for PHP

Table of Contents
  • Introduction -- UDDI implementation for PHP
Prev | Web Services | Next
Example | PEAR Manual | Introduction


Introduction

Introduction

Introduction – UDDI implementation for PHP

UDDI Description

Implementation of the Universal Description, Discovery and Integration API for locating and publishing Web Services listings in a UBR (UDDI Business Registry)

The full online documentation is available here

Prev | UDDI | Next
UDDI | PEAR Manual | XML_RPC


XML_RPC

XML_RPC

PHP implementation of the XML-RPC protocol.

This is a PEAR-ified version of Useful inc's XML-RPC for PHP. It has support for HTTP transport, proxies and authentication.

Table of Contents
  • Introduction
  • Support -- Getting support for XML_RPC
  • Examples -- Usage examples for the XML_RPC package
  • API -- Class documentation of the package
Prev | Web Services | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction –

General introduction

XML-RPC is a format devised by Userland Software for achieving remote procedure call via XML. XML-RPC has its own web site, www.XmlRpc.com.

The most common implementations of XML-RPC available at the moment use HTTP as the transport. A list of implementations for other languages such as Perl and Python can be found on the www.xmlrpc.com.

This collection of PHP classes provides a framework for writing XML-RPC clients and servers in PHP.

Acknowledgements

This package has been orginially written by Edd Dumbill of Useful Information Company, so he deservers most of the credits. Apart from that following people have contributed to the initial codebase that is still being maintained by Edd:

  • Jim Winstead <jimw at php dot net>

  • Peter Kocks <peter.kocks at baygate dot com>

  • Nicolay Mausz <mausz at flying-dog dot com>

  • Ben Margolin <ben at wendy.auctionwatch dot com>

  • Dan Libby <dan at libby dot com>

  • Gaetano Giunta <g.giunta at libero dot it>

  • Idan Sofer <i_sofer at yahoo dot com>

  • Giancarlo Pinerolo <ping at alt dot it>

  • Justin Miller <justin at voxel dot net>

Manifest - Files in the package

Server.php

the XML-RPC server class. include() this to get server functionality.

RPC.php

the XML-RPC client classes. include() this to get client functionality.

Prev | XML_RPC | Next
XML_RPC | PEAR Manual | Support


Support

Support

Support – Getting support for XML_RPC

Online Support

The package is offered "as-is" without any warranty or commitment to support. However, informal advice and help is available via the PEAR user mailing list and XML-RPC.com.

  • The PEAR user mailing list can be contacted for questions concerning the usage of the package. More details can be found here.

  • For more general XML-RPC questions, there is a Yahoo! Groups XML-RPC mailing list.

  • The XML-RPC.com discussion group is a useful place to get help with using XML-RPC. This group is also gatewayed into the Yahoo! Groups mailing list.

The Jellyfish Book

Together with Simon St.Laurent and Joe Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates on XML-RPC. It features a rather fetching jellyfish on the cover.

Complete details of the book are available from O'Reilly's web site.

If you've benefitted from the effort he has put into writing this software, then please consider buying the book!

Prev | XML_RPC | Next
Introduction | PEAR Manual | Examples


Examples

Examples

Examples – Usage examples for the XML_RPC package

Using a Client to Get Info About the Latest PEAR Release

<?php
require_once 'XML/RPC.php';

/*
 * Get info about the most recently released PEAR package
 */
$params = array(new XML_RPC_Value(1, 'int'));
$msg = new XML_RPC_Message('release.getRecent', $params);

$cli = new XML_RPC_Client('/xmlrpc.php', 'pear.php.net');

// If you want to turn debugging on...
// $cli->setDebug(1);

// If your payload requires extra lines to stay in tact...
// NOTE: The $remove_extra_lines property was added in Version 1.4.6.
// $cli->remove_extra_lines = false;

// If inspect the XML request sent to the server...
// $msg->createPayload();
// logit($msg->payload);  // Hypothetical function.

$resp = $cli->send($msg);

if (!$resp) {
    echo 'Communication error: ' . $cli->errstr;
    exit;
}

if (!$resp->faultCode()) {
    $val = $resp->value();
    $data = XML_RPC_decode($val);
    echo $data[0]['name'] . ' is at version ' . $data[0]['version'];
} else {
    /*
     * Display problems that have been gracefully cought and
     * reported by the xmlrpc.php script
     */
    echo 'Fault Code: ' . $resp->faultCode() . "\n";
    echo 'Fault Reason: ' . $resp->faultString() . "\n";
}

// To inspect the XML response from the server...
// NOTE: The $response_payload property was added in Version 1.4.6.
// logit($msg->response_payload);  // Hypothetical function.
?>

A Complete Client and Server Combination

Here is the server script. It's named xmlrpc.php and located in the document root of the web server at localhost:

<?php
require_once 'XML/RPC/Server.php';

/*
 * Declare the functions, etc.
 */
function returnTimes2($params) {
    $obj = new some_class_name;
    return $obj->returnTimes2($params);
}

class some_class_name {
    function returnTimes2($params) {
        $param = $params->getParam(0);

        // This error checking syntax was added in Release 1.3.0
        if (!XML_RPC_Value::isValue($param)) {
            return $param;
        }

        $val = new XML_RPC_Value($param->scalarval() * 2, 'int');
        return new XML_RPC_Response($val);
    }
}

$some_object = new some_class_name;

/*
 * Establish the dispatch map and XML_RPC server instance.
 */
$server = new XML_RPC_Server(
    array(
        'function_times2' => array(
            'function' => 'returnTimes2'
        ),
        'class_paamayim_nekudotayim_times2' => array(
            'function' => 'some_class_name::returnTimes2'
        ),
        'class_times2' => array(
            'function' => array('some_class_name', 'returnTimes2')
        ),
        'object_times2' => array(
            'function' => array($some_object, 'returnTimes2')
        ),
    ),
    1  // serviceNow
);
?>

And here is the client script:

<?php
require_once 'XML/RPC.php';

$input = 8;
$params = array(new XML_RPC_Value($input, 'int'));
$msg = new XML_RPC_Message('function_times2', $params);

$cli = new XML_RPC_Client('/xmlrpc.php', 'localhost');
// $cli->setDebug(1);
$resp = $cli->send($msg);

if (!$resp) {
    echo 'Communication error: ' . $cli->errstr;
    exit;
}

if (!$resp->faultCode()) {
    $val = $resp->value();
    echo $input . ' times 2 is ' . $val->scalarval();
} else {
    /*
     * Display problems that have been gracefully cought and
     * reported by the xmlrpc.php script.
     */
    echo 'Fault Code: ' . $resp->faultCode() . "\n";
    echo 'Fault Reason: ' . $resp->faultString() . "\n";
}
?>

Automatically encoding data

The XML_RPC_encode() function automatically converts PHP data into the format needed by the XML_RPC library.

<?php
require_once 'XML/RPC.php';

$data = fetch_row_from_db();  //  Hypothetical example.

$params = array(XML_RPC_encode($data));
$msg = new XML_RPC_Message('some_function_name', $params);

$cli = new XML_RPC_Client('/xmlrpc.php', 'pear.php.net');
$resp = $cli->send($msg);

// Process the same way as the other examples...
?>
Prev | XML_RPC | Next
Support | PEAR Manual | API


API

API

API – Class documentation of the package

XML_RPC_Client

This is the basic class used to represent a client of an XML-RPC server.

Creation

The constructor has the following syntax:

$client = new XML_RPC_Client ( string $path , string $server , integer $port , string $proxy , integer $proxy_port , string $proxy_user , string $proxy_pass )

string $path

the path and name of the RPC server script you want the request to go to

string $server

the URL of the remote server to connect to. If this parameter doesn't specify a protocol and $port is 443, ssl:// is assumed.

integer $port

a port for connecting to the remote server. Defaults to 80 for http:// connections and 443 for https:// and ssl:// connections.

string $proxy

the URL of the proxy server to use, if any. If this parameter doesn't specify a protocol and $port is 443, ssl:// is assumed.

integer $proxy_port

a port for connecting to the remote server. Defaults to 8080 for http:// connections and 443 for https:// and ssl:// connections.

string $proxy_user

a user name for accessing the proxy server

string $proxy_pass

a password for accessing the proxy server

Note: In order to use SSL connections, your PHP installation must have the openssl extension enabled.

Here's an example client set up to query Userland's XML-RPC server at betty.userland.com:

<?php
$client = new XML_RPC_Client('/RPC2', 'betty.userland.com');
?>

Methods

This class supports the following methods.

send()

This method takes the form:

$response = $client->send ( $xmlrpc_message , $timeout )

Where $xmlrpc_message is an instance of XML_RPC_Message and $response is an instance of XML_RPC_Response (see API).

The $timeout is optional, and will be set to 0 (wait forever) if omitted. This timeout value is passed to fsockopen().

If the value of $response is 0 rather than an XML_RPC_Response object, then this signifies an I/O error has occured. You can find out what the I/O error was from the values $client->errno and $client->errstring.

In addition to low-level errors, the XML-RPC server you were querying may return an error in the XML_RPC_Response object. See API for details of how to handle these errors.

setCredentials()

$client->setCredentials ( $username , $password )

This method sets the username and password for authorizing the client to a server. With the default (HTTP) transport, this information is used for HTTP Basic authorization.

setDebug()

$client->setDebug ( $debugOn )

$debugOn is either 0 or 1 depending on whether you require the client to print debugging information to the browser. The default is not to output this information.

The debugging information includes the raw data returned from the XML-RPC server it was querying, and the PHP value the client attempts to create to represent the value returned by the server. This option can be very useful when debugging servers as it allows you to see exactly what the server returns.

XML_RPC_Message

This class provides a representation for a request to an XML-RPC server. A client sends an XML_RPC_Message to a server, and receives back an XML_RPC_Response.

Creation

The constructor takes the following form:

$msg = new XML_RPC_Message ( $methodName , $parameterArray )

Where $methodName is a string indicating the name of the method you wish to invoke, and $parameterArray is a simple Array of XML_RPC_Value objects. Here's an example message to the US state name server:

<?php
require_once "XML/RPC.php";
$msg = new XML_RPC_Message("examples.getStateName", array(new XML_RPC_Value(23, "int")));
?>

This example requests the name of state number 23. For more information on XML_RPC_Value objects, see API.

Methods

serialize()

$outString = $msg->serialize ( )

Returns the an XML string representing the XML-RPC message.

addParam()

$msg->addParam ( $xmlrpcVal )

Adds the XML_RPC_Value $xmlrpcVal to the parameter list for this method call.

Returns an XML_RPC_Value object. If the parameter doesn't exist, an XML_RPC_Response object is returned.

getParam()

$xmlrpcVal = $msg->getParam ( $n )

Gets the $n th parameter in the message. Use this method in server implementations. Returns the undef value if no such parameter exists.

getNumParams()

$n = $msg->getNumParams ( )

Returns the number of parameters attached to this message.

method()

$methName=$msg->method ( )

$msg->method ( $methName )

Gets or sets the method contained in the XML-RPC message.

parseResponse()

$response = $msg->parseResponse ( $xmlString )

Given an incoming XML-RPC server response contained in the string $xmlString , this method constructs an XML_RPC_Response response object and returns it, setting error codes as appropriate.

This method processes any HTTP/MIME headers it finds.

parseResponseFile()

$response = $msg->parseResponseFile ( $fileHandle )

Given an incoming XML-RPC server response on the file handle $fileHandle , this method reads the data and passes it to parseResponse().

This method is useful to construct responses from pre-prepared files. It processes any HTTP headers it finds.

XML_RPC_Response

This class is used to contain responses to XML-RPC requests. A server method handler will construct an XML_RPC_Response and pass it as a return value. This same value will be returned by the result of an invocation of the send() method of the XML_RPC_Client class.

Creation

$resp = new XML_RPC_Response ( $xmlrpcval )

$resp = new XML_RPC_Response ( 0 , $errcode , $errstring )

The first instance is used when execution has happened without difficulty: $xmlrpcval is an XML_RPC_Value value with the result of the method execution contained in it.

The second type of constructor is used in case of failure. $errcode and $errstring are used to provide indication of what has gone wrong. See API for more information on passing error codes.

Methods

faultCode()

$fn = $resp->faultCode ( )

Returns the integer fault code return from the XML-RPC response $resp . A zero value indicates success, any other value indicates a failure response.

faultString()

$fs = $resp->faultString ( )

Returns the human readable explanation of the fault indicated by $resp->faultCode.

value()

$xmlrpcVal = $resp->value ( )

Returns an XML_RPC_Value object containing the return value sent by the server. If the response's faultCode is non-zero then the value returned by this method should not be used (it may not even be an object).

serialize()

$outString = $resp->serialize ( )

Returns an XML string representation of the response.

XML_RPC_Value

This is where a lot of the hard work gets done. This class enables the creation and encapsulation of values for XML-RPC.

Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 before reading on as it will make things clearer.

The XML_RPC_Value class can store arbitrarily complicated values using the following types: i4, int, boolean, string, double, dateTime.iso8601, base64, array or struct. You should refer to the spec for more information on what each of these types mean.

Notes on types

int

The type i4 is accepted as a synonym for int. The value parsing code will always convert i4 to int: int is regarded by this implementation as the canonical name for this type.

base64

Base 64 encoding is performed transparently to the caller when using this type. Therefore you ought to consider it as a binary data type, for use when you want to pass none 7-bit clean data. Decoding is also transparent.

boolean

The values true and 1 map to true. All other values (including the empty string) are converted to false.

string

The characters <, >, " and & are converted to their entity equivalents &lt;, &gt;, &quot; and &amp; for transport through XML-RPC. The current XML-RPC spec recommends only encoding < and & but this implementation goes further, for reasons explained by the XML 1.0 recommendation.

Note: Currently, passing a string "-1" to XML_RPC_Value's constructor creates an empty result since it serves as a special/magic value.

TODO: &apos; entity is not yet supported

Creation

The constructor is the normal way to create an XML_RPC_Value. The constructor can take these forms:

$myVal = new XML_RPC_Value ( )

$myVal = new XML_RPC_Value ( $stringVal )

$myVal = new XML_RPC_Value ( $scalarVal , 'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64' )

$myVal = new XML_RPC_Value ( $arrayVal , 'array' | 'struct' )

The first constructor creates an empty value, which must be altered using the methods addScalar(), addArray() or addStruct() before it can be used.

The second constructor creates a simple string value.

The third constructor is used to create a scalar value. The second parameter must be a name of an XML-RPC type. Examples:

<?php
$myInt = new XML_RPC_Value(1267, "int");
$myString= new XML_RPC_Value("Hello, World!", "string");
$myBool = new XML_RPC_Value(1, "boolean");
?>

The fourth constructor form can be used to compose complex XML-RPC values. The first argument is either a simple array in the case of an XML-RPC array or an associative array in the case of a struct. The elements of the array must be XML_RPC_Value objects themselves. Examples:

$myArray = new XML_RPC_Value(array(
new XML_RPC_Value("Tom"), new XML_RPC_Value("Dick"),
new XML_RPC_Value("Harry")), "array");

$myStruct = new XML_RPC_Value(array(
"name" => new XML_RPC_Value("Tom"),
"age" => new XML_RPC_Value(34, "int"),
"geek" => new XML_RPC_Value(1, "boolean")), "struct");

Methods

addScalar()

$ok = $val->addScalar ( $stringVal )

$ok = $val->addScalar ( $scalarVal , 'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64' )

If $val is an empty XML_RPC_Value this method makes it a scalar value, and sets that value. If $val is already a scalar value, then no more scalars can be added and 0 is returned. If all went OK, 1 is returned.

There is a special case if $val is an array: the scalar value passedis appended to the array.

addArray()

$ok = $val->addArray ( $arrayVal )

Turns an empty XML_RPC_Value into an array with contents as specified by $arrayVal . See the fourth constructor form for more information.

addStruct()

$ok = $val->addStruct ( $assocArrayVal )

Turns an empty XML_RPC_Value into a struct with contents as specified by $assocArrayVal . See the fourth constructor form for more information.

kindOf()

$kind = $val->kindOf ( )

Returns a string containing struct, array or scalar describing the base type of the value. If it returns undef it means that the value hasn't been initialised.

serialize()

$outString = $val->serialize ( )

Returns a string containing the XML-RPC representation of this value.

scalarval()

$scalarVal = $val->scalarval ( )

If $val->kindOf() == 'scalar', this method returns the actual PHP-language value of the scalar (base 64 decoding is automatically handled here).

scalartyp()

$typeName = $val->scalartyp ( )

If $val->kindOf() == 'scalar', this method returns a string denoting the type of the scalar. As mentioned before, i4 is always coerced to int.

arraymem()

$xmlrpcVal = $val->arraymem ( $n )

Returns the $n th element in the array represented by the value $val . The value returned is an XML_RPC_Value object.

arraysize()

$len = $val->arraysize ( )

If $val is an array, returns the number of elements in that array.

structmem()

$xmlrpcVal = $val->structmem ( $memberName )

Returns the element called $memberName from the struct represented by the value $val . The value returned is an XML_RPC_Value object.

structeach()

list($key,$value) = $val->structeach ( )

Returns the next (key,value) pair from the struct, when $val is a struct. See also API.

structreset()

$val->structreset ( )

Resets the internal pointer for structeach() to the beginning of the struct, where $val is a struct.

XML_RPC_Server

The current implementation of this class has been kept as simple as possible. The constructor for the server basically does all the work. Here's a minimal example:

<?php
function foo ($params) {
   ...
}

$s = new XML_RPC_Server(array("examples.myFunc" => array("function" => "foo")));
?>

This performs everything you need to do with a server. The single argument is an associative array from method names to function names. The request is parsed and despatched to the relevant function, which is reponsible for returning a XML_RPC_Response object, which gets serialized back to the caller.

Here is a more detailed look at what the handler function foo() may do:

<?php
function foo ($params) {
    global $XML_RPC_erruser; // import user errcode value

    // $params is the received XML_RPC_Message object.
    if ($err) {
        // this is an error condition
        return new XML_RPC_Response(0, $XML_RPC_erruser+1, // user error 1
           "There's a problem, Captain");
    } else {
        // this is a successful value being returned
        return new XML_RPC_Response(new XML_RPC_Value("All's fine!", "string"));
    }
}
?>

The dispatch map

The first argument to the XML_RPC_Server() constructor is an array, called the dispatch map. In this array is the information the server needs to service the XML-RPC methods you define.

The dispatch map takes the form of an associative array of associative arrays: the outer array has one entry for each method, the key being the method name. The corresponding value is another associative array, which can have the following members:

  • function - this entry is mandatory. It must be a name of a function in the global scope which services the XML-RPC method.

    It is possible to use regular functions, class names with method names and objects with method names. The Examples page of this manual demonstrates the appropriate syntax for all of these approaches.

  • signature - this entry is an array containg the possible signatures (see API) for the method. If this entry is present then the server will check that the correct number and type of parameters have been sent for this method before dispatching it.

  • docstring - this entry is a string containing documentation for the method. The documentation may contain HTML markup.

Method signatures

A signature is a description of a method's return type and its parameter types. A method may have more than one signature.

Within a server's dispatch map, each method has an array of possible signatures. Each signature is an array of types. The first entry is the return type.

Let's run through an example. Imagine you wanted to write a regular PHP function like this:

<?php
function is_8($input, $strict = false) {
    if ($strict) {
       return ($input === 8);
    } else {
       return ($input == 8);
    }
}
?>

To get it to work in an XML_RPC server, you would have to write it like this:

<?php
function is_8($params) {
    // This parameter is required.
    $param = $params->getParam(0);
    if (!XML_RPC_Value::isValue($param)) {
        return $param;
    }
    $input = $param->scalarval();

    // This parameter is optional.
    $param = $params->getParam(1);
    if (!XML_RPC_Value::isValue($param)) {
        $strict = false;
    } else {
        $strict = $param->scalarval();
    }

    if ($strict) {
       $answer = ($input === 8);
    } else {
       $answer = ($input == 8);
    }

    $val = new XML_RPC_Value($answer, 'boolean');
    return new XML_RPC_Response($val);
}
?>

Here is a signature covering all of the possible permutations:

<?php
array(
    array('boolean', 'int'),
    array('boolean', 'int', 'boolean'),
    array('boolean', 'string'),
    array('boolean', 'string', 'boolean'),
)
?>

The server could be instatiated like this:

<?php
$server = new XML_RPC_Server(
    array(
        'isan8' =>
            array(
                'function' => 'is_8',
                'signature' =>
                     array(
                         array('boolean', 'int'),
                         array('boolean', 'int', 'boolean'),
                         array('boolean', 'string'),
                         array('boolean', 'string', 'boolean'),
                     ),
                'docstring' => 'Is the value an 8?'
            ),
    ),
    1,
    0
);
?>

The strings representing the XML-RPC types have been encoded as global variables for your convenience:

<?php
$GLOBALS['XML_RPC_I4']       = 'i4';
$GLOBALS['XML_RPC_Int']      = 'int';
$GLOBALS['XML_RPC_Boolean']  = 'boolean';
$GLOBALS['XML_RPC_Double']   = 'double';
$GLOBALS['XML_RPC_String']   = 'string';
$GLOBALS['XML_RPC_DateTime'] = 'dateTime.iso8601';
$GLOBALS['XML_RPC_Base64']   = 'base64';
$GLOBALS['XML_RPC_Array']    = 'array';
$GLOBALS['XML_RPC_Struct']   = 'struct';
?>

Delaying the server response

You may want to construct the server, but for some reason not fulfill the request immediately (security verification, for instance). If you pass the constructor a second argument of 0 this will have the desired effect. You can then use the service() method of the server class to service the request. For example:

<?php
$s = new XML_RPC_Server($myDispMap, 0);

// ... some code that does other stuff here

$s->service();
?>

Fault reporting

Fault codes for your servers should start at the value indicated by the global $xmlrpcerruser + 1.

Standard errors returned by the server include:

1 Unknown method

Returned if the server was asked to dispatch a method it didn't know about

2 Invalid return payload

This error is actually generated by the client, not server, code, but signifies that a server returned something it couldn't understand.

3 Incorrect parameters

This error is generated when the server has signature(s) defined for a method, and the parameters passed by the client do not match any of signatures.

4 Can't introspect: method unknown

This error is generated by the builtin system.*() methods when any kind of introspection is attempted on a method undefined by the server.

5 Didn't receive 200 OK from remote server

This error is generated by the client when a remote server doesn't return HTTP/1.1 200 OK in response to a request. A more detailed error report is added onto the end of the phrase above.

100- XML parse errors

Returns 100 plus the XML parser error code for the fault that occurred. The faultString returned explains where the parse error was in the incoming XML stream.

XML_RPC_Dump

This class generates string representations of the data in XML_RPC_Value objects.

Other Functions

Below are functions that lay outside the various XML_RPC objects.

XML_RPC_encode()

$rpc = XML_RPC_encode ( $php_val )

Takes native php types and encodes them into XML_RPC PHP object format.

XML_RPC_decode()

$values = XML_RPC_decode ( $XML_RPC_val )

Takes a message in PHP XML_RPC object format and translates it into native PHP types.

Prev | XML_RPC | Next
Examples | PEAR Manual | XML_RPC2


XML_RPC2

XML_RPC2

PHP5 implementation of the XML-RPC protocol.

This is a "PHP5 only" implementation of the XMLRPC protocol. This package provides the client and the server side of the protocol. An optimized cache is also available for both parts.

As a client library, XML_RPC2 is capable of creating a proxy class which exposes the methods exported by the server. As a server library, XML_RPC2 is capable of exposing methods from a class or object instance, seamlessly exporting local methods as remotely callable procedures.

Table of Contents
  • Introduction
  • Client Side
  • Server Side
  • Client Side with cache
  • Server Side with cache
Prev | Web Services | Next
API | PEAR Manual | Introduction


Introduction

Introduction

Introduction –

Description

XML_RPC2 is a "PHP5 only" implementation of the XMLRPC protocol. This package provides the client and the server side of the protocol. An optimized cache is also available for both parts.

As a client library, XML_RPC2 is capable of creating a proxy class which exposes the methods exported by the server. So it's very easy and natural to call XMLRPC exported methods. Like in Python language, the classic way to use XML_RPC2 client side is :

  • We make a XML_RCP2_Client object with server informations as arguments.

  • In a classic way, we call a method of this object.

  • Then, the method call is XMLRPC encoded, sent to the server, the response is decoded into PHP native types and we get the result of the call (all this logic is made by the library in a completely transparent way).

As a server library, XML_RPC2 is capable of exposing methods from a class or object instance, seamlessly capable of exposing methods from a class or object instance, seamlessly exporting local methods as remotely callable procedures. Method signatures are automatically determined and checked by using the reflection API and PHPDOC comments. An automatic documentation about XMLRPC exported methods is dynamically built and available at the server URL (with a simple HTTP GET).

For both sides, an optimized cache based on Cache_Lite can be set. It can be really usefull especially on public XMLRPC servers.

Requirements

XML_RCP2 need PHP5 and the CURL extension. To avoid in next version, the CURL dependency, we are waiting for a PHP5 E_STRICT PEAR module for HTTP_Request.

If you want to use the integrated cache, you will also need the Cache_Lite PEAR module but it's of course an optional dependency.

XML_RPC2 can use two backends for the XMLRPC encoding/decoding :

  • XMLRPCEXT, which of course need this PHP extension (probably the better choice but it's an additional dependency) ;

  • PHP, which doesn't need the XMLRPCEXT extension at all (this is full PHP but slower).

A first example of the client side use

Let's start with a XMLRPC call to the pear.php.net XMLRPC server :

<?php

require_once 'XML/RPC2/Client.php';

$options = array(
    'prefix' => 'package.'
);

// We make the XML_RPC2_Client object (as the backend is not specified, XMLRPCEXT
// will be used if available (full PHP else))
$client = XML_RPC2_Client::create('http://pear.php.net/xmlrpc.php', $options);

try {

    // Because of the prefix specified in the $options array, indeed,  we will call
    // the package.info() method with a single argument (the string 'XML_RPC2')
    $result = $client->info('XML_RPC2');

    // $result is a complex PHP type (no XMLRPC decoding needed, it's already done)
    print_r($result);

} catch (XML_RPC2_FaultException $e) {

    // The XMLRPC server returns a XMLRPC error
    die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());

} catch (Exception $e) {

    // Other errors (HTTP or networking problems...)
    die('Exception : ' . $e->getMessage());

}

?>

A first example of the server side use

Let's build a XMLRPC "echo server" :

<?php

require_once 'XML/RPC2/Server.php';

// Let's define a class with public static methods
// PHPDOC comments are really important because they are used for automatic
// signature checking

class EchoServer {

    /**
     * echoes the message received
     *
     * @param string  Message
     * @return string The echo
     */
    public static function echoecho($string) {
        return $string;
    }

}

$options = array(
    'prefix' => 'test.' // we define a sort of "namespace" for the server
);

// Let's build the server object with the name of the Echo class
$server = XML_RPC2_Server::create('EchoServer', $options);
$server->handleCall();

?>

If you do a simple HTTP GET on the server URL, you will get an automatic HTML documentation about the echoecho function. If you make a XMLRPC client request on the same URL about the "test.echoecho()" method (with one argument), you will get your argument as a response. If you call another method or with a bad arguments number, you will get an error (because of automatic method signature checking).

A first example of the client side use (with integrated cache)

As the caching process is completely transparent, this is very similar to the standard client side use :

<?php

require_once 'XML/RPC2/CachedClient.php';

$options = array(
    'prefix' => 'package.',
    'cacheDebug' => false, // with cacheDebug set to true, it's very easy
                           // to get an indication about the cache using (or not)
    'cacheOptions' => array(
        'cacheDir' => '/tmp/',
        'lifetime' => 3600,      // during this lifetime, the local cache will be used
        'cacheByDefault' => true // all methods call will be cached
                                 // (but a more precise way is possible)
    )
);

// We make the XML_RPC2_CachedClient object (same syntax than XML_RPC2_Client)
$client = XML_RPC2_CachedClient::create('http://pear.php.net/xmlrpc.php', $options);

try {

    // First call, the cache won't be used
    $result = $client->info('XML_RPC2');
    print_r($result);

    // Second call, the cache will be used  (in a transparent way) and no
    // additional HTTP request will be sent to the server
    $result = $client->info('XML_RPC2');
    print_r($result);

} catch (XML_RPC2_FaultException $e) {

    // The XMLRPC server returns a XMLRPC error
    die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());

} catch (Exception $e) {

    // Other errors (HTTP or networking problems...)
    die('Exception : ' . $e->getMessage());

}

?>

A first example of the server side use (with integrated cache)

As the caching process is completely transparent, this is very similar to the standard server side use :

<?php

require_once 'XML/RPC2/CachedServer.php';

// Let's define a class with public static methods
// PHPDOC comments are really important because they are used for automatic
// signature checking

// IMPORTANT : note the @xmlrpc.caching PHPDOC tags to indicate
// that the method has to be cached

class EchoServer {

    /**
     * echoes the message received
     *
     * @param string  Message
     * @return string The echo
     * @xmlrpc.caching true
     */
    public static function echoecho($string) {
        return $string;
    }

}

$options = array(
    'prefix' => 'test..',
    'cacheDebug' => false, // with cacheDebug set to true, it's very easy
                           // to get an indication about the cache using (or not)
    'cacheOptions' => array(
        'cacheDir' => '/tmp/',
        'lifetime' => 3600,
        'cacheByDefault' => false // we don't cache by default (only methods with @xmlrpc.caching true)
    )
);

$server = XML_RPC2_CachedServer::create('EchoServer', $options);
$server->handleCall();

?>
Prev | XML_RPC2 | Next
XML_RPC2 | PEAR Manual | Client Side


Client Side

Client Side

Client Side –

Introduction about the XML_RPC2 client side usage

Thanks to PHP5, it's really easy to do XMLRPC client requests with XML_RPC2. The usage is really straightforward.

First, you include 'XML/RPC2/Client.php' file (only this one).

<?php
require_once 'XML/RPC2/Client.php';
?>

Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...).

<?php
$options = array(
    'prefix' => 'package.'
);
?>

Third, you make a XML_RPC2_Client object with the server URL and the with the options array.

<?php
$client = XML_RPC2_Client::create('http://pear.php.net/xmlrpc.php', $options);
?>

Then, you send your request by calling the server method as it was a local method of the $client object.

<?php
$result = $client->info('XML_RPC2');
?>

This single line will encode a XMLRPC client request for the package.info() (prefix + method name) method with a single argument (the string 'XML_RPC2'), will send the request over HTTP to the server and will decode the response into PHP native types. With a single line !

Of course, to catch server errors, you have to add a few lines around you client call like for example :

<?php
try {
    $result = $client->info('XML_RPC2');
    print_r($result);
} catch (XML_RPC2_FaultException $e) {
    // The XMLRPC server returns a XMLRPC error
    die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());
} catch (Exception $e) {
    // Other errors (HTTP or networking problems...)
    die('Exception : ' . $e->getMessage());
}
?>

The options array

This array is completely optional but really usefull. The following keys are available :

Options available keys
Option | Data Type | Default Value | Description
prefix | string | '' | Prefix added before XMLRPC called method name
proxy | string | '' | Proxy used for the HTTP request (default : no proxy)
debug | boolean | FALSE | Debug mode ?
encoding | string | '' | Encoding of the request 'utf-8', 'iso-8859-1' (for now, only these two ones are officialy supported)
uglyStructHack | boolean | TRUE | ugly hack to circumvent a XMLRPCEXT bug/feature , see this PHP bug for more details. The only (reasonable) counterpart of this hack is that you can't use structs with a key beginning with the string 'xml_rpc2_ugly_struct_hack_' as arguments of the called method.

Making the XML_RPC2_Client object

It's really easy to make the XML_RPC2_Client object. Use the following syntax :

<?php
// $XMLRPCServerURL is a string : 'http://pear.php.net/xmlrpc.php' (for example)
// $options is an optional array : see previous section for more informations
$client = XML_RPC2_Client::create($XMLRPCServerURL, $options);
?>

Don't try to call the XML_RPC2_Client constructor directly, use the call() static method.

Call the XMLRPC exported method

When the XML_RPC2_Client object is created, you can directly call the remote method as it was local. For example :

<?php
// We call the remote foo() method without any arguments
$result1 = $client->foo();

// We call the remote bar() method with two arguments (an integer : 123, a string : 'foo')
$result2 = $client->bar(123, 'foo');

// We call the remote foobar() method with complex data types (2 integer, a string, a structure)
$result3 = $client->foobar(1, 2, 'foo', array('foo' => 1, 'bar' => 2));
?>

Be careful, XMLRPC spec allows some remote method names with some special characters like "." or "/"... which are not available as PHP method names. To deal with them, you have to fix a prefix in a the options array. For example :

<?php
$options = array('prefix' => 'foo.');
$client = XML_RPC2_Client::create('http://...', $options);

// We call the foo.bar() method because of the prefix 'foo.' fixed in $options array
$result = $client->bar();
?>

In most cases, XML_RPC2 transforms automatically PHP native types into XMLRPC types (as described in the SPEC) for the request. In most cases too, XML_RPC2 transforms the XML server response into PHP native types too. Yet, there are two exceptions : 'dateTime.iso8601' and 'base64' which doesn't really exist in PHP.

To manipulate explicitely these two types, you have to use special objects. Let's see a complete example :

<?php

// Classic usage
require_once 'XML/RPC2/Client.php';

// To manipulate these types, we need to include this file too
require_once 'XML/RPC2/Value.php';

// To get a 'dateTime.iso8601' object, you have first to set a string with an iso8601 encoded date :
$tmp = "20060116T19:14:03";

// Then, you call this static method to get your 'dateTime.iso8601' object
$time = XML_RPC2_Value::createFromNative($tmp, 'datetime');

// For 'base64', you call the same static method with your string to get a 'base64' object
$base64 = XML_RPC2_Value::createFromNative('foobar', 'base64');

// Then, you can use XML_RPC2_Client as usual :
$options = array('prefix' => 'validator1.');
$client = XML_RPC2_Client::create('http://phpxmlrpc.sourceforge.net/server.php', $options);
$result = $client->manyTypesTest(1, true, 'foo', 3.14159, $time, $base64);

// The remote validator1.manyTypesTest() method returns an array with the 6 given arguments
$result_datetime = $result[4]; // a 'dateTime.iso8601' object
$result_base64 = $result[5];   // a 'base64' object

// To transform these objects into PHP native types, you have to use public properties of
// these objects as follow :
var_dump($result_datetime->scalar);      // will return string(17) "20060116T19:14:03"
var_dump($result_datetime->xmlrpc_type); // will return string(8) "datetime"
var_dump($result_datetime->timestamp);   // will return int(1137435243)
var_dump($result_base64->scalar);        // will return string(6) "foobar"
var_dump($result_base64->xmlrpc_type);   // will return string(6) "base64"

?>
Prev | XML_RPC2 | Next
Introduction | PEAR Manual | Server Side


Server Side

Server Side

Server Side –

to be written

to be written

Prev | XML_RPC2 | Next
Client Side | PEAR Manual | Client Side with cache


Client Side with cache

Client Side with cache

Client Side with cache –

Introduction about the XML_RPC2 "cached client side" usage

Thanks to PHP5 and PEAR/Cache_Lite, it's really easy to do XMLRPC "cached client" requests with XML_RPC2. The usage is really straightforward.

First, you include 'XML/RPC2/CachedClient.php' file (only this one).

<?php
require_once 'XML/RPC2/CachedClient.php';
?>

Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...).

<?php
$options = array(
    'prefix' => 'package.',
    'cacheOptions' => array(
        'cacheDir' => '/tmp/',
        'lifetime' => 3600
    )
);
?>

Third, you make a XML_RPC2_CachedClient object with the server URL and the with the options array.

<?php
$client = XML_RPC2_CachedClient::create('http://pear.php.net/xmlrpc.php', $options);
?>

Then, you send your request by calling the server method as it was a local method of the $client object.

<?php
$result = $client->info('XML_RPC2');
?>

This single line will encode a XMLRPC client request for the package.info() (prefix + method name) method with a single argument (the string 'XML_RPC2'), will send the request over HTTP to the server and will decode the response into PHP native types. With a single line ! Moreover, the result will be cached into a file for the given lifetime. So the next call will not send any HTTP request and it will be really fast.

Of course, to catch server errors, you have to add a few lines around you client call like for example :

<?php
try {
    $result = $client->info('XML_RPC2');
    print_r($result);
} catch (XML_RPC2_FaultException $e) {
    // The XMLRPC server returns a XMLRPC error
    die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString());
} catch (Exception $e) {
    // Other errors (HTTP or networking problems...)
    die('Exception : ' . $e->getMessage());
}
?>

The options array

This array is completely optional but really usefull. The following keys are available :

Options available keys
Option | Data Type | Default Value | Description
[...] | [...] | [...] | See "non cached client side" for more options
cacheOptions | array | array() | See next table for a complete description

"CacheOptions" entry is an associative array. Available keys are :

CacheOptions available keys
Option | Data Type | Default Value | Description
[...] | [...] | [...] | See "Cache_Lite constructor" for more options
defaultCacheGroup | string | '' | Name of the default cache group
cachedMethods | array | array() | Array of method names to be cached (if cacheByDefault is false)
notCachedMethods | array | array() | Array of method names not to be cached (if cacheByDefault is true)
cacheByDefault | boolean | TRUE | if true, the cache is "on" by default ; else, only methods listed in cachedMethods will be cached

Making the XML_RPC2_CachedClient object

It's really easy to make the XML_RPC2_CachedClient object. Use the following syntax :

<?php
// $XMLRPCServerURL is a string : 'http://pear.php.net/xmlrpc.php' (for example)
// $options is an optional array : see previous section for more informations
$client = XML_RPC2_CachedClient::create($XMLRPCServerURL, $options);
?>

Don't try to call the XML_RPC2_CachedClient constructor directly, use the call() static method.

Call the XMLRPC exported method

See "non cached client side" documentation, there is no difference.

The caching process is completly embedded and automatic. If a cache is available, result will be get from cache and no HTTP request will be sent. If there is no cache available for this particular call (method name and arguments), the classical XMLRPC communication will be used (and the result will be stored into a cache file for the next use).

Prev | XML_RPC2 | Next
Server Side | PEAR Manual | Server Side with cache


Server Side with cache

Server Side with cache

Server Side with cache –

to be written

to be written

Prev | XML_RPC2 | Next
Client Side with cache | PEAR Manual | XML


XML

XML

Provides Packages for creating and working with XML

Table of Contents
  • XML_Beautifier
  • XML_DTD
  • XML_Feed_Parser
  • XML_Parser
  • XML_Query2XML
  • XML_RDDL
  • XML_RSS
  • XML_Serializer
  • XML_sql2xml
  • XML_Statistics
  • XML_Transformer
  • XML_Tree
  • XML_Util
Prev | PEAR Packages | Next
Server Side with cache | PEAR Manual | XML_Beautifier


XML_Beautifier

XML_Beautifier

Package to "beautify" XML documents. This package will add line breaks, indentation and other layout elements to an XML document, so it can be easier read by humans.

Table of Contents
  • Introduction -- Introduction to XML_Beautifier
  • Example -- Example for the usage of XML_Beautifier
  • Options -- List of all XML_Beautifier options
  • XML_Beautifier::XML_Beautifier -- create new instance
  • XML_Beautifier::setOption -- set an option
  • XML_Beautifier::setOptions -- set several options
  • XML_Beautifier::resetOptions -- reset options to default
  • XML_Beautifier::apiVersion -- return API version
  • XML_Beautifier::formatFile -- beautify a file
  • XML_Beautifier::formatString -- beautify a string
Prev | XML | Next
XML | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_Beautifier

Introduction to XML_Beautifier

XML_Beautifier is a package, that helps you making XML documents easier to read for human beings.

It is able to add line-breaks, indentation, sorts attributes, convert tag cases and wraps long comments. It recognizes tags, character data, comments, XML declarations, processing instructions and external entities and is able to format these tokens nicely.

The document is split into these tokens using the XML_Beautifier_Tokenizer class and the expat parser. Then a renderer is used to create the string representation of the document and formats it using the specified options.

Currently only one renderer is available, but as XML_Beautifier uses a driver-based architecture, other renderers (like syntax-highlighting) will follow soon.

Prev | XML_Beautifier | Next
XML_Beautifier | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_Beautifier

Basic example

Let's assume, you've got an XML document that is really badly formatted:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE page [
    <!ENTITY foo SYSTEM "foo.xml">
    <!ENTITY bar SYSTEM "bar.xml">
]>
<document title="Current News">
<meta project="none" foo="bar">
    <keywords/><description/>
<author>Stephan Schmidt</author>
<getMetaNav/>
</meta>
<page label="PHP Application Tools" sublabel="Current News">
<?php
    for($i = 0; $i < count($_GET); $i++) {
        echo    $_GET[$i]."<br>";
    }
?>
&foo;&bar;
<intro>
   <!-- This Comment
has more
    than one line.
                    -->
        <introtitle>Welcome to PHP
Application Tools &amp; PEAR!</introtitle>
<para>
        If you're new to pat, and would like
        <!-- This is a comment in a single line that contains an &amp; -->
         to know

         what we do

         here, take a look at

         <link url=
         "/about/project.xml">
         "About Pat"</link>
or
check out the
<link url="/about/projectsOverview.xml">"projects overview"</link>. Otherwise, you probably know your way
around
the site already <smiley type="smile"/>
</para>
                                            </intro>
</page>
</document>

All you have to do is to use XML_Beautifier, pass the filename of the original file and the filename for the new file:

<?php
require_once "XML/Beautifier.php";
$fmt = new XML_Beautifier();
$result = $fmt->formatFile('originalFile.xml', 'beautifiedFile.xml');

if (PEAR::isError($result)) {
    echo $result->getMessage();
    exit();
}
echo "File beautified, awaiting orders!<br />";
?>

And voila, your document looks nice:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE page [
    <!ENTITY foo SYSTEM "foo.xml">
    <!ENTITY bar SYSTEM "bar.xml">
]>
<document title="Current News">
    <meta foo="bar" project="none">
        <keywords />
        <description />
        <author>Stephan Schmidt</author>
        <getMetaNav />
    </meta>
    <page label="PHP Application Tools" sublabel="Current News">
        <?php
        for($i = 0; $i < count($_GET); $i++) {
                echo    $_GET[$i]."<br>";
            }
        ?>
        &foo;
        &bar;
        <intro>
            <!--
                This Comment
                has more
                than one line.
            -->
            <introtitle>Welcome to PHP Application Tools &amp; PEAR!</introtitle>
            <para>
                If you&apos;re new to pat, and would like
                <!-- This is a comment in a single line that contains an &amp; -->
                to know what we do here, take a look at
                <link url="/about/project.xml">&quot;About Pat&quot;</link>
                or check out the
                <link url="/about/projectsOverview.xml">&quot;projects overview&quot;</link>
                . Otherwise, you probably know your way around the site already
                <smiley type="smile" />
            </para>
        </intro>
    </page>
</document>
Prev | XML_Beautifier | Next
Introduction | PEAR Manual | Options


Options

Options

Options – List of all XML_Beautifier options

Introduction to options

Options let you influence the beautifiying process. They are passed to the renderer and thus, you have to check, whether the renderer you are using supports the options you want to use.

As there currently is only one renderer (Plain) available, you should not worry about this too much.

Options can be passed as an associative array to the constructor of XML_Beautifier. You may also use setOption(), or setOptions() to set one or more options after the instance of XML_Beautifier has been created.

All available options

Here is a list of all options supported by XML_Beautifier.

XML_Beautifier options
Option | Possible values | Default | Description
removeLineBreaks | TRUE or FALSE | TRUE | Sets, whether linebreaks should be stripped from cdata sections
indent | any string | " " (4 spaces) | The string passed to this option will be used to indent the tags in one level.
linebreak | any string | "\n" | The string passed to this option will be used for linebreaks You should use "\n" or "\r\n".
caseFolding | TRUE or FALSE | FALSE | Disable or enable case folding for tags and attributes
caseFoldingTo | "uppercase" or "lowercase" | "uppercase" | Can be used, if caseFolding is set to TRUE to define whether tags and attributes should be converted to upper- or lowercase
normalizeComments | FALSE or TRUE | FALSE | If set to true, all adjacent whitespaces in an XML comment will be converted to one space. This will convert comments with more than one line to a comment with one line.
maxCommentLine | integer | -1 | Maximum length of comment line. If a comment exceeds this limit, it will be wrapped automatically. If set to -1 the line length is unlimited.
multilineTags | TRUE or FALSE | FALSE | If set to true, a linebreak will be added inside the tags after each attribute and attributes will be indeted.

Options example

The following example shows how to set options for XML_Beautifier.

Using setOptions() and setOption()

<?php
require_once "XML/Beautifier.php";
$options = array(
                    "caseFolding"       => true,
                    "caseFoldingTo"     => "uppercase",
                    "normalizeComments" => true
                );

$fmt = new XML_Beautifier($options);
$result = $fmt->formatFile('originalFile.xml', 'outputFile.xml');
?>

Options example setting options at a later point

The following example shows how to set options for XML_Beautifier, if the instance already has been created.

XML_Beautifier options

<?php
require_once "XML/Beautifier.php";
$fmt = new XML_Beautifier();
$options = array(
                    "caseFolding"       => true,
                    "caseFoldingTo"     => "uppercase",
                    "normalizeComments" => true
                );

$fmt->setOptions($options);
$fmt->setOption("indent", "\t");
$result = $fmt->formatFile('originalFile.xml', 'outputFile.xml');
?>
Prev | XML_Beautifier | Next
Example | PEAR Manual | XML_Beautifier::XML_Beautifier


XML_Beautifier::XML_Beautifier

XML_Beautifier::XML_Beautifier

XML_Beautifier::XML_Beautifier() – create new instance

Synopsis

require_once 'XML/Beautifier.php';

object XML_Beautifier::XML_Beautifier ( array $options = array() )

Description

Creates a new instance of XML_Beautifier.

Parameter

  • array $options - options are used to influence to beautifying process. You may set the indent string, specify whether case folding should be enabled, etc...

    See XML_Beautifier options for more information.

Return value

object XML_Beautifier object

Note

This function can not be called statically.

Prev | XML_Beautifier | Next
Options | PEAR Manual | XML_Beautifier::setOption


XML_Beautifier::setOption

XML_Beautifier::setOption

XML_Beautifier::setOption() – set an option

Synopsis

require_once 'XML/Beautifier.php';

void XML_Beautifier::setOption ( string $option , mixed $value )

Description

Set an option for the beautifying process.

See XML_Beautifier options for more information.

Parameter

  • string $option - name of the option

  • mixed $value - value of the option

Return value

void

Note

This function can not be called statically.

Prev | XML_Beautifier | Next
XML_Beautifier::XML_Beautifier | PEAR Manual | XML_Beautifier::setOptions


XML_Beautifier::setOptions

XML_Beautifier::setOptions

XML_Beautifier::setOptions() – set several options

Synopsis

require_once 'XML/Beautifier.php';

void XML_Beautifier::setOptions ( array $options )

Description

Set several options for the beautifying process.

See XML_Beautifier options for more information.

Parameter

  • array $options - associative array containing options and their values, like you would pass it to the constructor.

Return value

void

Note

This function can not be called statically.

Prev | XML_Beautifier | Next
XML_Beautifier::setOption | PEAR Manual | XML_Beautifier::resetOptions


XML_Beautifier::resetOptions

XML_Beautifier::resetOptions

XML_Beautifier::resetOptions() – reset options to default

Synopsis

require_once 'XML/Beautifier.php';

void XML_Beautifier::resetOptions ( )

Description

Reset all options to their default values.

See XML_Beautifier options for more information.

Parameter

This method does not accept any parameters.

Return value

void

Note

This function can not be called statically.

Prev | XML_Beautifier | Next
XML_Beautifier::setOptions | PEAR Manual | XML_Beautifier::apiVersion


XML_Beautifier::apiVersion

XML_Beautifier::apiVersion

XML_Beautifier::apiVersion() – return API version

Synopsis

require_once 'XML/Beautifier.php';

string XML_Beautifier::apiVersion ( )

Description

Returns API version of XML_Beautifier.

Return value

string API version

Note

This function can be called statically.

Prev | XML_Beautifier | Next
XML_Beautifier::resetOptions | PEAR Manual | XML_Beautifier::formatFile


XML_Beautifier::formatFile

XML_Beautifier::formatFile

XML_Beautifier::formatFile() – beautify a file

Synopsis

require_once 'XML/Beautifier.php';

object XML_Beautifier::formatFile ( string $file , string $newFile = null , string $renderer = "Plain" )

Description

Beautifies a file.

Parameter

  • string $file - filename of the original file

  • string $newFile - filename for the beautified file. If no file is given, the method will return the resulting XML document. To overwrite the original file, pass XML_BEAUTIFIER_OVERWRITE.

  • string $renderer - renderer to use, currently only a "Plain" XML renderer can be used.

Return value

mixed Either true, if file has been written or the XML document string.

Note

This function can not be called statically.

Prev | XML_Beautifier | Next
XML_Beautifier::apiVersion | PEAR Manual | XML_Beautifier::formatString


XML_Beautifier::formatString

XML_Beautifier::formatString

XML_Beautifier::formatString() – beautify a string

Synopsis

require_once 'XML/Beautifier.php';

object XML_Beautifier::formatString ( string $string , string $renderer = "Plain" )

Description

Beautifies an XML string. Use this method to beautify an XML document that has been generated on-the-fly.

Parameter

  • string $string - string containing an XML document.

  • string $renderer - renderer to use, currently only a "Plain" XML renderer can be used.

Return value

string beautified XML document

Note

This function can not be called statically.

Prev | XML_Beautifier | Next
XML_Beautifier::formatFile | PEAR Manual | XML_DTD


XML_DTD

XML_DTD

Parses DTD files and does DTD validation of XML documents.

Table of Contents
  • Introduction -- Introduction to XML_DTD
  • Example -- Example usage of XML_DTD
Prev | XML | Next
XML_Beautifier::formatString | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_DTD

Introduction to XML_DTD

XML_DTD is able to parse a document type definition (DTD) file and validate XML documents according to this DTD. A DTD is the grammar of an XML application, it consist of rules that declare how tags have to be nested and which attributes may be used in the tags.

If you want to learn how to create a DTD, you should take a look at the W3C.

XML_DTD consits of three parts:

  • XML_DTD_Parser, which will parse a DTD file and return an XML_DTD_Tree object

  • XML_DTD_XmlValidator, which validates an XML document using a DTD file

  • XML_DTD_XmlParser, which will parse a XML file to determine its skeleton, that is, which elements it contains and how they are linked together.

If you validate an XML_Document using XML_DTD_XmlValidator, it will automatically parse the DTD file and create an XML_DTD_Tree from it.

Prev | XML_DTD | Next
XML_DTD | PEAR Manual | Example


Example

Example

Example – Example usage of XML_DTD

Example usage of XML_DTD

You can validate a XML file against a DTD using isValid() like in the example below:

<?php

require_once 'XML/DTD/XmlValidator.php';

$dtd_file = realpath('myfile.dtd');
$xml_file = realpath('myfile.xml');

$validator = new XML_DTD_XmlValidator();
if (!$validator->isValid($dtd_file, $xml_file)) {
    die($validator->getMessage());
}

?>

isValid() will return true when the XML document validates and false otherwise.

This is pretty much the most common usage of XML_DTD and all you need to know to get started.

Prev | XML_DTD | Next
Introduction | PEAR Manual | XML_Feed_Parser


XML_Feed_Parser

XML_Feed_Parser

XML_Feed_Parser is a parser for (the various) RSS and Atom format XML feeds. It provides a somewhat unified API while still allowing access to the full details of each feed type.

Table of Contents
  • Introduction and Quick Start -- Overview of XML_Feed_Parser
  • XML_Feed_Parser and Extensions -- Handling extensions with XML_Feed_Parser
Prev | XML | Next
Example | PEAR Manual | Introduction and Quick Start


Introduction and Quick Start

Introduction and Quick Start

Introduction and Quick Start – Overview of XML_Feed_Parser

Description

XML_Feed_Parser provides a generic interface to a number of the most popular XML-based syndication formats (Atom, RSS1, RSS2, etc). In order to focus on its core competencies, it does not provide any HTTP or feed creation features, but instead parses a wide range of formats quickly and simply.

Presuming the XML for a feed is stored in the variable $xml_source, the simplest way to create an instance of the parser is:

<?php
try {
    $feed = new XML_Feed_Parser($xml_source);
} catch (XML_Feed_Parser_Exception $e) {
    die('Feed invalid: ' . $e->getMessage());
}
?>

The constructor accepts a number of parameters, as follows:

<?php
/* The file you wish to parse */
$source = 'my_source.xml';

/* Where Relax NG is available, we can force validation of the feed */
$validate = true;

/* Whether or not to suppress non-fatal warnings */
$suppress_warnings = false;

/* If the feed is not valid XML and the tidy extension is installed we can
 * attempt to use it to fix the feed */
$use_tidy = true;

$feed = new XML_Feed_Parser($source, $validate, $suppress_warnings, $use_tidy);
?>

Once you have an instance of the parser you can extract feed-level data by querying it directly. eg.

<?php
$title = $feed->title;
?>

You can also access elements by iterating over the feed, or directly by offset or id.

<?php
foreach ($feed as $entry) {
    print $entry->title . "\n";
}

$first_entry = $feed->getEntryByOffset(0);

$particular_entry = $feed->getEntryById('http://jystewart.net/entry/1');
?>
Prev | XML_Feed_Parser | Next
XML_Feed_Parser | PEAR Manual | XML_Feed_Parser and Extensions


XML_Feed_Parser and Extensions

XML_Feed_Parser and Extensions

XML_Feed_Parser and Extensions – Handling extensions with XML_Feed_Parser

Description

Using XML namespaces, the various syndication formats are very easy to extend and the number of extensions in use is enormous.

XML_Feed_Parser focuses on core functionality shared between the various syndication formats. Some of the most common extensions are handled natively—particularly when they provide one format with features to bring it into line with others, such as the content extension for RSS2—but the majority provide specialist content and providing support for them would quickly result in a bloated package.

It is possible that a proper extensions mechanism may be introduced in a future version, but as an alternative the DOM models in use within the classes are publicly accessible, allowing the package to be wrapped with special handlers.

For example, to make use of the 'pheed' extension (namespace http://www.pheed.com/pheed/) we might use:

<?php
$feed = new XML_Feed_Parser($xml_source);
$entry = $feed->getEntryByOffset(0);
$eModel = $entry->model;

$thumbnails = $eModel->getElementsByTagNameNS(
    'http://www.pheed.com/pheed/', 'thumbnail');

if ($thumbnails->length) {
    $thumbnail_url = $thumbnails->item(0)->nodeValue;
}
?>
Prev | XML_Feed_Parser | Next
Introduction and Quick Start | PEAR Manual | XML_Parser


XML_Parser

XML_Parser

Object-oriented abstraction for PHP's xml extension.

Table of Contents
  • Introduction -- Introduction to XML_Parser
  • Example -- Example for the usage of XML_Parser
  • Modes -- Explanation of possible parsing modes
  • Choosing input -- Explanation of different types of input data
Prev | XML | Next
XML_Feed_Parser and Extensions | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_Parser

Introduction to XML_Parser

XML_Parser provides an object-oriented abstraction to PHP's ext/xml. It helps you processing XML documents by supplying methods that are needed when working with XML documents, like automatic error handling, parsing from a file, URL or string as well as an easy way to register callbacks.

XML_Parser uses SAX-based parsing, which is a simple API to retrieve information from XML documents. While the parser reads the document, it will call methods for the different nodes that are found. These nodes range from opening and closing tags to character data and processing instructions.

You will not be able to use XML_Parser directly to parse your documents, but you have to create a new class that extends XML_Parser and implement handlers for the tags and all other elements you need to process.

Several of PEAR's XML packages use this approach and thus rely on XML_Parser. If you would like to take a look at real-life examples, just install XML_RDDL, XML_Beautifier, XML_Statistics or XML_Serializer.

A tutorial that explains nearly every feature of XML_Parser is available at http://www.schst.net/articles/XML_Parser.

Prev | XML_Parser | Next
XML_Parser | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_Parser

Basic example

This example shows you how to create a very simple parser that handles start, end elements (i.e. opening and closing tags), and character data (the "content" between the tags).

<?php
require_once 'XML/Parser.php';

class myParser extends XML_Parser
{
  function myParser()
  {
    parent::XML_Parser();
  }

 /**
  * handle start element
  *
  * @access private
  * @param  resource  xml parser resource
  * @param  string    name of the element
  * @param  array     attributes
  */
  function startHandler($xp, $name, $attribs)
  {
    printf('handle start tag: %s<br />', $name);
  }

 /**
  * handle end element
  *
  * @access private
  * @param  resource  xml parser resource
  * @param  string    name of the element
  */
  function endHandler($xp, $name)
  {
    printf('handle end tag: %s<br />', $name);
  }

 /**
  * handle character data
  *
  * @access private
  * @param  resource  xml parser resource
  * @param  string    character data
  */
  function cdataHandler($xp, $cdata)
  {
    // does nothing here, but might e.g. print $cdata
  }
}

$p = &new myParser();

$result = $p->setInputFile('xml_parser_file.xml');
$result = $p->parse();
?>

This parser will just output the names of the opening and closing tags that are found while parsing the document.

Prev | XML_Parser | Next
Introduction | PEAR Manual | Modes


Modes

Modes

Modes – Explanation of possible parsing modes

Parser modes of XML_Parser

XML_Parser provides two modes for parsing:

  • func

  • event

In the 'event' mode, XML_Parser will always call the methods startHandler() and endHandler(), independent of the tag name. In these methods you'll have to check for the tagname, which is passed as the second parameter and decide what you need to do. In most cases, this is done with a switch/case statement.

In the 'func' mode, XML_Parser will call different methods based on the name of the tag. This allows you to dispatch different tags to different methods. The methods to handle the start tag have to be called xmltag_[tagname](), where [tagname] has to be substituted by the name of the element that you wish to process. That means if you wish to write a method to process all opening <title> tags, it has to be called xmltag_title.

Methods to handle closing tags have to be named xmltag_[tagname]_() (distinguishes from the start element handler using a traling underscore).

As XML tags may contain chars like ".", ":" and "-" and those chars are not allowed in PHP function names, XML_Parser will replace them with "_" when building the name of the callback function.

If a method does not exist, XML_Parser will skip the tag without handling the element, unless you implemented the methods xmltag() and xmltag_(), which will be used as fallback methods.

Setting the mode

There are two ways of setting the mode:

  • Specifying the mode in the constructor as the second parameter.

    In the subclass of XML_Parser that you implemented to process the XML documents, you will have to call XML_Parser::XML_Parser() in the constructor. This method accepts the mode as its second parameter.

  • Setting the mode using XML_Parser::setMode().

Prev | XML_Parser | Next
Example | PEAR Manual | Choosing input


Choosing input

Choosing input

Choosing input – Explanation of different types of input data

Selecting the input for XML_Parser

XML_Parser is able to parse from several inputs:

  • filesystem or anything that can be accessed via stream

  • strings

  • resources

You will have to set the input using setInputFile(), setInputString() or setInput() and then call parse() to start the XML processing.

Parsing from a file

To parse from a file or URL, you'll have to set the name or URI using XML_Parser::setInputFile(). You may not only use files located on the filesystem, but any location that can be opened using fopen(). You may combine this functionality with the stream functions or PEAR's Streams packages to parse documents from shared memory, databases or anything else.

You may also use any of PHP's built-in wrappers to open HTTP or FTP locations as well as STDIN.

Parsing from a string

To parse an XML string, pass the string to XML_Parser (or your subclass of XML_Parser) using XML_Parser::setInputString(). A big advantage of SAX-based parsing is that the parser does not have to read the whole XML document to process it. If you are parsing very large documents, you should aboid setInputString() and use setInput() or setInputFile() instead.

Parsing from any resource

There's a third, but seldomly used way to specify XML_Parser's input. XML_Parser allows you to pass a PHP resource, like a file pointer that has been returned by fopen(). This can be useful, if you are generating the document on-the-fly and already opened it before. Instead of closing the file and passing its name to XML_Parser, you may simply use XML_Parser::setInput() to pass the resource. Make sure that the file pointer is at the correct location in your file using fseek().

Prev | XML_Parser | Next
Modes | PEAR Manual | XML_Query2XML


XML_Query2XML

XML_Query2XML

Allows you to transform records retrieved with one or more SQL SELECT queries into XML data.

Table of Contents
  • Introduction -- Start here
Prev | XML | Next
Choosing input | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Start here

Major Features

XML_Query2XML allows you to transform the records retrieved with one or more SQL SELECT queries into XML data. Very simple to highly complex transformations are supported. Is was written with performance in mind and can handle large amounts of data. No XSLT needed!

  • 1. XML_Query2XML works with the classes provided by PHP5's built-in DOM API

  • 2. minimum effort necessary to get the simple jobs done

  • 3. highly configurable for more complex tasks

  • 4. ISO/IEC 9075-14:2005 support: mapping of SQL identifiers to XML names

  • 5. works with any database that is supported by PDO, PEAR DB, PEAR MDB2 or ADOdb

  • 6. easy integration of other XML data sources (e.g. raw XML data stored in the DB)

  • 7. debugging, logging and profiling features

  • 8. XML encoding: support for UTF-8, ISO-8859-1 and others

  • 9. in-depth documentation and case studies: tutorials and API documentation

  • 10. 1084 phpt unit tests

Full Documentation

  • The full online documentation is available here

Prev | XML_Query2XML | Next
XML_Query2XML | PEAR Manual | XML_RDDL


XML_RDDL

XML_RDDL

Class to read RDDL (Resource Directory Description Language) documents.

Table of Contents
  • Introduction -- Introduction to XML_RDDL
  • Example -- Example for the usage of XML_RDDL
  • XML_RDDL::XML_RDDL -- Constructor
  • XML_RDDL::parseRDDL -- parse a document that contains RDDL resources
  • XML_RDDL::getAllResources -- return all resources that have been found
  • XML_RDDL::getResourceById -- get one resource from the document
  • XML_RDDL::getResourcesByNature -- selects all resources of a specified nature
  • XML_RDDL::getResourcesByPurpose -- selects all resources of a specified nature
  • XML_RDDL::getResourcesByLanguage -- selects all resources of a specified language
  • XML_RDDL::apiVersion -- return API version
Prev | XML | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_RDDL

Introduction to XML_RDDL

XML_RDDL is a class that allows the extraction of RDDL resources from an XML document.

The Resource Directory Description Language is an extension of XHTML Basic 1.0 with an added element named resource. This element serves as an XLink to the referenced resource, and contains a human-readable description of the resource and machine readable links which describe the purpose of the link and the nature of the resource being linked to. The nature of the resource being linked to is indicated by the xlink:role attribute and the purpose of the link is indicated by the xlink:arcrole attribute.

For more information on RDDL, visit the RDDL website.

Prev | XML_RDDL | Next
XML_RDDL | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_RDDL

Usage example

As the RDDL website contains RDDL resources embedded in the XHMTL code of the home page, it can be used in the following example.

Fetching resources from www.rddl.org

<?php
require_once "XML/RDDL.php";

// create new RDDL parser
$rddl   = &new XML_RDDL();

// parse a document that contains RDDL resources
$result = $rddl->parseRDDL('http://www.rddl.org');
// check for error
if (PEAR::isError($result)) {
echo    sprintf( "ERROR: %s (code %d)", $result->getMessage(), $result->getCode());
exit;
}

// get all resources
$resources = $rddl->getAllResources();
echo    "<pre>";
print_r($resources);
echo    "</pre>";

//    get one resource by its Id
$test = $rddl->getResourceById('CSS');
echo    "<pre>";
print_r($test);
echo    "</pre>";

// get all stylesheets
$test = $rddl->getResourcesByNature('http://www.w3.org/1999/XSL/Transform');
echo    "<pre>";
print_r($test);
echo    "</pre>";

// get all normative references
$test = $rddl->getResourcesByPurpose('http://www.rddl.org/purposes#normative-reference');
echo    "<pre>";
print_r($test);
echo    "</pre>";
?>
Prev | XML_RDDL | Next
Introduction | PEAR Manual | XML_RDDL::XML_RDDL


XML_RDDL::XML_RDDL

XML_RDDL::XML_RDDL

XML_RDDL::XML_RDDL() – Constructor

Synopsis

require_once 'XML/RDDL.php';

 object XML_RDDL::XML_RDDL (
 string  $rddlNamespace = "rddl"
  , string  $xlinkNamespace = "xlink"
)

Description

Creates a new instance of XML_RDDL that can be used to parse RDDL documents.

When instantiating you may specifiy RDDL and XLINK namespaces. This may change, when XML_Parser supports namespaces and XML_RDDL will be able to extract the correct namespace abbrevations.

Parameter

  • string $rddlNamespace - abbrevation for the RDDL namespace.

  • string $xlinkNamespace - abbrevation for the XLink namespace.

Note

This function can not be called statically.

Prev | XML_RDDL | Next
Example | PEAR Manual | XML_RDDL::parseRDDL


XML_RDDL::parseRDDL

XML_RDDL::parseRDDL

XML_RDDL::parseRDDL() – parse a document that contains RDDL resources

Synopsis

require_once 'XML/RDDL.php';

boolean XML_RDDL::parseRDDL ( string $input , boolean $isFile = true )

Description

Parses an XML or XHTML document that contains RDDL resources and stores information about them for retrieval by the other methods.

Parameter

  • string $input - input to parse, either a string or a file. If it's a file, you have to set $isFile to true.

  • boolean $isFile - flag to indicate whether the $input parameter should be treated as a filename.

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | XML_RDDL | Next
XML_RDDL::XML_RDDL | PEAR Manual | XML_RDDL::getAllResources


XML_RDDL::getAllResources

XML_RDDL::getAllResources

XML_RDDL::getAllResources() – return all resources that have been found

Synopsis

require_once 'XML/RDDL.php';

array XML_RDDL::getAllResources ( )

Description

Returns an array containing all reources that have been found. You have to call XML_RDDL::parseRDDL() first.

Return value

array array containing all resources

Note

This function can not be called statically.

Prev | XML_RDDL | Next
XML_RDDL::parseRDDL | PEAR Manual | XML_RDDL::getResourceById


XML_RDDL::getResourceById

XML_RDDL::getResourceById

XML_RDDL::getResourceById() – get one resource from the document

Synopsis

require_once 'XML/RDDL.php';

array XML_RDDL::getResourceById ( string $id )

Description

Gets one resource from a document. You have to call XML_RDDL::parseRDDL() first.

Parameter

  • string $id - ID of the resource you want to get.

Return value

array array containing all information about the specified resource or a PEAR_Error if the resource does not exist.

Note

This function can not be called statically.

Prev | XML_RDDL | Next
XML_RDDL::getAllResources | PEAR Manual | XML_RDDL::getResourcesByNature


XML_RDDL::getResourcesByNature

XML_RDDL::getResourcesByNature

XML_RDDL::getResourcesByNature() – selects all resources of a specified nature

Synopsis

require_once 'XML/RDDL.php';

array XML_RDDL::getResourcesByNature ( string $nature )

Description

Gets all resources of a given nature from an RDDL document. You have to call XML_RDDL::parseRDDL() first. The nature of a resource is specified by the 'xlink:role' attribute. A nature can be a stylesheet, a DTD, a HTML document, etc. You can find a list of well known natures at http://www.rddl.org/natures/.

Parameter

  • string $nature - nature of the resources you want to get.

Return value

array array containing all resources with the specified nature.

Note

This function can not be called statically.

Usage example

Getting all stylesheets from a document

<?php
require_once "XML/RDDL.php";
// create new parser
$rddl   = &new XML_RDDL();

// parse a document that contains RDDL resources
$result = $rddl->parseRDDL('http://www.rddl.org');
// check for error
if (PEAR::isError($result)) {
    echo sprintf( "ERROR: %s (code %d)", $result->getMessage(), $result->getCode());
    exit;
}
// get all stylesheets
$xslt = $rddl->getResourcesByNature('http://www.w3.org/1999/XSL/Transform');
echo "<pre>";
print_r($xslt);
echo "</pre>";
?>
Prev | XML_RDDL | Next
XML_RDDL::getResourceById | PEAR Manual | XML_RDDL::getResourcesByPurpose


XML_RDDL::getResourcesByPurpose

XML_RDDL::getResourcesByPurpose

XML_RDDL::getResourcesByPurpose() – selects all resources of a specified nature

Synopsis

require_once 'XML/RDDL.php';

array XML_RDDL::getResourcesByPurpose ( string $purpose )

Description

Gets all resources of a given purpose from an RDDL document. You have to call XML_RDDL::parseRDDL() first. The purpose of a resource is specified by the 'xlink:arcrole' attribute. The purpose of a resource link determines what the link will be used for. Frequently the purpose of a link can be determined from the nature of the referenced resource. For example the purpose of an XML Schema is typically schema validation, yet a schema may be comprised of a number of included modules and even when included modules are themselves an XML Schema, the purpose is as a module. You can find a list of well known purposes at http://www.rddl.org/purposes/.

Parameter

  • string $purpose - purpose of the resources you want to get.

Return value

array array containing all resources with the specified purpose.

Note

This function can not be called statically.

Usage example

Getting all normative references

<?php
require_once "XML/RDDL.php";
// create new parser
$rddl   = &new XML_RDDL();

// parse a document that contains RDDL resources
$result = $rddl->parseRDDL('http://www.rddl.org');
// check for error
if (PEAR::isError($result)) {
    echo sprintf( "ERROR: %s (code %d)", $result->getMessage(), $result->getCode());
    exit;
}
// get all normative references
$ref = $rddl->getResourcesByPurpose('http://www.rddl.org/purposes#normative-reference');
echo "<pre>";
print_r($ref);
echo "</pre>";
?>
Prev | XML_RDDL | Next
XML_RDDL::getResourcesByNature | PEAR Manual | XML_RDDL::getResourcesByLanguage


XML_RDDL::getResourcesByLanguage

XML_RDDL::getResourcesByLanguage

XML_RDDL::getResourcesByLanguage() – selects all resources of a specified language

Synopsis

require_once 'XML/RDDL.php';

array XML_RDDL::getResourcesByLanguage ( string $language )

Description

Gets all resources of a given language from an RDDL document. You have to call XML_RDDL::parseRDDL() first. If a resource has no xml:lang attribute, the xml:lang attribute of the root of the document is used.

Parameter

  • string $language - language of the resources you want to get.

Return value

array array containing all resources with the specified language.

Note

This function can not be called statically.

Usage example

Getting all english resource

<?php
require_once "XML/RDDL.php";
// create new parser
$rddl   = &new XML_RDDL();

// parse a document that contains RDDL resources
$result = $rddl->parseRDDL('http://www.rddl.org');
// check for error
if (PEAR::isError($result)) {
    echo sprintf( "ERROR: %s (code %d)", $result->getMessage(), $result->getCode());
    exit;
}
// get all english resources
$en = $rddl->getResourcesByLanguage('en');
echo "<pre>";
print_r($en);
echo "</pre>";
?>
Prev | XML_RDDL | Next
XML_RDDL::getResourcesByPurpose | PEAR Manual | XML_RDDL::apiVersion


XML_RDDL::apiVersion

XML_RDDL::apiVersion

XML_RDDL::apiVersion() – return API version

Synopsis

require_once 'XML/RDDL.php';

string XML_RDDL::apiVersion ( )

Description

Returns API version of XML_RDDL.

Return value

string API version

Note

This function can be called statically.

Prev | XML_RDDL | Next
XML_RDDL::getResourcesByLanguage | PEAR Manual | XML_RSS


XML_RSS

XML_RSS

Parser for Resource Description Framework (RDF) Site Summary (RSS) documents.

Table of Contents
  • Introduction -- Introduction to XML_RSS
  • Requirements -- Requirements for running XML_RSS
  • Example -- Example for the usage of XML_RSS
  • XML_RSS::XML_RSS -- Constructor
  • XML_RSS::getStructure -- Get complete structure of RSS file
  • XML_RSS::getChannelInfo -- Get general information about current channel
  • XML_RSS::getItems -- Get items from RSS file
  • XML_RSS::getImages -- Get images from RSS document
  • XML_RSS::getTextinputs -- Get text input fields from RSS document
Prev | XML | Next
XML_RDDL::apiVersion | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_RSS

Introduction to XML_RSS

Resource Description Framework (RDF) Site Summary (RSS) documents are XML documents, that provide a lightweight multipurpose extensible metadata description and syndication format. RSS files are often used to syndicate news or headlines from portal sites (e.g. Slashdot or freshmeat.net) or weblogs.

For more information on RSS see the website of the RSS working group (http://tech.groups.yahoo.com/group/rss-dev/files/specification.html).

RSS file

<?xml version="1.0"?>

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns="http://my.netscape.com/rdf/simple/0.9/">

<channel>
 <title>FooBar Inc.</title>
 <link>http://example.com/</link>
 <description>abcd, xyz, 123</description>
</channel>

<image>
 <title>FooBar</title>
 <url>http://example.com/images/rssicon.gif</url>
 <link>http://example.com/</link>
</image>

<item>
 <title>Headline 1</title>
 <link>http://example.com/news.php?h=1</link>
</item>

<item>
 <title>Headline 2</title>
 <link>http://example.com/news.php?h=2</link>
</item>

<textinput>
 <title>Search FooBar Inc.</title>
 <description>Search FooBar Inc. headlines</description>
 <name>q</name>
 <link>http://example.com/search.php</link>
</textinput>

</rdf:RDF>
Prev | XML_RSS | Next
XML_RSS | PEAR Manual | Requirements


Requirements

Requirements

Requirements – Requirements for running XML_RSS

XML_Parser

To parse the XML files that contain the RSS feeds, XML_RSS requires that the package XML_Parser is installed. However this dependency will be automatically handled by the installer during the installation phase of XML_RSS.

allow_url_fopen configuration value

Since most RSS feeds are located on remote hosts, one has to ensure that the PHP configuration value "allow_url_fopen" is set to "On" before running XML_RSS.

To find out the current value of "allow_url_fopen", one can use the function ini_get(). To set a new value of "allow_url_fopen", you must modify the php.ini configuration file of PHP.

Prev | XML_RSS | Next
Introduction | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_RSS

Usage example

The following script fetches the latest headlines from Slashdot.org via RSS.

Fetching headlines from Slashdot

<?php
require_once "XML/RSS.php";

$rss =& new XML_RSS("http://rss.slashdot.org/Slashdot/slashdot");
$rss->parse();

echo "<h1>Headlines from <a href=\"http://slashdot.org\">Slashdot</a></h1>\n";
echo "<ul>\n";

foreach ($rss->getItems() as $item) {
    echo "<li><a href=\"" . $item['link'] . "\">" . $item['title'] . "</a></li>\n";
}

echo "</ul>\n";
?>
Prev | XML_RSS | Next
Requirements | PEAR Manual | XML_RSS::XML_RSS


XML_RSS::XML_RSS

XML_RSS::XML_RSS

XML_RSS::XML_RSS – Constructor

Synopsis

require_once "XML/RSS.php";

void XML_RSS::XML_RSS ( mixed $handle='' )

Description

Constructor

Parameter

  • mixed $handle - file pointer or name of the RDF file.

Note

This function can not be called statically.

Example

Using XML_RSS()

<?php
$r =& new XML_RSS("test.rss");
?>
Prev | XML_RSS | Next
Example | PEAR Manual | XML_RSS::getStructure


XML_RSS::getStructure

XML_RSS::getStructure

XML_RSS::getStructure – Get complete structure of RSS file

Synopsis

require_once "XML/RSS.php";

array XML_RSS::getStructure ( )

Description

Get complete structure of RSS file

Return value

array - the array depends on the structure of the RSS document.

Note

This function can not be called statically.

Prev | XML_RSS | Next
XML_RSS::XML_RSS | PEAR Manual | XML_RSS::getChannelInfo


XML_RSS::getChannelInfo

XML_RSS::getChannelInfo

XML_RSS::getChannelInfo – Get general information about current channel

Synopsis

require_once "XML/RSS.php";

array XML_RSS::getChannelInfo ( )

Description

Get general information about current channel. This function returns an array containing the information that has been extracted from the <channel>-tag while parsing the RSS document.

Return value

array - an array of strings. The keys of the array are

  • 'title' - name of the channel

  • 'link' - URL to the channel site

  • 'description' - description of the channel

Note

This function can not be called statically.

Prev | XML_RSS | Next
XML_RSS::getStructure | PEAR Manual | XML_RSS::getItems


XML_RSS::getItems

XML_RSS::getItems

XML_RSS::getItems – Get items from RSS file

Synopsis

require_once "XML/RSS.php";

array XML_RSS::getItems ( )

Description

Get items from RSS document. This function returns an array containing the set of items that are provided by the RSS document.

Return value

array - a two-dimensional array. Every inner array contains information about a site. Use the array key 'title' to get the article title and the key 'link' for the URL of the site.

Note

This function can not be called statically.

Example

Using getItems()

<?php
foreach ($r->getItems() as $value) {
    echo $value['title'] . ": " . $value['link'] . "\n";
}
?>
Prev | XML_RSS | Next
XML_RSS::getChannelInfo | PEAR Manual | XML_RSS::getImages


XML_RSS::getImages

XML_RSS::getImages

XML_RSS::getImages – Get images from RSS document

Synopsis

require_once "XML/RSS.php";

array XML_RSS::getImages ( )

Description

Get images from RSS document. This function returns an array containing the set of images that are provided by the RSS document.

Return value

array - a two-dimensional array. Every inner array contains information about an image of a site.

  • 'title' - name of the channel

  • 'link' - URL to the site

  • 'url' - URL of the image

Note

This function can not be called statically.

Prev | XML_RSS | Next
XML_RSS::getItems | PEAR Manual | XML_RSS::getTextinputs


XML_RSS::getTextinputs

XML_RSS::getTextinputs

XML_RSS::getTextinputs – Get text input fields from RSS document

Synopsis

require_once "XML/RSS.php";

array XML_RSS::getTextinputs ( )

Description

Get text input fields from RSS document.

Return value

array - an hash containing the data of an input field

  • 'title' - name of the input field

  • 'description' - description of the inout field

  • 'link' - URL for the request

  • 'name' - name of the request parameter

Note

This function can not be called statically.

Prev | XML_RSS | Next
XML_RSS::getImages | PEAR Manual | XML_Serializer


XML_Serializer

XML_Serializer

Table of Contents
  • Introduction -- Introduction to XML_Serializer
  • Package XML_Serializer Constants -- Constants defined in and used by XML_Serializer
  • Class Summary XML_Serializer -- XML_Serializer - class that serializes various structures into an XML document
  • constructor XML_Serializer::XML_Serializer -- constructor
  • XML_Serializer::apiVersion -- return API version
  • XML_Serializer::serialize -- serialize data
  • XML_Serializer::getSerializedData -- get the result of the serialization
  • XML_Serializer::resetOptions -- reset all options to default options
  • XML_Serializer::setOption -- set an option
  • Example -- Example for the usage of XML_Serializer
  • Tutorial: Create an RSS Feed -- How to use XML_Serializer to build an RSS Newsfeed
  • Class Summary XML_Unserializer -- XML_Unserializer - class to unserialize (read) XML documents
  • XML_Unserializer Options -- List of all XML_Unserializer options
  • XML_Unserializer::XML_Unserializer -- Constructor for XML_Unserializer
  • XML_Unserializer::apiVersion -- return API version
  • XML_Unserializer::unserialize -- unserialize data
  • XML_Unserializer::getUnserializedData -- get the result of the unserialization
  • XML_Unserializer::getRootName -- get the name of the root tag of the parsed document.
  • XML_Unserializer::setOption -- set an option
  • XML_Unserializer::setoptions -- set several options
  • XML_Unserializer::resetOptions -- reset all options to default options
Prev | XML | Next
XML_RSS::getTextinputs | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_Serializer

Introduction to XML_Serializer

XML_Serializer serializes complex data structures like arrays or object as XML documents. This class helps you generating any XML document you require without the need for DOM.

Currently there are two ways in which XML_Serializer can be used in your applications:

  • use XML_Serializer's functionality to create XML documents in a specific XML application (e.g. RDF) that is being processed by an existing script)

  • use XML_Serializer's functionality to serialize data structures that have to be unserialized at a later point. This is possible by adding type information to all XML elements.

The package not only contains a serializer class but also a matching XML_Unserializer, which is able to virtually read any XML document and return an array or object structure that represents the data stored in the document.

Tutorials on XML_Serializer

There are several tutorials on XML_Serializer available, that help you get started.

  • Create a RSS newsfeed with XML_Serializer (local) by cnb

  • Instant XML with PHP and PEAR::XML_Serializer by Harry Fuecks

  • Serializing XML With PHP by Vikram Vaswani

Prev | XML_Serializer | Next
XML_Serializer | PEAR Manual | Package XML_Serializer Constants


Package XML_Serializer Constants

Package XML_Serializer Constants

Package XML_Serializer Constants – Constants defined in and used by XML_Serializer

All Constants

Constants defined in Serializer.php

Constants defined in Serializer.php
Name | Value | Notes
XML_SERIALIZER_ERROR_NO_SERIALIZATION | 51 | error code returned by serialize() when it did not succeed
XML_SERIALIZER_MODE_DEFAULT | default | use for default serializer mode behavior
XML_SERIALIZER_MODE_SIMPLEXML | simplexml | use for SimpleXML behavior in serializer
XML_SERIALIZER_ENTITIES_NONE | XML_UTIL_ENTITIES_NONE | maps to XML_Util's Entity replacement behavior of "don't replace entities"
XML_SERIALIZER_ENTITIES_XML | XML_UTIL_ENTITIES_XML | maps to XML_Util's Entity replacement behavior of "only replace XML entities"
XML_SERIALIZER_ENTITIES_XML_REQUIRED | XML_UTIL_ENTITIES_XML_REQUIRED | maps to XML_Util's Entity replacement behavior of "only replace required XML entities"
XML_SERIALIZER_ENTITIES_HTML | XML_UTIL_ENTITIES_HTML | maps to XML_Util's Entity replacement behavior of "only replace HTML entities"
XML_SERIALIZER_OPTION_INDENT | indent | OPTION constant for 'indent' option
XML_SERIALIZER_OPTION_LINEBREAKS | linebreak | OPTION constant for 'linebreak' option
XML_SERIALIZER_OPTION_TYPEHINTS | typeHints | OPTION constant for 'typeHints' option
XML_SERIALIZER_OPTION_XML_DECL_ENABLED | addDecl | OPTION constant for 'addDecl' option
XML_SERIALIZER_OPTION_XML_ENCODING | encoding | OPTION constant for 'encoding' option
XML_SERIALIZER_OPTION_DEFAULT_TAG | defaultTagName | OPTION constant for 'defaultTagName' option
XML_SERIALIZER_OPTION_CLASSNAME_AS_TAGNAME | classAsTagName | OPTION constant for 'classAsTagName' option
XML_SERIALIZER_OPTION_ATTRIBUTE_KEY | keyAttribute | OPTION constant for 'keyAttribute' option
XML_SERIALIZER_OPTION_ATTRIBUTE_TYPE | typeAttribute | OPTION constant for 'typeAttribute' option
XML_SERIALIZER_OPTION_ATTRIBUTE_CLASS | classAttribute | OPTION constant for 'classAttribute' option
XML_SERIALIZER_OPTION_SCALAR_AS_ATTRIBUTES | scalarAsAttributes | OPTION constant for 'scalarAsAttributes' option
XML_SERIALIZER_OPTION_PREPEND_ATTRIBUTES | prependAttributes | OPTION constant for 'prependAttributes' option
XML_SERIALIZER_OPTION_INDENT_ATTRIBUTES | indentAttributes | OPTION constant for 'indentAttributes' option
XML_SERIALIZER_OPTION_MODE | mode | OPTION constant for 'mode' option
XML_SERIALIZER_OPTION_DOCTYPE_ENABLED | addDoctype | OPTION constant for 'addDoctype' option
XML_SERIALIZER_OPTION_DOCTYPE | doctype | OPTION constant for 'doctype' option
XML_SERIALIZER_OPTION_ROOT_NAME | rootName | OPTION constant for 'rootName' option
XML_SERIALIZER_OPTION_ROOT_ATTRIBS | rootAttributes | OPTION constant for 'rootAttributes' option
XML_SERIALIZER_OPTION_ATTRIBUTES_KEY | attributesArray | OPTION constant for 'attributesArray' option
XML_SERIALIZER_OPTION_CONTENT_KEY | contentName | OPTION constant for 'contentName' option
XML_SERIALIZER_OPTION_COMMENT_KEY | commentName | OPTION constant for 'commentName' option
XML_SERIALIZER_OPTION_TAGMAP | tagMap | OPTION constant for 'tagMap' option
XML_SERIALIZER_OPTION_ENCODE_FUNC | encodeFunction | OPTION constant for 'encodeFunction' option
XML_SERIALIZER_OPTION_NAMESPACE | namespace | OPTION constant for 'namespace' option
XML_SERIALIZER_OPTION_ENTITIES | replaceEntities | OPTION constant for 'replaceEntities' option
XML_SERIALIZER_OPTION_RETURN_RESULT | returnResult | OPTION constant for 'returnResult' option
XML_SERIALIZER_OPTION_IGNORE_NULL | ignoreNull | OPTION constant for 'ignoreNull' option
XML_SERIALIZER_OPTION_CDATA_SECTIONS | cdata | OPTION constant for 'cdata' option
XML_SERIALIZER_OPTION_FALSE_AS_STRING | falseAsString | OPTION constant for 'falseAsString' option

Constants defined in Unserializer.php

Constants defined in Unserializer.php
Name | Value | Notes
XML_UNSERIALIZER_ERROR_NO_UNSERIALIZATION | 151 | error code returned by unserialize() when it did not succeed
XML_UNSERIALIZER_OPTION_COMPLEXTYPE | complexType | OPTION constant for 'complexType' option
XML_UNSERIALIZER_OPTION_ATTRIBUTE_KEY | keyAttribute | OPTION constant for 'keyAttribute' option
XML_UNSERIALIZER_OPTION_ATTRIBUTE_TYPE | typeAttribute | OPTION constant for 'typeAttribute' option
XML_UNSERIALIZER_OPTION_ATTRIBUTE_CLASS | classAttribute | OPTION constant for 'classAttribute' option
XML_UNSERIALIZER_OPTION_TAG_AS_CLASSNAME | tagAsClass | OPTION constant for 'tagAsClass' option
XML_UNSERIALIZER_OPTION_DEFAULT_CLASS | defaultClass | OPTION constant for 'defaultClass' option
XML_UNSERIALIZER_OPTION_ATTRIBUTES_PARSE | parseAttributes | OPTION constant for 'parseAttributes' option
XML_UNSERIALIZER_OPTION_ATTRIBUTES_ARRAYKEY | attributesArray | OPTION constant for 'attributesArray' option
XML_UNSERIALIZER_OPTION_ATTRIBUTES_PREPEND | prependAttributes | OPTION constant for 'prependAttributes' option
XML_UNSERIALIZER_OPTION_CONTENT_KEY | contentName | OPTION constant for 'contentName' option
XML_UNSERIALIZER_OPTION_TAG_MAP | tagMap | OPTION constant for 'tagMap' option
XML_UNSERIALIZER_OPTION_FORCE_ENUM | forceEnum | OPTION constant for 'forceEnum' option
XML_UNSERIALIZER_OPTION_ENCODING_SOURCE | encoding | OPTION constant for 'encoding' option
XML_UNSERIALIZER_OPTION_ENCODING_TARGET | targetEncoding | OPTION constant for 'targetEncoding' option
XML_UNSERIALIZER_OPTION_DECODE_FUNC | decodeFunction | OPTION constant for 'decodeFunction' option
XML_UNSERIALIZER_OPTION_RETURN_RESULT | returnResult | OPTION constant for 'returnResult' option
XML_UNSERIALIZER_OPTION_WHITESPACE | whitespace | OPTION constant for 'whitespace' option
XML_UNSERIALIZER_WHITESPACE_KEEP | keep | OPTION constant for 'keep' option
XML_UNSERIALIZER_WHITESPACE_TRIM | trim | OPTION constant for 'trim' option
XML_UNSERIALIZER_WHITESPACE_NORMALIZE | normalize | OPTION constant for 'normalize' option
XML_UNSERIALIZER_OPTION_OVERRIDE_OPTIONS | overrideOptions | OPTION constant for 'overrideOptions' option
XML_UNSERIALIZER_OPTION_IGNORE_KEYS | ignoreKeys | OPTION constant for 'ignoreKeys' option
XML_UNSERIALIZER_OPTION_GUESS_TYPES | guessTypes | OPTION constant for 'guessTypes' option
Prev | XML_Serializer | Next
Introduction | PEAR Manual | Class Summary XML_Serializer


Class Summary XML_Serializer

Class Summary XML_Serializer

Class Summary XML_Serializer – XML_Serializer - class that serializes various structures into an XML document

XML_Serializer - class that serializes various structures into an XML document

This class can be used in two modes:

  1. Create an XML document from an array or object that is processed by other applications.

  2. This classes can be used to serialize any data structure in a way that it can later be unserialized again. XML_Serializer will store the type of the value and additional meta information in attributes of the surrounding tag. This meta information can later be used to restore the original data structure in PHP.

Prev | XML_Serializer | Next
Package XML_Serializer Constants | PEAR Manual | constructor XML_Serializer::XML_Serializer


constructor XML_Serializer::XML_Serializer

constructor XML_Serializer::XML_Serializer

constructor XML_Serializer::XML_Serializer() – constructor

Synopsis

require_once 'Serializer.php';

void constructor XML_Serializer::XML_Serializer ( mixed $options = null )

Description

This package is not documented yet.

Parameter

mixed $options

array containing options for the serialization

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | XML_Serializer | Next
Class Summary XML_Serializer | PEAR Manual | XML_Serializer::apiVersion


XML_Serializer::apiVersion

XML_Serializer::apiVersion

XML_Serializer::apiVersion() – return API version

Synopsis

require_once 'Serializer.php';

string XML_Serializer::apiVersion ( )

Description

This package is not documented yet.

Return value

returns API version

Throws

throws no exceptions thrown

static

static

Note

This function can not be called statically.

Prev | XML_Serializer | Next
constructor XML_Serializer::XML_Serializer | PEAR Manual | XML_Serializer::serialize


XML_Serializer::serialize

XML_Serializer::serialize

XML_Serializer::serialize() – serialize data

Synopsis

require_once 'Serializer.php';

boolean XML_Serializer::serialize ( mixed $data , mixed $options = null )

Description

This package is not documented yet.

Parameter

mixed $data

data to serialize

mixed $options

Return value

returns true on success, pear error on failure

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Serializer::apiVersion | PEAR Manual | XML_Serializer::getSerializedData


XML_Serializer::getSerializedData

XML_Serializer::getSerializedData

XML_Serializer::getSerializedData() – get the result of the serialization

Synopsis

require_once 'Serializer.php';

string XML_Serializer::getSerializedData ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Serializer::serialize | PEAR Manual | XML_Serializer::resetOptions


XML_Serializer::resetOptions

XML_Serializer::resetOptions

XML_Serializer::resetOptions() – reset all options to default options

Synopsis

require_once 'Serializer.php';

void XML_Serializer::resetOptions ( )

Description

This package is not documented yet.

Throws

throws no exceptions thrown

See

see XML_Serializer::setOption(), XML_Unserializer()

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Serializer::getSerializedData | PEAR Manual | XML_Serializer::setOption


XML_Serializer::setOption

XML_Serializer::setOption

XML_Serializer::setOption() – set an option

Synopsis

require_once 'Serializer.php';

void XML_Serializer::setOption ( mixed $name , mixed $value )

Description

You can use this method if you do not want to set all options in the constructor

Parameter

mixed $name

mixed $value

Throws

throws no exceptions thrown

See

see resetOption(), XML_Serializer::XML_Serializer()

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Serializer::resetOptions | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_Serializer

Build a simple XML document

Example that uses the returnResult option to directly return the serialized XML document in the serialize() method.

In this example look at theses 3 lines.

<?php
$serializer = &new XML_Serializer($options);
$foo = PEAR::raiseError('Just a test', 1234);
$result = $serializer->serialize($foo);
?>
<?php
error_reporting(E_ALL);
require_once 'XML/Serializer.php';
$options = array(
  XML_SERIALIZER_OPTION_INDENT        => '    ',
  XML_SERIALIZER_OPTION_RETURN_RESULT => true
  );

$serializer = &new XML_Serializer($options);

$foo = PEAR::raiseError('Just a test', 1234);

$result = $serializer->serialize($foo);

echo '<pre>';
echo htmlspecialchars($result);
echo '</pre>';
?>

And this is the result

<pear_error>
    <error_message_prefix />
    <mode>1</mode>
    <level>1024</level>
    <code>1234</code>
    <message>Just a test</message>
    <userinfo />
    <backtrace>
        <XML_Serializer_Tag>
            <file>pathToMypear\PEAR.php</file>
            <line>566</line>
            <function>pear_error</function>
            <class>pear_error</class>
            <type>-&gt;</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
                <XML_Serializer_Tag>1</XML_Serializer_Tag>
                <XML_Serializer_Tag>1024</XML_Serializer_Tag>
                <XML_Serializer_Tag />
            </args>
        </XML_Serializer_Tag>
        <XML_Serializer_Tag>
            <file>pathToMyDocRoot\cvs.php.net\pear\xml_serializer\examples\serializeandreturn.php</file>
            <line>19</line>
            <function>raiseerror</function>
            <class>pear</class>
            <type>::</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
            </args>
        </XML_Serializer_Tag>
    </backtrace>
    <callback />
</pear_error>

You can find the last version of this source code in the package : serializeAndReturn.php

Build a RDF document

This example shows how to create an RDF document with a few lines of code. This can also be done with mode => simplexml.

In this example look at theses 3 lines.

<?php
$serializer = new XML_Serializer($options);
    $result = $serializer->serialize($rdf);
    echo    htmlentities($serializer->getSerializedData());
?>
<?php
/**
   * @see    serializeIndexedArray.php
   */
    error_reporting(E_ALL);

    require_once 'XML/Serializer.php';

    $options = array(
      "indent"          => "    ",
      "linebreak"       => "\n",
      "typeHints"       => false,
      "addDecl"         => true,
      "encoding"        => "UTF-8",
      "rootName"        => "rdf:RDF",
      "rootAttributes"  => array("version" => "0.91"),
      "defaultTagName"  => "item",
      "attributesArray" => "_attributes"
      );

    $serializer = new XML_Serializer($options);

    $rdf = array(
      "channel" => array(
        "title" => "Example RDF channel",
        "link"  => "http://www.php-tools.de",
        "image" => array(
          "title" => "Example image",
          "url"   => "http://www.php-tools.de/image.gif",
          "link"  => "http://www.php-tools.de"
          ),
        "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" ),
        array(
          "title"       => "Example item",
          "link"    => "http://example.com",
          "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" )
          ),
        array(
          "title"    => "Another item",
          "link"    => "http://example.com",
          "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" )
          ),
        array(
          "title"    => "I think you get it...",
          "link"    => "http://example.com",
          "_attributes" => array( "rdf:about" => "http://example.com/foobar.html" )
          )
        )
      );

    $result = $serializer->serialize($rdf);

    if( $result === true ) {
        echo    "<pre>";
        echo    htmlentities($serializer->getSerializedData());
        echo    "</pre>";
    }
?>

And this is the result

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF version="0.91">
    <channel rdf:about="http://example.com/foobar.html">
        <title>Example RDF channel</title>
        <link>http://www.php-tools.de</link>
        <image>
            <title>Example image</title>
            <url>http://www.php-tools.de/image.gif</url>
            <link>http://www.php-tools.de</link>
        </image>
        <item rdf:about="http://example.com/foobar.html">
            <title>Example item</title>
            <link>http://example.com</link>
        </item>
        <item rdf:about="http://example.com/foobar.html">
            <title>Another item</title>
            <link>http://example.com</link>
        </item>
        <item rdf:about="http://example.com/foobar.html">
            <title>I think you get it...</title>
            <link>http://example.com</link>
        </item>
    </channel>
</rdf:RDF>

You can find the last version of this source code in the package : serializeRDF.php

Note : if you search how to parse (read) an RDF/RSS document, look at XML_RSS package.

Build a XML document with a DTD

This example shows how to add a DocType Declaration to the XML document

In this example look at theses 3 lines.

<?php
$serializer = new XML_Serializer($options);
    $result = $serializer->serialize($rdf);
    echo    htmlentities($serializer->getSerializedData());
?>
<?php
error_reporting(E_ALL);

    require_once 'XML/Serializer.php';

    $options = array(
      "indent"     => "    ",
      "linebreak"  => "\n",
      "addDecl"    => true,
      "addDoctype" => true,
      "doctype"    => array(
        'uri' => 'http://pear.php.net/dtd/package-1.0',
        'id'  => '-//PHP//PEAR/DTD PACKAGE 0.1'
        )
      );

    $serializer = new XML_Serializer($options);

    $foo    =   PEAR::raiseError("Just a test", 1234);

    $result = $serializer->serialize($foo);

    if( $result === true ) {
        echo '<pre>';
        echo htmlentities($serializer->getSerializedData());
        echo '</pre>';
    }
?>

And this is the result

<?xml version="1.0"?>
<!DOCTYPE pear_error PUBLIC "-//PHP//PEAR/DTD PACKAGE 0.1" "http://pear.php.net/dtd/package-1.0">
<pear_error>
    <error_message_prefix />
    <mode>1</mode>
    <level>1024</level>
    <code>1234</code>
    <message>Just a test</message>
    <userinfo />
    <backtrace>
        <XML_Serializer_Tag>
            <file>pathToMyPear\PEAR.php</file>
            <line>566</line>
            <function>pear_error</function>
            <class>pear_error</class>
            <type>-&gt;</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
                <XML_Serializer_Tag>1</XML_Serializer_Tag>
                <XML_Serializer_Tag>1024</XML_Serializer_Tag>
                <XML_Serializer_Tag />
            </args>
        </XML_Serializer_Tag>
        <XML_Serializer_Tag>
            <file>pathToMyDocumentRoot\cvs.php.net\pear\xml_serializer\examples\serializewithdtd.php</file>
            <line>24</line>
            <function>raiseerror</function>
            <class>pear</class>
            <type>::</type>
            <args>
                <XML_Serializer_Tag>Just a test</XML_Serializer_Tag>
                <XML_Serializer_Tag>1234</XML_Serializer_Tag>
            </args>
        </XML_Serializer_Tag>
    </backtrace>
    <callback />
</pear_error>

You can find the last version of this source code in the package : serializeWithDTD.php

Prev | XML_Serializer | Next
XML_Serializer::setOption | PEAR Manual | Tutorial: Create an RSS Feed


Tutorial: Create an RSS Feed

Tutorial: Create an RSS Feed

Tutorial: Create an RSS Feed – How to use XML_Serializer to build an RSS Newsfeed

Mission

Note: This tutorial has been written by cnb and been published on http://freedomink.org/node/62. The site is offline since 2005 and has been rescued using the Internet Archive's Wayback Machine.

Here's how you can create an XML news feed in just five minutes using PHP, PEAR and the PEAR XML_Serializer package by Stephan Schmidt.

What a news feed consists of in it's barest form is your "site name", "site url" and a "listing of stories" from your site. To create a news feed what we need to do is create a publically accessible (web) document which can show this information in a format other sites can understand. This is possible by creating this document in the standard RDF Site Summary (RSS) format. A format used by many sites.

What we are aiming at is creating a document which looks like the following:

Note: This isn't "well formed" XML but a stripped version making it as simple as possible for illustrative purposes. Once we understand the basics we can move on to create well formed XML.
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF>
    <channel>
        <title>Freedom Ink</title>
        <link>http://freedomink.org/</link>
        <item>
            <item>
                <title>First Article</title>
                <link>http://freedomink.org/node/view/55</link>
                <description>Short blurb about article........</description>
            </item>
            <item>
                <title>Second Article</title>
                <link>http://freedomink.org/node/view/11</link>
                <description>This article shows you how ......</description>
            </item>
        </item>
    </channel>
</rdf:RDF>

Do it in PHP

Here's an easy way to do it in PHP.

Prerequisite: Install PEAR and the XML_Serializer package.

Include the following default options at the top of your php page.

<?php
require_once 'XML/Serializer.php';

$options = array(
    "indent"    => "    ",
    "linebreak" => "\n",
    "typeHints" => false,
    "addDecl"   => true,
    "encoding"  => "UTF-8",
    "rootName"   => "rdf:RDF",
    "defaultTagName" => "item"
);
?>

Let us first create an array containing a listing of the stories on your site.

We create array $stories and add one story.

<?php
$stories[] = array(
    'title'       => 'First Article',
    'link'        => 'http://freedomink.org/node/view/55',
    'description' => 'Short blurb about article........'
);
?>

You can add more stories to the array in the same manner. Ideally this should be done in a "for" or "foreach" loop.

<?php
$stories[] = array(
    'title'       => 'Second Article',
    'link'        => 'http://freedomink.org/node/view/11',
    'description' => 'This article shows you how ......'
);
?>

Finally we specify the channel details and add the stories to it.

<?php
$data['channel'] = array(
    "title" => "Freedom Ink",
    "link"  => "http://freedomink.org/",
    $stories
);
?>

Now we generate the XML using the PEAR XML_Serializer package.

<?php
$serializer = new XML_Serializer($options);

if ($serializer->serialize($data)) {
    header('Content-type: text/xml');
    echo $serializer->getSerializedData();
}
?>

And that's it! When a person visits the page containing this code an XML file like the one we saw above will be generated and served.

To learn how to parse XML/RSS files you can read this related article which has by far the easiest method of parsing XML/RSS documents.

Prev | XML_Serializer | Next
Example | PEAR Manual | Class Summary XML_Unserializer


Class Summary XML_Unserializer

Class Summary XML_Unserializer

Class Summary XML_Unserializer – XML_Unserializer - class to unserialize (read) XML documents

XML_Unserializer - class to unserialize (read) XML documents

Class to unserialize XML documents that have been created with XML_Serializer. To unserialize an XML document you have to add type hints to the XML_Serializer options.

If no type hints are available, XML_Unserializer will guess how the tags should be treated, that means complex structures will be arrays and tags with only CData in them will be strings.

Prev | XML_Serializer | Next
Tutorial: Create an RSS Feed | PEAR Manual | XML_Unserializer Options


XML_Unserializer Options

XML_Unserializer Options

XML_Unserializer Options – List of all XML_Unserializer options

Introduction to options

Options let you influence how XML_Unserializer treats the parsed XML. It allows you to define whether attributes should be parsed, whether to use associative arrays or objects for complex data types, and more.

Options can be passed as an associative array to the constructor of XML_Unserializer. You may also use setOption(), or setOptions() to set one or more options after the instance of XML_Unserializer has been created.

All available options

Here is a list of all options supported by XML_Unserializer.

XML_Unserializer options
XML_UNSERIALIZER_OPTION_ Name | Alternate Key for $options Array | Possible values | Default | Description
_COMPLEXTYPE | complexType | 'array' or 'object' | 'array' | Defines whether nested tags should be returned as associative arrays or objects.
_TAG_AS_CLASSNAME | tagAsClass | TRUE or FALSE | TRUE | Defines whether the tag name should be used as the class name if complexType is set to 'object'. If no class with the name of the tag exists, the class defined by 'defaultClass' is used.
_DEFAULT_CLASS | defaultClass | any string | stdClass | Defines the class that is used to create objects, if the complexType option is set to 'object'.
_ATTRIBUTE_KEY | keyAttribute | any string or array | '_originalKey' | If the attribute specified in this option exists for a tag, the value will be used as key or property name in the parent object or array. You may also specify an associative array if you want to use different key attributes for different tags. In this case, the array key contains the tag name and the array value the corresponding attribute name.
_ATTRIBUTE_TYPE | typeAttribute | any string | '_type' | If this attribute exists for a tag, the tag content will be converted to the specified type. Possible types are: string, integer, float, boolean, array, and object.
_ATTRIBUTE_CLASS | classAttribute | any string | '_class' | If XML_Unserializer creates an object, it will be an instance of the value specified with the defaultClass option, unless the tag has the attribute specified in this option. If it is set, the classname stored in the attribute value will be used.
_ATTRIBUTES_PARSE | parseAttributes | TRUE or FALSE | FALSE | With this option, you may tell XML_Unserializer to also parse the attributes of the tags. The next two options define how to treat the parsed attributes.
_ATTRIBUTES_ARRAYKEY | attributesArray | FALSE or any string | FALSE | If set to false, the attributes will be treated like nested tags. If you set it to a string, a new aray will be created and stored in the parent structure using key you specified in this option.
_ATTRIBUTES_PREPEND | prependAttributes | any string | '' | Allows you to specify a prefix for attribute names.
_CONTENT_KEY | contentName | any string | '_content' | If you decide to parse attributes or a tag contains cdata and tags, then the cdata will be stored in the index specified here.
_TAG_MAP | tagMap | associative array | array() | This allows you to map tag names to PHP classes. The names of the tags have to be in the keys and the values contain the class names to use for each tag.
_FORCE_ENUM | forceEnum | indexed array | array() | This allows you to specify a list of tags which will automatically be converted to an indexed array, independent of the number of repetitions of the tag. This can save you some IF conditions in your code.
_ENCODING_SOURCE | encoding | any valid encoding string (accepted by XML_Parser) | null | Defines the encoding of the original document.
_ENCODING_TARGET | targetEncoding | any valid encoding string (accepted by XML_Parser) | null | Defines the target encoding of the resulting data.
_DECODE_FUNC | decodeFunction | any valid PHP callback | null | This option allows you to define a callback function or method, that will be applied to all character data and attributes in the document before they are stored in the result. This allows you to decode any decoded data in the XML or convert all content to lowercase.
_RETURN_RESULT | returnResult | TRUE or FALSE | FALSE | If set to TRUE XML_Unserializer::unserialize() will return the result if the document could be unserialized instead of just TRUE.
_WHITESPACE | whitespace | OPTIONs _WHITESPACE_KEEP, _WHITESPACE_TRIM, or _WHITESPACE_NORMALIZE | _WHITESPACE_TRIM | Defines how whitespace in the document will be treated: keep it all, trim it, or normalize it.
_IGNORE_KEYS | ignoreKeys | any array | array() | List of tags whose contents will be passed to the parent tag instead of creating a new tag.
_GUESS_TYPES | guessTypes | TRUE or FALSE | FALSE | Whether or not to enable automatic type guessing for character data and attributes.
_OVERRIDE_OPTIONS | overrideOptions | TRUE or FALSE | FALSE | Allows you to override the options already set on this unserializer object.

Options via XML_UNSERIALIZER_OPTION Constants example

The following examples shows how to set options for XML_Unserializer, using the available XML_UNSERIALIZER_OPTION constants.

Using the constructor

<?php
require_once "XML/Unserializer.php";
$options = array(
    XML_UNSERIALIZER_OPTION_COMPLEXTYPE => 'array'
);

$us = new XML_Unserializer($options);
$result = $us->unserialize('example.xml', true);
?>

The following example shows how to set options for XML_Unserializer, using the available XML_UNSERIALIZER_OPTION constants, if the instance already has been created.

Using setOption() and setOptions()

<?php
require_once "XML/Unserializer.php";
$us = new XML_Unserializer();
$options = array(
    XML_UNSERIALIZER_OPTION_TAG_MAP         => array( 'util' => 'XML_Util' ),
    XML_UNSERIALIZER_OPTION_ATTRIBUTE_CLASS => '_classname'
);

$us->setOptions($options);
$us->setOption(XML_UNSERIALIZER_OPTION_COMPLEXTYPE, 'object');
$result = $us->unserialize('example.xml', true);
?>

Options via $options examples

The following example shows how to set options for XML_Unserializer, using an $options array.

Using the constructor

<?php
require_once "XML/Unserializer.php";
$options = array(
    'complexType' => 'array'
);

$us = new XML_Unserializer($options);
$result = $us->unserialize('example.xml', true);
?>

The following example shows how to set options for XML_Unserializer, using an $options array, if the instance already has been created.

Using setOption() and setOptions()

<?php
require_once "XML/Unserializer.php";
$us = new XML_Unserializer();
$options = array(
    'tagMap'         => array( 'util' => 'XML_Util' ),
    'classAttribute' => '_classname'
);

$us->setOptions($options);
$us->setOption('complexType', 'object');
$result = $us->unserialize('example.xml', true);
?>
Prev | XML_Serializer | Next
Class Summary XML_Unserializer | PEAR Manual | XML_Unserializer::XML_Unserializer


XML_Unserializer::XML_Unserializer

XML_Unserializer::XML_Unserializer

XML_Unserializer::XML_Unserializer() – Constructor for XML_Unserializer

Synopsis

require_once 'Unserializer.php';

XML_Unserializer::XML_Unserializer ( array $options = null )

Description

Creates a new instance of XML_Unserializer.

Parameter

  • array $options - Options for the instance. Can also be set using XML_Unserializer::setOption()

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer Options | PEAR Manual | XML_Unserializer::apiVersion


XML_Unserializer::apiVersion

XML_Unserializer::apiVersion

XML_Unserializer::apiVersion() – return API version

Synopsis

require_once 'Unserializer.php';

string XML_Unserializer::apiVersion ( )

Description

Returns API version of XML_Unserializer. This may be useful to check if the needed functionality exists.

Return value

string API version

Note

This function can be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::XML_Unserializer | PEAR Manual | XML_Unserializer::unserialize


XML_Unserializer::unserialize

XML_Unserializer::unserialize

XML_Unserializer::unserialize() – unserialize data

Synopsis

require_once 'Unserializer.php';

boolean XML_Unserializer::unserialize ( string $data , boolean $isFile = false , array $options = null )

Description

Unserialize an XML document from a string or a file.

The way the document is unserialized is influenced by the options you set in the constructor or with setOptions().

Parameter

  • string $data - either the file name of an XML document or a string containing the XML document.

  • boolean $isFile - indicates whether the first parameter should is a filename (TRUE) or an XML string (FALSE).

  • array $options - Options to override the options that have been set previously. The options will only be used for this unserialization and then reset the options you set before.

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::apiVersion | PEAR Manual | XML_Unserializer::getUnserializedData


XML_Unserializer::getUnserializedData

XML_Unserializer::getUnserializedData

XML_Unserializer::getUnserializedData() – get the result of the unserialization

Synopsis

require_once 'Unserializer.php';

string XML_Unserializer::getUnserializedData ( )

Description

This method returns the result of the last unserialization. You have to call XML_Unserializer::unserialize() first.

Return value

mixed result of the unserialization. May either be an array or an object.

Throws

throws PEAR_Error object, if not document has been parsed.

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::unserialize | PEAR Manual | XML_Unserializer::getRootName


XML_Unserializer::getRootName

XML_Unserializer::getRootName

XML_Unserializer::getRootName() – get the name of the root tag of the parsed document.

Synopsis

require_once 'Unserializer.php';

string XML_Unserializer::getRootName ( )

Description

This method will return the name of the root tag, after a document has been unserialized. This can be extremely useful when returning an array. You have to call XML_Unserializer::unserialize() first.

Return value

string name of the root tag

Throws

throws PEAR_Error object, if not document has been parsed.

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::getUnserializedData | PEAR Manual | XML_Unserializer::setOption


XML_Unserializer::setOption

XML_Unserializer::setOption

XML_Unserializer::setOption() – set an option

Synopsis

require_once 'Unserializer.php';

void XML_Unserializer::setOption ( string $name , mixed $value )

Description

Options influence the behaviour of XML_Unserializer and are the most important part of XML_Unserializer.

You can use this method if you do not want to set all options in the constructor.

Parameter

  • string $option - name of the option

  • mixed $value - value of the option

See

see XML_Unserializer::resetOptions()

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::getRootName | PEAR Manual | XML_Unserializer::setoptions


XML_Unserializer::setoptions

XML_Unserializer::setoptions

XML_Unserializer::setoptions() – set several options

Synopsis

require_once 'Unserializer.php';

void XML_Unserializer::setOptions ( array $options )

Description

Options influence the behaviour of XML_Unserializer and are the most important part of XML_Unserializer.

You can use this method if you do not want to set all options in the constructor.

Parameter

  • array $options - assoc array containing all options

See

see XML_Unserializer::resetOptions(), XML_Unserializer::setOption()

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::setOption | PEAR Manual | XML_Unserializer::resetOptions


XML_Unserializer::resetOptions

XML_Unserializer::resetOptions

XML_Unserializer::resetOptions() – reset all options to default options

Synopsis

require_once 'Unserializer.php';

void XML_Unserializer::resetOptions ( )

Description

Resets all XML_Unserializer options to the default options.

See

see XML_Unserializer::setOption() and XML_Unserializer::XML_Unserializer() on how to set options.

Note

This function can not be called statically.

Prev | XML_Serializer | Next
XML_Unserializer::setoptions | PEAR Manual | XML_sql2xml


XML_sql2xml

XML_sql2xml

Translates SQL-Queries to XML-Resultsets.

XML_sql2xml takes an existing result set or a SQL statement and transforms it to an XML representation

Table of Contents
  • Introduction -- Simple transformations
  • Introduction -- Passing the data to transform
  • Introduction -- Using XPath
  • XML_sql2xml::XML_sql2xml -- Constructor
  • XML_sql2xml::add -- General method for adding new result sets
  • XML_sql2xml::addXmlFile -- Adds a XML file
  • XML_sql2xml::addXmlString -- Adds XML string
  • XML_sql2xml::addResult -- Adds an PEAR::DB result set
  • XML_sql2xml::addSql -- Adds an result set from a SQL statement
  • XML_sql2xml::addArray -- Adds an aditional result set from an array
  • XML_sql2xml::getXML -- Returns a XML representation of the result set.
  • XML_sql2xml::getXMLObject -- return an XML DomDocument object
  • XML_sql2xml::setOptions -- set options for the instance
  • XML_sql2xml::setEncoding -- set encoding charset
  • XML_sql2xml::getXpathValue -- return match of a XPath expression
  • XML_sql2xml::getXpathChildValues -- return child tags from match of a XPath expression
Prev | XML | Next
XML_Unserializer::resetOptions | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Simple transformations

Example database

In this tutorial, the examples refers to this database tables:

mysql> select * from bands;
+----+--------------+------------+-------------+-------------+
| id | name | birth_year | birth_place | genre |
+----+--------------+------------+-------------+-------------+
| 1 | The Blabbers | 1998 | London | Rock'n'Roll |
| 2 | Only Stupids | 1997 | New York | Hip Hop |
+----+--------------+------------+-------------+-------------+

mysql> select * from albums;
+----+---------+------------------+------+-----------------+
| id | bandsID | title | year | comment |
+----+---------+------------------+------+-----------------+
| 1 | 1 | BlaBla | 1998 | Their first one |
| 2 | 1 | More Talks | 2000 | The second one |
| 3 | 2 | All your base... | 1999 | The Classic |
+----+---------+------------------+------+-----------------+

The typical using

Let's start with an example using the default options. The new instance is bind to an DSN, so you have only to provide an SQL query. The instance fetches the result automatically; in $xmlstring you found the XML representation of the result set.

The simplest example

<?php
require_once "XML/sql2xml.php";
$sql2xmlclass = new xml_sql2xml("mysql://username:password@localhost/xmltest");
$xmlstring = $sql2xmlclass->getxml("select * from bands");
?>

The content of $xmlstring based on the DB tables above is:

<?xml version="1.0"?>
<root>
<result>
<row>
<id>1</id>
<name>The Blabbers</name>
<birth_year>1998</birth_year>
<birth_place>London</birth_place>
<genre>Rock'n'Roll</genre>
</row>
<row>
<id>2</id>
<name>Only Stupids</name>
<birth_year>1997</birth_year>
<birth_place>New York</birth_place>
<genre>Hip Hop</genre>
</row>
</result>
</root>

Transformations based on Join queries

If your query result base on joined tables, a nested XML data structure can represent how the DBMS joins the tables. To enable or to disable this behavoir use setOptions() with the option key 'nested' . The default value is TRUE - the nesting is enabled.

Nested result set

<?php
$sql2xmlclass = new xml_sql2xml("mysql://username:password@localhost/xmltest");
$xmlstring = $sql2xmlclass->getxml("select * from bands left join albums on bands.id = bandsID");
?>

The generated XML output in $xmlstring :

<?xml version="1.0"?>
<root>
<result>
<row>
<id>1</id>
<name>The Blabbers</name>
<birth_year>1998</birth_year>
<birth_place>London</birth_place>
<genre>Rock'n'Roll</genre>
<row>
<id>1</id>
<bandsID>1</bandsID>
<title>BlaBla</title>
<year>1998</year>
<comment>Their first one</comment>
</row>
<row>
<id>2</id>
<bandsID>1</bandsID>
<title>More Talks</title>
<year>2000</year>
<comment>The second one</comment>
</row>
</row>
<row>
<id>2</id>
<name>Only Stupids</name>
<birth_year>1997</birth_year>
<birth_place>New York</birth_place>
<genre>Hip Hop</genre>
<row>
<id>3</id>
<bandsID>2</bandsID>
<title>All your base...</title>
<year>1999</year>
<comment>The Classic</comment>
</row>
</row>
</result>
</root>

If you disable the nesting, the XML structure of rows is flat.

Unnested result sets

<?php
$sql2xmlclass = new xml_sql2xml("mysql://username:password@localhost/xmltest");
$options      = array('nested' => false);
$sql2xmlclass->setOptions($options);
$xmlstring    = $sql2xmlclass->getxml("select * from bands left join albums on bands.id = bandsID");
?>

XML output:

$xmlstring =>

<?xml version="1.0"?>
<root>
<result>
<row>
<id>1</id>
<name>The Blabbers</name>
<birth_year>1998</birth_year>
<birth_place>London</birth_place>
<genre>Rock'n'Roll</genre>
<id>1</id>
<bandsID>1</bandsID>
<title>BlaBla</title>
<year>1998</year>
<comment>Their first one</comment>
</row>
<row>
<id>1</id>
<name>The Blabbers</name>
<birth_year>1998</birth_year>
<birth_place>London</birth_place>
<genre>Rock'n'Roll</genre>
<id>2</id>
<bandsID>1</bandsID>
<title>More Talks</title>
<year>2000</year>
<comment>The second one</comment>
</row>
<row>
<id>2</id>
<name>Only Stupids</name>
<birth_year>1997</birth_year>
<birth_place>New York</birth_place>
<genre>Hip Hop</genre>
<id>3</id>
<bandsID>2</bandsID>
<title>All your base...</title>
<year>1999</year>
<comment>The Classic</comment>
</row>
</result>
</root>
Prev | XML_sql2xml | Next
XML_sql2xml | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Passing the data to transform

Overview

There are three ways to pass the data for transforming to the object:

  • with a direct query

    This way you see in the first part of the introduction already.

  • with an existing DB_result object

    If you need the full power of the PEAR::DB or PEAR::MDB API, you should choose this way.

  • with an array

    This is not directly an SQL to XML transformation; if you pass an indice array to the instance, the keys of the array are transformed into XML tags, their values into the tag content. This feature his helpful for adding data to an XML transformed result set.

Direct query

This behavoir does connecting to the DBMS, quering and fetching he result automatically. XML_sql2xml requires an valid DSN as construtor parameter. The query has to be passed to the getXML() or add() method.

Take a look into the first part of the introduction for examples.

Passing an DB_Result object

PEAR::DB and PEAR::MDB return the result set of a query as DB_result object. You have to provide a DB_common instance to the construtor and the DB_result instance to getXML() or add().

Passing a DB_Result object

<?php
require_once "XML/sql2xml.php";
require_once "DB.php";

$db = db::connect("mysql://username:password@localhost/xmltest");
$result = $db->query("select * from bands");

$sql2xmlclass = new xml_sql2xml($db);
$xmlstring = $sql2xmlclass->getxml($result);
?>

The XML output in $xmlstring is equal to the example in "The typical using".

This way is the only one, if you want to benefit from all the features of the database APIs.

Passing an array

If you pass an nested array to getXML() or add(), it will be transformed into an XML document.

Passing an array

<?php
require_once "XML/sql2xml.php";

$sql2xmlclass = new xml_sql2xml();

$array = array (
            array("name"=>"The Blabbers",
                  "birth_year"=>"1998",
                  "birth_place"=>"London",
                  "genre"=>"Rock'n'Roll"),
            array("name"=>"Only Stupids",
                  "birth_year"=>"1997",
                  "birth_place"=>"New York",
                  "genre"=>"hiphop")
);

$xmlstring = $sql2xmlclass->getXML($array);
?>

The XML output in $xmlstring :

<?xml version="1.0"?>
    <root>
        <result>
            <row>
                <name>The Blabbers</name>
                <birth_year>1998</birth_year>
                <birth_place>London</birth_place>
                <genre>Rock'n'Roll</genre>
            </row>
            <row>
                <name>Only Stupids</name>
                <birth_year>1997</birth_year>
                <birth_place>New York</birth_place>
                <genre>hiphop</genre>
            </row>
        </result>
    </root>

Passing more then one result set

You can call add() several result sets to XML document. Just call the method for every result set; if you have added all result sets, call getXml() without any arguments to get the XML document.

Adding result sets

<?php
$sql2xmlclass->add("select * from bands");
$sql2xmlclass->add("select * from albums");
$xmlstring= $sql2xmlclass->getxml();
?>
Prev | XML_sql2xml | Next
Introduction | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Using XPath

Why XPath support?

The XPath support was introduced to provide an access to the result set after doing the SQL query. This allows further proccessing of the result set without quering the database again.

XPath is a W3-Standard and for further information about that, ask your preferred XSL/XML book, or http://www.w3.org/.

Passing an XPath expression

XML_sql2xml provides two functions for querying the result set: getXpathValue() and getXpathChildValues(). Both expect a XPath query and return the result as string or array.

getXpathValue

<?php
include_once("XML/sql2xml.php");
$sql2xmlclass = new xml_sql2xml("mysql://username:password@localhost/xmltest");
$sql2xmlclass->add("select * from bands");
$xmlstring  = $sql2xmlclass->getXpathValue("/root/result/row[id = '2']/name");
?>

$xmlstring contains:

$xmlstring = 'Only Stupids'

getXpathChildValues

<?php
include_once("XML/sql2xml.php");
$sql2xmlclass = new xml_sql2xml("mysql://username:password@localhost/xmltest");
$sql2xmlclass->add("select * from bands");
$xmlstring  = $sql2xmlclass->getXpathChildValues("/root/result/row[id = '2']");
?>

$xmlstring contains:

Array
(
[] =>
[id] => 2
[name] => Only Stupids
[birth_year] => 1997
[birth_place] => New York
[genre] => Hip Hop
)

Mixing SQL and XPath query

You can insert an XPath query into an SQL query. In the example, first a SQL query is done, in the second a SQL query done again - but the parameter for bandsID is taken from the XPath expression in the curly braces. This expression is processed on the result set of the first SQL query.

Mixed query

<?php
include_once("XML/sql2xml.php");
$sql2xmlclass = new xml_sql2xml("mysql://username:password@localhost/xmltest");
$sql2xmlclass->add("select * from bands");
$sql2xmlclass->add("select * from albums where bandsID = {/root/result/row[name = 'The Blabbers']/id}");
$xmlstring = $sql2xmlclass->getxml();
?>

$xmlstring = '

<?xml version="1.0"?>
<root>
<result>
<row>
<id>1</id>
<name>The Blabbers</name>
<birth_year>1998</birth_year>
<birth_place>London</birth_place>
<genre>Rock'n'Roll</genre>
</row>
<row>
<id>2</id>
<name>Only Stupids</name>
<birth_year>1997</birth_year>
<birth_place>New York</birth_place>
<genre>Hip Hop</genre>
</row>
</result>
<result>
<row>
<id>1</id>
<bandsID>1</bandsID>
<title>BlaBla</title>
<year>1998</year>
<comment>Their first one</comment>
</row>
<row>
<id>2</id>
<bandsID>1</bandsID>
<title>More Talks</title>
<year>2000</year>
<comment>The second one</comment>
</row>
</result>
</root>
Prev | XML_sql2xml | Next
Introduction | PEAR Manual | XML_sql2xml::XML_sql2xml


XML_sql2xml::XML_sql2xml

XML_sql2xml::XML_sql2xml

XML_sql2xml::XML_sql2xml – Constructor

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::XML_sql2xml ( mixed $dsn = null , string $root="root" )

Description

The Constructor can take a Pear::DB Data Source Name (DSN) and will then connect to the database; or a PEAR::DB object handle, if you already connected the database before. Providing sql-strings will not work.

If you provide only a DSN, you have to add a DB_result object, SQL statement or an array later.

The $root parameter is used, if you want to provide another name for your root-tag than <root>. If you give an empty string (""), there will be no root element created here, but only when you add a resultset, array or SQL Statement. And the first tag of this result is used as the root tag.

Parameter

  • mixed $dsn - PEAR::DB "data source name" or DB_common object

  • string $root - the name of the XML-root element.

Note

This function can be called statically.

See

XML_sql2xml::add()

Example

Using XML_sql2xml()

<?php
$sql2xml = new xml_sql2xml("mysql://root@localhost/xmltest");
$sql2xml->Add("select * from bands");
?>
Prev | XML_sql2xml | Next
Introduction | PEAR Manual | XML_sql2xml::add


XML_sql2xml::add

XML_sql2xml::add

XML_sql2xml::add – General method for adding new result sets

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::add ( string $resultset , mixed $params = null )

Description

General method for adding new result sets to the object. Give a SQL statement, a PEAR::DB_result object or an array as input parameter and the method calls the appropriate method for this input.

Parameter

  • string $resultset - SQL statement, an DB_result object or an array

  • mixed $params - parameters for the following functions

Note

This function can not be called statically.

See

XML_sql2xml::addResult(),

XML_sql2xml::addSql(),

XML_sql2xml::addArray(),

XML_sql2xml::addXmlFile()

Example

Using add()

<?php
$sql2xml->Add("select * from bands");
?>
Prev | XML_sql2xml | Next
XML_sql2xml::XML_sql2xml | PEAR Manual | XML_sql2xml::addXmlFile


XML_sql2xml::addXmlFile

XML_sql2xml::addXmlFile

XML_sql2xml::addXmlFile – Adds a XML file

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::addXmlFile ( string $file , mixed $xpath = null )

Description

Adds the content of a XML file on the same level as a normal result set (mostly just below <root>).

Parameter

  • string $file - file name

  • mixed $xpath - either a string with the XPath expression or an array with the keys "xpath"=>XPath expression and "root"=>tag/subtag/etc, which are the tags to be inserted before the result.

Note

This function can not be called statically.

See

XML_sql2xml::add()

Prev | XML_sql2xml | Next
XML_sql2xml::add | PEAR Manual | XML_sql2xml::addXmlString


XML_sql2xml::addXmlString

XML_sql2xml::addXmlString

XML_sql2xml::addXmlString – Adds XML string

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::addXmlString ( string $string , mixed $xpath = null )

Description

Adds the content of a xml-string on the same level as a normal result set (mostly just below <root>)

Parameter

  • string $string - XML string

  • mixed $xpath - either a string with the XPath expression or an array with the keys "xpath"=>XPath expression and "root"=>tag/subtag/etc, which are the tags to be inserted before the result.

Note

This function can not be called statically.

See

XML_sql2xml::add()

Prev | XML_sql2xml | Next
XML_sql2xml::addXmlFile | PEAR Manual | XML_sql2xml::addResult


XML_sql2xml::addResult

XML_sql2xml::addResult

XML_sql2xml::addResult – Adds an PEAR::DB result set

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::addResult ( Object $result )

Description

Adds an additional PEAR::DB_result result set

Parameter

  • Object $result - a DB_result object

Note

This function can not be called statically.

See

XML_sql2xml::add()

Prev | XML_sql2xml | Next
XML_sql2xml::addXmlString | PEAR Manual | XML_sql2xml::addSql


XML_sql2xml::addSql

XML_sql2xml::addSql

XML_sql2xml::addSql – Adds an result set from a SQL statement

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::addSql ( string $sql )

Description

Adds an aditional result set generated from an SQL statement. The function executes the statement and transform it into XML. You have to pass an DSN to the constructor.

Parameter

  • string $sql - a string containing an SQL statement.

Note

This function can not be called statically.

See

XML_sql2xml::XML_sql2xml(), XML_sql2xml::add()

Prev | XML_sql2xml | Next
XML_sql2xml::addResult | PEAR Manual | XML_sql2xml::addArray


XML_sql2xml::addArray

XML_sql2xml::addArray

XML_sql2xml::addArray – Adds an aditional result set from an array

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::addArray ( array $array )

Description

Adds an aditional result set generated from an array. The XML represents the nesting of the array.

Parameter

  • array $array - data array

Note

This function can not be called statically.

See

XML_sql2xml::add()

Prev | XML_sql2xml | Next
XML_sql2xml::addSql | PEAR Manual | XML_sql2xml::getXML


XML_sql2xml::getXML

XML_sql2xml::getXML

XML_sql2xml::getXML – Returns a XML representation of the result set.

Synopsis

require_once "XML/sql2xml.php";

string XML_sql2xml::getXML ( mixed $result = null )

Description

Returns an XML string with a XML representation of the result set. The result set can be directly provided here, or if you need more than one in your XML, then you have to provide each of them with add() before you call getXML(), but the last one can also be provided here.

Parameter

  • mixed $result - a DB_result object from a DB query or a SQL query

Return value

string - the XML string

Note

This function can not be called statically.

Prev | XML_sql2xml | Next
XML_sql2xml::addArray | PEAR Manual | XML_sql2xml::getXMLObject


XML_sql2xml::getXMLObject

XML_sql2xml::getXMLObject

XML_sql2xml::getXMLObject – return an XML DomDocument object

Synopsis

require_once "XML/sql2xml.php";

Object XML_sql2xml::getXMLObject ( mixed $result = null )

Description

Returns an XML DomDocument object with a XML representation of the result sets. The result set can be directly provided here, or if you need more than one in your XML, then you have to provide each of them with add() before you call getXMLObject(), but the last one can also be provided here.

Parameter

  • mixed $result - a DB_result object from a DB query

Return value

Object - DomDocument object

Note

This function can not be called statically.

Prev | XML_sql2xml | Next
XML_sql2xml::getXML | PEAR Manual | XML_sql2xml::setOptions


XML_sql2xml::setOptions

XML_sql2xml::setOptions

XML_sql2xml::setOptions – set options for the instance

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::setOptions ( array $options , constant $delete = false )

Description

This method sets the options for the class instance.

Parameter

  • array $options - array of options. The array key defines the option to set. Avaible options are:

    • boolean $options['nested'] - if TRUE the result of an join query will be nested. The default value is FALSE.

    • boolean $options['tagNameRow'] - name for the row mark up tag. Default is >row<

    • boolean $options['tagNameResult'] - name for the result-set mark up tag. Default is >result<

  • constant $delete - the old sub options should be deleted

Note

This function can not be called statically.

Prev | XML_sql2xml | Next
XML_sql2xml::getXMLObject | PEAR Manual | XML_sql2xml::setEncoding


XML_sql2xml::setEncoding

XML_sql2xml::setEncoding

XML_sql2xml::setEncoding – set encoding charset

Synopsis

require_once "XML/sql2xml.php";

void XML_sql2xml::setEncoding ( string $encoding_from="ISO-8859-1" , string $encoding_to="UTF-8" )

Description

Sets the encoding for the db2xml transformation. The $encoding_from value depends on your database system; check the DBMS manual which encoding your system use to deliever result sets.

The $encoding_to sets the charset for the created XML document.

Parameter

  • string $encoding_from - encoding to transform from

  • string $encoding_to - encoding to transform to

Note

This function can not be called statically.

Prev | XML_sql2xml | Next
XML_sql2xml::setOptions | PEAR Manual | XML_sql2xml::getXpathValue


XML_sql2xml::getXpathValue

XML_sql2xml::getXpathValue

XML_sql2xml::getXpathValue – return match of a XPath expression

Synopsis

require_once "XML/sql2xml.php";

mixed XML_sql2xml::getXpathValue ( string $expr )

Description

Returns the content of the first match of the XPath expression.

Parameter

  • string $expr - XPath expression

Return value

mixed - content of the evaluated XPath expression

Note

This function can not be called statically.

See

XML_sql2xml::getXpathChildValues()

Prev | XML_sql2xml | Next
XML_sql2xml::setEncoding | PEAR Manual | XML_sql2xml::getXpathChildValues


XML_sql2xml::getXpathChildValues

XML_sql2xml::getXpathChildValues

XML_sql2xml::getXpathChildValues – return child tags from match of a XPath expression

Synopsis

require_once "XML/sql2xml.php";

array XML_sql2xml::getXpathChildValues ( string $expr )

Description

Returns the values from the child tags from the first match of the XPath.

Parameter

  • string $expr - XPath expression

Return value

array - the content of the child tags. The child tag name is assigned as key, the content as value.

Note

This function can not be called statically.

See

XML_sql2xml::getXpathValue()

Prev | XML_sql2xml | Next
XML_sql2xml::getXpathValue | PEAR Manual | XML_Statistics


XML_Statistics

XML_Statistics

Package to statistically analyze an XML document.

Table of Contents
  • Introduction -- Introduction to XML_Statistics
  • Example -- Example for the usage of XML_Statistics
  • XML_Statistics::apiVersion -- return API version
  • XML_Statistics::analyzeFile -- Analyze an XML file
  • XML_Statistics::analyzeString -- Analyze an XML string
  • XML_Statistics::countTag -- count the occurences of a tag
  • XML_Statistics::countTagsInDepth -- count the tags in a certain depth
  • XML_Statistics::countPI -- count the occurences of a processing instruction
  • XML_Statistics::countExternalEntity -- count the occurences of an external entitity
  • XML_Statistics::getMaxDepth -- get the maximum nesting level
  • XML_Statistics::countAttribute -- count the occurences of an attribute
  • XML_Statistics::countDataChunks -- count the occurences of a data blocks
  • XML_Statistics::getCDataLength -- get the combined length of all CData sections
Prev | XML | Next
XML_sql2xml::getXpathChildValues | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_Statistics

Introduction to XML_Statistics

XML_Statistics is a package that allows you to analyze XML documents, which can be files or strings.

XML_Statistics is able to count tags, attributes, processing instructions, external entities and cdata blocks. Furthermore you can apply filters so you are able to count only the tags in a specific depth or only the attributes of a specific tag.

Prev | XML_Statistics | Next
XML_Statistics | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_Statistics

Usage example

The following examples shows how XML_Statistics can be used to analyze a document.

Basic example

<?php
require_once "XML/Statistics.php";
$stat = new XML_Statistics(array("ignoreWhitespace" => true));
$result = $stat->analyzeFile("example.xml");

if ($stat->isError($result)) {
    die("Error: " . $result->getMessage());
}

// total amount of tags:
echo "Total tags: " . $stat->countTag() . "<br />";

// count amount of 'title' attribute, in all tags
echo "Occurences of attribute title: " . $stat->countAttribute("title") . "<br />";

// count amount of 'title' attribute, only in <section> tags
echo "Occurences of attribute title in tag section: " . $stat->countAttribute("title", "section") . "<br />";

// count total number of tags in depth 4
echo "Amount of Tags in depth 4: " . $stat->countTagsInDepth(4) . "<br />";

echo "Occurences of PHP Blocks: " . $stat->countPI("PHP") . "<br />";

echo "Occurences of external entity 'bar': " . $stat->countExternalEntity("bar") . "<br />";

echo "Data chunks: " . $stat->countDataChunks() . "<br />";

echo "Length of all data chunks: " . $stat->getCDataLength() . "<br />";
?>
Prev | XML_Statistics | Next
Introduction | PEAR Manual | XML_Statistics::apiVersion


XML_Statistics::apiVersion

XML_Statistics::apiVersion

XML_Statistics::apiVersion() – return API version

Synopsis

require_once 'XML/Statistics.php';

string XML_Statistics::apiVersion ( )

Description

Returns API version of XML_Statistics.

Return value

string API version

Note

This function can be called statically.

Prev | XML_Statistics | Next
Example | PEAR Manual | XML_Statistics::analyzeFile


XML_Statistics::analyzeFile

XML_Statistics::analyzeFile

XML_Statistics::analyzeFile() – Analyze an XML file

Synopsis

require_once 'XML/Statistics.php';

string XML_Statistics::analyzeFile ( string $filename )

Description

Analyzes an XML document by reading from a file. You have to analyze a document before you can extract any statistical information.

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

See

XML_Statistics::analyzeString()

Prev | XML_Statistics | Next
XML_Statistics::apiVersion | PEAR Manual | XML_Statistics::analyzeString


XML_Statistics::analyzeString

XML_Statistics::analyzeString

XML_Statistics::analyzeString() – Analyze an XML string

Synopsis

require_once 'XML/Statistics.php';

string XML_Statistics::analyzeString ( string $string )

Description

Analyzes an XML document directly from a string. This can be useful if your documents are created on the fly by any other application. You have to analyze a document before you can extract any statistical information.

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function can not be called statically.

See

XML_Statistics::analyzeFile()

Prev | XML_Statistics | Next
XML_Statistics::analyzeFile | PEAR Manual | XML_Statistics::countTag


XML_Statistics::countTag

XML_Statistics::countTag

XML_Statistics::countTag() – count the occurences of a tag

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::countTag ( string $tagname = null )

Description

Counts how often a certain tag is used in the document. If no tagname is specified ot will count the total number of tags.

Parameter

  • string $tagname - name of the tag to count

Return value

integer occurences of the tag

Note

This function can not be called statically.

See

XML_Statistics::countTagsInDepth(), XML_Statistics::countAttribute()

Prev | XML_Statistics | Next
XML_Statistics::analyzeString | PEAR Manual | XML_Statistics::countTagsInDepth


XML_Statistics::countTagsInDepth

XML_Statistics::countTagsInDepth

XML_Statistics::countTagsInDepth() – count the tags in a certain depth

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::counttagsindepth ( integer $depth )

Description

Thru nesting a tag can be at a certain depth. The root tag is at depth zero. By counting the amount of tags in a depth you can count the number of recordsets in an XML document.

Parameter

  • integer $depth - tag depth (0 is root)

Return value

integer number of tags in this depth

Note

This function can not be called statically.

See

XML_Statistics::countTag()

Prev | XML_Statistics | Next
XML_Statistics::countTag | PEAR Manual | XML_Statistics::countPI


XML_Statistics::countPI

XML_Statistics::countPI

XML_Statistics::countPI() – count the occurences of a processing instruction

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::countPI ( string $target = null )

Description

Counts how often a certain processing instruction (e.g. <?PHP) is used in the document. The target is the 'language' of the processing instruction. You only need to specify the name, without the leading question mark. If no target is specified it will count the total number of processing instructions.

Parameter

  • string $target - target of the processing instruction

Return value

integer occurences of the processing instruction

Note

This function can not be called statically.

Prev | XML_Statistics | Next
XML_Statistics::countTagsInDepth | PEAR Manual | XML_Statistics::countExternalEntity


XML_Statistics::countExternalEntity

XML_Statistics::countExternalEntity

XML_Statistics::countExternalEntity() – count the occurences of an external entitity

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::countExternalEntity ( string $name = null )

Description

Counts how often a certain external is used in the document. If no name is specified ot will count the total number of external entities.

Parameter

  • string $name - name of the external entity, without '&' and ';'

Return value

integer occurences of the external entity

Note

This function can not be called statically.

Prev | XML_Statistics | Next
XML_Statistics::countPI | PEAR Manual | XML_Statistics::getMaxDepth


XML_Statistics::getMaxDepth

XML_Statistics::getMaxDepth

XML_Statistics::getMaxDepth() – get the maximum nesting level

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::getMaxDepth ( )

Description

The nesting level of a document tells you the maximum depth of the tags in the document.

Parameter

This method does not accept any parameters.

Return value

integer maximum nesting level.

Note

This function can not be called statically.

Prev | XML_Statistics | Next
XML_Statistics::countExternalEntity | PEAR Manual | XML_Statistics::countAttribute


XML_Statistics::countAttribute

XML_Statistics::countAttribute

XML_Statistics::countAttribute() – count the occurences of an attribute

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::countAttribute ( string $attribute = null , string $tagname = null )

Description

Counts how often a certain attribute is used in the document. If no attribute is specified ot will count the total number of tags.

With the second parameter you may limit the search to a special tag.

Parameter

  • string $attribute - if no attribute name is supplied, all attributes are counted

  • string $tagname - this allows you to limit your search to a tag

Return value

integer occurences of the attribute or a PEAR_Error if the attribute could not be found.

Note

This function can not be called statically.

See

XML_Statistics::countTag()

Prev | XML_Statistics | Next
XML_Statistics::getMaxDepth | PEAR Manual | XML_Statistics::countDataChunks


XML_Statistics::countDataChunks

XML_Statistics::countDataChunks

XML_Statistics::countDataChunks() – count the occurences of a data blocks

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::countDataChunks ( )

Description

This is influenced by the 'ignoreWhitespace' option. Furthermore a new chunk is counted when the parser find a linebreak or internal entity.

Parameter

This method does not accept any parameters.

Return value

integer number of data chunks in the document

Note

This function can not be called statically.

See

XML_Statistics::getCDataLength()

Prev | XML_Statistics | Next
XML_Statistics::countAttribute | PEAR Manual | XML_Statistics::getCDataLength


XML_Statistics::getCDataLength

XML_Statistics::getCDataLength

XML_Statistics::getCDataLength() – get the combined length of all CData sections

Synopsis

require_once 'XML/Statistics.php';

integer XML_Statistics::getCDataLength ( )

Description

If you need to know how many chars you have between your tags, this is the method that gets it.

Parameter

This method does not accept any parameters.

Return value

integer total length of all CData blocks in the XML document

Note

This function can not be called statically.

See

XML_Statistics::countDataChunks()

Prev | XML_Statistics | Next
XML_Statistics::countDataChunks | PEAR Manual | XML_Transformer


XML_Transformer

XML_Transformer

XML Transformations in PHP.

Table of Contents
  • Introduction -- Introduction to XML_Transformer
  • XML_Transformer::XML_Transformer -- parameters
  • XML_Transformer::overloadElement -- element
  • XML_Transformer::overloadNamespace -- namespacePrefix
  • XML_Transformer::isOverloadedElement -- element
  • XML_Transformer::isOverloadedNamespace -- namespacePrefix
  • XML_Transformer::unOverloadElement -- element
  • XML_Transformer::unOverloadNamespace -- namespacePrefix
  • XML_Transformer::start
  • XML_Transformer::transform -- xml
  • XML_Transformer::setCaseFolding -- caseFolding
  • XML_Transformer::setDebug -- debug
  • XML_Transformer::setDebug -- recursiveOperation
  • XML_Transformer::stackdump
  • XML_Transformer::attributesToString -- attributes
  • XML_Transformer::canonicalize -- target
Prev | XML | Next
XML_Statistics::getCDataLength | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_Transformer

Introduction to XML_Transformer

With the XML Transformer class one can easily bind PHP functionality to XML tags, thus transforming the input XML tree into an output XML tree without the need for XSLT. Single XML elements can be overloaded with PHP functions, methods and static method calls, XML namespaces can be registered to be handled by PHP classes.

Prev | XML_Transformer | Next
XML_Transformer | PEAR Manual | XML_Transformer::XML_Transformer


XML_Transformer::XML_Transformer

XML_Transformer::XML_Transformer

XML_Transformer::XML_Transformer –

Synopsis

void XML_Transformer::XML_Transformer ( array parameters )

Description

Constructor of the XML_Transformer class. It can be passed an associative array that may have the following keys:

  • caseFolding: If TRUE, XML attribute and element names will be case-folded.

    caseFoldingTo: May be either CASE_UPPER or CASE_LOWER and sets the target case for the case-folding.

    debug: May be either TRUE or FALSE, thus enabling or disabling complete debugging information. May also be an array containing the names of elements to which the generated debugging information shall be limited. The special keywords "&CDATA" and "&RECURSE" may be used to enable debugging information for CDATA and recursion events.

    recursiveOperation: If TRUE, the transformation will continue recursively until the XML contains no more overloaded elements. Can be overrided on a per-element basis.

    overloadedElements: Associative array with pre-defined set of overloaded elements.

    overloadedNamespaces: Associative array with pre-defined set of overloaded elements.

Prev | XML_Transformer | Next
Introduction | PEAR Manual | XML_Transformer::overloadElement


XML_Transformer::overloadElement

XML_Transformer::overloadElement

XML_Transformer::overloadElement –

Synopsis

void XML_Transformer::overloadElement ( string element , string startHandler , string endHandler , boolean recursiveOperation )

Description

Overloads an XML element and binds its opening and closing tags to a PHP callback. A PHP callback can be one of the following:

  • A PHP Function.

  • A PHP Method on an object.

  • A static PHP Method.

The optional fourth parameter can be used to override the global setting for recursive operation.

Prev | XML_Transformer | Next
XML_Transformer::XML_Transformer | PEAR Manual | XML_Transformer::overloadNamespace


XML_Transformer::overloadNamespace

XML_Transformer::overloadNamespace

XML_Transformer::overloadNamespace –

Synopsis

void XML_Transformer::overloadNamespace ( string namespacePrefix , object object , boolean recursiveOperation )

Description

Overloads an XML Namespace and binds all its elements to a PHP object, that must provide startElement($element, $attributes)() and endElement($element, $cdata)() methods.

If the PHP object provides a initObserver($namespacePrefix, $transformer)() method it is automatically called with the registered namespace prefix and a reference to the XML_Transformer object.

Prev | XML_Transformer | Next
XML_Transformer::overloadElement | PEAR Manual | XML_Transformer::isOverloadedElement


XML_Transformer::isOverloadedElement

XML_Transformer::isOverloadedElement

XML_Transformer::isOverloadedElement –

Synopsis

boolean XML_Transformer::isOverloadedElement ( string element )

Description

Returns TRUE if the given element is overloaded, FALSE otherwise.

Prev | XML_Transformer | Next
XML_Transformer::overloadNamespace | PEAR Manual | XML_Transformer::isOverloadedNamespace


XML_Transformer::isOverloadedNamespace

XML_Transformer::isOverloadedNamespace

XML_Transformer::isOverloadedNamespace –

Synopsis

boolean XML_Transformer::isOverloadedNamespace ( string namespacePrefix )

Description

Returns TRUE if the given namespace is overloaded, FALSE otherwise.

Prev | XML_Transformer | Next
XML_Transformer::isOverloadedElement | PEAR Manual | XML_Transformer::unOverloadElement


XML_Transformer::unOverloadElement

XML_Transformer::unOverloadElement

XML_Transformer::unOverloadElement –

Synopsis

boolean XML_Transformer::unOverloadElement ( string element )

Description

Reverts overloading of the given element.

Prev | XML_Transformer | Next
XML_Transformer::isOverloadedNamespace | PEAR Manual | XML_Transformer::unOverloadNamespace


XML_Transformer::unOverloadNamespace

XML_Transformer::unOverloadNamespace

XML_Transformer::unOverloadNamespace –

Synopsis

boolean XML_Transformer::unOverloadNamespace ( string namespacePrefix )

Description

Reverts overloading of the given namespace.

Prev | XML_Transformer | Next
XML_Transformer::unOverloadElement | PEAR Manual | XML_Transformer::start


XML_Transformer::start

XML_Transformer::start

XML_Transformer::start –

Synopsis

void XML_Transformer::start ( )

Description

Starts the transformation, if it has not yet been started, for instance by the constructor.

Prev | XML_Transformer | Next
XML_Transformer::unOverloadNamespace | PEAR Manual | XML_Transformer::transform


XML_Transformer::transform

XML_Transformer::transform

XML_Transformer::transform –

Synopsis

string XML_Transformer::transform ( string xml )

Description

Transforms a given XML string.

Prev | XML_Transformer | Next
XML_Transformer::start | PEAR Manual | XML_Transformer::setCaseFolding


XML_Transformer::setCaseFolding

XML_Transformer::setCaseFolding

XML_Transformer::setCaseFolding –

Synopsis

void XML_Transformer::setCaseFolding ( boolean caseFolding , integer caseFoldingTo )

Description

Sets the XML parser's case-folding option.

Prev | XML_Transformer | Next
XML_Transformer::transform | PEAR Manual | XML_Transformer::setDebug


XML_Transformer::setDebug

XML_Transformer::setDebug

XML_Transformer::setDebug –

Synopsis

void XML_Transformer::setDebug ( mixed debug )

Description

Enables or disables debugging to error.log.

The parameter may be either TRUE or FALSE, thus enabling or disabling complete debugging information. May also be an array containing the names of elements to which the generated debugging information shall be limited. The special keywords "&CDATA" and "&RECURSE" may be used to enable debugging information for CDATA and recursion events.

Prev | XML_Transformer | Next
XML_Transformer::setCaseFolding | PEAR Manual | XML_Transformer::setDebug


XML_Transformer::setDebug

XML_Transformer::setDebug

XML_Transformer::setDebug –

Synopsis

void XML_Transformer::setRecursiveOperation ( boolean recursiveOperation )

Description

Enables or disables the recursive operation.

Prev | XML_Transformer | Next
XML_Transformer::setDebug | PEAR Manual | XML_Transformer::stackdump


XML_Transformer::stackdump

XML_Transformer::stackdump

XML_Transformer::stackdump –

Synopsis

string XML_Transformer::stackdump ( )

Description

Returns a stack dump as a debugging aid.

Prev | XML_Transformer | Next
XML_Transformer::setDebug | PEAR Manual | XML_Transformer::attributesToString


XML_Transformer::attributesToString

XML_Transformer::attributesToString

XML_Transformer::attributesToString –

Synopsis

string XML_Transformer::attributesToString ( array attributes )

Description

Returns string representation of attributes array.

Prev | XML_Transformer | Next
XML_Transformer::stackdump | PEAR Manual | XML_Transformer::canonicalize


XML_Transformer::canonicalize

XML_Transformer::canonicalize

XML_Transformer::canonicalize –

Synopsis

mixed XML_Transformer::canonicalName ( mixed target )

Description

Canonicalizes XML attribute arrays and element names.

Prev | XML_Transformer | Next
XML_Transformer::attributesToString | PEAR Manual | XML_Tree


XML_Tree

XML_Tree

Build XML documents using a tree representation

The XML_Tree package allows one to build XML data structures using a tree representation, without the need for an extension like DOMXML.

Table of Contents
  • XML_Tree::XML_Tree -- Constructor
  • XML_Tree::&addRoot -- add root node
  • XML_Tree::&insertChild -- inserts a child/tree
  • XML_Tree::&removeChild -- remove child from tree
  • XML_Tree::&getTreeFromFile -- map XML file to tree
  • XML_Tree::clone -- copy tree
  • XML_Tree::dump -- print XML tree.
  • XML_Tree::&get -- get XML tree.
  • XML_Tree::&getName -- get namespace.
  • XML_Tree::registerName -- register namespace.
Prev | XML | Next
XML_Transformer::canonicalize | PEAR Manual | XML_Tree::XML_Tree


XML_Tree::XML_Tree

XML_Tree::XML_Tree

XML_Tree::XML_Tree – Constructor

Synopsis

require_once "XML/Tree.php";

void XML_Tree::XML_Tree ( string $filename='' , string $version='1.0' )

Description

Constructor

Parameter

  • string $filename - name of the file to parse

  • string $version - XML version to use

Note

This function can not be called statically.

Prev | XML_Tree | Next
XML_Tree | PEAR Manual | XML_Tree::&addRoot


XML_Tree::&addRoot

XML_Tree::&addRoot

XML_Tree::&addRoot – add root node

Synopsis

require_once "XML/Tree.php";

object XML_Tree_Node XML_Tree::&addRoot ( string $name , string $content='' , array $attributes=array() )

Description

Adds a new root node to the XML datastructure.

Parameter

  • string $name - name of root element

  • string $content - data between the opening and closing tag

  • array $attributes - additional attributes for the tag. The attribute name is represented as the array key and the attribute value as entry for the key.

Return value

object XML_Tree_Node - reference to root node

Note

This function can not be called statically.

Example

Using &addRoot()

<?php
$tree  = new XML_Tree;
$root =& $tree->addRoot("root");
?>
Prev | XML_Tree | Next
XML_Tree::XML_Tree | PEAR Manual | XML_Tree::&insertChild


XML_Tree::&insertChild

XML_Tree::&insertChild

XML_Tree::&insertChild – inserts a child/tree

Synopsis

require_once "XML/Tree.php";

object XML_Tree_Node XML_Tree::&insertChild ( array $path , integer $pos , mixed $child , string $content='' , array $attributes=array() )

Description

Inserts a child or tree into the tree in the path $path on position $pos and maintains namespace integrity

Parameter

  • array $path - path to parent of child to insert

  • integer $pos - position of child to be inserted in its parent's children-list

  • mixed $child - child-node (by XML_Tree, XML_Node or Name)

  • string $content - content (text) for new node

  • array $attributes - attribute-hash for new node

Return value

object XML_Tree_Node - inserted child (node)

Note

This function can not be called statically.

See

XML_Tree::removeChild()

Prev | XML_Tree | Next
XML_Tree::&addRoot | PEAR Manual | XML_Tree::&removeChild


XML_Tree::&removeChild

XML_Tree::&removeChild

XML_Tree::&removeChild – remove child from tree

Synopsis

require_once "XML/Tree.php";

object XML_Tree_Node XML_Tree::&removeChild ( array $path , integer $pos )

Description

Removes a child ($path ,$pos ) from tree and maintains namespace integrity

Parameter

  • array $path - path to parent of child to remove

  • integer $pos - position of child in parents children-list

Return value

object XML_Tree_Node - parent whichs child was removed

Note

This function can not be called statically.

See

XML_Tree::insertChild()

Prev | XML_Tree | Next
XML_Tree::&insertChild | PEAR Manual | XML_Tree::&getTreeFromFile


XML_Tree::&getTreeFromFile

XML_Tree::&getTreeFromFile

XML_Tree::&getTreeFromFile – map XML file to tree

Synopsis

require_once "XML/Tree.php";

object XML_Tree XML_Tree::&getTreeFromFile ( )

Description

Maps a XML file to an object tree

Return value

object XML_Tree - the object tree

Note

This function can not be called statically.

See

XML_Tree::XML_Tree()

Prev | XML_Tree | Next
XML_Tree::&removeChild | PEAR Manual | XML_Tree::clone


XML_Tree::clone

XML_Tree::clone

XML_Tree::clone – copy tree

Synopsis

require_once "XML/Tree.php";

object XML_Tree XML_Tree::clone ( )

Description

Get a copy of this tree instance.

Return value

object XML_Tree - the copied object

Note

This function can not be called statically.

Prev | XML_Tree | Next
XML_Tree::&getTreeFromFile | PEAR Manual | XML_Tree::dump


XML_Tree::dump

XML_Tree::dump

XML_Tree::dump – print XML tree.

Synopsis

require_once "XML/Tree.php";

void XML_Tree::dump ( )

Description

Print text representation of XML tree.

Note

This function can not be called statically.

See

XML_Tree::get()

Prev | XML_Tree | Next
XML_Tree::clone | PEAR Manual | XML_Tree::&get


XML_Tree::&get

XML_Tree::&get

XML_Tree::&get – get XML tree.

Synopsis

require_once "XML/Tree.php";

string XML_Tree::&get ( )

Description

Get text representation of XML tree.

Return value

string - XML document

Note

This function can not be called statically.

See

XML_Tree::get()

Prev | XML_Tree | Next
XML_Tree::dump | PEAR Manual | XML_Tree::&getName


XML_Tree::&getName

XML_Tree::&getName

XML_Tree::&getName – get namespace.

Synopsis

require_once "XML/Tree.php";

string XML_Tree::&getName ( string $name )

Description

Get the current namespace.

Parameter

  • string $name - namespace

Return value

string - namespace

Note

This function can not be called statically.

See

XML_Tree::registerName()

Prev | XML_Tree | Next
XML_Tree::&get | PEAR Manual | XML_Tree::registerName


XML_Tree::registerName

XML_Tree::registerName

XML_Tree::registerName – register namespace.

Synopsis

require_once "XML/Tree.php";

void XML_Tree::registerName ( string $name , string $path )

Description

Registers a namespace.

Parameter

  • string $name - namespace

  • string $path - path

Note

This function can not be called statically.

See

XML_Tree::getName()

Prev | XML_Tree | Next
XML_Tree::&getName | PEAR Manual | XML_Util


XML_Util

XML_Util

Collection of often needed methods that help you creating XML documents.

Table of Contents
  • Introduction -- Introduction to XML_Util
  • Example -- Example for the usage of XML_Util
  • XML_Util::apiVersion -- return API version
  • XML_Util::attributesToString -- create XML attribute string
  • XML_Util::collapseEmptyTags -- collapse empty XML tags in a string
  • XML_Util::createTag -- create a tag
  • XML_Util::createTagFromArray -- create a tag from an array
  • XML_Util::createStartElement -- create a start element
  • XML_Util::createEndElement -- create an end element
  • XML_Util::createCDataSection -- create a CData section
  • XML_Util::createComment -- create an XML comment
  • XML_Util::getDocTypeDeclaration -- build a document type declaration
  • XML_Util::getXMLDeclaration -- build an xml declaration
  • XML_Util::isValidName -- verify an XML name
  • XML_Util::replaceEntities -- replace XML entities
  • XML_Util::reverseEntities -- replace XML entities
  • XML_Util::splitQualifiedName -- split qualified name
Prev | XML | Next
XML_Tree::registerName | PEAR Manual | Introduction


Introduction

Introduction

Introduction – Introduction to XML_Util

Introduction to XML_Util

XML_Util is a utility class that helps you working with (and especially creating) XML documents.

All methods of XML_Util can be called statically, that means you do not have to instantiate an XML_Util object to use the provided methods.

The funcionality of XML_Util ranges from validating an XML tag name (as there are strict rules for tag and attribute names) to the creation of namespaced XML tags.

Prev | XML_Util | Next
XML_Util | PEAR Manual | Example


Example

Example

Example – Example for the usage of XML_Util

Usage example

The following examples shows how some of the methods of XML_Util have to be used.

Some basic examples

<?php
require_once "XML/Util.php";

// creating an XML tag
$tag = XML_Util::createTag("xsl:stylesheet", array("version" => "1.0"), "Place your content here", "http://www.w3.org/1999/XSL/Transform");

// verify tag name
$result = XML_Util::isValidName("my Tag");
if (PEAR::isError($result)) {
    print "Invalid XML name: " . $result->getMessage();
} else {
    print "Tagname is valid.";
}
?>
Prev | XML_Util | Next
Introduction | PEAR Manual | XML_Util::apiVersion


XML_Util::apiVersion

XML_Util::apiVersion

XML_Util::apiVersion() – return API version

Synopsis

require_once 'XML/Util.php';

string XML_Util::apiVersion ( )

Description

Returns API version of XML_Util.

Return value

string API version

Note

This function should be called statically.

Prev | XML_Util | Next
Example | PEAR Manual | XML_Util::attributesToString


XML_Util::attributesToString

XML_Util::attributesToString

XML_Util::attributesToString() – create XML attribute string

Synopsis

require_once 'XML/Util.php';

string XML_Util::attributesToString ( array $attributes , boolean $sort = true , boolean $multiline = false , string $indent = ' ' , string $linebreak = "\n" , integer $entities = XML_UTIL_ENTITIES_XML )

Description

create string representation of an attribute list

Parameter

  • array $attributes - assoc array containg attributes

  • boolean $sort - whether to sort the attributes alphabetically

  • boolean $multiline - whether to display the attributes on more than one line (makes it easier to read)

  • string $indent - indentation characters, only used when multiline is set to TRUE

  • string $linebreak - linebreak character, only used when multiline is set to TRUE

  • integer $entities - define, which entities should be replaced in the attribute values. One of XML_UTIL_ENTITIES_NONE, XML_UTIL_ENTITIES_XML, XML_UTIL_ENTITIES_XML_REQUIRED or XML_UTIL_ENTITIES_HTML

Return value

string string representation of the attributes

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::apiVersion | PEAR Manual | XML_Util::collapseEmptyTags


XML_Util::collapseEmptyTags

XML_Util::collapseEmptyTags

XML_Util::collapseEmptyTags() – collapse empty XML tags in a string

Synopsis

require_once 'XML/Util.php';

string XML_Util::collapseEmptyTags ( string $string , integer $mode = XML_UTIL_COLLAPSE_ALL )

Description

This method collapses empty tags like <foo></foo> with the short version <foo/> by applying a regular expression. This is especially helpful when dealing with XHTML-documents, as there is an important difference in rendering these tags in the browser.

This method has been added in XML_Util 1.1.0.

Parameter

  • string $string - string, in which empty tags should be collapsed

  • integer $mode - collapse all empty tags (XML_UTIL_COLLAPSE_ALL) or only XHTML tags (XML_UTIL_COLLAPSE_XHTML_ONLY).

Return value

string string with collapsed empty tags

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::attributesToString | PEAR Manual | XML_Util::createTag


XML_Util::createTag

XML_Util::createTag

XML_Util::createTag() – create a tag

Synopsis

require_once 'XML/Util.php';

string XML_Util::createTag ( string $qname , array $attributes = array() , string $content = null , string $namespaceUri = null , integer $replaceEntities = XML_UTIL_REPLACE_ENTITIES )

Description

create a tag with attributes, namespace and adds 'xmlns' if needed.

Parameter

  • string $qname - qualified tag name

  • array $attributes - assoc array with attributes

  • string $content - string content of the tag

  • string $namespaceUri - URI of the namespace if xmlns attribute should be added

  • integer $replaceEntities - whether to replace XML entities in content, embedd it in a CData section or leave it untouched. Possible values are FALSE, XML_UTIL_REPLACE_ENTITIES or XML_UTIL_CDATA_SECTION.

Return value

string xml tag

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::collapseEmptyTags | PEAR Manual | XML_Util::createTagFromArray


XML_Util::createTagFromArray

XML_Util::createTagFromArray

XML_Util::createTagFromArray() – create a tag from an array

Synopsis

require_once 'XML/Util.php';

string XML_Util::createTagFromArray ( array $tag , integer $replaceEntities = XML_UTIL_REPLACE_ENTITIES )

Description

create a tag from an array. This is similar to XML_Util::createTag(), but more flexible.

Parameter

  • array $tag - array containing information about the tag

  • integer $replaceEntities - whether to replace XML entities in content, embedd it in a CData section or leave it untouched. Possible values are FALSE, XML_UTIL_REPLACE_ENTITIES or XML_UTIL_CDATA_SECTION.

Return value

string xml tag

Note

This function should be called statically.

Usage example

Creating a tag with XML_Util::createTagFromArray()

<?php
require_once "XML/Util.php";

$tag = array(
             "namespace"    => "xslt",
             "localPart"    => "variable",
             "namespaceUri" => "http://www.w3.org/1999/XSL/Transform",
             "attributes"   => array( "name" => "myVar" ),
             "content"      => "myValue"
           );
$string = XML_Util::createTagFromArray($tag);
?>
Prev | XML_Util | Next
XML_Util::createTag | PEAR Manual | XML_Util::createStartElement


XML_Util::createStartElement

XML_Util::createStartElement

XML_Util::createStartElement() – create a start element

Synopsis

require_once 'XML/Util.php';

string XML_Util::createStartElement ( string $qname , array $attributes = array() , string $namespaceUri = null )

Description

create a start element with attributes, namespace and adds 'xmlns' if needed. (<pear foo="bar">)

Parameter

  • string $qname - qualified tag name

  • array $attributes - assoc array with attributes

  • string $namespaceUri - URI of the namespace if xmlns attribute should be added

Return value

string opening xml tag

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::createTagFromArray | PEAR Manual | XML_Util::createEndElement


XML_Util::createEndElement

XML_Util::createEndElement

XML_Util::createEndElement() – create an end element

Synopsis

require_once 'XML/Util.php';

string XML_Util::createEndElement ( string $qname )

Description

create an end element (</foo>)

Parameter

  • string $qname - qualified tag name

Return value

string closing xml tag

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::createStartElement | PEAR Manual | XML_Util::createCDataSection


XML_Util::createCDataSection

XML_Util::createCDataSection

XML_Util::createCDataSection() – create a CData section

Synopsis

require_once 'XML/Util.php';

string XML_Util::createCDataSection ( string $data )

Description

Creates a CData section, by embedding the data in <!CDATA[ and ]]>. If you use a CData section inside an XML document, entities do not have to be replaced in this sections.

Parameter

  • string $data - data for the CData section.

Return value

string CData section

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::createEndElement | PEAR Manual | XML_Util::createComment


XML_Util::createComment

XML_Util::createComment

XML_Util::createComment() – create an XML comment

Synopsis

require_once 'XML/Util.php';

string XML_Util::createComment ( string $data )

Description

Creates an XML comment, by embedding the supplied data in <!-- and -->.

Parameter

  • string $data - data for the comment.

Return value

string comment

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::createCDataSection | PEAR Manual | XML_Util::getDocTypeDeclaration


XML_Util::getDocTypeDeclaration

XML_Util::getDocTypeDeclaration

XML_Util::getDocTypeDeclaration() – build a document type declaration

Synopsis

require_once 'XML/Util.php';

string XML_Util::getDocTypeDeclaration ( string $root , mixed $uri = null , mixed $internalDtd = null )

Description

Returns a document type declaration based on parameters.

Parameter

  • string $root - root tag

  • mixed $uri - URI of the document type definition or array containing the public id and the URI of the DTD

  • mixed $internalDtd - internal definitions

Return value

string document type declaration

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::createComment | PEAR Manual | XML_Util::getXMLDeclaration


XML_Util::getXMLDeclaration

XML_Util::getXMLDeclaration

XML_Util::getXMLDeclaration() – build an xml declaration

Synopsis

require_once 'XML/Util.php';

string XML_Util::getXMLDeclaration ( string $version = "1.0" , string $encoding = null , boolean $standalone = null )

Description

Returns an XML declaration based on parameters.

Parameter

  • string $version - XML version

  • string $encoding - XML encoding

  • boolean $standalone - whether document is standalone

Return value

string XML declaration

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::getDocTypeDeclaration | PEAR Manual | XML_Util::isValidName


XML_Util::isValidName

XML_Util::isValidName

XML_Util::isValidName() – verify an XML name

Synopsis

require_once 'XML/Util.php';

boolean XML_Util::isValidName ( string $string )

Description

Checks, whether a string is a valid XML name. In XML the names of tags and attributes must follow strict rules. This method can be used to validate the names you are using.

Parameter

  • string $string - string to be checked

Return value

Returns TRUE on success, PEAR_Error on failure.

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::getXMLDeclaration | PEAR Manual | XML_Util::replaceEntities


XML_Util::replaceEntities

XML_Util::replaceEntities

XML_Util::replaceEntities() – replace XML entities

Synopsis

require_once 'XML/Util.php';

string XML_Util::replaceEntities ( string $string )

Description

In XML documents you are not allowed to use & and <. The have to be replaced with their respective entities. This method does this for you and furthermore replaces all other predefined XML entities.

Parameter

  • string $string - string, in which entities have to be replaced

Return value

string string with entities replaced

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::isValidName | PEAR Manual | XML_Util::reverseEntities


XML_Util::reverseEntities

XML_Util::reverseEntities

XML_Util::reverseEntities() – replace XML entities

Synopsis

require_once 'XML/Util.php';

string XML_Util::reverseEntities ( string $string )

Description

This is the reverse function to XML_Util::replaceEntities()(). It replaces all XML (or HTML) entities in a string by their corresponding characters. This can be useful when working with XML documents without using an XML parser.

This method has been added in XML_Util 1.0.0.

Parameter

  • string $string - string, in which entities have to be removed

Return value

string string with entities removed

Note

This function should be called statically.

Prev | XML_Util | Next
XML_Util::replaceEntities | PEAR Manual | XML_Util::splitQualifiedName


XML_Util::splitQualifiedName
Prev

XML_Util::splitQualifiedName

XML_Util::splitQualifiedName() – split qualified name

Synopsis

require_once 'XML/Util.php';

array XML_Util::splitQualifiedName ( string $qname , string $defaultNs = null )

Description

Splits a qualified name and returns array with namespace and local part.

Parameter

  • string $qname - qualified tag name (e.g. xsl:stylsheet)

  • string $defaultNs - default namespace, will be used in return value, if qualified name contains only a local part

Return value

array assoc array containing namespace and local part of the tag

Note

This function should be called statically.

Prev | XML_Util
XML_Util::reverseEntities | PEAR Manual