PEAR Manual

PEAR Manual

2008-06-03
Edited By: Daniel Convissor
Edited By: Martin Jansen
Edited By: Alexander Merz
© 2001 2002 2003 2004 2005 2006 2007 2008 The PEAR Documentation Group
  • Copyright
  • Copyright for the XML_RPC documentation
  • Preface
    • The structure of the Manual
    • Authors — Authors and Contributors
  • About PEAR
    • Introduction
    • Support
    • Coding Standards
    • PEAR2 Coding Standards
    • PEAR2 Policies
    • Contributing
    • FAQ — FAQ - Frequently Asked Questions
    • Constitution
    • PEAR Group Administrative Documents
  • User Guide
    • Installation
    • Command line installer
  • New Maintainers' Guide
    • 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
  • Developer Guide
    • Introduction
    • Meaning for developers — PEAR's meaning for developers
    • Contributing — Contributing your own code
    • package.xml — The package definition file package.xml
    • package.xml 2.0 — The package definition file package.xml, version 2.0
    • Releasing A Package
    • Supporting PEAR development
    • Recommendations
    • Documentation — Writing documentation
  • New features in PEAR 1.4
    • Introduction
    • Channels
    • Custom File Roles
    • Custom File Tasks
    • Post-installation Scripts
  • Core components
    • PEAR base classes
    • PEAR Installer classes
    • PEAR channel server REST interface
  • 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
    • Payment
    • PEAR
    • PHP
    • QA Tools
    • Science
    • Streams
    • Structures
    • System
    • Text
    • Tools and Utilities
    • Validate
    • Web Services
    • XML
PHP Manual


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.


Copyright for the XML_RPC documentation

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.


Preface

PEAR is the PHP Extension and Application Repository.

About this Manual

This manual is written in XML using the » DocBook XML DTD, using » DSSSL (Document Style and Semantics Specification Language) for formatting. The tools used for formatting HTML versions are » Jade, written by » James Clark and » The Modular DocBook Stylesheets written by » Norman Walsh.

The basic structure is based on the great work already done by the PHP documentation group. Read » About the PHP manual for more details.

Copyright for the XML_RPC documentation
The structure of the Manual
PEAR Manual


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.

Preface
Authors
Preface


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.

  • Lorenzo Alberton

  • Gregory Beaver

  • David Coallier

  • Daniel Convissor

  • David Costa

  • Thomas V.V. Cox

  • Christophe Gesché

  • Ken Guest

  • Martin Jansen

  • Alan Knowles

  • Clay Loveless

  • Alexander Merz

  • Stefan Neufeind

  • Jon Parise

  • Tobias Schlitt

  • Stephan Schmidt

  • Mika Tuupola

  • Michael Wallner

  • Christian Weiske

  • Mark Wiesemann

(In alphabetic order.)

Preface
About PEAR
Preface


About PEAR

Table of Contents

  • Introduction
  • Support
  • Coding Standards
  • PEAR2 Coding Standards
  • PEAR2 Policies
  • Contributing
  • FAQ - Frequently Asked Questions
  • Constitution
  • PEAR Group Administrative Documents
Authors
Introduction
PEAR Manual


Introduction

subtitleThe PEAR Manifest/subtitle
Stig Bakken
Gregory Beaver
date2007-03-14/date

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

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)

subtitlePECL/subtitle

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.

About PEAR
Support
About PEAR


Support

Table of Contents

  • Web resources
  • #PEAR on IRC

This chapter describes, how you can get support, if you have questions concerning PEAR.

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

Introduction
Web resources
About PEAR


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.

Support
#PEAR on IRC
Support


#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.

Support
Coding Standards
Support


Coding Standards

Table of Contents

  • Control Structures
  • Function Calls
  • Class Definitions
  • Function Definitions
  • 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.

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.

#PEAR on IRC
Control Structures
About PEAR


Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:

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:

switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}

Coding Standards
Function Calls
Coding Standards


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:

$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:

$short         = foo($bar);
$long_variable = foo($baz);

Control Structures
Class Definitions
Coding Standards


Class Definitions

Class declarations have their opening brace on a new line:

class Foo_Bar
{

    //... code goes here

}

Function Calls
Function Definitions
Coding Standards


Function Definitions

Function declarations follow the "K&R style":

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:

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;
}

Class Definitions
Comments
Coding Standards


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.

Function Definitions
Including Code
Coding Standards


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.

Comments
PHP Code Tags
Coding Standards


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.

Including Code
Header Comment Blocks
Coding Standards


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 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:$
 * @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_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_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_0.txt  PHP License 3.0

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:

$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.

PHP Code Tags
Using CVS
Coding Standards


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:

prompt$ /promptcd pear/Money_Fast
prompt$ /promptcvs 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:

prompt$ /promptcvs tag QA_2_0_0_BP
...
prompt$ /promptcvs rtag -b -r QA_2_0_0_BP QA_2_0_0
prompt$ /promptcvs update -r QA_2_0_0
prompt$ /promptcvs tag RELEASE_2_0_0RC1
...and then the actual release, from the same branch:
prompt$ /promptcvs 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.

Header Comment Blocks
Example URLs
Coding Standards


Example URLs

Use example.com, example.org and example.net for all example URLs and email addresses, per » RFC 2606.

Using CVS
Naming Conventions
Coding Standards


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 (meaning class members that are intended to be used only from within the same class in which they are declared; PHP does not yet support truly-enforceable private namespaces) are preceded by a single underscore. For example:

$_status _sort() _initTree()

Note: The following applies to PHP5.

Protected class members (meaning class members that are intended to be used only from within the same class in which they are declared or from subclasses that extend it) 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.

Example URLs
File Formats
Coding Standards


File Formats

All scripts contributed to PEAR must:

  • Be stored as ASCII text

  • Use ISO-8859-1 character encoding

  • 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.

Naming Conventions
E_STRICT-compatible code
Coding Standards


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 » PEPr proposal.

File Formats
Error Handling Guidelines
Coding Standards


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.

Example #1 One pretty straightforward example for an error

/*
 * 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.

Example #2 Error handling with recovery

/*
 * 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.

Example #3 Incomplete recovery

/*
 * 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:

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:

/*
 * 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.

Example #4 Rethrowing an exception

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);
    }
}

Example #5 Letting exceptions bubble up

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:

/**
 * 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.

Example #6 Exceptions should be documented using the @throws phpdoc keyword

/**
 * 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:

/**
 * 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.

/**
 * 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).
E_STRICT-compatible code
Best practices
Coding Standards


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.

Error Handling Guidelines
Sample File (including Docblock Comment standards)
Coding 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 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:$
 * @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_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 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:
 */

?>

Best practices
The PEAR toolbox
Coding Standards


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.

Coding Standards
PEAR2 Coding Standards
Coding Standards


PEAR2 Coding Standards

Table of Contents

  • Rules
subtitleCoding Standards to be used in PEAR2 (version 1)/subtitle
date2007-12-24/date

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

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.

The PEAR toolbox
Rules
About PEAR


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

PEAR2 Coding Standards
PEAR2 Policies
PEAR2 Coding Standards


PEAR2 Policies

subtitlePolicies in use in PEAR2 (version 1)/subtitle
date2008-04-07/date

Note: This document cannot be considered complete.

  • This document contains the general policies for how coding and collaboration works in PEAR2.
  • These coding standards will expire on March 1, 2008, and must be reviewed and renewed by the PEAR Group in order to continue

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.

Rules
Contributing
About PEAR


Contributing

Table of Contents

  • Writing New Packages
  • Submitting Patches
  • Reporting Bugs
  • Writing & Translating Documentation
  • Wishlists
Tal Peer
Martin Jansen
Daniel Convissor
date2004-04-15/date

This chapter describes the different ways in which one could contribute to PEAR.

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.

PEAR2 Policies
Writing New Packages
About PEAR


Writing New Packages

Explanations about submitting new packages can be found in the Developers' Guide.

Contributing
Submitting Patches
Contributing


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.

Writing New Packages
Reporting Bugs
Contributing


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.

Submitting Patches
Writing & Translating Documentation
Contributing


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.

Reporting Bugs
Wishlists
Contributing


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 ;-).

Contributing
FAQ
Contributing


FAQ - Frequently Asked Questions

Table of Contents

  • Developer FAQ
  • Documentation/translation 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.

Wishlists
Developer FAQ
About PEAR


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.

FAQ
Documentation/translation FAQ
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.

FAQ
Constitution
FAQ


Constitution

Table of Contents

  • What is the purpose of this document?
  • Official Constitution
subtitleThe PEAR Constitution/subtitle
date2007-03-14/date

PEAR's constitution was adopted by majority vote of active PEAR developers on 2007-03-08, see the » Official Results.

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.

Documentation/translation FAQ
What is the purpose of this document?
About PEAR


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.

Constitution
Official Constitution
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.

Constitution
PEAR Group Administrative Documents
Constitution


PEAR Group Administrative Documents

Table of Contents

  • 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.

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.

About PEAR
License Announcement
About PEAR


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.

PEAR Group Administrative Documents
New guidelines for BC breaking releases
PEAR Group Administrative Documents


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.

License Announcement
Orphaned Packages
PEAR Group Administrative Documents


Orphaned Packages

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
New guidelines for BC breaking releases
Orphaned PEPr Proposals
PEAR Group Administrative Documents


Orphaned PEPr Proposals

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.".
PEAR Group Administrative Documents
User Guide
PEAR Group Administrative Documents


User Guide

Table of Contents

  • Installation
  • Command line installer
Orphaned PEPr Proposals
Installation
PEAR Manual


Installation

Table of Contents

  • Getting the manager
  • Installation of a local PEAR copy on a shared host
  • Checking if PEAR works
Martin Jansen
date2006-11-25/date

This chapter describes how to install the PEAR package manager.

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.

User Guide
Getting the manager
User Guide


Getting the 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:

$ sudo curl http://pear.php.net/go-pear | 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.

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.

Warning

Prerequisites

Do not forget to protect the pear directory if you did not do already before the installation.

Now check that PEAR works.

Installation
Installation of a local PEAR copy on a shared host
Installation


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:

PEAR 1.3.5 and earlier

$ pear -s -c ~/.pearrc -d doc_dir=~/pear/docs \
    -d ext_dir=~/pear/ext -d php_dir=~/pear/lib \
    -d data_dir=~/pear/data -d test_dir=~/pear/tests \
    -d cache_dir=~/pear/cache -d bin_dir=~/pear/bin

PEAR 1.4+

$ 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 1.3.2 and older

$ pear -c ~/.pearrc install Archive_Tar PEAR Console_Getopt XML_RPC

PEAR 1.3.3+

$ 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());
?>

Getting the manager
Checking if PEAR works
Installation


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 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 ...

Verify 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/

  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 phpinfo(); in it and load it in your browser.

  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 the PHP's include_path in your web server, save a file with only phpinfo(); in it. Open it in your browser and verify the setting.

    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 .php file with the following contents:

    <?php
    require_once 'System.php';
    ?>

    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. There should be no output. A message like:

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

    means that your include path is not correct.

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.

  • 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.

Installation
Command line installer
Installation


Command line installer

Table of Contents

  • Configuring your PEAR setup
  • Installing packages
  • Getting information about packages
  • Using channels
  • Command list
Warning

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.

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 ..
User Guide
Configuring your PEAR setup
User Guide


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) |

Command line installer
Installing packages
Command line installer


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

Warning

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.

Configuring your PEAR setup
Getting information about packages
Command line installer


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.

Installing packages
Using channels
Command line installer


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.

Getting information about packages
Command list
Command line installer


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)

Command line installer
New Maintainers' Guide
Command line installer


New Maintainers' Guide

Table of Contents

  • Introduction
  • How best to contribute to PEAR
  • Joining the PEAR community
  • The formal proposal process
  • Taking over an unmaintained package
Command list
Introduction
PEAR Manual


Introduction

Martin Jansen
date$Date: 2004/06/17 08:30:32 $/date

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.

New Maintainers' Guide
Contributing
New Maintainers' Guide


How best to contribute to PEAR

Table of Contents

  • Cases in which it is better to improve existing packages
Martin Jansen
Gregory Beaver
date$Date: 2007/12/02 04:18:12 $/date

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.

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.

Introduction
Cases in which it is better to improve existing packages
New Maintainers' Guide


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.

Contributing
Getting started
Contributing


Joining the PEAR community

Table of Contents

  • More written information
Martin Jansen
Gregory Beaver
date$Date: 2007/12/02 04:18:12 $/date

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.

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.

Cases in which it is better to improve existing packages
More information
New Maintainers' Guide


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.

Getting started
Proposing
Getting started


The formal proposal process

Table of Contents

  • Step 2: Initiating a discussion
  • Step 3: Using PEPr
  • Changing a proposal
Martin Jansen
Tobias Schlitt
date$Date: 2008/05/04 18:35:01 $/date

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.

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 #1 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
More information
Step 2
New Maintainers' Guide


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.

Proposing
Step 3
Proposing


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.

Step 2
Changing a proposal
Proposing


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.

Proposing
Taking over a package
Proposing


Taking over an unmaintained package

Arnaud Limbourg
date$Date: 2007/03/23 03:16:14 $/date

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.
New Maintainers' Guide
Developer Guide
New Maintainers' Guide


Developer Guide

Table of Contents

  • Introduction
  • PEAR's meaning for developers
  • Contributing your own code
  • The package definition file package.xml
  • The package definition file package.xml, version 2.0
  • Releasing A Package
  • Supporting PEAR development
  • Recommendations
  • Writing documentation
Taking over a package
Introduction
PEAR Manual


Introduction

subtitleA guide to PEAR written for developers by developers./subtitle
Martin Jansen
Gregory Beaver
date2007-03-23/date

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.

Developer Guide
Meaning for developers
Developer Guide


PEAR's meaning for developers

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.

Introduction
Contributing
Developer Guide


Contributing your own code

Table of Contents

  • How to contribute code in practice
  • 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.

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 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.
    Warning

    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.

Meaning for developers
How to contribute
Developer Guide


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.

Contributing
How to document
Contributing


How to document code in practice

Writing documentation is covered in a dedicated section.

Contributing
package.xml
Contributing


The package definition file package.xml

package.xml

Introduction to the package definition file package.xml

Warning

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

Example #1 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 #2 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:

Example #3 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"

Warning

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.

How to document
package.xml 2.0
Developer Guide


The package definition file package.xml, version 2.0

Table of Contents

  • Special information for PECL developers
  • Detailed Tag Reference for package.xml version 2.0
package.xml 2.0

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>

package.xml
Special information for PECL developers
Developer Guide


Special information for PECL developers

package.xml 2.0
extsrcrelease and extbinrelease changes for PECL developers
package.xml 2.0


PECL-specific details of package.xml 2.0

Special information for PECL developers
Detailed Tag Reference for package.xml version 2.0
Special information for PECL developers
PHP Manual

extsrcrelease and extbinrelease changes for PECL developers

(No version information available, might be only in CVS)

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>

Special information for PECL developers
Detailed Tag Reference for package.xml version 2.0
Special information for PECL developers


Detailed Tag Reference for package.xml version 2.0

Each tag that needs further explanation is documented here (unfinished)

package.xml 2.0
package.xml 2.0


What is a channel?

Detailed Tag Reference for package.xml version 2.0
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<channel>

(No version information available, might be only in CVS)

<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>

Detailed Tag Reference for package.xml version 2.0
Detailed Tag Reference for package.xml version 2.0


Superseding a package

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<extends>

(No version information available, might be only in CVS)

<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.

Example #1 Using extends

...
 <name>Package_Name2</name>
 <channel>pear.php.net</channel>
 <extends>Package_Name</extends>
 <summary>Any one-line summary</summary>
...

Example #2 Examples for <extends> usage in PEAR

  • HTML_Common2 extends HTML_Common
  • HTML_Progress2 extends HTML_Progress
  • MDB2 extends MDB
  • MDB2_Schema extends MDB2
Detailed Tag Reference for package.xml version 2.0


When should I use

, , , and
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<uri>

(No version information available, might be only in CVS)

<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>

, , , and
Detailed Tag Reference for package.xml version 2.0


Developer documentation for a release

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<lead>, <developer>, <contributor>, and <helper>

(No version information available, might be only in CVS)

<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.

Detailed Tag Reference for package.xml version 2.0


versioning in package.xml 2.0

, , , and
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<version>

(No version information available, might be only in CVS)

<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.

, , , and
Detailed Tag Reference for package.xml version 2.0


specifying release and API stability

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<stability>

(No version information available, might be only in CVS)

<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.

Detailed Tag Reference for package.xml version 2.0


specifying software license and optional reference to license text

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<license>

(No version information available, might be only in CVS)

<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.

Detailed Tag Reference for package.xml version 2.0


specifying the contents of a release

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<contents>

(No version information available, might be only in CVS)

<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.

Detailed Tag Reference for package.xml version 2.0


documenting a directory in the

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<dir>

(No version information available, might be only in CVS)

<dir> — documenting a directory in the <contents> tag

Documenting directories

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

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

Detailed Tag Reference for package.xml version 2.0


documenting a file in the

tasks for s
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<file>

(No version information available, might be only in CVS)

<file> — documenting a file in the <contents> tag

Documenting files

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

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

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

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

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

and the release section would look like this:

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

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

tasks for s
Detailed Tag Reference for package.xml version 2.0


specialized file installation and manipulation

Detailed Tag Reference for package.xml version 2.0
PHP Manual

tasks for <file>s

(No version information available, might be only in CVS)

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)
    ?>

Detailed Tag Reference for package.xml version 2.0


Alleviating strict versioning with

tasks for s
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<compatible>

(No version information available, might be only in CVS)

<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

tasks for s
Detailed Tag Reference for package.xml version 2.0


Dependency Specification in package.xml 2.0

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<dependencies>

(No version information available, might be only in CVS)

<dependencies> — Dependency Specification in package.xml 2.0

Introduction to dependencies in package.xml 2.0

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

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

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

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

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

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

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.0a7</min>
  </pearinstaller>
  <php>
   <min>4.2.0</min>
   <max>6.0.0</max>
  </php>
  <package>
   <name>Archive_Tar</name>
   <channel>pear.php.net</channel>
   <min>1.3.1</min>
  </package>
 </required>

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

</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.

<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.

Warning

<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

Detailed Tag Reference for package.xml version 2.0


documenting custom file roles used in

Detailed Tag Reference for package.xml version 2.0
PHP Manual

<usesrole>

(No version information available, might be only in CVS)

<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>

Detailed Tag Reference for package.xml version 2.0


documenting custom tasks used in

, , ,
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<usestask>

(No version information available, might be only in CVS)

<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>

, , ,
Detailed Tag Reference for package.xml version 2.0


specifying the content type of a release

Detailed Tag Reference for package.xml version 2.0
Releasing A Package
Detailed Tag Reference for package.xml version 2.0
PHP Manual

<phprelease>, <extbinrelease>, <extsrcrelease>, <bundle>

(No version information available, might be only in CVS)

<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.

Detailed Tag Reference for package.xml version 2.0
Releasing A Package
Detailed Tag Reference for package.xml version 2.0


Releasing A Package

Table of Contents

  • Validating The Package Definition File
  • Packaging The Release Tarball
  • Releasing The Package Through The Web Interface
subtitleThe steps required from package maintainers to release a package./subtitle
Tal Peer
date2003-03-20/date

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.

, , ,
Validating The Package Definition File
Developer Guide


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.

Releasing A Package
Packaging The Release Tarball
Releasing A Package


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.

Validating The Package Definition File
Releasing The Package Through The Web Interface
Releasing A Package


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.

Releasing A Package
Supporting PEAR development
Releasing A Package


Supporting PEAR development

Martin Jansen
date2002-05-27/date

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.

Releasing The Package Through The Web Interface
Recommendations
Developer Guide


Recommendations

Table of Contents

  • Color Representation inside PEAR Packages
  • Checking if a driver can be loaded
  • Writing informative release notes
  • Unit test configuration
Stefan Neufeind
date2004-02-29/date

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.

Supporting PEAR development
Color Representation
Developer Guide


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.

$color = array(0x33, 0x99, 0x00);
or
$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:

$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.

$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.

Recommendations
Checking if a driver can be loaded
Recommendations


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;

//...
?>
Color Representation
Writing informative release notes
Recommendations


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.

Example #1 Bad release notes

- Fixed bug #11495

Example #2 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
Checking if a driver can be loaded
Unit test configuration
Recommendations


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.

Example #1 Exemplary directory layout

tests/
    config.php.dist
    config.php

Example #2 Exemplary configuration template

$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:

Example #3 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.');
        }
        //...
    }

    //...
}
?>
Recommendations
Documentation
Recommendations


Writing documentation

Table of Contents

  • Tips for good documentation
Daniel Convissor
Martin Jansen

This chapter provides a detailed description of how to write documentation using one of the supported formats. It is aimed at both PEAR developers that are already maintaining packages in PEAR and at people who are planning to contribute a new package.

The DocBook XML format

» 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 number of tools 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 » citationDocBook: The Definitive Guide/citation, 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.

Required software

Even if DocBook XML can (like any other XML file) be written using a normal text editor, it is optimal for users to install some software on their machine in order to test the validity of the documenting efforts. A list of the required software and installation instructions can be found in the » PHP Documentation HOWTO. Apart from providing information about the software, this HOWTO also provides a ton of other useful information that goes far beyond this chapter. One is encouraged to read it completely. (Chapter II can be skipped, because it only contains information that is very PHP specific.)

Note: Installation on OS X
The PHP Documentation HOWTO advises users of Mac OS X to use packages provided by Fink. Alternatively packages from the » MacPorts project can be used. After installing MacPorts, the toolchain can be installed using the following command:

sudo port install openjade docbook-dsssl

Unfortunately, installing that software can be difficult under some circumstances. If you are unable to get it working, don't use that as an excuse for not writing documentation. There are two test servers that automatically download peardoc from CVS and build the manual. Any parsing errors your changes cause will show up in the logs the next time the build happens:

  • » Build from Brett Bieber (» log) (updated every two hours)
  • » Build from TAKAGI Masahiro (» log) (updated daily at 06:00 JST = 21:00 UTC)
These automatic builds also give you an idea of what your changes will look like in the actual manual. This is helpful because the manual on the PEAR website is only built once per week (Sundays ~12:00 UTC).
Warning

The manual on the PEAR website is built only once per week. Any XML validation errors will cause the build to fail. If the main build fails, the old version remains in place, meaning the manual will be out of date. Therefore, always check the test build logs to ensure your changes are valid. More importantly, do not commit updates shortly before the main build happens (Sundays ~12:00 UTC).

Once the necessary software is in place, one has to get the latest version of the XML sources from PEAR's CVS repository:

$ cvs -d :pserver:<user>@cvs.php.net:/repository login

[password]

$ cvs -d :pserver:<user>@cvs.php.net:/repository co peardoc

If you do not own an account for cvs.php.net, please choose cvsread as the username. When asked for the password, type phpfi .

After that the directory ./peardoc will contain a local copy ("sandbox") of the latest sources. If you are not yet familiar with CVS, then the online book » "Open Source Development with CVS" will provide you with all the necessary information.

Directory structure

This chapter will not describe all the details about the directory structure, because one can find out the essentials about it by browsing the previously created directory peardoc. As a starting point for package documenters peardoc/en/package/ fits well. If one has further questions concerning the directory structure, they can ask on the » documentation mailinglist.

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:

  • » peardoc/en/authoring The CVS tree has a complete set of DocBook XML templates. These files provide the standard of how PEAR documentation should look. The simplest way to utilize them is to copy them to your working directory, rename them accordingly, edit the contents to match the reality of your program and then upload them to your package's directory in the repository.
  • » HTTP Request The documentation for HTTP_Request, which is a relatively small package, only consists of a bunch of end-user documentation, which describes all of the basic features of the package. Each feature description includes at least one example. For small packages with only a handful of methods this documentation type is absolutely enough.
  • » XML Beautifier XML_Beautifier is a package that is also relatively compact, but which supports different configuration options. These options are described in the documentation Additionally the documentation gives usage examples and (unlike HTTP_Request) also includes API documentation for its methods.
  • » DB DB is a large PEAR package and has excellent documentation, including usage examples. The DB docs carefully adhere to the formatting specified in peardoc/authoring. The link above goes to the DocBook source code in the CVS repository. It might be helpful to examine the HTML generated therefrom.

In addition to the examples above, you will find much more documentation examples by browsing the peardoc directory, which contains your local version of the CVS tree. Especially the directory peardoc/en/packages/ should be of interest for you. You can also browse the CVS module using the » web interface, including the » raw XML for the file you are presently reading.

Using phpDocumentor to generate documentation templates

Creating dozens of files, one for each function in each class of your package is rather boring. Luckily, we have the PhpDocumentor in PEAR which has a renderer to generate templates for your classes and methods.

Create a test directory and cd into it. Then, run the following command: phpdoc -p on -f /path/to/my/package/source/File.php -t . -o "XML:DocBook/peardoc2:default" -dc myPackageCategory After creating the files, check if they are all ok and edit them - add examples, additional documentation and remove unneccessary sections.

Note: phpdoc generates documentation templates. The generated docs are by no means complete, you need to edit them afterwards!

Testing documentation

Using GNU make

Generating human-readable versions of the DocBook sources requires the existence of the above-mentioned software. The PEAR documentation system uses Unix style makefiles:

peardoc$ autoconf
peardoc$ ./configure --with-lang=en
peardoc$ make html

If you want to build a language other than English, change en, above, to the appropriate language code.

It may be that the DSSSL stylesheets are not found, resulting in the message

checking for docbook.dsl... defaulting - WARNING!!!
DSSSL NOT FOUND - WON'T WORK THIS WAY

In this case make sure you've installed the DSSSL packages. On a Mac using Fink, you might have to specify the location yourself: ./configure --with-dsssl=/sw/share/sgml/dsssl/docbook-dsssl-nwalsh

On Windows, the easiest way to get the DSSSL sheets is to check out the phpdoc module on cvs.php.net - they can be found in the dsssl/ subdirectory.

This will generate a "raw" HTML version of the whole manual. The result will be placed in the subdirectory html/.

The command make test does not generate any human-readable result, but it can be used to make sure that the XML is syntactically correct and that the build runs fine. And it is much faster than make html.

Problems when using make html

Numerous developers have reported problems when using the make html command, namely that the output was not written to a file but instead dumped on the console. If you encounter this problem and have checked out the DocBook sources into e.g. /home/you/cvs/peardoc, checkout the phpdoc module (using the procedure described above) into /home/you/cvs/phpdoc, and run make html again.

Using xmllint

Alternatively one can use the » xmllint program that is part of the » libxml2 toolkit. This is especially useful for systems where the DSSSL/make setup does not work properly.

In addition to testing the well-formedness of the DocBook sources, xmllint can also check the semantical correctness with the help of RELAX NG schemas. The schema files for DocBook are available as a ZIP package from » docbook.org. After unzipping the package into the directory relaxng/ inside the peardoc source folder, one can run xmllint from the root folder of the PEAR documentation as follows:

xmllint --valid --noout --relaxng relaxng/ manual.xml

Partial builds

The build process (not the test builds, which are reasonably quick) actually takes a very long time which makes debugging and testing a very hard task. In order to increase build performance, the script make-partial.php in the root directory of the documentation module may be used. This is an interactive command line script that will enable to you to selectively include the different parts of the manual. In the following example a version of the manual is generated which only contains a certain part of the Developer's Guide and the documentation for the HTTP packages. Using these partial builds reduces the build time dramatically.

peardoc$ ./make-partial.php
Include about-pear? [NO]
Include guide-newmaint? [NO]
Include guide-developers? [NO] y
Include guide.developers.intro? [NO]
Include guide.developers.meaning? [NO]
Include guide.developers.contributing? [NO]
Include guide.developers.packagedef? [NO]
Include guide.developers.release? [NO]
Include guide.developers.supporting? [NO]
Include guide.developers.recommendations? [NO]
Include guide.developers.documentation? [NO] y
Include core? [NO]
Include packages? [NO] y
Include package.authentication? [NO]
Include package.benchmarking? [NO]
Include package.caching? [NO]
Include package.configuration? [NO]
Include package.console? [NO]
Include package.database? [NO]
Include package.datetime? [NO]
Include package.encryption? [NO]
Include package.fileformats? [NO]
Include package.filesystem? [NO]
Include package.gtk? [NO]
Include package.html? [NO]
Include package.http? [NO] y
Include package.images? [NO]
Include package.internationalization? [NO]
Include package.logging? [NO]
Include package.mail? [NO]
Include package.math? [NO]
Include package.networking? [NO]
Include package.numbers? [NO]
Include package.payment? [NO]
Include package.pear? [NO]
Include package.php? [NO]
Include package.science? [NO]
Include package.streams? [NO]
Include package.structures? [NO]
Include package.system? [NO]
Include package.text? [NO]
Include package.tools? [NO]
Include package.xml? [NO]
Include package.webservices? [NO]
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
/usr/bin/jade -wno-idref  -d html.dsl -V use-output-dir -t sgml ./phpdocxml.dcl manual.xml

In make-partial.php, takes a long time to complete all questions. make partial with the correct parameters is much faster, e.g. make partial INCLUDE="packages package.database". The full list of IDs can be obtained by inspecting the output of make.

Translating documentation

Translating documentation is another important task. 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.

Daily test builds for the translations (provided by TAKAGI Masahiro)
Language | Build | Log | Revcheck
English | » Build | » Log | » Revcheck
French | » Build | » Log | » Revcheck
German | » Build | » Log | » Revcheck
Japanese | » Build | » Log | » Revcheck

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.

Also consider reading the Documentation FAQ.

Developer Guide
Documentation Tips
Developer Guide


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. First, 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.

Documentation
New features in PEAR 1.4
Documentation


New features in PEAR 1.4

Table of Contents

  • Introduction
  • Channels
  • Custom File Roles
  • Custom File Tasks
  • Post-installation Scripts
Documentation Tips
Introduction
PEAR Manual


Introduction

Gregory Beaver
date$Date: 2005/03/26 05:58:19 $/date

The debut of PEAR 1.4.0 is very exciting. This chapter documents all of the differences between PEAR 1.3.x and the new features introduced in PEAR 1.4.

The most significant change in PEAR 1.4 is the addition of channels, a simple and effective method of distributing application development. This change has driven most of the other changes to PEAR, and in fact full application support is a major goal of this release.

In addition to channels, support for customization of the install process has been seriously enhanced with the addition of three essential features for application development:

  • Custom file installation roles in package.xml

  • Custom file tasks in package.xml

  • Post-installation scripts

New features in PEAR 1.4
Channels
New features in PEAR 1.4


Channels

Table of Contents

  • The channel definition file
  • XML-RPC function API documentation
Gregory Beaver
date$Date: 2005/11/25 19:10:52 $/date

PEAR Channels provide a robust and effective way of distributing development. The addition of channel support to the PEAR installer as of version 1.4.0 means that it is now simpler to distribute any PHP code project using the PEAR installer than it ever was. PEAR Channels allow developers of applications to effectively depend upon packages from pear.php.net and any other source that provides a channel server. For users of these applications, this eliminates the complexity of installation and configuration. Now, all the user will need to do is to type a single pear install channel/Packagename command and go!

Before PEAR 1.4.0, the only solution to depending on code from several sources is to bundle the code. This has several bad side effects, the most obvious of which is that code size increases dramatically, and makes upgrading for a minor bug fix a complicated download for the user.

Channels allow an application developer to depend on packages from pear.php.net, a package from pear.example.com, and others. The user will only need to install/upgrade from a single source using the pear installer. With the current state of affairs, the pear installer is only really useful for installing, well, PEAR packages. Because of this difficulty (among others), traditionally very few packages are available as PEAR packages that can be installed with the PEAR installer.

PEAR 1.4.0+ aims to eliminate this and other barriers to application development.

Warning

Incomplete documentation

Documentation is not yet complete

Introduction
channel.xml
New features in PEAR 1.4


The channel definition file

Channels
XML-RPC functions
Channels
PHP Manual

channel.xml

(No version information available, might be only in CVS)

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.

Channels
XML-RPC functions
Channels


XML-RPC function API documentation

Channels
Custom File Roles
Channels
PHP Manual

XML-RPC functions

(No version information available, might be only in CVS)

XML-RPC functions — XML-RPC function API documentation

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

funcsynopsis funcprototype funcdeffalse|struct package.getDownloadURL()/funcdef paramdefstruct packageinfo /paramdef paramdefstring preferred_state = stable /paramdef paramdef(v1.1) string installed_version = false /paramdef /funcprototype /funcsynopsis

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

funcsynopsis funcprototype funcdeffalse|struct package.getDepDownloadURL()/funcdef paramdefstring xsdversion /paramdef paramdefstruct dependency /paramdef paramdefstruct parentpackage /paramdef paramdefstring preferred_state = stable /paramdef paramdef(v1.1) string installed_version = false /paramdef /funcprototype /funcsynopsis

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

funcsynopsis funcprototype funcdeffalse|struct package.info()/funcdef paramdefstring package /paramdef paramdefstring field = null /paramdef /funcprototype /funcsynopsis

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

funcsynopsis funcprototype funcdefstruct package.listAll()/funcdef paramdefbool released_only = true /paramdef paramdefbool stable_only = true /paramdef /funcprototype /funcsynopsis

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:

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

funcsynopsis funcprototype funcdefstruct package.listLatestReleases()/funcdef paramdefstring state = '' /paramdef /funcprototype /funcsynopsis

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:

array(
  array(
    'package' => 'packagename',
    'version' => 'release version',
    'state' => 'release stability',
    'filesize' => 'size of the .tgz file to download',
  ),
  // etc.
);

package.search

funcsynopsis funcprototype funcdefstruct package.listAll()/funcdef paramdefstring fragment /paramdef paramdefstring|bool summary = false /paramdef paramdefbool released_only = true /paramdef paramdefbool stable_only = true /paramdef /funcprototype /funcsynopsis

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:

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.
);

Channels
Custom File Roles
Channels


Custom File Roles

Table of Contents

  • Defining a customized role for use in a package.xml
Gregory Beaver
date$Date: 2005/11/03 05:06:52 $/date
Warning

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.

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!

XML-RPC functions
creating custom roles
New features in PEAR 1.4


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/>DIRECTORY_SEPARATOR<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.4 2005/11/03 05:06:52 cellog 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:

<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.

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>PEAR_CONFIG_DEFAULT_VERBOSE</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>PEAR_CONFIG_DEFAULT_PREFERRED_STATE</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>PHP_OS<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/>DIRECTORY_SEPARATOR<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.

Custom File Roles
Custom File Tasks
Custom File Roles


Custom File Tasks

Table of Contents

  • Creating customized tasks in PHP
Gregory Beaver
date$Date: 2008/05/08 22:01:51 $/date

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.

Using a customized task in a package.xml

Tasks are defined in package.xml through the tasks namespace, which is currently urihttp://pear.php.net/dtd/tasks-1.0/uri. 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.

creating custom roles
coding custom tasks
New features in PEAR 1.4


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()

funcsynopsis funcprototype funcdeftrue|array validateXml()/funcdef paramdefPEAR_PackageFile_v2 $pkg /paramdef paramdefstring|array $xml /paramdef paramdefPEAR_Config &$config /paramdef paramdefarray $fileAttributes /paramdef /funcprototype /funcsynopsis

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()

funcsynopsis funcprototype funcdefvoid init()/funcdef paramdefstring|array $xml /paramdef paramdefarray $fileAttributes /paramdef paramdefstring|null $lastVersion /paramdef /funcprototype /funcsynopsis

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()

funcsynopsis funcprototype funcdefstring|false|PEAR_Error startSession()/funcdef paramdefstring $contents /paramdef paramdefstring $dest /paramdef /funcprototype /funcsynopsis

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()

funcsynopsis funcprototype funcdeffalse|string run()/funcdef paramdefarray $tasks /paramdef /funcprototype /funcsynopsis

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.

Custom File Tasks
Post-installation Scripts
Custom File Tasks


Post-installation Scripts

Table of Contents

  • Structure of a post-install script
Gregory Beaver
date$Date: 2005/05/30 21:07:46 $/date
Warning

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.

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. In other words, this postinstall script:

Path/To/Script.php

Must contain a class named Path_To_Script. Due to casing differences between operating systems, it is recommended to always use lowercased file names.

New features in PEAR 1.4
Post-install script structure
New features in PEAR 1.4


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

funcsynopsis funcprototype funcdefvoid init()/funcdef paramdefPEAR_Config $config /paramdef paramdefPEAR_PackageFile_v2 $self /paramdef paramdefstring|null $lastInstalledVersion /paramdef /funcprototype /funcsynopsis

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 run() method

funcsynopsis funcprototype funcdefbool run()/funcdef paramdefarray $infoArray /paramdef paramdefstring $paramGroupId /paramdef /funcprototype /funcsynopsis

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.

Post-installation Scripts
Core components
Post-installation Scripts


Core components

Table of Contents

  • PEAR base classes
  • PEAR Installer classes
  • PEAR channel server REST interface
Post-install script structure
PEAR base classes
PEAR Manual


PEAR base classes

Table of Contents

  • How to handle the PEAR base class (destructors, error handling)
  • Predefined Constants
  • constructor (package developer related)
  • Deconstructor (package developer related)
  • handle static properties (package developer related)
  • set a shutdown function for static classes (package developer related)
  • checks for a PEAR_Error object
  • Create a new PEAR_Error object and optionally specify error-handling instructions
  • sets handling of errors generated through PEAR packages
  • add an error code for non-disabling temporary error handling
  • removes the last error code for non-disabling temporary error handling
  • OS independent PHP extension load
  • PEAR_Exception - PHP 5 and versions above
  • PEAR_ErrorStack
  • PEAR_Error [deprecated]
  • System

The Core section provides information about the base classes in PEAR

PEAR

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.

Core components
Introduction
Core components


How to handle the PEAR base class (destructors, error handling)

Post-install script structure
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — How to handle the PEAR base class (destructors, error handling)

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.

Warning

Important!

In order for destructors to work properly, you must instantiate your class with the "=& new" operator like this:

$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:

Example #1 PEAR: emulated destructors

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.

Example #2 PEAR error example (1)

function mysockopen($host = "localhost", $port = 8090)
{
    $fp = fsockopen($host, $port, $errno, $errstr);
    if (!is_resource($fp)) {
        return new PEAR_Error($errstr, $errno);
    }
    return $fp;
}

$sock = mysockopen();
if (PEAR::isError($sock)) {
    print "mysockopen error: ".$sock->getMessage()."\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:

Example #3 PEAR error example (2)

class TCP_Socket extends PEAR
{
    var $sock;

    function TCP_Socket()
    {
        $this->PEAR();
    }

    function connect($host, $port)
    {
        $sock = fsockopen($host, $port, $errno, $errstr);
        if (!is_resource($sock)) {
            return $this->raiseError($errstr, $errno);
        }
    }
}

$sock = new TCP_Socket;
$sock->setErrorHandling(PEAR_ERROR_DIE);
$sock->connect('localhost', 8090);
print "still alive\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:

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:

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:

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:

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

Post-install script structure


Predefined Constants

Post-install script structure
PHP Manual

Constants

(No version information available, might be only in CVS)

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()

Post-install script structure


constructor (package developer related)

Post-install script structure
PHP Manual

PEAR::PEAR()

(No version information available, might be only in CVS)

PEAR::PEAR() — constructor (package developer related)

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR::PEAR()/funcdef paramdef string $errorClass = PEAR_Error /paramdef /funcprototype /funcsynopsis

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.

Post-install script structure


Deconstructor (package developer related)

Post-install script structure
PHP Manual

PEAR::_PEAR()

(No version information available, might be only in CVS)

PEAR::_PEAR() — Deconstructor (package developer related)

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR::_PEAR()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

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

Post-install script structure


handle static properties (package developer related)

Post-install script structure
PHP Manual

PEAR::getStaticProperty()

(No version information available, might be only in CVS)

PEAR::getStaticProperty() — handle static properties (package developer related)

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefmixed &PEAR::getStaticProperty()/funcdef paramdef string $class /paramdef paramdef string $var /paramdef /funcprototype /funcsynopsis

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:

$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

Example #1 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
Post-install script structure


set a shutdown function for static classes (package developer related)

Post-install script structure
PHP Manual

PEAR::registerShutdownFunc()

(No version information available, might be only in CVS)

PEAR::registerShutdownFunc() — set a shutdown function for static classes (package developer related)

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR::registerShutdownFunc()/funcdef paramdef array $func /paramdef paramdef array $var = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

}

?>
Post-install script structure


checks for a PEAR_Error object

Post-install script structure
PHP Manual

PEAR::isError()

(No version information available, might be only in CVS)

PEAR::isError() — checks for a PEAR_Error object

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR::isError()/funcdef paramdef mixed $data /paramdef paramdef mixed $msgcode /paramdef /funcprototype /funcsynopsis

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

Post-install script structure


Create a new PEAR_Error object and optionally specify error-handling instructions

Post-install script structure
PHP Manual

PEAR::raiseError()

(No version information available, might be only in CVS)

PEAR::raiseError() — Create a new PEAR_Error object and optionally specify error-handling instructions

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefPEAR_Error PEAR::raiseError()/funcdef paramdef mixed $message /paramdef paramdef int $code /paramdef paramdef int $mode /paramdef paramdef int|array $options /paramdef paramdef mixed $userinfo /paramdef paramdef string $error_class /paramdef paramdef boolean $skipmsg /paramdef /funcprototype /funcsynopsis

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.

Post-install script structure


sets handling of errors generated through PEAR packages

Post-install script structure
PHP Manual

PEAR::setErrorHandling()

(No version information available, might be only in CVS)

PEAR::setErrorHandling() — sets handling of errors generated through PEAR packages

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR::setErrorHandling()/funcdef paramdef integer $mode = NULL /paramdef paramdef mixed $options = NULL /paramdef /funcprototype /funcsynopsis

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);
?>

Post-install script structure


add an error code for non-disabling temporary error handling

Post-install script structure
PHP Manual

PEAR::expectError()

(No version information available, might be only in CVS)

PEAR::expectError() — add an error code for non-disabling temporary error handling

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefinteger PEAR::expectError()/funcdef paramdef mixed $errorCode = '*' /paramdef /funcprototype /funcsynopsis

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()

Post-install script structure


removes the last error code for non-disabling temporary error handling

Post-install script structure
PHP Manual

PEAR::popExpect()

(No version information available, might be only in CVS)

PEAR::popExpect() — removes the last error code for non-disabling temporary error handling

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR::popExpect()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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()

Post-install script structure


OS independent PHP extension load

Post-install script structure
PHP Manual

PEAR::loadExtension()

(No version information available, might be only in CVS)

PEAR::loadExtension() — OS independent PHP extension load

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR::loadExtension()/funcdef paramdef string $ext /paramdef /funcprototype /funcsynopsis

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

Example #1 Loading the domxml-extension

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


PEAR_Exception - PHP 5 and versions above

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.

PEAR::loadExtension()
Using PEAR_Exception for advanced error handling in PHP 5+
PEAR base classes


Using PEAR_Exception

PEAR_Exception
PEAR_ErrorStack
PEAR_Exception
PHP Manual

Using PEAR_Exception for advanced error handling in PHP 5+

(No version information available, might be only in CVS)

Using PEAR_Exception for advanced error handling in PHP 5+ — Using PEAR_Exception

Gregory Beaver personblurb

cellog@php.net

/personblurb
© 2006 Gregory Beaver
releaseinfoPEAR_Exception PEAR 1.5.0a1/releaseinfo

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.

PEAR_Exception
PEAR_ErrorStack
PEAR_Exception


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');

Using PEAR_Exception for advanced error handling in PHP 5+
Introduction to using PEAR_ErrorStack for advanced error handling
PEAR base classes


Using PEAR_ErrorStack to do both simple and advanced error handling

PEAR_ErrorStack
constructor PEAR_ErrorStack::PEAR_ErrorStack
PEAR_ErrorStack
PHP Manual

Introduction to using PEAR_ErrorStack for advanced error handling

(No version information available, might be only in CVS)

Introduction to using PEAR_ErrorStack for advanced error handling — Using PEAR_ErrorStack to do both simple and advanced error handling

Gregory Beaver personblurb

cellog@php.net

/personblurb
© 2003 2004 2005 2006 Gregory Beaver
releaseinfoPEAR_ErrorStack 1.3.2 (beta)/releaseinfo

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

    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());
?>

PEAR_ErrorStack
constructor PEAR_ErrorStack::PEAR_ErrorStack
PEAR_ErrorStack


Set up a new error stack instance

Introduction to using PEAR_ErrorStack for advanced error handling
PEAR_ErrorStack::getErrorMessage
PEAR_ErrorStack
PHP Manual

constructor PEAR_ErrorStack::PEAR_ErrorStack()

(No version information available, might be only in CVS)

constructor — Set up a new error stack instance

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor PEAR_ErrorStack::PEAR_ErrorStack()/funcdef paramdefstring $package /paramdef paramdefcallback $msgCallback = FALSE /paramdef paramdefcallback $contextCallback = FALSE /paramdef paramdefboolean $throwPEAR_Error = FALSE /paramdef /funcprototype /funcsynopsis

Backwards Compatibility Warning

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.

Introduction to using PEAR_ErrorStack for advanced error handling
PEAR_ErrorStack::getErrorMessage
PEAR_ErrorStack


Standard error message generation callback

constructor PEAR_ErrorStack::PEAR_ErrorStack
PEAR_ErrorStack::getErrorMessageTemplate
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::getErrorMessage()

(No version information available, might be only in CVS)

— Standard error message generation callback

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_ErrorStack::getErrorMessage()/funcdef paramdefPEAR_ErrorStack &$stack /paramdef paramdefarray $err /paramdef paramdefstring|false $template = FALSE /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_ErrorStack::PEAR_ErrorStack
PEAR_ErrorStack::getErrorMessageTemplate
PEAR_ErrorStack


Standard Error Message Template generator from error code

PEAR_ErrorStack::getErrorMessage
PEAR_ErrorStack::getErrors
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::getErrorMessageTemplate()

(No version information available, might be only in CVS)

— Standard Error Message Template generator from error code

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_ErrorStack::getErrorMessageTemplate()/funcdef paramdefmixed $code /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::getErrorMessage
PEAR_ErrorStack::getErrors
PEAR_ErrorStack


Retrieve all errors since last purge

PEAR_ErrorStack::getErrorMessageTemplate
PEAR_ErrorStack::getFileLine
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::getErrors()

(No version information available, might be only in CVS)

— Retrieve all errors since last purge

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_ErrorStack::getErrors()/funcdef paramdefboolean $purge = FALSE /paramdef paramdefstring|false $level = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::getErrorMessageTemplate
PEAR_ErrorStack::getFileLine
PEAR_ErrorStack


Standard file/line number/function/class context callback

PEAR_ErrorStack::getErrors
PEAR_ErrorStack::getMessageCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::getFileLine()

(No version information available, might be only in CVS)

— Standard file/line number/function/class context callback

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef array|false PEAR_ErrorStack::getFileLine()/funcdef paramdefarray $code /paramdef paramdefunused $params /paramdef paramdefinteger $backtrace = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::getErrors
PEAR_ErrorStack::getMessageCallback
PEAR_ErrorStack


Get an error code => error message mapping callback

PEAR_ErrorStack::getFileLine
PEAR_ErrorStack::hasErrors
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::getMessageCallback()

(No version information available, might be only in CVS)

— Get an error code => error message mapping callback

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef array|string|false PEAR_ErrorStack::getMessageCallback()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::getFileLine
PEAR_ErrorStack::hasErrors
PEAR_ErrorStack


Determine whether there are any errors on the stack

PEAR_ErrorStack::getMessageCallback
PEAR_ErrorStack::pop
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::hasErrors()

(No version information available, might be only in CVS)

— Determine whether there are any errors on the stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_ErrorStack::hasErrors()/funcdef paramdefstring $level = false /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::getMessageCallback
PEAR_ErrorStack::pop
PEAR_ErrorStack


Pop an error off of the error stack

PEAR_ErrorStack::hasErrors
PEAR_ErrorStack::popCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::pop()

(No version information available, might be only in CVS)

— Pop an error off of the error stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef false|array PEAR_ErrorStack::pop()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::hasErrors
PEAR_ErrorStack::popCallback
PEAR_ErrorStack


Remove a callback from the error callback stack

PEAR_ErrorStack::pop
PEAR_ErrorStack::push
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::popCallback()

(No version information available, might be only in CVS)

— Remove a callback from the error callback stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef array|string|false PEAR_ErrorStack::popCallback()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::pop
PEAR_ErrorStack::push
PEAR_ErrorStack


Add an error to the stack

PEAR_ErrorStack::popCallback
PEAR_ErrorStack::pushCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::push()

(No version information available, might be only in CVS)

— Add an error to the stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefPEAR_Error|array PEAR_ErrorStack::push()/funcdef paramdef integer $code /paramdef paramdef string $level = 'error' /paramdef paramdef array $params = array() /paramdef paramdef string $msg = FALSE /paramdef paramdef array $repackage = FALSE /paramdef paramdef array $backtrace = FALSE /paramdef /funcprototype /funcsynopsis

Backwards Compatibility Warning

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.

PEAR_ErrorStack::popCallback
PEAR_ErrorStack::pushCallback
PEAR_ErrorStack


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::push
PEAR_ErrorStack::raiseError
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::pushCallback()

(No version information available, might be only in CVS)

— 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.

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_ErrorStack::pushCallback()/funcdef paramdefstring|array $cb /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::push
PEAR_ErrorStack::raiseError
PEAR_ErrorStack


emulate PEAR::raiseError

PEAR_ErrorStack::pushCallback
PEAR_ErrorStack::setContextCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::raiseError()

(No version information available, might be only in CVS)

— emulate PEAR::raiseError()

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef PEAR_Error PEAR_ErrorStack::raiseError() /funcdef paramdef /funcprototype /funcsynopsis

Description

See PEAR::raiseError()

Throws

No exceptions thrown.

Note

This function can be called statically.

PEAR_ErrorStack::pushCallback
PEAR_ErrorStack::setContextCallback
PEAR_ErrorStack


Set a callback that generates context information (location of error) for an error stack

PEAR_ErrorStack::raiseError
PEAR_ErrorStack::setDefaultCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::setContextCallback()

(No version information available, might be only in CVS)

— Set a callback that generates context information (location of error) for an error stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_ErrorStack::setContextCallback() /funcdef paramdef array|string|null $contextCallback /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::raiseError
PEAR_ErrorStack::setDefaultCallback
PEAR_ErrorStack


Sets a default callback to be used by all error stacks

PEAR_ErrorStack::setContextCallback
PEAR_ErrorStack::setDefaultLogger
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::setDefaultCallback()

(No version information available, might be only in CVS)

— Sets a default callback to be used by all error stacks

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_ErrorStack::setDefaultCallback() /funcdef paramdef array|string $callback = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::setContextCallback
PEAR_ErrorStack::setDefaultLogger
PEAR_ErrorStack


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

PEAR_ErrorStack::setDefaultCallback
PEAR_ErrorStack::setErrorMessageTemplate
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::setDefaultLogger()

(No version information available, might be only in CVS)

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

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_ErrorStack::setDefaultLogger() /funcdef paramdef Log &$log /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::setDefaultCallback
PEAR_ErrorStack::setErrorMessageTemplate
PEAR_ErrorStack


Set the Error Message Template array

PEAR_ErrorStack::setDefaultLogger
PEAR_ErrorStack::setLogger
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::setErrorMessageTemplate()

(No version information available, might be only in CVS)

— Set the Error Message Template array

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef string PEAR_ErrorStack::setErrorMessageTemplate() /funcdef paramdef mixed $template /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::setDefaultLogger
PEAR_ErrorStack::setLogger
PEAR_ErrorStack


Set up a PEAR::Log object for this error stack

PEAR_ErrorStack::setErrorMessageTemplate
PEAR_ErrorStack::setMessageCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::setLogger()

(No version information available, might be only in CVS)

— Set up a PEAR::Log object for this error stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_ErrorStack::setLogger() /funcdef paramdef Log &$log /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::setErrorMessageTemplate
PEAR_ErrorStack::setMessageCallback
PEAR_ErrorStack


Set an error code => error message mapping callback

PEAR_ErrorStack::setLogger
PEAR_ErrorStack::singleton
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::setMessageCallback()

(No version information available, might be only in CVS)

— Set an error code => error message mapping callback

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_ErrorStack::setMessageCallback() /funcdef paramdef mixed $msgCallback /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::setLogger
PEAR_ErrorStack::singleton
PEAR_ErrorStack


Return a single error stack for this package.

PEAR_ErrorStack::setMessageCallback
PEAR_ErrorStack::staticGetErrors
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::singleton()

(No version information available, might be only in CVS)

— Return a single error stack for this package.

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef PEAR_ErrorStack & PEAR_ErrorStack::singleton() /funcdef paramdef string $package /paramdef paramdef callback $msgCallback = FALSE /paramdef paramdef callback $contextCallback = FALSE /paramdef paramdef boolean $throwPEAR_Error = FALSE /paramdef paramdef string $stackClass = 'PEAR_ErrorStack' /paramdef /funcprototype /funcsynopsis

Backwards Compatibility Warning

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.

PEAR_ErrorStack::setMessageCallback
PEAR_ErrorStack::staticGetErrors
PEAR_ErrorStack


Get a list of all errors since last purge, organized by package

PEAR_ErrorStack::singleton
PEAR_ErrorStack::staticHasErrors
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::staticGetErrors()

(No version information available, might be only in CVS)

— Get a list of all errors since last purge, organized by package

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_ErrorStack::staticGetErrors() /funcdef paramdef boolean $purge = FALSE /paramdef paramdef string|false $level = FALSE /paramdef paramdef boolean $merge = FALSE /paramdef paramdef array $sortfunc = array('PEAR_ErrorStack', '_sortErrors') /paramdef /funcprototype /funcsynopsis

Backwards Compatibility Warning

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.

PEAR_ErrorStack::singleton
PEAR_ErrorStack::staticHasErrors
PEAR_ErrorStack


Determine whether there are any errors on any error stack

PEAR_ErrorStack::staticGetErrors
PEAR_ErrorStack::staticPop
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::staticHasErrors()

(No version information available, might be only in CVS)

— Determine whether there are any errors on any error stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef boolean PEAR_ErrorStack::staticHasErrors() /funcdef paramdef string|false $package = false /paramdef paramdef string $level = false /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::staticGetErrors
PEAR_ErrorStack::staticPop
PEAR_ErrorStack


Static version of pop

PEAR_ErrorStack::staticHasErrors
PEAR_ErrorStack::staticPopCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::staticPop()

(No version information available, might be only in CVS)

— Static version of pop()

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef false|array PEAR_ErrorStack::staticPop() /funcdef paramdef string $package /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::staticHasErrors
PEAR_ErrorStack::staticPopCallback
PEAR_ErrorStack


Remove a callback from every error callback stack

PEAR_ErrorStack::staticPop
PEAR_ErrorStack::staticPush
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::staticPopCallback()

(No version information available, might be only in CVS)

— Remove a callback from every error callback stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef array|string|false PEAR_ErrorStack::staticPopCallback() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::staticPop
PEAR_ErrorStack::staticPush
PEAR_ErrorStack


Static version of push

PEAR_ErrorStack::staticPopCallback
PEAR_ErrorStack::staticPushCallback
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::staticPush()

(No version information available, might be only in CVS)

— Static version of push()

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef PEAR_Error|array PEAR_ErrorStack::staticPush() /funcdef paramdef string $package /paramdef paramdef integer $code /paramdef paramdef string $level = 'error' /paramdef paramdef array $params = array() /paramdef paramdef string $msg = FALSE /paramdef paramdef array $repackage = FALSE /paramdef paramdef array $backtrace = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::staticPopCallback
PEAR_ErrorStack::staticPushCallback
PEAR_ErrorStack


Set an error Callback for every package's error stack

PEAR_ErrorStack::staticPush
PEAR_ErrorStack::_log
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::staticPushCallback()

(No version information available, might be only in CVS)

— Set an error Callback for every package's error stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_ErrorStack::staticPushCallback() /funcdef paramdef string|array $cb /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::staticPush
PEAR_ErrorStack::_log
PEAR_ErrorStack


Log an error using PEAR::Log

PEAR_ErrorStack::staticPushCallback
Package PEAR_ErrorStack Constants
PEAR_ErrorStack
PHP Manual

PEAR_ErrorStack::_log()

(No version information available, might be only in CVS)

— Log an error using PEAR::Log

funcsynopsis funcsynopsisinfo require_once 'PEAR/ErrorStack.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_ErrorStack::_log()/funcdef paramdefarray $err /paramdef paramdefarray $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) /paramdef /funcprototype /funcsynopsis

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.

PEAR_ErrorStack::staticPushCallback
Package PEAR_ErrorStack Constants
PEAR_ErrorStack


Constants defined in and used by PEAR_ErrorStack

PEAR_ErrorStack
PEAR Error object
PEAR_ErrorStack
PHP Manual

Package PEAR_ErrorStack Constants

(No version information available, might be only in CVS)

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

PEAR_ErrorStack
PEAR Error object
PEAR_ErrorStack


PEAR_Error [deprecated]

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()

Package PEAR_ErrorStack Constants
PEAR_Error::addUserInfo()
PEAR base classes


add user information

PEAR Error object
PEAR_Error::getCallback()
PEAR Error object
PHP Manual

PEAR_Error::addUserInfo()

(No version information available, might be only in CVS)

PEAR_Error::addUserInfo() — add user information

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Error::addUserInfo()/funcdef paramdef string $info /paramdef /funcprototype /funcsynopsis

Description

Adds an user information to the error object.

Parameter

  • string - user info

Note

This function can not be called statically.

PEAR Error object
PEAR_Error::getCallback()
PEAR Error object


get callback function name

PEAR_Error::addUserInfo()
PEAR_Error::getCode()
PEAR Error object
PHP Manual

PEAR_Error::getCallback()

(No version information available, might be only in CVS)

PEAR_Error::getCallback() — get callback function name

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Error::getCallback()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Error::addUserInfo()
PEAR_Error::getCode()
PEAR Error object


get error code

PEAR_Error::getCallback()
PEAR_Error::getMessage()
PEAR Error object
PHP Manual

PEAR_Error::getCode()

(No version information available, might be only in CVS)

PEAR_Error::getCode() — get error code

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefinteger PEAR_Error::getCode()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the error code coming with the error object.

Return value

integer - error number

Note

This function can not be called statically.

PEAR_Error::getCallback()
PEAR_Error::getMessage()
PEAR Error object


get error message

PEAR_Error::getCode()
PEAR_Error::getMode()
PEAR Error object
PHP Manual

PEAR_Error::getMessage()

(No version information available, might be only in CVS)

PEAR_Error::getMessage() — get error message

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Error::getMessage()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the error message coming with the error object.

Return value

string - error message

Note

This function can not be called statically.

PEAR_Error::getCode()
PEAR_Error::getMode()
PEAR Error object


get error mode

PEAR_Error::getMessage()
PEAR_Error::getDebugInfo()
PEAR Error object
PHP Manual

PEAR_Error::getMode()

(No version information available, might be only in CVS)

PEAR_Error::getMode() — get error mode

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefinteger PEAR_Error::getMode()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the error mode used for throwing the error object.

Return value

integer - error mode

Note

This function can not be called statically.

PEAR_Error::getMessage()
PEAR_Error::getDebugInfo()
PEAR Error object


get debug information

PEAR_Error::getMode()
PEAR_Error::getType()
PEAR Error object
PHP Manual

PEAR_Error::getDebugInfo()

(No version information available, might be only in CVS)

PEAR_Error::getDebugInfo() — get debug information

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Error::getDebugInfo()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns debug information about an error

Return value

string - error debug information

Note

This function can not be called statically.

PEAR_Error::getMode()
PEAR_Error::getType()
PEAR Error object


get error type

PEAR_Error::getDebugInfo()
PEAR_Error::getUserInfo()
PEAR Error object
PHP Manual

PEAR_Error::getType()

(No version information available, might be only in CVS)

PEAR_Error::getType() — get error type

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefinteger PEAR_Error::getType()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Error::getDebugInfo()
PEAR_Error::getUserInfo()
PEAR Error object


get additional user-supplied information

PEAR_Error::getType()
PEAR_Error::PEAR_Error()
PEAR Error object
PHP Manual

PEAR_Error::getUserInfo()

(No version information available, might be only in CVS)

PEAR_Error::getUserInfo() — get additional user-supplied information

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Error::getUserInfo()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns additional information about an error

Return value

string - error information

Note

This function can not be called statically.

PEAR_Error::getType()
PEAR_Error::PEAR_Error()
PEAR Error object


constructor

PEAR_Error::getUserInfo()
PEAR_Error::toString()
PEAR Error object
PHP Manual

PEAR_Error::PEAR_Error()

(No version information available, might be only in CVS)

PEAR_Error::PEAR_Error() — constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Error::PEAR_Error()/funcdef paramdef string $message = 'unknown error' /paramdef paramdef integer $code = NULL /paramdef paramdef integer $mode = NULL /paramdef paramdef mixed $options = NULL /paramdef paramdef string $userinfo = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Error::getUserInfo()
PEAR_Error::toString()
PEAR Error object


make string representation

PEAR Error object
System
PEAR Error object
PHP Manual

PEAR_Error::toString()

(No version information available, might be only in CVS)

PEAR_Error::toString() — make string representation

funcsynopsis funcsynopsisinfo require_once 'PEAR.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Error::toString()/funcdef paramdef /funcprototype /funcsynopsis

Description

Makes a string representation of the error object.

Return value

string - object representation

Note

This function can not be called statically.

PEAR Error object
System
PEAR Error object


System

Commandline functions

System provides an API for cross platform compatible commandline programs.

PEAR base classes
Introduction
PEAR base classes


General usage informations

System
System::rm
System
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — General usage informations

Command line style

The System functions are called like there commandline pendants

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:
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.

Warning

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

System
System::rm
System


remove files

Introduction
System::mkDir
System
PHP Manual

System::rm

(No version information available, might be only in CVS)

System::rm — remove files

funcsynopsis funcsynopsisinfo require_once "System.php"; /funcsynopsisinfo funcprototype funcdefmixed System::rm()/funcdef paramdef string $args /paramdef /funcprototype /funcsynopsis

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

Introduction
System::mkDir
System


create directories

System::rm
System::&cat
System
PHP Manual

System::mkDir

(No version information available, might be only in CVS)

System::mkDir — create directories

funcsynopsis funcsynopsisinfo require_once "System.php"; /funcsynopsisinfo funcprototype funcdefbool System::mkDir()/funcdef paramdef string $args /paramdef /funcprototype /funcsynopsis

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

System::rm
System::&cat
System


concatenate files

System::mkDir
System::mktemp
System
PHP Manual

System::&cat

(No version information available, might be only in CVS)

System::&cat — concatenate files

funcsynopsis funcsynopsisinfo require_once "System.php"; /funcsynopsisinfo funcprototype funcdefboolean System::&cat()/funcdef paramdef string $args /paramdef /funcprototype /funcsynopsis

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

Example #1 Using &cat()

$var = System::cat('sample.txt test.txt');
       System::cat('sample.txt test.txt > final.txt');
       System::cat('sample.txt test.txt >> final.txt');
System::mkDir
System::mktemp
System


Create temporary files or directories

System::&cat
System::tmpdir
System
PHP Manual

System::mktemp

(No version information available, might be only in CVS)

System::mktemp — Create temporary files or directories

funcsynopsis funcsynopsisinfo require_once "System.php"; /funcsynopsisinfo funcprototype funcdefmixed System::mktemp()/funcdef paramdef string $args = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Using mktemp()

$tempfile = System::mktemp("prefix");
$tempdir  = System::mktemp("-d prefix");
$tempfile = System::mktemp();
$tempfile = System::mktemp("-t /var/tmp prefix");
System::&cat
System::tmpdir
System


Get path of temporal directory

System::mktemp
System::which
System
PHP Manual

System::tmpdir

(No version information available, might be only in CVS)

System::tmpdir — Get path of temporal directory

funcsynopsis funcsynopsisinfo require_once "System.php"; /funcsynopsisinfo funcprototype funcdefstring System::tmpdir()/funcdef paramdef /funcprototype /funcsynopsis

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

System::mktemp
System::which
System


show full path of a command

System
PEAR Installer classes
System
PHP Manual

System::which

(No version information available, might be only in CVS)

System::which — show full path of a command

funcsynopsis funcsynopsisinfo require_once "System.php"; /funcsynopsisinfo funcprototype funcdefmixed System::which()/funcdef paramdef string $program /paramdef paramdef boolean $fallback = FALSE /paramdef /funcprototype /funcsynopsis

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

System
PEAR Installer classes
System


PEAR Installer classes

Table of Contents

  • Add an aggregate object to object.
  • Add one or more autoload entries
  • Remove an aggregate object
  • Remove an autoload entry
  • Overloaded object call handler
  • 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.

Warning

Documentation is not fully up-to-date with PEAR version 1.4.0.

PEAR_Autoload

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

System::which
PEAR_Autoloader::addAggregateObject
Core components


Add an aggregate object to object.

System
PHP Manual

PEAR_Autoloader::addAggregateObject()

(No version information available, might be only in CVS)

— Add an aggregate object to object.

funcsynopsis funcsynopsisinfo require_once 'PEAR/autoloader.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Autoloader::addAggregateObject()/funcdef paramdefstring $classname /paramdef /funcprototype /funcsynopsis

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.

System


Add one or more autoload entries

System
PHP Manual

PEAR_Autoloader::addAutoload()

(No version information available, might be only in CVS)

— Add one or more autoload entries

funcsynopsis funcsynopsisinfo require_once 'PEAR/autoloader.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Autoloader::addAutoload()/funcdef paramdefstring $method /paramdef paramdefstring ''$classname = NULL /paramdef /funcprototype /funcsynopsis

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.

System


Remove an aggregate object

System
PHP Manual

PEAR_Autoloader::removeAggregateObject()

(No version information available, might be only in CVS)

— Remove an aggregate object

funcsynopsis funcsynopsisinfo require_once 'PEAR/autoloader.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Autoloader::removeAggregateObject()/funcdef paramdefstring $classname /paramdef /funcprototype /funcsynopsis

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.

System


Remove an autoload entry

System
PHP Manual

PEAR_Autoloader::removeAutoload()

(No version information available, might be only in CVS)

— Remove an autoload entry

funcsynopsis funcsynopsisinfo require_once 'autoloader.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Autoloader::removeAutoload()/funcdef paramdefstring $method /paramdef /funcprototype /funcsynopsis

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.

System


Overloaded object call handler

System
PHP Manual

PEAR_Autoloader::__call()

(No version information available, might be only in CVS)

— Overloaded object call handler

funcsynopsis funcsynopsisinfo require_once 'PEAR/autoloader.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Autoloader::__call()/funcdef paramdefstring $method /paramdef paramdefstring $args /paramdef paramdefmixed &$retval /paramdef /funcprototype /funcsynopsis

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.

System


PEAR_Builder

Class to handle building (compiling) extensions.

Class Trees for PEAR_Builder

  • PEAR_Common

    • PEAR_Builder

PEAR_Autoloader::__call
PEAR_Builder::PEAR_Builder
PEAR Installer classes


constructor

PEAR_Builder
PEAR_Builder::build
PEAR_Builder
PHP Manual

PEAR_Builder::PEAR_Builder()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/builder.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Builder::PEAR_Builder()/funcdef paramdefobject &$ui /paramdef /funcprototype /funcsynopsis

Description

PEAR_Builder constructor

Parameter

object &$ui

user interface object (instance of PEAR_Frontend_*)

Note

This function can be called statically.

PEAR_Builder
PEAR_Builder::build
PEAR_Builder


Build an extension from source

PEAR_Builder::PEAR_Builder
PEAR_Builder::log
PEAR_Builder
PHP Manual

PEAR_Builder::build()

(No version information available, might be only in CVS)

— Build an extension from source

funcsynopsis funcsynopsisinfo require_once 'PEAR/builder.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Builder::build()/funcdef paramdefstring $descfile /paramdef paramdefmixed $callback = NULL /paramdef /funcprototype /funcsynopsis

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:

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.

PEAR_Builder::PEAR_Builder
PEAR_Builder::log
PEAR_Builder


PEAR_Builder::log

PEAR_Builder::build
PEAR_Builder::phpizeCallback
PEAR_Builder
PHP Manual

PEAR_Builder::log()

(No version information available, might be only in CVS)

—

funcsynopsis funcsynopsisinfo require_once 'PEAR/builder.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Builder::log()/funcdef paramdefmixed $level /paramdef paramdefmixed $msg /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

mixed $level

mixed $msg

Note

This function can not be called statically.

PEAR_Builder::build
PEAR_Builder::phpizeCallback
PEAR_Builder


Message callback function when running phpize

PEAR_Builder
PEAR_ChannelFile
PEAR_Builder
PHP Manual

PEAR_Builder::phpizeCallback()

(No version information available, might be only in CVS)

— Message callback function when running phpize

funcsynopsis funcsynopsisinfo require_once 'PEAR/builder.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Builder::phpizeCallback()/funcdef paramdefstring $what /paramdef paramdefmixed $data /paramdef /funcprototype /funcsynopsis

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.

PEAR_Builder
PEAR_ChannelFile
PEAR_Builder


PEAR_ChannelFile

PEAR_Builder::phpizeCallback
Class Summary PEAR_ChannelFile
PEAR Installer classes


PEAR_ChannelFile
constructor PEAR_ChannelFile::PEAR_ChannelFile
PEAR_ChannelFile
PHP Manual

Class Summary PEAR_ChannelFile

(No version information available, might be only in CVS)

Class Summary — The Channel handling class

The Channel handling class

Represents channel.xml

Class Trees for PEAR_ChannelFile

  • PEAR_ChannelFile

PEAR_ChannelFile
constructor PEAR_ChannelFile::PEAR_ChannelFile
PEAR_ChannelFile


PEAR_ChannelFile

Class Summary PEAR_ChannelFile
PEAR_ChannelFile::addFunction
PEAR_ChannelFile
PHP Manual

constructor PEAR_ChannelFile::PEAR_ChannelFile()

(No version information available, might be only in CVS)

constructor — PEAR_ChannelFile

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void constructor PEAR_ChannelFile::PEAR_ChannelFile() /funcdef paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_ChannelFile
PEAR_ChannelFile::addFunction
PEAR_ChannelFile


Add a protocol to the provides section

constructor PEAR_ChannelFile::PEAR_ChannelFile
PEAR_ChannelFile::addMirror
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::addFunction()

(No version information available, might be only in CVS)

— Add a protocol to the provides section

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::addFunction() /funcdef paramdef string $type /paramdef paramdef string $version /paramdef paramdef string $name = '' /paramdef paramdef string $mirror = false /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_ChannelFile::PEAR_ChannelFile
PEAR_ChannelFile::addMirror
PEAR_ChannelFile


addMirror

PEAR_ChannelFile::addFunction
PEAR_ChannelFile::addMirrorFunction
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::addMirror()

(No version information available, might be only in CVS)

— addMirror

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef boolean PEAR_ChannelFile::addMirror() /funcdef paramdef string $server /paramdef paramdef int $port = null /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::addFunction
PEAR_ChannelFile::addMirrorFunction
PEAR_ChannelFile


Add a protocol to a mirror's provides section

PEAR_ChannelFile::addMirror
PEAR_ChannelFile::fromAny
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::addMirrorFunction()

(No version information available, might be only in CVS)

— Add a protocol to a mirror's provides section

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::addMirrorFunction() /funcdef paramdef string $mirror /paramdef paramdef string $type /paramdef paramdef string $version /paramdef paramdef string $name = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::addMirror
PEAR_ChannelFile::fromAny
PEAR_ChannelFile


Returns channel information from different sources

PEAR_ChannelFile::addMirrorFunction
PEAR_ChannelFile::fromArray
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::fromAny()

(No version information available, might be only in CVS)

— Returns channel information from different sources

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::fromAny() /funcdef paramdef string $info /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::addMirrorFunction
PEAR_ChannelFile::fromArray
PEAR_ChannelFile


fromArray

PEAR_ChannelFile::fromAny
PEAR_ChannelFile::fromXmlFile
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::fromArray()

(No version information available, might be only in CVS)

— fromArray

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_ChannelFile |false PEAR_ChannelFile::fromArray() /funcdef paramdef array $data /paramdef paramdef mixed $compatibility = FALSE /paramdef paramdef mixed $stackClass = 'PEAR_ErrorStack' /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::fromAny
PEAR_ChannelFile::fromXmlFile
PEAR_ChannelFile


Parse a channel.xml file. Expects the name of a channel xml file as input.

PEAR_ChannelFile::fromArray
PEAR_ChannelFile::fromXmlString
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::fromXmlFile()

(No version information available, might be only in CVS)

— Parse a channel.xml file. Expects the name of a channel xml file as input.

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::fromXmlFile() /funcdef paramdef string $descfile /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::fromArray
PEAR_ChannelFile::fromXmlString
PEAR_ChannelFile


fromXmlString

PEAR_ChannelFile::fromXmlFile
PEAR_ChannelFile::getAlias
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::fromXmlString()

(No version information available, might be only in CVS)

— fromXmlString

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::fromXmlString() /funcdef paramdef string $data /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::fromXmlFile
PEAR_ChannelFile::getAlias
PEAR_ChannelFile


Return the suggested alias users can use to refer to this channel on the command-line.

PEAR_ChannelFile::fromXmlString
PEAR_ChannelFile::getBaseURL
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getAlias()

(No version information available, might be only in CVS)

— Return the suggested alias users can use to refer to this channel on the command-line.

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string PEAR_ChannelFile::getAlias() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::fromXmlString
PEAR_ChannelFile::getBaseURL
PEAR_ChannelFile


Get the URL to access a base resource.

PEAR_ChannelFile::getAlias
PEAR_ChannelFile::getErrors
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getBaseURL()

(No version information available, might be only in CVS)

— Get the URL to access a base resource.

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string PEAR_ChannelFile::getBaseURL() /funcdef paramdef string $resourceType /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getAlias
PEAR_ChannelFile::getErrors
PEAR_ChannelFile


Wrapper to PEAR_ErrorStack::getErrors()

PEAR_ChannelFile::getBaseURL
PEAR_ChannelFile::getFunction
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getErrors()

(No version information available, might be only in CVS)

— Wrapper to PEAR_ErrorStack::getErrors()

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef array PEAR_ChannelFile::getErrors() /funcdef paramdef boolean $purge = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getBaseURL
PEAR_ChannelFile::getFunction
PEAR_ChannelFile


getFunction

PEAR_ChannelFile::getErrors
PEAR_ChannelFile::getFunctions
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getFunction()

(No version information available, might be only in CVS)

— getFunction

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef array PEAR_ChannelFile::getFunction() /funcdef paramdef string $type /paramdef paramdef string $name = NULL /paramdef paramdef string $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getErrors
PEAR_ChannelFile::getFunctions
PEAR_ChannelFile


Retrieve a list of all xmlrpc/soap functions

PEAR_ChannelFile::getFunction
PEAR_ChannelFile::getMirror
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getFunctions()

(No version information available, might be only in CVS)

— Retrieve a list of all xmlrpc/soap functions

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef array|false PEAR_ChannelFile::getFunctions() /funcdef paramdef string $protocol /paramdef paramdef string $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getFunction
PEAR_ChannelFile::getMirror
PEAR_ChannelFile


Get the unserialized XML representing a mirror

PEAR_ChannelFile::getFunctions
PEAR_ChannelFile::getMirrors
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getMirror()

(No version information available, might be only in CVS)

— Get the unserialized XML representing a mirror

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef array|false PEAR_ChannelFile::getMirror() /funcdef paramdef mixed $server /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getFunctions
PEAR_ChannelFile::getMirrors
PEAR_ChannelFile


Retrieve a list of all mirrors and their contents

PEAR_ChannelFile::getMirror
PEAR_ChannelFile::getName
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getMirrors()

(No version information available, might be only in CVS)

— Retrieve a list of all mirrors and their contents

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef array PEAR_ChannelFile::getMirrors() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getMirror
PEAR_ChannelFile::getName
PEAR_ChannelFile


retrieve the channel name

PEAR_ChannelFile::getMirrors
PEAR_ChannelFile::getPath
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getName()

(No version information available, might be only in CVS)

— retrieve the channel name

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string|false PEAR_ChannelFile::getName() /funcdef paramdef /funcprototype /funcsynopsis

Description

Note that the channel name is the channel server.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

PEAR_ChannelFile::getMirrors
PEAR_ChannelFile::getPath
PEAR_ChannelFile


getPath

PEAR_ChannelFile::getName
PEAR_ChannelFile::getPort
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getPath()

(No version information available, might be only in CVS)

— getPath

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string PEAR_ChannelFile::getPath() /funcdef paramdef string $protocol /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getName
PEAR_ChannelFile::getPort
PEAR_ChannelFile


retrieve the socket port used to connect to the server

PEAR_ChannelFile::getPath
PEAR_ChannelFile::getServer
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getPort()

(No version information available, might be only in CVS)

— retrieve the socket port used to connect to the server

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef int|80 PEAR_ChannelFile::getPort() /funcdef paramdef mixed $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getPath
PEAR_ChannelFile::getServer
PEAR_ChannelFile


Retrieve the channel server

PEAR_ChannelFile::getPort
PEAR_ChannelFile::getSSL
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getServer()

(No version information available, might be only in CVS)

— Retrieve the channel server

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string|false PEAR_ChannelFile::getServer() /funcdef paramdef /funcprototype /funcsynopsis

Description

This is an alias for getName().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

PEAR_ChannelFile::getPort
PEAR_ChannelFile::getSSL
PEAR_ChannelFile


get SSL support for a channel or mirror

PEAR_ChannelFile::getServer
PEAR_ChannelFile::getSummary
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getSSL()

(No version information available, might be only in CVS)

— get SSL support for a channel or mirror

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::getSSL() /funcdef paramdef mixed $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getServer
PEAR_ChannelFile::getSummary
PEAR_ChannelFile


Get channel summary

PEAR_ChannelFile::getSSL
PEAR_ChannelFile::getValidationObject
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getSummary()

(No version information available, might be only in CVS)

— Get channel summary

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string|false PEAR_ChannelFile::getSummary() /funcdef paramdef /funcprototype /funcsynopsis

Description

Return the brief description of a channel's purpose.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

PEAR_ChannelFile::getSSL
PEAR_ChannelFile::getValidationObject
PEAR_ChannelFile


Retrieve the object that can be used for custom validation

PEAR_ChannelFile::getSummary
PEAR_ChannelFile::getValidationPackage
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getValidationObject()

(No version information available, might be only in CVS)

— Retrieve the object that can be used for custom validation

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_Validate|false & PEAR_ChannelFile::getValidationObject() /funcdef paramdef string|false $package = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getSummary
PEAR_ChannelFile::getValidationPackage
PEAR_ChannelFile


Retrieve the name of the validation package for this channel

PEAR_ChannelFile::getValidationObject
PEAR_ChannelFile::isIncludeable
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::getValidationPackage()

(No version information available, might be only in CVS)

— Retrieve the name of the validation package for this channel

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string|false PEAR_ChannelFile::getValidationPackage() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getValidationObject
PEAR_ChannelFile::isIncludeable
PEAR_ChannelFile


Determine whether a file exists in the include_path and is readable

PEAR_ChannelFile::getValidationPackage
PEAR_ChannelFile::lastModified
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::isIncludeable()

(No version information available, might be only in CVS)

— Determine whether a file exists in the include_path and is readable

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::isIncludeable() /funcdef paramdef string $path /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::getValidationPackage
PEAR_ChannelFile::lastModified
PEAR_ChannelFile


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::isIncludeable
PEAR_ChannelFile::resetFunctions
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::lastModified()

(No version information available, might be only in CVS)

— 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

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string PEAR_ChannelFile::lastModified() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::isIncludeable
PEAR_ChannelFile::resetFunctions
PEAR_ChannelFile


Empty all protocol definitions

PEAR_ChannelFile::lastModified
PEAR_ChannelFile::resetREST
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::resetFunctions()

(No version information available, might be only in CVS)

— Empty all protocol definitions

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::resetFunctions() /funcdef paramdef string $type /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::lastModified
PEAR_ChannelFile::resetREST
PEAR_ChannelFile


Since REST does not implement RPC, provide this as a logical wrapper around resetFunctions for REST

PEAR_ChannelFile::resetFunctions
PEAR_ChannelFile::setAlias
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::resetREST()

(No version information available, might be only in CVS)

— Since REST does not implement RPC, provide this as a logical wrapper around resetFunctions for REST

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::resetREST() /funcdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::resetFunctions
PEAR_ChannelFile::setAlias
PEAR_ChannelFile


Set the channel alias

PEAR_ChannelFile::resetREST
PEAR_ChannelFile::setBaseURL
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setAlias()

(No version information available, might be only in CVS)

— Set the channel alias

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef boolean PEAR_ChannelFile::setAlias() /funcdef paramdef string $alias /paramdef paramdef boolean $local = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::resetREST
PEAR_ChannelFile::setBaseURL
PEAR_ChannelFile


set the base URL for a REST resource, or set of REST resources

PEAR_ChannelFile::setAlias
PEAR_ChannelFile::setDefaultPEARProtocols
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setBaseURL()

(No version information available, might be only in CVS)

— set the base URL for a REST resource, or set of REST resources

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::setBaseURL() /funcdef paramdef string $resourceType /paramdef paramdef string $url /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setAlias
PEAR_ChannelFile::setDefaultPEARProtocols
PEAR_ChannelFile


Set a channel's protocols to the protocols supported by pearweb

PEAR_ChannelFile::setBaseURL
PEAR_ChannelFile::setName
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setDefaultPEARProtocols()

(No version information available, might be only in CVS)

— Set a channel's protocols to the protocols supported by pearweb

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::setDefaultPEARProtocols() /funcdef paramdef string $version = '1.0' /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setBaseURL
PEAR_ChannelFile::setName
PEAR_ChannelFile


setName

PEAR_ChannelFile::setDefaultPEARProtocols
PEAR_ChannelFile::setPath
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setName()

(No version information available, might be only in CVS)

— setName

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string|false PEAR_ChannelFile::setName() /funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setDefaultPEARProtocols
PEAR_ChannelFile::setPath
PEAR_ChannelFile


Set the file path for xmlrpc or soap

PEAR_ChannelFile::setName
PEAR_ChannelFile::setPort
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setPath()

(No version information available, might be only in CVS)

— Set the file path for xmlrpc or soap

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::setPath() /funcdef paramdef string $protocol /paramdef paramdef string|false $path /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setName
PEAR_ChannelFile::setPort
PEAR_ChannelFile


Set the socket number (port) that is used to connect to this channel

PEAR_ChannelFile::setPath
PEAR_ChannelFile::setServer
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setPort()

(No version information available, might be only in CVS)

— Set the socket number (port) that is used to connect to this channel

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::setPort() /funcdef paramdef integer $port /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setPath
PEAR_ChannelFile::setServer
PEAR_ChannelFile


set the Channel server

PEAR_ChannelFile::setPort
PEAR_ChannelFile::setSSL
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setServer()

(No version information available, might be only in CVS)

— set the Channel server

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string|false PEAR_ChannelFile::setServer() /funcdef paramdef string $server /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setPort
PEAR_ChannelFile::setSSL
PEAR_ChannelFile


Sets whether SSL is used to connect to this channel

PEAR_ChannelFile::setServer
PEAR_ChannelFile::setSummary
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setSSL()

(No version information available, might be only in CVS)

— Sets whether SSL is used to connect to this channel

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_ChannelFile::setSSL() /funcdef paramdef bool $ssl = TRUE /paramdef paramdef string|false $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setServer
PEAR_ChannelFile::setSummary
PEAR_ChannelFile


set the summary of a channel's purpose

PEAR_ChannelFile::setSSL
PEAR_ChannelFile::setValidationPackage
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setSummary()

(No version information available, might be only in CVS)

— set the summary of a channel's purpose

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef boolean PEAR_ChannelFile::setSummary() /funcdef paramdef string $summary /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setSSL
PEAR_ChannelFile::setValidationPackage
PEAR_ChannelFile


Set the package validation object if it differs from PEAR's default.

PEAR_ChannelFile::setSummary
PEAR_ChannelFile::supports
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::setValidationPackage()

(No version information available, might be only in CVS)

— Set the package validation object if it differs from PEAR's default.

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef boolean PEAR_ChannelFile::setValidationPackage() /funcdef paramdef string|false $validateclass /paramdef paramdef string $version /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setSummary
PEAR_ChannelFile::supports
PEAR_ChannelFile


determines whether a webservices function is supported by a channel

PEAR_ChannelFile::setValidationPackage
PEAR_ChannelFile::supportsREST
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::supports()

(No version information available, might be only in CVS)

— determines whether a webservices function is supported by a channel

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef boolean PEAR_ChannelFile::supports() /funcdef paramdef string $type /paramdef paramdef string $name = NULL /paramdef paramdef string|false $mirror = FALSE /paramdef paramdef string $version = '1.0' /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::setValidationPackage
PEAR_ChannelFile::supportsREST
PEAR_ChannelFile


Determines whether a channel supports any Representational State Transfer (REST) resources

PEAR_ChannelFile::supports
PEAR_ChannelFile::toArray
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::supportsREST()

(No version information available, might be only in CVS)

— Determines whether a channel supports any Representational State Transfer (REST) resources

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::supportsREST() /funcdef paramdef string $mirror = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::supports
PEAR_ChannelFile::toArray
PEAR_ChannelFile


return the channel representation in array format

PEAR_ChannelFile::supportsREST
PEAR_ChannelFile::toXml
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::toArray()

(No version information available, might be only in CVS)

— return the channel representation in array format

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef array PEAR_ChannelFile::toArray() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::supportsREST
PEAR_ChannelFile::toXml
PEAR_ChannelFile


Return an XML document based on the internal representation of this channel

PEAR_ChannelFile::toArray
PEAR_ChannelFile::validate
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::toXml()

(No version information available, might be only in CVS)

— Return an XML document based on the internal representation of this channel

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef string PEAR_ChannelFile::toXml() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::toArray
PEAR_ChannelFile::validate
PEAR_ChannelFile


Validate channel information.

PEAR_ChannelFile::toXml
PEAR_ChannelFile::validChannelServer
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::validate()

(No version information available, might be only in CVS)

— Validate channel information.

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef boolean PEAR_ChannelFile::validate() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::toXml
PEAR_ChannelFile::validChannelServer
PEAR_ChannelFile


Test whether a string contains a valid channel server.

PEAR_ChannelFile::validate
Package PEAR Constants
PEAR_ChannelFile
PHP Manual

PEAR_ChannelFile::validChannelServer()

(No version information available, might be only in CVS)

— Test whether a string contains a valid channel server.

funcsynopsis funcsynopsisinforequire_once '/ChannelFile.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_ChannelFile::validChannelServer() /funcdef paramdef string $server /paramdef /funcprototype /funcsynopsis

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.

PEAR_ChannelFile::validate
Package PEAR Constants
PEAR_ChannelFile


Constants defined in and used by PEAR

PEAR_ChannelFile
PEAR_Command
PEAR_ChannelFile
PHP Manual

Package PEAR Constants

(No version information available, might be only in CVS)

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

PEAR_ChannelFile
PEAR_Command
PEAR_ChannelFile


PEAR_Command

PEAR command class, a simple factory class for administrative commands.

Package PEAR Constants
PEAR_Command::factory
PEAR Installer classes


get object for executing a command.

PEAR_Command
PEAR_Command::getCommands
PEAR_Command
PHP Manual

PEAR_Command::factory()

(No version information available, might be only in CVS)

— get object for executing a command.

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdefobject PEAR_Command::factory()/funcdef paramdefstring $command /paramdef paramdefobject &$config /paramdef /funcprototype /funcsynopsis

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.

PEAR_Command
PEAR_Command::getCommands
PEAR_Command


get list of currently supported commands

PEAR_Command::factory
PEAR_Command::getDescription
PEAR_Command
PHP Manual

PEAR_Command::getCommands()

(No version information available, might be only in CVS)

— get list of currently supported commands

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Command::getCommands()/funcdef ( void /funcprototype /funcsynopsis

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.

PEAR_Command::factory
PEAR_Command::getDescription
PEAR_Command


get description for a command

PEAR_Command::getCommands
PEAR_Command::getGetoptArgs
PEAR_Command
PHP Manual

PEAR_Command::getDescription()

(No version information available, might be only in CVS)

— get description for a command

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Command::getDescription()/funcdef paramdefstring $command /paramdef /funcprototype /funcsynopsis

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.

PEAR_Command::getCommands
PEAR_Command::getGetoptArgs
PEAR_Command


compiles arguments for getopt

PEAR_Command::getDescription
PEAR_Command::getHelp
PEAR_Command
PHP Manual

PEAR_Command::getGetoptArgs()

(No version information available, might be only in CVS)

— compiles arguments for getopt

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Command::getGetoptArgs()/funcdef paramdefstring $command /paramdef paramdefstring &$short_args /paramdef paramdefarray &$long_args /paramdef /funcprototype /funcsynopsis

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.

PEAR_Command::getDescription
PEAR_Command::getHelp
PEAR_Command


get help for command

PEAR_Command::getGetoptArgs
PEAR_Command::getShortcuts
PEAR_Command
PHP Manual

PEAR_Command::getHelp()

(No version information available, might be only in CVS)

— get help for command

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Command::getHelp()/funcdef paramdefstring $command /paramdef /funcprototype /funcsynopsis

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.

PEAR_Command::getGetoptArgs
PEAR_Command::getShortcuts
PEAR_Command


get list of command shortcuts.

PEAR_Command::getHelp
PEAR_Command::registerCommands
PEAR_Command
PHP Manual

PEAR_Command::getShortcuts()

(No version information available, might be only in CVS)

— get list of command shortcuts.

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Command::getShortcuts()/funcdef ( void /funcprototype /funcsynopsis

Description

Get the list of command shortcuts.

Return value

array shortcut => command

Note

This function should be called statically.

PEAR_Command::getHelp
PEAR_Command::registerCommands
PEAR_Command


scan the command directory

PEAR_Command
PEAR_Common
PEAR_Command
PHP Manual

PEAR_Command::registerCommands()

(No version information available, might be only in CVS)

— scan the command directory

funcsynopsis funcsynopsisinfo require_once 'PEAR/command.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Command::registerCommands()/funcdef paramdefbool $merge = FALSE /paramdef paramdefstring $dir = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Command
PEAR_Common
PEAR_Command


PEAR_Common

Class providing common functionality for PEAR administration classes.

Class Trees for PEAR_Common()

  • PEAR

    • PEAR_Common

PEAR_Command::registerCommands
PEAR_Common::PEAR_Common
PEAR Installer classes


PEAR_Common constructor

PEAR_Common
PEAR_Common::addTempFile
PEAR_Common
PHP Manual

PEAR_Common::PEAR_Common()

(No version information available, might be only in CVS)

— PEAR_Common constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Common::PEAR_Common()/funcdef ( void /funcprototype /funcsynopsis

Description

PEAR_Common constructor

Note

This function can be called statically.

PEAR_Common
PEAR_Common::addTempFile
PEAR_Common


register a temporary file or directory

PEAR_Common::PEAR_Common
PEAR_Common::analyzeSourceCode
PEAR_Common
PHP Manual

PEAR_Common::addTempFile()

(No version information available, might be only in CVS)

— register a temporary file or directory

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Common::addTempFile()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::PEAR_Common
PEAR_Common::analyzeSourceCode
PEAR_Common


analyze the source code of the given PHP file

PEAR_Common::addTempFile
PEAR_Common::buildProvidesArray
PEAR_Common
PHP Manual

PEAR_Common::analyzeSourceCode()

(No version information available, might be only in CVS)

— analyze the source code of the given PHP file

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Common::analyzeSourceCode()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::addTempFile
PEAR_Common::buildProvidesArray
PEAR_Common


Build a array

PEAR_Common::analyzeSourceCode
PEAR_Common::downloadHttp
PEAR_Common
PHP Manual

PEAR_Common::buildProvidesArray()

(No version information available, might be only in CVS)

— Build a array

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Common::buildProvidesArray()/funcdef paramdefarray $srcinfo /paramdef /funcprototype /funcsynopsis

Description

Build a "provides" array from data returned by analyzeSourceCode(). The format of the built array is like this:

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.

PEAR_Common::analyzeSourceCode
PEAR_Common::downloadHttp
PEAR_Common


Download a file through HTTP

PEAR_Common::buildProvidesArray
PEAR_Common::infoFromAny
PEAR_Common
PHP Manual

PEAR_Common::downloadHttp()

(No version information available, might be only in CVS)

— Download a file through HTTP

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Common::downloadHttp()/funcdef paramdefstring $url /paramdef paramdefobject &$ui /paramdef paramdefstring $save_dir = '.' /paramdef paramdefmixed $callback = NULL /paramdef /funcprototype /funcsynopsis

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

    array(host,port,errno,errmsg)

  • 'writefailed' - if writing to disk fails, this callback is called with

    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.

PEAR_Common::buildProvidesArray
PEAR_Common::infoFromAny
PEAR_Common


Returns package information from different sources

PEAR_Common::downloadHttp
PEAR_Common::infoFromDescriptionFile
PEAR_Common
PHP Manual

PEAR_Common::infoFromAny()

(No version information available, might be only in CVS)

— Returns package information from different sources

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Common::infoFromAny()/funcdef paramdefstring $info /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::downloadHttp
PEAR_Common::infoFromDescriptionFile
PEAR_Common


Returns information about a package file

PEAR_Common::infoFromAny
PEAR_Common::infoFromString
PEAR_Common
PHP Manual

PEAR_Common::infoFromDescriptionFile()

(No version information available, might be only in CVS)

— Returns information about a package file

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Common::infoFromDescriptionFile()/funcdef paramdefstring $descfile /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::infoFromAny
PEAR_Common::infoFromString
PEAR_Common


Returns information about a package file

PEAR_Common::infoFromDescriptionFile
PEAR_Common::infoFromTgzFile
PEAR_Common
PHP Manual

PEAR_Common::infoFromString()

(No version information available, might be only in CVS)

— Returns information about a package file

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Common::infoFromString()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::infoFromDescriptionFile
PEAR_Common::infoFromTgzFile
PEAR_Common


Returns information about a package file

PEAR_Common::infoFromString
PEAR_Common::log
PEAR_Common
PHP Manual

PEAR_Common::infoFromTgzFile()

(No version information available, might be only in CVS)

— Returns information about a package file

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Common::infoFromTgzFile()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::infoFromString
PEAR_Common::log
PEAR_Common


Logging method

PEAR_Common::infoFromTgzFile
PEAR_Common::mkDirHier
PEAR_Common
PHP Manual

PEAR_Common::log()

(No version information available, might be only in CVS)

— Logging method

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Common::log()/funcdef paramdefint $level /paramdef paramdefstring $msg /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::infoFromTgzFile
PEAR_Common::mkDirHier
PEAR_Common


Create a directory and necessary parent directories

PEAR_Common::log
PEAR_Common::mkTempDir
PEAR_Common
PHP Manual

PEAR_Common::mkDirHier()

(No version information available, might be only in CVS)

— Create a directory and necessary parent directories

funcsynopsis funcsynopsisinfo require_once 'common.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Common::mkDirHier()/funcdef paramdefstring $dir /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::log
PEAR_Common::mkTempDir
PEAR_Common


Create and register a temporary directory.

PEAR_Common::mkDirHier
PEAR_Common::setFrontendObject
PEAR_Common
PHP Manual

PEAR_Common::mkTempDir()

(No version information available, might be only in CVS)

— Create and register a temporary directory.

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Common::mkTempDir()/funcdef paramdefstring $tmpdir = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::mkDirHier
PEAR_Common::setFrontendObject
PEAR_Common


Set object representing frontend to use.

PEAR_Common::mkTempDir
PEAR_Common::validatePackageInfo
PEAR_Common
PHP Manual

PEAR_Common::setFrontendObject()

(No version information available, might be only in CVS)

— Set object representing frontend to use.

funcsynopsis funcsynopsisinfo require_once 'common.php'; /funcsynopsisinfo funcprototype funcdef void PEAR_Common::setFrontendObject()/funcdef paramdefobject &$ui /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::mkTempDir
PEAR_Common::validatePackageInfo
PEAR_Common


Validate XML package definition file

PEAR_Common::setFrontendObject
PEAR_Common::validPackageName
PEAR_Common
PHP Manual

PEAR_Common::validatePackageInfo()

(No version information available, might be only in CVS)

— Validate XML package definition file

funcsynopsis funcsynopsisinfo require_once 'common.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Common::validatePackageInfo()/funcdef paramdefstring $info /paramdef paramdefarray &$errors /paramdef paramdefarray &$warnings /paramdef paramdefstring $dir_prefix = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::setFrontendObject
PEAR_Common::validPackageName
PEAR_Common


Test whether a string is a valid package name

PEAR_Common::validatePackageInfo
PEAR_Common::xmlFromInfo
PEAR_Common
PHP Manual

PEAR_Common::validPackageName()

(No version information available, might be only in CVS)

— Test whether a string is a valid package name

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Common::validPackageName()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common::validatePackageInfo
PEAR_Common::xmlFromInfo
PEAR_Common


Return an XML document based on the package info

PEAR_Common
PEAR_Config
PEAR_Common
PHP Manual

PEAR_Common::xmlFromInfo()

(No version information available, might be only in CVS)

— Return an XML document based on the package info

funcsynopsis funcsynopsisinfo require_once 'PEAR/common.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Common::xmlFromInfo()/funcdef paramdefarray $pkginfo /paramdef /funcprototype /funcsynopsis

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.

PEAR_Common
PEAR_Config
PEAR_Common


PEAR_Config

Class Trees for PEAR_Config()

  • PEAR

    • PEAR_Config

PEAR_Common::xmlFromInfo
PEAR_Config::PEAR_Config
PEAR Installer classes


Constructor

PEAR_Config
PEAR_Config::apiVersion
PEAR_Config
PHP Manual

PEAR_Config::PEAR_Config()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Config::PEAR_Config()/funcdef paramdefstring $user_file = '' /paramdef paramdefstring $system_file = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config
PEAR_Config::apiVersion
PEAR_Config


return API version (1.1 as of PEAR 1.4.0)

PEAR_Config::PEAR_Config
PEAR_Config::definedBy
PEAR_Config
PHP Manual

PEAR_Config::apiVersion()

(No version information available, might be only in CVS)

— return API version (1.1 as of PEAR 1.4.0)

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefvoid PEAR_Config::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::PEAR_Config
PEAR_Config::definedBy
PEAR_Config


Tells what config layer that gets to define a key

PEAR_Config::apiVersion
PEAR_Config::deleteChannel
PEAR_Config
PHP Manual

PEAR_Config::definedBy()

(No version information available, might be only in CVS)

— Tells what config layer that gets to define a key

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Config::definedBy()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::apiVersion
PEAR_Config::deleteChannel
PEAR_Config


deleteChannel

PEAR_Config::definedBy
PEAR_Config::get
PEAR_Config
PHP Manual

PEAR_Config::deleteChannel()

(No version information available, might be only in CVS)

— deleteChannel

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefvoid PEAR_Config::deleteChannel()/funcdef paramdefstring $channel /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::definedBy
PEAR_Config::get
PEAR_Config


Returns a configuration value

PEAR_Config::deleteChannel
PEAR_Config::getConfFile
PEAR_Config
PHP Manual

PEAR_Config::get()

(No version information available, might be only in CVS)

— Returns a configuration value

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Config::get()/funcdef paramdefstring $key /paramdef paramdefmixed $layer = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::deleteChannel
PEAR_Config::getConfFile
PEAR_Config


Gets the file used for storing the config for a layer

PEAR_Config::get
PEAR_Config::getDefaultChannel
PEAR_Config
PHP Manual

PEAR_Config::getConfFile()

(No version information available, might be only in CVS)

— Gets the file used for storing the config for a layer

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefvoid PEAR_Config::getConfFile()/funcdef paramdefstring $layer /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::get
PEAR_Config::getDefaultChannel
PEAR_Config


Retrieve the default channel.

PEAR_Config::getConfFile
PEAR_Config::getDocs
PEAR_Config
PHP Manual

PEAR_Config::getDefaultChannel()

(No version information available, might be only in CVS)

— Retrieve the default channel.

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdef string|false PEAR_Config::getDefaultChannel()/funcdef paramdefstring $layer = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getConfFile
PEAR_Config::getDocs
PEAR_Config


Get the documentation for a config value

PEAR_Config::getDefaultChannel
PEAR_Config::getFTP
PEAR_Config
PHP Manual

PEAR_Config::getDocs()

(No version information available, might be only in CVS)

— Get the documentation for a config value

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Config::getDocs()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getDefaultChannel
PEAR_Config::getFTP
PEAR_Config


The ftp server is set in readFTPConfigFile. It exists only if a remote configuration file has been specified

PEAR_Config::getDocs
PEAR_Config::getGroup
PEAR_Config
PHP Manual

PEAR_Config::getFTP()

(No version information available, might be only in CVS)

— The ftp server is set in readFTPConfigFile(). It exists only if a remote configuration file has been specified

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdef PEAR_FTP|false& PEAR_Config::getFTP()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getDocs
PEAR_Config::getGroup
PEAR_Config


Get the parameter group for a config key

PEAR_Config::getFTP
PEAR_Config::getGroupKeys
PEAR_Config
PHP Manual

PEAR_Config::getGroup()

(No version information available, might be only in CVS)

— Get the parameter group for a config key

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Config::getGroup()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getFTP
PEAR_Config::getGroupKeys
PEAR_Config


Get the list of the parameters in a group

PEAR_Config::getGroup
PEAR_Config::getGroups
PEAR_Config
PHP Manual

PEAR_Config::getGroupKeys()

(No version information available, might be only in CVS)

— Get the list of the parameters in a group

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Config::getGroupKeys()/funcdef paramdefstring $group /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getGroup
PEAR_Config::getGroups
PEAR_Config


Get the list of parameter groups

PEAR_Config::getGroupKeys
PEAR_Config::getKeys
PEAR_Config
PHP Manual

PEAR_Config::getGroups()

(No version information available, might be only in CVS)

— Get the list of parameter groups

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Config::getGroups()/funcdef ( void /funcprototype /funcsynopsis

Description

Get the list of parameter groups.

Return value

array - list of parameter groups

Note

This function can not be called statically.

PEAR_Config::getGroupKeys
PEAR_Config::getKeys
PEAR_Config


Get all the current config keys

PEAR_Config::getGroups
PEAR_Config::getLayers
PEAR_Config
PHP Manual

PEAR_Config::getKeys()

(No version information available, might be only in CVS)

— Get all the current config keys

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Config::getKeys()/funcdef ( void /funcprototype /funcsynopsis

Description

Get all the current config keys

Return value

array - simple array of config keys

Note

This function can not be called statically.

PEAR_Config::getGroups
PEAR_Config::getLayers
PEAR_Config


Returns the layers defined

PEAR_Config::getKeys
PEAR_Config::getPrompt
PEAR_Config
PHP Manual

PEAR_Config::getLayers()

(No version information available, might be only in CVS)

— Returns the layers defined

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Config::getLayers()/funcdef ( void /funcprototype /funcsynopsis

Description

Returns the layers defined, except the 'default' one

Return value

array the defined layers

Note

This function can not be called statically.

PEAR_Config::getKeys
PEAR_Config::getPrompt
PEAR_Config


Get short documentation for a config value

PEAR_Config::getLayers
PEAR_Config::getRegistry
PEAR_Config
PHP Manual

PEAR_Config::getPrompt()

(No version information available, might be only in CVS)

— Get short documentation for a config value

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Config::getPrompt()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getLayers
PEAR_Config::getRegistry
PEAR_Config


getRegistry

PEAR_Config::getPrompt
PEAR_Config::getRemote
PEAR_Config
PHP Manual

PEAR_Config::getRegistry()

(No version information available, might be only in CVS)

— getRegistry

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefPEAR_Registry|false& PEAR_Config::getRegistry()/funcdef paramdefstring $use = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getPrompt
PEAR_Config::getRemote
PEAR_Config


getRemote

PEAR_Config::getRegistry
PEAR_Config::getREST
PEAR_Config
PHP Manual

PEAR_Config::getRemote()

(No version information available, might be only in CVS)

— getRemote

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefPEAR_Remote& PEAR_Config::getRemote()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getRegistry
PEAR_Config::getREST
PEAR_Config


getREST

PEAR_Config::getRemote
PEAR_Config::getSetValues
PEAR_Config
PHP Manual

PEAR_Config::getREST()

(No version information available, might be only in CVS)

— getREST

funcsynopsis funcsynopsisinfo require_once '/Config.php'; /funcsynopsisinfo funcprototype funcdefPEAR_REST& PEAR_Config::getREST()/funcdef paramdefstring $version /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getRemote
PEAR_Config::getSetValues
PEAR_Config


Get the list of allowed set values for a config value

PEAR_Config::getREST
PEAR_Config::getType
PEAR_Config
PHP Manual

PEAR_Config::getSetValues()

(No version information available, might be only in CVS)

— Get the list of allowed set values for a config value

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Config::getSetValues()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getREST
PEAR_Config::getType
PEAR_Config


Get the type of a config value

PEAR_Config::getSetValues
PEAR_Config::isDefined
PEAR_Config
PHP Manual

PEAR_Config::getType()

(No version information available, might be only in CVS)

— Get the type of a config value

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Config::getType()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getSetValues
PEAR_Config::isDefined
PEAR_Config


Tells whether a key exists as config value

PEAR_Config::getType
PEAR_Config::isDefinedLayer
PEAR_Config
PHP Manual

PEAR_Config::isDefined()

(No version information available, might be only in CVS)

— Tells whether a key exists as config value

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::isDefined()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::getType
PEAR_Config::isDefinedLayer
PEAR_Config


Tells whether a config layer exists

PEAR_Config::isDefined
PEAR_Config::mergeConfigFile
PEAR_Config
PHP Manual

PEAR_Config::isDefinedLayer()

(No version information available, might be only in CVS)

— Tells whether a config layer exists

funcsynopsis funcsynopsisinfo require_once 'config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::isDefinedLayer()/funcdef paramdefstring $layer /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::isDefined
PEAR_Config::mergeConfigFile
PEAR_Config


Merges data into a config layer from a file

PEAR_Config::isDefinedLayer
PEAR_Config::noRegistry
PEAR_Config
PHP Manual

PEAR_Config::mergeConfigFile()

(No version information available, might be only in CVS)

— Merges data into a config layer from a file

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::mergeConfigFile()/funcdef paramdefstring $file /paramdef paramdefbool $override = TRUE /paramdef paramdefstring $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::isDefinedLayer
PEAR_Config::noRegistry
PEAR_Config


noRegistry

PEAR_Config::mergeConfigFile
PEAR_Config::readConfigFile
PEAR_Config
PHP Manual

PEAR_Config::noRegistry()

(No version information available, might be only in CVS)

— noRegistry

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefvoid PEAR_Config::noRegistry()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::mergeConfigFile
PEAR_Config::readConfigFile
PEAR_Config


Reads configuration data from a file

PEAR_Config::noRegistry
PEAR_Config::readFTPConfigFile
PEAR_Config
PHP Manual

PEAR_Config::readConfigFile()

(No version information available, might be only in CVS)

— Reads configuration data from a file

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::readConfigFile()/funcdef paramdefstring $file = NULL /paramdef paramdefstring $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::noRegistry
PEAR_Config::readFTPConfigFile
PEAR_Config


readFTPConfigFile

PEAR_Config::readConfigFile
PEAR_Config::remove
PEAR_Config
PHP Manual

PEAR_Config::readFTPConfigFile()

(No version information available, might be only in CVS)

— readFTPConfigFile

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdef true|PEAR_Error PEAR_Config::readFTPConfigFile()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::readConfigFile
PEAR_Config::remove
PEAR_Config


Remove a config key from a config layer

PEAR_Config::readFTPConfigFile
PEAR_Config::removeLayer
PEAR_Config
PHP Manual

PEAR_Config::remove()

(No version information available, might be only in CVS)

— Remove a config key from a config layer

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::remove()/funcdef paramdefstring $key /paramdef paramdefstring $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::readFTPConfigFile
PEAR_Config::removeLayer
PEAR_Config


Temporarily remove an entire config layer

PEAR_Config::remove
PEAR_Config::set
PEAR_Config
PHP Manual

PEAR_Config::removeLayer()

(No version information available, might be only in CVS)

— Temporarily remove an entire config layer

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::removeLayer()/funcdef paramdefstring $layer /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::remove
PEAR_Config::set
PEAR_Config


Set config value in specific layer

PEAR_Config::removeLayer
PEAR_Config::setChannels
PEAR_Config
PHP Manual

PEAR_Config::set()

(No version information available, might be only in CVS)

— Set config value in specific layer

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::set()/funcdef paramdefstring $key /paramdef paramdefstring $value /paramdef paramdefstring $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::removeLayer
PEAR_Config::setChannels
PEAR_Config


Set the list of channels.

PEAR_Config::set
PEAR_Config::setInstallRoot
PEAR_Config
PHP Manual

PEAR_Config::setChannels()

(No version information available, might be only in CVS)

— Set the list of channels.

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::setChannels()/funcdef paramdefarray $channels /paramdef paramdefbool $merge = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::set
PEAR_Config::setInstallRoot
PEAR_Config


setInstallRoot

PEAR_Config::setChannels
PEAR_Config::setRegistry
PEAR_Config
PHP Manual

PEAR_Config::setInstallRoot()

(No version information available, might be only in CVS)

— setInstallRoot

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefvoid PEAR_Config::setInstallRoot()/funcdef paramdefstring|false $root /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::setChannels
PEAR_Config::setRegistry
PEAR_Config


This is to allow customization like the use of installroot

PEAR_Config::setInstallRoot
PEAR_Config::singleton
PEAR_Config
PHP Manual

PEAR_Config::setRegistry()

(No version information available, might be only in CVS)

— This is to allow customization like the use of installroot

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::setRegistry()/funcdef paramdefPEAR_Registry|false &$reg /paramdef paramdefstring $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::setInstallRoot
PEAR_Config::singleton
PEAR_Config


Return a reference of a PEAR_Config object

PEAR_Config::setRegistry
PEAR_Config::store
PEAR_Config
PHP Manual

PEAR_Config::singleton()

(No version information available, might be only in CVS)

— Return a reference of a PEAR_Config object

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefobject &PEAR_Config::singleton()/funcdef paramdefstring $user_file = '' /paramdef paramdefstring $system_file = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::setRegistry
PEAR_Config::store
PEAR_Config


Stores configuration data in a layer

PEAR_Config::singleton
PEAR_Config::toDefault
PEAR_Config
PHP Manual

PEAR_Config::store()

(No version information available, might be only in CVS)

— Stores configuration data in a layer

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::store()/funcdef paramdefstring $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::singleton
PEAR_Config::toDefault
PEAR_Config


Revert value of config key to the system-defined one

PEAR_Config::store
PEAR_Config::validConfiguration
PEAR_Config
PHP Manual

PEAR_Config::toDefault()

(No version information available, might be only in CVS)

— Revert value of config key to the system-defined one

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::toDefault()/funcdef paramdefstring $key /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::store
PEAR_Config::validConfiguration
PEAR_Config


Determine whether any configuration files have been detected, and whether a registry object can be retrieved from this configuration.

PEAR_Config::toDefault
PEAR_Config::writeConfigFile
PEAR_Config
PHP Manual

PEAR_Config::validConfiguration()

(No version information available, might be only in CVS)

— Determine whether any configuration files have been detected, and whether a registry object can be retrieved from this configuration.

funcsynopsis funcsynopsisinfo require_once '/Config.php'; (since PEAR 1.4.0) /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::validConfiguration()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Config::toDefault
PEAR_Config::writeConfigFile
PEAR_Config


Write data into config layer from file

PEAR_Config
PEAR_Dependency
PEAR_Config
PHP Manual

PEAR_Config::writeConfigFile()

(No version information available, might be only in CVS)

— Write data into config layer from file

funcsynopsis funcsynopsisinfo require_once 'PEAR/config.php'; /funcsynopsisinfo funcprototype funcdefbool PEAR_Config::writeConfigFile()/funcdef paramdefstring $file = NULL /paramdef paramdefbool $layer = 'user' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Config
PEAR_Dependency
PEAR_Config


PEAR_Dependency

This class is deprecated by PEAR_Dependency2 in PEAR 1.4.0

PEAR_Config::writeConfigFile
PEAR_Dependency::PEAR_Dependency
PEAR Installer classes


constructor

PEAR_Dependency
PEAR_Dependency::callCheckMethod
PEAR_Dependency
PHP Manual

PEAR_Dependency::PEAR_Dependency()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Dependency::PEAR_Dependency()/funcdef paramdefobject &$registry /paramdef /funcprototype /funcsynopsis

Description

Constructor

Parameter

object &$registry

a PEAR_Registry instance

Note

This function can not be called statically.

PEAR_Dependency
PEAR_Dependency::callCheckMethod
PEAR_Dependency


Maps the xml dependency definition

PEAR_Dependency::PEAR_Dependency
PEAR_Dependency::checkExtension
PEAR_Dependency
PHP Manual

PEAR_Dependency::callCheckMethod()

(No version information available, might be only in CVS)

— Maps the xml dependency definition

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Dependency::callCheckMethod()/funcdef paramdefmixed &$errmsg /paramdef paramdefarray $opts /paramdef /funcprototype /funcsynopsis

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:

$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.

PEAR_Dependency::PEAR_Dependency
PEAR_Dependency::checkExtension
PEAR_Dependency


Check Extension dependency

PEAR_Dependency::callCheckMethod
PEAR_Dependency::checkOS
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkExtension()

(No version information available, might be only in CVS)

— Check Extension dependency

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkExtension()/funcdef paramdefmixed &$errmsg /paramdef paramdefstring $name /paramdef paramdefstring $req = NULL /paramdef paramdefstring $relation = 'has' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency::callCheckMethod
PEAR_Dependency::checkOS
PEAR_Dependency


Check Operating system dependency

PEAR_Dependency::checkExtension
PEAR_Dependency::checkPackage
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkOS()

(No version information available, might be only in CVS)

— Check Operating system dependency

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkOS()/funcdef paramdefstring &$errmsg /paramdef paramdefstring $os /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency::checkExtension
PEAR_Dependency::checkPackage
PEAR_Dependency


check Package dependency

PEAR_Dependency::checkOS
PEAR_Dependency::checkPHP
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkPackage()

(No version information available, might be only in CVS)

— check Package dependency

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkPackage()/funcdef paramdefmixed &$errmsg /paramdef paramdefstring $name /paramdef paramdefstring $req = NULL /paramdef paramdefstring $relation = 'has' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency::checkOS
PEAR_Dependency::checkPHP
PEAR_Dependency


Check PHP version

PEAR_Dependency::checkPackage
PEAR_Dependency::checkProgram
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkPHP()

(No version information available, might be only in CVS)

— Check PHP version

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkPHP()/funcdef paramdefmixed &$errmsg /paramdef paramdefstring $req /paramdef paramdefstring $relation = 'ge' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency::checkPackage
PEAR_Dependency::checkProgram
PEAR_Dependency


Check external program

PEAR_Dependency::checkPHP
PEAR_Dependency::checkSAPI
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkProgram()

(No version information available, might be only in CVS)

— Check external program

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkProgram()/funcdef paramdefmixed &$errmsg /paramdef paramdefstring $program /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency::checkPHP
PEAR_Dependency::checkSAPI
PEAR_Dependency


Check SAPI backend

PEAR_Dependency::checkProgram
PEAR_Dependency::checkZend
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkSAPI()

(No version information available, might be only in CVS)

— Check SAPI backend

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkSAPI()/funcdef paramdefmixed &$errmsg /paramdef paramdefstring $name /paramdef paramdefstring $req = NULL /paramdef paramdefstring $relation = 'has' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency::checkProgram
PEAR_Dependency::checkZend
PEAR_Dependency


Check Zend version

PEAR_Dependency
PEAR_Dependency2
PEAR_Dependency
PHP Manual

PEAR_Dependency::checkZend()

(No version information available, might be only in CVS)

— Check Zend version

funcsynopsis funcsynopsisinfo require_once 'PEAR/Dependency.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Dependency::checkZend()/funcdef paramdefmixed &$errmsg /paramdef paramdefstring $req /paramdef paramdefstring ''}$relation = 'ge' /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency
PEAR_Dependency2
PEAR_Dependency


PEAR_Dependency2

PEAR_Dependency::checkZend
Class Summary PEAR_Dependency2
PEAR Installer classes


PEAR_Dependency2
constructor PEAR_Dependency2::PEAR_Dependency2
PEAR_Dependency2
PHP Manual

Class Summary PEAR_Dependency2

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_Dependency2
constructor PEAR_Dependency2::PEAR_Dependency2
PEAR_Dependency2


PEAR_Dependency2

Class Summary PEAR_Dependency2
PEAR_Dependency2::normalizeDep
PEAR_Dependency2
PHP Manual

constructor PEAR_Dependency2::PEAR_Dependency2()

(No version information available, might be only in CVS)

constructor — PEAR_Dependency2

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef void constructor PEAR_Dependency2::PEAR_Dependency2() /funcdef paramdef PEAR_Config &$config /paramdef paramdef array $installoptions /paramdef paramdef array $package /paramdef paramdef int $state = PEAR_VALIDATE_INSTALLING /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_Dependency2
PEAR_Dependency2::normalizeDep
PEAR_Dependency2


Convert a 1.0 dep into a 2.0 dep

constructor PEAR_Dependency2::PEAR_Dependency2
PEAR_Dependency2::validateArchDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::normalizeDep()

(No version information available, might be only in CVS)

— Convert a 1.0 dep into a 2.0 dep

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef array PEAR_Dependency2::normalizeDep() /funcdef paramdef array $dep /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_Dependency2::PEAR_Dependency2
PEAR_Dependency2::validateArchDependency
PEAR_Dependency2


Specify a complex dependency on an OS/processor/kernel version, Use OS for simple operating system dependency.

PEAR_Dependency2::normalizeDep
PEAR_Dependency2::validateDependency1
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validateArchDependency()

(No version information available, might be only in CVS)

— Specify a complex dependency on an OS/processor/kernel version, Use OS for simple operating system dependency.

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validateArchDependency() /funcdef paramdef array $dep /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::normalizeDep
PEAR_Dependency2::validateDependency1
PEAR_Dependency2


validate a package.xml 1.0 dependency

PEAR_Dependency2::validateArchDependency
PEAR_Dependency2::validateExtensionDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validateDependency1()

(No version information available, might be only in CVS)

— validate a package.xml 1.0 dependency

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validateDependency1() /funcdef paramdef array $dep /paramdef paramdef array $params = array() /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validateArchDependency
PEAR_Dependency2::validateExtensionDependency
PEAR_Dependency2


validate a dependency on a PHP extension

PEAR_Dependency2::validateDependency1
PEAR_Dependency2::validateOsDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validateExtensionDependency()

(No version information available, might be only in CVS)

— validate a dependency on a PHP extension

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validateExtensionDependency() /funcdef paramdef array $dep /paramdef paramdef bool $required = true /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validateDependency1
PEAR_Dependency2::validateOsDependency
PEAR_Dependency2


Specify a dependency on an OS. Use arch for detailed os/processor information

PEAR_Dependency2::validateExtensionDependency
PEAR_Dependency2::validatePackage
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validateOsDependency()

(No version information available, might be only in CVS)

— Specify a dependency on an OS. Use arch for detailed os/processor information

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validateOsDependency() /funcdef paramdef array $dep /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validateExtensionDependency
PEAR_Dependency2::validatePackage
PEAR_Dependency2


validatePackage

PEAR_Dependency2::validateOsDependency
PEAR_Dependency2::validatePackageDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validatePackage()

(No version information available, might be only in CVS)

— validatePackage

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validatePackage() /funcdef paramdef array|PEAR_PackageFile_v2|PEAR_Downloader_Package $pkg /paramdef paramdef PEAR_Common &$dl /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validateOsDependency
PEAR_Dependency2::validatePackageDependency
PEAR_Dependency2


validatePackageDependency

PEAR_Dependency2::validatePackage
PEAR_Dependency2::validatePackageUninstall
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validatePackageDependency()

(No version information available, might be only in CVS)

— validatePackageDependency

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef array|true|PEAR_Error PEAR_Dependency2::validatePackageDependency() /funcdef paramdef array $dep /paramdef paramdef boolean $required /paramdef paramdef array $params /paramdef paramdef bool $depv1 = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validatePackage
PEAR_Dependency2::validatePackageUninstall
PEAR_Dependency2


validatePackageUninstall

PEAR_Dependency2::validatePackageDependency
PEAR_Dependency2::validatePearinstallerDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validatePackageUninstall()

(No version information available, might be only in CVS)

— validatePackageUninstall

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validatePackageUninstall() /funcdef paramdef PEAR_Installer &$dl /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validatePackageDependency
PEAR_Dependency2::validatePearinstallerDependency
PEAR_Dependency2


validatePearinstallerDependency

PEAR_Dependency2::validatePackageUninstall
PEAR_Dependency2::validatePhpDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validatePearinstallerDependency()

(No version information available, might be only in CVS)

— validatePearinstallerDependency

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validatePearinstallerDependency() /funcdef paramdef array $dep /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validatePackageUninstall
PEAR_Dependency2::validatePhpDependency
PEAR_Dependency2


validatePhpDependency

PEAR_Dependency2::validatePearinstallerDependency
PEAR_Dependency2::validateSubpackageDependency
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validatePhpDependency()

(No version information available, might be only in CVS)

— validatePhpDependency

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error|array PEAR_Dependency2::validatePhpDependency() /funcdef paramdef array $dep /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2::validatePearinstallerDependency
PEAR_Dependency2::validateSubpackageDependency
PEAR_Dependency2


validateSubpackageDependency

PEAR_Dependency2
PEAR_DependencyDB
PEAR_Dependency2
PHP Manual

PEAR_Dependency2::validateSubpackageDependency()

(No version information available, might be only in CVS)

— validateSubpackageDependency

funcsynopsis funcsynopsisinforequire_once '/Dependency2.php';/funcsynopsisinfo funcprototype funcdef array|true|PEAR_Error PEAR_Dependency2::validateSubpackageDependency() /funcdef paramdef array $dep /paramdef paramdef bool $required /paramdef paramdef array $params /paramdef /funcprototype /funcsynopsis

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.

PEAR_Dependency2
PEAR_DependencyDB
PEAR_Dependency2


PEAR_DependencyDB

PEAR_Dependency2::validateSubpackageDependency
Class Summary PEAR_DependencyDB
PEAR Installer classes


PEAR_DependencyDB
PEAR_DependencyDB::assertDepsDB
PEAR_DependencyDB
PHP Manual

Class Summary PEAR_DependencyDB

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_DependencyDB
PEAR_DependencyDB::assertDepsDB
PEAR_DependencyDB


Create the dependency database, if it doesn't exist. Error if the database is newer than the code reading it.

Class Summary PEAR_DependencyDB
PEAR_DependencyDB::dependsOn
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::assertDepsDB()

(No version information available, might be only in CVS)

— Create the dependency database, if it doesn't exist. Error if the database is newer than the code reading it.

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef void|PEAR_Error PEAR_DependencyDB::assertDepsDB() /funcdef paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_DependencyDB
PEAR_DependencyDB::dependsOn
PEAR_DependencyDB


Determine whether $parent depends on $child, near or deep

PEAR_DependencyDB::assertDepsDB
PEAR_DependencyDB::getDependencies
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::dependsOn()

(No version information available, might be only in CVS)

— Determine whether $parent depends on $child, near or deep

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef void PEAR_DependencyDB::dependsOn() /funcdef paramdef array|PEAR_PackageFile_v2|PEAR_PackageFile_v2 $parent /paramdef paramdef array|PEAR_PackageFile_v2|PEAR_PackageFile_v2 $child /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::assertDepsDB
PEAR_DependencyDB::getDependencies
PEAR_DependencyDB


Get a list of dependencies of this installed package

PEAR_DependencyDB::dependsOn
PEAR_DependencyDB::getDependentPackageDependencies
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::getDependencies()

(No version information available, might be only in CVS)

— Get a list of dependencies of this installed package

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef array|false PEAR_DependencyDB::getDependencies() /funcdef paramdef PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::dependsOn
PEAR_DependencyDB::getDependentPackageDependencies
PEAR_DependencyDB


Get a list of the actual dependencies of installed packages that depend on a package.

PEAR_DependencyDB::getDependencies
PEAR_DependencyDB::getDependentPackages
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::getDependentPackageDependencies()

(No version information available, might be only in CVS)

— Get a list of the actual dependencies of installed packages that depend on a package.

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef array|false PEAR_DependencyDB::getDependentPackageDependencies() /funcdef paramdef PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::getDependencies
PEAR_DependencyDB::getDependentPackages
PEAR_DependencyDB


Get a list of installed packages that depend on this package

PEAR_DependencyDB::getDependentPackageDependencies
PEAR_DependencyDB::hasWriteAccess
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::getDependentPackages()

(No version information available, might be only in CVS)

— Get a list of installed packages that depend on this package

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef array|false PEAR_DependencyDB::getDependentPackages() /funcdef paramdef PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::getDependentPackageDependencies
PEAR_DependencyDB::hasWriteAccess
PEAR_DependencyDB


determines whether a dependency DB can be modified

PEAR_DependencyDB::getDependentPackages
PEAR_DependencyDB::installPackage
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::hasWriteAccess()

(No version information available, might be only in CVS)

— determines whether a dependency DB can be modified

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_DependencyDB::hasWriteAccess() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::getDependentPackages
PEAR_DependencyDB::installPackage
PEAR_DependencyDB


Register dependencies of a package that is being installed or upgraded

PEAR_DependencyDB::hasWriteAccess
PEAR_DependencyDB::rebuildDB
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::installPackage()

(No version information available, might be only in CVS)

— Register dependencies of a package that is being installed or upgraded

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef void PEAR_DependencyDB::installPackage() /funcdef paramdef PEAR_PackageFile_v2|PEAR_PackageFile_v2 &$package /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::hasWriteAccess
PEAR_DependencyDB::rebuildDB
PEAR_DependencyDB


Rebuild the dependency DB by reading registry entries.

PEAR_DependencyDB::installPackage
PEAR_DependencyDB::setConfig
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::rebuildDB()

(No version information available, might be only in CVS)

— Rebuild the dependency DB by reading registry entries.

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error PEAR_DependencyDB::rebuildDB() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::installPackage
PEAR_DependencyDB::setConfig
PEAR_DependencyDB


Set up the registry/location of dependency DB

PEAR_DependencyDB::rebuildDB
PEAR_DependencyDB::singleton
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::setConfig()

(No version information available, might be only in CVS)

— Set up the registry/location of dependency DB

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef void PEAR_DependencyDB::setConfig() /funcdef paramdef PEAR_Config|false &$config /paramdef paramdef string|false $depdb = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::rebuildDB
PEAR_DependencyDB::singleton
PEAR_DependencyDB


Get a raw dependency database. Calls setConfig() and assertDepsDB()

PEAR_DependencyDB::setConfig
PEAR_DependencyDB::uninstallPackage
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::singleton()

(No version information available, might be only in CVS)

— Get a raw dependency database. Calls setConfig() and assertDepsDB()

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef PEAR_DependencyDB |PEAR_Error & PEAR_DependencyDB::singleton() /funcdef paramdef PEAR_Config &$config /paramdef paramdef string|false $depdb = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB::setConfig
PEAR_DependencyDB::uninstallPackage
PEAR_DependencyDB


Remove dependencies of a package that is being uninstalled, or upgraded.

PEAR_DependencyDB
PEAR_Frontend
PEAR_DependencyDB
PHP Manual

PEAR_DependencyDB::uninstallPackage()

(No version information available, might be only in CVS)

— Remove dependencies of a package that is being uninstalled, or upgraded.

funcsynopsis funcsynopsisinforequire_once '/DependencyDB.php';/funcsynopsisinfo funcprototype funcdef void PEAR_DependencyDB::uninstallPackage() /funcdef paramdef PEAR_PackageFile_v1|PEAR_PackageFile_v2|array &$pkg /paramdef /funcprototype /funcsynopsis

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.

PEAR_DependencyDB
PEAR_Frontend
PEAR_DependencyDB


PEAR_Frontend

PEAR_DependencyDB::uninstallPackage
Class Summary PEAR_Frontend
PEAR Installer classes


Singleton-based frontend for PEAR user input/output

PEAR_Frontend
PEAR_Frontend::addTempFile
PEAR_Frontend
PHP Manual

Class Summary PEAR_Frontend

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_Frontend
PEAR_Frontend::addTempFile
PEAR_Frontend


This can be overridden to allow session-based temporary file management

Class Summary PEAR_Frontend
PEAR_Frontend::isIncludeable
PEAR_Frontend
PHP Manual

PEAR_Frontend::addTempFile()

(No version information available, might be only in CVS)

— This can be overridden to allow session-based temporary file management

funcsynopsis funcsynopsisinforequire_once '/Frontend.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Frontend::addTempFile() /funcdef paramdef mixed $file /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_Frontend
PEAR_Frontend::isIncludeable
PEAR_Frontend


isIncludeable

PEAR_Frontend::addTempFile
PEAR_Frontend::log
PEAR_Frontend
PHP Manual

PEAR_Frontend::isIncludeable()

(No version information available, might be only in CVS)

— isIncludeable

funcsynopsis funcsynopsisinforequire_once '/Frontend.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_Frontend::isIncludeable() /funcdef paramdef string $path /paramdef /funcprototype /funcsynopsis

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.

PEAR_Frontend::addTempFile
PEAR_Frontend::log
PEAR_Frontend


log

PEAR_Frontend::isIncludeable
PEAR_Frontend::setConfig
PEAR_Frontend
PHP Manual

PEAR_Frontend::log()

(No version information available, might be only in CVS)

— log

funcsynopsis funcsynopsisinforequire_once '/Frontend.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Frontend::log() /funcdef paramdef int $level /paramdef paramdef string $msg /paramdef paramdef bool $append_crlf = TRUE /paramdef /funcprototype /funcsynopsis

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.

PEAR_Frontend::isIncludeable
PEAR_Frontend::setConfig
PEAR_Frontend


setConfig

PEAR_Frontend::log
PEAR_Frontend::setFrontendClass
PEAR_Frontend
PHP Manual

PEAR_Frontend::setConfig()

(No version information available, might be only in CVS)

— setConfig

funcsynopsis funcsynopsisinforequire_once '/Frontend.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Frontend::setConfig() /funcdef paramdef PEAR_Config &$config /paramdef /funcprototype /funcsynopsis

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.

PEAR_Frontend::log
PEAR_Frontend::setFrontendClass
PEAR_Frontend


setFrontendClass

PEAR_Frontend::setConfig
PEAR_Frontend::singleton
PEAR_Frontend
PHP Manual

PEAR_Frontend::setFrontendClass()

(No version information available, might be only in CVS)

— setFrontendClass

funcsynopsis funcsynopsisinforequire_once '/Frontend.php';/funcsynopsisinfo funcprototype funcdef void& PEAR_Frontend::setFrontendClass() /funcdef paramdef string $uiclass /paramdef /funcprototype /funcsynopsis

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.

PEAR_Frontend::setConfig
PEAR_Frontend::singleton
PEAR_Frontend


Retrieve the frontend object

PEAR_Frontend
PEAR_Installer
PEAR_Frontend
PHP Manual

PEAR_Frontend::singleton()

(No version information available, might be only in CVS)

— Retrieve the frontend object

funcsynopsis funcsynopsisinforequire_once '/Frontend.php';/funcsynopsisinfo funcprototype funcdef PEAR_Frontend_CLI|PEAR_Frontend_Web|PEAR_Frontend_Gtk& PEAR_Frontend::singleton() /funcdef paramdef mixed $type = null /paramdef /funcprototype /funcsynopsis

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.

PEAR_Frontend
PEAR_Installer
PEAR_Frontend


PEAR_Installer

Administration class used to install PEAR packages and maintain the installed package database.

Class Trees for PEAR_Installer()

  • PEAR_Common

    • PEAR_Installer

PEAR_Frontend::singleton
PEAR_Installer::PEAR_Installer
PEAR Installer classes


constructor

PEAR_Installer
PEAR_Installer::install
PEAR_Installer
PHP Manual

PEAR_Installer::PEAR_Installer()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/Installer.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor PEAR_Installer::constructor PEAR_Installer()/funcdef paramdefobject &$ui /paramdef /funcprototype /funcsynopsis

Description

PEAR_Installer constructor.

Parameter

object &$ui

user interface object (instance of PEAR_Frontend_*)

Note

This function can not be called statically.

PEAR_Installer
PEAR_Installer::install
PEAR_Installer


Installs package files

PEAR_Installer
PEAR
PEAR_Installer
PHP Manual

PEAR_Installer::install()

(No version information available, might be only in CVS)

— Installs package files

funcsynopsis funcsynopsisinfo require_once 'PEAR/Installer.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Installer::install()/funcdef paramdefstring $pkgfile /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

PEAR_Installer
PEAR
PEAR_Installer


PEAR

PEAR_Installer::install
Class Summary PEAR_PackageFile
PEAR Installer classes


PEAR
constructor PEAR_PackageFile::PEAR_PackageFile
PEAR
PHP Manual

Class Summary PEAR_PackageFile

(No version information available, might be only in CVS)

Class Summary — 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

PEAR
constructor PEAR_PackageFile::PEAR_PackageFile
PEAR


PEAR_PackageFile

Class Summary PEAR_PackageFile
PEAR_PackageFile::factory
PEAR
PHP Manual

constructor PEAR_PackageFile::PEAR_PackageFile()

(No version information available, might be only in CVS)

constructor — PEAR_PackageFile

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef void constructor PEAR_PackageFile::PEAR_PackageFile() /funcdef paramdef PEAR_Config &$config /paramdef paramdef bool $debug = FALSE /paramdef paramdef string $tmpdir = FALSE /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_PackageFile
PEAR_PackageFile::factory
PEAR


factory

constructor PEAR_PackageFile::PEAR_PackageFile
PEAR_PackageFile::fromAnyFile
PEAR
PHP Manual

PEAR_PackageFile::factory()

(No version information available, might be only in CVS)

— factory

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_PackageFile_v1|PEAR_PackageFile_v2& PEAR_PackageFile::factory() /funcdef paramdef string $version /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_PackageFile::PEAR_PackageFile
PEAR_PackageFile::fromAnyFile
PEAR


Returns package information from different sources

PEAR_PackageFile::factory
PEAR_PackageFile::fromArray
PEAR
PHP Manual

PEAR_PackageFile::fromAnyFile()

(No version information available, might be only in CVS)

— Returns package information from different sources

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef string& PEAR_PackageFile::fromAnyFile() /funcdef paramdef string $info /paramdef paramdef int $state /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFile::factory
PEAR_PackageFile::fromArray
PEAR


Return a packagefile object from its toArray() method

PEAR_PackageFile::fromAnyFile
PEAR_PackageFile::fromPackageFile
PEAR
PHP Manual

PEAR_PackageFile::fromArray()

(No version information available, might be only in CVS)

— Return a packagefile object from its toArray() method

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_PackageFile_v1|PEAR_PackageFile_v2& PEAR_PackageFile::fromArray() /funcdef paramdef array $arr /paramdef /funcprototype /funcsynopsis

Description

Warning

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.

PEAR_PackageFile::fromAnyFile
PEAR_PackageFile::fromPackageFile
PEAR


Returns information about a package file. Expects the name of a package.xml file as input.

PEAR_PackageFile::fromArray
PEAR_PackageFile::fromTgzFile
PEAR
PHP Manual

PEAR_PackageFile::fromPackageFile()

(No version information available, might be only in CVS)

— Returns information about a package file. Expects the name of a package.xml file as input.

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef array& PEAR_PackageFile::fromPackageFile() /funcdef paramdef string $descfile /paramdef paramdef int $state /paramdef paramdef string|false $archive = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFile::fromArray
PEAR_PackageFile::fromTgzFile
PEAR


fromTgzFile

PEAR_PackageFile::fromPackageFile
PEAR_PackageFile::fromXmlString
PEAR
PHP Manual

PEAR_PackageFile::fromTgzFile()

(No version information available, might be only in CVS)

— fromTgzFile

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_PackageFile_v1|PEAR_PackageFile_v2|PEAR_Error& PEAR_PackageFile::fromTgzFile() /funcdef paramdef string $file /paramdef paramdef int $state /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFile::fromPackageFile
PEAR_PackageFile::fromXmlString
PEAR


fromXmlString

PEAR_PackageFile::fromTgzFile
PEAR_PackageFile::parserFactory
PEAR
PHP Manual

PEAR_PackageFile::fromXmlString()

(No version information available, might be only in CVS)

— fromXmlString

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_PackageFile_v1|PEAR_PackageFile_v2|PEAR_Error& PEAR_PackageFile::fromXmlString() /funcdef paramdef string $data /paramdef paramdef int $state /paramdef paramdef string $file /paramdef paramdef string|false $archive = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFile::fromTgzFile
PEAR_PackageFile::parserFactory
PEAR


parserFactory

PEAR_PackageFile::fromXmlString
PEAR_PackageFile::rawReturn
PEAR
PHP Manual

PEAR_PackageFile::parserFactory()

(No version information available, might be only in CVS)

— parserFactory

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef PEAR_PackageFile_Parser_v1|PEAR_PackageFile_Parser_v2& PEAR_PackageFile::parserFactory() /funcdef paramdef string $version /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFile::fromXmlString
PEAR_PackageFile::rawReturn
PEAR


Turn off validation - return a parsed package.xml without checking it for errors

PEAR_PackageFile::parserFactory
PEAR_PackageFile::setLogger
PEAR
PHP Manual

PEAR_PackageFile::rawReturn()

(No version information available, might be only in CVS)

— Turn off validation - return a parsed package.xml without checking it for errors

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_PackageFile::rawReturn() /funcdef paramdef /funcprototype /funcsynopsis

Description

This is used by the package-validate command

Throws

throws no exceptions thrown

Note

This function can not be called statically.

PEAR_PackageFile::parserFactory
PEAR_PackageFile::setLogger
PEAR


setLogger

PEAR_PackageFile::rawReturn
Package PEAR Constants
PEAR
PHP Manual

PEAR_PackageFile::setLogger()

(No version information available, might be only in CVS)

— setLogger

funcsynopsis funcsynopsisinforequire_once '/PackageFile.php';/funcsynopsisinfo funcprototype funcdef void PEAR_PackageFile::setLogger() /funcdef paramdef PEAR_Common &$l /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFile::rawReturn
Package PEAR Constants
PEAR


Constants defined in and used by PEAR

PEAR
PEAR_Packager
PEAR
PHP Manual

Package PEAR Constants

(No version information available, might be only in CVS)

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

PEAR
PEAR_Packager
PEAR


PEAR_Packager

Administration class used to make a PEAR release tarball.

Class Trees for PEAR_Packager

  • PEAR_Common

    • PEAR_Packager

Package PEAR Constants
PEAR_Packager::PEAR_Packager
PEAR Installer classes


constructor

PEAR_Packager
PEAR_Packager::package
PEAR_Packager
PHP Manual

PEAR_Packager::PEAR_Packager()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/Packager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Packager:: PEAR_Packager()/funcdef ( void /funcprototype /funcsynopsis

Description

constructor

Note

This function can be called statically.

PEAR_Packager
PEAR_Packager::package
PEAR_Packager


Create Package archive

PEAR_Packager
PEAR_Registry
PEAR_Packager
PHP Manual

PEAR_Packager::package()

(No version information available, might be only in CVS)

— Create Package archive

funcsynopsis funcsynopsisinfo require_once 'PEAR/Packager.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Packager::package()/funcdef paramdefstring $pkgfile = NULL /paramdef paramdefboolean $compress = TRUE /paramdef /funcprototype /funcsynopsis

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.

PEAR_Packager
PEAR_Registry
PEAR_Packager


PEAR_Registry

Administration class used to maintain the installed package database.

Class Trees for PEAR_Registry

  • PEAR

    • PEAR_Registry

PEAR_Packager::package
PEAR_Registry::PEAR_Registry
PEAR Installer classes


constructor

PEAR_Registry
PEAR_Registry::addPackage
PEAR_Registry
PHP Manual

PEAR_Registry::PEAR_Registry()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Registry::PEAR_Registry()/funcdef paramdefstring $pear_install_dir = PEAR_INSTALL_DIR /paramdef /funcprototype /funcsynopsis

Description

constructor

Parameter

string $pear_install_dir

PEAR install directory (for .php files)

Note

This function can not be called statically.

PEAR_Registry
PEAR_Registry::addPackage
PEAR_Registry


Registers a package to the registry

PEAR_Registry::PEAR_Registry
PEAR_Registry::checkFileMap
PEAR_Registry
PHP Manual

PEAR_Registry::addPackage()

(No version information available, might be only in CVS)

— Registers a package to the registry

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Registry::addPackage()/funcdef paramdefstring $package /paramdef paramdefarray $info /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::PEAR_Registry
PEAR_Registry::checkFileMap
PEAR_Registry


Test whether a file belongs to a package

PEAR_Registry::addPackage
PEAR_Registry::deletePackage
PEAR_Registry
PHP Manual

PEAR_Registry::checkFileMap()

(No version information available, might be only in CVS)

— Test whether a file belongs to a package

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Registry::checkFileMap()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::addPackage
PEAR_Registry::deletePackage
PEAR_Registry


Remove Package from registry

PEAR_Registry::checkFileMap
PEAR_Registry::listPackages
PEAR_Registry
PHP Manual

PEAR_Registry::deletePackage()

(No version information available, might be only in CVS)

— Remove Package from registry

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Registry::deletePackage()/funcdef paramdefstring $package /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::checkFileMap
PEAR_Registry::listPackages
PEAR_Registry


List all registered Packages

PEAR_Registry::deletePackage
PEAR_Registry::packageExists
PEAR_Registry
PHP Manual

PEAR_Registry::listPackages()

(No version information available, might be only in CVS)

— List all registered Packages

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_Registry::listPackages()/funcdef ( void /funcprototype /funcsynopsis

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.

PEAR_Registry::deletePackage
PEAR_Registry::packageExists
PEAR_Registry


Check for Package

PEAR_Registry::listPackages
PEAR_Registry::packageInfo
PEAR_Registry
PHP Manual

PEAR_Registry::packageExists()

(No version information available, might be only in CVS)

— Check for Package

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Registry::packageExists()/funcdef paramdefstring $package /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::listPackages
PEAR_Registry::packageInfo
PEAR_Registry


Get Package information

PEAR_Registry::packageExists
PEAR_Registry::rebuildDepsFile
PEAR_Registry
PHP Manual

PEAR_Registry::packageInfo()

(No version information available, might be only in CVS)

— Get Package information

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Registry::packageInfo()/funcdef paramdefstring $package = NULL /paramdef paramdefstring $key = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::packageExists
PEAR_Registry::rebuildDepsFile
PEAR_Registry


Rebuild dependencies file

PEAR_Registry::packageInfo
PEAR_Registry::rebuildFileMap
PEAR_Registry
PHP Manual

PEAR_Registry::rebuildDepsFile()

(No version information available, might be only in CVS)

— Rebuild dependencies file

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Registry::rebuildDepsFile()/funcdef ( void /funcprototype /funcsynopsis

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.

PEAR_Registry::packageInfo
PEAR_Registry::rebuildFileMap
PEAR_Registry


Rebuild file map

PEAR_Registry::rebuildDepsFile
PEAR_Registry::removePackageDep
PEAR_Registry
PHP Manual

PEAR_Registry::rebuildFileMap()

(No version information available, might be only in CVS)

— Rebuild file map

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Registry::rebuildFileMap()/funcdef ( void /funcprototype /funcsynopsis

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.

PEAR_Registry::rebuildDepsFile
PEAR_Registry::removePackageDep
PEAR_Registry


Remove dependency information of a Package

PEAR_Registry::rebuildFileMap
PEAR_Registry::setPackageDep
PEAR_Registry
PHP Manual

PEAR_Registry::removePackageDep()

(No version information available, might be only in CVS)

— Remove dependency information of a Package

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Registry::removePackageDep()/funcdef paramdefstring $package /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::rebuildFileMap
PEAR_Registry::setPackageDep
PEAR_Registry


Update or insert dependencies of a Package

PEAR_Registry::removePackageDep
PEAR_Registry::updatePackage
PEAR_Registry
PHP Manual

PEAR_Registry::setPackageDep()

(No version information available, might be only in CVS)

— Update or insert dependencies of a Package

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Registry::setPackageDep()/funcdef paramdefstring $package /paramdef paramdefstring $new_version /paramdef paramdefarray $rel_deps = array() /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry::removePackageDep
PEAR_Registry::updatePackage
PEAR_Registry


Update Package information

PEAR_Registry
PEAR_Remote
PEAR_Registry
PHP Manual

PEAR_Registry::updatePackage()

(No version information available, might be only in CVS)

— Update Package information

funcsynopsis funcsynopsisinfo require_once 'PEAR/Registry.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Registry::updatePackage()/funcdef paramdefstring $package /paramdef paramdefarray $info /paramdef paramdefbool $merge = TRUE /paramdef /funcprototype /funcsynopsis

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.

PEAR_Registry
PEAR_Remote
PEAR_Registry


PEAR_Remote

This is a class for doing remote operations against a PEAR Package Server.

Class Trees for PEAR_Remote()

  • PEAR

    • PEAR_Remote

PEAR_Registry::updatePackage
PEAR_Remote::PEAR_Remote
PEAR Installer classes


constructor

PEAR_Remote
PEAR_Remote::call
PEAR_Remote
PHP Manual

PEAR_Remote::PEAR_Remote()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'PEAR/Remote.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Remote::PEAR_Remote()/funcdef paramdefobject &$config /paramdef /funcprototype /funcsynopsis

Description

constructor

Parameter

object &$config

an instance of PEAR_Config

Note

This function can not be called statically.

PEAR_Remote
PEAR_Remote::call
PEAR_Remote


Execute a server function

PEAR_Remote
PEAR_REST
PEAR_Remote
PHP Manual

PEAR_Remote::call()

(No version information available, might be only in CVS)

— Execute a server function

funcsynopsis funcsynopsisinfo require_once 'PEAR/Remote.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_Remote::call()/funcdef paramdefstring $method /paramdef paramdefmixed $args,... /paramdef /funcprototype /funcsynopsis

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.

PEAR_Remote
PEAR_REST
PEAR_Remote


PEAR_REST

PEAR_Remote::call
Class Summary PEAR_REST
PEAR Installer classes


Intelligently retrieve data, following hyperlinks if necessary, and re-directing

PEAR_REST
constructor PEAR_REST::PEAR_REST
PEAR_REST
PHP Manual

Class Summary PEAR_REST

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_REST
constructor PEAR_REST::PEAR_REST
PEAR_REST


PEAR_REST

Class Summary PEAR_REST
PEAR_REST::downloadHttp
PEAR_REST
PHP Manual

constructor PEAR_REST::PEAR_REST()

(No version information available, might be only in CVS)

constructor — PEAR_REST

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef void constructor PEAR_REST::PEAR_REST() /funcdef paramdef PEAR_Config &$config /paramdef paramdef array $options = array() /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_REST
PEAR_REST::downloadHttp
PEAR_REST


Efficiently Download a file through HTTP. Returns downloaded file as a string in-memory This is best used for small files

constructor PEAR_REST::PEAR_REST
PEAR_REST::getCache
PEAR_REST
PHP Manual

PEAR_REST::downloadHttp()

(No version information available, might be only in CVS)

— Efficiently Download a file through HTTP. Returns downloaded file as a string in-memory This is best used for small files

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef string|array PEAR_REST::downloadHttp() /funcdef paramdef string $url /paramdef paramdef false|string|array $lastmodified = null /paramdef paramdef false|array $accept = false /paramdef paramdef string $save_dir /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_REST::PEAR_REST
PEAR_REST::getCache
PEAR_REST


getCache

PEAR_REST::downloadHttp
PEAR_REST::getCacheId
PEAR_REST
PHP Manual

PEAR_REST::getCache()

(No version information available, might be only in CVS)

— getCache

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef mixed|false PEAR_REST::getCache() /funcdef paramdef string $url /paramdef /funcprototype /funcsynopsis

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.

PEAR_REST::downloadHttp
PEAR_REST::getCacheId
PEAR_REST


getCacheId

PEAR_REST::getCache
PEAR_REST::retrieveCacheFirst
PEAR_REST
PHP Manual

PEAR_REST::getCacheId()

(No version information available, might be only in CVS)

— getCacheId

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef array|false PEAR_REST::getCacheId() /funcdef paramdef string $url /paramdef /funcprototype /funcsynopsis

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.

PEAR_REST::getCache
PEAR_REST::retrieveCacheFirst
PEAR_REST


Retrieve REST data, but always retrieve the local cache if it is available.

PEAR_REST::getCacheId
PEAR_REST::retrieveData
PEAR_REST
PHP Manual

PEAR_REST::retrieveCacheFirst()

(No version information available, might be only in CVS)

— Retrieve REST data, but always retrieve the local cache if it is available.

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef string|array PEAR_REST::retrieveCacheFirst() /funcdef paramdef string $url /paramdef paramdef array|false $accept = false /paramdef paramdef boolean $forcestring = false /paramdef /funcprototype /funcsynopsis

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.

PEAR_REST::getCacheId
PEAR_REST::retrieveData
PEAR_REST


Retrieve a remote REST resource

PEAR_REST::retrieveCacheFirst
PEAR_REST::saveCache
PEAR_REST
PHP Manual

PEAR_REST::retrieveData()

(No version information available, might be only in CVS)

— Retrieve a remote REST resource

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef string|array PEAR_REST::retrieveData() /funcdef paramdef string $url /paramdef paramdef array|false $accept = false /paramdef paramdef bool $forcestring = false /paramdef /funcprototype /funcsynopsis

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.

PEAR_REST::retrieveCacheFirst
PEAR_REST::saveCache
PEAR_REST


Save the value retrieved from a remote REST resource in the local cache.

PEAR_REST::retrieveData
PEAR_REST::useLocalCache
PEAR_REST
PHP Manual

PEAR_REST::saveCache()

(No version information available, might be only in CVS)

— Save the value retrieved from a remote REST resource in the local cache.

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef void PEAR_REST::saveCache() /funcdef paramdef string $url /paramdef paramdef mixed $contents /paramdef paramdef array $lastmodified /paramdef paramdef bool $nochange = false /paramdef /funcprototype /funcsynopsis

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.

PEAR_REST::retrieveData
PEAR_REST::useLocalCache
PEAR_REST


useLocalCache

PEAR_REST
PEAR
PEAR_REST
PHP Manual

PEAR_REST::useLocalCache()

(No version information available, might be only in CVS)

— useLocalCache

funcsynopsis funcsynopsisinforequire_once '/REST.php';/funcsynopsisinfo funcprototype funcdef mixed PEAR_REST::useLocalCache() /funcdef paramdef bool $url /paramdef /funcprototype /funcsynopsis

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.

PEAR_REST
PEAR
PEAR_REST


PEAR

PEAR_REST::useLocalCache
Class Summary PEAR_RunTest
PEAR Installer classes


PEAR
constructor PEAR_RunTest::PEAR_RunTest
PEAR
PHP Manual

Class Summary PEAR_RunTest

(No version information available, might be only in CVS)

Class Summary — 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

PEAR
constructor PEAR_RunTest::PEAR_RunTest
PEAR


Instantiate a PEAR_RunTest object.

Class Summary PEAR_RunTest
PEAR_RunTest::generate_diff
PEAR
PHP Manual

constructor PEAR_RunTest::PEAR_RunTest()

(No version information available, might be only in CVS)

constructor — Instantiate a PEAR_RunTest object.

funcsynopsis funcsynopsisinforequire_once '/RunTest.php';/funcsynopsisinfo funcprototype funcdef void constructor PEAR_RunTest::PEAR_RunTest() /funcdef paramdef PEAR_Common|null $logger = NULL /paramdef paramdef array $options = array() /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_RunTest
PEAR_RunTest::generate_diff
PEAR


generate_diff

constructor PEAR_RunTest::PEAR_RunTest
PEAR_RunTest::run
PEAR
PHP Manual

PEAR_RunTest::generate_diff()

(No version information available, might be only in CVS)

— generate_diff

funcsynopsis funcsynopsisinforequire_once '/RunTest.php';/funcsynopsisinfo funcprototype funcdef void PEAR_RunTest::generate_diff() /funcdef paramdef string $wanted /paramdef paramdef string $output /paramdef paramdef array|false $return_value /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_RunTest::PEAR_RunTest
PEAR_RunTest::run
PEAR


run

PEAR
PEAR_Validate
PEAR
PHP Manual

PEAR_RunTest::run()

(No version information available, might be only in CVS)

— run

funcsynopsis funcsynopsisinforequire_once '/RunTest.php';/funcsynopsisinfo funcprototype funcdef string|PEAR_Error PEAR_RunTest::run() /funcdef paramdef string $file /paramdef paramdef string $ini_settings = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR
PEAR_Validate
PEAR


PEAR_Validate

PEAR_RunTest::run
Class Summary PEAR_Validate
PEAR Installer classes


PEAR_Validate
PEAR_Validate::_addFailure
PEAR_Validate
PHP Manual

Class Summary PEAR_Validate

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_Validate
PEAR_Validate::_addFailure
PEAR_Validate


_addFailure

Class Summary PEAR_Validate
PEAR_Validate::_addWarning
PEAR_Validate
PHP Manual

PEAR_Validate::_addFailure()

(No version information available, might be only in CVS)

— _addFailure

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::_addFailure() /funcdef paramdef string $field /paramdef paramdef string $reason /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_Validate
PEAR_Validate::_addWarning
PEAR_Validate


_addWarning

PEAR_Validate::_addFailure
PEAR_Validate::getFailures
PEAR_Validate
PHP Manual

PEAR_Validate::_addWarning()

(No version information available, might be only in CVS)

— _addWarning

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::_addWarning() /funcdef paramdef string $field /paramdef paramdef string $reason /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::_addFailure
PEAR_Validate::getFailures
PEAR_Validate


getFailures

PEAR_Validate::_addWarning
PEAR_Validate::getValidStates
PEAR_Validate
PHP Manual

PEAR_Validate::getFailures()

(No version information available, might be only in CVS)

— getFailures

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::getFailures() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::_addWarning
PEAR_Validate::getValidStates
PEAR_Validate


Get a list of valid stability levels

PEAR_Validate::getFailures
PEAR_Validate::setPackageFile
PEAR_Validate
PHP Manual

PEAR_Validate::getValidStates()

(No version information available, might be only in CVS)

— Get a list of valid stability levels

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef array PEAR_Validate::getValidStates() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::getFailures
PEAR_Validate::setPackageFile
PEAR_Validate


setPackageFile

PEAR_Validate::getValidStates
PEAR_Validate::validate
PEAR_Validate
PHP Manual

PEAR_Validate::setPackageFile()

(No version information available, might be only in CVS)

— setPackageFile

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::setPackageFile() /funcdef paramdef PEAR_PackageFile_v1|PEAR_PackageFile_v2 &$pf /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::getValidStates
PEAR_Validate::validate
PEAR_Validate


validate

PEAR_Validate::setPackageFile
PEAR_Validate::validateChangelog
PEAR_Validate
PHP Manual

PEAR_Validate::validate()

(No version information available, might be only in CVS)

— validate

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validate() /funcdef paramdef int $state = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::setPackageFile
PEAR_Validate::validateChangelog
PEAR_Validate


validateChangelog

PEAR_Validate::validate
PEAR_Validate::validateDate
PEAR_Validate
PHP Manual

PEAR_Validate::validateChangelog()

(No version information available, might be only in CVS)

— validateChangelog

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateChangelog() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validate
PEAR_Validate::validateDate
PEAR_Validate


validateDate

PEAR_Validate::validateChangelog
PEAR_Validate::validateDependencies
PEAR_Validate
PHP Manual

PEAR_Validate::validateDate()

(No version information available, might be only in CVS)

— validateDate

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateDate() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateChangelog
PEAR_Validate::validateDependencies
PEAR_Validate


for package.xml 2.0 only - channels can't use package.xml 1.0

PEAR_Validate::validateDate
PEAR_Validate::validateDeps
PEAR_Validate
PHP Manual

PEAR_Validate::validateDependencies()

(No version information available, might be only in CVS)

— for package.xml 2.0 only - channels can't use package.xml 1.0

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateDependencies() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateDate
PEAR_Validate::validateDeps
PEAR_Validate


validateDeps

PEAR_Validate::validateDependencies
PEAR_Validate::validateDescription
PEAR_Validate
PHP Manual

PEAR_Validate::validateDeps()

(No version information available, might be only in CVS)

— validateDeps

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateDeps() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateDependencies
PEAR_Validate::validateDescription
PEAR_Validate


validateDescription

PEAR_Validate::validateDeps
PEAR_Validate::validateFilelist
PEAR_Validate
PHP Manual

PEAR_Validate::validateDescription()

(No version information available, might be only in CVS)

— validateDescription

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateDescription() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateDeps
PEAR_Validate::validateFilelist
PEAR_Validate


validateFilelist

PEAR_Validate::validateDescription
PEAR_Validate::validateLicense
PEAR_Validate
PHP Manual

PEAR_Validate::validateFilelist()

(No version information available, might be only in CVS)

— validateFilelist

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateFilelist() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateDescription
PEAR_Validate::validateLicense
PEAR_Validate


validateLicense

PEAR_Validate::validateFilelist
PEAR_Validate::validateMainFilelist
PEAR_Validate
PHP Manual

PEAR_Validate::validateLicense()

(No version information available, might be only in CVS)

— validateLicense

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateLicense() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateFilelist
PEAR_Validate::validateMainFilelist
PEAR_Validate


for package.xml 2.0 only

PEAR_Validate::validateLicense
PEAR_Validate::validateMaintainers
PEAR_Validate
PHP Manual

PEAR_Validate::validateMainFilelist()

(No version information available, might be only in CVS)

— for package.xml 2.0 only

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateMainFilelist() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateLicense
PEAR_Validate::validateMaintainers
PEAR_Validate


validateMaintainers

PEAR_Validate::validateMainFilelist
PEAR_Validate::validateNotes
PEAR_Validate
PHP Manual

PEAR_Validate::validateMaintainers()

(No version information available, might be only in CVS)

— validateMaintainers

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateMaintainers() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateMainFilelist
PEAR_Validate::validateNotes
PEAR_Validate


validateNotes

PEAR_Validate::validateMaintainers
PEAR_Validate::validatePackageName
PEAR_Validate
PHP Manual

PEAR_Validate::validateNotes()

(No version information available, might be only in CVS)

— validateNotes

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateNotes() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateMaintainers
PEAR_Validate::validatePackageName
PEAR_Validate


validatePackageName

PEAR_Validate::validateNotes
PEAR_Validate::validateReleaseFilelist
PEAR_Validate
PHP Manual

PEAR_Validate::validatePackageName()

(No version information available, might be only in CVS)

— validatePackageName

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validatePackageName() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateNotes
PEAR_Validate::validateReleaseFilelist
PEAR_Validate


for package.xml 2.0 only

PEAR_Validate::validatePackageName
PEAR_Validate::validateStability
PEAR_Validate
PHP Manual

PEAR_Validate::validateReleaseFilelist()

(No version information available, might be only in CVS)

— for package.xml 2.0 only

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateReleaseFilelist() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validatePackageName
PEAR_Validate::validateStability
PEAR_Validate


validateStability

PEAR_Validate::validateReleaseFilelist
PEAR_Validate::validateState
PEAR_Validate
PHP Manual

PEAR_Validate::validateStability()

(No version information available, might be only in CVS)

— validateStability

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateStability() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateReleaseFilelist
PEAR_Validate::validateState
PEAR_Validate


validateState

PEAR_Validate::validateStability
PEAR_Validate::validateSummary
PEAR_Validate
PHP Manual

PEAR_Validate::validateState()

(No version information available, might be only in CVS)

— validateState

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateState() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateStability
PEAR_Validate::validateSummary
PEAR_Validate


validateSummary

PEAR_Validate::validateState
PEAR_Validate::validateTime
PEAR_Validate
PHP Manual

PEAR_Validate::validateSummary()

(No version information available, might be only in CVS)

— validateSummary

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateSummary() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateState
PEAR_Validate::validateTime
PEAR_Validate


validateTime

PEAR_Validate::validateSummary
PEAR_Validate::validateVersion
PEAR_Validate
PHP Manual

PEAR_Validate::validateTime()

(No version information available, might be only in CVS)

— validateTime

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateTime() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateSummary
PEAR_Validate::validateVersion
PEAR_Validate


protected function to validate a version

PEAR_Validate::validateTime
PEAR_Validate::validGroupName
PEAR_Validate
PHP Manual

PEAR_Validate::validateVersion()

(No version information available, might be only in CVS)

— protected function to validate a version

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validateVersion() /funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateTime
PEAR_Validate::validGroupName
PEAR_Validate


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::validateVersion
PEAR_Validate::validPackageName
PEAR_Validate
PHP Manual

PEAR_Validate::validGroupName()

(No version information available, might be only in CVS)

— This validates a dependency group name, and dependency group names must conform to the PEAR naming convention, so the method is final and static.

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validGroupName() /funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validateVersion
PEAR_Validate::validPackageName
PEAR_Validate


utility method to validate a package name string

PEAR_Validate::validGroupName
PEAR_Validate::validState
PEAR_Validate
PHP Manual

PEAR_Validate::validPackageName()

(No version information available, might be only in CVS)

— utility method to validate a package name string

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Validate::validPackageName() /funcdef paramdef string $name /paramdef paramdef string $validatepackagename = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validGroupName
PEAR_Validate::validState
PEAR_Validate


Determine whether $state represents a valid stability level

PEAR_Validate::validPackageName
PEAR_Validate::validVersion
PEAR_Validate
PHP Manual

PEAR_Validate::validState()

(No version information available, might be only in CVS)

— Determine whether $state represents a valid stability level

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_Validate::validState() /funcdef paramdef string $state /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validPackageName
PEAR_Validate::validVersion
PEAR_Validate


Determine whether a version is a properly formatted version number that can be used by version_compare

PEAR_Validate::validState
PEAR_Validate::_validPackageName
PEAR_Validate
PHP Manual

PEAR_Validate::validVersion()

(No version information available, might be only in CVS)

— Determine whether a version is a properly formatted version number that can be used by version_compare()

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_Validate::validVersion() /funcdef paramdef string $ver /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validState
PEAR_Validate::_validPackageName
PEAR_Validate


Override this method to handle validation of normal package names

PEAR_Validate::validVersion
Package PEAR Constants
PEAR_Validate
PHP Manual

PEAR_Validate::_validPackageName()

(No version information available, might be only in CVS)

— Override this method to handle validation of normal package names

funcsynopsis funcsynopsisinforequire_once '/Validate.php';/funcsynopsisinfo funcprototype funcdef bool PEAR_Validate::_validPackageName() /funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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.

PEAR_Validate::validVersion
Package PEAR Constants
PEAR_Validate


Constants defined in and used by PEAR

PEAR_Validate
PEAR
PEAR_Validate
PHP Manual

Package PEAR Constants

(No version information available, might be only in CVS)

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

PEAR_Validate
PEAR
PEAR_Validate


PEAR

PEAR Installer classes
Class Summary PEAR_XMLParser
PEAR Installer classes


PEAR
PEAR_XMLParser::getData
PEAR
PHP Manual

Class Summary PEAR_XMLParser

(No version information available, might be only in CVS)

Class Summary — Parser for any xml file

Parser for any xml file

This package is not documented yet.

Class Trees for PEAR_XMLParser

  • PEAR_XMLParser

PEAR
PEAR_XMLParser::getData
PEAR


getData

Class Summary PEAR_XMLParser
PEAR_XMLParser::parse
PEAR
PHP Manual

PEAR_XMLParser::getData()

(No version information available, might be only in CVS)

— getData

funcsynopsis funcsynopsisinforequire_once '/XMLParser.php';/funcsynopsisinfo funcprototype funcdef array PEAR_XMLParser::getData() /funcdef paramdef /funcprototype /funcsynopsis

Description

Return the array representation of XML as parsed by parse().

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary PEAR_XMLParser
PEAR_XMLParser::parse
PEAR


parse

PEAR_XMLParser::getData
PEAR_XMLParser::preProcessStupidSaxon
PEAR
PHP Manual

PEAR_XMLParser::parse()

(No version information available, might be only in CVS)

— parse

funcsynopsis funcsynopsisinforequire_once '/XMLParser.php';/funcsynopsisinfo funcprototype funcdef true|PEAR_Error PEAR_XMLParser::parse() /funcdef paramdef string $data /paramdef /funcprototype /funcsynopsis

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.

PEAR_XMLParser::getData
PEAR_XMLParser::preProcessStupidSaxon
PEAR


pre-process xml to weed out characters/entities that would kill parsing

PEAR
PEAR channel server REST interface
PEAR
PHP Manual

PEAR_XMLParser::preProcessStupidSaxon()

(No version information available, might be only in CVS)

— pre-process xml to weed out characters/entities that would kill parsing

funcsynopsis funcsynopsisinforequire_once '/XMLParser.php';/funcsynopsisinfo funcprototype funcdef string PEAR_XMLParser::preProcessStupidSaxon() /funcdef paramdef string $data /paramdef /funcprototype /funcsynopsis

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.

PEAR
PEAR channel server REST interface
PEAR


PEAR channel server REST interface

Table of Contents

  • Directory structure
  • File formats
  • REST version history
  • Use cases

This manual section describes how the REST interface of a PEAR channel server works, as well as the files and their formats look like.

Core components
Which files a channel server provides
Core components


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
PEAR channel server REST interface
How the files look like
PEAR channel server REST interface


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>
<?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>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>

   <package>
    <name>Toolbox</name>
    <channel>pear.example.org</channel>
    <min>1.3.0</min>
   </package>

 </dependencies>
Which files a channel server provides
Changes between PEAR REST interface versions
PEAR channel server REST interface


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

How the files look like
What do do when releasing a new package
PEAR channel server REST interface


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 .

PEAR channel server REST interface
Packages
PEAR channel server REST interface


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
  • Payment
  • PEAR
  • PHP
  • QA Tools
  • Science
  • Streams
  • Structures
  • System
  • Text
  • Tools and Utilities
  • Validate
  • Web Services
  • XML
PEAR Manual
Authentication
PEAR Manual


Authentication

Table of Contents

  • Auth
  • Auth_HTTP
  • Auth_PrefManager
  • Auth_RADIUS
  • LiveUser
  • LiveUser_Admin

Provides Packages for authentication management

Packages
Auth
Packages


Auth

Provides a framework for user authentication.

Authentication
Introduction
Authentication


A usage example

Auth
Auth Options
Auth
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

Example #1 Typical usage example for PEAR::Auth

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.

Example #2 Using optional authentication

// 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!".

Example #3 Logout functionality

The following example performs a "logout" for the current user and displays the login form again.

$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.

Auth
Auth Options
Auth


Options for controlling the behaviour of Auth

Introduction
Logging
Auth
PHP Manual

Auth Options

(No version information available, might be only in CVS)

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.

Introduction
Logging
Auth


Introduction

Auth Options
Storage drivers
Auth
PHP Manual

Logging

(No version information available, might be only in CVS)

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

Example #1 Typical usage example for accessing the logs from PEAR::Auth

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.

$observer = new My_Log_Observer(PEAR_LOG_DEBUG);

Note

This container has only been available since version 1.5.0.

Auth Options
Storage drivers
Auth


Introduction

Logging
Auth_Container_Array
Auth
PHP Manual

Storage drivers

(No version information available, might be only in CVS)

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.

Logging
Auth_Container_Array
Auth


Authenticate against an array of usernames and passwords

Storage drivers
Auth_Container_DB
Auth
PHP Manual

Auth_Container_Array

(No version information available, might be only in CVS)

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.
array(
    'guest' => '084e0343a0486ff05530df6c705c8bb4', // password guest
    'georg' => 'fc77dba827fcc88e0243404572c51325' // password georg
)

Storage drivers
Auth_Container_DB
Auth


Authenticate against a database using DB

Auth_Container_Array
Auth_Container_DBLite
Auth
PHP Manual

Auth_Container_DB

(No version information available, might be only in CVS)

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.

Auth_Container_Array
Auth_Container_DBLite
Auth


Authenticate against a database using DB

Auth_Container_DB
Auth_Container_File
Auth
PHP Manual

Auth_Container_DBLite

(No version information available, might be only in CVS)

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.

Auth_Container_DB
Auth_Container_File
Auth


Authenticate a password file using File_Passwd

Auth_Container_DBLite
Auth_Container_IMAP
Auth
PHP Manual

Auth_Container_File

(No version information available, might be only in CVS)

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.

Auth_Container_DBLite
Auth_Container_IMAP
Auth


Authenticate against an IMAP server

Auth_Container_File
Auth_Container_KADM5
Auth
PHP Manual

Auth_Container_IMAP

(No version information available, might be only in CVS)

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.

Auth_Container_File
Auth_Container_KADM5
Auth


Authenticate against a Kerberos 5 server

Auth_Container_IMAP
Auth_Container_LDAP
Auth
PHP Manual

Auth_Container_KADM5

(No version information available, might be only in CVS)

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.

Auth_Container_IMAP
Auth_Container_LDAP
Auth


Authenticate against an LDAP server

Auth_Container_KADM5
Auth_Container_MDB
Auth
PHP Manual

Auth_Container_LDAP

(No version information available, might be only in CVS)

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.

Example #1 Authenticating against a LDAP server

$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'
   ));

Example #2 Requiring users to be within specific groups

$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'
   ));

Example #3 Authenticating against a Microsoft Active Directory server

$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).

Auth_Container_KADM5
Auth_Container_MDB
Auth


Authenticate against a database using MDB

Auth_Container_LDAP
Auth_Container_MDB2
Auth
PHP Manual

Auth_Container_MDB

(No version information available, might be only in CVS)

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.

Auth_Container_LDAP
Auth_Container_MDB2
Auth


Authenticate against a database using MDB2

Auth_Container_MDB
Auth_Container_Multiple
Auth
PHP Manual

Auth_Container_MDB2

(No version information available, might be only in CVS)

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 #1 Example overriding MDB2's default portability

$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');
Auth_Container_MDB
Auth_Container_Multiple
Auth


Authenticate against multiple Auth_Containers

Auth_Container_MDB2
Auth_Container_PEAR
Auth
PHP Manual

Auth_Container_Multiple

(No version information available, might be only in CVS)

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 #1 Example usage of Auth_Container_Multiple

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.

Auth_Container_MDB2
Auth_Container_PEAR
Auth


Authenticate against the PEAR website

Auth_Container_Multiple
Auth_Container_POP3
Auth
PHP Manual

Auth_Container_PEAR

(No version information available, might be only in CVS)

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.

Auth_Container_Multiple
Auth_Container_POP3
Auth


Authenticate against a POP3 server

Auth_Container_PEAR
Auth_Container_RADIUS
Auth
PHP Manual

Auth_Container_POP3

(No version information available, might be only in CVS)

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.

Auth_Container_PEAR
Auth_Container_RADIUS
Auth


Authenticate against a RADIUS server

Auth_Container_POP3
Auth_Container_SAP
Auth
PHP Manual

Auth_Container_RADIUS

(No version information available, might be only in CVS)

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.

Auth_Container_POP3
Auth_Container_SAP
Auth


Authenticate against a SAP server

Auth_Container_RADIUS
Auth_Container_SMBPasswd
Auth
PHP Manual

Auth_Container_SAP

(No version information available, might be only in CVS)

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.

Auth_Container_RADIUS
Auth_Container_SMBPasswd
Auth


Authenticate a SAMBA smbpasswd file using File_SMBPasswd

Auth_Container_SAP
Auth_Container_SOAP
Auth
PHP Manual

Auth_Container_SMBPasswd

(No version information available, might be only in CVS)

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.

Auth_Container_SAP
Auth_Container_SOAP
Auth


Authenticate against a SOAP service

Auth_Container_SMBPasswd
Auth_Container_SOAP5
Auth
PHP Manual

Auth_Container_SOAP

(No version information available, might be only in CVS)

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.

array(
  'field1'  => 'value1',
  'foo'     => 'bar',
);

Auth_Container_SMBPasswd
Auth_Container_SOAP5
Auth


Authenticate against a SOAP service

Auth_Container_SOAP
Auth_Container_vpopmail
Auth
PHP Manual

Auth_Container_SOAP5

(No version information available, might be only in CVS)

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.

array(
  'field1'  => 'value1',
  'foo'     => 'bar',
);

Auth_Container_SOAP
Auth_Container_vpopmail
Auth


Authenticate against a vpopmail service

Auth_Container_SOAP5
Custom Auth_Container
Auth
PHP Manual

Auth_Container_vpopmail

(No version information available, might be only in CVS)

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.

Auth_Container_SOAP5
Custom Auth_Container
Auth


Build a custom storage container

Auth_Container_vpopmail
Auth_Frontend_HTML
Auth
PHP Manual

Custom Auth_Container

(No version information available, might be only in CVS)

Custom Auth_Container — Build a custom storage container

Custom Storage Containers

Here is a skeleton for a custom Auth storage container

Example #1 CustomAuthContainer.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.

Example #2 authcustom.php

include_once 'CustomAuthContainer.php';
include_once 'Auth/Auth.php';

$auth_container = new CustomAuthContainer($params);
$myauth = new Auth($auth_container);

$myauth->start();
Auth_Container_vpopmail
Auth_Frontend_HTML
Auth


Default login form

Custom Auth_Container
Constants
Auth
PHP Manual

Auth_Frontend_HTML

(No version information available, might be only in CVS)

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.

Custom Auth_Container
Constants
Auth


predefined constants

Auth_Frontend_HTML
Auth::Auth()
Auth
PHP Manual

Constants

(No version information available, might be only in CVS)

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.

Auth_Frontend_HTML
Auth::Auth()
Auth


constructor

Constants
Auth::addUser()
Auth
PHP Manual

Auth::Auth()

(No version information available, might be only in CVS)

Auth::Auth() — constructor

funcsynopsis funcprototype funcdef Auth::Auth()/funcdef paramdefmixed $storageDriver /paramdef paramdefmixed $options = "" /paramdef paramdefstring $loginFunction = "" /paramdef paramdefboolean $showLogin = TRUE /paramdef /funcprototype /funcsynopsis

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

Example #1 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

Example #2 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

Constants
Auth::addUser()
Auth


add a new user

Auth::Auth()
Auth::attachLogObserver()
Auth
PHP Manual

Auth::addUser()

(No version information available, might be only in CVS)

Auth::addUser() — add a new user

funcsynopsis funcprototype funcdefmixed Auth::addUser()/funcdef paramdefstring $username /paramdef paramdefstring $password /paramdef paramdefmixed $additional = '' /paramdef /funcprototype /funcsynopsis

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.

Auth::Auth()
Auth::attachLogObserver()
Auth


Attach a log observer instance to the internal Log object

Auth::addUser()
Auth::changePassword()
Auth
PHP Manual

Auth::attachLogObserver()

(No version information available, might be only in CVS)

Auth::attachLogObserver() — Attach a log observer instance to the internal Log object

funcsynopsis funcprototype funcdefvoid Auth::attachLogObserver()/funcdef paramdefobject &$observer /paramdef /funcprototype /funcsynopsis

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.

Auth::addUser()
Auth::changePassword()
Auth


change the password of a user

Auth::attachLogObserver()
Auth::checkAuth()
Auth
PHP Manual

Auth::changePassword()

(No version information available, might be only in CVS)

Auth::changePassword() — change the password of a user

funcsynopsis funcprototype funcdefmixed Auth::changePassword()/funcdef paramdefstring $username /paramdef paramdefstring $password /paramdef /funcprototype /funcsynopsis

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.

Auth::attachLogObserver()
Auth::checkAuth()
Auth


check if a session with valid authentication information exists

Auth::changePassword()
Auth::getAuth()
Auth
PHP Manual

Auth::checkAuth()

(No version information available, might be only in CVS)

Auth::checkAuth() — check if a session with valid authentication information exists

funcsynopsis funcprototype funcdefboolean Auth::checkAuth()/funcdef paramdef /funcprototype /funcsynopsis

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.

Auth::changePassword()
Auth::getAuth()
Auth


check for an authenticated user

Auth::checkAuth()
Auth::getAuthData()
Auth
PHP Manual

Auth::getAuth()

(No version information available, might be only in CVS)

Auth::getAuth() — check for an authenticated user

funcsynopsis funcprototype funcdefboolean Auth::getAuth()/funcdef paramdef /funcprototype /funcsynopsis

Description

Check if the user has been authenticated.

Previously this function had a different behaviour to Auth::getAuth() but it is now just an alias.

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.

Auth::checkAuth()
Auth::getAuthData()
Auth


retrieve extra information stored within the auth session

Auth::getAuth()
Auth::getStatus()
Auth
PHP Manual

Auth::getAuthData()

(No version information available, might be only in CVS)

Auth::getAuthData() — retrieve extra information stored within the auth session

funcsynopsis funcprototype funcdefmixed Auth::getAuthData()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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.

Auth::getAuth()
Auth::getStatus()
Auth


get the current status of the auth session

Auth::getAuthData()
Auth::getUsername()
Auth
PHP Manual

Auth::getStatus()

(No version information available, might be only in CVS)

Auth::getStatus() — get the current status of the auth session

funcsynopsis funcprototype funcdefint Auth::getStatus()/funcdef paramdef /funcprototype /funcsynopsis

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".

Auth::getAuthData()
Auth::getUsername()
Auth


get the username of the authenticated user

Auth::getStatus()
Auth::listUsers()
Auth
PHP Manual

Auth::getUsername()

(No version information available, might be only in CVS)

Auth::getUsername() — get the username of the authenticated user

funcsynopsis funcprototype funcdefstring Auth::getUsername()/funcdef paramdef /funcprototype /funcsynopsis

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.

Auth::getStatus()
Auth::listUsers()
Auth


list available users

Auth::getUsername()
Auth::logout()
Auth
PHP Manual

Auth::listUsers()

(No version information available, might be only in CVS)

Auth::listUsers() — list available users

funcsynopsis funcprototype funcdefarray Auth::listUsers()/funcdef paramdef /funcprototype /funcsynopsis

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.

Auth::getUsername()
Auth::logout()
Auth


logout an authenticated user

Auth::listUsers()
Auth::removeUser()
Auth
PHP Manual

Auth::logout()

(No version information available, might be only in CVS)

Auth::logout() — logout an authenticated user

funcsynopsis funcprototype funcdefvoid Auth::logout()/funcdef paramdef /funcprototype /funcsynopsis

Description

Logout any currently logged in user.

Note

This function can not be called statically.

Auth::listUsers()
Auth::removeUser()
Auth


remove a user account

Auth::logout()
Auth::setAdvancedSecurity()
Auth
PHP Manual

Auth::removeUser()

(No version information available, might be only in CVS)

Auth::removeUser() — remove a user account

funcsynopsis funcprototype funcdefmixed Auth::removeUser()/funcdef paramdefstring $username /paramdef /funcprototype /funcsynopsis

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.

Auth::logout()
Auth::setAdvancedSecurity()
Auth


Enables advanced security features. Turned off by default

Auth::removeUser()
Auth::setAllowLogin()
Auth
PHP Manual

Auth::setAdvancedSecurity()

(No version information available, might be only in CVS)

Auth::setAdvancedSecurity() — Enables advanced security features. Turned off by default

funcsynopsis funcprototype funcdefvoid Auth::setAdvancedSecurity()/funcdef paramdefbool $flag = true /paramdef /funcprototype /funcsynopsis

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.

Auth::removeUser()
Auth::setAllowLogin()
Auth


Controls if the user will be allowed to login. Turned on by default

Auth::setAdvancedSecurity()
Auth::setAuth()
Auth
PHP Manual

Auth::setAllowLogin()

(No version information available, might be only in CVS)

Auth::setAllowLogin() — Controls if the user will be allowed to login. Turned on by default

funcsynopsis funcprototype funcdefvoid Auth::setAllowLogin()/funcdef paramdefbool $allowLogin = true /paramdef /funcprototype /funcsynopsis

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

Auth::setAdvancedSecurity()
Auth::setAuth()
Auth


set a specific user to be marked as logged in

Auth::setAllowLogin()
Auth::setAuthData()
Auth
PHP Manual

Auth::setAuth()

(No version information available, might be only in CVS)

Auth::setAuth() — set a specific user to be marked as logged in

funcsynopsis funcprototype funcdefvoid Auth::setAuth()/funcdef paramdefstring $username /paramdef /funcprototype /funcsynopsis

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.

Auth::setAllowLogin()
Auth::setAuthData()
Auth


store extra information with the Auth session

Auth::setAuth()
Auth::setCheckAuthCallback()
Auth
PHP Manual

Auth::setAuthData()

(No version information available, might be only in CVS)

Auth::setAuthData() — store extra information with the Auth session

funcsynopsis funcprototype funcdefvoid Auth::setAuthData()/funcdef paramdefstring $name /paramdef paramdefmixed $value /paramdef paramdefboolean $overwrite = true /paramdef /funcprototype /funcsynopsis

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.

Auth::setAuth()
Auth::setCheckAuthCallback()
Auth


set a callback to run when ever session validity is checked

Auth::setAuthData()
Auth::setExpire()
Auth
PHP Manual

Auth::setCheckAuthCallback()

(No version information available, might be only in CVS)

Auth::setCheckAuthCallback() — set a callback to run when ever session validity is checked

funcsynopsis funcprototype funcdefvoid Auth::setCheckAuthCallback()/funcdef paramdefstring $checkAuthCallback /paramdef /funcprototype /funcsynopsis

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.

Auth::setAuthData()
Auth::setExpire()
Auth


set expiration time for authentication

Auth::setCheckAuthCallback()
Auth::setFailedLoginCallback()
Auth
PHP Manual

Auth::setExpire()

(No version information available, might be only in CVS)

Auth::setExpire() — set expiration time for authentication

funcsynopsis funcprototype funcdefvoid Auth::setExpire()/funcdef paramdefinteger $time /paramdef paramdefboolean $add = FALSE /paramdef /funcprototype /funcsynopsis

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.

Auth::setCheckAuthCallback()
Auth::setFailedLoginCallback()
Auth


set a callback for failed login attempts

Auth::setExpire()
Auth::setIdle()
Auth
PHP Manual

Auth::setFailedLoginCallback()

(No version information available, might be only in CVS)

Auth::setFailedLoginCallback() — set a callback for failed login attempts

funcsynopsis funcprototype funcdefvoid Auth::setFailedLoginCallback()/funcdef paramdefstring $loginFailedCallback /paramdef /funcprototype /funcsynopsis

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.

Auth::setExpire()
Auth::setIdle()
Auth


set maximum idle time for authentication

Auth::setFailedLoginCallback()
Auth::setLoginCallback()
Auth
PHP Manual

Auth::setIdle()

(No version information available, might be only in CVS)

Auth::setIdle() — set maximum idle time for authentication

funcsynopsis funcprototype funcdefvoid Auth::setIdle()/funcdef paramdefinteger $time /paramdef paramdefboolean $add = FALSE /paramdef /funcprototype /funcsynopsis

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.

Auth::setFailedLoginCallback()
Auth::setLoginCallback()
Auth


set a callback for successful login attempts

Auth::setIdle()
Auth::setLogoutCallback()
Auth
PHP Manual

Auth::setLoginCallback()

(No version information available, might be only in CVS)

Auth::setLoginCallback() — set a callback for successful login attempts

funcsynopsis funcprototype funcdefvoid Auth::setLoginCallback()/funcdef paramdefstring $loginCallback /paramdef /funcprototype /funcsynopsis

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.

Auth::setIdle()
Auth::setLogoutCallback()
Auth


set a callback for successful logout attempts

Auth::setLoginCallback()
Auth::setSessionName()
Auth
PHP Manual

Auth::setLogoutCallback()

(No version information available, might be only in CVS)

Auth::setLogoutCallback() — set a callback for successful logout attempts

funcsynopsis funcprototype funcdefvoid Auth::setLogoutCallback()/funcdef paramdefstring $loginCallback /paramdef /funcprototype /funcsynopsis

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.

Auth::setLoginCallback()
Auth::setSessionName()
Auth


set a custom name for the Auth session variable

Auth::setLogoutCallback()
Auth::setShowLogin()
Auth
PHP Manual

Auth::setSessionName()

(No version information available, might be only in CVS)

Auth::setSessionName() — set a custom name for the Auth session variable

funcsynopsis funcprototype funcdefvoid Auth::setSessionName()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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!

Auth::setLogoutCallback()
Auth::setShowLogin()
Auth


controls if the login form will be displayed. Turned on by default

Auth::setSessionName()
Auth::sessionValidThru()
Auth
PHP Manual

Auth::setShowLogin()

(No version information available, might be only in CVS)

Auth::setShowLogin() — controls if the login form will be displayed. Turned on by default

funcsynopsis funcprototype funcdefvoid Auth::setShowLogin()/funcdef paramdefbool $showLogin = true /paramdef /funcprototype /funcsynopsis

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()

Auth::setSessionName()
Auth::sessionValidThru()
Auth


get the time up to the session is valid

Auth::setShowLogin()
Auth::start()
Auth
PHP Manual

Auth::sessionValidThru()

(No version information available, might be only in CVS)

Auth::sessionValidThru() — get the time up to the session is valid

funcsynopsis funcprototype funcdefvoid Auth::sessionValidThru()/funcdef paramdef /funcprototype /funcsynopsis

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.

Auth::setShowLogin()
Auth::start()
Auth


start authentication

Auth
Auth_HTTP
Auth
PHP Manual

Auth::start()

(No version information available, might be only in CVS)

Auth::start() — start authentication

funcsynopsis funcprototype funcdefvoid Auth::start()/funcdef paramdef /funcprototype /funcsynopsis

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.

Auth
Auth_HTTP
Auth


Auth_HTTP

Provides a framework for user authentication (aka an "User-Login") based on the HTTP

Auth::start()
Introduction
Authentication


to HTTP based authentication

Auth_HTTP
Auth_HTTP::Auth_HTTP()
Auth_HTTP
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Auth_HTTP
Auth_HTTP::Auth_HTTP()
Auth_HTTP


constructor

Introduction
Auth_HTTP Example
Auth_HTTP
PHP Manual

Auth_HTTP::Auth_HTTP()

(No version information available, might be only in CVS)

Auth_HTTP::Auth_HTTP() — constructor

funcsynopsis funcprototype funcdefvoid Auth_HTTP::Auth_HTTP()/funcdef paramdefstring $storageDriver = "DB" /paramdef paramdefmixed $options = "" /paramdef /funcprototype /funcsynopsis

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

Example #1 Using different DB parameters

require_once "Auth/HTTP.php";

$a = new Auth_HTTP("DB", "mysql://test:test@localhost/test");

$a->start();
Introduction
Auth_HTTP Example
Auth_HTTP


Example: A simple password protected page

Auth_HTTP::Auth_HTTP()
Auth_HTTP Example 2
Auth_HTTP
PHP Manual

Auth_HTTP Example

(No version information available, might be only in CVS)

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";

};

?>
Auth_HTTP::Auth_HTTP()
Auth_HTTP Example 2
Auth_HTTP


Example: A password protected page with multiple rows fetch and md5 password

Auth_HTTP Example
Auth_HTTP::getAuth()
Auth_HTTP
PHP Manual

Auth_HTTP Example 2

(No version information available, might be only in CVS)

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
};
?>
Auth_HTTP Example
Auth_HTTP::getAuth()
Auth_HTTP


check for an authenticated user

Auth_HTTP Example 2
Auth_HTTP::getStatus()
Auth_HTTP
PHP Manual

Auth_HTTP::getAuth()

(No version information available, might be only in CVS)

Auth_HTTP::getAuth() — check for an authenticated user

funcsynopsis funcprototype funcdefboolean Auth_HTTP::getAuth()/funcdef paramdef /funcprototype /funcsynopsis

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.

Auth_HTTP Example 2
Auth_HTTP::getStatus()
Auth_HTTP


returns informations about the current authentication status

Auth_HTTP::getAuth()
Auth_HTTP::start()
Auth_HTTP
PHP Manual

Auth_HTTP::getStatus()

(No version information available, might be only in CVS)

Auth_HTTP::getStatus() — returns informations about the current authentication status

funcsynopsis funcprototype funcdefstring Auth_HTTP::getStatus()/funcdef paramdef /funcprototype /funcsynopsis

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

Auth_HTTP::getAuth()
Auth_HTTP::start()
Auth_HTTP


start authentication

Auth_HTTP
Auth_PrefManager
Auth_HTTP
PHP Manual

Auth_HTTP::start()

(No version information available, might be only in CVS)

Auth_HTTP::start() — start authentication

funcsynopsis funcprototype funcdefvoid Auth_HTTP::start()/funcdef paramdef /funcprototype /funcsynopsis

Description

Start the authentication process.

Note

This function can not be called statically.

Auth_HTTP
Auth_PrefManager
Auth_HTTP


Auth_PrefManager

Provides a framework for managing preferences in applications.

Auth_HTTP::start()
Introduction to Auth_PrefManager
Authentication


Auth_PrefManager is a simple class to manage user or application preferences from a DB compatible database.

Auth_PrefManager
Tutorial
Auth_PrefManager
PHP Manual

Introduction to Auth_PrefManager

(No version information available, might be only in CVS)

Introduction to — 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

Auth_PrefManager
Tutorial
Auth_PrefManager


A short guide to using Auth_PrefManager

Introduction to Auth_PrefManager
constructor Auth_PrefManager::Auth_PrefManager
Auth_PrefManager
PHP Manual

Tutorial

(No version information available, might be only in CVS)

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:

Example #1 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.

Example #2 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.

Example #3 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.

Example #4 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.

Example #5 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

Example #6 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>
Introduction to Auth_PrefManager
constructor Auth_PrefManager::Auth_PrefManager
Auth_PrefManager


Constructor

Tutorial
Auth_PrefManager::clearCache
Auth_PrefManager
PHP Manual

constructor Auth_PrefManager::Auth_PrefManager()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef bool constructor Auth_PrefManager::Auth_PrefManager() /funcdef paramdef string $dsn /paramdef paramdef array $properties = NULL /paramdef paramdef string $defaultUser /paramdef /funcprototype /funcsynopsis

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.

Tutorial
Auth_PrefManager::clearCache
Auth_PrefManager


Cleans out the cache.

constructor Auth_PrefManager::Auth_PrefManager
Auth_PrefManager::deleteDefaultPref
Auth_PrefManager
PHP Manual

Auth_PrefManager::clearCache()

(No version information available, might be only in CVS)

— Cleans out the cache.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef void Auth_PrefManager::clearCache() /funcdef paramdef /funcprototype /funcsynopsis

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.

constructor Auth_PrefManager::Auth_PrefManager
Auth_PrefManager::deleteDefaultPref
Auth_PrefManager


Deletes a preference for the default user.

Auth_PrefManager::clearCache
Auth_PrefManager::deletePref
Auth_PrefManager
PHP Manual

Auth_PrefManager::deleteDefaultPref()

(No version information available, might be only in CVS)

— Deletes a preference for the default user.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef bool Auth_PrefManager::deleteDefaultPref() /funcdef paramdef string $pref_id /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::clearCache
Auth_PrefManager::deletePref
Auth_PrefManager


Deletes a preference for the specified user.

Auth_PrefManager::deleteDefaultPref
Auth_PrefManager::getDefaultPref
Auth_PrefManager
PHP Manual

Auth_PrefManager::deletePref()

(No version information available, might be only in CVS)

— Deletes a preference for the specified user.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef bool Auth_PrefManager::deletePref() /funcdef paramdef string $user_id /paramdef paramdef string $pref_id /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::deleteDefaultPref
Auth_PrefManager::getDefaultPref
Auth_PrefManager


Retrieves a default value.

Auth_PrefManager::deletePref
Auth_PrefManager::getPref
Auth_PrefManager
PHP Manual

Auth_PrefManager::getDefaultPref()

(No version information available, might be only in CVS)

— Retrieves a default value.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef mixed Auth_PrefManager::getDefaultPref() /funcdef paramdef string $pref_id /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::deletePref
Auth_PrefManager::getPref
Auth_PrefManager


Get a preference.

Auth_PrefManager::getDefaultPref
Auth_PrefManager::setDefaultPref
Auth_PrefManager
PHP Manual

Auth_PrefManager::getPref()

(No version information available, might be only in CVS)

— Get a preference.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef mixed Auth_PrefManager::getPref() /funcdef paramdef string $user_id /paramdef paramdef string $pref_id /paramdef paramdef bool $showDefaults = TRUE /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::getDefaultPref
Auth_PrefManager::setDefaultPref
Auth_PrefManager


Set the default value for a preference.

Auth_PrefManager::getPref
Auth_PrefManager::setPref
Auth_PrefManager
PHP Manual

Auth_PrefManager::setDefaultPref()

(No version information available, might be only in CVS)

— Set the default value for a preference.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef bool Auth_PrefManager::setDefaultPref() /funcdef paramdef string $pref_id /paramdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::getPref
Auth_PrefManager::setPref
Auth_PrefManager


Set a preference.

Auth_PrefManager::setDefaultPref
Auth_PrefManager::setReturnDefaults
Auth_PrefManager
PHP Manual

Auth_PrefManager::setPref()

(No version information available, might be only in CVS)

— Set a preference.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef bool Auth_PrefManager::setPref() /funcdef paramdef string $user_id /paramdef paramdef string $pref_id /paramdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::setDefaultPref
Auth_PrefManager::setReturnDefaults
Auth_PrefManager


Set whether to return default values.

Auth_PrefManager::setPref
Auth_PrefManager::useCache
Auth_PrefManager
PHP Manual

Auth_PrefManager::setReturnDefaults()

(No version information available, might be only in CVS)

— Set whether to return default values.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef void Auth_PrefManager::setReturnDefaults() /funcdef paramdef mixed $returnDefaults = TRUE /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager::setPref
Auth_PrefManager::useCache
Auth_PrefManager


Sets whether the cache should be used.

Auth_PrefManager
Auth_RADIUS
Auth_PrefManager
PHP Manual

Auth_PrefManager::useCache()

(No version information available, might be only in CVS)

— Sets whether the cache should be used.

funcsynopsis funcsynopsisinforequire_once '/PrefManager.php';/funcsynopsisinfo funcprototype funcdef void Auth_PrefManager::useCache() /funcdef paramdef bool $use = TRUE /paramdef /funcprototype /funcsynopsis

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.

Auth_PrefManager
Auth_RADIUS
Auth_PrefManager


Auth_RADIUS

Client implementation of RADIUS. This package contains wrapper classes for the » RADIUS PECL extension. Provides RADIUS Authentication (RFC2865) and RADIUS Accounting (RFC2866).

Auth_PrefManager::useCache
Introduction
Authentication


Basic usage of Auth_RADIUS

Auth_RADIUS
LiveUser
Auth_RADIUS
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.2 2008/05/09 13:15:00 saltybeagle 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.2 2008/05/09 13:15:00 saltybeagle 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();

?>

Auth_RADIUS
LiveUser
Auth_RADIUS


LiveUser

Introduction
Introduction
Authentication


LiveUser
Setting it up
LiveUser
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

LiveUser
Setting it up
LiveUser


Making the package and examples work

LiveUser
LiveUser_Admin
LiveUser
PHP Manual

Setting it up

(No version information available, might be only in CVS)

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.
    Warning

    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.

LiveUser
LiveUser_Admin
LiveUser


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

Authentication
Benchmarking
Authentication


Benchmarking

Table of Contents

  • Benchmarking_Benchmark

Provides Packages for Benchmarking and Profiling

LiveUser_Admin
Benchmarking_Benchmark
Packages


Benchmarking_Benchmark

Provides a simple framework for profiling and benchmarking your PHP applications.

Benchmarking
Introduction
Benchmarking


Benchmarking_Benchmark
Benchmark_Timer
Benchmarking_Benchmark
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Benchmarking_Benchmark
Benchmark_Timer
Benchmarking_Benchmark


Introduction
Benchmark_Profiler
Benchmarking_Benchmark
PHP Manual

Benchmark_Timer

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.

Introduction
Benchmark_Profiler
Benchmarking_Benchmark


Benchmark_Timer
Benchmark_Iterate
Benchmarking_Benchmark
PHP Manual

Benchmark_Profiler

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.

Benchmark_Timer
Benchmark_Iterate
Benchmarking_Benchmark


Benchmarking_Benchmark
Caching
Benchmarking_Benchmark
PHP Manual

Benchmark_Iterate

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.

Benchmarking_Benchmark
Caching
Benchmarking_Benchmark


Caching

Table of Contents

  • Cache_Lite

Provides Packages for creating caches

Benchmark_Iterate
Cache_Lite
Packages


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).

Caching
Introduction
Caching


Introduction to Cache_Lite

Cache_Lite
constructor Cache_Lite::Cache_Lite
Cache_Lite
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Cache_Lite
constructor Cache_Lite::Cache_Lite
Cache_Lite


Constructor

Introduction
Cache_Lite::get
Cache_Lite
PHP Manual

constructor Cache_Lite::Cache_Lite()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Cache_Lite::Cache_Lite()/funcdef paramdefarray $options = array(NULL) /paramdef /funcprototype /funcsynopsis

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

Example #1 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);

?>
Introduction
Cache_Lite::get
Cache_Lite


Test if a cache is available and (if yes) return it

constructor Cache_Lite::Cache_Lite
Cache_Lite::save
Cache_Lite
PHP Manual

Cache_Lite::get()

(No version information available, might be only in CVS)

— Test if a cache is available and (if yes) return it

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefstring Cache_Lite::get()/funcdef paramdefstring $id /paramdef paramdefstring $group = 'default' /paramdef paramdefboolean $doNotTestCacheValidity = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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)
    // (...)

}

?>
constructor Cache_Lite::Cache_Lite
Cache_Lite::save
Cache_Lite


Save some data in a cache file

Cache_Lite::get
Cache_Lite::remove
Cache_Lite
PHP Manual

Cache_Lite::save()

(No version information available, might be only in CVS)

— Save some data in a cache file

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefboolean Cache_Lite::save()/funcdef paramdefstring $data /paramdef paramdefstring $id = NULL /paramdef paramdefstring $group = 'default' /paramdef /funcprototype /funcsynopsis

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

Example #1 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);

}

?>
Cache_Lite::get
Cache_Lite::remove
Cache_Lite


Remove a cache file

Cache_Lite::save
Cache_Lite::clean
Cache_Lite
PHP Manual

Cache_Lite::remove()

(No version information available, might be only in CVS)

— Remove a cache file

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefboolean Cache_Lite::remove()/funcdef paramdefstring $id /paramdef paramdefstring $group = 'default' /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Cache_Lite::save
Cache_Lite::clean
Cache_Lite


Clean the cache

Cache_Lite::remove
Cache_Lite::setToDebug
Cache_Lite
PHP Manual

Cache_Lite::clean()

(No version information available, might be only in CVS)

— Clean the cache

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefboolean Cache_Lite::clean()/funcdef paramdef string $group = FALSE /paramdef paramdef string $mode = 'ingroup'; /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Cache_Lite::remove
Cache_Lite::setToDebug
Cache_Lite


Set to debug mode

Cache_Lite::clean
Cache_Lite::setLifeTime
Cache_Lite
PHP Manual

Cache_Lite::setToDebug()

(No version information available, might be only in CVS)

— Set to debug mode

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite::setToDebug()/funcdef paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::clean
Cache_Lite::setLifeTime
Cache_Lite


Set a new life time

Cache_Lite::setToDebug
Cache_Lite::saveMemoryCachingState
Cache_Lite
PHP Manual

Cache_Lite::setLifeTime()

(No version information available, might be only in CVS)

— Set a new life time

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite::setLifeTime()/funcdef paramdefint $newLifeTime /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::setToDebug
Cache_Lite::saveMemoryCachingState
Cache_Lite


Cache_Lite::saveMemoryCachingState

Cache_Lite::setLifeTime
Cache_Lite::getMemoryCachingState
Cache_Lite
PHP Manual

Cache_Lite::saveMemoryCachingState()

(No version information available, might be only in CVS)

—

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite::saveMemoryCachingState()/funcdef paramdefstring $id /paramdef paramdefstring $group = 'default' /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::setLifeTime
Cache_Lite::getMemoryCachingState
Cache_Lite


Cache_Lite::getMemoryCachingState

Cache_Lite::saveMemoryCachingState
Cache_Lite::lastModified
Cache_Lite
PHP Manual

Cache_Lite::getMemoryCachingState()

(No version information available, might be only in CVS)

—

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite::getMemoryCachingState()/funcdef paramdefstring $id /paramdef paramdefstring $group = 'default' /paramdef paramdefbool $doNotTestCacheValidity = FALSE /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::saveMemoryCachingState
Cache_Lite::lastModified
Cache_Lite


Return the cache last modification time

Cache_Lite::getMemoryCachingState
Cache_Lite::raiseError
Cache_Lite
PHP Manual

Cache_Lite::lastModified()

(No version information available, might be only in CVS)

— Return the cache last modification time

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefint Cache_Lite::lastModified()/funcdef paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::getMemoryCachingState
Cache_Lite::raiseError
Cache_Lite


Trigger a PEAR error

Cache_Lite::lastModified
Cache_Lite::extendLife
Cache_Lite
PHP Manual

Cache_Lite::raiseError()

(No version information available, might be only in CVS)

— Trigger a PEAR error

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite::raiseError() /funcdef paramdefstring $msg /paramdef paramdefint $code /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::lastModified
Cache_Lite::extendLife
Cache_Lite


Extend the life of a valid cache file

Cache_Lite::raiseError
constructor Cache_Lite_Output::Cache_Lite_Output
Cache_Lite
PHP Manual

Cache_Lite::extendLife()

(No version information available, might be only in CVS)

— Extend the life of a valid cache file

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite::extendLife()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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);

?>
Cache_Lite::raiseError
constructor Cache_Lite_Output::Cache_Lite_Output
Cache_Lite


Constructor

Cache_Lite::extendLife
Cache_Lite_Output::start
Cache_Lite
PHP Manual

constructor Cache_Lite_Output::Cache_Lite_Output()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/Output.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Cache_Lite_Output::Cache_Lite_Output()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite::extendLife
Cache_Lite_Output::start
Cache_Lite


Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.

constructor Cache_Lite_Output::Cache_Lite_Output
Cache_Lite_Output::end
Cache_Lite
PHP Manual

Cache_Lite_Output::start()

(No version information available, might be only in CVS)

— Test if a cache is available and (if yes) return it to the browser. Else, the output buffering is activated.

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/Output.php'; /funcsynopsisinfo funcprototype funcdefboolean Cache_Lite_Output::start()/funcdef paramdefstring $id /paramdef paramdefstring $group = 'default' /paramdef paramdefboolean $doNotTestCacheValidity = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

}

?>
constructor Cache_Lite_Output::Cache_Lite_Output
Cache_Lite_Output::end
Cache_Lite


Stop the output buffering started by the start() method and store the output to a cache file

Cache_Lite_Output::start
constructor Cache_Lite_Function::Cache_Lite_Function
Cache_Lite
PHP Manual

Cache_Lite_Output::end()

(No version information available, might be only in CVS)

— Stop the output buffering started by the start() method and store the output to a cache file

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/Output.php'; /funcsynopsisinfo funcprototype funcdefvoid Cache_Lite_Output::end()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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

}

?>
Cache_Lite_Output::start
constructor Cache_Lite_Function::Cache_Lite_Function
Cache_Lite


Constructor

Cache_Lite_Output::end
Cache_Lite_Function::call
Cache_Lite
PHP Manual

constructor Cache_Lite_Function::Cache_Lite_Function()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/Function.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Cache_Lite_Function::Cache_Lite_Function()/funcdef paramdefarray $options = array(NULL) /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite_Output::end
Cache_Lite_Function::call
Cache_Lite


Calls a cacheable function or method (or not if there is already a cache for it)

constructor Cache_Lite_Function::Cache_Lite_Function
Cache_Lite_Function::drop
Cache_Lite
PHP Manual

Cache_Lite_Function::call()

(No version information available, might be only in CVS)

— Calls a cacheable function or method (or not if there is already a cache for it)

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/Function.php'; /funcsynopsisinfo funcprototype funcdefmixed Cache_Lite_Function::call()/funcdef paramdefstring$functionName /paramdef paramdefmixed$arg1 /paramdef paramdefmixed$arg2 /paramdef paramdefmixed$arg3 /paramdef paramdefmixed... /paramdef /funcprototype /funcsynopsis

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

Example #1 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

Example #2 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

Example #3 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

Example #4 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.

constructor Cache_Lite_Function::Cache_Lite_Function
Cache_Lite_Function::drop
Cache_Lite


Drop a cache file

Cache_Lite_Function::call
constructor Cache_Lite_File::Cache_Lite_File
Cache_Lite
PHP Manual

Cache_Lite_Function::drop()

(No version information available, might be only in CVS)

— Drop a cache file

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/Function.php'; /funcsynopsisinfo funcprototype funcdefboolean Cache_Lite_Function::drop()/funcdef paramdefstring$functionName /paramdef paramdefmixed$arg1 /paramdef paramdefmixed$arg2 /paramdef paramdefmixed$arg3 /paramdef paramdefmixed... /paramdef /funcprototype /funcsynopsis

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

Example #1 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>";
}

?>
Cache_Lite_Function::call
constructor Cache_Lite_File::Cache_Lite_File
Cache_Lite


Constructor

Cache_Lite_Function::drop
Cache_Lite_File::get
Cache_Lite
PHP Manual

constructor Cache_Lite_File::Cache_Lite_File()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/File.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Cache_Lite_File::Cache_Lite_File()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Cache_Lite_Function::drop
Cache_Lite_File::get
Cache_Lite


Test if a cache is available and (if yes) return it

Cache_Lite
Configuration
Cache_Lite
PHP Manual

Cache_Lite_File::get()

(No version information available, might be only in CVS)

— Test if a cache is available and (if yes) return it

funcsynopsis funcsynopsisinfo require_once 'Cache/Lite/File.php'; /funcsynopsisinfo funcprototype funcdefstring Cache_Lite_File::get()/funcdef paramdefstring $id /paramdef paramdefstring $group = 'default' /paramdef /funcprototype /funcsynopsis

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

Example #1 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)
    // (...)

}

?>
Cache_Lite
Configuration
Cache_Lite


Configuration

Table of Contents

  • Config

Provides Packages for managing configurations

Cache_Lite_File::get
Config
Packages


Config

The Config package provides methods for configuration manipulation.

Configuration
Introduction
Configuration


What Config can do

Config
Editing a configuration
Config
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 An example that will create a new Config_Container

// 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.

Example #2 Reading configuration from an XML file

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.

Config
Editing a configuration
Config


How to manipulate your configuration content

Introduction
Available Containers
Config
PHP Manual

Editing a configuration

(No version information available, might be only in CVS)

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:

Example #1 Create configuration with array

// 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:

Example #2 Create configuration with a file

// 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.

Introduction
Available Containers
Config


Supported formats

Editing a configuration
Config::Config
Config
PHP Manual

Available Containers

(No version information available, might be only in CVS)

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.

Warning

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.

Editing a configuration
Config::Config
Config


constructor

Available Containers
Config::getRoot
Config
PHP Manual

Config::Config()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefobject Config::Config()/funcdef ( void /funcprototype /funcsynopsis

Description

The Config constructor, it creates a config object.

The next thing you should do is getting the root Config_Container object with getRoot() .

Available Containers
Config::getRoot
Config


Return root container for config object

Config::Config
Config::isConfigTypeRegistered
Config
PHP Manual

Config::getRoot()

(No version information available, might be only in CVS)

— Return root container for config object

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefobject &Config::getRoot()/funcdef ( void /funcprototype /funcsynopsis

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

Example #1 Using getRoot()

$config = new Config();
$root =& $config->getRoot();
Config::Config
Config::isConfigTypeRegistered
Config


Returns TRUE if container is registered

Config::getRoot
Config::parseConfig
Config
PHP Manual

Config::isConfigTypeRegistered()

(No version information available, might be only in CVS)

— Returns TRUE if container is registered

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefbool Config::isConfigTypeRegistered()/funcdef paramdefstring $configType /paramdef /funcprototype /funcsynopsis

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.

Config::getRoot
Config::parseConfig
Config


Parse datasource contents

Config::isConfigTypeRegistered
Config::registerConfigType
Config
PHP Manual

Config::parseConfig()

(No version information available, might be only in CVS)

— Parse datasource contents

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefmixed &Config::parseConfig()/funcdef paramdefmixed $datasrc /paramdef paramdefstring $configType /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Using parseConfig()

$config = new Config();
$root =& $config->parseConfig('/path/to/file.php', 'phparray',
                                array('name' => 'conf'));
Config::isConfigTypeRegistered
Config::registerConfigType
Config


Registers a custom Config container

Config::parseConfig
Config::setRoot
Config
PHP Manual

Config::registerConfigType()

(No version information available, might be only in CVS)

— Registers a custom Config container

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefbool Config::registerConfigType()/funcdef paramdefstring $configType /paramdef paramdefarray $configInfo = false /paramdef /funcprototype /funcsynopsis

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:

$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:

$configInfo = array("Config/Container/$configType.php",
                    "Config_Container_$configType"
                   );

Return value

mixed - Returns TRUE on success, PEAR_Error on failure.

Config::parseConfig
Config::setRoot
Config


Set content of root Config_container object

Config::registerConfigType
Config::writeConfig
Config
PHP Manual

Config::setRoot()

(No version information available, might be only in CVS)

— Set content of root Config_container object

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefmixed Config::setRoot()/funcdef paramdefobject &$rootContainer /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setRoot()

$container =& new Config_Container('section', 'conf');

$config = new Config();
$root =& $config->setRoot($container);
Config::registerConfigType
Config::writeConfig
Config


Write container content to datasource

Config::setRoot
Config_Container::Config_Container
Config
PHP Manual

Config::writeConfig()

(No version information available, might be only in CVS)

— Write container content to datasource

funcsynopsis funcsynopsisinfo require_once 'Config.php'; /funcsynopsisinfo funcprototype funcdefmixed Config::writeConfig()/funcdef paramdefmixed $datasrc = NULL /paramdef paramdefstring $configType = NULL /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

Example #1 Using writeConfig()

$config = new Config();
$config->parseConfig(
                       '/path/to/file.php',
               'phparray',
                       array('name' => 'conf')
            );
$config->writeConfig(  '/path/to/file.xml',
                       'xml',
                       array('name' => 'conf')
            );

Config::setRoot
Config_Container::Config_Container
Config


Constructor

Config::writeConfig
Config_Container::addItem
Config
PHP Manual

Config_Container::Config_Container()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdef&Config_Container::Config_Container()/funcdef paramdefstring $type = '' /paramdef paramdefstring $name = '' /paramdef paramdefstring $content = '' /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

Config::writeConfig
Config_Container::addItem
Config


Add item to this item.

Config_Container::Config_Container
Config_Container::countChildren
Config
PHP Manual

Config_Container::addItem()

(No version information available, might be only in CVS)

— Add item to this item.

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobject Config_Container::addItem()/funcdef paramdefobject &$item /paramdef paramdefstring $where = 'bottom' /paramdef paramdefobject $target = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Adding an item using addItem()

$section =& new Config_Container('section', 'conf');
$directive =& new Config_Container('directive', 'user', 'mansion');
$section->addItem($directive);

Example #2 Adding an item using addItem() and a position relative to another item

$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);
Config_Container::Config_Container
Config_Container::countChildren
Config


Count children of container

Config_Container::addItem
Config_Container::createBlank
Config
PHP Manual

Config_Container::countChildren()

(No version information available, might be only in CVS)

— Count children of container

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefint Config_Container::countChildren()/funcdef paramdefstring $type = NULL /paramdef paramdefstring $name = NULL /paramdef /funcprototype /funcsynopsis

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.

Config_Container::addItem
Config_Container::createBlank
Config


Add blank line to item

Config_Container::countChildren
Config_Container::createComment
Config
PHP Manual

Config_Container::createBlank()

(No version information available, might be only in CVS)

— Add blank line to item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobjectConfig_Container::createBlank()/funcdef paramdefmixed $where = 'bottom' /paramdef paramdefmixed $target = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Create a new directive using createBlank()

$section =& new Config_Container('section', 'conf');
$directive =& $section->createDirective('user', 'mansion');
$section->createBlank('before', $directive);
Config_Container::countChildren
Config_Container::createComment
Config


Add comment to item

Config_Container::createBlank
Config_Container::createDirective
Config
PHP Manual

Config_Container::createComment()

(No version information available, might be only in CVS)

— Add comment to item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobjectConfig_Container::createComment()/funcdef paramdefstring $content = '' /paramdef paramdefstring $where = 'bottom' /paramdef paramdefobject $target = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Create a new directive using createComment()

$section =& new Config_Container('section', 'conf');
$section->createComment('Database Configuration');
Config_Container::createBlank
Config_Container::createDirective
Config


Add directive to item

Config_Container::createComment
Config_Container::createItem
Config
PHP Manual

Config_Container::createDirective()

(No version information available, might be only in CVS)

— Add directive to item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobject Config_Container::createDirective()/funcdef paramdefstring $name /paramdef paramdefstring $content /paramdef paramdefmixed $attributes = NULL /paramdef paramdefstring $where = 'bottom' /paramdef paramdefmixed $target = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Create a new directive using createDirective()

$section =& new Config_Container('section', 'conf');
$section->createDirective('user', 'mansion');
Config_Container::createComment
Config_Container::createItem
Config


Create new child for section item

Config_Container::createDirective
Config_Container::createSection
Config
PHP Manual

Config_Container::createItem()

(No version information available, might be only in CVS)

— Create new child for section item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobject &Config_Container::createItem()/funcdef paramdefstring $type /paramdef paramdefmixed $item /paramdef paramdefstring $content /paramdef paramdefarray $attributes = NULL /paramdef paramdefstring $where = 'bottom' /paramdef paramdefobject $target = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Create some new items using createItem()

$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);
Config_Container::createDirective
Config_Container::createSection
Config


Add section to item

Config_Container::createItem
Config_Container::getAttribute
Config
PHP Manual

Config_Container::createSection()

(No version information available, might be only in CVS)

— Add section to item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobjectConfig_Container::createSection()/funcdef paramdefstring $name /paramdef paramdefarray $attributes = NULL /paramdef paramdefstring $where = 'bottom' /paramdef paramdefobject $target = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Create a new section using createSection()

$conf =& new Config_Container('section', 'MAIN');
$dbConf =& $conf->createSection('DB');
$dbConf->createDirective('user', 'mansion');
Config_Container::createItem
Config_Container::getAttribute
Config


Get attribute value of item

Config_Container::createSection
Config_Container::getAttributes
Config
PHP Manual

Config_Container::getAttribute()

(No version information available, might be only in CVS)

— Get attribute value of item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::getAttribute()/funcdef paramdefstring $attribute /paramdef /funcprototype /funcsynopsis

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.

Config_Container::createSection
Config_Container::getAttributes
Config


Get item attributes

Config_Container::getAttribute
Config_Container::getChild
Config
PHP Manual

Config_Container::getAttributes()

(No version information available, might be only in CVS)

— Get item attributes

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefarray Config_Container::getAttributes()/funcdef ( void /funcprototype /funcsynopsis

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

Example #1 Using attribute

$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');

Example #2 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';
?>

Example #3 Attributes are set the usual way with xml type

       <?xml version="1.0" encoding="ISO-8859-1"?>
       <main xml:id="db" language="en">
        <authentication type="mysql" host="localhost">
         test
        </authentication>;
       </main>
Config_Container::getAttribute
Config_Container::getChild
Config


Return child object at specified index.

Config_Container::getAttributes
Config_Container::getContent
Config
PHP Manual

Config_Container::getChild()

(No version information available, might be only in CVS)

— Return child object at specified index.

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::getChild()/funcdef paramdefint $index /paramdef /funcprototype /funcsynopsis

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.

Config_Container::getAttributes
Config_Container::getContent
Config


Get item content

Config_Container::getChild
Config_Container::getItem
Config
PHP Manual

Config_Container::getContent()

(No version information available, might be only in CVS)

— Get item content

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::getContent()/funcdef ( void /funcprototype /funcsynopsis

Description

Accessor method. Returns the item content.

Return value

mixed - item's content

Note

This function can not be called statically.

Config_Container::getChild
Config_Container::getItem
Config


Tries to find specific items

Config_Container::getContent
Config_Container::getItemIndex
Config
PHP Manual

Config_Container::getItem()

(No version information available, might be only in CVS)

— Tries to find specific items

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::getItem()/funcdef paramdefstring $type = NULL /paramdef paramdefstring $name = NULL /paramdef paramdefmixed $content = NULL /paramdef paramdefarray $attributes = NULL /paramdef paramdefint $index = -1 /paramdef /funcprototype /funcsynopsis

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

Example #1 A few examples on how to find items using getItem()

// 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'));
Config_Container::getContent
Config_Container::getItemIndex
Config


Return item index in its parent children array

Config_Container::getItem
Config_Container::getItemPosition
Config
PHP Manual

Config_Container::getItemIndex()

(No version information available, might be only in CVS)

— Return item index in its parent children array

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::getItemIndex()/funcdef ( void /funcprototype /funcsynopsis

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.

Config_Container::getItem
Config_Container::getItemPosition
Config


Return item rank in its parent children array

Config_Container::getItemIndex
Config_Container::getName
Config
PHP Manual

Config_Container::getItemPosition()

(No version information available, might be only in CVS)

— Return item rank in its parent children array

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefint Config_Container::getItemPosition()/funcdef ( void /funcprototype /funcsynopsis

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.

Config_Container::getItemIndex
Config_Container::getName
Config


Get item name

Config_Container::getItemPosition
Config_Container::getParent
Config
PHP Manual

Config_Container::getName()

(No version information available, might be only in CVS)

— Get item name

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefstring Config_Container::getName()/funcdef ( void /funcprototype /funcsynopsis

Description

Return the name of this item.

Return value

string - item's name

Note

This function can not be called statically.

Config_Container::getItemPosition
Config_Container::getParent
Config


Return item parent object

Config_Container::getName
Config_Container::getType
Config
PHP Manual

Config_Container::getParent()

(No version information available, might be only in CVS)

— Return item parent object

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefobject Config_Container::getParent()/funcdef ( void /funcprototype /funcsynopsis

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.

Config_Container::getName
Config_Container::getType
Config


Get item type

Config_Container::getParent
Config_Container::isRoot
Config
PHP Manual

Config_Container::getType()

(No version information available, might be only in CVS)

— Get item type

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefstring Config_Container::getType()/funcdef ( void /funcprototype /funcsynopsis

Description

Gets this item's type.

Return value

string - item type

Note

This function can not be called statically.

Config_Container::getParent
Config_Container::isRoot
Config


Check for root item

Config_Container::getType
Config_Container::removeItem
Config
PHP Manual

Config_Container::isRoot()

(No version information available, might be only in CVS)

— Check for root item

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefbool Config_Container::isRoot()/funcdef ( void /funcprototype /funcsynopsis

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.

Config_Container::getType
Config_Container::removeItem
Config


Deletes an item from the object

Config_Container::isRoot
Config_Container::searchPath
Config
PHP Manual

Config_Container::removeItem()

(No version information available, might be only in CVS)

— Deletes an item from the object

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::removeItem()/funcdef ( void /funcprototype /funcsynopsis

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.

Config_Container::isRoot
Config_Container::searchPath
Config


Finds a node using XPATH like format

Config_Container::removeItem
Config_Container::setAttributes
Config
PHP Manual

Config_Container::searchPath()

(No version information available, might be only in CVS)

— Finds a node using XPATH like format

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefmixed Config_Container::searchPath()/funcdef paramdefmixed $args /paramdef /funcprototype /funcsynopsis

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 #1 Example for searchPath() usage

// 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'));

Example #2 More complex example with attributes for searchPath()

// Let's say our XML configuration looks like this:

// <menu>
//   <group xml:id="company">
//     <page xml:id="news"/>
//     <page xml:id="jobs"/>
//   </group>
//   <group xml:id="projects">
//     <page xml:id="project1"/>
//     <page xml: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'))));
Config_Container::removeItem
Config_Container::setAttributes
Config


Set item attributes

Config_Container::searchPath
Config_Container::setContent
Config
PHP Manual

Config_Container::setAttributes()

(No version information available, might be only in CVS)

— Set item attributes

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdef void Config_Container::setAttributes()/funcdef paramdefarray $attributes /paramdef /funcprototype /funcsynopsis

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.

Config_Container::searchPath
Config_Container::setContent
Config


Set item content

Config_Container::setAttributes
Config_Container::setDirective
Config
PHP Manual

Config_Container::setContent()

(No version information available, might be only in CVS)

— Set item content

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefvoid Config_Container::setContent()/funcdef paramdefmixed $content /paramdef /funcprototype /funcsynopsis

Description

Set this item's content.

Parameter

mixed mixed $content

Item's content

Note

This function can not be called statically.

Config_Container::setAttributes
Config_Container::setDirective
Config


Set child directive content or create new directive

Config_Container::setContent
Config_Container::setName
Config
PHP Manual

Config_Container::setDirective()

(No version information available, might be only in CVS)

— Set child directive content or create new directive

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefvoid Config_Container::setDirective()/funcdef paramdefstring $name /paramdef paramdefmixed $content /paramdef paramdefint $index = -1 /paramdef /funcprototype /funcsynopsis

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.

Config_Container::setContent
Config_Container::setName
Config


Set item name

Config_Container::setDirective
Config_Container::setType
Config
PHP Manual

Config_Container::setName()

(No version information available, might be only in CVS)

— Set item name

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefvoid Config_Container::setName()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

Description

Set this item's name.

Parameter

string $name

Item name

Note

This function can not be called statically.

Config_Container::setDirective
Config_Container::setType
Config


Set item type

Config_Container::setName
Config_Container::toArray
Config
PHP Manual

Config_Container::setType()

(No version information available, might be only in CVS)

— Set item type

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefvoid Config_Container::setType()/funcdef paramdefstring $type /paramdef /funcprototype /funcsynopsis

Description

Set this item's type.

Parameter

string $type

item type

Note

This function can not be called statically.

Config_Container::setName
Config_Container::toArray
Config


Return key/value pair array of container and its children

Config_Container::setType
Config_Container::toString
Config
PHP Manual

Config_Container::toArray()

(No version information available, might be only in CVS)

— Return key/value pair array of container and its children

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefarray Config_Container::toArray()/funcdef ( void /funcprototype /funcsynopsis

Description

This method returns an array representation of the Config tree. The format is

$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

Example #1 Using toArray()()

$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());

Example #2 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"
  }
}
Config_Container::setType
Config_Container::toString
Config


Return string representation

Config_Container::toArray
Config_Container::updateAttributes
Config
PHP Manual

Config_Container::toString()

(No version information available, might be only in CVS)

— Return string representation

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefstring Config_Container::toString()/funcdef paramdefstring $configType /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

Config_Container::toArray
Config_Container::updateAttributes
Config


Update item attributes

Config_Container::toString
Config_Container::writeDatasrc
Config
PHP Manual

Config_Container::updateAttributes()

(No version information available, might be only in CVS)

— Update item attributes

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdef void Config_Container::updateAttributes()/funcdef paramdefarray $attributes /paramdef /funcprototype /funcsynopsis

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.

Config_Container::toString
Config_Container::writeDatasrc
Config


Write item to file

Config
Console
Config
PHP Manual

Config_Container::writeDatasrc()

(No version information available, might be only in CVS)

— Write item to file

funcsynopsis funcsynopsisinfo require_once 'Config/Container.php'; /funcsynopsisinfo funcprototype funcdefboolean Config_Container::writeDatasrc()/funcdef paramdefmixed $datasrc /paramdef paramdefstring $configType /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

Config
Console
Config


Console

Table of Contents

  • Comparison of option parsers
  • Console_Color
  • Console_CommandLine
  • Console_Getopt
  • Console_ProgressBar
  • Console_Table

Provides Packages for PHP-based command-line applications like the pear installer.

Config_Container::writeDatasrc
Comparison of option parsers
Packages


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
Console
Console_Color
Console


Console_Color

Console_Color allows you to easily use ANSI console colors in your application to colorize the output.

Comparison of option parsers
Introduction
Console


How to use Console_Color

Console_Color
Color codes
Console_Color
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

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");
?>
Console_Color
Color codes
Console_Color


Tabular reference

Console_Color
Console_CommandLine
Console_Color
PHP Manual

Color codes

(No version information available, might be only in CVS)

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 % | %%
Console_Color
Console_CommandLine
Console_Color


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.

Color codes
Introduction
Console


introduction to the Console_CommandLine package

Console_CommandLine
Creating the parser
Console_CommandLine
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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 parse() method based on user-supplied command-line values. When 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).

Console_CommandLine
Creating the parser
Console_CommandLine


how to create a parser using PHP code or an XML definition file

Introduction
Populating the parser
Console_CommandLine
PHP Manual

Creating the parser

(No version information available, might be only in CVS)

Creating the parser — how to create a parser using PHP code or an XML definition file

Console_CommandLine constructor

Console_CommandLine constructor 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.

Example #1 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
));
?>

Example #2 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.

Example #3 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>

Example #4 The PHP file

<?php
require_once 'Console/CommandLine.php';
$parser = Console_CommandLine::fromXmlFile('example.xml');
?>

Note: Using and XML string you would have called » Console_CommandLine::fromXmlString() instead of » Console_CommandLine::fromXmlFile() of course.

Introduction
Populating the parser
Console_CommandLine


how to add options, arguments and subcommands to the parser

Creating the parser
Extending Console_CommandLine
Console_CommandLine
PHP Manual

Populating the parser

(No version information available, might be only in CVS)

Populating the parser — how to add options, arguments and subcommands to the parser

Adding options

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')
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)

Example #1 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.

TODO: develop this section

Adding arguments

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
help_name | string | no, if not given it will default to the argument name | the name to display in the argument help line | files

Example #2 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
)

Adding sub-commands

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

TODO: develop this section

Creating the parser
Extending Console_CommandLine
Console_CommandLine


how to customize this package to achieve specific tasks

Populating the parser
Examples
Console_CommandLine
PHP Manual

Extending Console_CommandLine

(No version information available, might be only in CVS)

Extending Console_CommandLine — how to customize this package to achieve specific tasks

Adding custom actions

TODO: write this section

Using a custom renderer

TODO: write this section

Populating the parser
Examples
Console_CommandLine


various code examples

Console_CommandLine
Console_Getopt
Console_CommandLine
PHP Manual

Examples

(No version information available, might be only in CVS)

Examples — various code examples

Basic example

Example #1 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

Example #2 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 name="delete">
        <short_name>-d</short_name>
        <long_name>--delete</long_name>
        <description>delete original files after zip operation</description>
        <action>StoreTrue</action>

    <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>

Example #3 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());
}
?>

Console_CommandLine
Console_Getopt
Console_CommandLine


Console_Getopt

Console_Getopt provides functions for easily fetching and processing command-line arguments.

Examples
Introduction - Options
Console


Defining and processing options

Console_Getopt
Console_Getopt::getopt
Console_Getopt
PHP Manual

Introduction - Options

(No version information available, might be only in CVS)

Introduction - Options — Defining and processing options

Defining options

Getopt() supports two types of options: short options and long options

Example #1 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:
$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:
$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:

$longoptions = array("quite", "lang", "option");
For defining optional parameters, use '=' and '==' like the colon in short options.
$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.

Console_Getopt
Console_Getopt::getopt
Console_Getopt


fetch the command-line options

Introduction - Options
Console_Getopt::readPHPArgv
Console_Getopt
PHP Manual

Console_Getopt::getopt

(No version information available, might be only in CVS)

Console_Getopt::getopt — fetch the command-line options

funcsynopsis funcsynopsisinfo require_once 'Console/Getopt.php'; /funcsynopsisinfo funcprototype funcdefarray getopt()/funcdef paramdefarray $args /paramdef paramdefstring $shortoptions /paramdef paramdefarray $longoptions = NULL /paramdef /funcprototype /funcsynopsis

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.

Introduction - Options
Console_Getopt::readPHPArgv
Console_Getopt


read the predefined $argv array

Console_Getopt
Console_ProgressBar
Console_Getopt
PHP Manual

Console_Getopt::readPHPArgv

(No version information available, might be only in CVS)

Console_Getopt::readPHPArgv — read the predefined $argv array

funcsynopsis funcsynopsisinfo require_once 'Console/Getopt.php'; /funcsynopsisinfo funcprototype funcdefarray readPHPArgv()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using readPHPArgv()

$con  = new Console_Getopt;
$args = $con->readPHPArgv();
array_shift($args);
$options = $con->getopt2($args, $shortopt);

Console_Getopt
Console_ProgressBar
Console_Getopt


Console_ProgressBar

Console_ProgressBar displays a customizable progress bar in the console/terminal.

Example #1 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

    Things to setup

  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.

Example #2 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.

Console_Getopt::readPHPArgv
Console_Table
Console


Console_Table

Console_Table provides methods to build console tables

Console
constructor Console_Table::Console_Table
Console


Constructor

Console_Table
Console_Table::addCol
Console_Table
PHP Manual

constructor Console_Table::Console_Table()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdef void constructor Console_Table::Console_Table() /funcdef paramdef /funcprototype /funcsynopsis

Description

Constructor

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table
Console_Table::addCol
Console_Table


Adds a column to the table

constructor Console_Table::Console_Table
Console_Table::addData
Console_Table
PHP Manual

Console_Table::addCol()

(No version information available, might be only in CVS)

— Adds a column to the table

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid Console_Table::addCol()/funcdef paramdefarray $col_data /paramdef paramdefinteger $col_id /paramdef paramdefinteger $row_id /paramdef /funcprototype /funcsynopsis

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.

constructor Console_Table::Console_Table
Console_Table::addData
Console_Table


Adds data to the table.

Console_Table::addCol
Console_Table::addRow
Console_Table
PHP Manual

Console_Table::addData()

(No version information available, might be only in CVS)

— Adds data to the table.

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid Console_Table::addData()/funcdef paramdefarray $data /paramdef paramdefinteger $col_id /paramdef paramdefinteger $row_id /paramdef /funcprototype /funcsynopsis

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.

Console_Table::addCol
Console_Table::addRow
Console_Table


Adds a row to the table

Console_Table::addData
Console_Table::getTable
Console_Table
PHP Manual

Console_Table::addRow()

(No version information available, might be only in CVS)

— Adds a row to the table

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid Console_Table::addRow()/funcdef paramdefarray $row /paramdef paramdefarray $append = TRUE /paramdef /funcprototype /funcsynopsis

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.

Console_Table::addData
Console_Table::getTable
Console_Table


Returns the table in wonderful ASCII art

Console_Table::addRow
Console_Table::insertRow
Console_Table
PHP Manual

Console_Table::getTable()

(No version information available, might be only in CVS)

— Returns the table in wonderful ASCII art

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdef void Console_Table::getTable() /funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the table in wonderful ASCII art

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table::addRow
Console_Table::insertRow
Console_Table


Inserts a row after a given row number in the table.

Console_Table::getTable
Console_Table::setHeaders
Console_Table
PHP Manual

Console_Table::insertRow()

(No version information available, might be only in CVS)

— Inserts a row after a given row number in the table.

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid Console_Table::insertRow()/funcdef paramdefarray $row /paramdef paramdefinteger $row_id /paramdef /funcprototype /funcsynopsis

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.

Console_Table::getTable
Console_Table::setHeaders
Console_Table


Sets the headers for the columns

Console_Table
Database
Console_Table
PHP Manual

Console_Table::setHeaders()

(No version information available, might be only in CVS)

— Sets the headers for the columns

funcsynopsis funcsynopsisinfo require_once 'Console/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid Console_Table::setHeaders()/funcdef paramdefarray $headers /paramdef /funcprototype /funcsynopsis

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.

Console_Table
Database
Console_Table


Database

Table of Contents

  • DB
  • DB_DataObject
  • DB_DataObject_FormBuilder
  • DB_NestedSet
  • DB_Pager
  • DB_QueryTool
  • DB_Table
  • MDB
  • MDB2
  • MDB_QueryTool
  • MDB2_Schema

Provides database-related Packages

Console_Table::setHeaders
DB
Packages


DB

Warning

This package has been superseded. Please use MDB2 for new projects.

A unified API for accessing SQL databases

Database
Introduction - DSN
Database


The Data Source Name

DB
Introduction - Connect
DB
PHP Manual

Introduction - DSN

(No version information available, might be only in CVS)

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

Warning

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

Example #1 Connect to database through a socket

mysql://user@unix(/path/to/socket)/pear

Example #2 Connect to database on a non standard port

pgsql://user:pass@tcp(localhost:5555)/pear

Example #3 Connect to SQLite on a Unix machine using options

sqlite:////full/unix/path/to/file.db?mode=0666

Example #4 Connect to SQLite on a Windows machine using options

sqlite:///c:/full/windows/path/to/file.db?mode=0666

Example #5 Connect to MySQLi using SSL

mysqli://user:pass@localhost/pear?key=client-key.pem&cert=client-cert.pem

Example #6 Connecting to MS Access sometimes requires admin as the user name

odbc(access)://admin@/datasourcename

Example #7 Connecting to ODBC with a specific cursor

odbc(access)://admin@/datasourcename?cursor=SQL_CUR_USE_ODBC
DB
Introduction - Connect
DB


Connecting and disconnecting a database

Introduction - DSN
Introduction - Query
DB
PHP Manual

Introduction - Connect

(No version information available, might be only in CVS)

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.

Example #1 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();
?>

Example #2 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',
);
?>

Example #3 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());
}
?>

Example #4 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"

Introduction - DSN
Introduction - Query
DB


Performing queries

Introduction - Connect
Introduction - Results
DB
PHP Manual

Introduction - Query

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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());
}
?>

Example #3 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());
}
?>
Introduction - Connect
Introduction - Results
DB


Obtaining data from query results

Introduction - Query
Introduction - Prepare & Execute
DB
PHP Manual

Introduction - Results

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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";
}
?>

Example #3 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.

Example #4 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().

Example #5 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:

Example #6 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();
?>

Example #7 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();
?>

Example #8 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';
?>

Example #9 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.

Introduction - Query
Introduction - Prepare & Execute
DB


Prepare and execute SQL statements

Introduction - Results
Introduction - autoPrepare & autoExecute
DB
PHP Manual

Introduction - Prepare & Execute

(No version information available, might be only in CVS)

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:
$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.

Example #1 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.

Example #2 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);

?>

Warning

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:

Example #3 Passing arrays to execute()

// 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:

Example #4 Using executeMultiple() instead of execute()

// 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

Introduction - Results
Introduction - autoPrepare & autoExecute
DB


Automatically prepare and execute SQL statements

Introduction - Prepare & Execute
Introduction - Portability
DB
PHP Manual

Introduction - autoPrepare & autoExecute

(No version information available, might be only in CVS)

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 xml: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 xml: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.

Warning

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.

Introduction - Prepare & Execute
Introduction - Portability
DB


Database portability features

Introduction - autoPrepare & autoExecute
Introduction - Sequences
DB
PHP Manual

Introduction - Portability

(No version information available, might be only in CVS)

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

Example #1 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());
}
?>

Example #2 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);
?>

Example #3 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);
?>
Introduction - autoPrepare & autoExecute
Introduction - Sequences
DB


Sequences and auto-incrementing

Introduction - Portability
Overview - get* methods
DB
PHP Manual

Introduction - Sequences

(No version information available, might be only in CVS)

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.

Example #1 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

Warning

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()

Introduction - Portability
Overview - get* methods
DB


Comparison of get* methods

Introduction - Sequences
DB
DB
PHP Manual

Overview - get* methods

(No version information available, might be only in CVS)

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"
  }
}

Introduction - Sequences
DB
DB


Main class

Overview - get* methods
DB::connect()
DB
PHP Manual

DB

(No version information available, might be only in CVS)

— Main class

Description

The main DB class is simply a container class with some static methods for creating DB objects.

Overview - get* methods
DB::connect()
DB
PHP Manual


Connects to a database

DB
DB::isError()
DB
PHP Manual

DB::connect()

(No version information available, might be only in CVS)

DB::connect() — Connects to a database

funcsynopsis funcprototype funcdefobject connect()/funcdef paramdef mixed $dsn /paramdef paramdef array $options = array() /paramdef /funcprototype /funcsynopsis

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"

DB
DB::isError()
DB


Determines if a variable is a DB_Error object

DB::connect()
DB_common
DB
PHP Manual

DB::isError()

(No version information available, might be only in CVS)

DB::isError() — Determines if a variable is a DB_Error object

funcsynopsis funcprototype funcdefboolean isError()/funcdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

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

Example #1 Using isError()

<?php
require_once 'DB.php';

$db =& DB::connect('pgsql://usr:pw@localhost/dbnam');
if (PEAR::isError($db)) {
    die($db->getMessage());
}
?>
DB::connect()
DB_common
DB


Interface for database access

DB::isError()
DB_common::affectedRows()
DB
PHP Manual

DB_common

(No version information available, might be only in CVS)

— 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.

DB::isError()
DB_common::affectedRows()
DB


Finds number of rows affected by a data changing query

DB_common
DB_common::autoCommit()
DB
PHP Manual

DB_common::affectedRows()

(No version information available, might be only in CVS)

DB_common::affectedRows() — Finds number of rows affected by a data changing query

funcsynopsis funcprototype funcdefinteger affectedRows()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common
DB_common::autoCommit()
DB


Turns auto-commit on or off

DB_common::affectedRows()
DB_common::autoExecute()
DB
PHP Manual

DB_common::autoCommit()

(No version information available, might be only in CVS)

DB_common::autoCommit() — Turns auto-commit on or off

funcsynopsis funcprototype funcdefmixed autoCommit()/funcdef paramdef boolean $onoff = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::affectedRows()
DB_common::autoExecute()
DB


Prepares and runs an INSERT or UPDATE query based on variables you supply

DB_common::autoCommit()
DB_common::autoPrepare()
DB
PHP Manual

DB_common::autoExecute()

(No version information available, might be only in CVS)

DB_common::autoExecute() — Prepares and runs an INSERT or UPDATE query based on variables you supply

funcsynopsis funcprototype funcdefinteger autoExecute()/funcdef paramdef string $table /paramdef paramdef array $fields_values /paramdef paramdef integer $mode = DB_AUTOQUERY_INSERT /paramdef paramdef string $where = FALSE /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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());
}
?>

Example #2 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()

DB_common::autoCommit()
DB_common::autoPrepare()
DB


Prepares an INSERT or UPDATE statement based on variables you supply

DB_common::autoExecute()
DB_common::commit()
DB
PHP Manual

DB_common::autoPrepare()

(No version information available, might be only in CVS)

DB_common::autoPrepare() — Prepares an INSERT or UPDATE statement based on variables you supply

funcsynopsis funcprototype funcdefresource autoPrepare()/funcdef paramdef string $table /paramdef paramdef array $table_fields /paramdef paramdef integer $mode = DB_AUTOQUERY_INSERT /paramdef paramdef string $where = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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());

}

?>

Example #2 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()

DB_common::autoExecute()
DB_common::commit()
DB


Commits the current transaction

DB_common::autoPrepare()
DB_common::createSequence()
DB
PHP Manual

DB_common::commit()

(No version information available, might be only in CVS)

DB_common::commit() — Commits the current transaction

funcsynopsis funcprototype funcdefmixed commit()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::autoPrepare()
DB_common::createSequence()
DB


Creates a new sequence

DB_common::commit()
DB_common::disconnect()
DB
PHP Manual

DB_common::createSequence()

(No version information available, might be only in CVS)

DB_common::createSequence() — Creates a new sequence

funcsynopsis funcprototype funcdefinteger createSequence()/funcdef paramdef string $seq_name /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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()

DB_common::commit()
DB_common::disconnect()
DB


Disconnects from a database

DB_common::createSequence()
DB_common::dropSequence()
DB
PHP Manual

DB_common::disconnect()

(No version information available, might be only in CVS)

DB_common::disconnect() — Disconnects from a database

funcsynopsis funcprototype funcdefboolean disconnect()/funcdef paramdef /funcprototype /funcsynopsis

Description

Disconnects from a database

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can not be called statically.

Example

Example #1 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"

DB_common::createSequence()
DB_common::dropSequence()
DB


Deletes a sequence

DB_common::disconnect()
DB_common::escapeSimple()
DB
PHP Manual

DB_common::dropSequence()

(No version information available, might be only in CVS)

DB_common::dropSequence() — Deletes a sequence

funcsynopsis funcprototype funcdefinteger dropSequence()/funcdef paramdef string $seqName /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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()

DB_common::disconnect()
DB_common::escapeSimple()
DB


Escapes a string according to the current DBMS's standards

DB_common::dropSequence()
DB_common::execute()
DB
PHP Manual

DB_common::escapeSimple()

(No version information available, might be only in CVS)

DB_common::escapeSimple() — Escapes a string according to the current DBMS's standards

funcsynopsis funcprototype funcdefstring escapeSimple()/funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::dropSequence()
DB_common::execute()
DB


Executes a prepared SQL statement

DB_common::escapeSimple()
DB_common::executeMultiple()
DB
PHP Manual

DB_common::execute()

(No version information available, might be only in CVS)

DB_common::execute() — Executes a prepared SQL statement

funcsynopsis funcprototype funcdefmixed &execute()/funcdef paramdef resource $stmt /paramdef paramdef mixed $data = array() /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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());
}
?>

Example #2 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()

DB_common::escapeSimple()
DB_common::executeMultiple()
DB


Runs a prepared SQL statement for each element of an array

DB_common::execute()
DB_common::freePrepared()
DB
PHP Manual

DB_common::executeMultiple()

(No version information available, might be only in CVS)

DB_common::executeMultiple() — Runs a prepared SQL statement for each element of an array

funcsynopsis funcprototype funcdefinteger executeMultiple()/funcdef paramdef resource $stmt /paramdef paramdef array $data /paramdef /funcprototype /funcsynopsis

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.

Warning

If an error occurs during execution, the function will be stopped. Possible remaining data will be unprocessed.

Warning

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

Example #1 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()

DB_common::execute()
DB_common::freePrepared()
DB


Releases resources associated with a prepared SQL statement

DB_common::executeMultiple()
DB_common::getAll()
DB
PHP Manual

DB_common::freePrepared()

(No version information available, might be only in CVS)

DB_common::freePrepared() — Releases resources associated with a prepared SQL statement

funcsynopsis funcprototype funcdefboolean freePrepared()/funcdef paramdef resource $stmt /paramdef paramdef boolean $free_resource = true /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::executeMultiple()
DB_common::getAll()
DB


Runs a query and returns all the data as an array

DB_common::freePrepared()
DB_common::getAssoc()
DB
PHP Manual

DB_common::getAll()

(No version information available, might be only in CVS)

DB_common::getAll() — Runs a query and returns all the data as an array

funcsynopsis funcprototype funcdefarray &getAll()/funcdef paramdef string $query /paramdef paramdef array $params = array() /paramdef paramdef integer $fetchmode = DB_FETCHMODE_DEFAULT /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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

        )

)

Example #2 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

        )

)

Example #3 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

        )

)

Example #4 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

        )

)

Example #5 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

        )

)

Example #6 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

        )

)

Example #7 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"

DB_common::freePrepared()
DB_common::getAssoc()
DB


Runs a query and returns the data as an array

DB_common::getAll()
DB_common::getCol()
DB
PHP Manual

DB_common::getAssoc()

(No version information available, might be only in CVS)

DB_common::getAssoc() — Runs a query and returns the data as an array

funcsynopsis funcprototype funcdefarray &getAssoc()/funcdef paramdef string $query /paramdef paramdef boolean $force_array = FALSE /paramdef paramdef mixed $params = array() /paramdef paramdef integer $fetchmode = DB_FETCHMODE_DEFAULT /paramdef paramdef boolean $group = FALSE /paramdef /funcprototype /funcsynopsis

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.

Example #1 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

)

Example #2 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

        )

)

Example #3 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

        )

)

Example #4 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

        )

)

Example #5 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

        )

)

Example #6 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

                )

        )

)

Example #7 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

                )

        )

)

Example #8 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

Example #9 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

        )

)

Example #10 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

        )

)

Example #11 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

        )

)

Example #12 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

                )

        )

)

Example #13 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

                )

        )

)

Example #14 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

Example #15 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());

}

?>

Example #16 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"

DB_common::getAll()
DB_common::getCol()
DB


Runs a query and returns the data from a single column

DB_common::getAssoc()
DB_common::getListOf()
DB
PHP Manual

DB_common::getCol()

(No version information available, might be only in CVS)

DB_common::getCol() — Runs a query and returns the data from a single column

funcsynopsis funcprototype funcdefarray &getCol()/funcdef paramdef string $query /paramdef paramdef mixed $col = 0 /paramdef paramdef mixed $params = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 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

)

Example #2 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

)

Example #3 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

)

Example #4 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

)

Example #5 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"

DB_common::getAssoc()
DB_common::getListOf()
DB


Views database system information

DB_common::getCol()
DB_common::getOne()
DB
PHP Manual

DB_common::getListOf()

(No version information available, might be only in CVS)

DB_common::getListOf() — Views database system information

funcsynopsis funcprototype funcdefarray getListOf()/funcdef paramdef string $type /paramdef /funcprototype /funcsynopsis

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

Example #1 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);
?>
DB_common::getCol()
DB_common::getOne()
DB


Runs a query and returns the first column of the first row

DB_common::getListOf()
DB_common::getOption()
DB
PHP Manual

DB_common::getOne()

(No version information available, might be only in CVS)

DB_common::getOne() — Runs a query and returns the first column of the first row

funcsynopsis funcprototype funcdefmixed &getOne()/funcdef paramdef string $query /paramdef paramdef mixed $params = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 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";
?>

Example #2 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";
?>

Example #3 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"

DB_common::getListOf()
DB_common::getOption()
DB


Determines current state of a PEAR DB configuration option

DB_common::getOne()
DB_common::getRow()
DB
PHP Manual

DB_common::getOption()

(No version information available, might be only in CVS)

DB_common::getOption() — Determines current state of a PEAR DB configuration option

funcsynopsis funcprototype funcdefmixed getOption()/funcdef paramdef string $option /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple getOption() example

<?php

// Once you have a valid DB object named $db...

if ($db->getOption('autofree')) {

    // do something...

}

?>
DB_common::getOne()
DB_common::getRow()
DB


Runs a query and returns the first row

DB_common::getOption()
DB_common::limitQuery()
DB
PHP Manual

DB_common::getRow()

(No version information available, might be only in CVS)

DB_common::getRow() — Runs a query and returns the first row

funcsynopsis funcprototype funcdefarray &getRow()/funcdef paramdef string $query /paramdef paramdef array $params = array() /paramdef paramdef integer $fetchmode = DB_FETCHMODE_DEFAULT /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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

)

Example #2 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

)

Example #3 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

)

Example #4 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());

}

?>

Example #5 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"

DB_common::getOption()
DB_common::limitQuery()
DB


Sends a LIMIT query to the database

DB_common::getRow()
DB_common::nextId()
DB
PHP Manual

DB_common::limitQuery()

(No version information available, might be only in CVS)

DB_common::limitQuery() — Sends a LIMIT query to the database

funcsynopsis funcprototype funcdefmixed &limitQuery()/funcdef paramdef string $query /paramdef paramdef integer $from /paramdef paramdef integer $count /paramdef paramdef mixed $params = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::getRow()
DB_common::nextId()
DB


Returns the next number from a sequence

DB_common::limitQuery()
DB_common::nextQueryIsManip()
DB
PHP Manual

DB_common::nextId()

(No version information available, might be only in CVS)

DB_common::nextId() — Returns the next number from a sequence

funcsynopsis funcprototype funcdefinteger nextId()/funcdef paramdef string $seq_name /paramdef paramdef boolean $onDemand = TRUE /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 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()

DB_common::limitQuery()
DB_common::nextQueryIsManip()
DB


Informs the DB driver that the next query is a manipulation query

DB_common::nextId()
DB_common::prepare()
DB
PHP Manual

DB_common::nextQueryIsManip()

(No version information available, might be only in CVS)

DB_common::nextQueryIsManip() — Informs the DB driver that the next query is a manipulation query

funcsynopsis funcprototype funcdefvoid nextQueryIsManip()/funcdef paramdef boolean $manip /paramdef /funcprototype /funcsynopsis

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.

DB_common::nextId()
DB_common::prepare()
DB


Prepares a SQL statement for later execution

DB_common::nextQueryIsManip()
DB_common::provides()
DB
PHP Manual

DB_common::prepare()

(No version information available, might be only in CVS)

DB_common::prepare() — Prepares a SQL statement for later execution

funcsynopsis funcprototype funcdefresource prepare()/funcdef paramdef string $query /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::nextQueryIsManip()
DB_common::provides()
DB


Checks if the DBMS supports a particular feature

DB_common::prepare()
DB_common::query()
DB
PHP Manual

DB_common::provides()

(No version information available, might be only in CVS)

DB_common::provides() — Checks if the DBMS supports a particular feature

funcsynopsis funcprototype funcdefboolean provides()/funcdef paramdef string $feature /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 Using provides()

<?php
// Once you have a valid DB object named $db...
if ($db->provides('pconnect')) {
    echo "Persistent connections are allowed.\n";
}
?>
DB_common::prepare()
DB_common::query()
DB


Sends a query to the database

DB_common::provides()
DB_common::quote()
DB
PHP Manual

DB_common::query()

(No version information available, might be only in CVS)

DB_common::query() — Sends a query to the database

funcsynopsis funcprototype funcdefmixed &query()/funcdef paramdef string $query /paramdef paramdef mixed $params = array() /paramdef /funcprototype /funcsynopsis

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()

DB_common::provides()
DB_common::quote()
DB


DEPRECATED: Quotes a string

DB_common::query()
DB_common::quoteIdentifier()
DB
PHP Manual

DB_common::quote()

(No version information available, might be only in CVS)

DB_common::quote() — DEPRECATED: Quotes a string

funcsynopsis funcprototype funcdefstring quote()/funcdef paramdef string $string /paramdef /funcprototype /funcsynopsis

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.

Warning

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()

DB_common::query()
DB_common::quoteIdentifier()
DB


Formats a string so it can be safely used as an identifier

DB_common::quote()
DB_common::quoteSmart()
DB
PHP Manual

DB_common::quoteIdentifier()

(No version information available, might be only in CVS)

DB_common::quoteIdentifier() — Formats a string so it can be safely used as an identifier

funcsynopsis funcprototype funcdefstring quoteIdentifier()/funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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

Warning

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

Example #1 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()

DB_common::quote()
DB_common::quoteSmart()
DB


Formats input so it can be safely used as a literal

DB_common::quoteIdentifier()
DB_common::rollback()
DB
PHP Manual

DB_common::quoteSmart()

(No version information available, might be only in CVS)

DB_common::quoteSmart() — Formats input so it can be safely used as a literal

funcsynopsis funcprototype funcdefmixed quoteSmart()/funcdef paramdef mixed $in /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::quoteIdentifier()
DB_common::rollback()
DB


Rolls back the current transaction

DB_common::quoteSmart()
DB_common::setFetchMode()
DB
PHP Manual

DB_common::rollback()

(No version information available, might be only in CVS)

DB_common::rollback() — Rolls back the current transaction

funcsynopsis funcprototype funcdefmixed rollback()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_common::quoteSmart()
DB_common::setFetchMode()
DB


Sets the default fetch mode

DB_common::rollback()
DB_common::setOption()
DB
PHP Manual

DB_common::setFetchMode()

(No version information available, might be only in CVS)

DB_common::setFetchMode() — Sets the default fetch mode

funcsynopsis funcprototype funcdefvoid setFetchMode()/funcdef paramdef integer $fetchmode /paramdef paramdef string $object_class = stdClass /paramdef /funcprototype /funcsynopsis

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

Example #1 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

Example #2 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

Example #3 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

Example #4 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

Example #5 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

Example #6 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
DB_common::rollback()
DB_common::setOption()
DB


Sets run-time configuration options for PEAR DB

DB_common::setFetchMode()
DB_common::tableInfo()
DB
PHP Manual

DB_common::setOption()

(No version information available, might be only in CVS)

DB_common::setOption() — Sets run-time configuration options for PEAR DB

funcsynopsis funcprototype funcdefinteger setOption()/funcdef paramdef string $option /paramdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple setOption() example

<?php

// Once you have a valid DB object named $db...

$db->setOption('autofree', true);

?>

Example #2 Portability for lowercasing and trimming

<?php

// Once you have a valid DB object named $db...

$db->setOption('portability',

    DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);

?>

Example #3 All portability options except trimming

<?php

// Once you have a valid DB object named $db...

$db->setOption('portability',

    DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);

?>
DB_common::setFetchMode()
DB_common::tableInfo()
DB


Gets info about columns in a table or a query result

DB_common::setOption()
DB_result
DB
PHP Manual

DB_common::tableInfo()

(No version information available, might be only in CVS)

DB_common::tableInfo() — Gets info about columns in a table or a query result

funcsynopsis funcprototype funcdefarray tableInfo()/funcdef paramdef mixed $result /paramdef paramdef integer $mode = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Finding information about a table

<?php
// Once you have a valid DB object named $db...
$info = $db->tableInfo('tablename');
print_r($info);
?>

Example #2 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);
?>

Warning

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);
?>

DB_common::setOption()
DB_result
DB


DB result set

DB_common::tableInfo()
DB_result::fetchInto()
DB
PHP Manual

DB_result

(No version information available, might be only in CVS)

— 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.

DB_common::tableInfo()
DB_result::fetchInto()
DB


Fetches a row of a result set into a variable

DB_result
DB_result::fetchRow()
DB
PHP Manual

DB_result::fetchInto()

(No version information available, might be only in CVS)

DB_result::fetchInto() — Fetches a row of a result set into a variable

funcsynopsis funcprototype funcdefinteger fetchInto()/funcdef paramdef array &$arr /paramdef paramdef integer $fetchMode = DB_FETCHMODE_DEFAULT /paramdef paramdef integer $rowNum = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_result
DB_result::fetchRow()
DB


Fetches a row from a result set

DB_result::fetchInto()
DB_result::free()
DB
PHP Manual

DB_result::fetchRow()

(No version information available, might be only in CVS)

DB_result::fetchRow() — Fetches a row from a result set

funcsynopsis funcprototype funcdefmixed &fetchRow()/funcdef paramdef integer $fetchmode = DB_DEFAULT_MODE /paramdef paramdef integer $rownum = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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()

DB_result::fetchInto()
DB_result::free()
DB


Releases a result set

DB_result::fetchRow()
DB_result::nextResult()
DB
PHP Manual

DB_result::free()

(No version information available, might be only in CVS)

DB_result::free() — Releases a result set

funcsynopsis funcprototype funcdefboolean free()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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.

DB_result::fetchRow()
DB_result::nextResult()
DB


Gets result sets from multiple queries

DB_result::free()
DB_result::numCols()
DB
PHP Manual

DB_result::nextResult()

(No version information available, might be only in CVS)

DB_result::nextResult() — Gets result sets from multiple queries

funcsynopsis funcprototype funcdefboolean nextResult()/funcdef paramdef /funcprototype /funcsynopsis

Description

Some database backends supports executing more then one query at the same time. With nextResult() you can go through the result sets.

Warning

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.

DB_result::free()
DB_result::numCols()
DB


Gets number of columns in a result set

DB_result::nextResult()
DB_result::numRows()
DB
PHP Manual

DB_result::numCols()

(No version information available, might be only in CVS)

DB_result::numCols() — Gets number of columns in a result set

funcsynopsis funcprototype funcdefinteger numCols()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using numCols()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
echo $res->numCols();
?>

See

numRows(), affectedRows()

DB_result::nextResult()
DB_result::numRows()
DB


Gets number of rows in a result set

DB_result::numCols()
DB_Error
DB
PHP Manual

DB_result::numRows()

(No version information available, might be only in CVS)

DB_result::numRows() — Gets number of rows in a result set

funcsynopsis funcprototype funcdefinteger numRows()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get the number of rows in a result set.

Warning

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

Example #1 Using numRows()

<?php
// Once you have a valid DB object named $db...
$res =& $db->query('SELECT * FROM phptest');
echo $res->numRows();
?>

See

numCols(), affectedRows()

DB_result::numCols()
DB_Error
DB


DB Error object

DB
DB_DataObject
DB
PHP Manual

DB_Error

(No version information available, might be only in CVS)

— 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.

Example #1 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;
}
?>
DB
DB_DataObject
DB


DB_DataObject

SQL Builder and Data Modeling Layer

This chapter describes how to use the DB_DataObject SQL Builder and Data Modeling layer

DB_Error
Introduction
Database


What DB_DataObject can do

DB_DataObject
Configuration Options
DB_DataObject
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — What DB_DataObject can do

Introduction

Warning

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.

Example #1 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 xml: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.

Example #2 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 xml: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.

Example #3 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?

Example #4 At last some real DataObject Code..

// 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.

Example #5 In the above example, this query would be performed.

SELECT * FROM person WHERE xml:id=12;
SELECT * FROM person WHERE friend=12;

Example #6 To make a change to the Database you would just change the value of the objects variables and call the update method.

$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.

DB_DataObject
Configuration Options
DB_DataObject


Setting the defaults for database access

Introduction
Auto Building and Database Schema
DB_DataObject
PHP Manual

Configuration Options

(No version information available, might be only in CVS)

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)

Example #1 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)

Example #2 Setting the default options

$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.

Example #3 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

Example #4 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.

Example #5 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

Example #6 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

Example #7 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.

Introduction
Auto Building and Database Schema
DB_DataObject


creating the base Classes and Database schema

Configuration Options
DB_DataObject::factory()
DB_DataObject
PHP Manual

Auto Building and Database Schema

(No version information available, might be only in CVS)

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.

Example #1 an generated extended class

/*
* 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.

Example #2 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 tables() 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.

Example #3 A Hand Coded extended class

/*
* 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');
    }

}

Configuration Options
DB_DataObject::factory()
DB_DataObject


Autoload and instantate class based on table name.

Auto Building and Database Schema
->get()
DB_DataObject
PHP Manual

DB_DataObject::factory()

(No version information available, might be only in CVS)

DB_DataObject::factory() — Autoload and instantate class based on table name.

funcsynopsis funcprototype funcdefmixed DB_DataObject::factory()/funcdef paramdef string $table /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple fetch of data based on Primary Key

// 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();

    }
}
Auto Building and Database Schema
->get()
DB_DataObject


Simple Get (Select) request

DB_DataObject::factory()
DB_DataObject::staticGet()
DB_DataObject
PHP Manual

->get()

(No version information available, might be only in CVS)

->get() — Simple Get (Select) request

funcsynopsis funcprototype funcdefint $DB_DataObject->get()/funcdef paramdef mixed Key or Value /paramdef paramdef mixed value /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple fetch of data based on Primary Key

$person = new DataObjects_Person;
$person->get(12);
print_r($person);

Example #2 Resulting SQL

SELECT * FROM person WHERE xml:id=12

Example #3 Simple fetch of data based on Key and Value

$person = new DataObjects_Person;
$person->get('email','test@example.com');
print_r($person);

Example #4 Resulting SQL

SELECT * FROM person WHERE email='test@example.com'

Example #5 Results of example code

Object (DataObjects_Person) =>
    [N] => 1
    [id] => 12
    [group] => 5
    [has_glasses] => 1
    [name] => 'fred blogs'
    [password] => '**testing'
    [email] => 'test@example.com'
DB_DataObject::factory()
DB_DataObject::staticGet()
DB_DataObject


Simple Get (Select) request, abbreviated and Autoload.

->get()
{Child Class}::staticGet()
DB_DataObject
PHP Manual

DB_DataObject::staticGet()

(No version information available, might be only in CVS)

DB_DataObject::staticGet() — Simple Get (Select) request, abbreviated and Autoload.

funcsynopsis funcprototype funcdefmixed DB_DataObject::staticGet()/funcdef paramdef string $class /paramdef paramdef mixed $key or $value /paramdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

Description

Warning

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

Example #1 Simple fetch of data based on Primary Key

$person = DB_DataObject::staticGet('DataObjects_Person',12);
print_r($person);
->get()
{Child Class}::staticGet()
DB_DataObject


Simple Get (Select) request, abbreviated (autogenerated)

DB_DataObject::staticGet()
->find()
DB_DataObject
PHP Manual

{Child Class}::staticGet()

(No version information available, might be only in CVS)

{Child Class}::staticGet() — Simple Get (Select) request, abbreviated (autogenerated)

funcsynopsis funcprototype funcdefobject {Child Class}::staticGet()/funcdef paramdef mixed $key or $value /paramdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

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)

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

Example #1 Simple fetch of data based on Primary Key

$person = DataObjects_Person::staticGet(12);
print_r($person);
DB_DataObject::staticGet()
->find()
DB_DataObject


find results

{Child Class}::staticGet()
->fetch()
DB_DataObject
PHP Manual

->find()

(No version information available, might be only in CVS)

->find() — find results

funcsynopsis funcprototype funcdefint $DB_DataObject->find()/funcdef paramdef boolean $autoFetch /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple find() of data based on Object Vars

$person = new DataObjects_Person;
$person->hair = 'red';
$person->has_glasses = 1;
$number_of_rows = $person->find();

Example #2 Resulting SQL

SELECT * FROM person WHERE hair='red' and has_glasses = 1
{Child Class}::staticGet()
->fetch()
DB_DataObject


fetch next row

->find()
->count()
DB_DataObject
PHP Manual

->fetch()

(No version information available, might be only in CVS)

->fetch() — fetch next row

funcsynopsis funcprototype funcdefboolean $DB_DataObject->fetch()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Simple find and fetch of data based on object Vars

$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>";
}

Example #2 Overriding fetch to add extra data.

function fetch() {

  $ret = parent::fetch();
  if ($ret === false) {
      return false;
  }
  $this->dateFormated = date('d/M/Y', $this->date);
  return true;
}
->find()
->count()
DB_DataObject


Perform a select count() request

->fetch()
->insert()
DB_DataObject
PHP Manual

->count()

(No version information available, might be only in CVS)

->count() — Perform a select count() request

funcsynopsis funcprototype funcdefint $DB_DataObject->count()/funcdef paramdefstring|boolean $countWhat|$whereAddOnly /paramdef paramdefboolean $whereAddOnly /paramdef /funcprototype /funcsynopsis

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

Example #1 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";

?>

Example #2 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%';
->fetch()
->insert()
DB_DataObject


Insert current objects variables into database

->count()
->update()
DB_DataObject
PHP Manual

->insert()

(No version information available, might be only in CVS)

->insert() — Insert current objects variables into database

funcsynopsis funcprototype funcdefmixed $DB_DataObject->insert()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Simple insert

$person = new DataObjects_Person;
$person->name='fred';
$id = $person->insert();

Example #2 Resulting SQL

INSERT INTO person (name) VALUES ('fred');
->count()
->update()
DB_DataObject


Update objects variables into database

->insert()
->delete()
DB_DataObject
PHP Manual

->update()

(No version information available, might be only in CVS)

->update() — Update objects variables into database

funcsynopsis funcprototype funcdefint $DB_DataObject->update()/funcdef paramdef dataobject|boolean $original|$useWhere /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple fetch and update

$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);

Example #2 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

Example #3 Simple fetch and update

$person = new DataObjects_Person;
$person->removed=1;
$person->whereAdd('age > 21');
$person->update();

Example #4 Resulting SQL

SELECT * FROM person WHERE id = 12;
UPDATE person SET removed=1 WHERE age > 21
->insert()
->delete()
DB_DataObject


Delete items from table

->update()
Selecting Specific data (SELECT)
DB_DataObject
PHP Manual

->delete()

(No version information available, might be only in CVS)

->delete() — Delete items from table

funcsynopsis funcprototype funcdefint $DB_DataObject->delete()/funcdef paramdef boolean $useWhere /paramdef /funcprototype /funcsynopsis

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

Example #1 Simple Delete

$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);

Example #2 Resulting SQL

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 )
->update()
Selecting Specific data (SELECT)
DB_DataObject


Advanced Filters - ::query(), ::SelectAdd(), ::whereAdd(), ::Limit(), ::OrderBy(), ::GroupBy(),

->delete()
->query()
DB_DataObject
PHP Manual

Selecting Specific data (SELECT)

(No version information available, might be only in CVS)

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.

->delete()
->query()
DB_DataObject


send a raw query

Selecting Specific data (SELECT)
->free()
DB_DataObject
PHP Manual

->query()

(No version information available, might be only in CVS)

->query() — send a raw query

funcsynopsis funcprototype funcdefvoid $DB_DataObject->query()/funcdef paramdef string $string /paramdef /funcprototype /funcsynopsis

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 neccessary, 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

Example #1 raw queries on the database

$person = new DataObjects_Person;
$person->query("SELECT * FROM {$person->__table} WHERE id > 12 ORDER BY id");
while ($person->fetch()) {
  echo $person->name;
}
Selecting Specific data (SELECT)
->free()
DB_DataObject


Free resources

->query()
->selectAdd()
DB_DataObject
PHP Manual

->free()

(No version information available, might be only in CVS)

->free() — Free resources

funcsynopsis funcprototype funcdefobject $DB_DataObject->free()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Freeing resources in a loop

<?php

for ($i = 0; i< 10000; $i++) {
    $person = new DataObjects_Person;
    $person->query(' ... do something ... ');
    $person->free();
}

?>
->query()
->selectAdd()
DB_DataObject


Add selected columns

->free()
->whereAdd()
DB_DataObject
PHP Manual

->selectAdd()

(No version information available, might be only in CVS)

->selectAdd() — Add selected columns

funcsynopsis funcprototype funcdef void $DB_DataObject->selectAdd() /funcdef paramdef string $condition /paramdef /funcprototype /funcsynopsis

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

Example #1 Using selectAdd()

$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>";

Example #2 Resulting SQL

SELECT id,name FROM person

SELECT *, DATE_FORMAT(birthday,'%d %m %Y') as birthday_formated  FROM person WHERE xml:id=12
->free()
->whereAdd()
DB_DataObject


Add WHERE statement

->selectAdd()
->escape()
DB_DataObject
PHP Manual

->whereAdd()

(No version information available, might be only in CVS)

->whereAdd() — Add WHERE statement

funcsynopsis funcprototype funcdefvoid $DB_DataObject->whereAdd()/funcdef paramdef string $where /paramdef paramdef string $logic /paramdef /funcprototype /funcsynopsis

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

Example #1 Using whereAdd()

$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 />";
}

Example #2 Resulting SQL

SELECT * FROM person WHERE age > 12 AND age < 30

SELECT * FROM person WHERE age < 12 OR age > 30
->selectAdd()
->escape()
DB_DataObject


Escape a string for use with Like queries

->whereAdd()
->limit()
DB_DataObject
PHP Manual

->escape()

(No version information available, might be only in CVS)

->escape() — Escape a string for use with Like queries

funcsynopsis funcprototype funcdefvoid $DB_DataObject->escape()/funcdef paramdef string $value /paramdef /funcprototype /funcsynopsis

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

Example #1 Escaping a LIKE string

$person = new DataObjects_Person;
$person->whereAdd("name LIKE '%" . $person->escape("o'brian") . "%'");
$person->find();

Example #2 Sample SQL

SELECT * FROM PERSON WHERE name LIKE '%o\'brian%'
->whereAdd()
->limit()
DB_DataObject


Set limit

->escape()
->orderBy()
DB_DataObject
PHP Manual

->limit()

(No version information available, might be only in CVS)

->limit() — Set limit

funcsynopsis funcprototype funcdefvoid $DB_DataObject->limit()/funcdef paramdef int $from /paramdef paramdef int $number /paramdef /funcprototype /funcsynopsis

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

Example #1 Setting the Limit

$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>";
}

Example #2 Resulting SQL

SELECT * FROM person LIMIT 2

SELECT * FROM person LIMIT 2,4
->escape()
->orderBy()
DB_DataObject


Add an order by condition

->limit()
->groupBy()
DB_DataObject
PHP Manual

->orderBy()

(No version information available, might be only in CVS)

->orderBy() — Add an order by condition

funcsynopsis funcprototype funcdefvoid $DB_DataObject->orderBy()/funcdef paramdef string $order /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>

Example #2 Resulting SQL

SELECT * FROM person ORDER BY name, age, eye
->limit()
->groupBy()
DB_DataObject


Add group by condition

->orderBy()
Automatic Table Linking and Joins
DB_DataObject
PHP Manual

->groupBy()

(No version information available, might be only in CVS)

->groupBy() — Add group by condition

funcsynopsis funcprototype funcdefvoid $DB_DataObject->groupBy()/funcdef paramdef string $group /paramdef /funcprototype /funcsynopsis

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

Example #1 Setting the Group by

$person = new DataObjects_Person;
$person->groupBy('name');
$person->groupBy('age, eye');
$person->find();

Example #2 Resulting SQL

SELECT * FROM person GROUP BY name, age, eye
->orderBy()
Automatic Table Linking and Joins
DB_DataObject


Automatic Table Linking - ::getLink(), ::getLinks(), ::joinAdd(), ::selectAs()

->groupBy()
->getLink()
DB_DataObject
PHP Manual

Automatic Table Linking and Joins

(No version information available, might be only in CVS)

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.

Example #1 A simple introduction to links and joins

// 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())

Example #2 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:

Example #3 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):

Example #4 Resulting SQL

SELECT * FROM table_b INNER JOIN table_a ON table_b.field1 = table_a.field1 AND table_b.field2 = table_a.field2

->groupBy()
->getLink()
DB_DataObject


fetch and return a related object

Automatic Table Linking and Joins
->getLinks()
DB_DataObject
PHP Manual

->getLink()

(No version information available, might be only in CVS)

->getLink() — fetch and return a related object

funcsynopsis funcprototype funcdefmixed $DB_DataObject->getLink()/funcdef paramdef string $column /paramdef paramdef string $table /paramdef paramdef string $key /paramdef /funcprototype /funcsynopsis

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

Example #1 Getting the related object

$person = new DataObjects_Person;
$person->get(12);
$group = $person->getLink('group_owner');
echo $group->name;
$group = $person->getLink('colourid','hair');

Example #2 Resulting SQL

SELECT * FROM person WHERE xml:id=12
SELECT * FROM group WHERE xml:id=3
SELECT * FROM hair WHERE xml:id=4
Automatic Table Linking and Joins
->getLinks()
DB_DataObject


load related objects

->getLink()
->selectAs()
DB_DataObject
PHP Manual

->getLinks()

(No version information available, might be only in CVS)

->getLinks() — load related objects

funcsynopsis funcprototype funcdefboolean $DB_DataObject->getLinks()/funcdef paramdef string $variableFormat /paramdef /funcprototype /funcsynopsis

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

    Example #1 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

Example #2 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)   |      |     |         |                |
+----------------------+---------------+------+-----+---------+----------------+

Example #3 Loading all the related objects

$person = new DataObjects_Person;
$person->get(1079);
$person->getLinks();
print_r($person);

Example #4 Resulting SQL

SELECT * FROM person WHERE xml:id=1079
SELECT * FROM convention WHERE xml:id=1

Example #5 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 #6 Example with three tables join

/**
 * 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);

Example #7 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
->getLink()
->selectAs()
DB_DataObject


Build the select component of a query (usually for joins)

->getLinks()
->joinAdd()
DB_DataObject
PHP Manual

->selectAs()

(No version information available, might be only in CVS)

->selectAs() — Build the select component of a query (usually for joins)

funcsynopsis funcprototype funcdefvoid $DB_DataObject->selectAs()/funcdef paramdef object | array $columns_or_object /paramdef paramdef string $format /paramdef paramdef string $table_name /paramdef /funcprototype /funcsynopsis

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

Example #1 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()) {
  ......
}

?>
->getLinks()
->joinAdd()
DB_DataObject


add another dataobject to build a create join query

->selectAs()
->set*() and ->get*()
DB_DataObject
PHP Manual

->joinAdd()

(No version information available, might be only in CVS)

->joinAdd() — add another dataobject to build a create join query

funcsynopsis funcprototype funcdefvoid $DB_DataObject->joinAdd()/funcdef paramdef object $dataobject /paramdef paramdef string $joinType /paramdef paramdef string $joinAs /paramdef paramdef string $joinCol /paramdef /funcprototype /funcsynopsis

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.

    Example #1 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

Example #2 Simple simple Join

// (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
}

Example #3 Resulting SQL

SELECT * FROM image
  LEFT JOIN product_image
    ON (image.id = product_image.image_id)
  WHERE product_image.id = 24

Example #4 More Complex Join query

// 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
}

Example #5 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);
->selectAs()
->set*() and ->get*()
DB_DataObject


Automatic Setters and Getters using overload

->joinAdd()
->setFrom()
DB_DataObject
PHP Manual

->set*() and ->get*()

(No version information available, might be only in CVS)

->set*() and ->get*() — Automatic Setters and Getters using overload

funcsynopsis funcprototype funcdeftrue | string $DB_DataObject->set*()/funcdef paramdefmixed $value /paramdef /funcprototype funcprototype funcdefmixed $DB_DataObject->get*()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Simple find and fetch of data based on Object Vars

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();

Example #2 Resulting Output

       Fred Blogs was born on 1 April 1970
->joinAdd()
->setFrom()
DB_DataObject


Copy items from Array or Object (for form posting)

->set*() and ->get*()
->toArray()
DB_DataObject
PHP Manual

->setFrom()

(No version information available, might be only in CVS)

->setFrom() — Copy items from Array or Object (for form posting)

funcsynopsis funcprototype funcdefboolean $DB_DataObject->setFrom()/funcdef paramdef array or object $from /paramdef paramdef string $format = '%s' /paramdef paramdef bool $skipEmpty = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setFrom()

// 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();
->set*() and ->get*()
->toArray()
DB_DataObject


Get an array of the current result

->setFrom()
->validate()
DB_DataObject
PHP Manual

->toArray()

(No version information available, might be only in CVS)

->toArray() — Get an array of the current result

funcsynopsis funcprototype funcdefarray $DB_DataObject->toArray()/funcdef paramdef string $format = '%s' /paramdef paramdef bool $hideEmpty = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 getting arrays

$person = new DataObjects_Person;
$person->get(2);
print_r($person->toArray());
print_r($person->toArray('user[%s]'));
print_r($person->toArray('user[%s]', true));

Example #2 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
)
->setFrom()
->validate()
DB_DataObject


check object data, and call objects validation methods.

->toArray()
->tableName()
DB_DataObject
PHP Manual

->validate()

(No version information available, might be only in CVS)

->validate() — check object data, and call objects validation methods.

funcsynopsis funcprototype funcdefarray $DB_DataObject->validate()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 validate usage

$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";
    }
  }
}

Example #2 validate methods

/* 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));
->toArray()
->tableName()
DB_DataObject


Get or set the table name of an object

->validate()
->database()
DB_DataObject
PHP Manual

->tableName()

(No version information available, might be only in CVS)

->tableName() — Get or set the table name of an object

funcsynopsis funcprototype funcdefobject $DB_DataObject->tableName()/funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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

Example #1 getting and setting the tablename

$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..!
->validate()
->database()
DB_DataObject


Get or set the database the object uses

->tableName()
->table()
DB_DataObject
PHP Manual

->database()

(No version information available, might be only in CVS)

->database() — Get or set the database the object uses

funcsynopsis funcprototype funcdefobject $DB_DataObject->database()/funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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

Example #1 Getting the database name

$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);
->tableName()
->table()
DB_DataObject


Get or set the table schema

->database()
->keys()
DB_DataObject
PHP Manual

->table()

(No version information available, might be only in CVS)

->table() — Get or set the table schema

funcsynopsis funcprototype funcdefobject $DB_DataObject->table()/funcdef paramdef array $schema /paramdef /funcprototype /funcsynopsis

Description

Without any argument, it returns the table schema that the object deals with. With an array, it will set the table schema for the 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

Example #1 getting the connection

$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..!
->database()
->keys()
DB_DataObject


Get or set the table keys

->table()
->getDatabaseConnection()
DB_DataObject
PHP Manual

->keys()

(No version information available, might be only in CVS)

->keys() — Get or set the table keys

funcsynopsis funcprototype funcdefarray $DB_DataObject->keys()/funcdef paramdef string $keys ... /paramdef /funcprototype /funcsynopsis

Description

Without any argument, it returns the keys used by the object (the generator builds these and guess'es them based on finding things like primary key, unique, or nextval() in the description. Calling it with a value , or mulitple values, sets it for the current instance of the object.

The default keys are is normally stored in the database.ini file described in the Autobuilding section.

Note

This function can not be called statically.

Example

Example #1 getting the connection

$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..!
->table()
->getDatabaseConnection()
DB_DataObject


Get the PEAR Database Object

->keys()
->getDatabaseResult()
DB_DataObject
PHP Manual

->getDatabaseConnection()

(No version information available, might be only in CVS)

->getDatabaseConnection() — Get the PEAR Database Object

funcsynopsis funcprototype funcdefobject $DB_DataObject->getDatabaseConnection()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 getting the connection

$person = new DataObjects_Person;
$db=  &$person->getDatabaseConnection();
echo $db->phptype;

Example #2 Sample Output

1000_monkeys
->keys()
->getDatabaseResult()
DB_DataObject


Get the PEAR Database Result Object

->getDatabaseConnection()
DB_DataObject::debugLevel
DB_DataObject
PHP Manual

->getDatabaseResult()

(No version information available, might be only in CVS)

->getDatabaseResult() — Get the PEAR Database Result Object

funcsynopsis funcprototype funcdefobject $DB_DataObject->getDatabaseResult()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 getting the result object

$person = new DataObjects_Person;
$person->hair = 'green';
$person->selectAdd();
$person->selectAdd('id,name');
$person->find();

$res=  $person->getDatabaseResult();
$quickFormSelect->loadDbResult($res,'id','name');
->getDatabaseConnection()
DB_DataObject::debugLevel
DB_DataObject


set the amount of debugging output

->getDatabaseResult()
->debug()
DB_DataObject
PHP Manual

DB_DataObject::debugLevel

(No version information available, might be only in CVS)

DB_DataObject::debugLevel — set the amount of debugging output

funcsynopsis funcprototype funcdefvoid DB_DataObject::debugLevel()/funcdef paramdef integer $level /paramdef /funcprototype /funcsynopsis

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

Example #1 Using debugLevel()

// 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();
->getDatabaseResult()
->debug()
DB_DataObject


output debug information.

DB_DataObject::debugLevel
DB_DataObject::raiseError
DB_DataObject
PHP Manual

->debug()

(No version information available, might be only in CVS)

->debug() — output debug information.

funcsynopsis funcprototype funcdefvoid $DB_DataObject->debug()/funcdef paramdef string $message /paramdef paramdef string $logPrefix /paramdef paramdef integer $level=1 /paramdef /funcprototype /funcsynopsis

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.

Warning

In production mode, the debugger is disabled

See

DB_DataObject::debugLevel()

Example

Example #1 Setting the debugging level

$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();
DB_DataObject::debugLevel
DB_DataObject::raiseError
DB_DataObject


throw an error

->debug()
Casting - Dates, Blobs and Null
DB_DataObject
PHP Manual

DB_DataObject::raiseError

(No version information available, might be only in CVS)

DB_DataObject::raiseError — throw an error

funcsynopsis funcprototype funcdefobject DB_DataObject::raiseError()/funcdef paramdef int $message /paramdef paramdef resource $type=NULL /paramdef paramdef resource $behaviour=NULL /paramdef /funcprototype /funcsynopsis

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.

->debug()
Casting - Dates, Blobs and Null
DB_DataObject


DB_DataObject_Cast ::date(), ::blob(), ::sql()

DB_DataObject
DB_DataObject_FormBuilder
DB_DataObject
PHP Manual

Casting - Dates, Blobs and Null

(No version information available, might be only in CVS)

Casting - Dates, Blobs and Null — DB_DataObject_Cast ::date(), ::blob(), ::sql()

Dealing with Casting, (everything except strings and numbers)

Warning

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

Example #1 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.)

Example #2 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.

Example #3 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.

Example #4 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();

?>

DB_DataObject
DB_DataObject_FormBuilder
DB_DataObject


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.

Casting - Dates, Blobs and Null
Introduction
Database


A package for building HTML forms from DataObject classes

DB_DataObject_FormBuilder
DB_NestedSet
DB_DataObject_FormBuilder
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

$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();

DB_DataObject_FormBuilder
DB_NestedSet
DB_DataObject_FormBuilder


DB_NestedSet

With this package, one can easily create trees with infinite depth inside a relational database.

Introduction
Introduction
Database


Introduction to DB_NestedSet

DB_NestedSet
DB_NestedSet::addListener
DB_NestedSet
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Creates some root and subnodes

In this example, one rootnode and two subnodes are created, saved to the database and displayed.

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();
DB_NestedSet
DB_NestedSet::addListener
DB_NestedSet


Add an event listener

Introduction
DB_NestedSet::apiVersion
DB_NestedSet
PHP Manual

DB_NestedSet::addListener()

(No version information available, might be only in CVS)

— Add an event listener

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef string DB_NestedSet::addListener() /funcdef paramdef string $event /paramdef paramdef &$listener /paramdef paramdef string $listener /paramdef /funcprototype /funcsynopsis

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

Example #1 Add Listener

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->AddListener("nodeCreate", "listener");
Introduction
DB_NestedSet::apiVersion
DB_NestedSet


apiVersion

DB_NestedSet::addListener
DB_NestedSet::convertTreeModel
DB_NestedSet
PHP Manual

DB_NestedSet::apiVersion()

(No version information available, might be only in CVS)

— apiVersion

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef void DB_NestedSet::apiVersion() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Example #1 Get API-version

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->apiVersion();
DB_NestedSet::addListener
DB_NestedSet::convertTreeModel
DB_NestedSet


Convert a

DB_NestedSet::apiVersion
DB_NestedSet::createLeftNode
DB_NestedSet
PHP Manual

DB_NestedSet::convertTreeModel()

(No version information available, might be only in CVS)

— Convert a <1.3 tree into a 1.3 tree format

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::convertTreeModel() /funcdef paramdef &$orig /paramdef paramdef &$copy /paramdef paramdef integer $_parent = FALSE /paramdef paramdef object $ /paramdef /funcprototype /funcsynopsis

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.

DB_NestedSet::apiVersion
DB_NestedSet::createLeftNode
DB_NestedSet


Creates a node before a given node

DB_NestedSet::convertTreeModel
DB_NestedSet::createRightNode
DB_NestedSet
PHP Manual

DB_NestedSet::createLeftNode()

(No version information available, might be only in CVS)

— Creates a node before a given node

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::createLeftNode() /funcdef paramdef int $id /paramdef paramdef array $values /paramdef paramdef bool $returnID /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

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);
DB_NestedSet::convertTreeModel
DB_NestedSet::createRightNode
DB_NestedSet


Creates a node after a given node

DB_NestedSet::createLeftNode
DB_NestedSet::createRootNode
DB_NestedSet
PHP Manual

DB_NestedSet::createRightNode()

(No version information available, might be only in CVS)

— Creates a node after a given node

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::createRightNode() /funcdef paramdef int $id /paramdef paramdef array $values /paramdef paramdef bool $returnID /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

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);
DB_NestedSet::createLeftNode
DB_NestedSet::createRootNode
DB_NestedSet


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::createRightNode
DB_NestedSet::createSubNode
DB_NestedSet
PHP Manual

DB_NestedSet::createRootNode()

(No version information available, might be only in CVS)

— 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.

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::createRootNode() /funcdef paramdef array $values /paramdef paramdef integer $id = FALSE /paramdef paramdef bool $first = FALSE /paramdef paramdef string $pos = NESE_MOVE_AFTER /paramdef /funcprototype /funcsynopsis

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

Example #1 Create rootnodes

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->createRootNode(array('name' => 'rootnode'), false, true);
DB_NestedSet::createRightNode
DB_NestedSet::createSubNode
DB_NestedSet


Creates a subnode

DB_NestedSet::createRootNode
DB_NestedSet::deleteNode
DB_NestedSet
PHP Manual

DB_NestedSet::createSubNode()

(No version information available, might be only in CVS)

— Creates a subnode

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::createSubNode() /funcdef paramdef integer $id /paramdef paramdef array $values /paramdef /funcprototype /funcsynopsis

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

Example #1 Create subnodes

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"));
DB_NestedSet::createRootNode
DB_NestedSet::deleteNode
DB_NestedSet


Deletes a node

DB_NestedSet::createSubNode
DB_NestedSet::factory
DB_NestedSet
PHP Manual

DB_NestedSet::deleteNode()

(No version information available, might be only in CVS)

— Deletes a node

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::deleteNode() /funcdef paramdef int $id /paramdef /funcprototype /funcsynopsis

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

Example #1 Delete nodes

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->createRootNode(array('name' => 'root-node'), false, true);
    $nestedSet->deleteNode($id);
DB_NestedSet::createSubNode
DB_NestedSet::factory
DB_NestedSet


Handles the returning of a concrete instance of DB_NestedSet based on the driver.

DB_NestedSet::deleteNode
DB_NestedSet::getAllNodes
DB_NestedSet
PHP Manual

DB_NestedSet::factory()

(No version information available, might be only in CVS)

— Handles the returning of a concrete instance of DB_NestedSet based on the driver.

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef object The& DB_NestedSet::factory() /funcdef paramdef string $driver /paramdef paramdef string $dsn /paramdef paramdef array $params = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Factory

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
DB_NestedSet::deleteNode
DB_NestedSet::getAllNodes
DB_NestedSet


Fetch the whole NestedSet

DB_NestedSet::factory
DB_NestedSet::getBranch
DB_NestedSet
PHP Manual

DB_NestedSet::getAllNodes()

(No version information available, might be only in CVS)

— Fetch the whole NestedSet

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getAllNodes() /funcdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get all nodes

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);
DB_NestedSet::factory
DB_NestedSet::getBranch
DB_NestedSet


Fetch the whole branch where a given node id is in

DB_NestedSet::getAllNodes
DB_NestedSet::getChildren
DB_NestedSet
PHP Manual

DB_NestedSet::getBranch()

(No version information available, might be only in CVS)

— Fetch the whole branch where a given node id is in

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getBranch() /funcdef paramdef int $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get Branch

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);
DB_NestedSet::getAllNodes
DB_NestedSet::getChildren
DB_NestedSet


Fetch the children _one level_ after of a node given by id

DB_NestedSet::getBranch
DB_NestedSet::getParent
DB_NestedSet
PHP Manual

DB_NestedSet::getChildren()

(No version information available, might be only in CVS)

— Fetch the children _one level_ after of a node given by id

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getChildren() /funcdef paramdef int $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef bool $forceNorder = FALSE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get Children

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);
DB_NestedSet::getBranch
DB_NestedSet::getParent
DB_NestedSet


Fetch the immediate parent of a node given by id

DB_NestedSet::getChildren
DB_NestedSet::getParents
DB_NestedSet
PHP Manual

DB_NestedSet::getParent()

(No version information available, might be only in CVS)

— Fetch the immediate parent of a node given by id

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getParent() /funcdef paramdef int $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef paramdef $useDB = TRUE /paramdef /funcprototype /funcsynopsis

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

Example #1 Get Parent

Fetch the immediate parent of a node given by id. GetParent will return $parent2 as $data.

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);
DB_NestedSet::getChildren
DB_NestedSet::getParents
DB_NestedSet


Fetch the parents of a node given by id

DB_NestedSet::getParent
DB_NestedSet::getRootNodes
DB_NestedSet
PHP Manual

DB_NestedSet::getParents()

(No version information available, might be only in CVS)

— Fetch the parents of a node given by id

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getParents() /funcdef paramdef int $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get Parents

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);
DB_NestedSet::getParent
DB_NestedSet::getRootNodes
DB_NestedSet


Fetches the first level (the rootnodes) of the NestedSet

DB_NestedSet::getParents
DB_NestedSet::getSiblings
DB_NestedSet
PHP Manual

DB_NestedSet::getRootNodes()

(No version information available, might be only in CVS)

— Fetches the first level (the rootnodes) of the NestedSet

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getRootNodes() /funcdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get Rootnodes

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();
DB_NestedSet::getParents
DB_NestedSet::getSiblings
DB_NestedSet


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::getRootNodes
DB_NestedSet::getSubBranch
DB_NestedSet
PHP Manual

DB_NestedSet::getSiblings()

(No version information available, might be only in CVS)

— 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

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getSiblings() /funcdef paramdef int $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get Siblings

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);
DB_NestedSet::getRootNodes
DB_NestedSet::getSubBranch
DB_NestedSet


Fetch all the children of a node given by id

DB_NestedSet::getSiblings
DB_NestedSet::isParent
DB_NestedSet
PHP Manual

DB_NestedSet::getSubBranch()

(No version information available, might be only in CVS)

— Fetch all the children of a node given by id

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::getSubBranch() /funcdef paramdef string $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Get SubBranch

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);
DB_NestedSet::getSiblings
DB_NestedSet::isParent
DB_NestedSet


See if a given node is a parent of another given node

DB_NestedSet::getSubBranch
DB_NestedSet::moveTree
DB_NestedSet
PHP Manual

DB_NestedSet::isParent()

(No version information available, might be only in CVS)

— See if a given node is a parent of another given node

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::isParent() /funcdef paramdef mixed $parent /paramdef paramdef mixed $child /paramdef /funcprototype /funcsynopsis

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

Example #1 IsParent

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);
DB_NestedSet::getSubBranch
DB_NestedSet::moveTree
DB_NestedSet


Wrapper for node moving and copying

DB_NestedSet::isParent
DB_NestedSet::pickNode
DB_NestedSet
PHP Manual

DB_NestedSet::moveTree()

(No version information available, might be only in CVS)

— Wrapper for node moving and copying

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef int DB_NestedSet::moveTree() /funcdef paramdef int $id /paramdef paramdef $targetid /paramdef paramdef constant $pos /paramdef paramdef bool $copy = FALSE /paramdef paramdef int $target /paramdef /funcprototype /funcsynopsis

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

Example #1 Get SubBranch

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);
DB_NestedSet::isParent
DB_NestedSet::pickNode
DB_NestedSet


Fetch the data of a node with the given id

DB_NestedSet::moveTree
DB_NestedSet::removeListener
DB_NestedSet
PHP Manual

DB_NestedSet::pickNode()

(No version information available, might be only in CVS)

— Fetch the data of a node with the given id

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef mixed DB_NestedSet::pickNode() /funcdef paramdef int $id /paramdef paramdef bool $keepAsArray = FALSE /paramdef paramdef bool $aliasFields = TRUE /paramdef paramdef string $idfield = 'id' /paramdef paramdef array $addSQL = array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Pick Node

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);
DB_NestedSet::moveTree
DB_NestedSet::removeListener
DB_NestedSet


Removes an event listener

DB_NestedSet::pickNode
DB_NestedSet::setAttr
DB_NestedSet
PHP Manual

DB_NestedSet::removeListener()

(No version information available, might be only in CVS)

— Removes an event listener

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::removeListener() /funcdef paramdef string $event /paramdef paramdef string $listenerID /paramdef /funcprototype /funcsynopsis

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

Example #1 Remove Listener

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->AddListener("nodeCreate", "listener");
    $nestedSet->RemoveListener("nodeCreate", "listener");
DB_NestedSet::pickNode
DB_NestedSet::setAttr
DB_NestedSet


Sets an object attribute

DB_NestedSet::removeListener
DB_NestedSet::setDbOption
DB_NestedSet
PHP Manual

DB_NestedSet::setAttr()

(No version information available, might be only in CVS)

— Sets an object attribute

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::setAttr() /funcdef paramdef array $attr /paramdef /funcprototype /funcsynopsis

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

Example #1 Set attributes

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'
        )
    );
DB_NestedSet::removeListener
DB_NestedSet::setDbOption
DB_NestedSet


Sets a db option. Example, setting the sequence table format

DB_NestedSet::setAttr
DB_NestedSet::setsortMode
DB_NestedSet
PHP Manual

DB_NestedSet::setDbOption()

(No version information available, might be only in CVS)

— Sets a db option. Example, setting the sequence table format

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef void DB_NestedSet::setDbOption() /funcdef paramdef $option /paramdef paramdef $val /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

$option

$val

Throws

throws no exceptions thrown

Note

This function can not be called statically.

DB_NestedSet::setAttr
DB_NestedSet::setsortMode
DB_NestedSet


This enables you to set specific options for each output method

DB_NestedSet::setDbOption
DB_NestedSet::testLock
DB_NestedSet
PHP Manual

DB_NestedSet::setsortMode()

(No version information available, might be only in CVS)

— This enables you to set specific options for each output method

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef Current DB_NestedSet::setsortMode() /funcdef paramdef constant $sortMode = FALSE /paramdef /funcprototype /funcsynopsis

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.

DB_NestedSet::setDbOption
DB_NestedSet::testLock
DB_NestedSet


Tests if a database lock is set

DB_NestedSet::setsortMode
DB_NestedSet::triggerEvent
DB_NestedSet
PHP Manual

DB_NestedSet::testLock()

(No version information available, might be only in CVS)

— Tests if a database lock is set

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef void DB_NestedSet::testLock() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Example

Example #1 Test lock

require_once('DB/NestedSet.php');
    $nestedSet =& DB_NestedSet::factory('DB', $dsn, $params);
    $nestedSet->testLock();
DB_NestedSet::setsortMode
DB_NestedSet::triggerEvent
DB_NestedSet


Triggers and event an calls the event listeners

DB_NestedSet::testLock
DB_NestedSet::updateNode
DB_NestedSet
PHP Manual

DB_NestedSet::triggerEvent()

(No version information available, might be only in CVS)

— Triggers and event an calls the event listeners

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::triggerEvent() /funcdef paramdef string $event /paramdef paramdef &$node /paramdef paramdef array $eparams = FALSE /paramdef paramdef object $ /paramdef /funcprototype /funcsynopsis

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

Example #1 Trigger Event

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);
DB_NestedSet::testLock
DB_NestedSet::updateNode
DB_NestedSet


Changes the payload of a node

DB_NestedSet
DB_Pager
DB_NestedSet
PHP Manual

DB_NestedSet::updateNode()

(No version information available, might be only in CVS)

— Changes the payload of a node

funcsynopsis funcsynopsisinforequire_once 'DB/NestedSet.php';/funcsynopsisinfo funcprototype funcdef bool DB_NestedSet::updateNode() /funcdef paramdef int $id /paramdef paramdef array $values /paramdef paramdef $_internal = FALSE /paramdef paramdef bool $_intermal /paramdef /funcprototype /funcsynopsis

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

Example #1 Update nodes

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"));
DB_NestedSet
DB_Pager
DB_NestedSet


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.

Warning

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.

DB_NestedSet::updateNode
DB_QueryTool
Database


DB_QueryTool

Warning

This package has been superseded. Please use MDB_QueryTool for new projects.

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.

DB_Pager
Introduction
Database


An OO-interface for easily retrieving and modifying data in a database

DB_QueryTool
DB_Table
DB_QueryTool
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

DB_QueryTool
DB_Table
DB_QueryTool


DB_Table

An object-oriented interface to a database

Introduction
Introduction
Database


Overview of the DB_Table package.

DB_Table
DB_Table Class Tutorial
DB_Table
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

DB_Table
DB_Table Class Tutorial
DB_Table


Interface to a single table

Introduction
DB_Table Forms Tutorial
DB_Table
PHP Manual

DB_Table Class Tutorial

(No version information available, might be only in CVS)

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.

    Contents

  • 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:

Example #1 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:

Example #2 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.

Example #3 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.

Example #4 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:

Example #5 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.

Example #6 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.

Example #7 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.

Example #8 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":

Example #9 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:

Example #10 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.

Example #11 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.

Example #12 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:

Example #13 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:

Example #14 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:

Example #15 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.

Example #16 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.

Introduction
DB_Table Forms Tutorial
DB_Table


Creating HTML_QuickForm forms

DB_Table Class Tutorial
DB_Table_Database Class Tutorial
DB_Table
PHP Manual

DB_Table Forms Tutorial

(No version information available, might be only in CVS)

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.

Example #1 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()

Example #2 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.

Example #3 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:

Example #4 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:

Example #5 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.

Example #6 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)
        )
    );
}
?>

Example #7 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:

Example #8 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.

Example #9 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.

Example #10 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:

Example #11 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:

Example #12 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);

?>
DB_Table Class Tutorial
DB_Table_Database Class Tutorial
DB_Table


Interface to a relational database

DB_Table Forms Tutorial
DB_Table_Generator Class Tutorial
DB_Table
PHP Manual

DB_Table_Database Class Tutorial

(No version information available, might be only in CVS)

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.

    Contents

  • 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:

Example #1 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 $fetch_mode 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:

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.

DB_Table Forms Tutorial
DB_Table_Generator Class Tutorial
DB_Table


Code generation for an existing database

DB_Table_Database Class Tutorial
DB_Table Data Types
DB_Table
PHP Manual

DB_Table_Generator Class Tutorial

(No version information available, might be only in CVS)

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:

Example #1 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:

Example #2 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.

DB_Table_Database Class Tutorial
DB_Table Data Types
DB_Table


Abstract data types used in DB_Table column definitions

DB_Table
MDB
DB_Table
PHP Manual

DB_Table Data Types

(No version information available, might be only in CVS)

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.

Example #1 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:

Example #2 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.

Example #3 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.

Example #4 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:

Example #5 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.

Example #6 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.

Example #7 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.

Example #8 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)

Example #9 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.

DB_Table
MDB
DB_Table


MDB

A unified API for accessing databases, based on user provided meta data.

DB_Table Data Types
Introduction - DSN
Database


The Data Source Name

MDB
Introduction - Connect
MDB
PHP Manual

Introduction - DSN

(No version information available, might be only in CVS)

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

Example #1 Connect to database through a socket

mysql://user@unix(/path/to/socket)/pear

Example #2 Connect to database on a non standard port

pgsql://user:pass@word@tcp(localhost:5555)/pear

Warning

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.

MDB
Introduction - Connect
MDB


Connecting and disconnecting a database

Introduction - DSN
Introduction - Query
MDB
PHP Manual

Introduction - Connect

(No version information available, might be only in CVS)

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.

Example #1 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();

?>
Introduction - DSN
Introduction - Query
MDB


Performing a query against a database.

Introduction - Connect
Introduction - Fetch
MDB
PHP Manual

Introduction - Query

(No version information available, might be only in CVS)

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

Example #1 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

?>
Introduction - Connect
Introduction - Fetch
MDB


Fetching rows from the query

Introduction - Query
Introduction - Sequences
MDB
PHP Manual

Introduction - Fetch

(No version information available, might be only in CVS)

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.

Example #1 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.

    Example #2 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

    Example #3 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.

Example #4 Per call

while ($row = $db->fetchInto($res, MDB_FETCHMODE_ASSOC)) {

    $id = $row['id'];

}

Example #5 Once per instance

$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.

Example #6 Fetching by number

...

// 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.

Example #7 Freeing

...

$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

$numrows = $db->queryOne('select count(id) from clients');

queryRow() returns the first row and returns it as an array.

$sql = 'select name, address, phone from clients where xml: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.

$all_client_names = $db->queryCol('SELECT name FROM clients');
The above sentence could return for example:
$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.

$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.

    // Number of rows

    echo $db->numRows($res);

  • numCols() : Returns the total number of columns returned from a "SELECT" query.

    // Number of cols

    echo $db->numCols($res);

  • affectedRows() : Returns the number of rows affected by a data manipulation query ("INSERT", "UPDATE" or "DELETE").

    // 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.

    // 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.

Introduction - Query
Introduction - Sequences
MDB


Database sequences

Introduction - Fetch
Introduction - Execute
MDB
PHP Manual

Introduction - Sequences

(No version information available, might be only in CVS)

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.

Example #1 Using a sequence

...

$id = $db->nextId('mySequence');

// Use the ID in your INSERT query

$res = $db->query("INSERT INTO myTable (id,text) VALUES ($id,'foo')");

...

Introduction - Fetch
Introduction - Execute
MDB


Prepare & Execute/ExecuteMultiple

Introduction - Sequences
MDB
MDB
PHP Manual

Introduction - Execute

(No version information available, might be only in CVS)

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:
$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.

Example #1 Inserting data into a datebase

$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.

Example #2 Using executeMultiple() instead of executeQuery()

...
$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.

Introduction - Sequences
MDB
MDB


Main class

Introduction - Execute
MDB::connect()
MDB
PHP Manual

MDB

(No version information available, might be only in CVS)

— Main class

Description

The main MDB class is simply a container class with some static methods for creating MDB objects.

Introduction - Execute
MDB::connect()
MDB
PHP Manual


connects to database

MDB
MDB::isError()
MDB
PHP Manual

MDB::connect()

(No version information available, might be only in CVS)

MDB::connect() — connects to database

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefobject MDB::connect() /funcdef paramdefstring $dsn /paramdef paramdefboolean $options = FALSE /paramdef /funcprototype /funcsynopsis

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()

MDB
MDB::isError()
MDB


checks for an error

MDB::connect()
MDB_Common
MDB
PHP Manual

MDB::isError()

(No version information available, might be only in CVS)

MDB::isError() — checks for an error

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefboolean MDB::isError() /funcdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

MDB::connect()
MDB_Common
MDB


Interface for database access

MDB::isError()
MDB_Common::affectedRows()
MDB
PHP Manual

MDB_Common

(No version information available, might be only in CVS)

— 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.

MDB::isError()
MDB_Common::affectedRows()
MDB


Number of affected rows

MDB_Common
MDB_Common::createSequence()
MDB
PHP Manual

MDB_Common::affectedRows()

(No version information available, might be only in CVS)

MDB_Common::affectedRows() — Number of affected rows

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefinteger affectedRows() /funcdef paramdef /funcprototype /funcsynopsis

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()

MDB_Common
MDB_Common::createSequence()
MDB


create a new sequence

MDB_Common::affectedRows()
MDB_Common::currId()
MDB
PHP Manual

MDB_Common::createSequence()

(No version information available, might be only in CVS)

MDB_Common::createSequence() — create a new sequence

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefinteger createSequence() /funcdef paramdef string $seq_name /paramdef paramdef integer $start /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::affectedRows()
MDB_Common::currId()
MDB


returns the current free id of a sequence

MDB_Common::createSequence()
MDB_Common::disconnect()
MDB
PHP Manual

MDB_Common::currId()

(No version information available, might be only in CVS)

MDB_Common::currId() — returns the current free id of a sequence

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefresource currId() /funcdef paramdefstring $seq_name /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::createSequence()
MDB_Common::disconnect()
MDB


disconnect from a database

MDB_Common::currId()
MDB_Common::dropSequence()
MDB
PHP Manual

MDB_Common::disconnect()

(No version information available, might be only in CVS)

MDB_Common::disconnect() — disconnect from a database

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefboolean MDB::disconnect() /funcdef paramdef /funcprototype /funcsynopsis

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()

MDB_Common::currId()
MDB_Common::dropSequence()
MDB


deletes a sequence

MDB_Common::disconnect()
MDB_Common::execute()
MDB
PHP Manual

MDB_Common::dropSequence()

(No version information available, might be only in CVS)

MDB_Common::dropSequence() — deletes a sequence

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefinteger dropSequence() /funcdef paramdefstring $seqName /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::disconnect()
MDB_Common::execute()
MDB


executes a prepared SQL statement

MDB_Common::dropSequence()
MDB_Common::executeQuery()
MDB
PHP Manual

MDB_Common::execute()

(No version information available, might be only in CVS)

MDB_Common::execute() — executes a prepared SQL statement

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed execute() /funcdef paramdefresource $stmt /paramdef paramdef array $types = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::dropSequence()
MDB_Common::executeQuery()
MDB


executes a prepared SQL statement

MDB_Common::execute()
MDB_Common::executeMultiple()
MDB
PHP Manual

MDB_Common::executeQuery()

(No version information available, might be only in CVS)

MDB_Common::executeQuery() — executes a prepared SQL statement

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed executeQuery() /funcdef paramdefresource $stmt /paramdef paramdef array $types = NULL /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::execute()
MDB_Common::executeMultiple()
MDB


repeated execution of a prepared SQL statement

MDB_Common::executeQuery()
MDB_Common::fetchAll()
MDB
PHP Manual

MDB_Common::executeMultiple()

(No version information available, might be only in CVS)

MDB_Common::executeMultiple() — repeated execution of a prepared SQL statement

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed executeMultiple() /funcdef paramdefresource $stmt /paramdef paramdef array $types = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef paramdefarray $data /paramdef /funcprototype /funcsynopsis

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.

Warning

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()

MDB_Common::executeQuery()
MDB_Common::fetchAll()
MDB


fetch result set as a nested array

MDB_Common::executeMultiple()
MDB_Common::fetchCol()
MDB
PHP Manual

MDB_Common::fetchAll()

(No version information available, might be only in CVS)

MDB_Common::fetchAll() — fetch result set as a nested array

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &fetchAll() /funcdef paramdefresource $result /paramdef paramdefinteger $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef paramdefboolean $rekey = FALSE /paramdef paramdefboolean $force_array = FALSE /paramdef paramdefboolean $group = FALSE /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::executeMultiple()
MDB_Common::fetchCol()
MDB


Fetch a single column

MDB_Common::fetchAll()
MDB_Common::fetchOne()
MDB
PHP Manual

MDB_Common::fetchCol()

(No version information available, might be only in CVS)

MDB_Common::fetchCol() — Fetch a single column

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &fetchCol() /funcdef paramdefresource $result /paramdef paramdef mixed $colnum = 0 /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::fetchAll()
MDB_Common::fetchOne()
MDB


fetch the first column of the first row

MDB_Common::fetchCol()
MDB_Common::fetchRow()
MDB
PHP Manual

MDB_Common::fetchOne()

(No version information available, might be only in CVS)

MDB_Common::fetchOne() — fetch the first column of the first row

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed &fetchOne() /funcdef paramdefresource $result /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::fetchCol()
MDB_Common::fetchRow()
MDB


fetch the first row

MDB_Common::fetchOne()
MDB_Common::fetchInto()
MDB
PHP Manual

MDB_Common::fetchRow()

(No version information available, might be only in CVS)

MDB_Common::fetchRow() — fetch the first row

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdef array &fetchRow() /funcdef paramdefresource $result /paramdef paramdef integer $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef paramdefinteger $rownum = NULL /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::fetchOne()
MDB_Common::fetchInto()
MDB


fetch a row into a variable

MDB_Common::fetchRow()
MDB_Common::freeResult()
MDB
PHP Manual

MDB_Common::fetchInto()

(No version information available, might be only in CVS)

MDB_Common::fetchInto() — fetch a row into a variable

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed fetchInto()/funcdef paramdefresource $result /paramdef paramdefinteger $fetchMode MDB_FETCHMODE_DEFAULT /paramdef paramdefinteger $rownum = NULL /paramdef /funcprototype /funcsynopsis

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

MDB_Common::fetchRow()
MDB_Common::freeResult()
MDB


delete the result set

MDB_Common::fetchInto()
MDB_Common::getAll()
MDB
PHP Manual

MDB_Common::freeResult()

(No version information available, might be only in CVS)

MDB_Common::freeResult() — delete the result set

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefboolean freeResult()/funcdef paramdefresource $result /paramdef /funcprototype /funcsynopsis

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.

MDB_Common::fetchInto()
MDB_Common::getAll()
MDB


Fetch all rows

MDB_Common::freeResult()
MDB_Common::getAssoc()
MDB
PHP Manual

MDB_Common::getAll()

(No version information available, might be only in CVS)

MDB_Common::getAll() — Fetch all rows

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &getAll() /funcdef paramdef string $query /paramdef paramdef array $types = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef paramdef integer $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::freeResult()
MDB_Common::getAssoc()
MDB


fetch result set as associative array

MDB_Common::getAll()
MDB_Common::getCol()
MDB
PHP Manual

MDB_Common::getAssoc()

(No version information available, might be only in CVS)

MDB_Common::getAssoc() — fetch result set as associative array

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &getAssoc() /funcdef paramdef string $query /paramdef paramdef array $types = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef paramdefinteger $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef paramdef boolean $force_array = FALSE /paramdef paramdef boolean $group = FALSE /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::getAll()
MDB_Common::getCol()
MDB


Fetch a single column

MDB_Common::getAssoc()
MDB_Common::getOne()
MDB
PHP Manual

MDB_Common::getCol()

(No version information available, might be only in CVS)

MDB_Common::getCol() — Fetch a single column

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &getCol() /funcdef paramdef string $query /paramdef paramdef string $type = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef paramdef mixed $colnum = 0 /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::getAssoc()
MDB_Common::getOne()
MDB


fetch the first column of the first row

MDB_Common::getCol()
MDB_Common::getRow()
MDB
PHP Manual

MDB_Common::getOne()

(No version information available, might be only in CVS)

MDB_Common::getOne() — fetch the first column of the first row

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed &getOne() /funcdef paramdefstring $query /paramdef paramdef string $type = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::getCol()
MDB_Common::getRow()
MDB


fetch the first row

MDB_Common::getOne()
MDB_Common::getTextValue()
MDB
PHP Manual

MDB_Common::getRow()

(No version information available, might be only in CVS)

MDB_Common::getRow() — fetch the first row

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &getRow() /funcdef paramdefstring $query /paramdef paramdef array $types = NULL /paramdef paramdef array $params = array() /paramdef paramdef array $param_types = NULL /paramdef paramdefinteger $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::getOne()
MDB_Common::getTextValue()
MDB


quotes a string

MDB_Common::getRow()
MDB_Common::limitQuery()
MDB
PHP Manual

MDB_Common::getTextValue()

(No version information available, might be only in CVS)

MDB_Common::getTextValue() — quotes a string

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefstring MDB::getTextValue() /funcdef paramdefstring $string /paramdef /funcprototype /funcsynopsis

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.

MDB_Common::getRow()
MDB_Common::limitQuery()
MDB


send a limited query to the database

MDB_Common::getTextValue()
MDB_Common::nextId()
MDB
PHP Manual

MDB_Common::limitQuery()

(No version information available, might be only in CVS)

MDB_Common::limitQuery() — send a limited query to the database

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed &limitQuery() /funcdef paramdefstring $query /paramdef paramdef array $types /paramdef paramdefinteger $from /paramdef paramdefinteger $count /paramdef /funcprototype /funcsynopsis

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.

Warning

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()

MDB_Common::getTextValue()
MDB_Common::nextId()
MDB


returns the next free id of a sequence

MDB_Common::limitQuery()
MDB_Common::numCols()
MDB
PHP Manual

MDB_Common::nextId()

(No version information available, might be only in CVS)

MDB_Common::nextId() — returns the next free id of a sequence

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefresource nextId() /funcdef paramdefstring $seq_name /paramdef paramdefboolean $onDemand = TRUE /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::limitQuery()
MDB_Common::numCols()
MDB


get number of columns

MDB_Common::nextId()
MDB_Common::numRows()
MDB
PHP Manual

MDB_Common::numCols()

(No version information available, might be only in CVS)

MDB_Common::numCols() — get number of columns

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefinteger numCols() /funcdef paramdefresource $result /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::nextId()
MDB_Common::numRows()
MDB


get number of rows

MDB_Common::numCols()
MDB_Common::prepareQuery()
MDB
PHP Manual

MDB_Common::numRows()

(No version information available, might be only in CVS)

MDB_Common::numRows() — get number of rows

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefinteger numRows()/funcdef paramdefresource $result /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::numCols()
MDB_Common::prepareQuery()
MDB


prepares a SQL statement

MDB_Common::numRows()
MDB_Common::query()
MDB
PHP Manual

MDB_Common::prepareQuery()

(No version information available, might be only in CVS)

MDB_Common::prepareQuery() — prepares a SQL statement

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefresource prepareQuery() /funcdef paramdefstring $query /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::numRows()
MDB_Common::query()
MDB


send a query to the database

MDB_Common::prepareQuery()
MDB_Common::queryAll()
MDB
PHP Manual

MDB_Common::query()

(No version information available, might be only in CVS)

MDB_Common::query() — send a query to the database

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed &query() /funcdef paramdefstring $query /paramdef paramdef array $types /paramdef /funcprototype /funcsynopsis

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.

MDB_Common::prepareQuery()
MDB_Common::queryAll()
MDB


fetch result set as a nested array

MDB_Common::query()
MDB_Common::queryCol()
MDB
PHP Manual

MDB_Common::queryAll()

(No version information available, might be only in CVS)

MDB_Common::queryAll() — fetch result set as a nested array

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &queryAll() /funcdef paramdef string $query /paramdef paramdef array $types = NULL /paramdef paramdefinteger $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef paramdefboolean $rekey = FALSE /paramdef paramdefboolean $force_array = FALSE /paramdef paramdefboolean $group = FALSE /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::query()
MDB_Common::queryCol()
MDB


Fetch a single column

MDB_Common::queryAll()
MDB_Common::queryOne()
MDB
PHP Manual

MDB_Common::queryCol()

(No version information available, might be only in CVS)

MDB_Common::queryCol() — Fetch a single column

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefarray &queryCol() /funcdef paramdef string $query /paramdef paramdef string $type = NULL /paramdef paramdef mixed $colnum = 0 /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::queryAll()
MDB_Common::queryOne()
MDB


fetch the first column of the first row

MDB_Common::queryCol()
MDB_Common::queryRow()
MDB
PHP Manual

MDB_Common::queryOne()

(No version information available, might be only in CVS)

MDB_Common::queryOne() — fetch the first column of the first row

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefmixed &queryOne() /funcdef paramdefstring $query /paramdef paramdef string $type = NULL /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::queryCol()
MDB_Common::queryRow()
MDB


fetch the first row

MDB_Common::queryOne()
MDB_Common::setFetchMode()
MDB
PHP Manual

MDB_Common::queryRow()

(No version information available, might be only in CVS)

MDB_Common::queryRow() — fetch the first row

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdef array &queryRow() /funcdef paramdef string $query /paramdef paramdef array $types = NULL /paramdef paramdef integer $fetchmode = MDB_FETCHMODE_DEFAULT /paramdef paramdefinteger $rownum = NULL /paramdef /funcprototype /funcsynopsis

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()

MDB_Common::queryOne()
MDB_Common::setFetchMode()
MDB


sets the default fetch mode

MDB_Common::queryRow()
MDB_Common::tableInfo()
MDB
PHP Manual

MDB_Common::setFetchMode()

(No version information available, might be only in CVS)

MDB_Common::setFetchMode() — sets the default fetch mode

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefvoid setFetchMode() /funcdef paramdefinteger $fetchmode /paramdef paramdefstring $object_class = NULL /paramdef /funcprototype /funcsynopsis

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.

MDB_Common::queryRow()
MDB_Common::tableInfo()
MDB


get table info from a query

MDB_Common::setFetchMode()
MDB_Error
MDB
PHP Manual

MDB_Common::tableInfo()

(No version information available, might be only in CVS)

MDB_Common::tableInfo() — get table info from a query

funcsynopsis funcsynopsisinfo require_once 'MDB.php'; /funcsynopsisinfo funcprototype funcdefboolean tableInfo()/funcdef paramdefresource $result /paramdef paramdefint $mode = NULL /paramdef /funcprototype /funcsynopsis

Description

Fetch table information from result query.

Return value

Returns an associative array of table and field information.

Warning

This function is currently not documented.

Note

This function can not be called statically.

MDB_Common::setFetchMode()
MDB_Error
MDB


MDB Error object

MDB
MDB2
MDB
PHP Manual

MDB_Error

(No version information available, might be only in CVS)

— 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.

MDB
MDB2
MDB


MDB2

A unified API for accessing databases and constructing SQL in a portable way.

MDB_Error
Introduction
Database


A feature overview

MDB2
DSN
MDB2
PHP Manual

Introduction

(No version information available, might be only in CVS)

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
MDB2
DSN
MDB2


The Data Source Name

Introduction
Connecting
MDB2
PHP Manual

DSN

(No version information available, might be only in CVS)

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

Warning

Please note, that some features may be not supported by all database backends.

Example

Example #1 Connect to database through a socket

mysql://user@unix(/path/to/socket)/pear

Example #2 Connect to database on a non standard port

pgsql://user:pass@tcp(localhost:5555)/pear

Example #3 Connect to SQLite on a Unix machine using options

sqlite:////full/unix/path/to/file.db?mode=0666

Example #4 Connect to SQLite on a Windows machine using options

sqlite:///c:/full/windows/path/to/file.db?mode=0666

Example #5 Connect to MySQLi using SSL

mysqli://user:pass@localhost/pear?key=client-key.pem&cert=client-cert.pem

Example #6 Connect to Oracle using Service name

oci8://username:password@foo.example.com[:port]/?service=service

Example #7 Connect to Oracle using "Easy Connect" syntax

username/password@[//]host[:port][/service_name]
Introduction
Connecting
MDB2


Connecting and disconnecting a database

DSN
Querying
MDB2
PHP Manual

Connecting

(No version information available, might be only in CVS)

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.

Example #1 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();
?>

Example #2 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',
);
?>

Example #3 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());
}
?>

Example #4 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());
}
?>

Example #5 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().

DSN
Querying
MDB2


Performing queries

Connecting
Quoting and escaping
MDB2
PHP Manual

Querying

(No version information available, might be only in CVS)

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)

Example #1 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());
}
?>

» 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)

Example #2 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 in all relevant methods. 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.

Example #3 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);

?>
Connecting
Quoting and escaping
MDB2


Quote values in a suitable format to compose a query.

Querying
Datatypes
MDB2
PHP Manual

Quoting and escaping

(No version information available, might be only in CVS)

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.

Example #1 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:

Example #2 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:

$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 xml: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.

Querying
Datatypes
MDB2


An overview of datatype handling

Quoting and escaping
Results
MDB2
PHP Manual

Datatypes

(No version information available, might be only in CVS)

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)
'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 #1 Example of the length modifier

'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 #2 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 #3 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 #4 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 #5 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 #6 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 #7 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 #8 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 #9 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 #10 Example of large object data types

<?php
'someblob' = array(
    'type' => 'blob',
),
// or
'someclob' = array(
    'type' => 'clob',
),
?>

Putting it all together

Example #11 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.

Quoting and escaping
Results
MDB2


Obtaining data from query results

Datatypes
Prepare & Execute
MDB2
PHP Manual

Results

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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";
}
?>

Example #3 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.

Example #4 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().

Example #5 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).

Example #6 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:

Example #7 » 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';
}
?>

Example #8 » 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();
?>

Example #9 » 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();

?>

Example #10 » 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());

?>

Example #11 » 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));

?>

Example #12 » 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';
}

?>

Example #13 » 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

Example #14 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.

Datatypes
Prepare & Execute
MDB2


Prepare and execute SQL statements

Results
Transactions
MDB2
PHP Manual

Prepare & Execute

(No version information available, might be only in CVS)

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:
$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:
$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. 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.

Example #1 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.

Example #2 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.

Example #3 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.

Example #4 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);
?>

Warning

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:

Example #5 Passing arrays to execute()

// 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:

Example #6 Using executeMultiple() from the Extended Module instead of execute()

// 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 prepared placeholders as well as result sets in all relevant methods. 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().

Example #7 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.

Example #8 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'));

?>
Results
Transactions
MDB2


Performing transactions

Prepare & Execute
Modules
MDB2
PHP Manual

Transactions

(No version information available, might be only in CVS)

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.

Example #1 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();
}

?>
Warning

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.

Example #2 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.

Example #3 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);

?>
Prepare & Execute
Modules
MDB2


Loading and calling modules

Transactions
Manager Module
MDB2
PHP Manual

Modules

(No version information available, might be only in CVS)

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.

Warning

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.

Example #1 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);
?>

Example #2 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');

?>

Example #3 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');

?>

Example #4 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.

Example #5 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();
?>

Example #6 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();
?>
Transactions
Manager Module
MDB2


Module for managing database structure

Modules
Reverse Module
MDB2
PHP Manual

Manager Module

(No version information available, might be only in CVS)

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.

Example #1 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:

Example #2 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

Example #3 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).

Example #4 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.

Example #5 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.

Example #6 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,
);
?>

Example #7 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.

Example #8 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.

Example #9 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.

Example #10 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

Example #11 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.

Example #12 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();
?>

Modules
Reverse Module
MDB2


Module for managing database structure

Manager Module
autoPrepare & autoExecute
MDB2
PHP Manual

Reverse Module

(No version information available, might be only in CVS)

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:

Example #1 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:

Example #2 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:

Example #3 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:
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.

Example #4 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.

Example #5 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.

Manager Module
autoPrepare & autoExecute
MDB2


Automatically prepare and execute SQL statements

Reverse Module
Portability
MDB2
PHP Manual

autoPrepare & autoExecute

(No version information available, might be only in CVS)

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 xml: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 xml: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

Warning

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"

Reverse Module
Portability
MDB2


Database portability features

autoPrepare & autoExecute
Sequences
MDB2
PHP Manual

Portability

(No version information available, might be only in CVS)

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

Example #1 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());
}
?>

Example #2 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);
?>

Example #3 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);
?>
autoPrepare & autoExecute
Sequences
MDB2


Sequences and auto-incrementing

Portability
FAQ
MDB2
PHP Manual

Sequences

(No version information available, might be only in CVS)

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.

Example #1 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

Warning

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.

Example #2 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.

Example #3 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.

Example #4 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()

Portability
FAQ
MDB2


Frequently asked questions

MDB2
MDB_QueryTool
MDB2
PHP Manual

FAQ

(No version information available, might be only in CVS)

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.

MDB2
MDB_QueryTool
MDB2


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.

FAQ
Introduction
Database


An OO-interface for easily retrieving and modifying data in a database

MDB_QueryTool
Object
MDB_QueryTool
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

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:

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);

MDB_QueryTool
Object
MDB_QueryTool


An introduction to the usage of Objects with MDB_QueryTool

Introduction
Quick API reference
MDB_QueryTool
PHP Manual

Object

(No version information available, might be only in CVS)

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.

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.

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.

Introduction
Quick API reference
MDB_QueryTool


A quick overview of the available methods. Please refer to the full API docs for a detailed documentation.

MDB_QueryTool
MDB2_Schema
MDB_QueryTool
PHP Manual

Quick API reference

(No version information available, might be only in CVS)

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:

    $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:

    $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

    setJoin(array(table1, table2), '<where clause1> AND <where clause2>');
    you can also call
    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:

    $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.

MDB_QueryTool
MDB2_Schema
MDB_QueryTool


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.

Database
Introduction
Database


MDB2_Schema
Installation and Usage Example
MDB2_Schema
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

MDB2_Schema
Installation and Usage Example
MDB2_Schema


Installation and example for the usage of MDB2_Schema

Introduction
Get Database Definition
MDB2_Schema
PHP Manual

Installation and Usage Example

(No version information available, might be only in CVS)

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();
?>
Introduction
Get Database Definition
MDB2_Schema


Generating the definition array of a physical database or MDB2 XML

Installation and Usage Example
Dump Database
MDB2_Schema
PHP Manual

Get Database Definition

(No version information available, might be only in CVS)

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.

Installation and Usage Example
Dump Database
MDB2_Schema


Dumping a database to MDB2 XML

Get Database Definition
Create Database
MDB2_Schema
PHP Manual

Dump Database

(No version information available, might be only in CVS)

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.

Get Database Definition
Create Database
MDB2_Schema


Restoring a database from MDB2 XML

Dump Database
Update Database
MDB2_Schema
PHP Manual

Create Database

(No version information available, might be only in CVS)

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();
?>
Dump Database
Update Database
MDB2_Schema


Updating a database against a new schema

MDB2_Schema
Date and Time
MDB2_Schema
PHP Manual

Update Database

(No version information available, might be only in CVS)

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.

MDB2_Schema
Date and Time
MDB2_Schema


Date and Time

Table of Contents

  • Calendar
  • Date
  • Date_Holidays

Provides Packages for working with date and time data

Update Database
Calendar
Packages


Calendar

Calendar Data Structures

This chapter describes how to use PEAR::Calendar

Date and Time
Introduction
Date and Time


What Calendar can do

Calendar
Installing
Calendar
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — What Calendar can do

Introduction

Warning

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.

Example #1 A Simple Example

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.

Calendar
Installing
Calendar


How to install PEAR::Calendar

Introduction
In A Hurry
Calendar
PHP Manual

Installing

(No version information available, might be only in CVS)

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.

Introduction
In A Hurry
Calendar


Just add hot water...

Installing
Package Overview
Calendar
PHP Manual

In A Hurry

(No version information available, might be only in CVS)

In A Hurry — Just add hot water...

In A Hurry

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";

Installing
Package Overview
Calendar


Summary of Calendar Classes

In A Hurry
Method Overview
Calendar
PHP Manual

Package Overview

(No version information available, might be only in CVS)

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

    require_once 'Calendar/Year.php';
    .

  • Calendar_Month - represents a month and can build Calendar_Day objects.

    Include with

    require_once 'Calendar/Month.php';
    .

  • Calendar_Day - represents a day and can build Calendar_Hour objects.

    Include with

    require_once 'Calendar/Day.php';
    .

  • Calendar_Hour - represents a hour and can build Calendar_Minute objects.

    Include with

    require_once 'Calendar/Hour.php';
    .

  • Calendar_Minute - represents a minute and can build Calendar_Second objects.

    Include with

    require_once 'Calendar/Minute.php';
    .

  • Calendar_Second - represents a second but cannot build anything.

    Include with

    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

    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

    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

    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;

    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

    require_once 'Calendar/Decorator/Uri.php';
    .

  • Calendar_Decorator_Textual - helps with obtaining textual month names and weekday names from a calendar object.

    Include with

    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

    require_once 'Calendar/Decorator/Wrapper.php';
    .

In A Hurry
Method Overview
Calendar


Summary of Calendar API

Package Overview
Calendar Decorators
Calendar
PHP Manual

Method Overview

(No version information available, might be only in CVS)

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;

// 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;

// 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;

// 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.

Warning

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;

$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;

$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;

$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;
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    $Validator = & $Day->getValidator();
    while ($Error = $Validator->fetch()) {
        echo $Error->getUnit().' is invalid<br>';
    }
}
or...
$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;

$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.

Package Overview
Calendar Decorators
Calendar


What Calendar_Decorator is for

Method Overview
FAQ
Calendar
PHP Manual

Calendar Decorators

(No version information available, might be only in CVS)

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:

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:

$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:

$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

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 />';
}

Method Overview
FAQ
Calendar


Frequently Asked Questions

Calendar Decorators
Calendar
Calendar
PHP Manual

FAQ

(No version information available, might be only in CVS)

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.

// 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.:

$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;
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:

$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;

$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;

$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:

$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:

$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

Calendar Decorators
Calendar
Calendar


Calendar base class

FAQ
constructor Calendar::Calendar
Calendar
PHP Manual

Calendar

(No version information available, might be only in CVS)

Calendar — Calendar base class

Description

Calendar API.

FAQ
constructor Calendar::Calendar
Calendar
PHP Manual


Constructs the Calendar

Calendar
Calendar::adjust
Calendar
PHP Manual

constructor Calendar::Calendar()

(No version information available, might be only in CVS)

constructor — Constructs the Calendar

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar::Calendar()/funcdef paramdefint $y = 2000 /paramdef paramdefint $m = 1 /paramdef paramdefint $d = 1 /paramdef paramdefint $h = 0 /paramdef paramdefint $i = 0 /paramdef paramdefint $s = 0 /paramdef /funcprototype /funcsynopsis

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.

Calendar
Calendar::adjust
Calendar


Adjusts the date (helper method)

constructor Calendar::Calendar
Calendar::build
Calendar
PHP Manual

Calendar::adjust()

(No version information available, might be only in CVS)

— Adjusts the date (helper method)

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefvoid Calendar::adjust()/funcdef paramdef /funcprototype /funcsynopsis

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.

constructor Calendar::Calendar
Calendar::build
Calendar


Abstract method for building the children of a calendar object.

Calendar::adjust
Calendar::fetch
Calendar
PHP Manual

Calendar::build()

(No version information available, might be only in CVS)

— Abstract method for building the children of a calendar object.

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

Description

Implemented by Calendar subclasses

Parameter

array $sDates

containing Calendar objects to select (optional)

abstract

Note

This function can not be called statically.

Calendar::adjust
Calendar::fetch
Calendar


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::build
Calendar::fetchAll
Calendar
PHP Manual

Calendar::fetch()

(No version information available, might be only in CVS)

— 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.

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefmixed Calendar::fetch()/funcdef paramdef /funcprototype /funcsynopsis

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.

Calendar::build
Calendar::fetchAll
Calendar


Fetches all child from the current collection of children

Calendar::fetch
Calendar::getTimestamp
Calendar
PHP Manual

Calendar::fetchAll()

(No version information available, might be only in CVS)

— Fetches all child from the current collection of children

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefarray Calendar::fetchAll()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar::fetch
Calendar::getTimestamp
Calendar


Returns a timestamp from the current date / time values

Calendar::fetchAll
Calendar::getValidator
Calendar
PHP Manual

Calendar::getTimestamp()

(No version information available, might be only in CVS)

— Returns a timestamp from the current date / time values

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::getTimestamp()/funcdef paramdef /funcprototype /funcsynopsis

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.

Calendar::fetchAll
Calendar::getValidator
Calendar


Returns an instance of Calendar_Validator

Calendar::getTimestamp
Calendar::isSelected
Calendar
PHP Manual

Calendar::getValidator()

(No version information available, might be only in CVS)

— Returns an instance of Calendar_Validator

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdef Calendar_Validator& Calendar::getValidator()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar::getTimestamp
Calendar::isSelected
Calendar


True if the calendar subclass object is selected (e.g. today)

Calendar::getValidator
Calendar::isValid
Calendar
PHP Manual

Calendar::isSelected()

(No version information available, might be only in CVS)

— True if the calendar subclass object is selected (e.g. today)

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar::isSelected()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar::getValidator
Calendar::isValid
Calendar


Determine whether this date is valid

Calendar::isSelected
Calendar::nextDay
Calendar
PHP Manual

Calendar::isValid()

(No version information available, might be only in CVS)

— Determine whether this date is valid

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar::isValid()/funcdef paramdef /funcprototype /funcsynopsis

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.

Calendar::isSelected
Calendar::nextDay
Calendar


Returns the value for the next day

Calendar::isValid
Calendar::nextHour
Calendar
PHP Manual

Calendar::nextDay()

(No version information available, might be only in CVS)

— Returns the value for the next day

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::nextDay()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::isValid
Calendar::nextHour
Calendar


Returns the value for the next hour

Calendar::nextDay
Calendar::nextMinute
Calendar
PHP Manual

Calendar::nextHour()

(No version information available, might be only in CVS)

— Returns the value for the next hour

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::nextHour()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::nextDay
Calendar::nextMinute
Calendar


Returns the value for the next minute

Calendar::nextHour
Calendar::nextMonth
Calendar
PHP Manual

Calendar::nextMinute()

(No version information available, might be only in CVS)

— Returns the value for the next minute

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::nextMinute()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::nextHour
Calendar::nextMonth
Calendar


Returns the value for next month

Calendar::nextMinute
Calendar::nextSecond
Calendar
PHP Manual

Calendar::nextMonth()

(No version information available, might be only in CVS)

— Returns the value for next month

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::nextMonth()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::nextMinute
Calendar::nextSecond
Calendar


Returns the value for the next second

Calendar::nextMonth
Calendar::nextYear
Calendar
PHP Manual

Calendar::nextSecond()

(No version information available, might be only in CVS)

— Returns the value for the next second

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::nextSecond()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::nextMonth
Calendar::nextYear
Calendar


Returns the value for next year

Calendar::nextSecond
Calendar::prevDay
Calendar
PHP Manual

Calendar::nextYear()

(No version information available, might be only in CVS)

— Returns the value for next year

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::nextYear()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::nextSecond
Calendar::prevDay
Calendar


Returns the value for the previous day

Calendar::nextYear
Calendar::prevHour
Calendar
PHP Manual

Calendar::prevDay()

(No version information available, might be only in CVS)

— Returns the value for the previous day

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::prevDay()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::nextYear
Calendar::prevHour
Calendar


Returns the value for the previous hour

Calendar::prevDay
Calendar::prevMinute
Calendar
PHP Manual

Calendar::prevHour()

(No version information available, might be only in CVS)

— Returns the value for the previous hour

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::prevHour()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::prevDay
Calendar::prevMinute
Calendar


Returns the value for the previous minute

Calendar::prevHour
Calendar::prevMonth
Calendar
PHP Manual

Calendar::prevMinute()

(No version information available, might be only in CVS)

— Returns the value for the previous minute

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::prevMinute()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::prevHour
Calendar::prevMonth
Calendar


Returns the value for the previous month

Calendar::prevMinute
Calendar::prevSecond
Calendar
PHP Manual

Calendar::prevMonth()

(No version information available, might be only in CVS)

— Returns the value for the previous month

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::prevMonth()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::prevMinute
Calendar::prevSecond
Calendar


Returns the value for the previous second

Calendar::prevMonth
Calendar::prevYear
Calendar
PHP Manual

Calendar::prevSecond()

(No version information available, might be only in CVS)

— Returns the value for the previous second

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::prevSecond()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::prevMonth
Calendar::prevYear
Calendar


Returns the value for the previous year

Calendar::prevSecond
Calendar::setSelected
Calendar
PHP Manual

Calendar::prevYear()

(No version information available, might be only in CVS)

— Returns the value for the previous year

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::prevYear()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::prevSecond
Calendar::setSelected
Calendar


Defines calendar object as selected (e.g. for today)

Calendar::prevYear
Calendar::setSelection
Calendar
PHP Manual

Calendar::setSelected()

(No version information available, might be only in CVS)

— Defines calendar object as selected (e.g. for today)

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefvoid Calendar::setSelected()/funcdef paramdefboolean $state = TRUE /paramdef /funcprototype /funcsynopsis

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.

Calendar::prevYear
Calendar::setSelection
Calendar


Abstract method for selected data objects called from build

Calendar::setSelected
Calendar::setTimestamp
Calendar
PHP Manual

Calendar::setSelection()

(No version information available, might be only in CVS)

— Abstract method for selected data objects called from build

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar::setSelection()/funcdef paramdefarray $sDates /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

array $sDates

abstract

Note

This function can not be called statically.

Calendar::setSelected
Calendar::setTimestamp
Calendar


Defines the calendar by a Unix timestamp

Calendar::setSelection
Calendar::size
Calendar
PHP Manual

Calendar::setTimestamp()

(No version information available, might be only in CVS)

— Defines the calendar by a Unix timestamp

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefvoid Calendar::setTimestamp()/funcdef paramdefint $ts /paramdef /funcprototype /funcsynopsis

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.

Calendar::setSelection
Calendar::size
Calendar


Get the number Calendar subclass objects stored in the internal collection.

Calendar::setTimestamp
Calendar::thisDay
Calendar
PHP Manual

Calendar::size()

(No version information available, might be only in CVS)

— Get the number Calendar subclass objects stored in the internal collection.

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::size()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar::setTimestamp
Calendar::thisDay
Calendar


Returns the value for this day

Calendar::size
Calendar::thisHour
Calendar
PHP Manual

Calendar::thisDay()

(No version information available, might be only in CVS)

— Returns the value for this day

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::thisDay()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::size
Calendar::thisHour
Calendar


Returns the value for this hour

Calendar::thisDay
Calendar::thisMinute
Calendar
PHP Manual

Calendar::thisHour()

(No version information available, might be only in CVS)

— Returns the value for this hour

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::thisHour()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::thisDay
Calendar::thisMinute
Calendar


Returns the value for this minute

Calendar::thisHour
Calendar::thisMonth
Calendar
PHP Manual

Calendar::thisMinute()

(No version information available, might be only in CVS)

— Returns the value for this minute

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::thisMinute()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::thisHour
Calendar::thisMonth
Calendar


Returns the value for this month

Calendar::thisMinute
Calendar::thisSecond
Calendar
PHP Manual

Calendar::thisMonth()

(No version information available, might be only in CVS)

— Returns the value for this month

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::thisMonth()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::thisMinute
Calendar::thisSecond
Calendar


Returns the value for this second

Calendar::thisMonth
Calendar::thisYear
Calendar
PHP Manual

Calendar::thisSecond()

(No version information available, might be only in CVS)

— Returns the value for this second

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::thisSecond()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::thisMonth
Calendar::thisYear
Calendar


Returns the value for this year

Calendar::thisSecond
Calendar_Year
Calendar
PHP Manual

Calendar::thisYear()

(No version information available, might be only in CVS)

— Returns the value for this year

funcsynopsis funcsynopsisinfo require_once 'Calendar.php'; /funcsynopsisinfo funcprototype funcdefint Calendar::thisYear()/funcdef paramdefstring $format = 'int' /paramdef /funcprototype /funcsynopsis

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.

Calendar::thisSecond
Calendar_Year
Calendar


Calendar_Year API

Calendar::thisYear
constructor Calendar_Year::Calendar_Year
Calendar
PHP Manual

Calendar_Year

(No version information available, might be only in CVS)

Calendar_Year — Calendar_Year API

Description

Calendar_Year API.

Calendar::thisYear
constructor Calendar_Year::Calendar_Year
Calendar


Constructs Calendar_Year

Calendar_Year
Calendar_Year::build
Calendar
PHP Manual

constructor Calendar_Year::Calendar_Year()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Year

funcsynopsis funcsynopsisinfo require_once 'Year.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Year::Calendar_Year()/funcdef paramdefint $y /paramdef /funcprototype /funcsynopsis

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.

Calendar_Year
Calendar_Year::build
Calendar


Builds the Months of the Year.

constructor Calendar_Year::Calendar_Year
Calendar_Month
Calendar
PHP Manual

Calendar_Year::build()

(No version information available, might be only in CVS)

— Builds the Months of the Year.

funcsynopsis funcsynopsisinforequire_once 'Year.php';/funcsynopsisinfo funcprototype funcdefboolean Calendar_Year::build()/funcdef paramdefarray$sDates = array() /paramdef paramdefint$firstDay = NULL /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Year::Calendar_Year
Calendar_Month
Calendar


Calendar_Month API

Calendar_Year::build
constructor Calendar_Month::Calendar_Month
Calendar
PHP Manual

Calendar_Month

(No version information available, might be only in CVS)

Calendar_Month — Calendar_Month API

Description

Calendar_Month API.

Calendar_Year::build
constructor Calendar_Month::Calendar_Month
Calendar


Constructs Calendar_Month

Calendar_Month
Calendar_Month::build
Calendar
PHP Manual

constructor Calendar_Month::Calendar_Month()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Month

funcsynopsis funcsynopsisinfo require_once 'Month.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Month::Calendar_Month()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $firstDay = NULL /paramdef /funcprototype /funcsynopsis

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.

Calendar_Month
Calendar_Month::build
Calendar


Builds Day objects for this Month. Creates as many Calendar_Day objects

constructor Calendar_Month::Calendar_Month
Calendar_Month_Weekdays
Calendar
PHP Manual

Calendar_Month::build()

(No version information available, might be only in CVS)

— Builds Day objects for this Month. Creates as many Calendar_Day objects

funcsynopsis funcsynopsisinfo require_once 'Month.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Month::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Month::Calendar_Month
Calendar_Month_Weekdays
Calendar


Calendar_Month_Weekdays API

Calendar_Month::build
constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays
Calendar
PHP Manual

Calendar_Month_Weekdays

(No version information available, might be only in CVS)

Calendar_Month_Weekdays — Calendar_Month_Weekdays API

Description

Calendar_Month_Weekdays API.

Calendar_Month::build
constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays
Calendar


Constructs Calendar_Month_Weekdays

Calendar_Month_Weekdays
Calendar_Month_Weekdays::build
Calendar
PHP Manual

constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Month_Weekdays

funcsynopsis funcsynopsisinfo require_once 'MonthWeekdays.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $firstDay = FALSE /paramdef /funcprototype /funcsynopsis

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.

Calendar_Month_Weekdays
Calendar_Month_Weekdays::build
Calendar


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.

constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays
Calendar_Month_Weeks
Calendar
PHP Manual

Calendar_Month_Weekdays::build()

(No version information available, might be only in CVS)

— 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.

funcsynopsis funcsynopsisinfo require_once 'MonthWeekdays.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Month_Weekdays::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Month_Weekdays::Calendar_Month_Weekdays
Calendar_Month_Weeks
Calendar


Calendar_Month_Weeks API

Calendar_Month_Weekdays::build
constructor Calendar_Month_Weeks::Calendar_Month_Weeks
Calendar
PHP Manual

Calendar_Month_Weeks

(No version information available, might be only in CVS)

Calendar_Month_Weeks — Calendar_Month_Weeks API

Description

Calendar API.

Calendar_Month_Weekdays::build
constructor Calendar_Month_Weeks::Calendar_Month_Weeks
Calendar


Constructs Calendar_Month_Weeks

Calendar_Month_Weeks
Calendar_Month_Weeks::build
Calendar
PHP Manual

constructor Calendar_Month_Weeks::Calendar_Month_Weeks()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Month_Weeks

funcsynopsis funcsynopsisinfo require_once 'MonthWeeks.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Month_Weeks::Calendar_Month_Weeks()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $firstDay = FALSE /paramdef /funcprototype /funcsynopsis

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.

Calendar_Month_Weeks
Calendar_Month_Weeks::build
Calendar


Builds Calendar_Week objects for the Month. Note that Calendar_Week

constructor Calendar_Month_Weeks::Calendar_Month_Weeks
Calendar_Week
Calendar
PHP Manual

Calendar_Month_Weeks::build()

(No version information available, might be only in CVS)

— Builds Calendar_Week objects for the Month. Note that Calendar_Week

funcsynopsis funcsynopsisinfo require_once 'MonthWeeks.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Month_Weeks::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Month_Weeks::Calendar_Month_Weeks
Calendar_Week
Calendar


Calendar_Week API

Calendar_Month_Weeks::build
constructor Calendar_Week::Calendar_Week
Calendar
PHP Manual

Calendar_Week

(No version information available, might be only in CVS)

Calendar_Week — Calendar_Week API

Description

Calendar_Week API.

Calendar_Month_Weeks::build
constructor Calendar_Week::Calendar_Week
Calendar


Constructs Week

Calendar_Week
Calendar_Week::build
Calendar
PHP Manual

constructor Calendar_Week::Calendar_Week()

(No version information available, might be only in CVS)

constructor — Constructs Week

funcsynopsis funcsynopsisinfo require_once 'Week.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Week::Calendar_Week()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $d /paramdef paramdefint $firstDay = FALSE /paramdef /funcprototype /funcsynopsis

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.

Calendar_Week
Calendar_Week::build
Calendar


Builds Calendar_Day objects for this Week

constructor Calendar_Week::Calendar_Week
Calendar_Week::nextWeek
Calendar
PHP Manual

Calendar_Week::build()

(No version information available, might be only in CVS)

— Builds Calendar_Day objects for this Week

funcsynopsis funcsynopsisinfo require_once 'Week.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Week::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Week::Calendar_Week
Calendar_Week::nextWeek
Calendar


Gets the value of the following week, according to the requested format

Calendar_Week::build
Calendar_Week::prevWeek
Calendar
PHP Manual

Calendar_Week::nextWeek()

(No version information available, might be only in CVS)

— Gets the value of the following week, according to the requested format

funcsynopsis funcsynopsisinfo require_once 'Week.php'; /funcsynopsisinfo funcprototype funcdefmixed Calendar_Week::nextWeek()/funcdef paramdefstring $format /paramdef /funcprototype /funcsynopsis

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.

Calendar_Week::build
Calendar_Week::prevWeek
Calendar


Gets the value of the previous week, according to the requested format

Calendar_Week::nextWeek
Calendar_Week::thisWeek
Calendar
PHP Manual

Calendar_Week::prevWeek()

(No version information available, might be only in CVS)

— Gets the value of the previous week, according to the requested format

funcsynopsis funcsynopsisinfo require_once 'Week.php'; /funcsynopsisinfo funcprototype funcdefmixed Calendar_Week::prevWeek()/funcdef paramdefstring $format /paramdef /funcprototype /funcsynopsis

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.

Calendar_Week::nextWeek
Calendar_Week::thisWeek
Calendar


Gets the value of the current week, according to the requested format

Calendar_Week::prevWeek
Calendar_Day
Calendar
PHP Manual

Calendar_Week::thisWeek()

(No version information available, might be only in CVS)

— Gets the value of the current week, according to the requested format

funcsynopsis funcsynopsisinfo require_once 'Week.php'; /funcsynopsisinfo funcprototype funcdefmixed Calendar_Week::thisWeek()/funcdef paramdefstring $format = 'n_in_month' /paramdef /funcprototype /funcsynopsis

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.

Calendar_Week::prevWeek
Calendar_Day
Calendar


Calendar_Day API

Calendar_Week::thisWeek
constructor Calendar_Day::Calendar_Day
Calendar
PHP Manual

Calendar_Day

(No version information available, might be only in CVS)

Calendar_Day — Calendar_Day API

Description

Calendar_Day API.

Calendar_Week::thisWeek
constructor Calendar_Day::Calendar_Day
Calendar


Constructs Calendar_Day

Calendar_Day
Calendar_Day::build
Calendar
PHP Manual

constructor Calendar_Day::Calendar_Day()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Day

funcsynopsis funcsynopsisinfo require_once 'Day.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Day::Calendar_Day()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $d /paramdef /funcprototype /funcsynopsis

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.

Calendar_Day
Calendar_Day::build
Calendar


Builds the Hours of the Day

constructor Calendar_Day::Calendar_Day
Calendar_Day::isEmpty
Calendar
PHP Manual

Calendar_Day::build()

(No version information available, might be only in CVS)

— Builds the Hours of the Day

funcsynopsis funcsynopsisinfo require_once 'Day.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Day::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Day::Calendar_Day
Calendar_Day::isEmpty
Calendar


Calendar_Day::isEmpty

Calendar_Day::build
Calendar_Day::isFirst
Calendar
PHP Manual

Calendar_Day::isEmpty()

(No version information available, might be only in CVS)

—

funcsynopsis funcsynopsisinfo require_once 'Day.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Day::isEmpty()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Day::build
Calendar_Day::isFirst
Calendar


Returns true if Day object is first in a Week

Calendar_Day::isEmpty
Calendar_Day::isLast
Calendar
PHP Manual

Calendar_Day::isFirst()

(No version information available, might be only in CVS)

— Returns true if Day object is first in a Week

funcsynopsis funcsynopsisinfo require_once 'Day.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Day::isFirst()/funcdef paramdef /funcprototype /funcsynopsis

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.

Calendar_Day::isEmpty
Calendar_Day::isLast
Calendar


Returns true if Day object is last in a Week

Calendar_Day::isFirst
Calendar_Hour
Calendar
PHP Manual

Calendar_Day::isLast()

(No version information available, might be only in CVS)

— Returns true if Day object is last in a Week

funcsynopsis funcsynopsisinfo require_once 'Day.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Day::isLast()/funcdef paramdef /funcprototype /funcsynopsis

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.

Calendar_Day::isFirst
Calendar_Hour
Calendar


Calendar_Hour API

Calendar_Day::isLast
constructor Calendar_Hour::Calendar_Hour
Calendar
PHP Manual

Calendar_Hour

(No version information available, might be only in CVS)

Calendar_Hour — Calendar_Hour API

Description

Calendar_Hour API.

Calendar_Day::isLast
constructor Calendar_Hour::Calendar_Hour
Calendar


Constructs Calendar_Hour

Calendar_Hour
Calendar_Hour::build
Calendar
PHP Manual

constructor Calendar_Hour::Calendar_Hour()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Hour

funcsynopsis funcsynopsisinfo require_once 'Hour.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Hour::Calendar_Hour()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $d /paramdef paramdefint $h /paramdef /funcprototype /funcsynopsis

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.

Calendar_Hour
Calendar_Hour::build
Calendar


Builds the Minutes in the Hour

constructor Calendar_Hour::Calendar_Hour
Calendar_Minute
Calendar
PHP Manual

Calendar_Hour::build()

(No version information available, might be only in CVS)

— Builds the Minutes in the Hour

funcsynopsis funcsynopsisinfo require_once 'Hour.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Hour::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Hour::Calendar_Hour
Calendar_Minute
Calendar


Calendar_Minute API

Calendar_Hour::build
constructor Calendar_Minute::Calendar_Minute
Calendar
PHP Manual

Calendar_Minute

(No version information available, might be only in CVS)

Calendar_Minute — Calendar_Minute API

Description

Calendar_Minute API.

Calendar_Hour::build
constructor Calendar_Minute::Calendar_Minute
Calendar


Constructs Minute

Calendar_Minute
Calendar_Minute::build
Calendar
PHP Manual

constructor Calendar_Minute::Calendar_Minute()

(No version information available, might be only in CVS)

constructor — Constructs Minute

funcsynopsis funcsynopsisinfo require_once 'Minute.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Minute::Calendar_Minute()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $d /paramdef paramdefint $h /paramdef paramdefint $i /paramdef /funcprototype /funcsynopsis

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.

Calendar_Minute
Calendar_Minute::build
Calendar


Builds the Calendar_Second objects

constructor Calendar_Minute::Calendar_Minute
Calendar_Second
Calendar
PHP Manual

Calendar_Minute::build()

(No version information available, might be only in CVS)

— Builds the Calendar_Second objects

funcsynopsis funcsynopsisinfo require_once 'Minute.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Minute::build()/funcdef paramdefarray $sDates = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Minute::Calendar_Minute
Calendar_Second
Calendar


Calendar_Second API

Calendar_Minute::build
constructor Calendar_Second::Calendar_Second
Calendar
PHP Manual

Calendar_Second

(No version information available, might be only in CVS)

Calendar_Second — Calendar_Second API

Description

Calendar_Second API.

Calendar_Minute::build
constructor Calendar_Second::Calendar_Second
Calendar


Constructs Second

Calendar_Second
Calendar_Second::build
Calendar
PHP Manual

constructor Calendar_Second::Calendar_Second()

(No version information available, might be only in CVS)

constructor — Constructs Second

funcsynopsis funcsynopsisinfo require_once 'Second.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Second::Calendar_Second()/funcdef paramdefint $y /paramdef paramdefint $m /paramdef paramdefint $d /paramdef paramdefint $h /paramdef paramdefint $i /paramdef paramdefint $s /paramdef /funcprototype /funcsynopsis

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.

Calendar_Second
Calendar_Second::build
Calendar


Overwrite build

constructor Calendar_Second::Calendar_Second
Calendar_Second::fetch
Calendar
PHP Manual

Calendar_Second::build()

(No version information available, might be only in CVS)

— Overwrite build

funcsynopsis funcsynopsisinfo require_once 'Second.php'; /funcsynopsisinfo funcprototype funcdefNULL Calendar_Second::build()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

constructor Calendar_Second::Calendar_Second
Calendar_Second::fetch
Calendar


Overwrite fetch

Calendar_Second::build
Calendar_Second::fetchAll
Calendar
PHP Manual

Calendar_Second::fetch()

(No version information available, might be only in CVS)

— Overwrite fetch

funcsynopsis funcsynopsisinfo require_once 'Second.php'; /funcsynopsisinfo funcprototype funcdefNULL Calendar_Second::fetch()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Second::build
Calendar_Second::fetchAll
Calendar


Overwrite fetchAll

Calendar_Second::fetch
Calendar_Second::size
Calendar
PHP Manual

Calendar_Second::fetchAll()

(No version information available, might be only in CVS)

— Overwrite fetchAll

funcsynopsis funcsynopsisinfo require_once 'Second.php'; /funcsynopsisinfo funcprototype funcdefNULL Calendar_Second::fetchAll()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Second::fetch
Calendar_Second::size
Calendar


Overwrite size

Calendar_Second::fetchAll
Calendar_Validation_Error
Calendar
PHP Manual

Calendar_Second::size()

(No version information available, might be only in CVS)

— Overwrite size

funcsynopsis funcsynopsisinfo require_once 'Second.php'; /funcsynopsisinfo funcprototype funcdefNULL Calendar_Second::size()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Second::fetchAll
Calendar_Validation_Error
Calendar


Calendar_Validation_Error API

Calendar_Second::size
constructor Calendar_Validation_Error::Calendar_Validation_Error
Calendar
PHP Manual

Calendar_Validation_Error

(No version information available, might be only in CVS)

Calendar_Validation_Error — Calendar_Validation_Error API

Description

Calendar_Validation_Error API.

Calendar_Second::size
constructor Calendar_Validation_Error::Calendar_Validation_Error
Calendar


Constructs Calendar_Validation_Error

Calendar_Validation_Error
Calendar_Validation_Error::getMessage
Calendar
PHP Manual

constructor Calendar_Validation_Error::Calendar_Validation_Error()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Validation_Error

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Validation_Error::Calendar_Validation_Error()/funcdef paramdefstring $unit /paramdef paramdefint $value /paramdef paramdefstring $message /paramdef /funcprototype /funcsynopsis

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.

Calendar_Validation_Error
Calendar_Validation_Error::getMessage
Calendar


Returns the validation error message

constructor Calendar_Validation_Error::Calendar_Validation_Error
Calendar_Validation_Error::getUnit
Calendar
PHP Manual

Calendar_Validation_Error::getMessage()

(No version information available, might be only in CVS)

— Returns the validation error message

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefstring Calendar_Validation_Error::getMessage()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

constructor Calendar_Validation_Error::Calendar_Validation_Error
Calendar_Validation_Error::getUnit
Calendar


Returns the Date unit

Calendar_Validation_Error::getMessage
Calendar_Validation_Error::getValue
Calendar
PHP Manual

Calendar_Validation_Error::getUnit()

(No version information available, might be only in CVS)

— Returns the Date unit

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefstring Calendar_Validation_Error::getUnit()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validation_Error::getMessage
Calendar_Validation_Error::getValue
Calendar


Returns the value of the unit

Calendar_Validation_Error::getUnit
Calendar_Validation_Error::toString
Calendar
PHP Manual

Calendar_Validation_Error::getValue()

(No version information available, might be only in CVS)

— Returns the value of the unit

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefint Calendar_Validation_Error::getValue()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validation_Error::getUnit
Calendar_Validation_Error::toString
Calendar


Returns a string containing the unit, value and error message

Calendar_Validation_Error::getValue
Calendar_Validator
Calendar
PHP Manual

Calendar_Validation_Error::toString()

(No version information available, might be only in CVS)

— Returns a string containing the unit, value and error message

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefstring Calendar_Validation_Error::toString()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validation_Error::getValue
Calendar_Validator
Calendar


Calendar_Validator API

Calendar_Validation_Error::toString
constructor Calendar_Validator::Calendar_Validator
Calendar
PHP Manual

Calendar_Validator

(No version information available, might be only in CVS)

Calendar_Validator — Calendar_Validator API

Description

Calendar_Validator API.

Calendar_Validation_Error::toString
constructor Calendar_Validator::Calendar_Validator
Calendar


Constructs Calendar_Validator

Calendar_Validator
Calendar_Validator::fetch
Calendar
PHP Manual

constructor Calendar_Validator::Calendar_Validator()

(No version information available, might be only in CVS)

constructor — Constructs Calendar_Validator

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Calendar_Validator::Calendar_Validator()/funcdef paramdefobject subclass &$calendar /paramdef /funcprototype /funcsynopsis

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.

Calendar_Validator
Calendar_Validator::fetch
Calendar


Iterates over any validation errors

constructor Calendar_Validator::Calendar_Validator
Calendar_Validator::isValid
Calendar
PHP Manual

Calendar_Validator::fetch()

(No version information available, might be only in CVS)

— Iterates over any validation errors

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefmixed Calendar_Validator::fetch()/funcdef paramdef /funcprototype /funcsynopsis

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.

constructor Calendar_Validator::Calendar_Validator
Calendar_Validator::isValid
Calendar


Calls all the other isValidXXX() methods in the validator

Calendar_Validator::fetch
Calendar_Validator::isValidDay
Calendar
PHP Manual

Calendar_Validator::isValid()

(No version information available, might be only in CVS)

— Calls all the other isValidXXX() methods in the validator

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValid()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::fetch
Calendar_Validator::isValidDay
Calendar


Check whether this is a valid day

Calendar_Validator::isValid
Calendar_Validator::isValidHour
Calendar
PHP Manual

Calendar_Validator::isValidDay()

(No version information available, might be only in CVS)

— Check whether this is a valid day

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValidDay()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::isValid
Calendar_Validator::isValidHour
Calendar


Check whether this is a valid hour

Calendar_Validator::isValidDay
Calendar_Validator::isValidMinute
Calendar
PHP Manual

Calendar_Validator::isValidHour()

(No version information available, might be only in CVS)

— Check whether this is a valid hour

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValidHour()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::isValidDay
Calendar_Validator::isValidMinute
Calendar


Check whether this is a valid minute

Calendar_Validator::isValidHour
Calendar_Validator::isValidMonth
Calendar
PHP Manual

Calendar_Validator::isValidMinute()

(No version information available, might be only in CVS)

— Check whether this is a valid minute

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValidMinute()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::isValidHour
Calendar_Validator::isValidMonth
Calendar


Check whether this is a valid month

Calendar_Validator::isValidMinute
Calendar_Validator::isValidSecond
Calendar
PHP Manual

Calendar_Validator::isValidMonth()

(No version information available, might be only in CVS)

— Check whether this is a valid month

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValidMonth()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::isValidMinute
Calendar_Validator::isValidSecond
Calendar


Check whether this is a valid second

Calendar_Validator::isValidMonth
Calendar_Validator::isValidYear
Calendar
PHP Manual

Calendar_Validator::isValidSecond()

(No version information available, might be only in CVS)

— Check whether this is a valid second

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValidSecond()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::isValidMonth
Calendar_Validator::isValidYear
Calendar


Check whether this is a valid year

Calendar_Validator::isValidSecond
Package Calendar Constants
Calendar
PHP Manual

Calendar_Validator::isValidYear()

(No version information available, might be only in CVS)

— Check whether this is a valid year

funcsynopsis funcsynopsisinfo require_once 'Validator.php'; /funcsynopsisinfo funcprototype funcdefboolean Calendar_Validator::isValidYear()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Calendar_Validator::isValidSecond
Package Calendar Constants
Calendar


Constants defined in and used by Calendar

Calendar
Date
Calendar
PHP Manual

Package Calendar Constants

(No version information available, might be only in CVS)

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

Calendar
Date
Calendar


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.

Package Calendar Constants
Examples
Date and Time


Learning by doing

Date
Basics
Date
PHP Manual

Examples

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.

Example #3 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.

Example #4 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.

Example #5 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";
}
?>
Date
Basics
Date


How to get information

Date
Date_Holidays
Date
PHP Manual

Basics

(No version information available, might be only in CVS)

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

Date
Date_Holidays
Date


Date_Holidays

Holiday calculation package.

This chapter describes how to use PEAR::Date_Holidays

Date and Time
Introduction
Date and Time


What Date_Holidays can do

Date_Holidays
Example
Date_Holidays
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Date_Holidays
Example
Date_Holidays


Example for the usage of Date_Holidays

Date_Holidays
Encryption
Date_Holidays
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Example for the usage of Date_Holidays

Basic example

This example shows you, how to calculate the Easter date of 2005.

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] =>
                )

        )

)
Date_Holidays
Encryption
Date_Holidays


Encryption

Table of Contents

  • Crypt_CHAP

Provides Packages for de- and encryption

Example
Crypt_CHAP
Packages


Crypt_CHAP

Classes for generating packets for various CHAP Protocols

Encryption
Introduction
Encryption


encryption

Crypt_CHAP
Crypt_CHAP::generateChallenge()
Crypt_CHAP
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Crypt_CHAP
Crypt_CHAP::generateChallenge()
Crypt_CHAP


Generates a new random challenge.

Introduction
Crypt_CHAP_MD5::Crypt_CHAP_MD5()
Crypt_CHAP
PHP Manual

Crypt_CHAP::generateChallenge()

(No version information available, might be only in CVS)

Crypt_CHAP::generateChallenge() — Generates a new random challenge.

funcsynopsis funcprototype funcdefstring Crypt_CHAP::generateChallenge()/funcdef paramdefstring $varname = 'challenge' /paramdef paramdefint $size = 8 /paramdef /funcprototype /funcsynopsis

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

Example #1 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());

?>
Introduction
Crypt_CHAP_MD5::Crypt_CHAP_MD5()
Crypt_CHAP


constructor

Crypt_CHAP::generateChallenge()
Crypt_CHAP_MD5::challengeResponse()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MD5::Crypt_CHAP_MD5()

(No version information available, might be only in CVS)

Crypt_CHAP_MD5::Crypt_CHAP_MD5() — constructor

funcsynopsis funcsynopsisinfo require_once 'Crypt/CHAP.php'; /funcsynopsisinfo funcprototype funcdefvoid Crypt_CHAP_MD5::Crypt_CHAP_MD5()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

Generates a new Object for generating CHAP-MD5 compliant pakets.

Crypt_CHAP::generateChallenge()
Crypt_CHAP_MD5::challengeResponse()
Crypt_CHAP


Generates the challenge-response paket.

Crypt_CHAP_MD5::Crypt_CHAP_MD5()
Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MD5::challengeResponse()

(No version information available, might be only in CVS)

Crypt_CHAP_MD5::challengeResponse() — Generates the challenge-response paket.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MD5::challengeResponse()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using Crypt_CHAP_MD5::challengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MD5();
$cr->password = 'MyPw';
echo bin2hex($cr->challengeResponse());

?>
Crypt_CHAP_MD5::Crypt_CHAP_MD5()
Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()
Crypt_CHAP


constructor

Crypt_CHAP_MD5::challengeResponse()
Crypt_CHAP_MSCHAPv1::challengeResponse()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1() — constructor

funcsynopsis funcsynopsisinfo require_once 'Crypt/CHAP.php'; /funcsynopsisinfo funcprototype funcdefvoid Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

Crypt_CHAP_MD5::challengeResponse()
Crypt_CHAP_MSCHAPv1::challengeResponse()
Crypt_CHAP


Generates the Challenge-Response paket.

Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()
Crypt_CHAP_MSCHAPv1::lmChallengeResponse()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::challengeResponse()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::challengeResponse() — Generates the Challenge-Response paket.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::challengeResponse()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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());

?>
Crypt_CHAP_MSCHAPv1::Crypt_CHAP_MSCHAPv1()
Crypt_CHAP_MSCHAPv1::lmChallengeResponse()
Crypt_CHAP


Generates the Challenge-Response paket using the LAN-Manager Hash.

Crypt_CHAP_MSCHAPv1::challengeResponse()
Crypt_CHAP_MSCHAPv1::ntChallengeResponse()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::lmChallengeResponse()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::lmChallengeResponse() — Generates the Challenge-Response paket using the LAN-Manager Hash.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::lmChallengeResponse()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using Crypt_CHAP_MSCHAPv1::lmChallengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password = 'MyPw';
echo bin2hex($cr->lmChallengeResponse());

?>
Crypt_CHAP_MSCHAPv1::challengeResponse()
Crypt_CHAP_MSCHAPv1::ntChallengeResponse()
Crypt_CHAP


Generates the Challenge-Response paket using the NT-Hash.

Crypt_CHAP_MSCHAPv1::lmChallengeResponse()
Crypt_CHAP_MSCHAPv1::ntPasswordHash()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::ntChallengeResponse()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::ntChallengeResponse() — Generates the Challenge-Response paket using the NT-Hash.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::ntChallengeResponse()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using Crypt_CHAP_MSCHAPv1::ntChallengeResponse()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password = 'MyPw';
echo bin2hex($cr->ntChallengeResponse());

?>
Crypt_CHAP_MSCHAPv1::lmChallengeResponse()
Crypt_CHAP_MSCHAPv1::ntPasswordHash()
Crypt_CHAP


Generates the NT-Hash from the given plaintext-password.

Crypt_CHAP_MSCHAPv1::ntChallengeResponse()
Crypt_CHAP_MSCHAPv1::lmPasswordHash()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::ntPasswordHash()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::ntPasswordHash() — Generates the NT-Hash from the given plaintext-password.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::ntPasswordHash()/funcdef paramdefstring $password = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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'));

?>
Crypt_CHAP_MSCHAPv1::ntChallengeResponse()
Crypt_CHAP_MSCHAPv1::lmPasswordHash()
Crypt_CHAP


Generates the LAN-Manager-Hash from the given plaintext-password.

Crypt_CHAP_MSCHAPv1::ntPasswordHash()
Crypt_CHAP_MSCHAPv1::str2unicode()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::lmPasswordHash()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::lmPasswordHash() — Generates the LAN-Manager-Hash from the given plaintext-password.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::lmPasswordHash()/funcdef paramdefstring $password = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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'));

?>
Crypt_CHAP_MSCHAPv1::ntPasswordHash()
Crypt_CHAP_MSCHAPv1::str2unicode()
Crypt_CHAP


Converts a string to unicode.

Crypt_CHAP_MSCHAPv1::lmPasswordHash()
Crypt_CHAP_MSCHAPv1::response()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::str2unicode()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::str2unicode() — Converts a string to unicode.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::str2unicode()/funcdef paramdefstring $str /paramdef /funcprototype /funcsynopsis

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

Example #1 Using Crypt_CHAP_MSCHAPv1::str2unicode()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
echo bin2hex($cr->str2unicode('MyPw'));

?>
Crypt_CHAP_MSCHAPv1::lmPasswordHash()
Crypt_CHAP_MSCHAPv1::response()
Crypt_CHAP


Generates the response-packet.

Crypt_CHAP_MSCHAPv1::str2unicode()
Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv1::response()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv1::response() — Generates the response-packet.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv1::response()/funcdef paramdefbool $lm = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 Using Crypt_CHAP_MSCHAPv1::response()

<?php
require_once 'Crypt/CHAP.php';

$cr = new Crypt_CHAP_MSCHAPv1();
$cr->password  = 'MyPw';
echo bin2hex($cr->response());

?>
Crypt_CHAP_MSCHAPv1::str2unicode()
Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()
Crypt_CHAP


constructor

Crypt_CHAP_MSCHAPv1::response()
Crypt_CHAP_MSCHAPv2::challengeHash()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2() — constructor

funcsynopsis funcsynopsisinfo require_once 'Crypt/CHAP.php'; /funcsynopsisinfo funcprototype funcdefvoid Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

Crypt_CHAP_MSCHAPv1::response()
Crypt_CHAP_MSCHAPv2::challengeHash()
Crypt_CHAP


Generates the Challenge-Hash.

Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()
Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv2::challengeHash()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv2::challengeHash() — Generates the Challenge-Hash.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv2::challengeHash()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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());

?>
Crypt_CHAP_MSCHAPv2::Crypt_CHAP_MSCHAPv2()
Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()
Crypt_CHAP


Generates an MD4 Hash from the NT-Hash.

Crypt_CHAP
Event
Crypt_CHAP
PHP Manual

Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()

(No version information available, might be only in CVS)

Crypt_CHAP_MSCHAPv2::ntPasswordHashHash() — Generates an MD4 Hash from the NT-Hash.

funcsynopsis funcprototype funcdefstring Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()/funcdef paramdefstring $nthash /paramdef /funcprototype /funcsynopsis

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

Example #1 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));

?>
Crypt_CHAP
Event
Crypt_CHAP


Event

Table of Contents

  • Event_Dispatcher

Provides packages for event based development.

Crypt_CHAP_MSCHAPv2::ntPasswordHashHash()
Event_Dispatcher
Packages


Event_Dispatcher

Dispatch notifications using PHP callbacks

Event
Introduction
Event


Event_Dispatcher
Examples
Event_Dispatcher
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Event_Dispatcher
Examples
Event_Dispatcher


Examples for the usage of Event_Dispatcher

Introduction
Event_Dispatcher::getInstance
Event_Dispatcher
PHP Manual

Examples

(No version information available, might be only in CVS)

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.

Example #1 Basic example

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.

Example #2 Cancelling notifications

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.

Introduction
Event_Dispatcher::getInstance
Event_Dispatcher


Create a new Event_Dispatcher object

Examples
Event_Dispatcher::getName
Event_Dispatcher
PHP Manual

Event_Dispatcher::getInstance()

(No version information available, might be only in CVS)

— Create a new Event_Dispatcher object

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefobject Event_Dispatcher Event_Dispatcher::getInstance()/funcdef paramdefstring $name = '__default' /paramdef /funcprototype /funcsynopsis

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.

Examples
Event_Dispatcher::getName
Event_Dispatcher


Get the name of the dispatcher.

Event_Dispatcher::getInstance
Event_Dispatcher::addObserver
Event_Dispatcher
PHP Manual

Event_Dispatcher::getName()

(No version information available, might be only in CVS)

— Get the name of the dispatcher.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefstring Event_Dispatcher::getName()/funcdef paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::getInstance
Event_Dispatcher::addObserver
Event_Dispatcher


Add a new observer.

Event_Dispatcher::getName
Event_Dispatcher::removeObserver
Event_Dispatcher
PHP Manual

Event_Dispatcher::addObserver()

(No version information available, might be only in CVS)

— Add a new observer.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefvoid Event_Dispatcher::addObserver()/funcdef paramdefmixed $callback /paramdef paramdefstring $nName = EVENT_DISPATCHER_GLOBAL /paramdef paramdefstring $class = '' /paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::getName
Event_Dispatcher::removeObserver
Event_Dispatcher


Remove an observer.

Event_Dispatcher::addObserver
Event_Dispatcher::setNotificationClass
Event_Dispatcher
PHP Manual

Event_Dispatcher::removeObserver()

(No version information available, might be only in CVS)

— Remove an observer.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefbool Event_Dispatcher::removeObserver()/funcdef paramdefmixed $callback /paramdef paramdefstring $nName = EVENT_DISPATCHER_GLOBAL /paramdef paramdefstring $class = '' /paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::addObserver
Event_Dispatcher::setNotificationClass
Event_Dispatcher


Set the class that is used as notification.

Event_Dispatcher::removeObserver
Event_Dispatcher::post
Event_Dispatcher
PHP Manual

Event_Dispatcher::setNotificationClass()

(No version information available, might be only in CVS)

— Set the class that is used as notification.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefbool Event_Dispatcher::setNotificationClass()/funcdef paramdefstring $class /paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::removeObserver
Event_Dispatcher::post
Event_Dispatcher


Post a notification.

Event_Dispatcher::setNotificationClass
Event_Dispatcher::addNestedDispatcher
Event_Dispatcher
PHP Manual

Event_Dispatcher::post()

(No version information available, might be only in CVS)

— Post a notification.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefobject Event_Notification Event_Dispatcher::post()/funcdef paramdefobject &$object /paramdef paramdefstring $nName /paramdef paramdefmixed $info = array() /paramdef paramdefbool $pending = TRUE /paramdef paramdefbool $bubble = TRUE /paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::setNotificationClass
Event_Dispatcher::addNestedDispatcher
Event_Dispatcher


Add a nested dispatcher.

Event_Dispatcher::post
Event_Dispatcher::removeNestedDispatcher
Event_Dispatcher
PHP Manual

Event_Dispatcher::addNestedDispatcher()

(No version information available, might be only in CVS)

— Add a nested dispatcher.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefvoid Event_Dispatcher::addNestedDispatcher()/funcdef paramdefobject Event_Dispatcher &$dispatcher /paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::post
Event_Dispatcher::removeNestedDispatcher
Event_Dispatcher


Remove a nested dispatcher.

Event_Dispatcher::addNestedDispatcher
Event_Notification
Event_Dispatcher
PHP Manual

Event_Dispatcher::removeNestedDispatcher()

(No version information available, might be only in CVS)

— Remove a nested dispatcher.

funcsynopsis funcsynopsisinfo require_once 'Event/Dispatcher.php'; /funcsynopsisinfo funcprototype funcdefboolean Event_Dispatcher::removeNestedDispatcher()/funcdef paramdefobject Event_Dispatcher &$dispatcher /paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher::addNestedDispatcher
Event_Notification
Event_Dispatcher


Container class for notifications.

Event_Dispatcher::removeNestedDispatcher
Event_Notification::Event_Notification
Event_Dispatcher
PHP Manual

Event_Notification

(No version information available, might be only in CVS)

— 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.

Event_Dispatcher::removeNestedDispatcher
Event_Notification::Event_Notification
Event_Dispatcher


Create a new notification object.

Event_Notification
Event_Notification::getNotificationName
Event_Dispatcher
PHP Manual

Event_Notification::Event_Notification()

(No version information available, might be only in CVS)

— Create a new notification object.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefobject Event_Notification Event_Notification::Event_Notifcation()/funcdef paramdefobject &$object /paramdef paramdefstring $nName /paramdef paramdefmixed $info = array() /paramdef /funcprototype /funcsynopsis

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.

Event_Notification
Event_Notification::getNotificationName
Event_Dispatcher


Get the name of the notification.

Event_Notification::Event_Notification
Event_Notification::getNotificationObject
Event_Dispatcher
PHP Manual

Event_Notification::getNotificationName()

(No version information available, might be only in CVS)

— Get the name of the notification.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefstring Event_Notification::getNotificationName()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get the name of the notification.

Return value

string name of the notification

Note

This function can not be called statically.

Event_Notification::Event_Notification
Event_Notification::getNotificationObject
Event_Dispatcher


Get the object that sent the notification.

Event_Notification::getNotificationName
Event_Notification::getNotificationInfo
Event_Dispatcher
PHP Manual

Event_Notification::getNotificationObject()

(No version information available, might be only in CVS)

— Get the object that sent the notification.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefobject &Event_Notification::getNotificationObject()/funcdef paramdef /funcprototype /funcsynopsis

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.

Event_Notification::getNotificationName
Event_Notification::getNotificationInfo
Event_Dispatcher


Get additional information from the notification.

Event_Notification::getNotificationObject
Event_Notification::getNotificationCount
Event_Dispatcher
PHP Manual

Event_Notification::getNotificationInfo()

(No version information available, might be only in CVS)

— Get additional information from the notification.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefmixed Event_Notification::getNotificationInfo()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get additional information that has been stored in the notification.

Return value

mixed additional information.

Note

This function can not be called statically.

Event_Notification::getNotificationObject
Event_Notification::getNotificationCount
Event_Dispatcher


Get number of observers notified.

Event_Notification::getNotificationInfo
Event_Notification::cancelNotification
Event_Dispatcher
PHP Manual

Event_Notification::getNotificationCount()

(No version information available, might be only in CVS)

— Get number of observers notified.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefint Event_Notification::getNotificationCount()/funcdef paramdef /funcprototype /funcsynopsis

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.

Event_Notification::getNotificationInfo
Event_Notification::cancelNotification
Event_Dispatcher


Cancel the notification.

Event_Notification::getNotificationCount
Event_Notification::isNotificationCancelled
Event_Dispatcher
PHP Manual

Event_Notification::cancelNotification()

(No version information available, might be only in CVS)

— Cancel the notification.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefvoid Event_Notification::cancelNotification()/funcdef paramdef /funcprototype /funcsynopsis

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.

Event_Notification::getNotificationCount
Event_Notification::isNotificationCancelled
Event_Dispatcher


Check, whether notification has been cancelled.

Event_Dispatcher
File Formats
Event_Dispatcher
PHP Manual

Event_Notification::isNotificationCancelled()

(No version information available, might be only in CVS)

— Check, whether notification has been cancelled.

funcsynopsis funcsynopsisinfo require_once 'Event/Notification.php'; /funcsynopsisinfo funcprototype funcdefbool Event_Notification::isNotificationCancelled()/funcdef paramdef /funcprototype /funcsynopsis

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.

Event_Dispatcher
File Formats
Event_Dispatcher


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
  • Spreadsheet_Excel_Writer

Provides Packages for working with different file formats.

Event_Notification::isNotificationCancelled
Contact_Vcard
Packages


Contact_VCard
File Formats
PHP Manual

Contact_Vcard

Parse and create vCards.

File Formats
Contact_VCard
File Formats


About the classes

Contact_Vcard
Components
Contact_Vcard
PHP Manual

Contact_VCard

(No version information available, might be only in CVS)

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.

Contact_Vcard
Components
Contact_Vcard
PHP Manual


Data stored in a vCard

Contact_VCard
Lines
Contact_Vcard
PHP Manual

Components

(No version information available, might be only in CVS)

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.

Contact_VCard
Lines
Contact_Vcard


vCards internally

Components
Projects
Contact_Vcard
PHP Manual

Lines

(No version information available, might be only in CVS)

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.

Components
Projects
Contact_Vcard


Other vCard projects

Contact_Vcard
Contact_Vcard_Build
Contact_Vcard
PHP Manual

Projects

(No version information available, might be only in CVS)

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.

Contact_Vcard
Contact_Vcard_Build
Contact_Vcard


Contact_Vcard_Build

Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Please read About Contact_Vcard first.

Projects
Introduction
File Formats


Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Contact_Vcard_Build
Usage
Contact_Vcard_Build
PHP Manual

Introduction

(No version information available, might be only in CVS)

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 #1 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())

Contact_Vcard_Build
Usage
Contact_Vcard_Build


How to use Contact_VCard_Build

Contact_Vcard_Build
Contact_Vcard_Parse
Contact_Vcard_Build
PHP Manual

Usage

(No version information available, might be only in CVS)

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.

Contact_Vcard_Build
Contact_Vcard_Parse
Contact_Vcard_Build


Contact_Vcard_Parse

Parse vCard 2.1 and 3.0 files.

Please read About Contact_Vcard first.

Usage
Introduction
File Formats


Build (create) and fetch vCard 2.1 and 3.0 text blocks.

Contact_Vcard_Parse
How Data Is Returned
Contact_Vcard_Parse
PHP Manual

Introduction

(No version information available, might be only in CVS)

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 #1 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>';

?>
Contact_Vcard_Parse
How Data Is Returned
Contact_Vcard_Parse


Getting data from the file

Introduction
Known issues
Contact_Vcard_Parse
PHP Manual

How Data Is Returned

(No version information available, might be only in CVS)

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.

Introduction
Known issues
Contact_Vcard_Parse


Problems you might encounter

Contact_Vcard_Parse
File_Archive
Contact_Vcard_Parse
PHP Manual

Known issues

(No version information available, might be only in CVS)

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].

Contact_Vcard_Parse
File_Archive
Contact_Vcard_Parse


File_Archive

This package will let you manipulate easily tar, gz, bz2, tgz, tbz, zip, ar and deb files.

Known issues
Examples
File Formats


Some simple usage examples

File_Archive
Dynamic generation of archive files for a gallery
File_Archive
PHP Manual

Examples

(No version information available, might be only in CVS)

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 output/.

<?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()
);
?>
File_Archive
Dynamic generation of archive files for a gallery
File_Archive


How to use File_Archive for a photo/video gallery

Examples
Readers
File_Archive
PHP Manual

Dynamic generation of archive files for a gallery

(No version information available, might be only in CVS)

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.

Example #1 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()
    )
);
?>

Example #2 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.

Example #3 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()
    )
);
?>
Examples
Readers
File_Archive


Getting files into an archive

Dynamic generation of archive files for a gallery
Writers
File_Archive
PHP Manual

Readers

(No version information available, might be only in CVS)

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:

funcsynopsis funcprototype funcdef read() /funcdef paramdef string $url /paramdef paramdef string $symbolic = null /paramdef paramdef integer $uncompression = 0 /paramdef paramdef integer $directoryDepth = -0 /paramdef /funcprototype /funcsynopsis

In this function the URL will represent what you want to read.

Example #1 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.

Example #2 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.

Example #3 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:

Example #4 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')
);
?>
Dynamic generation of archive files for a gallery
Writers
File_Archive


Saving archives

Readers
Predicates
File_Archive
PHP Manual

Writers

(No version information available, might be only in CVS)

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:

funcsynopsis funcprototype funcdef toArchive() /funcdef paramdef string $filename /paramdef paramdef &$innerWriter /paramdef paramdef $type = null /paramdef paramdef $stat = array() /paramdef paramdef $autoClose = true /paramdef /funcprototype /funcsynopsis

  • $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.

Example #1 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.

Example #2 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.

funcsynopsis funcprototype funcdef toMail() /funcdef paramdef array $to /paramdef paramdef array $headers /paramdef paramdef string $message /paramdef paramdef &$mail = null /paramdef /funcprototype /funcsynopsis

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).

Example #3 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.

Example #4 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:

Example #5 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()
        )
    )
);
?>
Readers
Predicates
File_Archive


Filters

Writers
Archive modification
File_Archive
PHP Manual

Predicates

(No version information available, might be only in CVS)

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.

Example #1 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()
    )
);
?>
Writers
Archive modification
File_Archive


Remove and append files

Predicates
Cache
File_Archive
PHP Manual

Archive modification

(No version information available, might be only in CVS)

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:

  • funcsynopsis funcprototype funcdef remove() /funcdef paramdef&$pred/paramdef paramdef$URL/paramdef /funcprototype /funcsynopsis

    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.

  • funcsynopsis funcprototype funcdef removeFromSource() /funcdef paramdef&$pred/paramdef paramdef&$source/paramdef paramdef$URL = null/paramdef /funcprototype /funcsynopsis

    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.

  • funcsynopsis funcprototype funcdef removeDuplicates() /funcdef paramdef$URL/paramdef /funcprototype /funcsynopsis

    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.

  • funcsynopsis funcprototype funcdef removeDuplicatesFromSource() /funcdef paramdef&$source/paramdef paramdef$URL = null/paramdef /funcprototype /funcsynopsis

    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.

Example #1 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'
);
?>

Example #2 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:

  • funcsynopsis funcprototype funcdef appender() /funcdef paramdef$URL/paramdef paramdef$unique = null /paramdef paramdef$type = null /paramdef paramdef$stat = array() /paramdef /funcprototype /funcsynopsis

    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.

  • funcsynopsis funcprototype funcdef appenderFromSource() /funcdef paramdef&$source /paramdef paramdef$URL = null /paramdef paramdef$unique = null /paramdef paramdef$type = null /paramdef paramdef$stat = array() /paramdef /funcprototype /funcsynopsis

    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

Example #3 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:

Example #4 Add a folder to an archive

<?php
require_once "File/Archive.php";

File_Archive::extract(
    $src = 'folder',
    $dest= 'archive.zip'
);
?>
Predicates
Cache
File_Archive


Caching compressed files

File_Archive
File_Cabinet
File_Archive
PHP Manual

Cache

(No version information available, might be only in CVS)

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.

Example #1 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()
    )
);
?>
File_Archive
File_Cabinet
File_Archive


File_Cabinet

Microsoft Cabinet file extraction using either cabextract or expand

Cache
Introduction
File Formats


Extraction of Microsoft Cabinet files

File_Cabinet
File_DICOM
File_Cabinet
PHP Manual

Introduction

(No version information available, might be only in CVS)

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');
?>

File_Cabinet
File_DICOM
File_Cabinet


File_DICOM

Package for reading and modifying DICOM files

Introduction
Introduction
File Formats


using File_DICOM

File_DICOM
constructor File_DICOM::File_DICOM
File_DICOM
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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");
}
?>
File_DICOM
constructor File_DICOM::File_DICOM
File_DICOM


Constructor.

Introduction
File_DICOM::parse
File_DICOM
PHP Manual

constructor File_DICOM::File_DICOM()

(No version information available, might be only in CVS)

constructor — Constructor.

funcsynopsis funcsynopsisinfo require_once 'File/DICOM.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor File_DICOM::File_DICOM()/funcdef paramdef /funcprototype /funcsynopsis

Description

It creates a File_DICOM object.

Note

This function can not be called statically.

Introduction
File_DICOM::parse
File_DICOM


Parse a DICOM file.

constructor File_DICOM::File_DICOM
File_DICOM::write
File_DICOM
PHP Manual

File_DICOM::parse()

(No version information available, might be only in CVS)

— Parse a DICOM file.

funcsynopsis funcsynopsisinfo require_once 'File/DICOM.php'; /funcsynopsisinfo funcprototype funcdefmixed File_DICOM::parse()/funcdef paramdefstring $infile /paramdef /funcprototype /funcsynopsis

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.

constructor File_DICOM::File_DICOM
File_DICOM::write
File_DICOM


Write current contents to a DICOM file.

File_DICOM::parse
File_DICOM::getValue
File_DICOM
PHP Manual

File_DICOM::write()

(No version information available, might be only in CVS)

— Write current contents to a DICOM file.

funcsynopsis funcsynopsisinfo require_once 'File/DICOM.php'; /funcsynopsisinfo funcprototype funcdefmixed File_DICOM::write()/funcdef paramdefstring $outfile = '' /paramdef /funcprototype /funcsynopsis

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.

File_DICOM::parse
File_DICOM::getValue
File_DICOM


Gets the value for a DICOM element.

File_DICOM::write
File_DICOM::setValue
File_DICOM
PHP Manual

File_DICOM::getValue()

(No version information available, might be only in CVS)

— Gets the value for a DICOM element.

funcsynopsis funcsynopsisinfo require_once 'File/DICOM.php'; /funcsynopsisinfo funcprototype funcdefmixed File_DICOM::getValue()/funcdef paramdefmixed $group_or_name /paramdef paramdefinteger $element = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getValue()

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";
File_DICOM::write
File_DICOM::setValue
File_DICOM


Sets the value for a DICOM element.

File_DICOM::getValue
File_DICOM::dumpImage
File_DICOM
PHP Manual

File_DICOM::setValue()

(No version information available, might be only in CVS)

— Sets the value for a DICOM element.

funcsynopsis funcsynopsisinfo require_once 'File/DICOM.php'; /funcsynopsisinfo funcprototype funcdefvoid File_DICOM::setValue()/funcdef paramdefinteger $gp /paramdef paramdefinteger $el /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

File_DICOM::getValue
File_DICOM::dumpImage
File_DICOM


Dumps the contents of the image inside the DICOM file (element 0x0010 from group 0x7FE0) to a PGM (Portable Gray Map) file.

File_DICOM
File_Fortune
File_DICOM
PHP Manual

File_DICOM::dumpImage()

(No version information available, might be only in CVS)

— Dumps the contents of the image inside the DICOM file (element 0x0010 from group 0x7FE0) to a PGM (Portable Gray Map) file.

funcsynopsis funcsynopsisinfo require_once 'File/DICOM.php'; /funcsynopsisinfo funcprototype funcdefmixed File_DICOM::dumpImage()/funcdef paramdefstring $filename /paramdef /funcprototype /funcsynopsis

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.

File_DICOM
File_Fortune
File_DICOM


File_Fortune

File_DICOM::dumpImage
Class Summary File_Fortune
File Formats


File_Fortune
Introduction
File_Fortune
PHP Manual

Class Summary File_Fortune

(No version information available, might be only in CVS)

Class Summary — 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

File_Fortune
Introduction
File_Fortune
PHP Manual


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.

Class Summary File_Fortune
Examples
File_Fortune
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Class Summary File_Fortune
Examples
File_Fortune


Common use cases.

Introduction
File_Fortune::__construct
File_Fortune
PHP Manual

Examples

(No version information available, might be only in CVS)

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.

Introduction
File_Fortune::__construct
File_Fortune


Constructor

Examples
File_Fortune::add
File_Fortune
PHP Manual

File_Fortune::__construct()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef File_Fortune File_Fortune::__construct() /funcdef paramdef string|array $file = NULL /paramdef paramdef string $headerFile = NULL /paramdef /funcprototype /funcsynopsis

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.

Examples
File_Fortune::add
File_Fortune


Add a new fortune

File_Fortune::__construct
File_Fortune::create
File_Fortune
PHP Manual

File_Fortune::add()

(No version information available, might be only in CVS)

— Add a new fortune

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef File_Fortune File_Fortune::add() /funcdef paramdef string $fortune /paramdef /funcprototype /funcsynopsis

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.

File_Fortune::__construct
File_Fortune::create
File_Fortune


Create a new fortune file from an array of fortunes

File_Fortune::add
File_Fortune::delete
File_Fortune
PHP Manual

File_Fortune::create()

(No version information available, might be only in CVS)

— Create a new fortune file from an array of fortunes

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef void File_Fortune::create() /funcdef paramdef $fortunes /paramdef paramdef string $file = NULL /paramdef /funcprototype /funcsynopsis

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.

File_Fortune::add
File_Fortune::delete
File_Fortune


Delete an existing fortune

File_Fortune::create
File_Fortune::getAll
File_Fortune
PHP Manual

File_Fortune::delete()

(No version information available, might be only in CVS)

— Delete an existing fortune

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef void File_Fortune::delete() /funcdef paramdef int $index /paramdef /funcprototype /funcsynopsis

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.

File_Fortune::create
File_Fortune::getAll
File_Fortune


Retrieve all fortunes from the current file

File_Fortune::delete
File_Fortune::getDirectory
File_Fortune
PHP Manual

File_Fortune::getAll()

(No version information available, might be only in CVS)

— Retrieve all fortunes from the current file

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef array File_Fortune::getAll() /funcdef paramdef /funcprototype /funcsynopsis

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.

File_Fortune::delete
File_Fortune::getDirectory
File_Fortune


Retrieve current directory of fortune files

File_Fortune::getAll
File_Fortune::getFile
File_Fortune
PHP Manual

File_Fortune::getDirectory()

(No version information available, might be only in CVS)

— Retrieve current directory of fortune files

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef string File_Fortune::getDirectory() /funcdef paramdef /funcprototype /funcsynopsis

Description

getDirectory() returns the currently registered fortune file directory, if any.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getAll
File_Fortune::getFile
File_Fortune


Retrieve current fortune file name

File_Fortune::getDirectory
File_Fortune::getFiles
File_Fortune
PHP Manual

File_Fortune::getFile()

(No version information available, might be only in CVS)

— Retrieve current fortune file name

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef string File_Fortune::getFile() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::getDirectory
File_Fortune::getFiles
File_Fortune


Retrieve list of currently set fortune files

File_Fortune::getFile
File_Fortune::getHeaderFile
File_Fortune
PHP Manual

File_Fortune::getFiles()

(No version information available, might be only in CVS)

— Retrieve list of currently set fortune files

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef array File_Fortune::getFiles() /funcdef paramdef /funcprototype /funcsynopsis

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.

File_Fortune::getFile
File_Fortune::getHeaderFile
File_Fortune


Retrieve current header file name

File_Fortune::getFiles
File_Fortune::getRandom
File_Fortune
PHP Manual

File_Fortune::getHeaderFile()

(No version information available, might be only in CVS)

— Retrieve current header file name

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef string File_Fortune::getHeaderFile() /funcdef paramdef /funcprototype /funcsynopsis

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.

File_Fortune::getFiles
File_Fortune::getRandom
File_Fortune


Retrieve random fortune

File_Fortune::getHeaderFile
File_Fortune::save
File_Fortune
PHP Manual

File_Fortune::getRandom()

(No version information available, might be only in CVS)

— Retrieve random fortune

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef string File_Fortune::getRandom() /funcdef paramdef /funcprototype /funcsynopsis

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.

File_Fortune::getHeaderFile
File_Fortune::save
File_Fortune


Save changes

File_Fortune::getRandom
File_Fortune::setDirectory
File_Fortune
PHP Manual

File_Fortune::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef void File_Fortune::save() /funcdef paramdef /funcprototype /funcsynopsis

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.

File_Fortune::getRandom
File_Fortune::setDirectory
File_Fortune


Set directory from which to randomly select a fortune file

File_Fortune::save
File_Fortune::setFile
File_Fortune
PHP Manual

File_Fortune::setDirectory()

(No version information available, might be only in CVS)

— Set directory from which to randomly select a fortune file

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef File_Fortune File_Fortune::setDirectory() /funcdef paramdef string $directory /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $directory

Throws

throws no exceptions thrown

Note

This function can not be called statically.

File_Fortune::save
File_Fortune::setFile
File_Fortune


Set fortune file

File_Fortune::setDirectory
File_Fortune::setFiles
File_Fortune
PHP Manual

File_Fortune::setFile()

(No version information available, might be only in CVS)

— Set fortune file

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef File_Fortune File_Fortune::setFile() /funcdef paramdef string $file /paramdef paramdef string $headerFile = NULL /paramdef /funcprototype /funcsynopsis

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.

File_Fortune::setDirectory
File_Fortune::setFiles
File_Fortune


Set multiple fortune files

File_Fortune::setFile
File_Fortune::setHeaderFile
File_Fortune
PHP Manual

File_Fortune::setFiles()

(No version information available, might be only in CVS)

— Set multiple fortune files

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef File_Fortune File_Fortune::setFiles() /funcdef paramdef /funcprototype /funcsynopsis

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.

File_Fortune::setFile
File_Fortune::setHeaderFile
File_Fortune


Set header file name

File_Fortune::setFiles
File_Fortune::update
File_Fortune
PHP Manual

File_Fortune::setHeaderFile()

(No version information available, might be only in CVS)

— Set header file name

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef File_Fortune File_Fortune::setHeaderFile() /funcdef paramdef string $headerFile /paramdef /funcprototype /funcsynopsis

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.

File_Fortune::setFiles
File_Fortune::update
File_Fortune


Update an existing fortune

File_Fortune
File_Fstab
File_Fortune
PHP Manual

File_Fortune::update()

(No version information available, might be only in CVS)

— Update an existing fortune

funcsynopsis funcsynopsisinforequire_once 'File/Fortune.php';/funcsynopsisinfo funcprototype funcdef void File_Fortune::update() /funcdef paramdef int $index /paramdef paramdef string $fortune /paramdef /funcprototype /funcsynopsis

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.

File_Fortune
File_Fstab
File_Fortune


File_Fstab

This package reads and writes fstab files, or other files sharing their format, such as /proc/mounts on Linux systems.

File_Fortune::update
Introduction
File Formats


Introduction to File_Fstab.

File_Fstab
Entries
File_Fstab
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Getting the filesystem type of the root device.

require_once 'File/Fstab.php';

$fstab =& new File_Fstab();

$root =& $fstab->getEntryForPath('/');
echo "Root FS type: " . $root->fsType . "\n";

Example #2 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.

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";
}
File_Fstab
Entries
File_Fstab


Working with entries

Introduction
Saving
File_Fstab
PHP Manual

Entries

(No version information available, might be only in CVS)

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.

Example #1 Get entry by device

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.

Example #2 Get entry by path

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.

Example #3 Get entry by UUID

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.

Example #4 Get entry by label

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.

Example #5 Add an entry for a floppy disk

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);
Introduction
Saving
File_Fstab


File_Fstab
File_MARC
File_Fstab
PHP Manual

Saving

(No version information available, might be only in CVS)

Saving — Saving your changes

Saving your changes

After modifying a fstab file, you will want to save your changes. The save() function does this.

Warning

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.

Example #1 Save to the same file

This will save your changes back to the file you loaded, overwriting the old file.

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());
}

Example #2 Save to a different file

This will save your changes to a different file than the one you originally loaded.

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());
}
File_Fstab
File_MARC
File_Fstab


File_MARC

This package creates, reads, and modifies Machine Readable Cataloging (MARC) formatted files.

Saving
Reading MARC data
File Formats


Reading MARC data with File_MARC

File_MARC
Formatting MARC data
File_MARC
PHP Manual

Reading MARC data

(No version information available, might be only in CVS)

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.

Example #1 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.

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";
}

Example #2 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.

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.

Example #3 Printing the elements of a record

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.

Example #4 Retrieving all 650 fields from a record

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.

Example #5 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.

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.

Example #6 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.

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');
}
File_MARC
Formatting MARC data
File_MARC


Formatting MARC data with File_MARC

File_MARC
File_Passwd
File_MARC
PHP Manual

Formatting MARC data

(No version information available, might be only in CVS)

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.

Example #1 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.

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.

Example #2 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.

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.

Warning

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.

Example #3 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.

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);
File_MARC
File_Passwd
File_MARC


Formatting MARC data
Introduction
File Formats
PHP Manual

File_Passwd

Package to manage passwd-style files

Introduction

File_Passwd

The File_Passwd class provides a factory for all special purpose classes, static authentication and common encryption methods.

File_Passwd_Common

Base class for worker class extensions.

File_Passwd_Custom

Manipulate custom formatted passwd files. (inherited methods)

File_Passwd_Unix

Manipulate standard Unix passwd files. (inherited methods)

File_Passwd_Cvs

Manipulate CVS pserver passwd files. (inherited methods)

File_Passwd_Smb

Manipulate SMB server passwd files. (inherited methods)

File_Passwd_Authbasic

Manipulate AuthUserFiles. (inherited methods)

File_Passwd_Authdigest

Manipulate AuthDigestFiles. (inherited methods)

Formatting MARC data
Introduction
File Formats


Introduction

(No version information available, might be only in CVS)

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!

Formatting MARC data


Constants used by File_Passwd

Formatting MARC data
PHP Manual

File_Passwd Constants

(No version information available, might be only in CVS)

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
Formatting MARC data


Get API version

Formatting MARC data
PHP Manual

File_Passwd::apiVersion()

(No version information available, might be only in CVS)

— Get API version

funcsynopsis funcsynopsisinfo require_once 'File/Passwd.php'; /funcsynopsisinfo funcprototype funcdefstring File_Passwd::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Factory for extensions

Formatting MARC data
PHP Manual

File_Passwd::factory()

(No version information available, might be only in CVS)

— Factory for extensions

funcsynopsis funcsynopsisinforequire_once 'File/Passwd.php';/funcsynopsisinfo funcprototype funcdef object &File_Passwd::factory() /funcdef paramdefstring $class /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd::staticAuth()/funcdef paramdefstring $type /paramdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefmixed $opt = '' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Classes that extend File_Passwd_Common and their inherited methods

Formatting MARC data
PHP Manual

Childs

(No version information available, might be only in CVS)

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

Formatting MARC data


Delete a certain user

Formatting MARC data
PHP Manual

File_Passwd_Common::delUser()

(No version information available, might be only in CVS)

— Delete a certain user

funcsynopsis funcprototype funcdefmixed^File_Passwd_Common::delUser()/funcdef paramdefstring $user /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


List user

Formatting MARC data
PHP Manual

File_Passwd_Common::listUser()

(No version information available, might be only in CVS)

— List user

funcsynopsis funcprototype funcdefmixed File_Passwd_Common::listUser()/funcdef paramdefstring $user = '' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Check if user exists

Formatting MARC data
PHP Manual

File_Passwd_Common::userExists()

(No version information available, might be only in CVS)

— Check if user exists

funcsynopsis funcprototype funcdefbool File_Passwd_Common::userExists()/funcdef paramdefstring $user /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get path of passwd file

Formatting MARC data
PHP Manual

File_Passwd_Common::getFile()

(No version information available, might be only in CVS)

— Get path of passwd file

funcsynopsis funcprototype funcdefstring File_Passwd_Common::getFile()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get the path of the passwd file.

Return value

Returns string path of passwd file.

Note

This function can not be called statically.

Formatting MARC data


Set path to passwd file

Formatting MARC data
PHP Manual

File_Passwd_Common::setFile()

(No version information available, might be only in CVS)

— Set path to passwd file

funcsynopsis funcprototype funcdefvoid File_Passwd_Common::setFile()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

Description

Set path to passwd file.

Parameter

string $file

path to passwd file

Note

This function can not be called statically.

Formatting MARC data


Loads the file

Formatting MARC data
PHP Manual

File_Passwd_Common::load()

(No version information available, might be only in CVS)

— Loads the file

funcsynopsis funcprototype funcdefmixed File_Passwd_Common::load()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse the content of the file

Formatting MARC data
PHP Manual

File_Passwd_Common::parse()

(No version information available, might be only in CVS)

— Parse the content of the file

funcsynopsis funcprototype funcdefobject File_Passwd_Common::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Apply changes and rewrite passwd file

Formatting MARC data
PHP Manual

File_Passwd_Common::save()

(No version information available, might be only in CVS)

— Apply changes and rewrite passwd file

funcsynopsis funcprototype funcdefobject File_Passwd_Common::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Base method for File_Passwd::staticAuth()

Formatting MARC data
PHP Manual

File_Passwd_Common::_auth()

(No version information available, might be only in CVS)

— Base method for File_Passwd::staticAuth()

funcsynopsis funcprototype funcdefmixed File_Passwd_Common::_auth()/funcdef paramdefstring $file /paramdef paramdefstring $id /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Open a file

Formatting MARC data
PHP Manual

File_Passwd_Common::_open()

(No version information available, might be only in CVS)

— Open a file

funcsynopsis funcprototype funcdefmixed &File_Passwd_Common::_open()/funcdef paramdefstring $mode /paramdef paramdefmixed $file = null /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Closes a prior opened and locked file handle

Formatting MARC data
PHP Manual

File_Passwd_Common::_close()

(No version information available, might be only in CVS)

— Closes a prior opened and locked file handle

funcsynopsis funcprototype funcdefmixed File_Passwd_Common::_close()/funcdef paramdefresource &$file_handle /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save the modified content to the passwd file

Formatting MARC data
PHP Manual

File_Passwd_Common::_save()

(No version information available, might be only in CVS)

— Save the modified content to the passwd file

funcsynopsis funcprototype funcdefmixed File_Passwd_Common::_save()/funcdef paramdefstring $content /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor (ZE2)

Formatting MARC data
PHP Manual

File_Passwd_Common::__construct()

(No version information available, might be only in CVS)

— Constructor (ZE2)

funcsynopsis funcprototype funcdefobject File_Passwd_Common::__construct()/funcdef paramdefstring $file = 'passwd' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd_Custom::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd/Custom.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd_Custom::staticAuth()/funcdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefarray $opts /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor

Formatting MARC data
PHP Manual

File_Passwd_Custom::File_Passwd_Custom()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Passwd/Custom.php';/funcsynopsisinfo funcprototype funcdefobject &new File_Passwd_custom()/funcdef paramdefstring $file = 'passwd' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse passwd file

Formatting MARC data
PHP Manual

File_Passwd_Custom::parse()

(No version information available, might be only in CVS)

— Parse passwd file

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save changes

Formatting MARC data
PHP Manual

File_Passwd_Custom::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Add an user

Formatting MARC data
PHP Manual

File_Passwd_Custom::addUser()

(No version information available, might be only in CVS)

— Add an user

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::addUser()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefarray $extra = array() /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Modify user

Formatting MARC data
PHP Manual

File_Passwd_Custom::modUser()

(No version information available, might be only in CVS)

— Modify user

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::modUser()/funcdef paramdefstring $user /paramdef paramdefarray $properties = array() /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change password

Formatting MARC data
PHP Manual

File_Passwd_Custom::changePasswd()

(No version information available, might be only in CVS)

— Change password

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::changePasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verify password

Formatting MARC data
PHP Manual

File_Passwd_Custom::verifyPasswd()

(No version information available, might be only in CVS)

— Verify password

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::verifyPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Whether to use the 'name map'

Formatting MARC data
PHP Manual

File_Passwd_Custom::useMap()

(No version information available, might be only in CVS)

— Whether to use the 'name map'

funcsynopsis funcprototype funcdefboolean File_Passwd_Custom::useMap()/funcdef paramdefboolean $bool = null /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get 'name map'

Formatting MARC data
PHP Manual

File_Passwd_Custom::getMap()

(No version information available, might be only in CVS)

— Get 'name map'

funcsynopsis funcprototype funcdefarray File_Passwd_Custom::getMap()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Set 'name map'

Formatting MARC data
PHP Manual

File_Passwd_Custom::setMap()

(No version information available, might be only in CVS)

— Set 'name map'

funcsynopsis funcprototype funcdefmixed File_Passwd_Custom::setMap()/funcdef paramdefmixed $map = array() /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd_Unix::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd/Unix.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd_Unix::staticAuth()/funcdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefstring $mode /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor

Formatting MARC data
PHP Manual

File_Passwd_Unix::File_Passwd_Unix()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Passwd/Unix.php';/funcsynopsisinfo funcprototype funcdefobject &new File_Passwd_Unix()/funcdef paramdefstring $file = 'passwd' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse passwd file

Formatting MARC data
PHP Manual

File_Passwd_Unix::parse()

(No version information available, might be only in CVS)

— Parse passwd file

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save changes

Formatting MARC data
PHP Manual

File_Passwd_Unix::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Add an user

Formatting MARC data
PHP Manual

File_Passwd_Unix::addUser()

(No version information available, might be only in CVS)

— Add an user

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::addUser()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefarray $extra = array() /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Modify user

Formatting MARC data
PHP Manual

File_Passwd_Unix::modUser()

(No version information available, might be only in CVS)

— Modify user

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::modUser()/funcdef paramdefstring $user /paramdef paramdefarray $properties = array() /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change password

Formatting MARC data
PHP Manual

File_Passwd_Unix::changePasswd()

(No version information available, might be only in CVS)

— Change password

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::changePasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verify password

Formatting MARC data
PHP Manual

File_Passwd_Unix::verifyPasswd()

(No version information available, might be only in CVS)

— Verify password

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::verifyPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Whether to use the 'name map'

Formatting MARC data
PHP Manual

File_Passwd_Unix::useMap()

(No version information available, might be only in CVS)

— Whether to use the 'name map'

funcsynopsis funcprototype funcdefboolean File_Passwd_Unix::useMap()/funcdef paramdefboolean $bool = null /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get 'name map'

Formatting MARC data
PHP Manual

File_Passwd_Unix::getMap()

(No version information available, might be only in CVS)

— Get 'name map'

funcsynopsis funcprototype funcdefarray File_Passwd_Unix::getMap()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Set 'name map'

Formatting MARC data
PHP Manual

File_Passwd_Unix::setMap()

(No version information available, might be only in CVS)

— Set 'name map'

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::setMap()/funcdef paramdefmixed $map = array() /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get actual encryption mode

Formatting MARC data
PHP Manual

File_Passwd_Unix::getMode()

(No version information available, might be only in CVS)

— Get actual encryption mode

funcsynopsis funcprototype funcdefstring File_Passwd_Unix::getMode()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Set encryption mode

Formatting MARC data
PHP Manual

File_Passwd_Unix::setMode()

(No version information available, might be only in CVS)

— Set encryption mode

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::setMode()/funcdef paramdefstring $mode /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get supported encryption modes

Formatting MARC data
PHP Manual

File_Passwd_Unix::listModes()

(No version information available, might be only in CVS)

— Get supported encryption modes

funcsynopsis funcprototype funcdefarray File_Passwd_Unix::listModes()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Check if passwd file is shadowed

Formatting MARC data
PHP Manual

File_Passwd_Unix::isShadowed()

(No version information available, might be only in CVS)

— Check if passwd file is shadowed

funcsynopsis funcprototype funcdefboolean File_Passwd_Unix::isShadowed()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Generate password

Formatting MARC data
PHP Manual

File_Passwd_Unix::generatePassword()

(No version information available, might be only in CVS)

— Generate password

funcsynopsis funcprototype funcdefmixed File_Passwd_Unix::generatePassword()/funcdef paramdefstring $pass /paramdef paramdefstring $mode = 'md5' /paramdef paramdefstring $salt = null /paramdef /funcprototype /funcsynopsis

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

Example #1 File_Passwd_Unix::generatePassword()

require_once 'File/Passwd/Unix.php';
$pass = File_Passwd_Unix::generatePassword('secret', FILE_PASSWD_MD5);

Note

This function should be called statically.

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd_Cvs::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd/Cvs.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd_Cvs::staticAuth()/funcdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor

Formatting MARC data
PHP Manual

File_Passwd_Cvs::File_Passwd_Cvs()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Passwd/Cvs.php';/funcsynopsisinfo funcprototype funcdefobject &new File_Passwd_Cvs()/funcdef paramdefmixed $file = 'passwd' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse file

Formatting MARC data
PHP Manual

File_Passwd_Cvs::parse()

(No version information available, might be only in CVS)

— Parse file

funcsynopsis funcprototype funcdefmixed File_Passwd_Cvs::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save changes

Formatting MARC data
PHP Manual

File_Passwd_Cvs::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcprototype funcdefmixed File_Passwd_Cvs::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Add an user

Formatting MARC data
PHP Manual

File_Passwd_Cvs::addUser()

(No version information available, might be only in CVS)

— Add an user

funcsynopsis funcprototype funcdefmixed File_Passwd_Cvs::addUser()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefstring $system_user = '' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change syste user

Formatting MARC data
PHP Manual

File_Passwd_Cvs::changeSysUser()

(No version information available, might be only in CVS)

— Change syste user

funcsynopsis funcprototype funcdefmixed File_Passwd_Cvs::changeSysUser()/funcdef paramdefmixed $user /paramdef paramdefmixed $system /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change password

Formatting MARC data
PHP Manual

File_Passwd_Cvs::changePasswd()

(No version information available, might be only in CVS)

— Change password

funcsynopsis funcprototype funcdefmixed File_Passwd_Cvs::changePasswd()/funcdef paramdefmixed $user /paramdef paramdefmixed $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verify password

Formatting MARC data
PHP Manual

File_Passwd_Cvs::verifyPasswd()

(No version information available, might be only in CVS)

— Verify password

funcsynopsis funcprototype funcdefmixed File_Passwd_Cvs::verifyPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Generate password

Formatting MARC data
PHP Manual

File_Passwd_Cvs::generatePassword()

(No version information available, might be only in CVS)

— Generate password

funcsynopsis funcprototype funcdefstring File_Passwd_Cvs::generatePassword()/funcdef paramdefstring $pass /paramdef paramdefstring $salt = null /paramdef /funcprototype /funcsynopsis

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

Example #1 File_Passwd_Cvs::generatePassword()

require_once 'File/Passwd/Cvs.php';
$pass = File_Passwd_Cvs::generatePassword('secret');

Note

This function should be called statically.

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd_Smb::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd/Smb.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd_Smb::staticAuth()/funcdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefstring $mode /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor

Formatting MARC data
PHP Manual

File_Passwd_Smb::File_Passwd_Smb()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Passwd/Smb.php';/funcsynopsisinfo funcprototype funcdefobject &new File_Passwd_Smb()/funcdef paramdefstring $file = 'smbpasswd' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse file

Formatting MARC data
PHP Manual

File_Passwd_Smb::parse()

(No version information available, might be only in CVS)

— Parse file

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save changes

Formatting MARC data
PHP Manual

File_Passwd_Smb::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Add an user

Formatting MARC data
PHP Manual

File_Passwd_Smb::addUser()

(No version information available, might be only in CVS)

— Add an user

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::addUser()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefarray $params /paramdef paramdefboolean $isMachine = false /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Modify a user

Formatting MARC data
PHP Manual

File_Passwd_Smb::modUser()

(No version information available, might be only in CVS)

— Modify a user

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::modUser()/funcdef paramdefstring $user /paramdef paramdefarray $params /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change password

Formatting MARC data
PHP Manual

File_Passwd_Smb::changePasswd()

(No version information available, might be only in CVS)

— Change password

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::changePasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verify password

Formatting MARC data
PHP Manual

File_Passwd_Smb::verifyPasswd()

(No version information available, might be only in CVS)

— Verify password

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::verifyPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verify encrypted password

Formatting MARC data
PHP Manual

File_Passwd_Smb::verifyEncryptedPasswd()

(No version information available, might be only in CVS)

— Verify encrypted password

funcsynopsis funcprototype funcdefmixed File_Passwd_Smb::verifyEncryptedPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $nthash /paramdef paramdefstring $lmhash = '' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Generate password

Formatting MARC data
PHP Manual

File_Passwd_Smb::generatePassword()

(No version information available, might be only in CVS)

— Generate password

funcsynopsis funcprototype funcdefstring File_Passwd_Smb::generatePassword()/funcdef paramdefstring $pass /paramdef paramdefstring $mode = 'nt' /paramdef /funcprototype /funcsynopsis

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

Example #1 File_Passwd_Smb::generatePassword()

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() .

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd/Authbasic.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd_Authbasic::staticAuth()/funcdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefstring $mode /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::File_Passwd_Authbasic()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Passwd/Authbasic.php';/funcsynopsisinfo funcprototype funcdef object &new File_Passwd_Authbasic() /funcdef paramdefstring $file = '.htpasswd' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse the AuthUserFile

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::parse()

(No version information available, might be only in CVS)

— Parse the AuthUserFile

funcsynopsis funcprototype funcdefmixed File_Passwd_Authbasic::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save changes

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcprototype funcdefmixed File_Passwd_Authbasic::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Add an user

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::addUser()

(No version information available, might be only in CVS)

— Add an user

funcsynopsis funcprototype funcdef mixed File_Passwd_Authbasic::addUser() /funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change password

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::changePasswd()

(No version information available, might be only in CVS)

— Change password

funcsynopsis funcprototype funcdef mixed File_Passwd_Authbasic::changePasswd() /funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verify password

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::verifyPasswd()

(No version information available, might be only in CVS)

— Verify password

funcsynopsis funcprototype funcdefmixed File_Passwd_Authbasic::verifyPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get actual encryption mode

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::getMode()

(No version information available, might be only in CVS)

— Get actual encryption mode

funcsynopsis funcprototype funcdef string File_Passwd_Authbasic::getMode() /funcdef paramdef /funcprototype /funcsynopsis

Description

Get the actual encryption mode.

Return value

string - actual encryption mode

Note

This function can not be called statically.

Formatting MARC data


Set the encryption mode

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::setMode()

(No version information available, might be only in CVS)

— Set the encryption mode

funcsynopsis funcprototype funcdefmixed File_Passwd_Authbasic::setMode()/funcdef paramdefstring $mode /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Get supported encryption modes

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::listModes()

(No version information available, might be only in CVS)

— Get supported encryption modes

funcsynopsis funcprototype funcdef array File_Passwd_Authbasic::listModes()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Generate password

Formatting MARC data
PHP Manual

File_Passwd_Authbasic::generatePassword()

(No version information available, might be only in CVS)

— Generate password

funcsynopsis funcprototype funcdefmixed File_Passwd_Authbasic::generatePassword()/funcdef paramdefstring $pass /paramdef paramdefstring $mode = 'des' /paramdef paramdefstring $salt = null /paramdef /funcprototype /funcsynopsis

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

Example #1 File_Passwd_Authbasic::generatePassword()

require_once 'File/Passwd/Authbasic.php';
$pass = File_Passwd_Authbasic::generatePassword('secret', FILE_PASSWD_MD5);

Note

This function should be called statically.

Formatting MARC data


Fast authentication

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::staticAuth()

(No version information available, might be only in CVS)

— Fast authentication

funcsynopsis funcsynopsisinfo require_once 'File/Passwd/Authdigest.php'; /funcsynopsisinfo funcprototype funcdefmixed File_Passwd_Authdigest::staticAuth()/funcdef paramdefstring $file /paramdef paramdefstring $user /paramdef paramdefstring $pass /paramdef paramdefstring $realm /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Constructor

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::File_Passwd_Authdigest()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'File/Passwd/Authdigest.php';/funcsynopsisinfo funcprototype funcdefobject &new File_Passwd_Authdigest()/funcdef paramdefstring $file = '.htdigest' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Parse the AuthDigestFile

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::parse()

(No version information available, might be only in CVS)

— Parse the AuthDigestFile

funcsynopsis funcprototype funcdefmixed File_Passwd_Authdigest::parse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Save changes

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::save()

(No version information available, might be only in CVS)

— Save changes

funcsynopsis funcprototype funcdefmixed File_Passwd_Authdigest::save()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Add an user

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::addUser()

(No version information available, might be only in CVS)

— Add an user

funcsynopsis funcprototype funcdefmixed File_Passwd_Authdigest::addUser()/funcdef paramdefstring $user /paramdef paramdefstring $realm /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Change password

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::changePasswd()

(No version information available, might be only in CVS)

— Change password

funcsynopsis funcprototype funcdefmixed File_Passwd_Authdigest::changePasswd()/funcdef paramdefstring $user /paramdef paramdefstring $realm /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Verifiy password

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::verifyPasswd()

(No version information available, might be only in CVS)

— Verifiy password

funcsynopsis funcprototype funcdefmixed File_Passwd_Authdigest::verifyPasswd()/funcdef paramdefstring $user /paramdef paramdefstring $realm /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Delete a user

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::delUserInRealm()

(No version information available, might be only in CVS)

— Delete a user

funcsynopsis funcprototype funcdefmixed File_Passwd_Authdigest::delUserInRealm()/funcdef paramdefstring $user /paramdef paramdefstring $inRealm /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


List user

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::listUserInRealm()

(No version information available, might be only in CVS)

— List user

funcsynopsis funcprototype funcdefarray File_Passwd_Authdigest::listUserInRealm()/funcdef paramdefstring $inRealm = '' /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Ckeck if a certain user is in a specific realm

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::userInRealm()

(No version information available, might be only in CVS)

— Ckeck if a certain user is in a specific realm

funcsynopsis funcsynopsisinfo require_once 'Passwd/Authdigest.php'; /funcsynopsisinfo funcprototype funcdefboolean File_Passwd_Authdigest::userInRealm()/funcdef paramdefstring $user /paramdef paramdefstring $realm /paramdef /funcprototype /funcsynopsis

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.

Formatting MARC data


Generate password

Formatting MARC data
PHP Manual

File_Passwd_Authdigest::generatePassword()

(No version information available, might be only in CVS)

— Generate password

funcsynopsis funcprototype funcdefstring File_Passwd_Authdigest::generatePassword()/funcdef paramdefstring $user /paramdef paramdefstring $realm /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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

Example #1 File_Passwd_Authdigest::generatePassword()

require_once 'File/Passwd/Authdigest.php';
$pass = File_Passwd_Authdigest::generatePassword('mike', 'restricted', 'secret');

Note

This function should be called statically.

Formatting MARC data


MP3_Id

This package offers methods for reading and writing IDv1-information tags of MP3 files.

File_Passwd_Authdigest::generatePassword
Constants
File Formats


Constants defined in and used by MP3_Id

MP3_Id
MP3_Id::MP3_Id
MP3_Id
PHP Manual

Constants

(No version information available, might be only in CVS)

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

MP3_Id
MP3_Id::MP3_Id
MP3_Id


constructor

Constants
MP3_Id::copy
MP3_Id
PHP Manual

MP3_Id::MP3_Id()

(No version information available, might be only in CVS)

— constructor

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::MP3_Id()/funcdef paramdefboolean $study = FALSE /paramdef /funcprototype /funcsynopsis

Description

Constructor

Parameter

boolean $study

Enables an in-deep look in the file (increase execution time!)

Note

This function can not be called statically.

Constants
MP3_Id::copy
MP3_Id


copy the tags of another instance

MP3_Id::MP3_Id
MP3_Id::genres
MP3_Id
PHP Manual

MP3_Id::copy()

(No version information available, might be only in CVS)

— copy the tags of another instance

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::copy()/funcdef paramdefstring $from /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::MP3_Id
MP3_Id::genres
MP3_Id


get Genre list

MP3_Id::copy
MP3_Id::getGenre
MP3_Id
PHP Manual

MP3_Id::genres()

(No version information available, might be only in CVS)

— get Genre list

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefarray MP3_Id::genres()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns a list of genre numbers and names

Return value

array - list of genres

Note

This function can not be called statically.

MP3_Id::copy
MP3_Id::getGenre
MP3_Id


return genre name by number

MP3_Id::genres
MP3_Id::getGenreNo
MP3_Id
PHP Manual

MP3_Id::getGenre()

(No version information available, might be only in CVS)

— return genre name by number

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefmixed MP3_Id::getGenre()/funcdef paramdefinteger $genreno /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::genres
MP3_Id::getGenreNo
MP3_Id


get number of genre

MP3_Id::getGenre
MP3_Id::getTag
MP3_Id
PHP Manual

MP3_Id::getGenreNo()

(No version information available, might be only in CVS)

— get number of genre

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefinteger MP3_Id::getGenreNo()/funcdef paramdefstring $genre /paramdef paramdefinteger $default = 0xff /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::getGenre
MP3_Id::getTag
MP3_Id


get the value of a tag

MP3_Id::getGenreNo
MP3_Id::read
MP3_Id
PHP Manual

MP3_Id::getTag()

(No version information available, might be only in CVS)

— get the value of a tag

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefmixed MP3_Id::getTag()/funcdef paramdefstring $name /paramdef paramdefmixed $default /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::getGenreNo
MP3_Id::read
MP3_Id


reads and parses file

MP3_Id::getTag
MP3_Id::remove
MP3_Id
PHP Manual

MP3_Id::read()

(No version information available, might be only in CVS)

— reads and parses file

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::read()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::getTag
MP3_Id::remove
MP3_Id


remove tags

MP3_Id::read
MP3_Id::setTag
MP3_Id
PHP Manual

MP3_Id::remove()

(No version information available, might be only in CVS)

— remove tags

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::remove()/funcdef paramdefboolean $id3v1 = TRUE /paramdef paramdefboolean $id3v2 = TRUE /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::read
MP3_Id::setTag
MP3_Id


sets a tag content

MP3_Id::remove
MP3_Id::study
MP3_Id
PHP Manual

MP3_Id::setTag()

(No version information available, might be only in CVS)

— sets a tag content

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::setTag()/funcdef paramdefmixed $name /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

MP3_Id::remove
MP3_Id::study
MP3_Id


does extra work to get the MPEG frame info

MP3_Id::setTag
MP3_Id::write
MP3_Id
PHP Manual

MP3_Id::study()

(No version information available, might be only in CVS)

— does extra work to get the MPEG frame info

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::study()/funcdef ( void /funcprototype /funcsynopsis

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.

MP3_Id::setTag
MP3_Id::write
MP3_Id


save changed tags

MP3_Id
Spreadsheet_Excel_Writer
MP3_Id
PHP Manual

MP3_Id::write()

(No version information available, might be only in CVS)

— save changed tags

funcsynopsis funcsynopsisinfo require_once 'Id.php'; /funcsynopsisinfo funcprototype funcdefvoid MP3_Id::write()/funcdef paramdef boolean $v1 = TRUE /paramdef /funcprototype /funcsynopsis

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.

MP3_Id
Spreadsheet_Excel_Writer
MP3_Id


Spreadsheet_Excel_Writer

Package for generating Excel spreadsheets

File Formats
Introduction
File Formats


how to generate Excel files

Spreadsheet_Excel_Writer
Formatting Tutorial
Spreadsheet_Excel_Writer
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

Example #1 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:

Example #2 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.

Spreadsheet_Excel_Writer
Formatting Tutorial
Spreadsheet_Excel_Writer


how to format cells in a spreadsheet

Introduction
Workbook::close
Spreadsheet_Excel_Writer
PHP Manual

Formatting Tutorial

(No version information available, might be only in CVS)

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 citetitlenew/citetitle 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:

Example #1 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.

Example #2 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!

Example #3 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:

Example #4 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();
?>
Introduction
Workbook::close
Spreadsheet_Excel_Writer


Calls finalization methods for the workbook

Formatting Tutorial
Workbook::&addWorksheet
Spreadsheet_Excel_Writer
PHP Manual

Workbook::close

(No version information available, might be only in CVS)

Workbook::close — Calls finalization methods for the workbook

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefmixed Workbook::close()/funcdef paramdef /funcprototype /funcsynopsis

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.

Formatting Tutorial
Workbook::&addWorksheet
Spreadsheet_Excel_Writer


Add a new worksheet to the Excel workbook.

Workbook::close
Workbook::&addFormat
Spreadsheet_Excel_Writer
PHP Manual

Workbook::&addWorksheet

(No version information available, might be only in CVS)

Workbook::&addWorksheet — Add a new worksheet to the Excel workbook.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefobject reference Workbook::&addWorksheet()/funcdef paramdef string $name='' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
Workbook::close
Workbook::&addFormat
Spreadsheet_Excel_Writer


Add a new format to the Excel workbook.

Workbook::&addWorksheet
Workbook::&setTempDir
Spreadsheet_Excel_Writer
PHP Manual

Workbook::&addFormat

(No version information available, might be only in CVS)

Workbook::&addFormat — Add a new format to the Excel workbook.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefobject reference Workbook::&addFormat()/funcdef paramdef array $properties=array() /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
Workbook::&addWorksheet
Workbook::&setTempDir
Spreadsheet_Excel_Writer


Sets the temp dir used for storing the OLE file.

Workbook::&addFormat
Workbook::setCustomColor
Spreadsheet_Excel_Writer
PHP Manual

Workbook::&setTempDir

(No version information available, might be only in CVS)

Workbook::&setTempDir — Sets the temp dir used for storing the OLE file.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefboolean Workbook::&setTempDir()/funcdef paramdef string $dir /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
?>
Workbook::&addFormat
Workbook::setCustomColor
Spreadsheet_Excel_Writer


Change the RGB components of the elements in the colour palette.

Workbook::&setTempDir
Worksheet::getName
Spreadsheet_Excel_Writer
PHP Manual

Workbook::setCustomColor

(No version information available, might be only in CVS)

Workbook::setCustomColor — Change the RGB components of the elements in the colour palette.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefinteger Workbook::setCustomColor()/funcdef paramdef integer $index /paramdef paramdef integer $red /paramdef paramdef integer $green /paramdef paramdef integer $blue /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setCustomColor()

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();
Workbook::&setTempDir
Worksheet::getName
Spreadsheet_Excel_Writer


Retrieve the worksheet name. This is usefull when creating worksheets

Workbook::setCustomColor
Worksheet::setInputEncoding
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::getName

(No version information available, might be only in CVS)

Worksheet::getName — Retrieve the worksheet name. This is usefull when creating worksheets

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefstring Worksheet::getName()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using getName()

Workbook::setCustomColor
Worksheet::setInputEncoding
Spreadsheet_Excel_Writer


Allow writing for different charsets.

Worksheet::getName
Worksheet::select
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setInputEncoding

(No version information available, might be only in CVS)

Worksheet::setInputEncoding — Allow writing for different charsets.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setInputEncoding()/funcdef paramdef string $encoding /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
Worksheet::getName
Worksheet::select
Spreadsheet_Excel_Writer


Set this worksheet as a selected worksheet, i.e. the worksheet has its tab

Worksheet::setInputEncoding
Worksheet::activate
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::select

(No version information available, might be only in CVS)

Worksheet::select — Set this worksheet as a selected worksheet, i.e. the worksheet has its tab

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::select()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using select()

Worksheet::setInputEncoding
Worksheet::activate
Spreadsheet_Excel_Writer


Set this worksheet as the active worksheet, i.e. the worksheet that is

Worksheet::select
Worksheet::setFirstSheet
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::activate

(No version information available, might be only in CVS)

Worksheet::activate — Set this worksheet as the active worksheet, i.e. the worksheet that is

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::activate()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using activate()

Worksheet::select
Worksheet::setFirstSheet
Spreadsheet_Excel_Writer


Set this worksheet as the first visible sheet. This is necessary

Worksheet::activate
Worksheet::protect
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setFirstSheet

(No version information available, might be only in CVS)

Worksheet::setFirstSheet — Set this worksheet as the first visible sheet. This is necessary

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setFirstSheet()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using setFirstSheet()

Worksheet::activate
Worksheet::protect
Spreadsheet_Excel_Writer


Set the worksheet protection flag

Worksheet::setFirstSheet
Worksheet::setColumn
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::protect

(No version information available, might be only in CVS)

Worksheet::protect — Set the worksheet protection flag

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::protect()/funcdef paramdef string $password /paramdef /funcprototype /funcsynopsis

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

Example #1 Using protect()

Worksheet::setFirstSheet
Worksheet::setColumn
Spreadsheet_Excel_Writer


Set the width of a single column or a range of columns.

Worksheet::protect
Worksheet::setSelection
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setColumn

(No version information available, might be only in CVS)

Worksheet::setColumn — Set the width of a single column or a range of columns.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setColumn()/funcdef paramdef integer $firstcol /paramdef paramdef integer $lastcol /paramdef paramdef float $width /paramdef paramdef mixed $format=0 /paramdef paramdef integer $hidden=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setColumn()

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();
Worksheet::protect
Worksheet::setSelection
Spreadsheet_Excel_Writer


Set which cell or cells are selected in a worksheet

Worksheet::setColumn
Worksheet::freezePanes
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setSelection

(No version information available, might be only in CVS)

Worksheet::setSelection — Set which cell or cells are selected in a worksheet

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setSelection()/funcdef paramdef integer $first_row /paramdef paramdef integer $first_column /paramdef paramdef integer $last_row /paramdef paramdef integer $last_column /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setSelection()

Worksheet::setColumn
Worksheet::freezePanes
Spreadsheet_Excel_Writer


Set panes and mark them as frozen.

Worksheet::setSelection
Worksheet::thawPanes
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::freezePanes

(No version information available, might be only in CVS)

Worksheet::freezePanes — Set panes and mark them as frozen.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::freezePanes()/funcdef paramdef array $panes /paramdef /funcprototype /funcsynopsis

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 menuchoiceguimenuWindow/guimenuguimenuFreeze Panes/guimenu/menuchoice 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

Example #1 Using freezePanes()

$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:

/* Freeze the first six rows and start the scrollable region at row nine: */
$worksheet->freezePanes(array(6, 0, 9, 0));
Worksheet::setSelection
Worksheet::thawPanes
Spreadsheet_Excel_Writer


Set panes and mark them as unfrozen.

Worksheet::freezePanes
Worksheet::setPortrait
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::thawPanes

(No version information available, might be only in CVS)

Worksheet::thawPanes — Set panes and mark them as unfrozen.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::thawPanes()/funcdef paramdef array $panes /paramdef /funcprototype /funcsynopsis

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

Example #1 Using thawPanes()

Worksheet::freezePanes
Worksheet::setPortrait
Spreadsheet_Excel_Writer


Set the page orientation as portrait.

Worksheet::thawPanes
Worksheet::setLandscape
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setPortrait

(No version information available, might be only in CVS)

Worksheet::setPortrait — Set the page orientation as portrait.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setPortrait()/funcdef paramdef /funcprototype /funcsynopsis

Description

Set the page orientation as portrait.

Note

This function can not be called statically.

Example

Example #1 Using setPortrait()

Worksheet::thawPanes
Worksheet::setLandscape
Spreadsheet_Excel_Writer


Set the page orientation as landscape.

Worksheet::setPortrait
Worksheet::setPaper
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setLandscape

(No version information available, might be only in CVS)

Worksheet::setLandscape — Set the page orientation as landscape.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setLandscape()/funcdef paramdef /funcprototype /funcsynopsis

Description

Set the page orientation as landscape.

Note

This function can not be called statically.

Example

Example #1 Using setLandscape()

Worksheet::setPortrait
Worksheet::setPaper
Spreadsheet_Excel_Writer


Set the paper type. Ex. 1 = US Letter, 9 = A4

Worksheet::setLandscape
Worksheet::setHeader
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setPaper

(No version information available, might be only in CVS)

Worksheet::setPaper — Set the paper type. Ex. 1 = US Letter, 9 = A4

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setPaper()/funcdef paramdef integer $size=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
?>
Worksheet::setLandscape
Worksheet::setHeader
Spreadsheet_Excel_Writer


Set the page header caption and optional margin.

Worksheet::setPaper
Worksheet::setFooter
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setHeader

(No version information available, might be only in CVS)

Worksheet::setHeader — Set the page header caption and optional margin.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setHeader()/funcdef paramdef string $string /paramdef paramdef float $margin=0.5 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setHeader()

Worksheet::setPaper
Worksheet::setFooter
Spreadsheet_Excel_Writer


Set the page footer caption and optional margin.

Worksheet::setHeader
Worksheet::centerHorizontally
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setFooter

(No version information available, might be only in CVS)

Worksheet::setFooter — Set the page footer caption and optional margin.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setFooter()/funcdef paramdef string $string /paramdef paramdef float $margin=0.5 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setFooter()

Worksheet::setHeader
Worksheet::centerHorizontally
Spreadsheet_Excel_Writer


Center the page horizontally.

Worksheet::setFooter
Worksheet::centerVertically
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::centerHorizontally

(No version information available, might be only in CVS)

Worksheet::centerHorizontally — Center the page horizontally.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::centerHorizontally()/funcdef paramdef integer $center=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using centerHorizontally()

Worksheet::setFooter
Worksheet::centerVertically
Spreadsheet_Excel_Writer


Center the page vertically.

Worksheet::centerHorizontally
Worksheet::setMargins
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::centerVertically

(No version information available, might be only in CVS)

Worksheet::centerVertically — Center the page vertically.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::centerVertically()/funcdef paramdef integer $center=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using centerVertically()

Worksheet::centerHorizontally
Worksheet::setMargins
Spreadsheet_Excel_Writer


Set all the page margins to the same value in inches.

Worksheet::centerVertically
Worksheet::setMargins_LR
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMargins

(No version information available, might be only in CVS)

Worksheet::setMargins — Set all the page margins to the same value in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMargins()/funcdef paramdef float $margin /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMargins()

Worksheet::centerVertically
Worksheet::setMargins_LR
Spreadsheet_Excel_Writer


Set the left and right margins to the same value in inches.

Worksheet::setMargins
Worksheet::setMargins_TB
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMargins_LR

(No version information available, might be only in CVS)

Worksheet::setMargins_LR — Set the left and right margins to the same value in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMargins_LR()/funcdef paramdef float $margin /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMargins_LR()

Worksheet::setMargins
Worksheet::setMargins_TB
Spreadsheet_Excel_Writer


Set the top and bottom margins to the same value in inches.

Worksheet::setMargins_LR
Worksheet::setMarginLeft
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMargins_TB

(No version information available, might be only in CVS)

Worksheet::setMargins_TB — Set the top and bottom margins to the same value in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMargins_TB()/funcdef paramdef float $margin /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMargins_TB()

Worksheet::setMargins_LR
Worksheet::setMarginLeft
Spreadsheet_Excel_Writer


Set the left margin in inches.

Worksheet::setMargins_TB
Worksheet::setMarginRight
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMarginLeft

(No version information available, might be only in CVS)

Worksheet::setMarginLeft — Set the left margin in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMarginLeft()/funcdef paramdef float $margin=0.75 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMarginLeft()

Worksheet::setMargins_TB
Worksheet::setMarginRight
Spreadsheet_Excel_Writer


Set the right margin in inches.

Worksheet::setMarginLeft
Worksheet::setMarginTop
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMarginRight

(No version information available, might be only in CVS)

Worksheet::setMarginRight — Set the right margin in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMarginRight()/funcdef paramdef float $margin=0.75 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMarginRight()

Worksheet::setMarginLeft
Worksheet::setMarginTop
Spreadsheet_Excel_Writer


Set the top margin in inches.

Worksheet::setMarginRight
Worksheet::setMarginBottom
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMarginTop

(No version information available, might be only in CVS)

Worksheet::setMarginTop — Set the top margin in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMarginTop()/funcdef paramdef float $margin=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMarginTop()

Worksheet::setMarginRight
Worksheet::setMarginBottom
Spreadsheet_Excel_Writer


Set the bottom margin in inches.

Worksheet::setMarginTop
Worksheet::repeatRows
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setMarginBottom

(No version information available, might be only in CVS)

Worksheet::setMarginBottom — Set the bottom margin in inches.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setMarginBottom()/funcdef paramdef float $margin=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMarginBottom()

Worksheet::setMarginTop
Worksheet::repeatRows
Spreadsheet_Excel_Writer


Set the rows to repeat at the top of each printed page.

Worksheet::setMarginBottom
Worksheet::repeatColumns
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::repeatRows

(No version information available, might be only in CVS)

Worksheet::repeatRows — Set the rows to repeat at the top of each printed page.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::repeatRows()/funcdef paramdef integer $first_row /paramdef paramdef integer $last_row=NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
?>
Worksheet::setMarginBottom
Worksheet::repeatColumns
Spreadsheet_Excel_Writer


Set the columns to repeat at the left hand side of each printed page.

Worksheet::repeatRows
Worksheet::printArea
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::repeatColumns

(No version information available, might be only in CVS)

Worksheet::repeatColumns — Set the columns to repeat at the left hand side of each printed page.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::repeatColumns()/funcdef paramdef integer $first_col /paramdef paramdef integer $last_col=NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Using repeatColumns()

Worksheet::repeatRows
Worksheet::printArea
Spreadsheet_Excel_Writer


Set the area of each worksheet that will be printed.

Worksheet::repeatColumns
Worksheet::hideGridlines
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::printArea

(No version information available, might be only in CVS)

Worksheet::printArea — Set the area of each worksheet that will be printed.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::printArea()/funcdef paramdef integer $first_row /paramdef paramdef integer $first_col /paramdef paramdef integer $last_row /paramdef paramdef integer $last_col /paramdef /funcprototype /funcsynopsis

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

Example #1 Using printArea()

Worksheet::repeatColumns
Worksheet::hideGridlines
Spreadsheet_Excel_Writer


Set the option to hide gridlines on the printed page.

Worksheet::printArea
Worksheet::printRowColHeaders
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::hideGridlines

(No version information available, might be only in CVS)

Worksheet::hideGridlines — Set the option to hide gridlines on the printed page.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::hideGridlines()/funcdef paramdef /funcprototype /funcsynopsis

Description

Set the option to hide gridlines on the printed page.

Note

This function can not be called statically.

Example

Example #1 Using hideGridlines()

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();
Worksheet::printArea
Worksheet::printRowColHeaders
Spreadsheet_Excel_Writer


Set the option to print the row and column headers on the printed page.

Worksheet::hideGridlines
Worksheet::fitToPages
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::printRowColHeaders

(No version information available, might be only in CVS)

Worksheet::printRowColHeaders — Set the option to print the row and column headers on the printed page.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::printRowColHeaders()/funcdef paramdef integer $print=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using printRowColHeaders()

Worksheet::hideGridlines
Worksheet::fitToPages
Spreadsheet_Excel_Writer


Store the vertical and horizontal number of pages that will define the

Worksheet::printRowColHeaders
Worksheet::setHPagebreaks
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::fitToPages

(No version information available, might be only in CVS)

Worksheet::fitToPages — Store the vertical and horizontal number of pages that will define the

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::fitToPages()/funcdef paramdef integer $width /paramdef paramdef integer $height /paramdef /funcprototype /funcsynopsis

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

Example #1 Using fitToPages()

Worksheet::printRowColHeaders
Worksheet::setHPagebreaks
Spreadsheet_Excel_Writer


Store the horizontal page breaks on a worksheet (for printing).

Worksheet::fitToPages
Worksheet::setVPagebreaks
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setHPagebreaks

(No version information available, might be only in CVS)

Worksheet::setHPagebreaks — Store the horizontal page breaks on a worksheet (for printing).

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setHPagebreaks()/funcdef paramdef array $breaks /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setHPagebreaks()

Worksheet::fitToPages
Worksheet::setVPagebreaks
Spreadsheet_Excel_Writer


Store the vertical page breaks on a worksheet (for printing).

Worksheet::setHPagebreaks
Worksheet::setZoom
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setVPagebreaks

(No version information available, might be only in CVS)

Worksheet::setVPagebreaks — Store the vertical page breaks on a worksheet (for printing).

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setVPagebreaks()/funcdef paramdef array $breaks /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setVPagebreaks()

Worksheet::setHPagebreaks
Worksheet::setZoom
Spreadsheet_Excel_Writer


Set the worksheet zoom factor.

Worksheet::setVPagebreaks
Worksheet::setPrintScale
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setZoom

(No version information available, might be only in CVS)

Worksheet::setZoom — Set the worksheet zoom factor.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setZoom()/funcdef paramdef integer $scale=100 /paramdef /funcprototype /funcsynopsis

Description

Set the worksheet zoom factor.

Parameter

  • integer $scale - The zoom factor

Note

This function can not be called statically.

Example

Example #1 Using setZoom()

Worksheet::setVPagebreaks
Worksheet::setPrintScale
Spreadsheet_Excel_Writer


Set the scale factor for the printed page.

Worksheet::setZoom
Worksheet::write
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setPrintScale

(No version information available, might be only in CVS)

Worksheet::setPrintScale — Set the scale factor for the printed page.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setPrintScale()/funcdef paramdef integer $scale=100 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setPrintScale()

Worksheet::setZoom
Worksheet::write
Spreadsheet_Excel_Writer


Map to the appropriate write method acording to the token recieved.

Worksheet::setPrintScale
Worksheet::writeNumber
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::write

(No version information available, might be only in CVS)

Worksheet::write — Map to the appropriate write method acording to the token recieved.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::write()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef mixed $token /paramdef paramdef mixed $format=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using write()

Worksheet::setPrintScale
Worksheet::writeNumber
Spreadsheet_Excel_Writer


Write a double to the specified row and column (zero indexed).

Worksheet::write
Worksheet::writeString
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::writeNumber

(No version information available, might be only in CVS)

Worksheet::writeNumber — Write a double to the specified row and column (zero indexed).

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::writeNumber()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef float $num /paramdef paramdef mixed $format=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using writeNumber()

Worksheet::write
Worksheet::writeString
Spreadsheet_Excel_Writer


Write a string to the specified row and column (zero indexed).

Worksheet::writeNumber
Worksheet::writeNote
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::writeString

(No version information available, might be only in CVS)

Worksheet::writeString — Write a string to the specified row and column (zero indexed).

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::writeString()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef string $str /paramdef paramdef mixed $format=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using writeString()

Worksheet::writeNumber
Worksheet::writeNote
Spreadsheet_Excel_Writer


Writes a note associated with the cell given by the row and column.

Worksheet::writeString
Worksheet::writeBlank
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::writeNote

(No version information available, might be only in CVS)

Worksheet::writeNote — Writes a note associated with the cell given by the row and column.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::writeNote()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef string $note /paramdef /funcprototype /funcsynopsis

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

Example #1 Using writeNote()

Worksheet::writeString
Worksheet::writeBlank
Spreadsheet_Excel_Writer


Write a blank cell to the specified row and column (zero indexed).

Worksheet::writeNote
Worksheet::writeFormula
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::writeBlank

(No version information available, might be only in CVS)

Worksheet::writeBlank — Write a blank cell to the specified row and column (zero indexed).

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::writeBlank()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef mixed $format /paramdef /funcprototype /funcsynopsis

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

Example #1 Using writeBlank()

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();
Worksheet::writeNote
Worksheet::writeFormula
Spreadsheet_Excel_Writer


Write a formula to the specified row and column (zero indexed).

Worksheet::writeBlank
Worksheet::writeUrl
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::writeFormula

(No version information available, might be only in CVS)

Worksheet::writeFormula — Write a formula to the specified row and column (zero indexed).

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefinteger Worksheet::writeFormula()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef string $formula /paramdef paramdef mixed $format=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using writeFormula()

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();
Worksheet::writeBlank
Worksheet::writeUrl
Spreadsheet_Excel_Writer


Write a hyperlink. This is comprised of two elements: the visible label and

Worksheet::writeFormula
Worksheet::setRow
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::writeUrl

(No version information available, might be only in CVS)

Worksheet::writeUrl — Write a hyperlink. This is comprised of two elements: the visible label and

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::writeUrl()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef string $url /paramdef paramdef string $string='' /paramdef paramdef mixed $format=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using writeUrl()

Worksheet::writeFormula
Worksheet::setRow
Spreadsheet_Excel_Writer


This method is used to set the height and XF format for a row.

Worksheet::writeUrl
Worksheet::mergeCells
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setRow

(No version information available, might be only in CVS)

Worksheet::setRow — This method is used to set the height and XF format for a row.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setRow()/funcdef paramdef integer $row /paramdef paramdef integer $height /paramdef paramdef mixed $format=0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setRow()

Worksheet::writeUrl
Worksheet::mergeCells
Spreadsheet_Excel_Writer


This is an Excel97/2000 method. It is required to perform more complicated

Worksheet::setRow
Worksheet::insertBitmap
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::mergeCells

(No version information available, might be only in CVS)

Worksheet::mergeCells — This is an Excel97/2000 method. It is required to perform more complicated

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::mergeCells()/funcdef paramdef integer $first_row /paramdef paramdef integer $first_col /paramdef paramdef integer $last_row /paramdef paramdef integer $last_col /paramdef /funcprototype /funcsynopsis

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

Example #1 Using mergeCells()

Worksheet::setRow
Worksheet::insertBitmap
Spreadsheet_Excel_Writer


Insert a 24bit bitmap image in a worksheet. The main record required is

Worksheet::mergeCells
Worksheet::setOutline
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::insertBitmap

(No version information available, might be only in CVS)

Worksheet::insertBitmap — Insert a 24bit bitmap image in a worksheet. The main record required is

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::insertBitmap()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef paramdef string $bitmap /paramdef paramdef integer $x=0 /paramdef paramdef integer $y=0 /paramdef paramdef integer $scale_x=1 /paramdef paramdef integer $scale_y=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using insertBitmap()

Worksheet::mergeCells
Worksheet::setOutline
Spreadsheet_Excel_Writer


This method sets the properties for outlining and grouping

Worksheet::insertBitmap
Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer
Spreadsheet_Excel_Writer
PHP Manual

Worksheet::setOutline

(No version information available, might be only in CVS)

Worksheet::setOutline — This method sets the properties for outlining and grouping

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Worksheet::setOutline()/funcdef paramdef bool $visible=true /paramdef paramdef bool $symbols_below=true /paramdef paramdef bool $symbols_right=true /paramdef paramdef bool $auto_style=false /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setOutline()

Worksheet::insertBitmap
Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer
Spreadsheet_Excel_Writer


The constructor. It just creates a Workbook

Worksheet::setOutline
Spreadsheet_Excel_Writer::send
Spreadsheet_Excel_Writer
PHP Manual

Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer

(No version information available, might be only in CVS)

Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer — The constructor. It just creates a Workbook

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefobject The Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer()/funcdef paramdef string $filename='' /paramdef /funcprototype /funcsynopsis

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

Example #1 Using Spreadsheet_Excel_Writer()

Worksheet::setOutline
Spreadsheet_Excel_Writer::send
Spreadsheet_Excel_Writer


Send HTTP headers for the Excel file.

Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer
Spreadsheet_Excel_Writer::rowcolToCell
Spreadsheet_Excel_Writer
PHP Manual

Spreadsheet_Excel_Writer::send

(No version information available, might be only in CVS)

Spreadsheet_Excel_Writer::send — Send HTTP headers for the Excel file.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Spreadsheet_Excel_Writer::send()/funcdef paramdef string $filename /paramdef /funcprototype /funcsynopsis

Description

Send HTTP headers for the Excel file.

Parameter

  • string $filename - The filename to use for HTTP headers

Note

This function can not be called statically.

Example

Example #1 Using send()

Spreadsheet_Excel_Writer::Spreadsheet_Excel_Writer
Spreadsheet_Excel_Writer::rowcolToCell
Spreadsheet_Excel_Writer


Utility function for writing formulas.

Spreadsheet_Excel_Writer::send
Format::setAlign
Spreadsheet_Excel_Writer
PHP Manual

Spreadsheet_Excel_Writer::rowcolToCell

(No version information available, might be only in CVS)

Spreadsheet_Excel_Writer::rowcolToCell — Utility function for writing formulas.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefstring Spreadsheet_Excel_Writer::rowcolToCell()/funcdef paramdef integer $row /paramdef paramdef integer $col /paramdef /funcprototype /funcsynopsis

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

Example #1 Using rowcolToCell()

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();
Spreadsheet_Excel_Writer::send
Format::setAlign
Spreadsheet_Excel_Writer


Set cell alignment.

Spreadsheet_Excel_Writer::rowcolToCell
Format::setVAlign
Spreadsheet_Excel_Writer
PHP Manual

Format::setAlign

(No version information available, might be only in CVS)

Format::setAlign — Set cell alignment.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setAlign()/funcdef paramdef string $location /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setAlign()

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();
Spreadsheet_Excel_Writer::rowcolToCell
Format::setVAlign
Spreadsheet_Excel_Writer


Set cell alignment.

Format::setAlign
Format::setHAlign
Spreadsheet_Excel_Writer
PHP Manual

Format::setVAlign

(No version information available, might be only in CVS)

Format::setVAlign — Set cell alignment.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setVAlign()/funcdef paramdef string $location /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setVAlign()

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();
Format::setAlign
Format::setHAlign
Spreadsheet_Excel_Writer


Set cell alignment.

Format::setVAlign
Format::setMerge
Spreadsheet_Excel_Writer
PHP Manual

Format::setHAlign

(No version information available, might be only in CVS)

Format::setHAlign — Set cell alignment.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setHAlign()/funcdef paramdef string $location /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setHAlign()

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();
Format::setVAlign
Format::setMerge
Spreadsheet_Excel_Writer


This is an alias for the unintuitive setAlign('merge')

Format::setHAlign
Format::setBold
Spreadsheet_Excel_Writer
PHP Manual

Format::setMerge

(No version information available, might be only in CVS)

Format::setMerge — This is an alias for the unintuitive setAlign('merge')

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setMerge()/funcdef paramdef /funcprototype /funcsynopsis

Description

This is an alias for the unintuitive setAlign('merge')

Note

This function can not be called statically.

Example

Example #1 Using setMerge()

Format::setHAlign
Format::setBold
Spreadsheet_Excel_Writer


Sets the boldness of the text.

Format::setMerge
Format::setBottom
Spreadsheet_Excel_Writer
PHP Manual

Format::setBold

(No version information available, might be only in CVS)

Format::setBold — Sets the boldness of the text.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setBold()/funcdef paramdef integer $weight=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setBold()

Format::setMerge
Format::setBottom
Spreadsheet_Excel_Writer


Sets the width for the bottom border of the cell

Format::setBold
Format::setTop
Spreadsheet_Excel_Writer
PHP Manual

Format::setBottom

(No version information available, might be only in CVS)

Format::setBottom — Sets the width for the bottom border of the cell

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setBottom()/funcdef paramdef integer $style /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setBottom()

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();
Format::setBold
Format::setTop
Spreadsheet_Excel_Writer


Sets the width for the top border of the cell

Format::setBottom
Format::setLeft
Spreadsheet_Excel_Writer
PHP Manual

Format::setTop

(No version information available, might be only in CVS)

Format::setTop — Sets the width for the top border of the cell

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setTop()/funcdef paramdef integer $style /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setTop()

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();
Format::setBottom
Format::setLeft
Spreadsheet_Excel_Writer


Sets the width for the left border of the cell

Format::setTop
Format::setRight
Spreadsheet_Excel_Writer
PHP Manual

Format::setLeft

(No version information available, might be only in CVS)

Format::setLeft — Sets the width for the left border of the cell

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setLeft()/funcdef paramdef integer $style /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setLeft()

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();
Format::setTop
Format::setRight
Spreadsheet_Excel_Writer


Sets the width for the right border of the cell

Format::setLeft
Format::setBorder
Spreadsheet_Excel_Writer
PHP Manual

Format::setRight

(No version information available, might be only in CVS)

Format::setRight — Sets the width for the right border of the cell

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setRight()/funcdef paramdef integer $style /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setRight()

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();
Format::setLeft
Format::setBorder
Spreadsheet_Excel_Writer


Set cells borders to the same style

Format::setRight
Format::setBorderColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setBorder

(No version information available, might be only in CVS)

Format::setBorder — Set cells borders to the same style

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setBorder()/funcdef paramdef integer $style /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setBorder()

Format::setRight
Format::setBorderColor
Spreadsheet_Excel_Writer


Sets all the cell's borders to the same color

Format::setBorder
Format::setBottomColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setBorderColor

(No version information available, might be only in CVS)

Format::setBorderColor — Sets all the cell's borders to the same color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setBorderColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setBorderColor()

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();
Format::setBorder
Format::setBottomColor
Spreadsheet_Excel_Writer


Sets the cell's bottom border color

Format::setBorderColor
Format::setTopColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setBottomColor

(No version information available, might be only in CVS)

Format::setBottomColor — Sets the cell's bottom border color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setBottomColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setBottomColor()

Format::setBorderColor
Format::setTopColor
Spreadsheet_Excel_Writer


Sets the cell's top border color

Format::setBottomColor
Format::setLeftColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setTopColor

(No version information available, might be only in CVS)

Format::setTopColor — Sets the cell's top border color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setTopColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setTopColor()

Format::setBottomColor
Format::setLeftColor
Spreadsheet_Excel_Writer


Sets the cell's left border color

Format::setTopColor
Format::setRightColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setLeftColor

(No version information available, might be only in CVS)

Format::setLeftColor — Sets the cell's left border color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setLeftColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setLeftColor()

Format::setTopColor
Format::setRightColor
Spreadsheet_Excel_Writer


Sets the cell's right border color

Format::setLeftColor
Format::setFgColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setRightColor

(No version information available, might be only in CVS)

Format::setRightColor — Sets the cell's right border color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setRightColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setRightColor()

Format::setLeftColor
Format::setFgColor
Spreadsheet_Excel_Writer


Sets the cell's foreground color

Format::setRightColor
Format::setBgColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setFgColor

(No version information available, might be only in CVS)

Format::setFgColor — Sets the cell's foreground color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setFgColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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 » citetitleColor Palette and the 56 Excel ColorIndex Colors/citetitle. 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

Example #1 Using setFgColor()

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()

Format::setRightColor
Format::setBgColor
Spreadsheet_Excel_Writer


Sets the cell's background color

Format::setFgColor
Format::setColor
Spreadsheet_Excel_Writer
PHP Manual

Format::setBgColor

(No version information available, might be only in CVS)

Format::setBgColor — Sets the cell's background color

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setBgColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setBgColor()

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()

Format::setFgColor
Format::setColor
Spreadsheet_Excel_Writer


Sets the color of a cell's content

Format::setBgColor
Format::setPattern
Spreadsheet_Excel_Writer
PHP Manual

Format::setColor

(No version information available, might be only in CVS)

Format::setColor — Sets the color of a cell's content

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setColor()/funcdef paramdef mixed $color /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setColor()

See

setFgColor(), setBgColor()

Format::setBgColor
Format::setPattern
Spreadsheet_Excel_Writer


Sets the fill pattern attribute of a cell

Format::setColor
Format::setUnderline
Spreadsheet_Excel_Writer
PHP Manual

Format::setPattern

(No version information available, might be only in CVS)

Format::setPattern — Sets the fill pattern attribute of a cell

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setPattern()/funcdef paramdef integer $arg=1 /paramdef /funcprototype /funcsynopsis

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

Example #1 How background and foreground colors interact with patterns

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()

Format::setColor
Format::setUnderline
Spreadsheet_Excel_Writer


Sets the underline of the text

Format::setPattern
Format::setItalic
Spreadsheet_Excel_Writer
PHP Manual

Format::setUnderline

(No version information available, might be only in CVS)

Format::setUnderline — Sets the underline of the text

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setUnderline()/funcdef paramdef integer $underline /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setUnderline()

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);
Format::setPattern
Format::setItalic
Spreadsheet_Excel_Writer


Sets the font style as italic

Format::setUnderline
Format::setSize
Spreadsheet_Excel_Writer
PHP Manual

Format::setItalic

(No version information available, might be only in CVS)

Format::setItalic — Sets the font style as italic

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setItalic()/funcdef paramdef /funcprototype /funcsynopsis

Description

Sets the font style as italic

Note

This function can not be called statically.

Example

Example #1 Using setItalic()

Format::setUnderline
Format::setSize
Spreadsheet_Excel_Writer


Sets the font size

Format::setItalic
Format::setTextWrap
Spreadsheet_Excel_Writer
PHP Manual

Format::setSize

(No version information available, might be only in CVS)

Format::setSize — Sets the font size

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setSize()/funcdef paramdef integer $size /paramdef /funcprototype /funcsynopsis

Description

Sets the font size

Parameter

  • integer $size - The font size (in pixels I think).

Note

This function can not be called statically.

Example

Example #1 Using setSize()

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();
Format::setItalic
Format::setTextWrap
Spreadsheet_Excel_Writer


Sets text wrapping

Format::setSize
Format::setTextRotation
Spreadsheet_Excel_Writer
PHP Manual

Format::setTextWrap

(No version information available, might be only in CVS)

Format::setTextWrap — Sets text wrapping

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setTextWrap()/funcdef paramdef /funcprototype /funcsynopsis

Description

Sets text wrapping

Note

This function can not be called statically.

Example

Example #1 Using setTextWrap()

Format::setSize
Format::setTextRotation
Spreadsheet_Excel_Writer


Sets the orientation of the text

Format::setTextWrap
Format::setNumFormat
Spreadsheet_Excel_Writer
PHP Manual

Format::setTextRotation

(No version information available, might be only in CVS)

Format::setTextRotation — Sets the orientation of the text

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setTextRotation()/funcdef paramdef integer $angle /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setTextRotation()

Format::setTextWrap
Format::setNumFormat
Spreadsheet_Excel_Writer


Sets the numeric format.

Format::setTextRotation
Format::setStrikeOut
Spreadsheet_Excel_Writer
PHP Manual

Format::setNumFormat

(No version information available, might be only in CVS)

Format::setNumFormat — Sets the numeric format.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setNumFormat()/funcdef paramdef string $num_format /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setNumFormat()

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();
Format::setTextRotation
Format::setStrikeOut
Spreadsheet_Excel_Writer


Sets font as strikeout.

Format::setNumFormat
Format::setOutLine
Spreadsheet_Excel_Writer
PHP Manual

Format::setStrikeOut

(No version information available, might be only in CVS)

Format::setStrikeOut — Sets font as strikeout.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setStrikeOut()/funcdef paramdef /funcprototype /funcsynopsis

Description

Sets font as strikeout.

Note

This function can not be called statically.

Example

Example #1 Using setStrikeOut()

Format::setNumFormat
Format::setOutLine
Spreadsheet_Excel_Writer


Sets outlining for a font.

Format::setStrikeOut
Format::setShadow
Spreadsheet_Excel_Writer
PHP Manual

Format::setOutLine

(No version information available, might be only in CVS)

Format::setOutLine — Sets outlining for a font.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setOutLine()/funcdef paramdef /funcprototype /funcsynopsis

Description

Sets outlining for a font.

Note

This function can not be called statically.

Example

Example #1 Using setOutLine()

Format::setStrikeOut
Format::setShadow
Spreadsheet_Excel_Writer


Sets font as shadow.

Format::setOutLine
Format::setScript
Spreadsheet_Excel_Writer
PHP Manual

Format::setShadow

(No version information available, might be only in CVS)

Format::setShadow — Sets font as shadow.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setShadow()/funcdef paramdef /funcprototype /funcsynopsis

Description

Sets font as shadow.

Note

This function can not be called statically.

Example

Example #1 Using setShadow()

Format::setOutLine
Format::setScript
Spreadsheet_Excel_Writer


Sets the script type of the text

Format::setShadow
Format::setFontFamily
Spreadsheet_Excel_Writer
PHP Manual

Format::setScript

(No version information available, might be only in CVS)

Format::setScript — Sets the script type of the text

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setScript()/funcdef paramdef integer $script /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setScript()

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);
Format::setShadow
Format::setFontFamily
Spreadsheet_Excel_Writer


Sets the font family.

Spreadsheet_Excel_Writer
File System
Spreadsheet_Excel_Writer
PHP Manual

Format::setFontFamily

(No version information available, might be only in CVS)

Format::setFontFamily — Sets the font family.

funcsynopsis funcsynopsisinfo require_once "Spreadsheet/Excel/Writer.php"; /funcsynopsisinfo funcprototype funcdefvoid Format::setFontFamily()/funcdef paramdef string $font_family /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setFontFamily()

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();
Spreadsheet_Excel_Writer
File System
Spreadsheet_Excel_Writer


File System

Table of Contents

  • Archive-Tar
  • File
  • File_Find
  • File_SMBPasswd
  • File_SearchReplace
  • File_HtAccess

Provides Packages for working with files and file system

Format::setFontFamily
Archive-Tar
Packages


Archive-Tar

Archive_Tar provides an API for handling (compressed) Tar archives.

File System
Archive_Tar::Archive_Tar()
File System


constructor

Archive-Tar
Archive_Tar::add()
Archive-Tar
PHP Manual

Archive_Tar::Archive_Tar()

(No version information available, might be only in CVS)

Archive_Tar::Archive_Tar() — constructor

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefvoid Archive_Tar()/funcdef paramdefstring $tarname /paramdef paramdefmixed $compress = NULL /paramdef /funcprototype /funcsynopsis

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'.

Archive-Tar
Archive_Tar::add()
Archive-Tar


add files or directories

Archive_Tar::Archive_Tar()
Archive_Tar::addModify()
Archive-Tar
PHP Manual

Archive_Tar::add()

(No version information available, might be only in CVS)

Archive_Tar::add() — add files or directories

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean add()/funcdef paramdefmixed $filelist /paramdef /funcprototype /funcsynopsis

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

Example #1 Add files to a compressed archive

$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);
Archive_Tar::Archive_Tar()
Archive_Tar::addModify()
Archive-Tar


add files or directories

Archive_Tar::add()
Archive_Tar::create()
Archive-Tar
PHP Manual

Archive_Tar::addModify()

(No version information available, might be only in CVS)

Archive_Tar::addModify() — add files or directories

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean addModify()/funcdef paramdefmixed $filelist /paramdef paramdefstring $add_dir /paramdef paramdefstring $remove_dir = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 Add files to a compressed archive in a new directory

$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

Example #2 Add files to a compressed archive moving to a new directory

$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

Example #3 Add files to a compressed archive moving to a new directory (especially for Windows)

$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.

Archive_Tar::add()
Archive_Tar::create()
Archive-Tar


create archive file

Archive_Tar::addModify()
Archive_Tar::createModify()
Archive-Tar
PHP Manual

Archive_Tar::create()

(No version information available, might be only in CVS)

Archive_Tar::create() — create archive file

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean create()/funcdef paramdefmixed $filelist /paramdef /funcprototype /funcsynopsis

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

Example #1 Creating an archive

$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);

Example #2 Creating a compressed archive, use a string as create() argument

$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$tar_object->create("file.txt data/ file.log");
Archive_Tar::addModify()
Archive_Tar::createModify()
Archive-Tar


create a new archive

Archive_Tar::create()
Archive_Tar::extract()
Archive-Tar
PHP Manual

Archive_Tar::createModify()

(No version information available, might be only in CVS)

Archive_Tar::createModify() — create a new archive

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean createModify()/funcdef paramdefarray $filelist /paramdef paramdefstring $add_dir /paramdef paramdefstring $remove_dir = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 Create a new compressed archive in a new directory

$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

Example #2 Create a new compressed archive in a new directory (especially for Windows)

$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
Archive_Tar::create()
Archive_Tar::extract()
Archive-Tar


extract files

Archive_Tar::createModify()
Archive_Tar::extractList()
Archive-Tar
PHP Manual

Archive_Tar::extract()

(No version information available, might be only in CVS)

Archive_Tar::extract() — extract files

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean extract()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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

Example #1 Extract compressed archive

$tar = new Archive_Tar('archive.tar.gz', true);
$result = $tar->extract('/home/myFolder');
Archive_Tar::createModify()
Archive_Tar::extractList()
Archive-Tar


extract a list files

Archive_Tar::extract()
Archive_Tar::extractModify()
Archive-Tar
PHP Manual

Archive_Tar::extractList()

(No version information available, might be only in CVS)

Archive_Tar::extractList() — extract a list files

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean extractList()/funcdef paramdefarray $filelist /paramdef paramdefstring $path = '' /paramdef paramdefstring $remove_path = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 Extract compressed archive

// 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
Archive_Tar::extract()
Archive_Tar::extractModify()
Archive-Tar


extract files to a new dir

Archive_Tar::extractList()
Archive_Tar::listContent()
Archive-Tar
PHP Manual

Archive_Tar::extractModify()

(No version information available, might be only in CVS)

Archive_Tar::extractModify() — extract files to a new dir

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean extractModify()/funcdef paramdefstring $path /paramdef paramdefstring $remove_path /paramdef /funcprototype /funcsynopsis

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

Example #1 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

Example #2 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
Archive_Tar::extractList()
Archive_Tar::listContent()
Archive-Tar


list files and directories in archive

Archive_Tar::extractModify()
Archive_Tar::extractInString()
Archive-Tar
PHP Manual

Archive_Tar::listContent()

(No version information available, might be only in CVS)

Archive_Tar::listContent() — list files and directories in archive

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefarray listContent()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 List archive content

$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>";
   }
}
Archive_Tar::extractModify()
Archive_Tar::extractInString()
Archive-Tar


extract one file and return it as a string

Archive_Tar::listContent()
Archive_Tar::addString()
Archive-Tar
PHP Manual

Archive_Tar::extractInString()

(No version information available, might be only in CVS)

Archive_Tar::extractInString() — extract one file and return it as a string

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean extractInString()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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

Example #1 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;
Archive_Tar::listContent()
Archive_Tar::addString()
Archive-Tar


add a string in the archive

Archive-Tar
File
Archive-Tar
PHP Manual

Archive_Tar::addString()

(No version information available, might be only in CVS)

Archive_Tar::addString() — add a string in the archive

funcsynopsis funcsynopsisinfo require_once 'Archive/Tar.php'; /funcsynopsisinfo funcprototype funcdefboolean addString()/funcdef paramdefstring $filename /paramdef paramdefstring $content /paramdef /funcprototype /funcsynopsis

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

Example #1 Add a string in a compressed archive

$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
Archive-Tar
File
Archive-Tar


File

Common file and directory routines

Archive_Tar::addString()
Introduction
File System


Introduction to the File class

File
Constants
File
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 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);

?>
File
Constants
File


Predefined Constants

Introduction
File::buildpath()
File
PHP Manual

Constants

(No version information available, might be only in CVS)

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()

Introduction
File::buildpath()
File


build a path from given parts array

Constants
File::close()
File
PHP Manual

File::buildpath()

(No version information available, might be only in CVS)

File::buildpath() — build a path from given parts array

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::buildpath()/funcdef paramdef array $parts /paramdef paramdef string $separatir = DIRECTORY_SEPARATOR /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Example #1 Using File::write()

<?php
require_once 'File.php';

// deprecated Use File_Util::buildPath() instead.
?>
Constants
File::close()
File


closes an open file pointer

File::buildpath()
File::getTempDir()
File
PHP Manual

File::close()

(No version information available, might be only in CVS)

File::close() — closes an open file pointer

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::close()/funcdef paramdef string $filename /paramdef paramdef string $mode /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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";
}
?>
File::buildpath()
File::getTempDir()
File


retrieves the system's temporary directory

File::close()
File::getTempFile()
File
PHP Manual

File::getTempDir()

(No version information available, might be only in CVS)

File::getTempDir() — retrieves the system's temporary directory

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefstring File::gettempdir()/funcdef paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Example #1 Using File::getTempDir()

<?php
require_once 'File.php';

// deprecated Use File_Util::tmpDir() instead
?>
File::close()
File::getTempFile()
File


returns a path to a temporary file

File::getTempDir()
File::isAbsolute()
File
PHP Manual

File::getTempFile()

(No version information available, might be only in CVS)

File::getTempFile() — returns a path to a temporary file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefstring File::getTempFile()/funcdef paramdef string $dirname = NULL /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Deprecated

deprecated

Note

This function can be called statically.

See

Example

Example #1 Using File::getTempFile()

<?php
require_once 'File.php';

// deprecated Use File_Util::tmpFile() instead
?>
File::getTempDir()
File::isAbsolute()
File


checks wether the given path is an absolute path

File::getTempFile()
File::read()
File
PHP Manual

File::isAbsolute()

(No version information available, might be only in CVS)

File::isAbsolute() — checks wether the given path is an absolute path

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefbool File::isAbsolute()/funcdef paramdef string $path /paramdef /funcprototype /funcsynopsis

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

Example #1 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'.

File::getTempFile()
File::read()
File


read bytes from a file

File::isAbsolute()
File::readAll()
File
PHP Manual

File::read()

(No version information available, might be only in CVS)

File::read() — read bytes from a file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::read()/funcdef paramdef string $filename /paramdef paramdef int $size = FILE_DEFAULT_READSIZE /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 Using File::read()

<?php
require_once 'File.php';

//output 40 bytes of file foo.bar
echo File::read("/path/to/foo.bar", 40);
?>
File::isAbsolute()
File::readAll()
File


reads a complete file

File::read()
File::readChar()
File
PHP Manual

File::readAll()

(No version information available, might be only in CVS)

File::readAll() — reads a complete file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::readAll()/funcdef paramdef string $filename /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 Using File::readAll()

<?php
require_once 'File.php';

?>
File::read()
File::readChar()
File


reads a single character from a file

File::readAll()
File::readLine()
File
PHP Manual

File::readChar()

(No version information available, might be only in CVS)

File::readChar() — reads a single character from a file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::readCharChar()/funcdef paramdef string $filename /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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;
}
?>
File::readAll()
File::readLine()
File


reads a single line from a file

File::readChar()
File::rewind()
File
PHP Manual

File::readLine()

(No version information available, might be only in CVS)

File::readLine() — reads a single line from a file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::readLine()/funcdef paramdef string $filename /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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;
}
?>
File::readChar()
File::rewind()
File


rewinds a file pointer

File::readLine()
File::skipRoot()
File
PHP Manual

File::rewind()

(No version information available, might be only in CVS)

File::rewind() — rewinds a file pointer

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::rewind()/funcdef paramdef string $filename /paramdef paramdef string $mode /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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";
}
?>
File::readLine()
File::skipRoot()
File


strips the root directory from a given path

File::rewind()
File::stripLeadingSeparators()
File
PHP Manual

File::skipRoot()

(No version information available, might be only in CVS)

File::skipRoot() — strips the root directory from a given path

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefstring File::skipRoot()/funcdef paramdef string $path /paramdef /funcprototype /funcsynopsis

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

Example #1 Using File::skipRoot()

<?php
require_once 'File.php';

echo File::skipRoot("/home/foo/bar");
?>

This example prints out home/foo/bar.

File::rewind()
File::stripLeadingSeparators()
File


strip leading separators from a path

File::skipRoot()
File::stripTrailingSeparators()
File
PHP Manual

File::stripLeadingSeparators()

(No version information available, might be only in CVS)

File::stripLeadingSeparators() — strip leading separators from a path

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefstring File::stripLeadingSeparators()/funcdef paramdef string $path /paramdef paramdef string $separator = DIRECTORY_SEPARATOR /paramdef /funcprototype /funcsynopsis

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

Example #1 Using File::stripLeadingSeparators()

<?php
require_once "File.php";

echo File::stripLeadingSeparators("/home/foo/lala/");
?>

This example will print home/foo/lala/.

File::skipRoot()
File::stripTrailingSeparators()
File


strips trailing separators from a path

File::stripLeadingSeparators()
File::unlock()
File
PHP Manual

File::stripTrailingSeparators()

(No version information available, might be only in CVS)

File::stripTrailingSeparators() — strips trailing separators from a path

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefstring File:stripTrailingSeparators()/funcdef paramdef string $path /paramdef paramdef string $separator = DIRECTORY_SEPARATOR /paramdef /funcprototype /funcsynopsis

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

Example #1 Using File:stripTrailingSeparators()

<?php
require_once "File.php";

echo File::stripTrailingSeparators("/home/foo/lala/");
?>

This example will print /home/foo/lala.

File::stripLeadingSeparators()
File::unlock()
File


unlocks a locked file pointer

File::stripTrailingSeparators()
File::write()
File
PHP Manual

File::unlock()

(No version information available, might be only in CVS)

File::unlock() — unlocks a locked file pointer

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::unlock()/funcdef paramdef string $filename /paramdef paramdef string $mode /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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";
}
?>
File::stripTrailingSeparators()
File::write()
File


writes bytes to a file

File::unlock()
File::writeChar()
File
PHP Manual

File::write()

(No version information available, might be only in CVS)

File::write() — writes bytes to a file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::write()/funcdef paramdef string $filename /paramdef paramdef string $char /paramdef paramdef string $mode = FILE_MODE_APPEND /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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";
}
?>
File::unlock()
File::writeChar()
File


writes a single character to a file

File::write()
File::writeLine()
File
PHP Manual

File::writeChar()

(No version information available, might be only in CVS)

File::writeChar() — writes a single character to a file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::writeChar()/funcdef paramdef string $filename /paramdef paramdef string $char /paramdef paramdef string $mode = FILE_MODE_APPEND /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

Description

Parameter

Return value

Throws

Note

This function can be called statically.

See

Example

Example #1 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";
}
?>
File::write()
File::writeLine()
File


writes a single line to a file

File
File_Find
File
PHP Manual

File::writeLine()

(No version information available, might be only in CVS)

File::writeLine() — writes a single line to a file

funcsynopsis funcsynopsisinfo require_once 'File.php'; /funcsynopsisinfo funcprototype funcdefmixed File::writeLine()/funcdef paramdef string $filename /paramdef paramdef string $line /paramdef paramdef string $mode = FILE_MODE_APPEND /paramdef paramdef string $crlf = "\n" /paramdef paramdef mixed $lock = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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";
}
?>
File
File_Find
File


File_Find

Commonly needed functions to search for files and directories

File::writeLine()
Search methods
File System


Types of methods what can be used in search functions

File_Find
File_Find::glob()
File_Find
PHP Manual

Search methods

(No version information available, might be only in CVS)

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

File_Find
File_Find::glob()
File_Find


find matches for a pattern in a directory

Search methods
File_Find::maptree()
File_Find
PHP Manual

File_Find::glob()

(No version information available, might be only in CVS)

File_Find::glob() — find matches for a pattern in a directory

funcsynopsis funcsynopsisinfo require_once 'File/Find.php'; /funcsynopsisinfo funcprototype funcdefarray &File_Find::glob()/funcdef paramdef string $pattern /paramdefparamdef string $dirpath /paramdefparamdef string $pattern_type = 'php' /paramdef /funcprototype /funcsynopsis

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

Example #1 Find all PHP files in current directory

include "File/Find.php";

$dir = ".";
$items = &File_Find::glob( '!.*\.php$!', $dir, 'perl' );

print_r($items);
Search methods
File_Find::maptree()
File_Find


create a view map for a directory

File_Find::glob()
File_Find::mapTreeMultiple()
File_Find
PHP Manual

File_Find::maptree()

(No version information available, might be only in CVS)

File_Find::maptree() — create a view map for a directory

funcsynopsis funcsynopsisinfo require_once 'File/Find.php'; /funcsynopsisinfo funcprototype funcdefarray &File_Find::maptree()/funcdef paramdef string $directory /paramdef /funcprototype /funcsynopsis

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

Example #1 Get the map of a directory

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
)
File_Find::glob()
File_Find::mapTreeMultiple()
File_Find


create a recursive view map for a directory

File_Find::maptree()
File_Find::search()
File_Find
PHP Manual

File_Find::mapTreeMultiple()

(No version information available, might be only in CVS)

File_Find::mapTreeMultiple() — create a recursive view map for a directory

funcsynopsis funcsynopsisinfo require_once 'File/Find.php'; /funcsynopsisinfo funcprototype funcdefarray &File_Find::mapTreeMultiple()/funcdef paramdef string $directory /paramdef paramdef integer $maxrecursion = 0 /paramdef paramdef integer $count = 0 /paramdef /funcprototype /funcsynopsis

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

Example #1 Get the content of a directory including the content of subdirectories

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
      )
)
File_Find::maptree()
File_Find::search()
File_Find


find matches for a pattern in a directory

File_Find
File_SMBPasswd
File_Find
PHP Manual

File_Find::search()

(No version information available, might be only in CVS)

File_Find::search() — find matches for a pattern in a directory

funcsynopsis funcsynopsisinfo require_once 'File/Find.php'; /funcsynopsisinfo funcprototype funcdefarray &File_Find::search()/funcdef paramdef string $pattern /paramdef paramdef string $dirpath /paramdef paramdef string $pattern_type = 'php' /paramdef paramdef bool $fullpath = true /paramdef paramdef string $match = 'files' /paramdef /funcprototype /funcsynopsis

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()

File_Find
File_SMBPasswd
File_Find


File_SMBPasswd

Provides an API for managing SAMBA passwd-style files

File_Find::search()
Introduction
File System


file format

File_SMBPasswd
File_SMBPasswd::File_SMBPasswd()
File_SMBPasswd
PHP Manual

Introduction

(No version information available, might be only in CVS)

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 $.

File_SMBPasswd
File_SMBPasswd::File_SMBPasswd()
File_SMBPasswd


constructor

Introduction
File_SMBPasswd::load()
File_SMBPasswd
PHP Manual

File_SMBPasswd::File_SMBPasswd()

(No version information available, might be only in CVS)

File_SMBPasswd::File_SMBPasswd() — constructor

funcsynopsis funcsynopsisinfo require_once 'File/SMBPasswd.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SMBPasswd::File_SMBPasswd()/funcdef paramdef string $file /paramdef /funcprototype /funcsynopsis

Description

Creates a new File_SMBPasswd object and bind it to the given file.

Parameter

  • string $file - SAMBA password file to read

Introduction
File_SMBPasswd::load()
File_SMBPasswd


load the contents of an existing smbpasswd file

File_SMBPasswd::File_SMBPasswd()
File_SMBPasswd::getFile()
File_SMBPasswd
PHP Manual

File_SMBPasswd::load()

(No version information available, might be only in CVS)

File_SMBPasswd::load() — load the contents of an existing smbpasswd file

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::load()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

?>
File_SMBPasswd::File_SMBPasswd()
File_SMBPasswd::getFile()
File_SMBPasswd


get the value of the file property

File_SMBPasswd::load()
File_SMBPasswd::getAccounts()
File_SMBPasswd
PHP Manual

File_SMBPasswd::getFile()

(No version information available, might be only in CVS)

File_SMBPasswd::getFile() — get the value of the file property

funcsynopsis funcprototype funcdefstring File_SMBPasswd::getFile()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

File_SMBPasswd::load()
File_SMBPasswd::getAccounts()
File_SMBPasswd


get the value of the accounts property

File_SMBPasswd::getFile()
File_SMBPasswd::addAccountEncrypted()
File_SMBPasswd
PHP Manual

File_SMBPasswd::getAccounts()

(No version information available, might be only in CVS)

File_SMBPasswd::getAccounts() — get the value of the accounts property

funcsynopsis funcprototype funcdefarray File_SMBPasswd::getAccounts()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

File_SMBPasswd::getFile()
File_SMBPasswd::addAccountEncrypted()
File_SMBPasswd


adds a new account with pre-encrypted passwords.

File_SMBPasswd::getAccounts()
File_SMBPasswd::addAccount()
File_SMBPasswd
PHP Manual

File_SMBPasswd::addAccountEncrypted()

(No version information available, might be only in CVS)

File_SMBPasswd::addAccountEncrypted() — adds a new account with pre-encrypted passwords.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::addAccountEncrypted()/funcdef paramdefstring $user /paramdef paramdefint $userid /paramdef paramdefstring $lmhash = '' /paramdef paramdefstring $nthash = '' /paramdef paramdefstring $comment = '' /paramdef paramdefstring $flags = '[U ]' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::getAccounts()
File_SMBPasswd::addAccount()
File_SMBPasswd


add a new account with the given plaintext-password.

File_SMBPasswd::addAccountEncrypted()
File_SMBPasswd::addUser()
File_SMBPasswd
PHP Manual

File_SMBPasswd::addAccount()

(No version information available, might be only in CVS)

File_SMBPasswd::addAccount() — add a new account with the given plaintext-password.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::addAccount()/funcdef paramdefstring $user /paramdef paramdefint $userid /paramdef paramdefstring $pass = '' /paramdef paramdefstring $comment = '' /paramdef paramdefstring $flags = '[U ]' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::addAccountEncrypted()
File_SMBPasswd::addUser()
File_SMBPasswd


add a new user with the given plaintext-password.

File_SMBPasswd::addAccount()
File_SMBPasswd::addMachine()
File_SMBPasswd
PHP Manual

File_SMBPasswd::addUser()

(No version information available, might be only in CVS)

File_SMBPasswd::addUser() — add a new user with the given plaintext-password.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::addUser()/funcdef paramdefstring $user /paramdef paramdefint $userid /paramdef paramdefstring $pass = '' /paramdef paramdefstring $comment = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::addAccount()
File_SMBPasswd::addMachine()
File_SMBPasswd


add a new maschine-account with the given plaintext-password.

File_SMBPasswd::addUser()
File_SMBPasswd::modAccountEncrypted()
File_SMBPasswd
PHP Manual

File_SMBPasswd::addMachine()

(No version information available, might be only in CVS)

File_SMBPasswd::addMachine() — add a new maschine-account with the given plaintext-password.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::addMachine()/funcdef paramdefstring $machine /paramdef paramdefint $userid /paramdef paramdefstring $comment = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::addUser()
File_SMBPasswd::modAccountEncrypted()
File_SMBPasswd


modify an existing account with the given encrypted password.

File_SMBPasswd::addMachine()
File_SMBPasswd::modAccount()
File_SMBPasswd
PHP Manual

File_SMBPasswd::modAccountEncrypted()

(No version information available, might be only in CVS)

File_SMBPasswd::modAccountEncrypted() — modify an existing account with the given encrypted password.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::modAccountEncrypted()/funcdef paramdefstring $user /paramdef paramdefint $userid /paramdef paramdefstring $nthash = '' /paramdef paramdefstring $lmhash = '' /paramdef paramdefstring $comment = '' /paramdef paramdefstring $flags = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::addMachine()
File_SMBPasswd::modAccount()
File_SMBPasswd


modify an exsting account with the given plaintext-password.

File_SMBPasswd::modAccountEncrypted()
File_SMBPasswd::modUser()
File_SMBPasswd
PHP Manual

File_SMBPasswd::modAccount()

(No version information available, might be only in CVS)

File_SMBPasswd::modAccount() — modify an exsting account with the given plaintext-password.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::modAccount()/funcdef paramdefstring $user /paramdef paramdefint $userid /paramdef paramdefstring $pass = '' /paramdef paramdefstring $comment = '' /paramdef paramdefstring $flags = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::modAccountEncrypted()
File_SMBPasswd::modUser()
File_SMBPasswd


modify an exsting account with the given plaintext-password.

File_SMBPasswd::modAccount()
File_SMBPasswd::delAccount()
File_SMBPasswd
PHP Manual

File_SMBPasswd::modUser()

(No version information available, might be only in CVS)

File_SMBPasswd::modUser() — modify an exsting account with the given plaintext-password.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::modUser()/funcdef paramdefstring $user /paramdef paramdefint $userid /paramdef paramdefstring $pass = '' /paramdef paramdefstring $comment = '' /paramdef paramdefstring $flags = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::modAccount()
File_SMBPasswd::delAccount()
File_SMBPasswd


deletes an existing account.

File_SMBPasswd::modUser()
File_SMBPasswd::delUser()
File_SMBPasswd
PHP Manual

File_SMBPasswd::delAccount()

(No version information available, might be only in CVS)

File_SMBPasswd::delAccount() — deletes an existing account.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::delAccount()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::modUser()
File_SMBPasswd::delUser()
File_SMBPasswd


deletes an existing user.

File_SMBPasswd::delAccount()
File_SMBPasswd::verifyAccountEncrypted()
File_SMBPasswd
PHP Manual

File_SMBPasswd::delUser()

(No version information available, might be only in CVS)

File_SMBPasswd::delUser() — deletes an existing user.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::delUser()/funcdef paramdefstring $user /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}

?>
File_SMBPasswd::delAccount()
File_SMBPasswd::verifyAccountEncrypted()
File_SMBPasswd


Verifies the given account with the given encrypted passwords.

File_SMBPasswd::delUser()
File_SMBPasswd::verifyAccount()
File_SMBPasswd
PHP Manual

File_SMBPasswd::verifyAccountEncrypted()

(No version information available, might be only in CVS)

File_SMBPasswd::verifyAccountEncrypted() — Verifies the given account with the given encrypted passwords.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::verifyAccountEncrypted()/funcdef paramdefstring $user /paramdef paramdefstring $nthash /paramdef paramdefstring $lmhash = '' /paramdef /funcprototype /funcsynopsis

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

Example #1 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";
}

?>
File_SMBPasswd::delUser()
File_SMBPasswd::verifyAccount()
File_SMBPasswd


Verifies the given account with the given plaintext passwords.

File_SMBPasswd::verifyAccountEncrypted()
File_SMBPasswd::lock()
File_SMBPasswd
PHP Manual

File_SMBPasswd::verifyAccount()

(No version information available, might be only in CVS)

File_SMBPasswd::verifyAccount() — Verifies the given account with the given plaintext passwords.

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::verifyAccount()/funcdef paramdefstring $user /paramdef paramdefstring $pass /paramdef /funcprototype /funcsynopsis

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

Example #1 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";
}

?>
File_SMBPasswd::verifyAccountEncrypted()
File_SMBPasswd::lock()
File_SMBPasswd


lock the smbpasswd file

File_SMBPasswd::verifyAccount()
File_SMBPasswd::unlock()
File_SMBPasswd
PHP Manual

File_SMBPasswd::lock()

(No version information available, might be only in CVS)

File_SMBPasswd::lock() — lock the smbpasswd file

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::lock()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

?>
File_SMBPasswd::verifyAccount()
File_SMBPasswd::unlock()
File_SMBPasswd


unlock the smbpasswd file

File_SMBPasswd::lock()
File_SMBPasswd::save()
File_SMBPasswd
PHP Manual

File_SMBPasswd::unlock()

(No version information available, might be only in CVS)

File_SMBPasswd::unlock() — unlock the smbpasswd file

funcsynopsis funcprototype funcdefmixed File_SMBPasswd::unlock()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

?>
File_SMBPasswd::lock()
File_SMBPasswd::save()
File_SMBPasswd


saves the smbpasswd file

File_SMBPasswd::unlock()
File_SMBPasswd::printAccounts()
File_SMBPasswd
PHP Manual

File_SMBPasswd::save()

(No version information available, might be only in CVS)

File_SMBPasswd::save() — saves the smbpasswd file

funcsynopsis funcprototype funcdefmixed File_SMBPasswds:save()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

?>
File_SMBPasswd::unlock()
File_SMBPasswd::printAccounts()
File_SMBPasswd


prints the contents of an existing smbpasswd file

File_SMBPasswd
File_SearchReplace
File_SMBPasswd
PHP Manual

File_SMBPasswd::printAccounts()

(No version information available, might be only in CVS)

File_SMBPasswd::printAccounts() — prints the contents of an existing smbpasswd file

funcsynopsis funcprototype funcdefvoid File_SMBPasswd::printAccounts()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

Print all accounts of the loaded smbpasswd file.

Return value

void

Note

This function can not be called statically.

Example

Example #1 Using File_SMBPasswd::printAccounts()

<?php
require_once('File/SMBPasswd.php');

$f     = new File_SMBPasswd('/usr/local/private/smbpasswd');
$f->load();
$f->printaccounts();

?>
File_SMBPasswd
File_SearchReplace
File_SMBPasswd


File_SearchReplace

Provides an API for replacing text in files

File_SMBPasswd::printAccounts()
Introduction
File System


HowTo s'n'r in files

File_SearchReplace
File_SearchReplace::File_SearchReplace()
File_SearchReplace
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — HowTo s'n'r in files

Using

With SearchReplace, you can replace a text in as many as desired files by another.

Example #1 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.

Example #2 Do a new search

...
// 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().

File_SearchReplace
File_SearchReplace::File_SearchReplace()
File_SearchReplace


constructor

Introduction
File_SearchReplace::getNumOccurences()
File_SearchReplace
PHP Manual

File_SearchReplace::File_SearchReplace()

(No version information available, might be only in CVS)

File_SearchReplace::File_SearchReplace() — constructor

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::File_SearchReplace()/funcdef paramdef mixed $find /paramdef paramdef mixed $replace /paramdef paramdef string $files /paramdef paramdef mixed $directories = '' /paramdef paramdef boolean $include_subdir = TRUE /paramdef paramdef array $ignore_lines = array() /paramdef /funcprototype /funcsynopsis

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.

Introduction
File_SearchReplace::getNumOccurences()
File_SearchReplace


return number of replaces

File_SearchReplace::File_SearchReplace()
File_SearchReplace::doSearch()
File_SearchReplace
PHP Manual

File_SearchReplace::getNumOccurences()

(No version information available, might be only in CVS)

File_SearchReplace::getNumOccurences() — return number of replaces

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefinteger File_SearchReplace::getNumOccurences()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

File_SearchReplace::File_SearchReplace()
File_SearchReplace::doSearch()
File_SearchReplace


execute search&replace

File_SearchReplace::getNumOccurences()
File_SearchReplace::setDirectories()
File_SearchReplace
PHP Manual

File_SearchReplace::doSearch()

(No version information available, might be only in CVS)

File_SearchReplace::doSearch() — execute search&replace

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::doSearch()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

Starts searching for the patterns and replaces them, if found.

Note

This function can not be called statically.

File_SearchReplace::getNumOccurences()
File_SearchReplace::setDirectories()
File_SearchReplace


set file location

File_SearchReplace::doSearch()
File_SearchReplace::setFiles()
File_SearchReplace
PHP Manual

File_SearchReplace::setDirectories()

(No version information available, might be only in CVS)

File_SearchReplace::setDirectories() — set file location

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::setDirectories()/funcdef paramdef array $directories /paramdef /funcprototype /funcsynopsis

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()

File_SearchReplace::doSearch()
File_SearchReplace::setFiles()
File_SearchReplace


set the files to scan

File_SearchReplace::setDirectories()
File_SearchReplace::setFind()
File_SearchReplace
PHP Manual

File_SearchReplace::setFiles()

(No version information available, might be only in CVS)

File_SearchReplace::setFiles() — set the files to scan

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::setFiles()/funcdef paramdef array $files /paramdef /funcprototype /funcsynopsis

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()

File_SearchReplace::setDirectories()
File_SearchReplace::setFind()
File_SearchReplace


set pattern to find

File_SearchReplace::setFiles()
File_SearchReplace::setIncludeSubdir()
File_SearchReplace
PHP Manual

File_SearchReplace::setFind()

(No version information available, might be only in CVS)

File_SearchReplace::setFind() — set pattern to find

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::setFind()/funcdef paramdef mixed $find /paramdef /funcprototype /funcsynopsis

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()

File_SearchReplace::setFiles()
File_SearchReplace::setIncludeSubdir()
File_SearchReplace


allow scan in sub directories

File_SearchReplace::setFind()
File_SearchReplace::setReplace()
File_SearchReplace
PHP Manual

File_SearchReplace::setIncludeSubdir()

(No version information available, might be only in CVS)

File_SearchReplace::setIncludeSubdir() — allow scan in sub directories

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::setIncludeSubdir()/funcdef paramdef integer $include_subdir /paramdef /funcprototype /funcsynopsis

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()

File_SearchReplace::setFind()
File_SearchReplace::setReplace()
File_SearchReplace


set replace string

File_SearchReplace::setIncludeSubdir()
File_SearchReplace::setSearchFunction()
File_SearchReplace
PHP Manual

File_SearchReplace::setReplace()

(No version information available, might be only in CVS)

File_SearchReplace::setReplace() — set replace string

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::setReplace()/funcdef paramdef mixed $replace /paramdef /funcprototype /funcsynopsis

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()

File_SearchReplace::setIncludeSubdir()
File_SearchReplace::setSearchFunction()
File_SearchReplace


set search function to use

File_SearchReplace
File_HtAccess
File_SearchReplace
PHP Manual

File_SearchReplace::setSearchFunction()

(No version information available, might be only in CVS)

File_SearchReplace::setSearchFunction() — set search function to use

funcsynopsis funcsynopsisinfo require_once 'File/SearchReplace.php'; /funcsynopsisinfo funcprototype funcdefvoid File_SearchReplace::setSearchFunction()/funcdef paramdef array $search_function /paramdef /funcprototype /funcsynopsis

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"

File_SearchReplace
File_HtAccess
File_SearchReplace


File_HtAccess

Provides methods to create and manipulate .htaccess files.

File System
Introduction
File System


what are .htaccess files

File_HtAccess
File_HtAccess::file_htaccess()
File_HtAccess
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

File_HtAccess
File_HtAccess::file_htaccess()
File_HtAccess


constructor

Introduction
File_HtAccess::load
File_HtAccess
PHP Manual

File_HtAccess::file_htaccess()

(No version information available, might be only in CVS)

File_HtAccess::file_htaccess() — constructor

funcsynopsis funcprototype funcdefobject new File_HtAccess()/funcdef paramdef string $file='.htaccess' /paramdef paramdef array $params /paramdef /funcprototype /funcsynopsis

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

Example #1 How to create new instance of File_HtAccess

<?php
require_once('File/HtAccess.php');
$fh = new File_HtAccess('.htaccess');
?>
Introduction
File_HtAccess::load
File_HtAccess


load the contents of existing .htaccess file

File_HtAccess::file_htaccess()
File_HtAccess::save()
File_HtAccess
PHP Manual

File_HtAccess::load()

(No version information available, might be only in CVS)

— load the contents of existing .htaccess file

funcsynopsis funcprototype funcdefmixed File_HtAccess::load()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

?>
File_HtAccess::file_htaccess()
File_HtAccess::save()
File_HtAccess


saves the .htaccess file

File_HtAccess::load
File_HtAccess::setRequire()
File_HtAccess
PHP Manual

File_HtAccess::save()

(No version information available, might be only in CVS)

File_HtAccess::save() — saves the .htaccess file

funcsynopsis funcprototype funcdefmixed File_HtAccesss:save()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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
}

?>
File_HtAccess::load
File_HtAccess::setRequire()
File_HtAccess


set the value of require property

File_HtAccess::save()
File_HtAccess::addRequire()
File_HtAccess
PHP Manual

File_HtAccess::setRequire()

(No version information available, might be only in CVS)

File_HtAccess::setRequire() — set the value of require property

funcsynopsis funcprototype funcdefvoid File_HtAccess::setRequire()/funcdef paramdef mixed $require /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess::save()
File_HtAccess::addRequire()
File_HtAccess


add a value into require property

File_HtAccess::setRequire()
File_HtAccess::delRequire()
File_HtAccess
PHP Manual

File_HtAccess::addRequire()

(No version information available, might be only in CVS)

File_HtAccess::addRequire() — add a value into require property

funcsynopsis funcprototype funcdefvoid File_HtAccess::addRequire()/funcdef paramdef string $require /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess::setRequire()
File_HtAccess::delRequire()
File_HtAccess


remove a value from require property

File_HtAccess::addRequire()
File_HtAccess::getRequire()
File_HtAccess
PHP Manual

File_HtAccess::delRequire()

(No version information available, might be only in CVS)

File_HtAccess::delRequire() — remove a value from require property

funcsynopsis funcprototype funcdefvoid File_HtAccess::delRequire()/funcdef paramdef string $require /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess::addRequire()
File_HtAccess::getRequire()
File_HtAccess


get the value(s) of require property

File_HtAccess::delRequire()
File_HtAccess::setProperties()
File_HtAccess
PHP Manual

File_HtAccess::getRequire()

(No version information available, might be only in CVS)

File_HtAccess::getRequire() — get the value(s) of require property

funcsynopsis funcprototype funcdefarray File_HtAccess::getRequire()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 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    */

?>
File_HtAccess::delRequire()
File_HtAccess::setProperties()
File_HtAccess


set the values of objects properties

File_HtAccess::getRequire()
File_HtAccess::setAuthUserFile()
File_HtAccess
PHP Manual

File_HtAccess::setProperties()

(No version information available, might be only in CVS)

File_HtAccess::setProperties() — set the values of objects properties

funcsynopsis funcprototype funcdefvoid File_HtAccess::setProperties()/funcdef paramdef array $params /paramdef /funcprototype /funcsynopsis

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

Example #1 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);

?>
File_HtAccess::getRequire()
File_HtAccess::setAuthUserFile()
File_HtAccess


set the value of authuserfile property

File_HtAccess::setProperties()
File_HtAccess::setAuthGroupFile()
File_HtAccess
PHP Manual

File_HtAccess::setAuthUserFile()

(No version information available, might be only in CVS)

File_HtAccess::setAuthUserFile() — set the value of authuserfile property

funcsynopsis funcprototype funcdefvoid File_HtAccess::setAuthUserFile()/funcdef paramdef string $file /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess::setProperties()
File_HtAccess::setAuthGroupFile()
File_HtAccess


set the value of authgroupfile property

File_HtAccess::setAuthUserFile()
File_HtAccess::setAuthType
File_HtAccess
PHP Manual

File_HtAccess::setAuthGroupFile()

(No version information available, might be only in CVS)

File_HtAccess::setAuthGroupFile() — set the value of authgroupfile property

funcsynopsis funcprototype funcdefvoid File_HtAccess::setAuthGroupFile()/funcdef paramdef string $file /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess::setAuthUserFile()
File_HtAccess::setAuthType
File_HtAccess


set the value of authtype property

File_HtAccess::setAuthGroupFile()
File_HtAccess::setAuthDigestFile
File_HtAccess
PHP Manual

File_HtAccess::setAuthType

(No version information available, might be only in CVS)

File_HtAccess::setAuthType — set the value of authtype property

funcsynopsis funcprototype funcdefvoid File_HtAccess::setAuthType()/funcdef paramdef string $type='Basic' /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess::setAuthGroupFile()
File_HtAccess::setAuthDigestFile
File_HtAccess


set the value of authdigestfile property

File_HtAccess
Gtk
File_HtAccess
PHP Manual

File_HtAccess::setAuthDigestFile

(No version information available, might be only in CVS)

File_HtAccess::setAuthDigestFile — set the value of authdigestfile property

funcsynopsis funcprototype funcdefvoid File_HtAccess::setAuthDigestFile()/funcdef paramdef string $file /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>
File_HtAccess
Gtk
File_HtAccess


Gtk

Table of Contents

  • FileDrop
  • Gtk_ScrollingLabel
  • Gtk_VarDump

Provides useful packages for the » PHP-Gtk extension.

File_HtAccess::setAuthDigestFile
FileDrop
Packages


FileDrop

Setting up GtkWidgets to accept files via Drag'n'Drop in a very easy way.

Gtk
Introduction
Gtk


Why using Gtk_FileDrop?

FileDrop
Widget support
FileDrop
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

FileDrop
Widget support
FileDrop


Drops handled on different widget types

Introduction
Example
FileDrop
PHP Manual

Widget support

(No version information available, might be only in CVS)

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.

Introduction
Example
FileDrop


How to use Gtk_FileDrop

FileDrop
Gtk_ScrollingLabel
FileDrop
PHP Manual

Example

(No version information available, might be only in CVS)

Example — How to use Gtk_FileDrop

Using Gtk_FileDrop

Example #1 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.

Example #2 Accepting directories

$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.

Example #3 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:

Example #4 Using a callback

<?php
Gtk_FileDrop::attach($widget, $accepted_types, array( &$this, 'filesDropped'));
?>

Example #5 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();
?>
FileDrop
Gtk_ScrollingLabel
FileDrop


Gtk_ScrollingLabel

Warning

This package has been superseded. Please use Gtk2_ScrollingLabel for new projects.

A class that creates a scrolling marquee.

Example
Introduction
Gtk


Getting started with Gtk_Scrollinglabel?

Gtk_ScrollingLabel
Gtk_ScrollingLabel::getFullText
Gtk_ScrollingLabel
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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();
?>

Gtk_ScrollingLabel
Gtk_ScrollingLabel::getFullText
Gtk_ScrollingLabel


Returns the full text of the label.

Introduction
Gtk_ScrollingLabel::getHiddenText
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::getFullText

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::getFullText — Returns the full text of the label.

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefstring Gtk_ScrollingLabel::getFullText()/funcdef paramdef /funcprototype /funcsynopsis

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.

Introduction
Gtk_ScrollingLabel::getHiddenText
Gtk_ScrollingLabel


Returns all of the text that is not currently visible.

Gtk_ScrollingLabel::getFullText
Gtk_ScrollingLabel::getScrollingLabel
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::getHiddenText

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::getHiddenText — Returns all of the text that is not currently visible.

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefstring Gtk_ScrollingLabel::getHiddenText()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::getFullText
Gtk_ScrollingLabel::getScrollingLabel
Gtk_ScrollingLabel


Returns a GtkEventBox with the scrolling label inside.

Gtk_ScrollingLabel::getHiddenText
Gtk_ScrollingLabel::getStyle
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::getScrollingLabel

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::getScrollingLabel — Returns a GtkEventBox with the scrolling label inside.

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk_ScrollingLabel::getScrollingLabel()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::getHiddenText
Gtk_ScrollingLabel::getStyle
Gtk_ScrollingLabel


Gets the label's style widget

Gtk_ScrollingLabel::getScrollingLabel
Gtk_ScrollingLabel::getVisibleLength
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::getStyle

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::getStyle — Gets the label's style widget

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdef&object Gtk_ScrollingLabel::getStyle()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::getScrollingLabel
Gtk_ScrollingLabel::getVisibleLength
Gtk_ScrollingLabel


Returns the length of the visible area in characters.

Gtk_ScrollingLabel::getStyle
Gtk_ScrollingLabel::pause
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::getVisibleLength

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::getVisibleLength — Returns the length of the visible area in characters.

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefint Gtk_ScrollingLabel::getVisibleLength()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::getStyle
Gtk_ScrollingLabel::pause
Gtk_ScrollingLabel


Stops the label from scrolling without reseting the label text

Gtk_ScrollingLabel::getVisibleLength
Gtk_ScrollingLabel::setBounce
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::pause

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::pause — Stops the label from scrolling without reseting the label text

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk_ScrollingLabel::pause()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::getVisibleLength
Gtk_ScrollingLabel::setBounce
Gtk_ScrollingLabel


Sets the text to bounce between the borders of the label

Gtk_ScrollingLabel::pause
Gtk_ScrollingLabel::setStartSignal
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::setBounce

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::setBounce — Sets the text to bounce between the borders of the label

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefboolean Gtk_ScrollingLabel::setBounce()/funcdef paramdef boolean $bounce /paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::pause
Gtk_ScrollingLabel::setStartSignal
Gtk_ScrollingLabel


Connects the startScroll method to a given event.

Gtk_ScrollingLabel::setBounce
Gtk_ScrollingLabel::startScroll
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::setStartSignal

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::setStartSignal — Connects the startScroll() method to a given event.

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk_ScrollingLabel::setStartSignal()/funcdef paramdef string $signal /paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::setBounce
Gtk_ScrollingLabel::startScroll
Gtk_ScrollingLabel


Begins scrolling the text from the start of the string.

Gtk_ScrollingLabel::setStartSignal
Gtk_ScrollingLabel::unPause
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::startScroll

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::startScroll — Begins scrolling the text from the start of the string.

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefboolean Gtk_ScrollingLabel::startScroll()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel::setStartSignal
Gtk_ScrollingLabel::unPause
Gtk_ScrollingLabel


Begins scrolling the label from its current position

Gtk_ScrollingLabel
Gtk_VarDump
Gtk_ScrollingLabel
PHP Manual

Gtk_ScrollingLabel::unPause

(No version information available, might be only in CVS)

Gtk_ScrollingLabel::unPause — Begins scrolling the label from its current position

funcsynopsis funcsynopsisinfo require_once 'Gtk/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk_ScrollingLabel::unPause()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk_ScrollingLabel
Gtk_VarDump
Gtk_ScrollingLabel


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.

Example #1 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());
?>
Gtk
Gtk2
Gtk


Gtk2

Table of Contents

  • Gtk2_EntryDialog
  • Gtk2_ExceptionDump
  • Gtk2_FileDrop
  • Gtk2_IndexedComboBox
  • Gtk2_PHPConfig
  • Gtk2_ScrollingLabel
  • Gtk2_VarDump

Provides useful packages for the » PHP-Gtk2 extension.

Gtk_VarDump
Gtk2_EntryDialog
Packages


Gtk2_EntryDialog

The package provides a simple dialogbox for text input.

Gtk2
Introduction
Gtk2


Gtk2_EntryDialog
constructor Gtk2_EntryDialog
Gtk2_EntryDialog
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Gtk2_EntryDialog
constructor Gtk2_EntryDialog
Gtk2_EntryDialog


Create a entry dialog instance.

Introduction
Gtk2_EntryDialog::new_simple
Gtk2_EntryDialog
PHP Manual

constructor Gtk2_EntryDialog()

(No version information available, might be only in CVS)

constructor — Create a entry dialog instance.

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef void constructor Gtk2_EntryDialog::__construct() /funcdef paramdef GtkWindow $parent /paramdef paramdef GtkDialogFlags $flags /paramdef paramdef GtkMessageType $type /paramdef paramdef GtkButtonsType $buttons /paramdef paramdef string $message /paramdef paramdef string $default /paramdef /funcprototype /funcsynopsis

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.

Introduction
Gtk2_EntryDialog::new_simple
Gtk2_EntryDialog


Simplified constructor with not so much parameters.

constructor Gtk2_EntryDialog
Gtk2_EntryDialog::get
Gtk2_EntryDialog
PHP Manual

Gtk2_EntryDialog::new_simple()

(No version information available, might be only in CVS)

— Simplified constructor with not so much parameters.

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef Gtk2_EntryDialog Gtk2_EntryDialog::new_simple() /funcdef paramdef string $message /paramdef paramdef string $default = null /paramdef paramdef GtkWindow $parent = null /paramdef /funcprototype /funcsynopsis

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).

constructor Gtk2_EntryDialog
Gtk2_EntryDialog::get
Gtk2_EntryDialog


Show the dialog and retrieve the text

Gtk2_EntryDialog::new_simple
Gtk2_EntryDialog::run
Gtk2_EntryDialog
PHP Manual

Gtk2_EntryDialog::get()

(No version information available, might be only in CVS)

— Show the dialog and retrieve the text

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef string Gtk2_EntryDialog::get() /funcdef paramdef string $message /paramdef paramdef string $default /paramdef paramdef GtkWindow $parent /paramdef /funcprototype /funcsynopsis

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.

Gtk2_EntryDialog::new_simple
Gtk2_EntryDialog::run
Gtk2_EntryDialog


Show the dialog and block until a button has been pressed.

Gtk2_EntryDialog::get
Gtk2_EntryDialog::get_text
Gtk2_EntryDialog
PHP Manual

Gtk2_EntryDialog::run()

(No version information available, might be only in CVS)

— Show the dialog and block until a button has been pressed.

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef int Gtk2_EntryDialog::run() /funcdef paramdef /funcprototype /funcsynopsis

Description

Show the dialog and block until a button has been pressed.

Return value

returns The response id of the pressed button.

Gtk2_EntryDialog::get
Gtk2_EntryDialog::get_text
Gtk2_EntryDialog


Returns the text input by the user.

Gtk2_EntryDialog::run
Gtk2_EntryDialog::set_text
Gtk2_EntryDialog
PHP Manual

Gtk2_EntryDialog::get_text()

(No version information available, might be only in CVS)

— Returns the text input by the user.

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef string Gtk2_EntryDialog::get_text() /funcdef paramdef /funcprototype /funcsynopsis

Description

Retrieves the text from the entry.

Return value

returns The input from the user.

Gtk2_EntryDialog::run
Gtk2_EntryDialog::set_text
Gtk2_EntryDialog


Sets the text for the entry

Gtk2_EntryDialog::get_text
Gtk2_EntryDialog::set_default_response
Gtk2_EntryDialog
PHP Manual

Gtk2_EntryDialog::set_text()

(No version information available, might be only in CVS)

— Sets the text for the entry

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef string Gtk2_EntryDialog::set_text() /funcdef paramdef string $text /paramdef /funcprototype /funcsynopsis

Description

Sets the text for the entry.

Gtk2_EntryDialog::get_text
Gtk2_EntryDialog::set_default_response
Gtk2_EntryDialog


Set the default response.

Gtk2_EntryDialog
Gtk2_ExceptionDump
Gtk2_EntryDialog
PHP Manual

Gtk2_EntryDialog::set_default_response()

(No version information available, might be only in CVS)

— Set the default response.

funcsynopsis funcsynopsisinforequire_once 'Gtk2/EntryDialog.php';/funcsynopsisinfo funcprototype funcdef void Gtk2_EntryDialog::set_default_response() /funcdef paramdef int $response_id /paramdef /funcprototype /funcsynopsis

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

Gtk2_EntryDialog
Gtk2_ExceptionDump
Gtk2_EntryDialog


Gtk2_ExceptionDump

Catches and displays PHP errors, notices and warnings as well as PEAR Errors and uncaught exceptions.

Gtk2_EntryDialog::set_default_response
Introduction
Gtk2


Using Gtk2_ExceptionDump

Gtk2_ExceptionDump
Re-using Gtk2_ExceptionDump
Gtk2_ExceptionDump
PHP Manual

Introduction

(No version information available, might be only in CVS)

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()

Example #1 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.

Example #2 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/.

Gtk2_ExceptionDump
Re-using Gtk2_ExceptionDump
Gtk2_ExceptionDump


Embedding it in own applications

Gtk2_ExceptionDump
Gtk2_FileDrop
Gtk2_ExceptionDump
PHP Manual

Re-using Gtk2_ExceptionDump

(No version information available, might be only in CVS)

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().

Gtk2_ExceptionDump
Gtk2_FileDrop
Gtk2_ExceptionDump


Gtk2_FileDrop

Setting up GtkWidgets to accept files via Drag'n'Drop in a very easy way.

Re-using Gtk2_ExceptionDump
Introduction
Gtk2


Why using Gtk2_FileDrop?

Gtk2_FileDrop
Widget support
Gtk2_FileDrop
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Gtk2_FileDrop
Widget support
Gtk2_FileDrop


Drops handled on different widget types

Introduction
Example
Gtk2_FileDrop
PHP Manual

Widget support

(No version information available, might be only in CVS)

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.

Introduction
Example
Gtk2_FileDrop


How to use Gtk2_FileDrop

Gtk2_FileDrop
Gtk2_IndexedComboBox
Gtk2_FileDrop
PHP Manual

Example

(No version information available, might be only in CVS)

Example — How to use Gtk2_FileDrop

Using Gtk2_FileDrop

Example #1 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.

Example #2 Accepting directories

$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.

Example #3 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:

Example #4 Using a callback

<?php
Gtk2_FileDrop::attach($widget, $accepted_types, array( &$this, 'filesDropped'));
?>

Example #5 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();
?>
Gtk2_FileDrop
Gtk2_IndexedComboBox
Gtk2_FileDrop


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.

Example
Simple example
Gtk2


To get started easily

Gtk2_IndexedComboBox
Conquering Glade combo boxes
Gtk2_IndexedComboBox
PHP Manual

Simple example

(No version information available, might be only in CVS)

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.

Example #1 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.

Gtk2_IndexedComboBox
Conquering Glade combo boxes
Gtk2_IndexedComboBox


How to use glade combos with this class

Simple example
Gtk2_IndexedComboBox
Gtk2_IndexedComboBox
PHP Manual

Conquering Glade combo boxes

(No version information available, might be only in CVS)

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.

Example #1 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" xml: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" xml:id="cmbNormal">
      <property name="visible">True</property>
    </widget>
  </child>
</widget>

</glade-interface>

Example #2 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().

Simple example
Gtk2_IndexedComboBox
Gtk2_IndexedComboBox


The main class

Conquering Glade combo boxes
Gtk2_IndexedComboBox_Model
Gtk2_IndexedComboBox
PHP Manual

Gtk2_IndexedComboBox

(No version information available, might be only in CVS)

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.

Conquering Glade combo boxes
Gtk2_IndexedComboBox_Model
Gtk2_IndexedComboBox
PHP Manual


Model class behind the scenes

Gtk2_IndexedComboBox
Gtk2_PHPConfig
Gtk2_IndexedComboBox
PHP Manual

Gtk2_IndexedComboBox_Model

(No version information available, might be only in CVS)

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().

Gtk2_IndexedComboBox
Gtk2_PHPConfig
Gtk2_IndexedComboBox


Gtk2_PHPConfig

Provides a simple GUI to enable the user to edit php.ini values.

Gtk2_IndexedComboBox_Model
Introduction
Gtk2


About Gtk2_PHPConfig

Gtk2_PHPConfig
Usage
Gtk2_PHPConfig
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Gtk2_PHPConfig
Usage
Gtk2_PHPConfig


Gtk2_PHPConfig
Gtk2_ScrollingLabel
Gtk2_PHPConfig
PHP Manual

Usage

(No version information available, might be only in CVS)

Usage — Using Gtk2_PHPConfig

Using Gtk2_PHPConfig

Example #1 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.

Gtk2_PHPConfig
Gtk2_ScrollingLabel
Gtk2_PHPConfig


Gtk2_ScrollingLabel

A class that creates a scrolling marquee.

Usage
Introduction
Gtk2


Getting started with Gtk2_Scrollinglabel

Gtk2_ScrollingLabel
Gtk2_ScrollingLabel
Gtk2_ScrollingLabel
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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();
?>

Gtk2_ScrollingLabel
Gtk2_ScrollingLabel
Gtk2_ScrollingLabel


Create a new Scrolling label.

Introduction
Gtk2_ScrollingLabel::getFullText
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel — Create a new Scrolling label.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk2_SrollingLabel()/funcdef paramdef string $text = '' /paramdef /funcprototype /funcsynopsis

Description

Class constructor

Parameter

  • string $text - The text to scroll

Note

This function can not be called statically.

Introduction
Gtk2_ScrollingLabel::getFullText
Gtk2_ScrollingLabel
PHP Manual


Returns the full text of the label.

Gtk2_ScrollingLabel
Gtk2_ScrollingLabel::getHiddenText
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::getFullText

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::getFullText — Returns the full text of the label.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefstring Gtk2_ScrollingLabel::getFullText()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel
Gtk2_ScrollingLabel::getHiddenText
Gtk2_ScrollingLabel


Returns all of the text that is not currently visible.

Gtk2_ScrollingLabel::getFullText
Gtk2_ScrollingLabel::getScrollingLabel
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::getHiddenText

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::getHiddenText — Returns all of the text that is not currently visible.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefstring Gtk2_ScrollingLabel::getHiddenText()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::getFullText
Gtk2_ScrollingLabel::getScrollingLabel
Gtk2_ScrollingLabel


Returns a GtkEventBox with the scrolling label inside.

Gtk2_ScrollingLabel::getHiddenText
Gtk2_ScrollingLabel::getStyle
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::getScrollingLabel

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::getScrollingLabel — Returns a GtkEventBox with the scrolling label inside.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk2_ScrollingLabel::getScrollingLabel()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::getHiddenText
Gtk2_ScrollingLabel::getStyle
Gtk2_ScrollingLabel


Gets the label's style widget

Gtk2_ScrollingLabel::getScrollingLabel
Gtk2_ScrollingLabel::getVisibleLength
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::getStyle

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::getStyle — Gets the label's style widget

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdef&object Gtk2_ScrollingLabel::getStyle()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::getScrollingLabel
Gtk2_ScrollingLabel::getVisibleLength
Gtk2_ScrollingLabel


Returns the length of the visible area in characters.

Gtk2_ScrollingLabel::getStyle
Gtk2_ScrollingLabel::pause
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::getVisibleLength

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::getVisibleLength — Returns the length of the visible area in characters.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefint Gtk2_ScrollingLabel::getVisibleLength()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::getStyle
Gtk2_ScrollingLabel::pause
Gtk2_ScrollingLabel


Stops the label from scrolling without reseting the label text

Gtk2_ScrollingLabel::getVisibleLength
Gtk2_ScrollingLabel::setBounce
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::pause

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::pause — Stops the label from scrolling without reseting the label text

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk2_ScrollingLabel::pause()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::getVisibleLength
Gtk2_ScrollingLabel::setBounce
Gtk2_ScrollingLabel


Sets the text to bounce between the borders of the label

Gtk2_ScrollingLabel::pause
Gtk2_ScrollingLabel::setStartSignal
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::setBounce

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::setBounce — Sets the text to bounce between the borders of the label

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefboolean Gtk2_ScrollingLabel::setBounce()/funcdef paramdef boolean $bounce /paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::pause
Gtk2_ScrollingLabel::setStartSignal
Gtk2_ScrollingLabel


Connects the startScroll method to a given event.

Gtk2_ScrollingLabel::setBounce
Gtk2_ScrollingLabel::startScroll
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::setStartSignal

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::setStartSignal — Connects the startScroll() method to a given event.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk2_ScrollingLabel::setStartSignal()/funcdef paramdef string $signal /paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::setBounce
Gtk2_ScrollingLabel::startScroll
Gtk2_ScrollingLabel


Begins scrolling the text from the start of the string.

Gtk2_ScrollingLabel::setStartSignal
Gtk2_ScrollingLabel::unPause
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::startScroll

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::startScroll — Begins scrolling the text from the start of the string.

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefboolean Gtk2_ScrollingLabel::startScroll()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel::setStartSignal
Gtk2_ScrollingLabel::unPause
Gtk2_ScrollingLabel


Begins scrolling the label from its current position

Gtk2_ScrollingLabel
Gtk2_VarDump
Gtk2_ScrollingLabel
PHP Manual

Gtk2_ScrollingLabel::unPause

(No version information available, might be only in CVS)

Gtk2_ScrollingLabel::unPause — Begins scrolling the label from its current position

funcsynopsis funcsynopsisinfo require_once 'Gtk2/ScrollingLabel.php'; /funcsynopsisinfo funcprototype funcdefvoid Gtk2_ScrollingLabel::unPause()/funcdef paramdef /funcprototype /funcsynopsis

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.

Gtk2_ScrollingLabel
Gtk2_VarDump
Gtk2_ScrollingLabel


Gtk2_VarDump

Provides a simple GUI to examine PHP variables, for example complex arrays or objects.

Gtk2
Introduction
Gtk2


Gtk2_VarDump
Re-using Gtk2_VarDump
Gtk2_VarDump
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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');

?>
Gtk2_VarDump
Re-using Gtk2_VarDump
Gtk2_VarDump


Embedding it in own applications

Gtk2_VarDump
HTML
Gtk2_VarDump
PHP Manual

Re-using Gtk2_VarDump

(No version information available, might be only in CVS)

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.

Gtk2_VarDump
HTML
Gtk2_VarDump


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

Provides packages for working and creating HTML

Re-using Gtk2_VarDump
HTML_Crypt
Packages


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.

Example #1 A basic example to encrypt an email address

// 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.

HTML
HTML_CSS
HTML


HTML_CSS

The PEAR::HTML_CSS package provides a simple interface for handling and generating cascading style sheets.

Introduction

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.

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.

System Requirements

Mandatory resources :

  • » PHP 4.3.0 or newer.

  • » PEAR 1.5.4 or newer.

  • » PEAR::HTML_Common 1.2.4 or newer.

Optional resources :

  • » PHP 5.0.0 or newer.

  • » PEAR::Services_W3C_CSSValidator 0.1.0 or newer.

  • » PHPUnit 3.2.0 or newer.

About

Reference guide

HTML_Crypt
FAQ
HTML


Answers to most Frequently Asked Questions

File_Passwd_Authdigest::generatePassword
PHP Manual

FAQ

(No version information available, might be only in CVS)

FAQ — Answers to most Frequently Asked Questions

HTML_CSS FAQ

  1. What does it cost ?
  2. Do you offer support ?
  3. I found a bug, what shall I do ?
  4. What is CSS ?
  5. What is PEAR ?
  6. I want to use HTML_CSS without PEAR. Is it possible ?
  7. I want to know property value of a selector, but it can not exist
qandadiv

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 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.

/qandadiv qandadiv

How to

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.

/qandadiv
File_Passwd_Authdigest::generatePassword


What is New in version ?

File_Passwd_Authdigest::generatePassword
PHP Manual

News

(No version information available, might be only in CVS)

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

File_Passwd_Authdigest::generatePassword


Application Programming Interface

Re-using Gtk2_VarDump
PHP Manual

API

(No version information available, might be only in CVS)

API — Application Programming Interface

Initialize parser/writer options

With the class constructor, you have ability to set many options :

  • xhtml option defines whether element selectors should be automatically lowercased. See also: HTML_CSS::setXhtmlCompliance() .

  • tab option defines the string used to indent CSS text. See also: HTML_CSS::setTab() .

  • filename option allow to parse an external css file. See also: HTML_CSS::parseFile() .

  • cache option controls caching of the page. See also: HTML_CSS::setCache() .

  • oneline option defines whether to output all properties on one line. See also: HTML_CSS::setSingleLineOutput() .

  • charset option defines the character encoding string. See also: HTML_CSS::setCharset() .

  • contentDisposition option contains the Content-Disposition filename. See also: HTML_CSS::setContentDisposition() .

  • lineEnd option sets the line end style to Windows, Mac, Unix or a custom string. See also: HTML_CSS::setLineEnd() .

  • groupsfirst option determines whether to output groups before elements. See also: HTML_CSS::setOutputGroupsFirst() .

  • allowduplicates option allow to have duplicate rules in selector.

Tip

HTML_CSS 1.4.0+ users may now set a single option directly like that:

<?php
require_once 'HTML/CSS.php';

$css = new HTML_CSS();

// with PHP5 only
$css->allowduplicates = true;

// with PHP4 use
$css->__set('allowduplicates', true);
?>

Handle selector and property values

Read and write single selector or even descendant selector is made easy with : HTML_CSS::getStyle() and HTML_CSS::setStyle()

Grouping selectors

The most advanced/complex functions are those which handle group of selectors HTML_CSS::createGroup() , HTML_CSS::unsetGroup() , HTML_CSS::getGroupStyle() , HTML_CSS::setGroupStyle() , HTML_CSS::addGroupSelector() , HTML_CSS::removeGroupSelector() , HTML_CSS::setSameStyle()

Parsing data sources

Handle data sources are so easy than just one call of these three methods : HTML_CSS::parseString() , HTML_CSS::parseFile() , and HTML_CSS::parseData()

Checking data sources

Check validity of data source is now possible if you run HTML_CSS with PHP5. Use this function : HTML_CSS::validate()

Output

Send result directly to browser, send it to file or capture to a PHP variable, you will certainly use one of them. HTML_CSS::toArray() , HTML_CSS::toInline() , HTML_CSS::toFile() , HTML_CSS::toString() , HTML_CSS::display() , HTML_CSS::getContentDisposition() , and HTML_CSS::setContentDisposition()

Searching for selectors and/or properties

Ability to find if a selector or a property (with perl-compatible pattern) is already defined with HTML_CSS::grepStyle() important

This function is available since version 1.1.0

/important

Handle At-Rules

List of at-rules supported can be obtained by call to function HTML_CSS::getAtRulesList() important

All these related at-rules functions are available since version 1.5.0

/important

Distinguish simple declarative at-rules (without declaration style blocks) : @charset, @import, @namespace, handled by : HTML_CSS::createAtRule() and HTML_CSS::unsetAtRule()

And conditional/informative at-rules (with declaration style blocks) : @media, @page, @font-face, handled by : HTML_CSS::getAtRuleStyle() and HTML_CSS::setAtRuleStyle()

Re-using Gtk2_VarDump


Class constructor

Re-using Gtk2_VarDump
PHP Manual

constructor HTML_CSS::HTML_CSS()

(No version information available, might be only in CVS)

constructor — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_CSS::HTML_CSS()/funcdef paramdefarray $attributes = array() /paramdef paramdefarray $errorPrefs = array() /paramdef /funcprototype /funcsynopsis

Description

Class constructors : Zend Engine 1 uses HTML_CSS, while Zend Engine 2 uses __construct

Parameter

array $attributes

(optional) Pass options to the constructor. Valid options are :

  • xhtml (sets xhtml compliance),

  • tab (sets indent string),

  • filename (name of file to be parsed),

  • cache (determines whether the nocache headers are sent),

  • oneline (whether to output each definition on one line),

  • groupsfirst (determines whether to output groups before elements)

  • allowduplicates (allow to have duplicate rules in selector)

array $errorPrefs

(optional) has to configure error handler

Throws

throws no exceptions thrown

Since

since version 0.2.0 (2003-07-31)

Note

This function can not be called statically.

Re-using Gtk2_VarDump


Get option for the class

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::__get()

(No version information available, might be only in CVS)

— Get option for the class

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef mixed HTML_CSS::__get() /funcdef paramdef string $option /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set option for the class

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::__set()

(No version information available, might be only in CVS)

— Set option for the class

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef void HTML_CSS::__set() /funcdef paramdef string $option /paramdef paramdef string $val /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set xhtml flag

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setXhtmlCompliance()

(No version information available, might be only in CVS)

— Set xhtml flag

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setXhtmlCompliance()/funcdef paramdefbool $value /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set cache flag

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setCache()

(No version information available, might be only in CVS)

— Set cache flag

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setCache()/funcdef paramdefbool $cache = TRUE /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set oneline flag

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setSingleLineOutput()

(No version information available, might be only in CVS)

— Set oneline flag

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setSingleLineOutput()/funcdef paramdefbool $value /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set groupsfirst flag

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setOutputGroupsFirst()

(No version information available, might be only in CVS)

— Set groupsfirst flag

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setOutputGroupsFirst()/funcdef paramdefbool $value /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set tab value

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setTab()

(No version information available, might be only in CVS)

— Set tab value

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdef void HTML_CSS::setTab() /funcdef paramdef string $string /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set lineend value

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setLineEnd()

(No version information available, might be only in CVS)

— Set lineend value

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdef void HTML_CSS::setLineEnd() /funcdef paramdef string $style /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return the charset encoding string

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getCharset()

(No version information available, might be only in CVS)

— Return the charset encoding string

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_CSS::getCharset()/funcdef paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set charset value

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setCharset()

(No version information available, might be only in CVS)

— Set charset value

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setCharset()/funcdef paramdefstring $type = 'iso-8859-1' /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return all options for the class

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getOptions()

(No version information available, might be only in CVS)

— Return all options for the class

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef array HTML_CSS::getOptions() /funcdef paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return the value of a CSS property

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getStyle()

(No version information available, might be only in CVS)

— Return the value of a CSS property

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefmixed|PEAR_Error HTML_CSS::getStyle()/funcdef paramdefstring $element /paramdef paramdefstring $property /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set or add a CSS definition

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setStyle()

(No version information available, might be only in CVS)

— Set or add a CSS definition

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setStyle()/funcdef paramdefstring $element /paramdef paramdefstring $property /paramdef paramdefstring $value /paramdef paramdefbool $duplicates = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Create a new CSS definition group

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::createGroup()

(No version information available, might be only in CVS)

— Create a new CSS definition group

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefmixed|PEAR_Error HTML_CSS::createGroup()/funcdef paramdefstring $selectors /paramdef paramdefmixed $group = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Remove a CSS definition group

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::unsetGroup()

(No version information available, might be only in CVS)

— Remove a CSS definition group

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::unsetGroup()/funcdef paramdefmixed $group /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return CSS definition for a CSS group

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getGroupStyle()

(No version information available, might be only in CVS)

— Return CSS definition for a CSS group

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefmixed|PEAR_Error HTML_CSS::getGroupStyle()/funcdef paramdefmixed $group /paramdef paramdefstring $property /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Set or add a CSS definition for a CSS group

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setGroupStyle()

(No version information available, might be only in CVS)

— Set or add a CSS definition for a CSS group

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|int|PEAR_Error HTML_CSS::setGroupStyle()/funcdef paramdefmixed $group /paramdef paramdefstring $property /paramdef paramdefstring $value /paramdef paramdefbool $duplicates = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Add a selector to a CSS definition group.

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::addGroupSelector()

(No version information available, might be only in CVS)

— Add a selector to a CSS definition group.

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::addGroupSelector()/funcdef paramdefmixed $group /paramdef paramdefstring $selectors /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Remove a selector from a group

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::removeGroupSelector()

(No version information available, might be only in CVS)

— Remove a selector from a group

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::removeGroupSelector()/funcdef paramdefmixed $group /paramdef paramdefstring $selectors /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Apply same styles on two selectors

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setSameStyle()

(No version information available, might be only in CVS)

— Apply same styles on two selectors

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setSameStyle()/funcdef paramdefstring $new /paramdef paramdefstring $old /paramdef /funcprototype /funcsynopsis

Description

Set or change the properties of new selectors to the values of an existing selector

Parameter

string $new

New selector(s) that should share the same definitions, separated by commas

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.

Re-using Gtk2_VarDump


Parse a string

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::parseString()

(No version information available, might be only in CVS)

— Parse a string

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::parseString()/funcdef paramdefstring $str /paramdef paramdefbool $duplicates = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Parse file content

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::parseFile()

(No version information available, might be only in CVS)

— Parse file content

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::parseFile()/funcdef paramdefstring $filename /paramdef paramdefbool $duplicates = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Parse multiple data sources

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::parseData()

(No version information available, might be only in CVS)

— Parse multiple data sources

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::parseData()/funcdef paramdefarray $styles /paramdef paramdefbool $duplicates = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return the CSS contents in an array

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::toArray()

(No version information available, might be only in CVS)

— Return the CSS contents in an array

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_CSS::toArray()/funcdef paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return a string-properties for style attribute of an HTML element

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::toInline()

(No version information available, might be only in CVS)

— Return a string-properties for style attribute of an HTML element

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefstring|PEAR_Error HTML_CSS::toInline()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Generate CSS and stores it in a file

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::toFile()

(No version information available, might be only in CVS)

— Generate CSS and stores it in a file

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::toFile()/funcdef paramdefstring $filename /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return current CSS parsed data as a string

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::toString()

(No version information available, might be only in CVS)

— Return current CSS parsed data as a string

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_CSS::toString()/funcdef paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Output CSS Code

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::display()

(No version information available, might be only in CVS)

— Output CSS Code

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_CSS::display()/funcdef paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return the Content-Disposition header

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getContentDisposition()

(No version information available, might be only in CVS)

— Return the Content-Disposition header

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_CSS::getContentDisposition()/funcdef paramdef /funcprototype /funcsynopsis

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()

see » http://pear.php.net/bugs/bug.php?id=12195 Patch by Carsten Wiedmann

Re-using Gtk2_VarDump


Set Content-Disposition header

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setContentDisposition()

(No version information available, might be only in CVS)

— Set Content-Disposition header

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error HTML_CSS::setContentDisposition()/funcdef paramdefboolean $enable = TRUE /paramdef paramdefstring $filename = '' /paramdef /funcprototype /funcsynopsis

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()

see » http://pear.php.net/bugs/bug.php?id=12195 Patch by Carsten Wiedmann

Note

This function can not be called statically.

Re-using Gtk2_VarDump


Retrieve styles corresponding to an element filter

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::grepStyle()

(No version information available, might be only in CVS)

— Retrieve styles corresponding to an element filter

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdefarray|PEAR_Error HTML_CSS::grepStyle()/funcdef paramdefstring $elmPattern /paramdef paramdefstring $proPattern /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Validate a CSS data source

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::validate()

(No version information available, might be only in CVS)

— Validate a CSS data source

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef boolean|PEAR_Error HTML_CSS::validate() /funcdef paramdef array $styles /paramdef paramdef array &$messages /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Return list of supported At-Rules

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getAtRulesList()

(No version information available, might be only in CVS)

— Return list of supported At-Rules

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdef void HTML_CSS::getAtRulesList() /funcdef paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Create a new simple declarative At-Rule

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::createAtRule()

(No version information available, might be only in CVS)

— Create a new simple declarative At-Rule

funcsynopsis funcsynopsisinfo require_once 'HTML/CSS.php'; /funcsynopsisinfo funcprototype funcdef void|PEAR_Error HTML_CSS::createAtRule() /funcdef paramdef string $atKeyword /paramdef paramdef string $arguments = '' /paramdef /funcprototype /funcsynopsis

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

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.

Re-using Gtk2_VarDump


Remove an existing At-Rule

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::unsetAtRule()

(No version information available, might be only in CVS)

— Remove an existing At-Rule

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef void|PEAR_Error HTML_CSS::unsetAtRule() /funcdef paramdef string $atKeyword /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Get style value of an existing At-Rule

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::getAtRuleStyle()

(No version information available, might be only in CVS)

— Get style value of an existing At-Rule

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef void|PEAR_Error HTML_CSS::getAtRuleStyle() /funcdef paramdef string $atKeyword /paramdef paramdef string $arguments /paramdef paramdef string $selectors /paramdef paramdef string $property /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Define a conditional/informative At-Rule

Re-using Gtk2_VarDump
PHP Manual

HTML_CSS::setAtRuleStyle()

(No version information available, might be only in CVS)

— Define a conditional/informative At-Rule

funcsynopsis funcsynopsisinforequire_once 'HTML/CSS.php';/funcsynopsisinfo funcprototype funcdef void|PEAR_Error HTML_CSS::setAtRuleStyle() /funcdef paramdef string $atKeyword /paramdef paramdef string $arguments /paramdef paramdef string $selectors /paramdef paramdef string $property /paramdef paramdef string $value /paramdef paramdef bool $duplicates = NULL /paramdef /funcprototype /funcsynopsis

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.

Re-using Gtk2_VarDump


Flexible error handler plug-in system

Re-using Gtk2_VarDump
PHP Manual

Error Handler

(No version information available, might be only in CVS)

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)***

* | error level
** | message body with context informations
*** | 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

/important

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 coref
Function: html_css->setstyle coref

* | error level
** | message body with context informations
*** | 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"*********

* | client ip address and execution date
** | error level
*** | 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.

Re-using Gtk2_VarDump


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.

Error Handler
Introduction
HTML


Generating HTML forms.

HTML_Form
Usage examples
HTML_Form
PHP Manual
Martin Jansen

Introduction

(No version information available, might be only in CVS)

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

Example #1 Basic example

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.

HTML_Form
Usage examples
HTML_Form


Using HTML_Form.

HTML_Form
HTML_Menu
HTML_Form
PHP Manual
Martin Jansen

Usage examples

(No version information available, might be only in CVS)

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).

Example #1 Creating a form

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.

Example #2 Directly displaying form tags

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.

Example #3 Returning form tags

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" />.

HTML_Form
HTML_Menu
HTML_Form


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.

Usage examples
Introduction
HTML


Menu structure and supported output modes

HTML_Menu
constructor HTML_Menu::HTML_Menu()
HTML_Menu
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

Example #1 Menu multidimensional hash

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.

Possible menu types
'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.

Example #2 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.

Example #3 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.

Example #4 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.

Example #5 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.

Example #6 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

Example #7 Very basic usage example

// 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();
HTML_Menu
constructor HTML_Menu::HTML_Menu()
HTML_Menu


Initializes the menu, sets the type and menu structure.

Introduction
HTML_Menu::forceCurrentUrl()
HTML_Menu
PHP Manual

constructor HTML_Menu::HTML_Menu()

(No version information available, might be only in CVS)

constructor HTML_Menu::HTML_Menu() — Initializes the menu, sets the type and menu structure.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_Menu::HTML_Menu()/funcdef paramdefarray $menu = NULL /paramdef paramdefstring $type = 'tree' /paramdef paramdefstring $urlEnvVar = 'PHP_SELF' /paramdef /funcprototype /funcsynopsis

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.

Introduction
HTML_Menu::forceCurrentUrl()
HTML_Menu


Forces the given URL to be "current"

constructor HTML_Menu::HTML_Menu()
HTML_Menu::get()
HTML_Menu
PHP Manual

HTML_Menu::forceCurrentUrl()

(No version information available, might be only in CVS)

HTML_Menu::forceCurrentUrl() — Forces the given URL to be "current"

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::forceCurrentUrl()/funcdef paramdefstring $url /paramdef /funcprototype /funcsynopsis

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.

constructor HTML_Menu::HTML_Menu()
HTML_Menu::get()
HTML_Menu


Returns the HTML menu.

HTML_Menu::forceCurrentUrl()
HTML_Menu::getCurrentURL()
HTML_Menu
PHP Manual

HTML_Menu::get()

(No version information available, might be only in CVS)

HTML_Menu::get() — Returns the HTML menu.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Menu::get()/funcdef paramdefstring $menuType = '' /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::forceCurrentUrl()
HTML_Menu::getCurrentURL()
HTML_Menu


Returns the URL of the currently selected page.

HTML_Menu::get()
HTML_Menu::getPath()
HTML_Menu
PHP Manual

HTML_Menu::getCurrentURL()

(No version information available, might be only in CVS)

HTML_Menu::getCurrentURL() — Returns the URL of the currently selected page.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Menu::getCurrentURL()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::get()
HTML_Menu::getPath()
HTML_Menu


Returns the path of the current page in the menu 'tree'.

HTML_Menu::getCurrentURL()
HTML_Menu::render()
HTML_Menu
PHP Manual

HTML_Menu::getPath()

(No version information available, might be only in CVS)

HTML_Menu::getPath() — Returns the path of the current page in the menu 'tree'.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Menu::getPath()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::getCurrentURL()
HTML_Menu::render()
HTML_Menu


Renders the menu.

HTML_Menu::getPath()
HTML_Menu::setMenu()
HTML_Menu
PHP Manual

HTML_Menu::render()

(No version information available, might be only in CVS)

HTML_Menu::render() — Renders the menu.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::render()/funcdef paramdefobject HTML_Menu_Renderer &$renderer /paramdef paramdefstring $menuType = '' /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::getPath()
HTML_Menu::setMenu()
HTML_Menu


Sets the menu structure.

HTML_Menu::render()
HTML_Menu::setMenuType()
HTML_Menu
PHP Manual

HTML_Menu::setMenu()

(No version information available, might be only in CVS)

HTML_Menu::setMenu() — Sets the menu structure.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::setMenu()/funcdef paramdefarray $menu /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::render()
HTML_Menu::setMenuType()
HTML_Menu


Sets the type of the menu.

HTML_Menu::setMenu()
HTML_Menu::setURLEnvVar()
HTML_Menu
PHP Manual

HTML_Menu::setMenuType()

(No version information available, might be only in CVS)

HTML_Menu::setMenuType() — Sets the type of the menu.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::setMenuType()/funcdef paramdefstring $menuType /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::setMenu()
HTML_Menu::setURLEnvVar()
HTML_Menu


Sets the environment variable to use to get the current URL.

HTML_Menu::setMenuType()
HTML_Menu::setURLPrefix()
HTML_Menu
PHP Manual

HTML_Menu::setURLEnvVar()

(No version information available, might be only in CVS)

HTML_Menu::setURLEnvVar() — Sets the environment variable to use to get the current URL.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::setURLEnvVar()/funcdef paramdefstring $urlEnvVar /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::setMenuType()
HTML_Menu::setURLPrefix()
HTML_Menu


Sets the prefix for the URLs in the menu

HTML_Menu::setURLEnvVar()
HTML_Menu::show()
HTML_Menu
PHP Manual

HTML_Menu::setURLPrefix()

(No version information available, might be only in CVS)

HTML_Menu::setURLPrefix() — Sets the prefix for the URLs in the menu

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::setURLPrefix()/funcdef paramdefstring $prefix /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::setURLEnvVar()
HTML_Menu::show()
HTML_Menu


Prints the HTML menu.

HTML_Menu::setURLPrefix()
Class Summary HTML_Menu_Renderer
HTML_Menu
PHP Manual

HTML_Menu::show()

(No version information available, might be only in CVS)

HTML_Menu::show() — Prints the HTML menu.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu::show()/funcdef paramdefstring $menuType = '' /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu::setURLPrefix()
Class Summary HTML_Menu_Renderer
HTML_Menu


An abstract base class for HTML_Menu renderers (package developer related)

HTML_Menu::show()
HTML_Menu_Renderer::finishLevel()
HTML_Menu
PHP Manual

Class Summary HTML_Menu_Renderer

(No version information available, might be only in CVS)

Class Summary — 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.

HTML_Menu::show()
HTML_Menu_Renderer::finishLevel()
HTML_Menu


Finish the tree level (for types 'tree' and 'sitemap') (package developer related)

Class Summary HTML_Menu_Renderer
HTML_Menu_Renderer::finishMenu()
HTML_Menu
PHP Manual

HTML_Menu_Renderer::finishLevel()

(No version information available, might be only in CVS)

HTML_Menu_Renderer::finishLevel() — Finish the tree level (for types 'tree' and 'sitemap') (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_Renderer::finishLevel()/funcdef paramdefint $level /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_Menu_Renderer
HTML_Menu_Renderer::finishMenu()
HTML_Menu


Finish the menu (package developer related)

HTML_Menu_Renderer::finishLevel()
HTML_Menu_Renderer::finishRow()
HTML_Menu
PHP Manual

HTML_Menu_Renderer::finishMenu()

(No version information available, might be only in CVS)

HTML_Menu_Renderer::finishMenu() — Finish the menu (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_Renderer::finishMenu()/funcdef paramdefint $level /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu_Renderer::finishLevel()
HTML_Menu_Renderer::finishRow()
HTML_Menu


Finish the row in the menu (package developer related)

HTML_Menu_Renderer::finishMenu()
HTML_Menu_Renderer::renderEntry()
HTML_Menu
PHP Manual

HTML_Menu_Renderer::finishRow()

(No version information available, might be only in CVS)

HTML_Menu_Renderer::finishRow() — Finish the row in the menu (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_Renderer::finishRow()/funcdef paramdefint $level /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu_Renderer::finishMenu()
HTML_Menu_Renderer::renderEntry()
HTML_Menu


Renders the element of the menu (package developer related)

HTML_Menu_Renderer::finishRow()
HTML_Menu_Renderer::setMenuType()
HTML_Menu
PHP Manual

HTML_Menu_Renderer::renderEntry()

(No version information available, might be only in CVS)

HTML_Menu_Renderer::renderEntry() — Renders the element of the menu (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_Renderer::renderEntry()/funcdef paramdefarray $node /paramdef paramdefint $level /paramdef paramdefint $type /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu_Renderer::finishRow()
HTML_Menu_Renderer::setMenuType()
HTML_Menu


Sets the type of the menu being rendered

HTML_Menu_Renderer::renderEntry()
Class Summary HTML_Menu_DirectRenderer
HTML_Menu
PHP Manual

HTML_Menu_Renderer::setMenuType()

(No version information available, might be only in CVS)

HTML_Menu_Renderer::setMenuType() — Sets the type of the menu being rendered

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_Renderer::setMenuType()/funcdef paramdefstring $menuType /paramdef /funcprototype /funcsynopsis

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.

HTML_Menu_Renderer::renderEntry()
Class Summary HTML_Menu_DirectRenderer
HTML_Menu


The renderer that generates HTML for the menu all by itself.

HTML_Menu_Renderer::setMenuType()
DirectRenderer::setEntryTemplate()
HTML_Menu
PHP Manual

Class Summary HTML_Menu_DirectRenderer

(No version information available, might be only in CVS)

Class Summary — 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.

HTML_Menu_Renderer::setMenuType()
DirectRenderer::setEntryTemplate()
HTML_Menu


Sets the template for menu entry.

Class Summary HTML_Menu_DirectRenderer
DirectRenderer::setMenuTemplate()
HTML_Menu
PHP Manual

DirectRenderer::setEntryTemplate()

(No version information available, might be only in CVS)

DirectRenderer::setEntryTemplate() — Sets the template for menu entry.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_DirectRenderer::setEntryTemplate()/funcdef paramdefmixed $type /paramdef paramdefstring $template = NULL /paramdef /funcprototype /funcsynopsis

Description

The template should contain at least the {title} placeholder, can also contain {url} and {indent} placeholders, depending on entry type. Default templates are:

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.

Class Summary HTML_Menu_DirectRenderer
DirectRenderer::setMenuTemplate()
HTML_Menu


Sets the menu template (HTML that wraps around rows)

DirectRenderer::setEntryTemplate()
DirectRenderer::setRowTemplate()
HTML_Menu
PHP Manual

DirectRenderer::setMenuTemplate()

(No version information available, might be only in CVS)

DirectRenderer::setMenuTemplate() — Sets the menu template (HTML that wraps around rows)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_DirectRenderer::setMenuTemplate()/funcdef paramdefstring $prepend /paramdef paramdefstring $append /paramdef /funcprototype /funcsynopsis

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.

DirectRenderer::setEntryTemplate()
DirectRenderer::setRowTemplate()
HTML_Menu


Sets the row template (HTML that wraps around entries)

DirectRenderer::setMenuTemplate()
DirectRenderer::toHtml()
HTML_Menu
PHP Manual

DirectRenderer::setRowTemplate()

(No version information available, might be only in CVS)

DirectRenderer::setRowTemplate() — Sets the row template (HTML that wraps around entries)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_DirectRenderer::setRowTemplate()/funcdef paramdefstring $prepend /paramdef paramdefstring $append /paramdef /funcprototype /funcsynopsis

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.

DirectRenderer::setMenuTemplate()
DirectRenderer::toHtml()
HTML_Menu


returns the HTML generated for the menu

DirectRenderer::setRowTemplate()
Class Summary HTML_Menu_DirectTreeRenderer
HTML_Menu
PHP Manual

DirectRenderer::toHtml()

(No version information available, might be only in CVS)

DirectRenderer::toHtml() — returns the HTML generated for the menu

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectRenderer.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Menu_DirectRenderer::toHtml()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

DirectRenderer::setRowTemplate()
Class Summary HTML_Menu_DirectTreeRenderer
HTML_Menu


The "direct" renderer for 'tree' and 'sitemap' menu types where level is represented by tags nesting.

DirectRenderer::toHtml()
DirectTreeRenderer::setEntryTemplate()
HTML_Menu
PHP Manual

Class Summary HTML_Menu_DirectTreeRenderer

(No version information available, might be only in CVS)

Class Summary — 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.

DirectRenderer::toHtml()
DirectTreeRenderer::setEntryTemplate()
HTML_Menu


Sets the template for menu entry.

Class Summary HTML_Menu_DirectTreeRenderer
DirectTreeRenderer::setItemTemplate()
HTML_Menu
PHP Manual

DirectTreeRenderer::setEntryTemplate()

(No version information available, might be only in CVS)

DirectTreeRenderer::setEntryTemplate() — Sets the template for menu entry.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectTreeRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_DirectTreeRenderer::setEntryTemplate()/funcdef paramdefmixed $type /paramdef paramdefstring $template = NULL /paramdef /funcprototype /funcsynopsis

Description

The template should contain at least the {title} placeholder, can also contain {url} placeholder. Default templates are:

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.

Class Summary HTML_Menu_DirectTreeRenderer
DirectTreeRenderer::setItemTemplate()
HTML_Menu


Sets the item template (HTML that wraps around entries)

DirectTreeRenderer::setEntryTemplate()
DirectTreeRenderer::setLevelTemplate()
HTML_Menu
PHP Manual

DirectTreeRenderer::setItemTemplate()

(No version information available, might be only in CVS)

DirectTreeRenderer::setItemTemplate() — Sets the item template (HTML that wraps around entries)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectTreeRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_DirectTreeRenderer::setRowTemplate()/funcdef paramdefstring $prepend /paramdef paramdefstring $append /paramdef /funcprototype /funcsynopsis

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.

DirectTreeRenderer::setEntryTemplate()
DirectTreeRenderer::setLevelTemplate()
HTML_Menu


Sets the level template (HTML that wraps around the submenu)

DirectTreeRenderer::setItemTemplate()
DirectTreeRenderer::toHtml()
HTML_Menu
PHP Manual

DirectTreeRenderer::setLevelTemplate()

(No version information available, might be only in CVS)

DirectTreeRenderer::setLevelTemplate() — Sets the level template (HTML that wraps around the submenu)

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectTreeRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Menu_DirectTreeRenderer::setLevelTemplate()/funcdef paramdefstring $prepend /paramdef paramdefstring $append /paramdef /funcprototype /funcsynopsis

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.

DirectTreeRenderer::setItemTemplate()
DirectTreeRenderer::toHtml()
HTML_Menu


returns the HTML generated for the menu

DirectTreeRenderer::setLevelTemplate()
Class Summary HTML_Menu_ArrayRenderer
HTML_Menu
PHP Manual

DirectTreeRenderer::toHtml()

(No version information available, might be only in CVS)

DirectTreeRenderer::toHtml() — returns the HTML generated for the menu

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/DirectTreeRenderer.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Menu_DirectTreeRenderer::toHtml()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

DirectTreeRenderer::setLevelTemplate()
Class Summary HTML_Menu_ArrayRenderer
HTML_Menu


The renderer that creates an array of visible menu entries.

DirectTreeRenderer::toHtml()
ArrayRenderer::toArray()
HTML_Menu
PHP Manual

Class Summary HTML_Menu_ArrayRenderer

(No version information available, might be only in CVS)

Class Summary — 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:

array(

    'entry1',

    ...

    'entryN'

)
while 'rows' produce a two-dimensional array:
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

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.

DirectTreeRenderer::toHtml()
ArrayRenderer::toArray()
HTML_Menu


returns the resultant array

Class Summary HTML_Menu_ArrayRenderer
Class Summary HTML_Menu_SigmaRenderer
HTML_Menu
PHP Manual

ArrayRenderer::toArray()

(No version information available, might be only in CVS)

ArrayRenderer::toArray() — returns the resultant array

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/ArrayRenderer.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Menu_ArrayRenderer::toArray()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_Menu_ArrayRenderer
Class Summary HTML_Menu_SigmaRenderer
HTML_Menu


The renderer that uses HTML_Template_Sigma instance for menu output.

ArrayRenderer::toArray()
constructor HTML_Menu_SigmaRenderer()
HTML_Menu
PHP Manual

Class Summary HTML_Menu_SigmaRenderer

(No version information available, might be only in CVS)

Class Summary — 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.

Blocks in the template (without prefix)
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.

ArrayRenderer::toArray()
constructor HTML_Menu_SigmaRenderer()
HTML_Menu


Class constructor.

Class Summary HTML_Menu_SigmaRenderer
Class Summary HTML_Menu_SigmaTreeRenderer
HTML_Menu
PHP Manual

constructor HTML_Menu_SigmaRenderer()

(No version information available, might be only in CVS)

constructor HTML_Menu_SigmaRenderer() — Class constructor.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/SigmaRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_Menu_SigmaRenderer::HTML_Menu_SigmaRenderer()/funcdef paramdefobject HTML_Template_Sigma &$tpl /paramdef paramdefstring $prefix = 'mu_' /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_Menu_SigmaRenderer
Class Summary HTML_Menu_SigmaTreeRenderer
HTML_Menu


HTML_Template_Sigma-based renderer for 'tree' and 'sitemap' type menus, where menu level is represented by tag nesting.

constructor HTML_Menu_SigmaRenderer()
constructor HTML_Menu_SigmaTreeRenderer()
HTML_Menu
PHP Manual

Class Summary HTML_Menu_SigmaTreeRenderer

(No version information available, might be only in CVS)

Class Summary — 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.

Blocks in the template (without prefix)
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.

constructor HTML_Menu_SigmaRenderer()
constructor HTML_Menu_SigmaTreeRenderer()
HTML_Menu


Class constructor.

Class Summary HTML_Menu_SigmaTreeRenderer
Class Summary HTML_MenuBrowser
HTML_Menu
PHP Manual

constructor HTML_Menu_SigmaTreeRenderer()

(No version information available, might be only in CVS)

constructor HTML_Menu_SigmaTreeRenderer() — Class constructor.

funcsynopsis funcsynopsisinfo require_once 'HTML/Menu/SigmaTreeRenderer.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_Menu_SigmaTreeRenderer::HTML_Menu_SigmaTreeRenderer()/funcdef paramdefobject HTML_Template_Sigma &$tpl /paramdef paramdefstring $prefix = 'mu_' /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_Menu_SigmaTreeRenderer
Class Summary HTML_MenuBrowser
HTML_Menu


constructor HTML_Menu_SigmaTreeRenderer()
constructor HTML_MenuBrowser::HTML_MenuBrowser()
HTML_Menu
PHP Manual

Class Summary HTML_MenuBrowser

(No version information available, might be only in CVS)

Class Summary — 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

constructor HTML_Menu_SigmaTreeRenderer()
constructor HTML_MenuBrowser::HTML_MenuBrowser()
HTML_Menu


Creates the object and optionally sets the directory to scan.

Class Summary HTML_MenuBrowser
HTML_MenuBrowser::addFileInfo()
HTML_Menu
PHP Manual

constructor HTML_MenuBrowser::HTML_MenuBrowser()

(No version information available, might be only in CVS)

constructor HTML_MenuBrowser::HTML_MenuBrowser() — Creates the object and optionally sets the directory to scan.

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_MenuBrowser::HTML_MenuBrowser()/funcdef paramdefstring $dir = '' /paramdef paramdefstring $index = '' /paramdef paramdefstring $file_suffix = '' /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_MenuBrowser
HTML_MenuBrowser::addFileInfo()
HTML_Menu


Adds further informations to the menu hash gathered from the files in it

constructor HTML_MenuBrowser::HTML_MenuBrowser()
HTML_MenuBrowser::browse()
HTML_Menu
PHP Manual

HTML_MenuBrowser::addFileInfo()

(No version information available, might be only in CVS)

HTML_MenuBrowser::addFileInfo() — Adds further informations to the menu hash gathered from the files in it

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_MenuBrowser::addFileInfo()/funcdef paramdefmixed $menu /paramdef /funcprototype /funcsynopsis

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.

constructor HTML_MenuBrowser::HTML_MenuBrowser()
HTML_MenuBrowser::browse()
HTML_Menu


Recursive function that does the scan and builds the menu (3) hash.

HTML_MenuBrowser::addFileInfo()
HTML_MenuBrowser::exploreFile()
HTML_Menu
PHP Manual

HTML_MenuBrowser::browse()

(No version information available, might be only in CVS)

HTML_MenuBrowser::browse() — Recursive function that does the scan and builds the menu (3) hash.

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_MenuBrowser::browse()/funcdef paramdefstring $dir /paramdef paramdefinteger $id = 0 /paramdef paramdefboolean $noindex = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_MenuBrowser::addFileInfo()
HTML_MenuBrowser::exploreFile()
HTML_Menu


Returns additional menu informations decoded in the file that appears in the menu.

HTML_MenuBrowser::browse()
HTML_MenuBrowser::getMenu()
HTML_Menu
PHP Manual

HTML_MenuBrowser::exploreFile()

(No version information available, might be only in CVS)

HTML_MenuBrowser::exploreFile() — Returns additional menu informations decoded in the file that appears in the menu.

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_MenuBrowser::exploreFile()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

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.

HTML_MenuBrowser::browse()
HTML_MenuBrowser::getMenu()
HTML_Menu


Returns a hash to be used with menu(3)'s setMenu().

HTML_MenuBrowser::exploreFile()
HTML_MenuBrowser::setDirectory()
HTML_Menu
PHP Manual

HTML_MenuBrowser::getMenu()

(No version information available, might be only in CVS)

HTML_MenuBrowser::getMenu() — Returns a hash to be used with menu(3)'s setMenu().

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_MenuBrowser::getMenu()/funcdef paramdefstring $dir = '' /paramdef paramdefstring $prefix = '' /paramdef /funcprototype /funcsynopsis

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.

HTML_MenuBrowser::exploreFile()
HTML_MenuBrowser::setDirectory()
HTML_Menu


Sets the directory to scan.

HTML_MenuBrowser::getMenu()
HTML_MenuBrowser::setIDPrefix()
HTML_Menu
PHP Manual

HTML_MenuBrowser::setDirectory()

(No version information available, might be only in CVS)

HTML_MenuBrowser::setDirectory() — Sets the directory to scan.

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_MenuBrowser::setDirectory()/funcdef paramdefstring $dir /paramdef /funcprototype /funcsynopsis

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.

HTML_MenuBrowser::getMenu()
HTML_MenuBrowser::setIDPrefix()
HTML_Menu


Sets the prefix for every id in the menu hash.

HTML_MenuBrowser::setDirectory()
Package HTML_Menu Constants
HTML_Menu
PHP Manual

HTML_MenuBrowser::setIDPrefix()

(No version information available, might be only in CVS)

HTML_MenuBrowser::setIDPrefix() — Sets the prefix for every id in the menu hash.

funcsynopsis funcsynopsisinfo require_once 'HTML/MenuBrowser.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_MenuBrowser::setIDPrefix()/funcdef paramdefstring $prefix /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $prefix

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_MenuBrowser::setDirectory()
Package HTML_Menu Constants
HTML_Menu


Constants defined in and used by HTML_Menu

HTML_Menu
HTML_Page2
HTML_Menu
PHP Manual

Package HTML_Menu Constants

(No version information available, might be only in CVS)

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')

HTML_Menu
HTML_Page2
HTML_Menu


HTML_Page2

API to create HTML Pages

Package HTML_Menu Constants
Creation
HTML


Making a new page

HTML_Page2
Headers
HTML_Page2
PHP Manual

Creation

(No version information available, might be only in CVS)

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.

    Default page settings

  • 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() .

Example #1 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();
?>
HTML_Page2
Headers
HTML_Page2


Setting title and other meta data

Creation
Body
HTML_Page2
PHP Manual

Headers

(No version information available, might be only in CVS)

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()

$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');
?>
Creation
Body
HTML_Page2


Adding content

Headers
Output
HTML_Page2
PHP Manual

Body

(No version information available, might be only in CVS)

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>');
?>
Headers
Output
HTML_Page2


Finishing the page

HTML_Page2
HTML_Progress
HTML_Page2
PHP Manual

Output

(No version information available, might be only in CVS)

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();
?>
HTML_Page2
HTML_Progress
HTML_Page2


HTML_Progress

Warning

This package has been superseded. Please use » HTML_Progress2 for new projects.

Output
HTML_Progress2
HTML


HTML_Progress2

How to include a loading bar in your XHTML documents quickly and easily

HTML_Progress
Introduction
HTML


A feature overview

HTML_Progress2
HTML_QuickForm
HTML_Progress2
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

HTML_Progress2
HTML_QuickForm
HTML_Progress2


Introduction
QuickStart
HTML
PHP Manual

HTML_QuickForm

The PEAR::HTML_QuickForm package provides methods for creating, validating, processing HTML forms.

Introduction

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.

Creating a basic form

To be written.

Classes representing form elements

To be written

Base classes

Standard HTML elements

Custom elements

Using groups

To be written.

Working with elements' values

This section covers the methods QuickForm offers for managing form element's values and working with submitted values.

Getting, setting and processing element values

Validation and filters

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.

Outputting the form

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.

Form customization and output helpers

Basic renderers

These renderers are based on pre-3.0 HTML_QuickForm code and require no external classes to do their work.

Template-based renderers

These renderers use template engines to actually generate the HTML for the form.

Renderer infrastructure

If you want to modify an existing renderer or write a new one, this section will be of interest to you.

Introduction
QuickStart
HTML


A tutorial for HTML_QuickForm

Introduction
PHP Manual

QuickStart

(No version information available, might be only in CVS)

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

Example #1 Basic QuickForm usage

// 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

$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

$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:

$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

$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:

$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:

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

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:

$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.

Introduction
PHP Manual


Answers to most Frequently Asked Questions

Introduction
PHP Manual

QuickHelp

(No version information available, might be only in CVS)

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

  1. The forms I generate with HTML_QuickForm cannot be submitted. When I look at the page's HTML source, I see something like <formArray>.
  2. When I pass some GET parameters to the script containing a form, QuickForm thinks that the form was already submitted, displaying validation errors.
  3. How do I set default/constant values for 'date' element?
  4. I receive weird "Call to a member function on a non-object" or "Undefined function" errors, especially when dealing with groups.
  5. QuickForm generates code which does not validate as XHTML Strict!
  6. The 'required' rule does not work for my elements!
  7. How do I change * denotes required field and Invalid information entered. / Please correct these fields. validation messages?

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:

$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:
$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.

Introduction


What elements can be added to QuickForm

Introduction
PHP Manual

QuickForm element types

(No version information available, might be only in CVS)

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.

Standard HTML 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

Custom element types
'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

Introduction


API changes to observe

Introduction
PHP Manual

Migration to version 3.2

(No version information available, might be only in CVS)

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()

$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

$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

$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:

$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:

$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:
$file =& $form->getElement('myfile');
if ($file->isUploadedFile()) {
     $fileInfo = $file->getValue();
}

Introduction


An overview about subpackages and packages that use QuickForm

Introduction
PHP Manual

Subpackages

(No version information available, might be only in CVS)

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.

Introduction


Class constructor

Introduction
PHP Manual

constructor HTML_QuickForm::HTML_QuickForm()

(No version information available, might be only in CVS)

constructor HTML_QuickForm::HTML_QuickForm() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::HTML_QuickForm()/funcdef paramdefstring $formName = '' /paramdef paramdefstring $method = 'post' /paramdef paramdefstring $action = '' /paramdef paramdefstring $target = '' /paramdef paramdefmixed $attributes = NULL /paramdef paramdefbool $trackSubmit = FALSE /paramdef /funcprototype /funcsynopsis

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.

Introduction


Adds an element into the form

Introduction
PHP Manual

HTML_QuickForm::addElement()

(No version information available, might be only in CVS)

HTML_QuickForm::addElement() — Adds an element into the form

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::addElement()/funcdef paramdefmixed $element /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns the current API version

Introduction
PHP Manual

HTML_QuickForm::apiVersion()

(No version information available, might be only in CVS)

HTML_QuickForm::apiVersion() — Returns the current API version

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdeffloat HTML_QuickForm::apiVersion()/funcdef ( void /funcprototype /funcsynopsis

Description

Returns the current API version

Throws

throws no exceptions thrown

Note

since 1.0

This function can be called statically.

Introduction


Creates a new form element of the given type

Introduction
PHP Manual

HTML_QuickForm::createElement()

(No version information available, might be only in CVS)

HTML_QuickForm::createElement() — Creates a new form element of the given type

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::createElement()/funcdef paramdefstring $elementType /paramdef /funcprototype /funcsynopsis

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.

Introduction


Checks if element is in the form

Introduction
PHP Manual

HTML_QuickForm::elementExists()

(No version information available, might be only in CVS)

HTML_QuickForm::elementExists() — Checks if element is in the form

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::elementExists()/funcdef paramdefstring $element = NULL /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns an error message for error code

Introduction
PHP Manual

HTML_QuickForm::errorMessage()

(No version information available, might be only in CVS)

HTML_QuickForm::errorMessage() — Returns an error message for error code

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::errorMessage()/funcdef paramdefint $value /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns the type of an element

Introduction
PHP Manual

HTML_QuickForm::getElementType()

(No version information available, might be only in CVS)

HTML_QuickForm::getElementType() — Returns the type of an element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::getElementType()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns a reference to the element

Introduction
PHP Manual

HTML_QuickForm::getElement()

(No version information available, might be only in CVS)

HTML_QuickForm::getElement() — Returns a reference to the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::getElement()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns the value of MAX_FILE_SIZE hidden element

Introduction
PHP Manual

HTML_QuickForm::getMaxFileSize()

(No version information available, might be only in CVS)

HTML_QuickForm::getMaxFileSize() — Returns the value of MAX_FILE_SIZE hidden element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefint HTML_QuickForm::getMaxFileSize()/funcdef ( void /funcprototype /funcsynopsis

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.

Introduction


Returns registered element types

Introduction
PHP Manual

HTML_QuickForm::getRegisteredTypes()

(No version information available, might be only in CVS)

HTML_QuickForm::getRegisteredTypes() — Returns registered element types

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm::getRegisteredTypes()/funcdef ( void /funcprototype /funcsynopsis

Description

Returns an array of registered element types.

Throws

throws

Note

since 1.0

This function can be called statically.

Introduction


Inserts a new element right before the other element

Introduction
PHP Manual

HTML_QuickForm::insertElementBefore()

(No version information available, might be only in CVS)

HTML_QuickForm::insertElementBefore() — Inserts a new element right before the other element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::insertElementBefore()/funcdef paramdefobject &$element /paramdef paramdefstring $nameAfter /paramdef /funcprototype /funcsynopsis

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():

$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.

Introduction


Tells whether a result is an error

Introduction
PHP Manual

HTML_QuickForm::isError()

(No version information available, might be only in CVS)

HTML_QuickForm::isError() — Tells whether a result is an error

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm::isError()/funcdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

Introduction


Checks whether the form element type is supported

Introduction
PHP Manual

HTML_QuickForm::isTypeRegistered()

(No version information available, might be only in CVS)

HTML_QuickForm::isTypeRegistered() — Checks whether the form element type is supported

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::isTypeRegistered()/funcdef paramdefstring $type /paramdef /funcprototype /funcsynopsis

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.

Introduction


Registers a new element type

Introduction
PHP Manual

HTML_QuickForm::registerElementType()

(No version information available, might be only in CVS)

HTML_QuickForm::registerElementType() — Registers a new element type

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::registerElementType()/funcdef paramdefstring $typeName /paramdef paramdefstring $include /paramdef paramdefstring $className /paramdef /funcprototype /funcsynopsis

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.

Introduction


Removes an element

Introduction
PHP Manual

HTML_QuickForm::removeElement()

(No version information available, might be only in CVS)

HTML_QuickForm::removeElement() — Removes an element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::removeElement()/funcdef paramdefstring $elementName /paramdef paramdefboolean $removeRules = TRUE /paramdef /funcprototype /funcsynopsis

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.

Introduction


Sets the value of MAX_FILE_SIZE hidden element

Introduction
PHP Manual

HTML_QuickForm::setMaxFileSize()

(No version information available, might be only in CVS)

HTML_QuickForm::setMaxFileSize() — Sets the value of MAX_FILE_SIZE hidden element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::setMaxFileSize()/funcdef paramdefint $bytes /paramdef /funcprototype /funcsynopsis

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.

Introduction


Updates Attributes for one or more elements

Introduction
PHP Manual

HTML_QuickForm::updateElementAttr()

(No version information available, might be only in CVS)

HTML_QuickForm::updateElementAttr() — Updates Attributes for one or more elements

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::updateElementAttr()/funcdef paramdefmixed $elements /paramdef paramdefmixed $attrs /paramdef /funcprototype /funcsynopsis

Description

Updates Attributes for one or more elements

Warning

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.

Introduction


Base class for form elements

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_element

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_element()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_element() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_element::HTML_QuickForm_element()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Accepts a renderer

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::accept()

(No version information available, might be only in CVS)

HTML_QuickForm_element::accept() — Accepts a renderer

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::accept()/funcdef paramdefobject HTML_QuickForm_Renderer &$renderer /paramdef paramdefbool $required = FALSE /paramdef paramdefstring $error = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the current API version

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::apiVersion()

(No version information available, might be only in CVS)

HTML_QuickForm_element::apiVersion() — Returns the current API version

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdeffloat HTML_QuickForm_element::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm::updateElementAttr()


Returns a 'safe' element's value (package developer related)

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::exportValue()

(No version information available, might be only in CVS)

HTML_QuickForm_element::exportValue() — Returns a 'safe' element's value (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_element::exportValue()/funcdef paramdefarray &$submitValues /paramdef paramdefbool $assoc = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Freezes the element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::freeze()

(No version information available, might be only in CVS)

HTML_QuickForm_element::freeze() — Freezes the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::freeze()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Freezing the text element

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";

Example #2 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" />
HTML_QuickForm::updateElementAttr()


Returns the value of field without HTML tags

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::getFrozenHtml()

(No version information available, might be only in CVS)

HTML_QuickForm_element::getFrozenHtml() — Returns the value of field without HTML tags

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_element::getFrozenHtml()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the label for the element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::getLabel()

(No version information available, might be only in CVS)

HTML_QuickForm_element::getLabel() — Returns the label for the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_element::getLabel()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the element name

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::getName()

(No version information available, might be only in CVS)

HTML_QuickForm_element::getName() — Returns the element name

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_element::getName()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the element type

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::getType()

(No version information available, might be only in CVS)

HTML_QuickForm_element::getType() — Returns the element type

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_element::getType()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm::updateElementAttr()


Returns the value of the form element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::getValue()

(No version information available, might be only in CVS)

HTML_QuickForm_element::getValue() — Returns the value of the form element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_element::getValue()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns whether or not the element is frozen

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::isFrozen()

(No version information available, might be only in CVS)

HTML_QuickForm_element::isFrozen() — Returns whether or not the element is frozen

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_element::isFrozen()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Called by HTML_QuickForm whenever form event is made on this element (package developer related)

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::onQuickFormEvent()

(No version information available, might be only in CVS)

HTML_QuickForm_element::onQuickFormEvent() — Called by HTML_QuickForm whenever form event is made on this element (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::onQuickFormEvent()/funcdef paramdefstring $event /paramdef paramdefmixed $arg /paramdef paramdefobject &$caller /paramdef /funcprototype /funcsynopsis

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.

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.

HTML_QuickForm::updateElementAttr()


Sets a label for the element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::setLabel()

(No version information available, might be only in CVS)

HTML_QuickForm_element::setLabel() — Sets a label for the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::setLabel()/funcdef paramdefmixed $label /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the input field name

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::setName()

(No version information available, might be only in CVS)

HTML_QuickForm_element::setName() — Sets the input field name

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::setName()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets whether element value should persist on freeze

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::setPersistantFreeze()

(No version information available, might be only in CVS)

HTML_QuickForm_element::setPersistantFreeze() — Sets whether element value should persist on freeze()

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::setPersistantFreeze()/funcdef paramdefbool $persistant = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the value of the form element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::setValue()

(No version information available, might be only in CVS)

HTML_QuickForm_element::setValue() — Sets the value of the form element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::setValue()/funcdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Unfreezes the element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_element::unfreeze()

(No version information available, might be only in CVS)

HTML_QuickForm_element::unfreeze() — Unfreezes the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/element.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_element::unfreeze()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Base class for input form elements

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_input

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_input()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_input() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/input.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_input::HTML_QuickForm_input()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the element type

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_input::setType()

(No version information available, might be only in CVS)

HTML_QuickForm_input::setType() — Sets the element type

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/input.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_input::setType()/funcdef paramdefstring $type /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a button type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_button

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_button()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_button() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/button.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_button::HTML_QuickForm_button()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $value = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a checkbox type field

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_checkbox

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_checkbox()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_checkbox() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/checkbox.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_checkbox::HTML_QuickForm_checkbox()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefstring $text = '' /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns whether a checkbox is checked

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_checkbox::getChecked()

(No version information available, might be only in CVS)

HTML_QuickForm_checkbox::getChecked() — Returns whether a checkbox is checked

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/checkbox.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_checkbox::getChecked()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the checkbox text

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_checkbox::getText()

(No version information available, might be only in CVS)

HTML_QuickForm_checkbox::getText() — Returns the checkbox text

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/checkbox.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_checkbox::getText()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets whether a checkbox is checked

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_checkbox::setChecked()

(No version information available, might be only in CVS)

HTML_QuickForm_checkbox::setChecked() — Sets whether a checkbox is checked

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/checkbox.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_checkbox::setChecked()/funcdef paramdefbool $checked /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the checkbox text

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_checkbox::setText()

(No version information available, might be only in CVS)

HTML_QuickForm_checkbox::setText() — Sets the checkbox text

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/checkbox.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_checkbox::setText()/funcdef paramdefstring $text /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a file type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_file

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_file()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_file() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/file.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_file::HTML_QuickForm_file()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns size of file element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_file::getSize()

(No version information available, might be only in CVS)

HTML_QuickForm_file::getSize() — Returns size of file element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/file.php'; /funcsynopsisinfo funcprototype funcdefint HTML_QuickForm_file::getSize()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns information about the uploaded file

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_file::getValue()

(No version information available, might be only in CVS)

HTML_QuickForm_file::getValue() — Returns information about the uploaded file

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/file.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm_file::getValue()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Checks if the element contains an uploaded file

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_file::isUploadedFile()

(No version information available, might be only in CVS)

HTML_QuickForm_file::isUploadedFile() — Checks if the element contains an uploaded file

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/file.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_file::isUploadedFile()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Moves an uploaded file into the destination

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_file::moveUploadedFile()

(No version information available, might be only in CVS)

HTML_QuickForm_file::moveUploadedFile() — Moves an uploaded file into the destination

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/file.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_file::moveUploadedFile()/funcdef paramdefstring $dest /paramdef paramdefstring $fileName = '' /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets size of file element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_file::setSize()

(No version information available, might be only in CVS)

HTML_QuickForm_file::setSize() — Sets size of file element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/file.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_file::setSize()/funcdef paramdefint $size /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a hidden type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_hidden

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_hidden()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_hidden() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/hidden.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_hidden::HTML_QuickForm_hidden()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $value = '' /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a image type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_image

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_image()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_image() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/image.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_image::HTML_QuickForm_image()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $src = '' /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets alignment for image element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_image::setAlign()

(No version information available, might be only in CVS)

HTML_QuickForm_image::setAlign() — Sets alignment for image element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/image.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_image::setAlign()/funcdef paramdefstring $align /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


Sets border size for image element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_image::setBorder()

(No version information available, might be only in CVS)

HTML_QuickForm_image::setBorder() — Sets border size for image element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/image.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_image::setBorder()/funcdef paramdefstring $border /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


Sets source for image element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_image::setSource()

(No version information available, might be only in CVS)

HTML_QuickForm_image::setSource() — Sets source for image element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/image.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_image::setSource()/funcdef paramdefstring $src /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


HTML class for a password type field

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_password

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_password()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_password() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/password.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_password::HTML_QuickForm_password()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets maxlength of password element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_password::setMaxlength()

(No version information available, might be only in CVS)

HTML_QuickForm_password::setMaxlength() — Sets maxlength of password element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/password.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_password::setMaxlength()/funcdef paramdefstring $maxlength /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


Sets size of password element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_password::setSize()

(No version information available, might be only in CVS)

HTML_QuickForm_password::setSize() — Sets size of password element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/password.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_password::setSize()/funcdef paramdefstring $size /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


HTML class for a radio type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_radio

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_radio()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_radio() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/radio.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_radio::HTML_QuickForm_radio()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefstring $text = NULL /paramdef paramdefstring $value = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns whether radio button is checked

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_radio::getChecked()

(No version information available, might be only in CVS)

HTML_QuickForm_radio::getChecked() — Returns whether radio button is checked

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/radio.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_radio::getChecked()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the radio text

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_radio::getText()

(No version information available, might be only in CVS)

HTML_QuickForm_radio::getText() — Returns the radio text

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/radio.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_radio::getText()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets whether radio button is checked

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_radio::setChecked()

(No version information available, might be only in CVS)

HTML_QuickForm_radio::setChecked() — Sets whether radio button is checked

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/radio.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_radio::setChecked()/funcdef paramdefbool $checked /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the radio text

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_radio::setText()

(No version information available, might be only in CVS)

HTML_QuickForm_radio::setText() — Sets the radio text

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/radio.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_radio::setText()/funcdef paramdefstring $text /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a reset type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_reset

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_reset()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_reset() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/reset.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_reset::HTML_QuickForm_reset()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $value = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Class to dynamically create an HTML SELECT

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_select

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_select()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_select() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_select::HTML_QuickForm_select()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefmixed $options = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Adds a new OPTION to the SELECT

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::addOption()

(No version information available, might be only in CVS)

HTML_QuickForm_select::addOption() — Adds a new OPTION to the SELECT

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_select::addOption()/funcdef paramdefstring $text /paramdef paramdefstring $value /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the select mutiple attribute

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::getMultiple()

(No version information available, might be only in CVS)

HTML_QuickForm_select::getMultiple() — Returns the select mutiple attribute

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_select::getMultiple()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the element name (possibly with brackets appended)

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::getPrivateName()

(No version information available, might be only in CVS)

HTML_QuickForm_select::getPrivateName() — Returns the element name (possibly with brackets appended)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_select::getPrivateName()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns an array of the selected values

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::getSelected()

(No version information available, might be only in CVS)

HTML_QuickForm_select::getSelected() — Returns an array of the selected values

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm_select::getSelected()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Returns the select field size

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::getSize()

(No version information available, might be only in CVS)

HTML_QuickForm_select::getSize() — Returns the select field size

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefint HTML_QuickForm_select::getSize()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Loads options from different types of data sources

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::load()

(No version information available, might be only in CVS)

HTML_QuickForm_select::load() — Loads options from different types of data sources

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefPEAR_Error HTML_QuickForm_select::load()/funcdef paramdefmixed &$options /paramdef paramdefmixed $param1 = NULL /paramdef paramdefmixed $param2 = NULL /paramdef paramdefmixed $param3 = NULL /paramdef paramdefmixed $param4 = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Loads the options from an associative array

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::loadArray()

(No version information available, might be only in CVS)

HTML_QuickForm_select::loadArray() — Loads the options from an associative array

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_select::loadArray()/funcdef paramdefarray $arr /paramdef paramdefmixed $values = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Loads the options from DB_result object

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::loadDbResult()

(No version information available, might be only in CVS)

HTML_QuickForm_select::loadDbResult() — Loads the options from DB_result object

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_select::loadDbResult()/funcdef paramdefobject DB_Result &$result /paramdef paramdefstring $textCol = NULL /paramdef paramdefstring $valueCol = NULL /paramdef paramdefmixed $values = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Queries a database and loads the options from the results

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::loadQuery()

(No version information available, might be only in CVS)

HTML_QuickForm_select::loadQuery() — Queries a database and loads the options from the results

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_select::loadQuery()/funcdef paramdefmixed &$conn /paramdef paramdefstring $sql /paramdef paramdefstring $textCol = NULL /paramdef paramdefstring $valueCol = NULL /paramdef paramdefmixed $values = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the select mutiple attribute

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::setMultiple()

(No version information available, might be only in CVS)

HTML_QuickForm_select::setMultiple() — Sets the select mutiple attribute

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_select::setMultiple()/funcdef paramdefbool $multiple /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the default values of the select box

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::setSelected()

(No version information available, might be only in CVS)

HTML_QuickForm_select::setSelected() — Sets the default values of the select box

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_select::setSelected()/funcdef paramdefmixed $values /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the select field size, only applies to 'multiple' selects

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_select::setSize()

(No version information available, might be only in CVS)

HTML_QuickForm_select::setSize() — Sets the select field size, only applies to 'multiple' selects

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/select.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_select::setSize()/funcdef paramdefint $size /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a submit type element

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_submit

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_submit()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_submit() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/submit.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_submit::HTML_QuickForm_submit()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $value = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a text field

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_text

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_text

(No version information available, might be only in CVS)

constructor HTML_QuickForm_text — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/text.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_text::HTML_QuickForm_text()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets maxlength of text field

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_text::setMaxlength()

(No version information available, might be only in CVS)

HTML_QuickForm_text::setMaxlength() — Sets maxlength of text field

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/text.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_text::setMaxlength()/funcdef paramdefstring $maxlength /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


Sets size of text field

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_text::setSize()

(No version information available, might be only in CVS)

HTML_QuickForm_text::setSize() — Sets size of text field

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/text.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_text::setSize()/funcdef paramdefstring $size /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$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.

HTML_QuickForm::updateElementAttr()


HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_textarea

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_textarea()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_textarea() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/textarea.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_textarea::HTML_QuickForm_textarea()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets width in cols for textarea element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_textarea::setCols()

(No version information available, might be only in CVS)

HTML_QuickForm_textarea::setCols() — Sets width in cols for textarea element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/textarea.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_textarea::setCols()/funcdef paramdefstring $cols /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets height in rows for textarea element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_textarea::setRows()

(No version information available, might be only in CVS)

HTML_QuickForm_textarea::setRows() — Sets height in rows for textarea element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/textarea.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_textarea::setRows()/funcdef paramdefstring $rows /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets wrap type for textarea element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_textarea::setWrap()

(No version information available, might be only in CVS)

HTML_QuickForm_textarea::setWrap() — Sets wrap type for textarea element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/textarea.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_textarea::setWrap()/funcdef paramdefstring $wrap /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Class for HTML 4.0

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_xbutton

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_xbutton()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_xbutton() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/xbutton.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_xbutton::HTML_QuickForm_xbutton()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementContent = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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

HTML_QuickForm::updateElementAttr()


Sets the contents of the element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_xbutton::setContent()

(No version information available, might be only in CVS)

HTML_QuickForm_xbutton::setContent() — Sets the contents of the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/xbutton.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_xbutton::setContent()/funcdef paramdefstring $content /paramdef /funcprototype /funcsynopsis

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

HTML_QuickForm::updateElementAttr()


HTML class for an advanced checkbox type field

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_advcheckbox

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_advcheckbox()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_advcheckbox() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/advcheckbox.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_advcheckbox::HTML_QuickForm_advcheckbox()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefstring $text = NULL /paramdef paramdefmixed $attributes = NULL /paramdef paramdefmixed $values = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Create the javascript for the onclick event

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_advcheckbox::getOnclickJs()

(No version information available, might be only in CVS)

HTML_QuickForm_advcheckbox::getOnclickJs() — Create the javascript for the onclick event

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/advcheckbox.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_advcheckbox::getOnclickJs()/funcdef paramdefstring $elementName /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Gets the private name for the element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_advcheckbox::getPrivateName()

(No version information available, might be only in CVS)

HTML_QuickForm_advcheckbox::getPrivateName() — Gets the private name for the element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/advcheckbox.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_advcheckbox::getPrivateName()/funcdef paramdefstring $elementName /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the values used by the hidden element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_advcheckbox::setValues()

(No version information available, might be only in CVS)

HTML_QuickForm_advcheckbox::setValues() — Sets the values used by the hidden element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/advcheckbox.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_advcheckbox::setValues()/funcdef paramdefmixed $values /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a text field with autocompletion feature

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_autocomplete

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_autocomplete

(No version information available, might be only in CVS)

constructor HTML_QuickForm_autocomplete — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/autocomplete.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_autocomplete::HTML_QuickForm_autocomplete()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefarray $options = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the options for the autocomplete input text element

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_autocomplete::setoptions()

(No version information available, might be only in CVS)

HTML_QuickForm_autocomplete::setoptions() — Sets the options for the autocomplete input text element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/autocomplete.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_autocomplete::setOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Class for a group of elements used to input dates (and times).

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_date

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_date()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_date() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/date.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_date::HTML_QuickForm_date()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefarray $options = array() /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

Description

The $options parameter controls the element's appearance. It is an associative array of the form 'option name' => 'option value'.

Recognised option names
'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.

HTML_QuickForm::updateElementAttr()


A pseudo-element used for adding headers to form

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_header

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_header()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_header() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/header.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_header::HTML_QuickForm_header()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $text = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Creates hidden elements with select's values

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_hiddenselect

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_hiddenselect()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_hiddenselect() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/hiddenselect.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_hiddenselect::HTML_QuickForm_hiddenselect()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefmixed $options = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Class to dynamically create chained HTML Select elements, each select changes the content of the next.

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_hierselect

(No version information available, might be only in CVS)

Class Summary — 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], ...

Example #1 Creating a hierselect element based on values from a database table

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.

Example #2 Creating a hierselect element with three select elements

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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_hierselect()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_hierselect() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/hierselect.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_hierselect::HTML_QuickForm_hierselect()/funcdef paramdefstring $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefmixed $attributes = NULL /paramdef paramdefmixed $separator = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the options for the select elements

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_hierselect::setOptions()

(No version information available, might be only in CVS)

HTML_QuickForm_hierselect::setOptions() — Sets the options for the select elements

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/hierselect.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_hierselect::setOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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

Example #1 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));
?>
HTML_QuickForm::updateElementAttr()


DEPRECATED: Sets the options for the first select

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_hierselect::setMainOptions()

(No version information available, might be only in CVS)

HTML_QuickForm_hierselect::setMainOptions() — DEPRECATED: Sets the options for the first select

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/hierselect.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_hierselect::setMainOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Warning

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 3.2.2

HTML_QuickForm::updateElementAttr()


DEPRECATED: Sets the options for the secondary select

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_hierselect::setSecOptions()

(No version information available, might be only in CVS)

HTML_QuickForm_hierselect::setSecOptions() — DEPRECATED: Sets the options for the secondary select

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/hierselect.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_hierselect::setSecOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Warning

This function is deprecated. That means that future versions of this package may not support it anymore.

Deprecated in release 3.2.2

Example

Example #1 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);
?>
HTML_QuickForm::updateElementAttr()


A pseudo-element used for adding raw HTML to form (deprecated)

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_html

(No version information available, might be only in CVS)

Class Summary — 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.

Warning

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.

Warning

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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_html()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_html() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/html.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_html::HTML_QuickForm_html()/funcdef paramdefstring $text = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


HTML class for a link type field

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_link

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_link()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_link() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/link.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_link::HTML_QuickForm_link()/funcdef paramdefmixed $elementName = NULL /paramdef paramdefstring $elementLabel = NULL /paramdef paramdefstring $href = NULL /paramdef paramdefstring $text = NULL /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the links href

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_link::setHref()

(No version information available, might be only in CVS)

HTML_QuickForm_link::setHref() — Sets the links href

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/link.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_link::setHref()/funcdef paramdefstring $href /paramdef /funcprototype /funcsynopsis

Description

This is just a shortcut for

$element->updateAttributes(array('href' => $href));

Parameter

string $href

Throws

throws

Note

since 1.0

This function can not be called statically.

HTML_QuickForm::updateElementAttr()


HTML class for static data

HTML_QuickForm::updateElementAttr()
PHP Manual

Class Summary HTML_QuickForm_static

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm::updateElementAttr()


Class constructor

HTML_QuickForm::updateElementAttr()
PHP Manual

constructor HTML_QuickForm_static()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_static() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/static.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_static::HTML_QuickForm_static()/funcdef paramdefstring $elementName = NULL /paramdef paramdefmixed $elementLabel = NULL /paramdef paramdefstring $text = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Sets the text

HTML_QuickForm::updateElementAttr()
PHP Manual

HTML_QuickForm_static::setText()

(No version information available, might be only in CVS)

HTML_QuickForm_static::setText() — Sets the text

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/static.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_static::setText()/funcdef paramdefstring $text /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm::updateElementAttr()


Adds an element group

Introduction
PHP Manual

HTML_QuickForm::addGroup()

(No version information available, might be only in CVS)

HTML_QuickForm::addGroup() — Adds an element group

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::addGroup()/funcdef paramdefarray $elements /paramdef paramdefstring $name = NULL /paramdef paramdefmixed $groupLabel = '' /paramdef paramdefstring $separator = NULL /paramdef paramdefstring $appendName = TRUE /paramdef /funcprototype /funcsynopsis

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

Example #1 Using addGroup()

<?php

$group[] =& HTML_QuickForm::createElement('text', 'first', 'First');
$group[] =& HTML_QuickForm::createElement('text', 'last', 'Last');

$form->addGroup($group, 'name', 'Name:', ',&nbsp;');

?>
Introduction


HTML class for a form element group

Introduction
PHP Manual

Class Summary HTML_QuickForm_group

(No version information available, might be only in CVS)

Class Summary — 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

Introduction


Class constructor

Introduction
PHP Manual

constructor HTML_QuickForm_group()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_group() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/group.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_group::HTML_QuickForm_group()/funcdef paramdefstring $elementName = NULL /paramdef paramdefarray $elementLabel = NULL /paramdef paramdefarray $elements = NULL /paramdef paramdefmixed $separator = NULL /paramdef paramdefbool $appendName = TRUE /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns the name of an element inside the group

Introduction
PHP Manual

HTML_QuickForm_group::getElementName()

(No version information available, might be only in CVS)

HTML_QuickForm_group::getElementName() — Returns the name of an element inside the group

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/group.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_group::getElementName()/funcdef paramdefmixed $index /paramdef /funcprototype /funcsynopsis

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.

Introduction


Gets the grouped elements

Introduction
PHP Manual

HTML_QuickForm_group::getElements()

(No version information available, might be only in CVS)

HTML_QuickForm_group::getElements() — Gets the grouped elements

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/group.php'; /funcsynopsisinfo funcprototype funcdefarray &HTML_QuickForm_group::getElements()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

since 2.4

This function can not be called statically.

Introduction


Gets the group type based on its elements.

Introduction
PHP Manual

HTML_QuickForm_group::getGroupType()

(No version information available, might be only in CVS)

HTML_QuickForm_group::getGroupType() — Gets the group type based on its elements.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/group.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_group::getGroupType()/funcdef paramdef /funcprototype /funcsynopsis

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.

Introduction


Sets the grouped elements

Introduction
PHP Manual

HTML_QuickForm_group::setElements()

(No version information available, might be only in CVS)

HTML_QuickForm_group::setElements() — Sets the grouped elements

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/group.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_group::setElements()/funcdef paramdefarray $elements /paramdef /funcprototype /funcsynopsis

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.

Introduction


Sets constant form values

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::setConstants()

(No version information available, might be only in CVS)

HTML_QuickForm::setConstants() — Sets constant form values

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::setConstants()/funcdef paramdefarray $constantValues = NULL /paramdef paramdefmixed $filter = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets default form values

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::setDefaults()

(No version information available, might be only in CVS)

HTML_QuickForm::setDefaults() — Sets default form values

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::setDefaults()/funcdef paramdefarray $defaultValues = NULL /paramdef paramdefmixed $filter = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Tells whether the form was already submitted

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::isSubmitted()

(No version information available, might be only in CVS)

HTML_QuickForm::isSubmitted() — Tells whether the form was already submitted

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::isSubmitted()/funcdef ( void /funcprototype /funcsynopsis

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

HTML_QuickForm_group::setElements()


Returns the element's "safe" value

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::exportValue()

(No version information available, might be only in CVS)

HTML_QuickForm::exportValue() — Returns the element's "safe" value

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm::exportValue()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns "safe" elements' values

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::exportValues()

(No version information available, might be only in CVS)

HTML_QuickForm::exportValues() — Returns "safe" elements' values

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm::exportValues()/funcdef paramdefmixed $elementList = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the element's raw value

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getElementValue()

(No version information available, might be only in CVS)

HTML_QuickForm::getElementValue() — Returns the element's raw value

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefmixed &HTML_QuickForm::getElementValue()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the submitted element's value

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getSubmitValue()

(No version information available, might be only in CVS)

HTML_QuickForm::getSubmitValue() — Returns the submitted element's value

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm::getSubmitValue()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the values submitted by the form

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getSubmitValues()

(No version information available, might be only in CVS)

HTML_QuickForm::getSubmitValues() — Returns the values submitted by the form

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm::getSubmitValues()/funcdef paramdefbool $mergeFiles = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Performs the form data processing

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::process()

(No version information available, might be only in CVS)

HTML_QuickForm::process() — Performs the form data processing

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::process()/funcdef paramdefmixed $callback /paramdef paramdefbool $mergeFiles = TRUE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


How to process submitted data

HTML_QuickForm_group::setElements()
PHP Manual

Introduction - validation and filters

(No version information available, might be only in CVS)

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.

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.

$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.

spanspec
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.

Example #1 Email validation function

/**
 * 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:

// 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.

Example #2 Complex group validation

// 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.

$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

$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:

$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.

HTML_QuickForm_group::setElements()


Adds a validation rule for the given field

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::addRule()

(No version information available, might be only in CVS)

HTML_QuickForm::addRule() — Adds a validation rule for the given field

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::addRule()/funcdef paramdefmixed $element /paramdef paramdefstring $message /paramdef paramdefstring $type /paramdef paramdefstring $format = '' /paramdef paramdefstring $validation = 'server' /paramdef paramdefboolean $reset = FALSE /paramdef paramdefboolean $force = FALSE /paramdef /funcprototype /funcsynopsis

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:

$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.

HTML_QuickForm_group::setElements()


Adds a validation rule for the given group

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::addGroupRule()

(No version information available, might be only in CVS)

HTML_QuickForm::addGroupRule() — Adds a validation rule for the given group

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::addGroupRule()/funcdef paramdefstring $group /paramdef paramdefmixed $arg1 /paramdef paramdefstring $type = '' /paramdef paramdefstring $format = '' /paramdef paramdefint $howmany = 0 /paramdef paramdefstring $validation = 'server' /paramdef paramdefbool $reset = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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')
    )
));
?>
HTML_QuickForm_group::setElements()


Adds a global validation rule

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::addFormRule()

(No version information available, might be only in CVS)

HTML_QuickForm::addFormRule() — Adds a global validation rule

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::addFormRule()/funcdef paramdefmixed $rule /paramdef /funcprototype /funcsynopsis

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

Example #1 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');
?>
HTML_QuickForm_group::setElements()


Returns whether the form element is required

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::isElementRequired()

(No version information available, might be only in CVS)

HTML_QuickForm::isElementRequired() — Returns whether the form element is required

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::isElementRequired()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Performs the server side validation

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::validate()

(No version information available, might be only in CVS)

HTML_QuickForm::validate() — Performs the server side validation

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::validate()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns error corresponding to validated element

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getElementError()

(No version information available, might be only in CVS)

HTML_QuickForm::getElementError() — Returns error corresponding to validated element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::getElementError()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Set error message for a form element

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::setElementError()

(No version information available, might be only in CVS)

HTML_QuickForm::setElementError() — Set error message for a form element

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::setElementError()/funcdef paramdefstring $element /paramdef paramdefstring $message /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Registers a new validation rule

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::registerRule()

(No version information available, might be only in CVS)

HTML_QuickForm::registerRule() — Registers a new validation rule

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::registerRule()/funcdef paramdefstring $ruleName /paramdef paramdefstring $type /paramdef paramdefstring $data1 /paramdef paramdefstring $data2 = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns registered validation rules

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getRegisteredRules()

(No version information available, might be only in CVS)

HTML_QuickForm::getRegisteredRules() — Returns registered validation rules

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm::getRegisteredRules()/funcdef ( void /funcprototype /funcsynopsis

Description

Returns an array of registered validation rules.

Throws

throws no exceptions thrown

Note

since 1.0

This function can not be called statically.

HTML_QuickForm_group::setElements()


Returns whether the rule is supported

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::isRuleRegistered()

(No version information available, might be only in CVS)

HTML_QuickForm::isRuleRegistered() — Returns whether the rule is supported

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::isRuleRegistered()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Applies a filter for the given field(s)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::applyFilter()

(No version information available, might be only in CVS)

HTML_QuickForm::applyFilter() — Applies a filter for the given field(s)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::applyFilter()/funcdef paramdefmixed $element /paramdef paramdefmixed $filter /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


"Freezes" the form's elements

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::freeze()

(No version information available, might be only in CVS)

HTML_QuickForm::freeze() — "Freezes" the form's elements

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::freeze()/funcdef paramdefmixed $elementList = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Checks whether the element is frozen

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::isElementFrozen()

(No version information available, might be only in CVS)

HTML_QuickForm::isElementFrozen() — Checks whether the element is frozen

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::isElementFrozen()/funcdef paramdefstring $element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Checks whether the form is frozen

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::isFrozen()

(No version information available, might be only in CVS)

HTML_QuickForm::isFrozen() — Checks whether the form is frozen

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_QuickForm::isFrozen()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets required note

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::setRequiredNote()

(No version information available, might be only in CVS)

HTML_QuickForm::setRequiredNote() — Sets required note

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::setRequiredNote()/funcdef paramdefstring $note /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets JavaScript warning messages

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::setJsWarnings()

(No version information available, might be only in CVS)

HTML_QuickForm::setJsWarnings() — Sets JavaScript warning messages

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::setJsWarnings()/funcdef paramdefstring $pref /paramdef paramdefstring $post /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the required note

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getRequiredNote()

(No version information available, might be only in CVS)

HTML_QuickForm::getRequiredNote() — Returns the required note

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::getRequiredNote()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the client side validation script

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::getValidationScript()

(No version information available, might be only in CVS)

HTML_QuickForm::getValidationScript() — Returns the client side validation script

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::getValidationScript()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Accepts a renderer

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::accept()

(No version information available, might be only in CVS)

HTML_QuickForm::accept() — Accepts a renderer

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm::accept()/funcdef paramdefobject &$renderer /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns a reference to default renderer object

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::defaultRenderer()

(No version information available, might be only in CVS)

HTML_QuickForm::defaultRenderer() — Returns a reference to default renderer object

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefobject &HTML_QuickForm::defaultRenderer()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the form's contents in an array

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::toArray()

(No version information available, might be only in CVS)

HTML_QuickForm::toArray() — Returns the form's contents in an array

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm::toArray()/funcdef paramdefboolean $collectHidden = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns an HTML version of the form

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::toHtml()

(No version information available, might be only in CVS)

HTML_QuickForm::toHtml() — Returns an HTML version of the form

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::toHtml()/funcdef paramdefstring $in_data = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Outputs an HTML version of the form

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm::display()

(No version information available, might be only in CVS)

HTML_QuickForm::display() — Outputs an HTML version of the form

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm::display()/funcdef paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


How to output the form

HTML_QuickForm_group::setElements()
PHP Manual

Introduction - renderers

(No version information available, might be only in CVS)

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.

HTML_QuickForm_group::setElements()


Default renderer

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default

(No version information available, might be only in CVS)

— 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.

Example #1 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.

HTML_QuickForm_group::setElements()


Clears all templates

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::clearAllTemplates()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::clearAllTemplates() — Clears all templates

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::clearAllTemplates()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets element template

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::setElementTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::setElementTemplate() — Sets element template

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::setElementTemplate()/funcdef paramdefstring $html /paramdef paramdefstring $element = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets form template

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::setFormTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::setFormTemplate() — Sets form template

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::setFormTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets template for group elements

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::setGroupElementTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::setGroupElementTemplate() — Sets template for group elements

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::setGroupElementTemplate()/funcdef paramdefstring $html /paramdef paramdefstring $group /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets template for a group wrapper

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::setGroupTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::setGroupTemplate() — Sets template for a group wrapper

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::setGroupTemplate()/funcdef paramdefstring $html /paramdef paramdefstring $group /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets header template

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::setHeaderTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::setHeaderTemplate() — Sets header template

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::setHeaderTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the template for 'required' note

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate() — Sets the template for 'required' note

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Default::setRequiredNoteTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the HTML

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Default::toHtml()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Default::toHtml() — Returns the HTML

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Default.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Renderer_Default::toHtml()/funcdef ( void /funcprototype /funcsynopsis

Description

Returns the HTML generated for the form.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTML_QuickForm_group::setElements()


Array representation of the form

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Array

(No version information available, might be only in CVS)

— 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.

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Array.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Array::HTML_QuickForm_Renderer_Array()/funcdef paramdef bool $collectHidden = FALSE bool $staticLabels = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets a style to use for element rendering

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Array::setElementStyle()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Array::setElementStyle() — Sets a style to use for element rendering

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Array.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Array::setElementStyle()/funcdef paramdefmixed $elementName /paramdef paramdefstring $styleName = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the resultant array

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Array::toArray()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Array::toArray() — Returns the resultant array

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Array.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm_Renderer_Array::toArray()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Object representation of the form

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Object

(No version information available, might be only in CVS)

— 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" xml: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.

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Object.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_Object::HTML_QuickForm_Renderer_Object()/funcdef paramdef bool $collectHidden = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Returns the resultant object

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_Object::toObject()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_Object::toObject() — Returns the resultant object

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/Object.php'; /funcsynopsisinfo funcprototype funcdefQuickformForm HTML_QuickForm_Renderer_Object::toObject()/funcdef ( void /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


A renderer for 'static' Smarty templates

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ArraySmarty

(No version information available, might be only in CVS)

— 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'
);

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ArraySmarty.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ArraySmarty::HTML_QuickForm_Renderer_ArraySmarty()/funcdef paramdefmixed &$tpl /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the way elements with validation errors are rendered

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate() — Sets the way elements with validation errors are rendered

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ArraySmarty.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ArraySmarty::setErrorTemplate()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the way required elements are rendered

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate() — Sets the way required elements are rendered

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ArraySmarty.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ArraySmarty::setRequiredTemplate()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Dynamic renderer for Integrated Templates

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ITDynamic

(No version information available, might be only in CVS)

— 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>

Blocks in the template
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.

Placeholders in the template
{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.

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ITDynamic.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ITDynamic::HTML_QuickForm_Renderer_ITDynamic()/funcdef paramdefobject &$tpl /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the block to use for element rendering

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ITDynamic::setElementBlock()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ITDynamic::setElementBlock() — Sets the block to use for element rendering

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ITDynamic.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ITDynamic::setElementBlock()/funcdef paramdefmixed $elementName /paramdef paramdefstring $blockName = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the name of a block to use for header rendering

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock() — Sets the name of a block to use for header rendering

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ITDynamic.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ITDynamic::setHeaderBlock()/funcdef paramdefstring $blockName /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Static renderer for Integrated Templates

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ITStatic

(No version information available, might be only in CVS)

— 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.

Example #1 Defining the elements

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.

Example #2 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.

Example #3 Using the renderer

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.

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ITStatic.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ITStatic::HTML_QuickForm_Renderer_ITStatic()/funcdef paramdefobject &$tpl /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the way elements with validation errors are rendered

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ITStatic::setErrorTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ITStatic::setErrorTemplate() — Sets the way elements with validation errors are rendered

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ITStatic.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ITStatic::setErrorTemplate()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Sets the way required elements are rendered

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate() — Sets the way required elements are rendered

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ITStatic.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ITStatic::setRequiredTemplate()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


A renderer for Flexy templates

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ObjectFlexy

(No version information available, might be only in CVS)

— 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.

Example #1 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

Example #2 A template for the labels

{if:required}
    <font color="red" size="1">*</font>
{end:}
{label:h}
html.html

Example #3 A template for the overall html

{if:error}
    <font color="orange" size="1">{error:h}</font><br />
{end:}
{html:h}
flexy-static.html

Example #4 A template for the form

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--  $Id: html-quickform-renderer-objectflexy.xml,v 1.1 2008/03/21 21:38:44 saltybeagle 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.

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ObjectFlexy::HTML_QuickForm_Renderer_ObjectFlexy()/funcdef paramdefobject &$flexy /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Set the filename of the template to render html elements.

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate() — Set the filename of the template to render html elements.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ObjectFlexy::setHtmlTemplate()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Set the filename of the template to render html elements.

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate() — Set the filename of the template to render html elements.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/ObjectFlexy.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_ObjectFlexy::setLabelTemplate()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Render form elements into HTML in an easy and flexible manner

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_QuickHtml

(No version information available, might be only in CVS)

— 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

Example #1 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);
?>

HTML_QuickForm_group::setElements()


Constructor

HTML_QuickForm_group::setElements()
PHP Manual

constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/QuickHtml.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer_QuickHtml::HTML_QuickForm_Renderer_QuickHtml()/funcdef ( void /funcprototype /funcsynopsis

Description

The constructor for HTML_QuickForm_Renderer_QuickHtml().

Throws

throws no exceptions thrown

HTML_QuickForm_group::setElements()


Returns the HTML

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_QuickHtml::toHtml()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_QuickHtml::toHtml() — Returns the HTML

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/QuickHtml.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Renderer_QuickHtml::toHtml()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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

HTML_QuickForm_group::setElements()


Renders a specific form element into HTML

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer_QuickHtml::elementToHtml()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer_QuickHtml::elementToHtml() — Renders a specific form element into HTML

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer/QuickHtml.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Renderer_QuickHtml::elementToHtml()/funcdef paramdefstring $elementName /paramdef paramdefstring $elementValue /paramdef /funcprototype /funcsynopsis

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

HTML_QuickForm_group::setElements()


Abstract base class for renderers (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer

(No version information available, might be only in CVS)

— 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.

HTML_QuickForm_group::setElements()


Start visiting a form (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::startForm()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::startForm() — Start visiting a form (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::startForm()/funcdef paramdefobject &$form /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Finish visiting a form (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::finishForm()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::finishForm() — Finish visiting a form (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::finishForm()/funcdef paramdefobject &$form /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Start visiting a group (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::startGroup()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::startGroup() — Start visiting a group (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::startGroup()/funcdef paramdefobject &$group /paramdef paramdefbool $required /paramdef paramdefstring $error /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Finish visiting a group (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::finishGroup()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::finishGroup() — Finish visiting a group (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::finishGroup()/funcdef paramdefobject &$group /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Visit an element (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::renderElement()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::renderElement() — Visit an element (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::renderElement()/funcdef paramdefobject &$element /paramdef paramdefbool $required /paramdef paramdefstring $error /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Visit a header (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::renderHeader()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::renderHeader() — Visit a header (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::renderHeader()/funcdef paramdefobject &$header /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Visit a hidden element (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::renderHidden()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::renderHidden() — Visit a hidden element (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::renderHidden()/funcdef paramdefobject &$element /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


Visit a raw HTML/text element (package developer related)

HTML_QuickForm_group::setElements()
PHP Manual

HTML_QuickForm_Renderer::renderHtml()

(No version information available, might be only in CVS)

HTML_QuickForm_Renderer::renderHtml() — Visit a raw HTML/text element (package developer related)

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Renderer.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Renderer::renderHtml()/funcdef paramdefobject &$data /paramdef /funcprototype /funcsynopsis

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.

HTML_QuickForm_group::setElements()


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).

HTML_QuickForm_Renderer::renderHtml()
Introduction
HTML


What is this package useful for

HTML_QuickForm_Controller
FAQ
HTML_QuickForm_Controller
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

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:

Example #1 Basic Controller usage

// 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:

$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

$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

$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

$page =& new FirstPage('firstForm');
and add our custom action handler to it
$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

$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

$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

$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.

HTML_QuickForm_Controller
FAQ
HTML_QuickForm_Controller


Understanding package features

Introduction
Class Summary HTML_QuickForm_Controller
HTML_QuickForm_Controller
PHP Manual

FAQ

(No version information available, might be only in CVS)

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.

Default action names
'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:

$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:

// Note the reference
$data =& $page->controller->container();
$data['_my_stuff'] = $stuff;
On the target page you do
$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
    $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;

Introduction
Class Summary HTML_QuickForm_Controller
HTML_QuickForm_Controller


The class implementing a PageController pattern.

FAQ
constructor HTML_QuickForm_Controller()
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Controller

(No version information available, might be only in CVS)

Class Summary — 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

FAQ
constructor HTML_QuickForm_Controller()
HTML_QuickForm_Controller


Class constructor.

Class Summary HTML_QuickForm_Controller
Controller::addAction()
HTML_QuickForm_Controller
PHP Manual

constructor HTML_QuickForm_Controller()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Controller() — Class constructor.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_Controller::HTML_QuickForm_Controller()/funcdef paramdefstring $name /paramdef paramdefbool $modal = TRUE /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Controller
Controller::addAction()
HTML_QuickForm_Controller


Registers a handler for a specific action.

constructor HTML_QuickForm_Controller()
Controller::addPage()
HTML_QuickForm_Controller
PHP Manual

Controller::addAction()

(No version information available, might be only in CVS)

Controller::addAction() — Registers a handler for a specific action.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::addAction()/funcdef paramdefstring $actionName /paramdef paramdefobject HTML_QuickForm_Action &$action /paramdef /funcprototype /funcsynopsis

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.

constructor HTML_QuickForm_Controller()
Controller::addPage()
HTML_QuickForm_Controller


Adds a new page to the form

Controller::addAction()
Controller::applyDefaults()
HTML_QuickForm_Controller
PHP Manual

Controller::addPage()

(No version information available, might be only in CVS)

Controller::addPage() — Adds a new page to the form

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::addPage()/funcdef paramdefobject HTML_QuickForm_Page &$page /paramdef /funcprototype /funcsynopsis

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.

Controller::addAction()
Controller::applyDefaults()
HTML_QuickForm_Controller


Sets the default values for the given page

Controller::addPage()
Controller::container()
HTML_QuickForm_Controller
PHP Manual

Controller::applyDefaults()

(No version information available, might be only in CVS)

Controller::applyDefaults() — Sets the default values for the given page

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::applyDefaults()/funcdef paramdefstring $pageName /paramdef /funcprototype /funcsynopsis

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.

Controller::addPage()
Controller::container()
HTML_QuickForm_Controller


Returns a reference to the form's values container.

Controller::applyDefaults()
Controller::exportValue()
HTML_QuickForm_Controller
PHP Manual

Controller::container()

(No version information available, might be only in CVS)

Controller::container() — Returns a reference to the form's values container.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefarray &HTML_QuickForm_Controller::container()/funcdef paramdefbool $reset = FALSE /paramdef /funcprototype /funcsynopsis

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.

Controller::applyDefaults()
Controller::exportValue()
HTML_QuickForm_Controller


Returns the element's value

Controller::container()
Controller::exportValues()
HTML_QuickForm_Controller
PHP Manual

Controller::exportValue()

(No version information available, might be only in CVS)

Controller::exportValue() — Returns the element's value

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_QuickForm_Controller::exportValue()/funcdef paramdefstring $pageName /paramdef paramdefstring $elementName /paramdef /funcprototype /funcsynopsis

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.

Controller::container()
Controller::exportValues()
HTML_QuickForm_Controller


Returns the form's values

Controller::exportValue()
Controller::findInvalid()
HTML_QuickForm_Controller
PHP Manual

Controller::exportValues()

(No version information available, might be only in CVS)

Controller::exportValues() — Returns the form's values

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm_Controller::exportValues()/funcdef paramdefstring $pageName = NULL /paramdef /funcprototype /funcsynopsis

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.

Controller::exportValue()
Controller::findInvalid()
HTML_QuickForm_Controller


Finds the (first) invalid page

Controller::exportValues()
Controller::getActionName()
HTML_QuickForm_Controller
PHP Manual

Controller::findInvalid()

(No version information available, might be only in CVS)

Controller::findInvalid() — Finds the (first) invalid page

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Controller::findInvalid()/funcdef paramdef /funcprototype /funcsynopsis

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.

Controller::exportValues()
Controller::getActionName()
HTML_QuickForm_Controller


Finds the names of the current page and the current action.

Controller::findInvalid()
Controller::getNextName()
HTML_QuickForm_Controller
PHP Manual

Controller::getActionName()

(No version information available, might be only in CVS)

Controller::getActionName() — Finds the names of the current page and the current action.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_QuickForm_Controller::getActionName()/funcdef paramdef /funcprototype /funcsynopsis

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.

Controller::findInvalid()
Controller::getNextName()
HTML_QuickForm_Controller


Returns the name of the page after the given.

Controller::getActionName()
Controller::getPage()
HTML_QuickForm_Controller
PHP Manual

Controller::getNextName()

(No version information available, might be only in CVS)

Controller::getNextName() — Returns the name of the page after the given.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Controller::getNextName()/funcdef paramdefstring $pageName /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $pageName

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Controller::getActionName()
Controller::getPage()
HTML_QuickForm_Controller


Returns a page

Controller::getNextName()
Controller::getPrevName()
HTML_QuickForm_Controller
PHP Manual

Controller::getPage()

(No version information available, might be only in CVS)

Controller::getPage() — Returns a page

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdef object HTML_QuickForm_Page &HTML_QuickForm_Controller::getPage()/funcdef paramdefstring $pageName /paramdef /funcprototype /funcsynopsis

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.

Controller::getNextName()
Controller::getPrevName()
HTML_QuickForm_Controller


Returns the name of the page before the given.

Controller::getPage()
Controller::handle()
HTML_QuickForm_Controller
PHP Manual

Controller::getPrevName()

(No version information available, might be only in CVS)

Controller::getPrevName() — Returns the name of the page before the given.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Controller::getPrevName()/funcdef paramdefstring $pageName /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $pageName

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Controller::getPage()
Controller::handle()
HTML_QuickForm_Controller


Handles an action.

Controller::getPrevName()
Controller::isModal()
HTML_QuickForm_Controller
PHP Manual

Controller::handle()

(No version information available, might be only in CVS)

Controller::handle() — Handles an action.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::handle()/funcdef paramdefobject HTML_QuickForm_Page &$page /paramdef paramdefstring $actionName /paramdef /funcprototype /funcsynopsis

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.

Controller::getPrevName()
Controller::isModal()
HTML_QuickForm_Controller


Checks whether the form is modal.

Controller::handle()
Controller::isValid()
HTML_QuickForm_Controller
PHP Manual

Controller::isModal()

(No version information available, might be only in CVS)

Controller::isModal() — Checks whether the form is modal.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_Controller::isModal()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Controller::handle()
Controller::isValid()
HTML_QuickForm_Controller


Checks whether the pages of the controller are valid

Controller::isModal()
Controller::run()
HTML_QuickForm_Controller
PHP Manual

Controller::isValid()

(No version information available, might be only in CVS)

Controller::isValid() — Checks whether the pages of the controller are valid

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_Controller::isValid()/funcdef paramdefstring $pageName = NULL /paramdef /funcprototype /funcsynopsis

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.

Controller::isModal()
Controller::run()
HTML_QuickForm_Controller


Processes the request.

Controller::isValid()
Controller::setConstants()
HTML_QuickForm_Controller
PHP Manual

Controller::run()

(No version information available, might be only in CVS)

Controller::run() — Processes the request.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::run()/funcdef paramdef /funcprototype /funcsynopsis

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.

Controller::isValid()
Controller::setConstants()
HTML_QuickForm_Controller


Initializes constant form values.

Controller::run()
Controller::setDefaults()
HTML_QuickForm_Controller
PHP Manual

Controller::setConstants()

(No version information available, might be only in CVS)

Controller::setConstants() — Initializes constant form values.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::setConstants()/funcdef paramdefarray $constantValues = NULL /paramdef /funcprototype /funcsynopsis

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.

Controller::run()
Controller::setDefaults()
HTML_QuickForm_Controller


Initializes default form values.

Controller::setConstants()
Class Summary HTML_QuickForm_Page
HTML_QuickForm_Controller
PHP Manual

Controller::setDefaults()

(No version information available, might be only in CVS)

Controller::setDefaults() — Initializes default form values.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Controller.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Controller::setDefaults()/funcdef paramdefarray $defaultValues = NULL /paramdef /funcprototype /funcsynopsis

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.

Controller::setConstants()
Class Summary HTML_QuickForm_Page
HTML_QuickForm_Controller


The class represents a page of a multipage form.

Controller::setDefaults()
constructor HTML_QuickForm_Page()
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Page

(No version information available, might be only in CVS)

Class Summary — 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

Controller::setDefaults()
constructor HTML_QuickForm_Page()
HTML_QuickForm_Controller


Class constructor

Class Summary HTML_QuickForm_Page
Page::addAction()
HTML_QuickForm_Controller
PHP Manual

constructor HTML_QuickForm_Page()

(No version information available, might be only in CVS)

constructor HTML_QuickForm_Page() — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTML_QuickForm_Page::HTML_QuickForm_Page()/funcdef paramdefstring $formName /paramdef paramdefstring $method = 'post' /paramdef paramdefstring $target = '_self' /paramdef paramdefmixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Page
Page::addAction()
HTML_QuickForm_Controller


Registers a handler for a specific action.

constructor HTML_QuickForm_Page()
Page::buildForm()
HTML_QuickForm_Controller
PHP Manual

Page::addAction()

(No version information available, might be only in CVS)

Page::addAction() — Registers a handler for a specific action.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Page::addAction()/funcdef paramdefstring $actionName /paramdef paramdefobject HTML_QuickForm_Action &$action /paramdef /funcprototype /funcsynopsis

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.

constructor HTML_QuickForm_Page()
Page::buildForm()
HTML_QuickForm_Controller


Builds a form.

Page::addAction()
Page::getButtonName()
HTML_QuickForm_Controller
PHP Manual

Page::buildForm()

(No version information available, might be only in CVS)

Page::buildForm() — Builds a form.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Page::buildForm()/funcdef paramdef /funcprototype /funcsynopsis

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.

Page::addAction()
Page::getButtonName()
HTML_QuickForm_Controller


Returns a name for a submit button that will invoke a specific action.

Page::buildForm()
Page::handle()
HTML_QuickForm_Controller
PHP Manual

Page::getButtonName()

(No version information available, might be only in CVS)

Page::getButtonName() — Returns a name for a submit button that will invoke a specific action.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_QuickForm_Page::getButtonName()/funcdef paramdefstring $actionName /paramdef /funcprototype /funcsynopsis

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

$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.

Page::buildForm()
Page::handle()
HTML_QuickForm_Controller


Handles an action.

Page::getButtonName()
Page::isFormBuilt()
HTML_QuickForm_Controller
PHP Manual

Page::handle()

(No version information available, might be only in CVS)

Page::handle() — Handles an action.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Page::handle()/funcdef paramdefstring $actionName /paramdef /funcprototype /funcsynopsis

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.

Page::getButtonName()
Page::isFormBuilt()
HTML_QuickForm_Controller


Checks whether the form was already built.

Page::handle()
Page::loadValues()
HTML_QuickForm_Controller
PHP Manual

Page::isFormBuilt()

(No version information available, might be only in CVS)

Page::isFormBuilt() — Checks whether the form was already built.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_QuickForm_Page::isFormBuilt()/funcdef paramdef /funcprototype /funcsynopsis

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.

Page::handle()
Page::loadValues()
HTML_QuickForm_Controller


Loads the submit values from the array.

Page::isFormBuilt()
Page::setDefaultAction()
HTML_QuickForm_Controller
PHP Manual

Page::loadValues()

(No version information available, might be only in CVS)

Page::loadValues() — Loads the submit values from the array.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Page::loadValues()/funcdef paramdefarray $values /paramdef /funcprototype /funcsynopsis

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.

Page::isFormBuilt()
Page::setDefaultAction()
HTML_QuickForm_Controller


Sets the default action invoked on page-form submit.

Page::loadValues()
Class Summary HTML_QuickForm_Action
HTML_QuickForm_Controller
PHP Manual

Page::setDefaultAction()

(No version information available, might be only in CVS)

Page::setDefaultAction() — Sets the default action invoked on page-form submit.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Page.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Page::setDefaultAction()/funcdef paramdefstring $actionName /paramdef /funcprototype /funcsynopsis

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.

Page::loadValues()
Class Summary HTML_QuickForm_Action
HTML_QuickForm_Controller


Class representing an action to perform on HTTP request.

Page::setDefaultAction()
Action::perform()
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action

(No version information available, might be only in CVS)

Class Summary — 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.

Page::setDefaultAction()
Action::perform()
HTML_QuickForm_Controller


Processes the request.

Class Summary HTML_QuickForm_Action
Class Summary HTML_QuickForm_Action_Back
HTML_QuickForm_Controller
PHP Manual

Action::perform()

(No version information available, might be only in CVS)

Action::perform() — Processes the request.

funcsynopsis funcsynopsisinfo require_once 'HTML/QuickForm/Action.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_QuickForm_Action::perform()/funcdef paramdefobject HTML_QuickForm_Page &$page /paramdef paramdefstring $actionName /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action
Class Summary HTML_QuickForm_Action_Back
HTML_QuickForm_Controller


The action for a 'back' button of wizard-type multipage form.

Action::perform()
Class Summary HTML_QuickForm_Action_Direct
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action_Back

(No version information available, might be only in CVS)

Class Summary — 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

Action::perform()
Class Summary HTML_QuickForm_Action_Direct
HTML_QuickForm_Controller


This action allows to go to a specific page of a multipage form.

Class Summary HTML_QuickForm_Action_Back
Class Summary HTML_QuickForm_Action_Display
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action_Direct

(No version information available, might be only in CVS)

Class Summary — 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

Class Summary HTML_QuickForm_Action_Back
Class Summary HTML_QuickForm_Action_Display
HTML_QuickForm_Controller


This action handles the output of the form.

Class Summary HTML_QuickForm_Action_Direct
Class Summary HTML_QuickForm_Action_Jump
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action_Display

(No version information available, might be only in CVS)

Class Summary — 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

Class Summary HTML_QuickForm_Action_Direct
Class Summary HTML_QuickForm_Action_Jump
HTML_QuickForm_Controller


The action handles the HTTP redirect to a specific page.

Class Summary HTML_QuickForm_Action_Display
Class Summary HTML_QuickForm_Action_Next
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action_Jump

(No version information available, might be only in CVS)

Class Summary — 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

Class Summary HTML_QuickForm_Action_Display
Class Summary HTML_QuickForm_Action_Next
HTML_QuickForm_Controller


The action for a 'next' button of wizard-type multipage form.

Class Summary HTML_QuickForm_Action_Jump
Class Summary HTML_QuickForm_Action_Submit
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action_Next

(No version information available, might be only in CVS)

Class Summary — 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

Class Summary HTML_QuickForm_Action_Jump
Class Summary HTML_QuickForm_Action_Submit
HTML_QuickForm_Controller


The action for a 'submit' button.

HTML_QuickForm_Controller
HTML_QuickForm_Renderer_Tableless
HTML_QuickForm_Controller
PHP Manual

Class Summary HTML_QuickForm_Action_Submit

(No version information available, might be only in CVS)

Class Summary — 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

HTML_QuickForm_Controller
HTML_QuickForm_Renderer_Tableless
HTML_QuickForm_Controller


Class Summary HTML_QuickForm_Action_Submit
Introduction
HTML
PHP Manual

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.

Introduction

Important methods

Class Summary HTML_QuickForm_Action_Submit
Introduction
HTML


Introduction to HTML_QuickForm_Renderer_Tableless

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

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:

$form->removeAttribute('name');
Class Summary HTML_QuickForm_Action_Submit


Answers to most Frequently Asked Questions

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

FAQ

(No version information available, might be only in CVS)

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

Class Summary HTML_QuickForm_Action_Submit


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)

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements()

(No version information available, might be only in CVS)

— 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)

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::addStopFieldsetElements()/funcdef paramdefmixed $element /paramdef paramdefstring $class = '' /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Clears all the HTML out of the templates that surround notes, elements, etc.

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::clearAllTemplates()

(No version information available, might be only in CVS)

— Clears all the HTML out of the templates that surround notes, elements, etc.

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_tableless::clearAllTemplates()/funcdef paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets element template

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setElementTemplate()

(No version information available, might be only in CVS)

— Sets element template

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setElementTemplate()/funcdef paramdefstring $html /paramdef paramdefstring $element = NULL /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets the template used when closing a fieldset

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate()

(No version information available, might be only in CVS)

— Sets the template used when closing a fieldset

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setCloseFieldsetTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets form template

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setFormTemplate()

(No version information available, might be only in CVS)

— Sets form template

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setFormTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets element template for elements within a group

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setGroupElementTemplate()

(No version information available, might be only in CVS)

— Sets element template for elements within a group

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_tableless::setGroupElementTemplate()/funcdef paramdefstring $html /paramdef paramdefstring $group /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets template for a group wrapper

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setGroupTemplate()

(No version information available, might be only in CVS)

— Sets template for a group wrapper

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setGroupTemplate()/funcdef paramdefstring $html /paramdef paramdefstring $group /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets header template

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setHeaderTemplate()

(No version information available, might be only in CVS)

— Sets header template

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setHeaderTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets the template used when opening a fieldset

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate()

(No version information available, might be only in CVS)

— Sets the template used when opening a fieldset

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setOpenFieldsetTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets the template used when opening a hidden fieldset (i.e. a fieldset that is opened when there is no header element)

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate()

(No version information available, might be only in CVS)

— Sets the template used when opening a hidden fieldset (i.e. a fieldset that is opened when there is no header element)

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setOpenHiddenFieldsetTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


Sets the note indicating required fields template

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate()

(No version information available, might be only in CVS)

— Sets the note indicating required fields template

funcsynopsis funcprototype funcdefvoid HTML_QuickForm_Renderer_Tableless::setRequiredNoteTemplate()/funcdef paramdefstring $html /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTML_QuickForm_Action_Submit


returns the HTML generated for the form

Class Summary HTML_QuickForm_Action_Submit
PHP Manual

HTML_QuickForm_Renderer_Tableless::toHtml()

(No version information available, might be only in CVS)

— returns the HTML generated for the form

funcsynopsis funcprototype funcdefstring HTML_QuickForm_Renderer_Tableless::toHtml()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the HTML generated for the form.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTML_QuickForm_Action_Submit


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).

Usage

To use this package you just need to do something like this:

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:

$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:

$form->getValidationScript();
HTML_QuickForm_Renderer_Tableless::toHtml
HTML_QuickForm_advmultiselect
HTML


HTML_QuickForm_advmultiselect

Element for HTML_QuickForm that emulate a multi-select.

HTML_QuickForm_DHTMLRulesTableless
Introduction
HTML


A feature overview

HTML_QuickForm_advmultiselect
HTML_Table
HTML_QuickForm_advmultiselect
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — A feature overview

Description

HTML_QuickForm_advmultiselect (qfams) is designed as custom QuickForm element to emulates via two select boxes a select box that allows selecting of multiple options.

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
  • JavaScript functions can be renamed to avoid conflict with others scripts on the same page
  • 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

External support resources

  • » external documentation ( full user guide in english )

  • » external documentation ( full user guide in french )

  • » Download page to get the full definitive guide. Three formats available : single HTML page, many HTML pages, Windows HTML help.

HTML_QuickForm_advmultiselect
HTML_Table
HTML_QuickForm_advmultiselect


HTML_Table

API to create HTML tables

Introduction
Introduction
HTML


Creating an HTML-Table

HTML_Table
FAQ
HTML_Table
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

$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" .

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:
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.

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.

$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.

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.

$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.

HTML_Table
FAQ
HTML_Table


Answers to most Frequently Asked Questions

Introduction
Constructor HTML_Table::HTML_Table()
HTML_Table
PHP Manual

FAQ

(No version information available, might be only in CVS)

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.

$table = new HTML_Table();
// [...]
$thead =& $table->getHeader();
$thead->setAttributes(array('id' => 'header'));
// [...]
$table->display();

This would give the following result:

<table>
  <thead xml: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.

Introduction
Constructor HTML_Table::HTML_Table()
HTML_Table


Constructor

FAQ
HTML_Table::addBody()
HTML_Table
PHP Manual

Constructor HTML_Table::HTML_Table()

(No version information available, might be only in CVS)

Constructor HTML_Table::HTML_Table() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::HTML_Table()/funcdef paramdef array $attributes = NULL /paramdef paramdef integer $tabOffset=0 /paramdef paramdef boolean $useTGroups=false /paramdef /funcprototype /funcsynopsis

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()

FAQ
HTML_Table::addBody()
HTML_Table


Add body

Constructor HTML_Table::HTML_Table()
HTML_Table::addCol()
HTML_Table
PHP Manual

HTML_Table::addBody()

(No version information available, might be only in CVS)

HTML_Table::addBody() — Add body

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefint HTML_Table::addBody()/funcdef paramdef array $attributes = NULL /paramdef /funcprototype /funcsynopsis

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()

Constructor HTML_Table::HTML_Table()
HTML_Table::addCol()
HTML_Table


Add column

HTML_Table::addBody()
HTML_Table::addRow()
HTML_Table
PHP Manual

HTML_Table::addCol()

(No version information available, might be only in CVS)

HTML_Table::addCol() — Add column

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefint HTML_Table::addCol()/funcdef paramdef array $contents = NULL /paramdef paramdef mixed $attributes = NULL /paramdef paramdef string $type='TD' /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::addBody()
HTML_Table::addRow()
HTML_Table


Add row

HTML_Table::addCol()
HTML_Table::altRowAttributes()
HTML_Table
PHP Manual

HTML_Table::addRow()

(No version information available, might be only in CVS)

HTML_Table::addRow() — Add row

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefint HTML_Table::addRow()/funcdef paramdef array $contents = NULL /paramdef paramdef mixed $attributes = NULL /paramdef paramdef string $type='TD' /paramdef paramdef boolean $inTR = FALSE /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::addCol()
HTML_Table::altRowAttributes()
HTML_Table


Alternate row attributes

HTML_Table::addRow()
HTML_Table::apiVersion()
HTML_Table
PHP Manual

HTML_Table::altRowAttributes()

(No version information available, might be only in CVS)

HTML_Table::altRowAttributes() — Alternate row attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::altRowAttributes()/funcdef paramdef int $start /paramdef paramdef mixed $attributes1 /paramdef paramdef mixed $attributes2 /paramdef paramdef boolean $inTR = FALSE /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::addRow()
HTML_Table::apiVersion()
HTML_Table


Return API version (DEPRECATED)

HTML_Table::altRowAttributes()
HTML_Table::display()
HTML_Table
PHP Manual

HTML_Table::apiVersion()

(No version information available, might be only in CVS)

HTML_Table::apiVersion() — Return API version (DEPRECATED)

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefdouble HTML_Table::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

Description

DEPRECATED: Returns the API version of HTML_Table

Return value

double - the version number

Note

This function can not be called statically.

Warning

This function is deprecated. That means that future versions of this package may not support it anymore.

HTML_Table::altRowAttributes()
HTML_Table::display()
HTML_Table


Output HTML code

HTML_Table::apiVersion()
HTML_Table::getAutoFill()
HTML_Table
PHP Manual

HTML_Table::display()

(No version information available, might be only in CVS)

HTML_Table::display() — Output HTML code

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Table::display()/funcdef paramdef /funcprototype /funcsynopsis

Description

Outputs the table structure as HTML

Note

This function can not be called statically.

See

HTML_Table::toHtml()

HTML_Table::apiVersion()
HTML_Table::getAutoFill()
HTML_Table


Return autoFill value

HTML_Table::display()
HTML_Table::getAutoGrow()
HTML_Table
PHP Manual

HTML_Table::getAutoFill()

(No version information available, might be only in CVS)

HTML_Table::getAutoFill() — Return autoFill value

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Table::getAutoFill()/funcdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::display()
HTML_Table::getAutoGrow()
HTML_Table


Return autoGrow flag

HTML_Table::getAutoFill()
HTML_Table::getBody()
HTML_Table
PHP Manual

HTML_Table::getAutoGrow()

(No version information available, might be only in CVS)

HTML_Table::getAutoGrow() — Return autoGrow flag

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_Table::getAutoGrow()/funcdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getAutoFill()
HTML_Table::getBody()
HTML_Table


Return the table object for the tbody group

HTML_Table::getAutoGrow()
HTML_Table::getCellAttributes()
HTML_Table
PHP Manual

HTML_Table::getBody()

(No version information available, might be only in CVS)

HTML_Table::getBody() — Return the table object for the tbody group

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Table::getBody()/funcdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getAutoGrow()
HTML_Table::getCellAttributes()
HTML_Table


Return cell attributes

HTML_Table::getBody()
HTML_Table::getCellContents()
HTML_Table
PHP Manual

HTML_Table::getCellAttributes()

(No version information available, might be only in CVS)

HTML_Table::getCellAttributes() — Return cell attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Table::getCellAttributes()/funcdef paramdef int $row /paramdef paramdef int $col /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getBody()
HTML_Table::getCellContents()
HTML_Table


Return cell content

HTML_Table::getCellAttributes()
HTML_Table::getColCount()
HTML_Table
PHP Manual

HTML_Table::getCellContents()

(No version information available, might be only in CVS)

HTML_Table::getCellContents() — Return cell content

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Table::getCellContents()/funcdef paramdef int $row /paramdef paramdef int $col /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::getCellAttributes()
HTML_Table::getColCount()
HTML_Table


Return numbers of column

HTML_Table::getCellContents()
HTML_Table::getFooter()
HTML_Table
PHP Manual

HTML_Table::getColCount()

(No version information available, might be only in CVS)

HTML_Table::getColCount() — Return numbers of column

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefint HTML_Table::getColCount()/funcdef paramdef int $row=null /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getCellContents()
HTML_Table::getFooter()
HTML_Table


Return the table object for the tfoot group

HTML_Table::getColCount()
HTML_Table::getHeader()
HTML_Table
PHP Manual

HTML_Table::getFooter()

(No version information available, might be only in CVS)

HTML_Table::getFooter() — Return the table object for the tfoot group

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Table::getFooter()/funcdef paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getColCount()
HTML_Table::getHeader()
HTML_Table


Return the table object for the thead group

HTML_Table::getFooter()
HTML_Table::getRowAttributes()
HTML_Table
PHP Manual

HTML_Table::getHeader()

(No version information available, might be only in CVS)

HTML_Table::getHeader() — Return the table object for the thead group

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Table::getHeader()/funcdef paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getFooter()
HTML_Table::getRowAttributes()
HTML_Table


Return row attributes

HTML_Table::getHeader()
HTML_Table::getRowCount()
HTML_Table
PHP Manual

HTML_Table::getRowAttributes()

(No version information available, might be only in CVS)

HTML_Table::getRowAttributes() — Return row attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Table::getRowAttributes()/funcdef paramdef int $row /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::getHeader()
HTML_Table::getRowCount()
HTML_Table


Return number of rows

HTML_Table::getRowAttributes()
HTML_Table::setAllAttributes()
HTML_Table
PHP Manual

HTML_Table::getRowCount()

(No version information available, might be only in CVS)

HTML_Table::getRowCount() — Return number of rows

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefint HTML_Table::getRowCount()/funcdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getRowAttributes()
HTML_Table::setAllAttributes()
HTML_Table


Set attributes for all cells

HTML_Table::getRowCount()
HTML_Table::setAutoGrow()
HTML_Table
PHP Manual

HTML_Table::setAllAttributes()

(No version information available, might be only in CVS)

HTML_Table::setAllAttributes() — Set attributes for all cells

funcsynopsis funcsynopsisinfo require_once 'HTML_Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setAllAttributes()/funcdef paramdef mixed $attributes = NULL /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::getRowCount()
HTML_Table::setAutoGrow()
HTML_Table


Set autoGrow flag

HTML_Table::setAllAttributes()
HTML_Table::setAutoFill()
HTML_Table
PHP Manual

HTML_Table::setAutoGrow()

(No version information available, might be only in CVS)

HTML_Table::setAutoGrow() — Set autoGrow flag

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setAutoGrow()/funcdef paramdef bool $grow /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setAllAttributes()
HTML_Table::setAutoFill()
HTML_Table


Set autoFill value

HTML_Table::setAutoGrow()
HTML_Table::setCaption()
HTML_Table
PHP Manual

HTML_Table::setAutoFill()

(No version information available, might be only in CVS)

HTML_Table::setAutoFill() — Set autoFill value

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setAutoFill()/funcdef paramdef mixed $fill /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setAutoGrow()
HTML_Table::setCaption()
HTML_Table


Set table caption

HTML_Table::setAutoFill()
HTML_Table::setCellAttributes()
HTML_Table
PHP Manual

HTML_Table::setCaption()

(No version information available, might be only in CVS)

HTML_Table::setCaption() — Set table caption

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setCaption()/funcdef paramdef string $caption /paramdef paramdef mixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::setAutoFill()
HTML_Table::setCellAttributes()
HTML_Table


Set cell attributes

HTML_Table::setCaption()
HTML_Table::setCellContents()
HTML_Table
PHP Manual

HTML_Table::setCellAttributes()

(No version information available, might be only in CVS)

HTML_Table::setCellAttributes() — Set cell attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setCellAttributes()/funcdef paramdef int $row /paramdef paramdef int $col /paramdef paramdef mixed $attributes /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setCaption()
HTML_Table::setCellContents()
HTML_Table


Set cell content

HTML_Table::setCellAttributes()
HTML_Table::setColAttributes()
HTML_Table
PHP Manual

HTML_Table::setCellContents()

(No version information available, might be only in CVS)

HTML_Table::setCellContents() — Set cell content

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setCellContents()/funcdef paramdef int $row /paramdef paramdef int $col /paramdef paramdef mixed $contents /paramdef paramdef string $type='TD' /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setCellAttributes()
HTML_Table::setColAttributes()
HTML_Table


Set column attributes

HTML_Table::setCellContents()
HTML_Table::setColCount()
HTML_Table
PHP Manual

HTML_Table::setColAttributes()

(No version information available, might be only in CVS)

HTML_Table::setColAttributes() — Set column attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setColAttributes()/funcdef paramdef int $col /paramdef paramdef mixed $attributes = NULL /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setCellContents()
HTML_Table::setColCount()
HTML_Table


Set number of columns

HTML_Table::setColAttributes()
HTML_Table::setColGroup()
HTML_Table
PHP Manual

HTML_Table::setColCount()

(No version information available, might be only in CVS)

HTML_Table::setColCount() — Set number of columns

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setColCount()/funcdef paramdef int $cols /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setColAttributes()
HTML_Table::setColGroup()
HTML_Table


Set a colgroup

HTML_Table::setColCount()
HTML_Table::setColType()
HTML_Table
PHP Manual

HTML_Table::setColGroup()

(No version information available, might be only in CVS)

HTML_Table::setColGroup() — Set a colgroup

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setColGroup()/funcdef paramdef mixed $colgroup = NULL /paramdef paramdef mixed $attributes = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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);
?>

Example #2 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);
?>

Example #3 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.

HTML_Table::setColCount()
HTML_Table::setColType()
HTML_Table


Set column type

HTML_Table::setColGroup()
HTML_Table::setHeaderContents()
HTML_Table
PHP Manual

HTML_Table::setColType()

(No version information available, might be only in CVS)

HTML_Table::setColType() — Set column type

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setColType()/funcdef paramdef int $col /paramdef paramdef string $type /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::setColGroup()
HTML_Table::setHeaderContents()
HTML_Table


Set content of header cell

HTML_Table::setColType()
HTML_Table::setRowCount()
HTML_Table
PHP Manual

HTML_Table::setHeaderContents()

(No version information available, might be only in CVS)

HTML_Table::setHeaderContents() — Set content of header cell

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setHeaderContents()/funcdef paramdef int $row /paramdef paramdef int $col /paramdef paramdef mixed $contents /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setColType()
HTML_Table::setRowCount()
HTML_Table


Set row number

HTML_Table::setHeaderContents()
HTML_Table::setRowType()
HTML_Table
PHP Manual

HTML_Table::setRowCount()

(No version information available, might be only in CVS)

HTML_Table::setRowCount() — Set row number

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setRowCount()/funcdef paramdef int $rows /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setHeaderContents()
HTML_Table::setRowType()
HTML_Table


Set row type

HTML_Table::setRowCount()
HTML_Table::setRowAttributes()
HTML_Table
PHP Manual

HTML_Table::setRowType()

(No version information available, might be only in CVS)

HTML_Table::setRowType() — Set row type

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setRowType()/funcdef paramdef int $row /paramdef paramdef string $type /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setRowCount()
HTML_Table::setRowAttributes()
HTML_Table


Set row attributes

HTML_Table::setRowType()
HTML_Table::toHtml()
HTML_Table
PHP Manual

HTML_Table::setRowAttributes()

(No version information available, might be only in CVS)

HTML_Table::setRowAttributes() — Set row attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::setRowAttributes()/funcdef paramdef int $row /paramdef paramdef mixed $attributes /paramdef paramdef boolean $inTR = FALSE /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setRowType()
HTML_Table::toHtml()
HTML_Table


Return HTML code

HTML_Table::setRowAttributes()
HTML_Table::updateAllAttributes()
HTML_Table
PHP Manual

HTML_Table::toHtml()

(No version information available, might be only in CVS)

HTML_Table::toHtml() — Return HTML code

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Table::toHtml()/funcdef paramdef /funcprototype /funcsynopsis

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()

HTML_Table::setRowAttributes()
HTML_Table::updateAllAttributes()
HTML_Table


Update attributes of all cells

HTML_Table::toHtml()
HTML_Table::updateCellAttributes()
HTML_Table
PHP Manual

HTML_Table::updateAllAttributes()

(No version information available, might be only in CVS)

HTML_Table::updateAllAttributes() — Update attributes of all cells

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::updateAllAttributes()/funcdef paramdef mixed $attributes = NULL /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::toHtml()
HTML_Table::updateCellAttributes()
HTML_Table


Update cell attributes

HTML_Table::updateAllAttributes()
HTML_Table::updateColAttributes()
HTML_Table
PHP Manual

HTML_Table::updateCellAttributes()

(No version information available, might be only in CVS)

HTML_Table::updateCellAttributes() — Update cell attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::updateCellAttributes()/funcdef paramdef int $row /paramdef paramdef int $col /paramdef paramdef mixed $attributes /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::updateAllAttributes()
HTML_Table::updateColAttributes()
HTML_Table


Update column attributes

HTML_Table::updateCellAttributes()
HTML_Table::updateRowAttributes()
HTML_Table
PHP Manual

HTML_Table::updateColAttributes()

(No version information available, might be only in CVS)

HTML_Table::updateColAttributes() — Update column attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::updateColAttributes()/funcdef paramdef int $col /paramdef paramdef mixed $attributes = NULL /paramdef paramdef int $body=NULL /paramdef /funcprototype /funcsynopsis

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.

HTML_Table::updateCellAttributes()
HTML_Table::updateRowAttributes()
HTML_Table


Update row attributes

HTML_Table
HTML_TagCloud
HTML_Table
PHP Manual

HTML_Table::updateRowAttributes()

(No version information available, might be only in CVS)

HTML_Table::updateRowAttributes() — Update row attributes

funcsynopsis funcsynopsisinfo require_once 'HTML/Table.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Table::updateRowAttributes()/funcdef paramdef int $row /paramdef paramdef mixed $attributes = NULL /paramdef paramdef boolean $inTR = FALSE /paramdef paramdef int $body=0 /paramdef /funcprototype /funcsynopsis

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.

HTML_Table
HTML_TagCloud
HTML_Table


HTML_TagCloud

Create and display defined "tags" (words) in a "tag cloud".

HTML_Table::updateRowAttributes()
Introduction
HTML


Introduction to HTML_TagCloud.

HTML_TagCloud
Usage examples
HTML_TagCloud
PHP Manual
Shoma Suzuki

Introduction

(No version information available, might be only in CVS)

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

Example #1 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.

HTML_TagCloud
Usage examples
HTML_TagCloud


Using HTML_TagCloud.

HTML_TagCloud
HTML_Template_Flexy
HTML_TagCloud
PHP Manual
Shoma Suzuki

Usage examples

(No version information available, might be only in CVS)

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.

Example #1 output HTML and CSS separately

// 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.

Example #2 Decoration example

class MyTags extends HTML_TagCloud
{
    protected $epoc_level = 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.

Example #3 Omitting the timeline

$tags->addElement('PHP','http://www.php.net', 39);
HTML_TagCloud
HTML_Template_Flexy
HTML_TagCloud


HTML_Template_Flexy

An extremely flexible Template core, with multiple engines.

Usage examples
Introduction
HTML


What HTML_Template_Flexy can do

HTML_Template_Flexy
Configuration Options
HTML_Template_Flexy
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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 #2 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

Example #3 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
HTML_Template_Flexy
Configuration Options
HTML_Template_Flexy


Setting the defaults for HTML_Template_Flexy

Introduction
new HTML_Template_Flexy
HTML_Template_Flexy
PHP Manual

Configuration Options

(No version information available, might be only in CVS)

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)

Example #1 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)

Example #2 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

Example #3 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

Introduction
new HTML_Template_Flexy
HTML_Template_Flexy


constructor

Configuration Options
$flexy->compile()
HTML_Template_Flexy
PHP Manual

new HTML_Template_Flexy

(No version information available, might be only in CVS)

new HTML_Template_Flexy — constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Flexy.php'; /funcsynopsisinfo funcprototype funcdefnew HTML_Template_Flexy()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Configuration Options
$flexy->compile()
HTML_Template_Flexy


Converts a template from markup to PHP if required

new HTML_Template_Flexy
$flexy->outputObject()
HTML_Template_Flexy
PHP Manual

$flexy->compile()

(No version information available, might be only in CVS)

$flexy->compile() — Converts a template from markup to PHP if required

funcsynopsis funcprototype funcdefvoid $flexy-> compile()/funcdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

Description

If neccessary 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 neccessary 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

Example #1 Compiling multiple files.

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;

Example #2 Master template example

Page Header Goes here.

{outputBody()}

Page Footer Goes here

Example #3 Simple ouput example

Page Header Goes here.

some numbers
Number 1
Number 2
Number 3
Number 4

Page Footer Goes here
new HTML_Template_Flexy
$flexy->outputObject()
HTML_Template_Flexy


Merges a controller object with the template and outputs the result

$flexy->compile()
$flexy->bufferedOutputObject()
HTML_Template_Flexy
PHP Manual

$flexy->outputObject()

(No version information available, might be only in CVS)

$flexy->outputObject() — Merges a controller object with the template and outputs the result

funcsynopsis funcprototype funcdefvoid $flexy-> outputObject()/funcdef paramdefobject $controllerObject /paramdef paramdefarray $elements /paramdef /funcprototype /funcsynopsis

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

Example #1 PHP code initiating the template, and outputing it

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);

Example #2 The Template with some tags

<B>{tag}</B>
<B>{tag:h}</B>
<INPUT name="test">

Example #3 Resulting output

<B>&gt;&gt; hello world</B>
<B>>> hello world</B>
<INPUT name="test" value="hello input">
$flexy->compile()
$flexy->bufferedOutputObject()
HTML_Template_Flexy


Merges a controller object with the template and returns the result

$flexy->outputObject()
$flexy->getElements()
HTML_Template_Flexy
PHP Manual

$flexy->bufferedOutputObject()

(No version information available, might be only in CVS)

$flexy->bufferedOutputObject() — Merges a controller object with the template and returns the result

funcsynopsis funcprototype funcdefstring $flexy->bufferedOutputObject()/funcdef paramdefobject $controllerObject /paramdef paramdefarray $elements /paramdef /funcprototype /funcsynopsis

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

Example #1 Person DataObject send_password method

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);

        }

}

Example #2 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 :)

Example #3 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 :)
$flexy->outputObject()
$flexy->getElements()
HTML_Template_Flexy


Fetch Dynamic HTML Elements from template

$flexy->bufferedOutputObject()
new HTML_Template_Flexy_Element
HTML_Template_Flexy
PHP Manual

$flexy->getElements()

(No version information available, might be only in CVS)

$flexy->getElements() — Fetch Dynamic HTML Elements from template

funcsynopsis funcprototype funcdefarray $flexy-> getElements()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Introspecting a template

$form = new HTML_Template_Flexy();
$form->compile('some_file_name');
print_r($form->getElements());

Example #2 template example

<BODY>
  <FORM name="XXXX">
    <INPUT name="yyy">
    <SELECT name="zzz">
       <OPTION value="aaaa">AAAAA</OPTION>
    </SELECT>
  </FORM>
</BODY>

Example #3 template compiled

<BODY>
  <?php echo $this->elements['XXXX']->toHtmlnoClose();?>
    <?php echo $this->elements['yyy']->toHtml();?>
    <?php echo $this->elements['zzz']->toHtml();?>
  </form>
</BODY>

Example #4 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] =>
        )

)
$flexy->bufferedOutputObject()
new HTML_Template_Flexy_Element
HTML_Template_Flexy


Class constructor

$flexy->getElements()
$element->setValue()
HTML_Template_Flexy
PHP Manual

new HTML_Template_Flexy_Element

(No version information available, might be only in CVS)

new HTML_Template_Flexy_Element — Class constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Flexy/Element.php'; /funcsynopsisinfo funcprototype funcdefnew HTML_Template_Flexy_Element()/funcdef paramdefstring $tag = '' /paramdef paramdefarray $attributes = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Using an element to change a template.

$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

Example #2 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" xml:id="yes" value="yes" />yes<br />
    <input name="test_radio" type="radio" xml:id="no" value="no" />no<br />

  </form>
</body>

Example #3 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 value="1234" selected>another selection 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" xml:id="yes" value="yes" checked>yes<br />
    <input name="test_radio" type="radio" xml:id="no" value="no">no<br />

  </form>
</body>
$flexy->getElements()
$element->setValue()
HTML_Template_Flexy


Utility function to set or store values from common tag types.

new HTML_Template_Flexy_Element
$element->setOptions()
HTML_Template_Flexy
PHP Manual

$element->setValue()

(No version information available, might be only in CVS)

$element->setValue() — Utility function to set or store values from common tag types.

funcsynopsis funcprototype funcdef $element->setValue()/funcdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

new HTML_Template_Flexy_Element
$element->setOptions()
HTML_Template_Flexy


Utility function equivilant to HTML_Select - loadArray **

$element->setValue()
$element->removeAttributes()
HTML_Template_Flexy
PHP Manual

$element->setOptions()

(No version information available, might be only in CVS)

$element->setOptions() — Utility function equivilant to HTML_Select - loadArray **

funcsynopsis funcprototype funcdef $element->setOptions()/funcdef paramdefmixed $array /paramdef paramdefboolean $noValue = FALSE /paramdef /funcprototype /funcsynopsis

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.

$element->setValue()
$element->removeAttributes()
HTML_Template_Flexy


Removes an attributes

$element->setOptions()
$element->setAttributes()
HTML_Template_Flexy
PHP Manual

$element->removeAttributes()

(No version information available, might be only in CVS)

$element->removeAttributes() — Removes an attributes

funcsynopsis funcprototype funcdef $element->removeAttributes()/funcdef paramdefmixed $attrs /paramdef /funcprototype /funcsynopsis

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.

$element->setOptions()
$element->setAttributes()
HTML_Template_Flexy


Sets the HTML attributes

$element->removeAttributes()
$element->toHtml
HTML_Template_Flexy
PHP Manual

$element->setAttributes()

(No version information available, might be only in CVS)

$element->setAttributes() — Sets the HTML attributes

funcsynopsis funcsynopsisinfo require_once 'Flexy/Element.php'; /funcsynopsisinfo funcprototype funcdef HTML_Template_Flexy_Element::setAttributes()/funcdef paramdefmixed $attributes /paramdef /funcprototype /funcsynopsis

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.

$element->removeAttributes()
$element->toHtml
HTML_Template_Flexy


Output HTML and children

$element->setAttributes()
$element->toHtmlnoClose()
HTML_Template_Flexy
PHP Manual

$element->toHtml

(No version information available, might be only in CVS)

$element->toHtml — Output HTML and children

funcsynopsis funcprototype funcdefstring $element->toHtml()/funcdef paramdef /funcprototype /funcsynopsis

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.

$element->setAttributes()
$element->toHtmlnoClose()
HTML_Template_Flexy


Output Open Tag and any children and not Child tag (designed for use with

$element->toHtml
$factory->freeze()
HTML_Template_Flexy
PHP Manual

$element->toHtmlnoClose()

(No version information available, might be only in CVS)

$element->toHtmlnoClose() — Output Open Tag and any children and not Child tag (designed for use with <form + hidden elements>

funcsynopsis funcprototype funcdefstring $element->toHtmlnoClose()/funcdef paramdef /funcprototype /funcsynopsis

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.

$element->toHtml
$factory->freeze()
HTML_Template_Flexy


freeze - freeze's an element. - just copies the value to the override.

$element->toHtmlnoClose()
$factory->fromArray()
HTML_Template_Flexy
PHP Manual

$factory->freeze()

(No version information available, might be only in CVS)

$factory->freeze() — freeze - freeze's an element. - just copies the value to the override.

funcsynopsis funcsynopsisinfo require_once 'Flexy/Factory.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_Flexy_Factory::freeze()/funcdef paramdefarray $array /paramdef /funcprototype /funcsynopsis

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.

$element->toHtmlnoClose()
$factory->fromArray()
HTML_Template_Flexy


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->freeze()
$factory->fromArrayPrefixed()
HTML_Template_Flexy
PHP Manual

$factory->fromArray()

(No version information available, might be only in CVS)

$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.

funcsynopsis funcsynopsisinfo require_once 'Flexy/Factory.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_Flexy_Factory::fromArray()/funcdef paramdefarray $ar /paramdef paramdefoptional $ret = array() /paramdef /funcprototype /funcsynopsis

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.

$factory->freeze()
$factory->fromArrayPrefixed()
HTML_Template_Flexy


fromArrayPrefixed - takes a multi dimensional array, and builds the 'xxx[sss][xx]' => value

$factory->fromArray()
$factory->setErrors()
HTML_Template_Flexy
PHP Manual

$factory->fromArrayPrefixed()

(No version information available, might be only in CVS)

$factory->fromArrayPrefixed() — fromArrayPrefixed - takes a multi dimensional array, and builds the 'xxx[sss][xx]' => value

funcsynopsis funcsynopsisinfo require_once 'Flexy/Factory.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_Flexy_Factory::fromArrayPrefixed()/funcdef paramdefarray $prefix /paramdef paramdefarray $ar /paramdef paramdefoptional $ret = array() /paramdef /funcprototype /funcsynopsis

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.

$factory->fromArray()
$factory->setErrors()
HTML_Template_Flexy


setErrors - sets the suffix of an element to a value..

$factory->fromArrayPrefixed()
$factory->setRequired()
HTML_Template_Flexy
PHP Manual

$factory->setErrors()

(No version information available, might be only in CVS)

$factory->setErrors() — setErrors - sets the suffix of an element to a value..

funcsynopsis funcsynopsisinfo require_once 'Flexy/Factory.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_Flexy_Factory::setErrors()/funcdef paramdefarray $ret /paramdef paramdefarray $set /paramdef paramdefstring $format = '<span class="error">%s</span>' /paramdef /funcprototype /funcsynopsis

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.

$factory->fromArrayPrefixed()
$factory->setRequired()
HTML_Template_Flexy


setRequired - sets the prefix of an element to a value..

$factory->setErrors()
{variable}
HTML_Template_Flexy
PHP Manual

$factory->setRequired()

(No version information available, might be only in CVS)

$factory->setRequired() — setRequired - sets the prefix of an element to a value..

funcsynopsis funcprototype funcdefarray HTML_Template_Flexy_Factory::setRequired()/funcdef paramdefarray $ret /paramdef paramdefarray $set /paramdef paramdefstring $format = '>span class="required"<*>/span<' /paramdef /funcprototype /funcsynopsis

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.

$factory->setErrors()
{variable}
HTML_Template_Flexy


creates PHP code to echo a variable

$factory->setRequired()
{method(arguments,#quoted arguments#)}
HTML_Template_Flexy
PHP Manual

{variable}

(No version information available, might be only in CVS)

{variable} — creates PHP code to echo a variable

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef{variable} /paramdef paramdef{variable:h} /paramdef paramdef{variable:u} /paramdef /funcprototype /funcsynopsis

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.

Example

Example #1 setting an object variable

$this->a = "hello >>";
$template->outputObject($this);

Example #2 Outputting the variable

{a}
{a:h}
{a:u}

Example #3 Compiled template

<?php echo htmlspecialchars($t->a); ?>
<?php echo  $t->a; ?>
<?php echo urlencode($t->a); ?>

Example #4 Simple ouput example

hello &gt;&gt;
hello >>
hello+%3E%3
$factory->setRequired()
{method(arguments,#quoted arguments#)}
HTML_Template_Flexy


creates a PHP method call, and echos the results

{variable}
{foreach:variable,key,value}
HTML_Template_Flexy
PHP Manual

{method(arguments,#quoted arguments#)}

(No version information available, might be only in CVS)

{method(arguments,#quoted arguments#)} — creates a PHP method call, and echos the results

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef{method()} /paramdef paramdef{method():h} /paramdef paramdef{method():u} /paramdef paramdef{object.method()} /paramdef paramdef{method(with.a.variable)} /paramdef paramdef{method(with.multiple,variables)} /paramdef paramdef{method(with.variables,#and strings or literals#)} /paramdef /funcprototype /funcsynopsis

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

Example #1 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);
    }
}

Example #2 Calling includeBody in template, and ucfirst

{ucfirst(#this is the header#)}

{includeBody():h}

Footer Goes Here.

Example #3 Compiled template

<?php echo htmlspecialchars($t->ucfirst("this is the header")); ?>

<?php echo $t->includeBody(); ?>

Footer Goes Here.

Example #4 Output from the code

This is the header

Hello World

Footer Goes Here.
{variable}
{foreach:variable,key,value}
HTML_Template_Flexy


creates a PHP foreach loop

{method(arguments,#quoted arguments#)}
{if:variable}
HTML_Template_Flexy
PHP Manual

{foreach:variable,key,value}

(No version information available, might be only in CVS)

{foreach:variable,key,value} — creates a PHP foreach loop

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef{foreach:variable,key,value} /paramdef paramdef{foreach:variable,value} /paramdef /funcprototype /funcsynopsis

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

Example #1 Setting variables for foreach

$this->a = array(
  "dog" => "cat",
  "fire" => "water"
);
$this->b = array('a','b','c');

$template->outputObject($this);

Example #2 Foreach in template

{foreach:a,k,v}
  k is {k}, and v is {v}
{end:}
{foreach:b,v}
  v is {v}
{end:}

Example #3 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 #4 example output

k is dog, v is cat
k is fire, v is water
v is a
v is b
v is c
{method(arguments,#quoted arguments#)}
{if:variable}
HTML_Template_Flexy


creates a PHP if statement

{foreach:variable,key,value}
{end:}
HTML_Template_Flexy
PHP Manual

{if:variable}

(No version information available, might be only in CVS)

{if:variable} — creates a PHP if statement

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef{if:variable} /paramdef paramdef{if:method()} /paramdef /funcprototype /funcsynopsis

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

Example #1 Setting variables for if

class example {
    function showDog() {
        return true;
    }

    function output() {

        $this->showStuff = true;

        .........
        $template->outputObject($this);
    }
}

Example #2 The template

{if:showStuff}Hello{end:}
{if:showDog()}Doggy{end:}

Example #3 Compiled template

<?php if ($t->showStuff)  { ?>Hello<?php } ?>
<?php if ($t->showDog()) {  ?>Doggy<?php } ?>

Example #4 The output

Hello
Doggy
{foreach:variable,key,value}
{end:}
HTML_Template_Flexy


closes an if or foreach block

{if:variable}
{else:}
HTML_Template_Flexy
PHP Manual

{end:}

(No version information available, might be only in CVS)

{end:} — closes an if or foreach block

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef{end:} /paramdef /funcprototype /funcsynopsis

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

Example #1 Setting variables for if

class example {
    function showDog() {
        return true;
    }

    function output() {

        $this->showStuff = true;

        .........
        $template->outputObject($this);
    }
}

Example #2 The template

{if:showStuff}Hello{end:}
{if:showDog()}Doggy{end:}

Example #3 The compiled template

<?php if ($t->showStuff)  { ?>Hello<?php } ?>
<?php if ($t->showDog()) {  ?>Doggy<?php } ?>

Example #4 The output

Hello
Doggy
{if:variable}
{else:}
HTML_Template_Flexy


adds an PHP else in an if block

{end:}
HTML_Template_Flexy
PHP Manual

{else:}

(No version information available, might be only in CVS)

{else:} — adds an PHP else in an if block

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef{else:} /paramdef /funcprototype /funcsynopsis

Description

adds an else statement in PHP so that blocks of conditional HTML are shown correctly.

Example

Example #1 Setting variables for if

class example {

    function output() {

        $this->showStuff = false;

        .........
        $template->outputObject($this);
    }
}

Example #2 Else in template

{if:showStuff}Hello{else:}World{end:}

Example #3 Compiled template

<?php if ($t->showStuff)  { ?>Hello<?php } else { ?>World<<?php } ?>

Example #4 The output

World
{end:}
HTML_Template_Flexy


configures automatic form elements

{else:}
HTML_Template_Flexy
PHP Manual

<FORM NAME="name"

(No version information available, might be only in CVS)

<FORM NAME="name" — configures automatic form elements

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef<FORM NAME="name" >/paramdef /funcprototype /funcsynopsis

Description

By default, all forms are converted to HTML_Template_Flexy_Elements, so they can be altered at runtime.

Example

Example #1 Using an element to change a template.

$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

Example #2 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" xml:id="radio_yes" value="yes">yes<BR>
    <input name="test_radio" type="radio" xml:id="radio_no" value="no">no<BR>

  </FORM>
</BODY>

Example #3 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 value="1234" selected>another selection 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" xml:id="radio_yes" checked>yes<BR>
    <input name="test_radio" type="radio" value="no" xml:id="radio_no">no<BR>

  </FORM>
</BODY>
{else:}
HTML_Template_Flexy


creates a PHP if conditional tag

flexy:foreach="variable,key,value"
HTML_Template_Flexy


creates a PHP foreach loop using a html attribute

flexy:if="variable or method()"
flexy:start="here"
HTML_Template_Flexy
PHP Manual

flexy:foreach="variable,key,value"

(No version information available, might be only in CVS)

flexy:foreach="variable,key,value" — creates a PHP foreach loop using a html attribute

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef flexy:foreach="variable,key,value" /paramdef paramdef flexy:foreach="variable,value" /paramdef /funcprototype /funcsynopsis

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

Example #1 Setting variables for foreach

$this->a = array(
  "dog" => "cat",
  "fire" => "water"
);

$this->b = array('a','b','c');

$template->outputObject($this);

Example #2 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>

Example #3 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>

Example #4 Simple ouput example

k is dog, v is cat
k is fire, V is water

v is a
v is b
v is c
flexy:if="variable or method()"
flexy:start="here"
HTML_Template_Flexy


Start the output, using this tag and its children.

flexy:foreach="variable,key,value"
flexy:startchildren="here"
HTML_Template_Flexy
PHP Manual

flexy:start="here"

(No version information available, might be only in CVS)

flexy:start="here" — Start the output, using this tag and its children.

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef flexy:start="here" /paramdef /funcprototype /funcsynopsis

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

Example #1 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>

Example #2 Compiled template

   <FORM NAME="input">
      <INPUT NAME="hello">
    </FORM>
flexy:foreach="variable,key,value"
flexy:startchildren="here"
HTML_Template_Flexy


Start the output using its children.

flexy:start="here"
flexy:ignore="yes"
HTML_Template_Flexy
PHP Manual

flexy:startchildren="here"

(No version information available, might be only in CVS)

flexy:startchildren="here" — Start the output using its children.

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef flexy:startchildren="here" /paramdef /funcprototype /funcsynopsis

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

Example #1 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>

Example #2 Compiled template

    <H1>This is an example</H1>
    <FORM NAME="input">
      <INPUT NAME="hello">
    </FORM>
flexy:start="here"
flexy:ignore="yes"
HTML_Template_Flexy


Prevent Automatic form value replacement

flexy:startchildren="here"
flexy:nameuses="variable"
HTML_Template_Flexy
PHP Manual

flexy:ignore="yes"

(No version information available, might be only in CVS)

flexy:ignore="yes" — Prevent Automatic form value replacement

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef flexy:ignore="yes" /paramdef /funcprototype /funcsynopsis

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

Example #1 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>

Example #2 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>
flexy:startchildren="here"
flexy:nameuses="variable"
HTML_Template_Flexy


Use a variable in the name for a flexy form element

flexy:ignore="yes"
...
HTML_Template_Flexy
PHP Manual

flexy:nameuses="variable"

(No version information available, might be only in CVS)

flexy:nameuses="variable" — Use a variable in the name for a flexy form element

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef flexy:nameuses="variable" name="sometag[%s]" /paramdef /funcprototype /funcsynopsis

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

Example #1 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>

Example #2 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);

?>

Example #3 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>

Example #4 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>
flexy:ignore="yes"
...
HTML_Template_Flexy


Provides a simple way to pass data from PHP to Javascript

HTML_Template_Flexy
HTML_Template_IT
HTML_Template_Flexy
PHP Manual

<FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ...

(No version information available, might be only in CVS)

<FLEXY:TOJAVASCRIPT JSVAR="PHPVAR"> ... — Provides a simple way to pass data from PHP to Javascript

funcsynopsis funcprototype funcdef Usage() /funcdef paramdef<flexy:tojavascript JSVAR="PHPVAR" ... >/paramdef /funcprototype /funcsynopsis

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

Example #1 A template with javascript and flexy:tojavasscript

<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>

Example #2 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>

Example #3 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>
HTML_Template_Flexy
HTML_Template_IT
HTML_Template_Flexy


HTML_Template_IT

...
Introduction
HTML


Creating and Parsing templates

HTML_Template_IT
HTML_Template_IT::HTML_Template_IT()
HTML_Template_IT
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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

Example #2 The template

<html>
 <table border>
<!-- BEGIN row -->
  <tr>
<!-- BEGIN cell -->
   <td>
    {DATA}
   </td>
<!-- END cell -->
  </tr>
<!-- END row -->
 </table>
</html>

Example #3 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();

?>

Example #4 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>
HTML_Template_IT
HTML_Template_IT::HTML_Template_IT()
HTML_Template_IT


constructor

Introduction
HTML_Template_IT::get()
HTML_Template_IT
PHP Manual

HTML_Template_IT::HTML_Template_IT()

(No version information available, might be only in CVS)

HTML_Template_IT::HTML_Template_IT() — constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_IT::HTML_Template_IT()/funcdef paramdefstring $root = '.' /paramdef /funcprototype /funcsynopsis

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()

Introduction
HTML_Template_IT::get()
HTML_Template_IT


get a block including replacments

HTML_Template_IT::HTML_Template_IT()
HTML_Template_IT::getGlobalvariables()
HTML_Template_IT
PHP Manual

HTML_Template_IT::get()

(No version information available, might be only in CVS)

HTML_Template_IT::get() — get a block including replacments

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Template_IT::get()/funcdef paramdefstring $block = "__global__" /paramdef /funcprototype /funcsynopsis

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()

HTML_Template_IT::HTML_Template_IT()
HTML_Template_IT::getGlobalvariables()
HTML_Template_IT


returns an array of all global variables from the variable cache

HTML_Template_IT::get()
HTML_Template_IT::loadTemplatefile()
HTML_Template_IT
PHP Manual

HTML_Template_IT::getGlobalvariables()

(No version information available, might be only in CVS)

HTML_Template_IT::getGlobalvariables() — returns an array of all global variables from the variable cache

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_IT::getGlobalvariables()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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());

?>

Example #2 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(),

HTML_Template_IT::get()
HTML_Template_IT::loadTemplatefile()
HTML_Template_IT


load a template file

HTML_Template_IT::getGlobalvariables()
HTML_Template_IT::parse()
HTML_Template_IT
PHP Manual

HTML_Template_IT::loadTemplatefile()

(No version information available, might be only in CVS)

HTML_Template_IT::loadTemplatefile() — load a template file

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_Template_IT::loadTemplatefile() /funcdef paramdefstring $filename /paramdef paramdefboolean $removeUnknownVariables = TRUE /paramdef paramdefboolean $removeEmptyBlocks = TRUE /paramdef /funcprototype /funcsynopsis

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()

HTML_Template_IT::getGlobalvariables()
HTML_Template_IT::parse()
HTML_Template_IT


parse a block

HTML_Template_IT::loadTemplatefile()
HTML_Template_IT::parseCurrentBlock()
HTML_Template_IT
PHP Manual

HTML_Template_IT::parse()

(No version information available, might be only in CVS)

HTML_Template_IT::parse() — parse a block

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_IT::parse()/funcdef paramdefstring $block = "__global__" /paramdef paramdefboolean $flag_recursion = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 The template cvsnames.tpl.htm

<html>
 <table>
<!-- BEGIN row -->
  <tr>
   <td>
    {CVS_USERNAME}
   </td>
   <td>
    {REALNAME}
   </td>
  </tr>
<!-- END row -->
 </table>
</html>

Example #2 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()

HTML_Template_IT::loadTemplatefile()
HTML_Template_IT::parseCurrentBlock()
HTML_Template_IT


parse the current block

HTML_Template_IT::parse()
HTML_Template_IT::setCurrentBlock()
HTML_Template_IT
PHP Manual

HTML_Template_IT::parseCurrentBlock()

(No version information available, might be only in CVS)

HTML_Template_IT::parseCurrentBlock() — parse the current block

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_IT::parseCurrentBlock()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 The template cvsnames.tpl.htm

<html>
 <table>
<!-- BEGIN row -->
  <tr>
   <td>
    {CVS_USERNAME}
   </td>
   <td>
    {REALNAME}
   </td>
  </tr>
<!-- END row -->
 </table>
</html>

Example #2 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()

HTML_Template_IT::parse()
HTML_Template_IT::setCurrentBlock()
HTML_Template_IT


set the current block

HTML_Template_IT::parseCurrentBlock()
HTML_Template_IT::setRoot()
HTML_Template_IT
PHP Manual

HTML_Template_IT::setCurrentBlock()

(No version information available, might be only in CVS)

HTML_Template_IT::setCurrentBlock() — set the current block

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_Template_IT::setCurrentBlock()/funcdef paramdefstring $block = "__global__" /paramdef /funcprototype /funcsynopsis

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(),

HTML_Template_IT::parseCurrentBlock()
HTML_Template_IT::setRoot()
HTML_Template_IT


set the template root directory

HTML_Template_IT::setCurrentBlock()
HTML_Template_IT::setOption()
HTML_Template_IT
PHP Manual

HTML_Template_IT::setRoot()

(No version information available, might be only in CVS)

HTML_Template_IT::setRoot() — set the template root directory

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_IT::setRoot()/funcdef paramdef string $root /paramdef /funcprototype /funcsynopsis

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

Example #1 Directorytree.

./
./testscript.php
./templates/design01/main.tpl.htm
./templates/design01/table.tpl.htm
./templates/design02/main.tpl.htm
./templates/design02/table.tpl.htm

Example #2 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()

HTML_Template_IT::setCurrentBlock()
HTML_Template_IT::setOption()
HTML_Template_IT


sets an option

HTML_Template_IT::setRoot()
HTML_Template_IT::setTemplate()
HTML_Template_IT
PHP Manual

HTML_Template_IT::setOption()

(No version information available, might be only in CVS)

HTML_Template_IT::setOption() — sets an option

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefint HTML_Template_IT::setOption()/funcdef paramdefstring $option /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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

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()

HTML_Template_IT::setRoot()
HTML_Template_IT::setTemplate()
HTML_Template_IT


set a template

HTML_Template_IT::setOption()
HTML_Template_IT::setVariable()
HTML_Template_IT
PHP Manual

HTML_Template_IT::setTemplate()

(No version information available, might be only in CVS)

HTML_Template_IT::setTemplate() — set a template

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_Template_IT::setTemplate()/funcdef paramdefstring $template /paramdef paramdefboolean $removeUnkownVariables = TRUE /paramdef paramdefboolean $removeEmptyBlocks = TRUE /paramdef /funcprototype /funcsynopsis

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

Example #1 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::setTemplatefile()

HTML_Template_IT::setOption()
HTML_Template_IT::setVariable()
HTML_Template_IT


set a variable

HTML_Template_IT::setTemplate()
HTML_Template_IT::show()
HTML_Template_IT
PHP Manual

HTML_Template_IT::setVariable()

(No version information available, might be only in CVS)

HTML_Template_IT::setVariable() — set a variable

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_IT::setVariable()/funcdef paramdefmixed $placeholder /paramdef paramdefmixed $variable = "" /paramdef /funcprototype /funcsynopsis

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

Example #1 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>

Example #2 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()

HTML_Template_IT::setTemplate()
HTML_Template_IT::show()
HTML_Template_IT


print a block including replacments

HTML_Template_IT::setVariable()
HTML_Template_IT::touchBlock()
HTML_Template_IT
PHP Manual

HTML_Template_IT::show()

(No version information available, might be only in CVS)

HTML_Template_IT::show() — print a block including replacments

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_IT::show()/funcdef paramdef string $block /paramdef /funcprototype /funcsynopsis

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()

HTML_Template_IT::setVariable()
HTML_Template_IT::touchBlock()
HTML_Template_IT


preserve empty block

HTML_Template_IT
HTML_Template_PHPLIB
HTML_Template_IT
PHP Manual

HTML_Template_IT::touchBlock()

(No version information available, might be only in CVS)

HTML_Template_IT::touchBlock() — preserve empty block

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/IT.php'; /funcsynopsisinfo funcprototype funcdefboolean HTML_Template_IT::touchBlock()/funcdef paramdefstring $block /paramdef /funcprototype /funcsynopsis

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

Example #1 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>

Example #2 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.

HTML_Template_IT
HTML_Template_PHPLIB
HTML_Template_IT


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.

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>

Simple example

Example #1 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>

Example #2 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'));
?>

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.

Example #3 Loading a template file

$t =& new HTML_Template_PHPLIB(dirname(__FILE__), 'keep');
$t->setFile('authors', 'authors.tpl');

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.

Example #4 Defining a block

$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.

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).

Example #5 Setting a variable

$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.

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.

Example #6 Parsing a block

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.

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.

Example #7 Finishing a file and writing it out

$t->parse('OUT', 'authors');
$htmlcode = $t->finish(
    $tpl->get('OUT')
);
echo $htmlcode;

Example #8 Finishing a file and writing it out, the easy way

echo $tpl->finish($t->parse('OUT', 'authors'));
HTML_Template_IT::touchBlock()
HTML_Template_Sigma
HTML


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

HTML_Template_PHPLIB
Introduction - template syntax
HTML


Creating and editing templates

HTML_Template_Sigma
Introduction - cache
HTML_Template_Sigma
PHP Manual

Introduction - template syntax

(No version information available, might be only in CVS)

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, 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:

  • Although this functionality is implemented using addBlockfile(), unlike addBlockfile() no new blocks are created in the template.

  • <!-- INCLUDE --> calls 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.

Example #1 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()
  • 'u' for » urlencode()
  • '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.

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.

Example #2 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>

Example #3 The table_header.html template file

    <tr>
        <th>First name</th>
        <th>Last name</th>
    </tr>

Example #4 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();
?>

Example #5 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>
HTML_Template_Sigma
Introduction - cache
HTML_Template_Sigma


How Sigma caches the "prepared" templates

Introduction - template syntax
constructor HTML_Template_Sigma()
HTML_Template_Sigma
PHP Manual

Introduction - cache

(No version information available, might be only in CVS)

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.

Introduction - template syntax
constructor HTML_Template_Sigma()
HTML_Template_Sigma


constructor

Introduction - cache
addBlock()
HTML_Template_Sigma
PHP Manual

constructor HTML_Template_Sigma()

(No version information available, might be only in CVS)

constructor HTML_Template_Sigma() — constructor

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::HTML_Template_Sigma()/funcdef paramdefstring $root = '' /paramdef paramdefstring $cacheRoot = '' /paramdef /funcprototype /funcsynopsis

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.

Introduction - cache
addBlock()
HTML_Template_Sigma


Adds a block to the template

constructor HTML_Template_Sigma()
addBlockfile()
HTML_Template_Sigma
PHP Manual

addBlock()

(No version information available, might be only in CVS)

addBlock() — Adds a block to the template

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::addBlock()/funcdef paramdefstring $placeholder /paramdef paramdefstring $block /paramdef paramdefstring $template /paramdef /funcprototype /funcsynopsis

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.

constructor HTML_Template_Sigma()
addBlockfile()
HTML_Template_Sigma


Adds a block contained in the file to the template

addBlock()
blockExists()
HTML_Template_Sigma
PHP Manual

addBlockfile()

(No version information available, might be only in CVS)

addBlockfile() — Adds a block contained in the file to the template

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::addBlockfile()/funcdef paramdefstring $placeholder /paramdef paramdefstring $block /paramdef paramdefstring $filename /paramdef /funcprototype /funcsynopsis

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.

addBlock()
blockExists()
HTML_Template_Sigma


Checks if the block exists in the template

addBlockfile()
clearVariables()
HTML_Template_Sigma
PHP Manual

blockExists()

(No version information available, might be only in CVS)

blockExists() — Checks if the block exists in the template

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefbool HTML_Template_Sigma::blockExists()/funcdef paramdefstring $block /paramdef /funcprototype /funcsynopsis

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.

addBlockfile()
clearVariables()
HTML_Template_Sigma


Clears the variables

blockExists()
errorMessage()
HTML_Template_Sigma
PHP Manual

clearVariables()

(No version information available, might be only in CVS)

clearVariables() — Clears the variables

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::clearVariables()/funcdef ( void /funcprototype /funcsynopsis

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.

blockExists()
errorMessage()
HTML_Template_Sigma


Returns a textual error message for an error code

clearVariables()
get()
HTML_Template_Sigma
PHP Manual

errorMessage()

(No version information available, might be only in CVS)

errorMessage() — Returns a textual error message for an error code

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Template_Sigma::errorMessage()/funcdef paramdefinteger $code /paramdef paramdefstring $data = NULL /paramdef /funcprototype /funcsynopsis

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.

clearVariables()
get()
HTML_Template_Sigma


Returns a block with all replacements done.

errorMessage()
getBlockList()
HTML_Template_Sigma
PHP Manual

get()

(No version information available, might be only in CVS)

get() — Returns a block with all replacements done.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Template_Sigma::get()/funcdef paramdefstring $block = '__global__' /paramdef paramdefbool $clear = FALSE /paramdef /funcprototype /funcsynopsis

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.

errorMessage()
getBlockList()
HTML_Template_Sigma


Returns a list of blocks within a template.

get()
getCurrentBlock()
HTML_Template_Sigma
PHP Manual

getBlockList()

(No version information available, might be only in CVS)

getBlockList() — Returns a list of blocks within a template.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_Sigma::getBlockList()/funcdef paramdefstring $parent = '__global__' /paramdef paramdefbool $recursive = FALSE /paramdef /funcprototype /funcsynopsis

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.

get()
getCurrentBlock()
HTML_Template_Sigma


Returns the current block name

getBlockList()
getPlaceholderList()
HTML_Template_Sigma
PHP Manual

getCurrentBlock()

(No version information available, might be only in CVS)

getCurrentBlock() — Returns the current block name

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Template_Sigma::getCurrentBlock()/funcdef ( void /funcprototype /funcsynopsis

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.

getBlockList()
getPlaceholderList()
HTML_Template_Sigma


Returns a list of placeholders within a block.

getCurrentBlock()
hideBlock()
HTML_Template_Sigma
PHP Manual

getPlaceholderList()

(No version information available, might be only in CVS)

getPlaceholderList() — Returns a list of placeholders within a block.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefarray HTML_Template_Sigma::getPlaceholderList()/funcdef paramdefstring $block = '__global__' /paramdef /funcprototype /funcsynopsis

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.

getCurrentBlock()
hideBlock()
HTML_Template_Sigma


Hides the block even if it is not "empty".

getPlaceholderList()
loadTemplateFile()
HTML_Template_Sigma
PHP Manual

hideBlock()

(No version information available, might be only in CVS)

hideBlock() — Hides the block even if it is not "empty".

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::hideBlock()/funcdef paramdefstring $block /paramdef /funcprototype /funcsynopsis

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.

getPlaceholderList()
loadTemplateFile()
HTML_Template_Sigma


Loads a template file.

hideBlock()
parse()
HTML_Template_Sigma
PHP Manual

loadTemplateFile()

(No version information available, might be only in CVS)

loadTemplateFile() — Loads a template file.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::loadTemplateFile()/funcdef paramdefstring $filename /paramdef paramdefboolean $removeUnknownVariables = TRUE /paramdef paramdefboolean $removeEmptyBlocks = TRUE /paramdef /funcprototype /funcsynopsis

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.

hideBlock()
parse()
HTML_Template_Sigma


Parses the given block.

loadTemplateFile()
parseCurrentBlock()
HTML_Template_Sigma
PHP Manual

parse()

(No version information available, might be only in CVS)

parse() — Parses the given block.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::parse()/funcdef paramdefstring $block = '__global__' /paramdef paramdefboolean $flagRecursion = FALSE /paramdef paramdefboolean $fakeParse = FALSE /paramdef /funcprototype /funcsynopsis

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.

loadTemplateFile()
parseCurrentBlock()
HTML_Template_Sigma


Parses the current block

parse()
placeholderExists()
HTML_Template_Sigma
PHP Manual

parseCurrentBlock()

(No version information available, might be only in CVS)

parseCurrentBlock() — Parses the current block

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::parseCurrentBlock()/funcdef ( void /funcprototype /funcsynopsis

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.

parse()
placeholderExists()
HTML_Template_Sigma


Checks whether the placeholder exists

parseCurrentBlock()
replaceBlock()
HTML_Template_Sigma
PHP Manual

placeholderExists()

(No version information available, might be only in CVS)

placeholderExists() — Checks whether the placeholder exists

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefstring HTML_Template_Sigma::placeholderExists()/funcdef paramdefstring $placeholder /paramdef paramdefstring $block = '' /paramdef /funcprototype /funcsynopsis

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.

parseCurrentBlock()
replaceBlock()
HTML_Template_Sigma


Replaces an existing block with new content.

placeholderExists()
replaceBlockfile()
HTML_Template_Sigma
PHP Manual

replaceBlock()

(No version information available, might be only in CVS)

replaceBlock() — Replaces an existing block with new content.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::replaceBlock()/funcdef paramdefstring $block /paramdef paramdefstring $template /paramdef paramdefboolean $keepContent = FALSE /paramdef /funcprototype /funcsynopsis

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.

placeholderExists()
replaceBlockfile()
HTML_Template_Sigma


Replaces an existing block with new content from a file.

replaceBlock()
setCacheRoot()
HTML_Template_Sigma
PHP Manual

replaceBlockfile()

(No version information available, might be only in CVS)

replaceBlockfile() — Replaces an existing block with new content from a file.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::replaceBlockfile()/funcdef paramdefstring $block /paramdef paramdefstring $filename /paramdef paramdefboolean $keepContent = FALSE /paramdef /funcprototype /funcsynopsis

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.

replaceBlock()
setCacheRoot()
HTML_Template_Sigma


Sets the directory to cache "prepared" templates in.

replaceBlockfile()
setCallbackFunction()
HTML_Template_Sigma
PHP Manual

setCacheRoot()

(No version information available, might be only in CVS)

setCacheRoot() — Sets the directory to cache "prepared" templates in.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::setCacheRoot()/funcdef paramdefstring $root /paramdef /funcprototype /funcsynopsis

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.

replaceBlockfile()
setCallbackFunction()
HTML_Template_Sigma


Sets a callback function.

setCacheRoot()
setCurrentBlock()
HTML_Template_Sigma
PHP Manual

setCallbackFunction()

(No version information available, might be only in CVS)

setCallbackFunction() — Sets a callback function.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::setCallbackFunction()/funcdef paramdefstring $tplFunction /paramdef paramdefmixed $callback /paramdef paramdefbool $preserveArgs = FALSE /paramdef /funcprototype /funcsynopsis

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.

setCacheRoot()
setCurrentBlock()
HTML_Template_Sigma


Sets the name of the current block.

setCallbackFunction()
setGlobalVariable()
HTML_Template_Sigma
PHP Manual

setCurrentBlock()

(No version information available, might be only in CVS)

setCurrentBlock() — Sets the name of the current block.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::setCurrentBlock()/funcdef paramdefstring $block = '__global__' /paramdef /funcprototype /funcsynopsis

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.

setCallbackFunction()
setGlobalVariable()
HTML_Template_Sigma


Sets a global variable value.

setCurrentBlock()
setOption()
HTML_Template_Sigma
PHP Manual

setGlobalVariable()

(No version information available, might be only in CVS)

setGlobalVariable() — Sets a global variable value.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::setGlobalVariable()/funcdef paramdefmixed $variable /paramdef paramdefstring $value = '' /paramdef /funcprototype /funcsynopsis

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.

setCurrentBlock()
setOption()
HTML_Template_Sigma


Sets the option for the template class

setGlobalVariable()
setRoot()
HTML_Template_Sigma
PHP Manual

setOption()

(PECL axis2:0.1.0-0.1.1)

setOption() — Sets the option for the template class

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::setOption()/funcdef paramdefstring $option /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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

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.

setGlobalVariable()
setRoot()
HTML_Template_Sigma


Sets the file root for templates.

setOption()
setTemplate()
HTML_Template_Sigma
PHP Manual

setRoot()

(No version information available, might be only in CVS)

setRoot() — Sets the file root for templates.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::setRoot()/funcdef paramdefstring $root /paramdef /funcprototype /funcsynopsis

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.

setOption()
setTemplate()
HTML_Template_Sigma


Sets the template.

setRoot()
setVariable()
HTML_Template_Sigma
PHP Manual

setTemplate()

(No version information available, might be only in CVS)

setTemplate() — Sets the template.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::setTemplate()/funcdef paramdefstring $template /paramdef paramdefboolean $removeUnknownVariables = TRUE /paramdef paramdefboolean $removeEmptyBlocks = TRUE /paramdef /funcprototype /funcsynopsis

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.

setRoot()
setVariable()
HTML_Template_Sigma


Sets a variable value.

setTemplate()
show()
HTML_Template_Sigma
PHP Manual

setVariable()

(No version information available, might be only in CVS)

setVariable() — Sets a variable value.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::setVariable()/funcdef paramdefmixed $variable /paramdef paramdefstring $value = '' /paramdef /funcprototype /funcsynopsis

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.

setTemplate()
show()
HTML_Template_Sigma


Prints a block with all replacements done.

setVariable()
touchBlock()
HTML_Template_Sigma
PHP Manual

show()

(No version information available, might be only in CVS)

show() — Prints a block with all replacements done.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefvoid HTML_Template_Sigma::show()/funcdef paramdefstring $block = '__global__' /paramdef /funcprototype /funcsynopsis

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.

setVariable()
touchBlock()
HTML_Template_Sigma


Preserves the block even if empty blocks should be removed.

HTML_Template_Sigma
HTML_Template_Xipe
HTML_Template_Sigma
PHP Manual

touchBlock()

(No version information available, might be only in CVS)

touchBlock() — Preserves the block even if empty blocks should be removed.

funcsynopsis funcsynopsisinfo require_once 'HTML/Template/Sigma.php'; /funcsynopsisinfo funcprototype funcdefmixed HTML_Template_Sigma::touchBlock()/funcdef paramdefstring $block /paramdef /funcprototype /funcsynopsis

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.

HTML_Template_Sigma
HTML_Template_Xipe
HTML_Template_Sigma


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

touchBlock()
Introduction
HTML


A simple, fast and powerful template engine.

HTML_Template_Xipe
HTML_TreeMenu
HTML_Template_Xipe
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

HTML_Template_Xipe
HTML_TreeMenu
HTML_Template_Xipe


HTML_TreeMenu

This manual page shows the basic steps to get HTML_TreeMenu working.

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.

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();

?>

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 :)

Example #1 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 #2 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();

?>
Introduction
Pager
HTML


Pager

Data paging class which also builds links to the pages.

HTML_TreeMenu
Introduction
HTML


Usage of Pager 2.x

Pager
Pager "Jumping" vs. "Sliding"
Pager
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

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 xmlns:xlink="http://www.w3.org/1999/xlink" 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"

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:

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:

$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):

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:

//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.

Pager
Pager "Jumping" vs. "Sliding"
Pager


Feature comparison of the two pager styles

Introduction
Pager::factory
Pager
PHP Manual

Pager "Jumping" vs. "Sliding"

(No version information available, might be only in CVS)

"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:

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):

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.

Introduction
Pager::factory
Pager


Creates a pager instance

Pager "Jumping" vs. "Sliding"
Pager::setOptions
Pager
PHP Manual

Pager::factory()

(No version information available, might be only in CVS)

— Creates a pager instance

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefobject &factory()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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

Pager "Jumping" vs. "Sliding"
Pager::setOptions
Pager


Set or change option after the Pager object has been constructed

Pager::factory
Pager::build
Pager
PHP Manual

Pager::setOptions()

(No version information available, might be only in CVS)

— Set or change option after the Pager object has been constructed

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::setOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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

Pager::factory
Pager::build
Pager


Generate or refresh the links and paged data after a call to setOptions

Pager::setOptions
Pager::getCurrentPageID
Pager
PHP Manual

Pager::build()

(No version information available, might be only in CVS)

— Generate or refresh the links and paged data after a call to setOptions()

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::build()/funcdef paramdef /funcprototype /funcsynopsis

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.

Pager::setOptions
Pager::getCurrentPageID
Pager


Returns current page number

Pager::build
Pager::getLinks
Pager
PHP Manual

Pager::getCurrentPageID()

(No version information available, might be only in CVS)

— Returns current page number

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefinteger getCurrentPageID()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

integer - Current page number.

Pager::build
Pager::getLinks
Pager


Returns back/next/first/last and page links, both as ordered and associative array.

Pager::getCurrentPageID
Pager::getNextPageID
Pager
PHP Manual

Pager::getLinks()

(No version information available, might be only in CVS)

— Returns back/next/first/last and page links, both as ordered and associative array.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getLinks()/funcdef paramdefinteger $pageID = NULL /paramdef /funcprototype /funcsynopsis

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.

Pager::getCurrentPageID
Pager::getNextPageID
Pager


Returns next page number.

Pager::getLinks
Pager::getOffsetByPageId
Pager
PHP Manual

Pager::getNextPageID()

(No version information available, might be only in CVS)

— Returns next page number.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefmixed Pager::getNextPageID()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

If current page is last page this function returns FALSE, otherwise returns next page number.

Return value

return Next page number or FALSE

Pager::getLinks
Pager::getOffsetByPageId
Pager


Returns offsets for given pageID.

Pager::getNextPageID
Pager::getPageData
Pager
PHP Manual

Pager::getOffsetByPageId()

(No version information available, might be only in CVS)

— Returns offsets for given pageID.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getOffsetByPageId()/funcdef paramdefinteger $pageid = NULL /paramdef /funcprototype /funcsynopsis

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

Pager::getNextPageID
Pager::getPageData
Pager


Returns an array of current pages data

Pager::getOffsetByPageId
Pager::getPageIdByOffset
Pager
PHP Manual

Pager::getPageData()

(No version information available, might be only in CVS)

— Returns an array of current pages data

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getPageData()/funcdef paramdefinteger $pageID = NULL /paramdef /funcprototype /funcsynopsis

Parameter

  • integer $pageID - Desired page ID (optional)

Return value

return array of data for this page.

Pager::getOffsetByPageId
Pager::getPageIdByOffset
Pager


Returns the page number for the given offset

Pager::getPageData
Pager::getPageRangeByPageId
Pager
PHP Manual

Pager::getPageIdByOffset()

(No version information available, might be only in CVS)

— Returns the page number for the given offset

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getPageIdByOffset()/funcdef paramdefinteger $index /paramdef /funcprototype /funcsynopsis

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

Pager::getPageData
Pager::getPageRangeByPageId
Pager


Returns offsets for given pageID.

Pager::getPageIdByOffset
Pager::getPageSelectBox
Pager
PHP Manual

Pager::getPageRangeByPageId()

(No version information available, might be only in CVS)

— Returns offsets for given pageID.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getPageRangeByPageId()/funcdef paramdefinteger $pageid = NULL /paramdef /funcprototype /funcsynopsis

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

Pager::getPageIdByOffset
Pager::getPageSelectBox
Pager


Returns a string with a XHTML SELECT menu, to choose the page to display.

Pager::getPageRangeByPageId
Pager::getPreviousPageID
Pager
PHP Manual

Pager::getPageSelectBox()

(No version information available, might be only in CVS)

— Returns a string with a XHTML SELECT menu, to choose the page to display.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getPageSelectBox()/funcdef paramdefarray $params /paramdef paramdefstring $extraAttributes = '' /paramdef /funcprototype /funcsynopsis

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.

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.

Pager::getPageRangeByPageId
Pager::getPreviousPageID
Pager


Returns previous page number.

Pager::getPageSelectBox
Pager::getPerPageSelectBox
Pager
PHP Manual

Pager::getPreviousPageID()

(No version information available, might be only in CVS)

— Returns previous page number.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefmixed Pager::getPreviousPageID()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

If current page is first page this function returns FALSE, otherwise returns previous page number.

Return value

return Previous page number or FALSE.

Pager::getPageSelectBox
Pager::getPerPageSelectBox
Pager


Returns a string with a XHTML SELECT menu, to choose how many items per page should be displayed.

Pager::getPreviousPageID
Pager::isFirstPage
Pager
PHP Manual

Pager::getPerPageSelectBox()

(No version information available, might be only in CVS)

— Returns a string with a XHTML SELECT menu, to choose how many items per page should be displayed.

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefarray Pager::getPerPageSelectBox()/funcdef paramdefinteger $start = 5 /paramdef paramdefinteger $end = 30 /paramdef paramdefinteger $step = 5 /paramdef paramdefboolean $showAllData = false /paramdef paramdefstring $optionText = '%d' /paramdef /funcprototype /funcsynopsis

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.

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.

Pager::getPreviousPageID
Pager::isFirstPage
Pager


Returns whether current page is first page

Pager::getPerPageSelectBox
Pager::isLastPage
Pager
PHP Manual

Pager::isFirstPage()

(No version information available, might be only in CVS)

— Returns whether current page is first page

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefbool Pager::isFirstPage()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return TRUE or FALSE, wrt it is the first page or not.

Pager::getPerPageSelectBox
Pager::isLastPage
Pager


Returns whether current page is last page

Pager::isFirstPage
Pager::isLastPageComplete
Pager
PHP Manual

Pager::isLastPage()

(No version information available, might be only in CVS)

— Returns whether current page is last page

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefbool Pager::isLastPage()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return TRUE or FALSE, wrt it is the last page or not.

Pager::isFirstPage
Pager::isLastPageComplete
Pager


Returns whether last page is complete

Pager::isLastPage
Pager::numItems
Pager
PHP Manual

Pager::isLastPageComplete()

(No version information available, might be only in CVS)

— Returns whether last page is complete

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefbool Pager::isLastPageComplete()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

Pager::isLastPage
Pager::numItems
Pager


Returns number of items

Pager::isLastPageComplete
Pager::numPages
Pager
PHP Manual

Pager::numItems()

(No version information available, might be only in CVS)

— Returns number of items

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefint Pager_Sliding::numItems() /funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return integer - Number of items

Pager::isLastPageComplete
Pager::numPages
Pager


Returns number of pages

Pager::numItems
Pager::Pager
Pager
PHP Manual

Pager::numPages()

(No version information available, might be only in CVS)

— Returns number of pages

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefint Pager_Sliding::numPages() /funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return integer - Number of pages

Pager::numItems
Pager::Pager
Pager


Creates a pager instance

Pager
Pager_Sliding
Pager
PHP Manual

Pager::Pager()

(No version information available, might be only in CVS)

— Creates a pager instance

funcsynopsis funcsynopsisinfo require_once 'Pager.php'; /funcsynopsisinfo funcprototype funcdefobject &Pager()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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

Pager
Pager_Sliding
Pager


Pager_Sliding

Data paging class which also builds links to the pages.

HTML
Introduction
HTML


Usage of Pager_Sliding

Pager_Sliding
Pager (v.1.x) vs. Pager_Sliding
Pager_Sliding
PHP Manual

Introduction

(No version information available, might be only in CVS)

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:

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"

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:

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();

Pager_Sliding
Pager (v.1.x) vs. Pager_Sliding
Pager_Sliding


Feature comparison of the two classes

Introduction
Pager_Sliding::getCurrentPageID
Pager_Sliding
PHP Manual

Pager (v.1.x) vs. Pager_Sliding

(No version information available, might be only in CVS)

(v.1.x) vs. — 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:

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):

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!

Introduction
Pager_Sliding::getCurrentPageID
Pager_Sliding


Returns current page number

Pager (v.1.x) vs. Pager_Sliding
Pager_Sliding::getLinks
Pager_Sliding
PHP Manual

Pager_Sliding::getCurrentPageID()

(No version information available, might be only in CVS)

— Returns current page number

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefinteger getCurrentPageID()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

integer - Current page number.

Pager (v.1.x) vs. Pager_Sliding
Pager_Sliding::getLinks
Pager_Sliding


Returns back/next/first/last and page links, both as ordered and associative array.

Pager_Sliding::getCurrentPageID
Pager_Sliding::getNextPageID
Pager_Sliding
PHP Manual

Pager_Sliding::getLinks()

(No version information available, might be only in CVS)

— Returns back/next/first/last and page links, both as ordered and associative array.

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefarray Pager_Sliding::getLinks()/funcdef paramdefinteger $pageID = NULL /paramdef /funcprototype /funcsynopsis

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.

Pager_Sliding::getCurrentPageID
Pager_Sliding::getNextPageID
Pager_Sliding


Returns next page number.

Pager_Sliding::getLinks
Pager_Sliding::getOffsetByPageId
Pager_Sliding
PHP Manual

Pager_Sliding::getNextPageID()

(No version information available, might be only in CVS)

— Returns next page number.

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefmixed Pager_Sliding::getNextPageID()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

If current page is last page this function returns FALSE, otherwise returns next page number.

Return value

return Next page number or FALSE

Pager_Sliding::getLinks
Pager_Sliding::getOffsetByPageId
Pager_Sliding


Returns offsets for given pageID.

Pager_Sliding::getNextPageID
Pager_Sliding::getPageData
Pager_Sliding
PHP Manual

Pager_Sliding::getOffsetByPageId()

(No version information available, might be only in CVS)

— Returns offsets for given pageID.

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefarray Pager_Sliding::getOffsetByPageId()/funcdef paramdefinteger $pageid = NULL /paramdef /funcprototype /funcsynopsis

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

Pager_Sliding::getNextPageID
Pager_Sliding::getPageData
Pager_Sliding


Returns an array of current pages data

Pager_Sliding::getOffsetByPageId
Pager_Sliding::getPageIdByOffset
Pager_Sliding
PHP Manual

Pager_Sliding::getPageData()

(No version information available, might be only in CVS)

— Returns an array of current pages data

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefarray Pager_Sliding::getPageData()/funcdef paramdefinteger $pageID = NULL /paramdef /funcprototype /funcsynopsis

Parameter

  • integer $pageID - Desired page ID (optional)

Return value

return array of data for this page.

Pager_Sliding::getOffsetByPageId
Pager_Sliding::getPageIdByOffset
Pager_Sliding


Overload PEAR::Pager method. VOID.

Pager_Sliding::getPageData
Pager_Sliding::getPreviousPageID
Pager_Sliding
PHP Manual

Pager_Sliding::getPageIdByOffset()

(No version information available, might be only in CVS)

— Overload PEAR::Pager method. VOID.

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefarray Pager_Sliding::getPageIdByOffset()/funcdef paramdefinteger $index /paramdef /funcprototype /funcsynopsis

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.

Pager_Sliding::getPageData
Pager_Sliding::getPreviousPageID
Pager_Sliding


Returns previous page number.

Pager_Sliding::getPageIdByOffset
Pager_Sliding::isFirstPage
Pager_Sliding
PHP Manual

Pager_Sliding::getPreviousPageID()

(No version information available, might be only in CVS)

— Returns previous page number.

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefmixed Pager_Sliding::getPreviousPageID()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

If current page is first page this function returns FALSE, otherwise returns previous page number.

Return value

return Previous page number or FALSE.

Pager_Sliding::getPageIdByOffset
Pager_Sliding::isFirstPage
Pager_Sliding


Returns whether current page is first page

Pager_Sliding::getPreviousPageID
Pager_Sliding::isLastPage
Pager_Sliding
PHP Manual

Pager_Sliding::isFirstPage()

(No version information available, might be only in CVS)

— Returns whether current page is first page

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefbool Pager_Sliding::isFirstPage()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return TRUE or FALSE, wrt it is the first page or not.

Pager_Sliding::getPreviousPageID
Pager_Sliding::isLastPage
Pager_Sliding


Returns whether current page is last page

Pager_Sliding::isFirstPage
Pager_Sliding::isLastPageComplete
Pager_Sliding
PHP Manual

Pager_Sliding::isLastPage()

(No version information available, might be only in CVS)

— Returns whether current page is last page

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefbool Pager_Sliding::isLastPage()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return TRUE or FALSE, wrt it is the last page or not.

Pager_Sliding::isFirstPage
Pager_Sliding::isLastPageComplete
Pager_Sliding


Returns whether last page is complete

Pager_Sliding::isLastPage
Pager_Sliding::numItems
Pager_Sliding
PHP Manual

Pager_Sliding::isLastPageComplete()

(No version information available, might be only in CVS)

— Returns whether last page is complete

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefbool Pager_Sliding::isLastPageComplete()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

Pager_Sliding::isLastPage
Pager_Sliding::numItems
Pager_Sliding


Returns number of items

Pager_Sliding::isLastPageComplete
Pager_Sliding::numPages
Pager_Sliding
PHP Manual

Pager_Sliding::numItems()

(No version information available, might be only in CVS)

— Returns number of items

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefint Pager_Sliding::numItems()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return integer - Number of items

Pager_Sliding::isLastPageComplete
Pager_Sliding::numPages
Pager_Sliding


Returns number of pages

Pager_Sliding::numItems
Pager_Sliding::Sliding
Pager_Sliding
PHP Manual

Pager_Sliding::numPages()

(No version information available, might be only in CVS)

— Returns number of pages

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefint Pager_Sliding::numPages()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Return value

return integer - Number of pages

Pager_Sliding::numItems
Pager_Sliding::Sliding
Pager_Sliding


Creates a pager instance

Pager_Sliding
HTTP
Pager_Sliding
PHP Manual

Pager_Sliding::Sliding()

(No version information available, might be only in CVS)

— Creates a pager instance

funcsynopsis funcsynopsisinfo require_once 'Pager/Sliding.php'; /funcsynopsisinfo funcprototype funcdefobject &Sliding()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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

Pager_Sliding
HTTP
Pager_Sliding


HTTP
Packages
PHP Manual

HTTP

Table of Contents

  • HTTP
  • HTTP_Client
  • HTTP_Download
  • HTTP_Request
  • HTTP_Session
  • HTTP_Session2
  • HTTP_Upload

Provides Packages for working with the Hyper-Text-Transfer-Protocol.

Pager_Sliding::Sliding
HTTP
Packages


HTTP
HTTP::Date
HTTP
PHP Manual

HTTP

Provides a set of usefull, static functions related to the Hyper-Text-Transfer-Protocol.

HTTP
HTTP::Date
HTTP
PHP Manual


format a date

HTTP
HTTP::head
HTTP
PHP Manual

HTTP::Date

(PECL pecl_http:0.1.0-1.5.5)

HTTP::Date — format a date

funcsynopsis funcsynopsisinfo require_once 'HTTP.php'; /funcsynopsisinfo funcprototype funcdefstring HTTP::date()/funcdef paramdefinteger time /paramdef /funcprototype /funcsynopsis

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.

HTTP
HTTP::head
HTTP


sends a "HEAD" command

HTTP::Date
HTTP::negotiateLanguage
HTTP
PHP Manual

HTTP::head

(PECL pecl_http:0.1.0-1.5.5)

HTTP::head — sends a "HEAD" command

funcsynopsis funcsynopsisinfo require_once 'HTTP.php'; /funcsynopsisinfo funcprototype funcdefarray HTTP::head()/funcdef paramdefstring $url /paramdef /funcprototype /funcsynopsis

Description

Sends a "HEAD" HTTP command to a server and returns the headers in an associative array.

Example

Example #1 HEAD request to example.com

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:

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.

HTTP::Date
HTTP::negotiateLanguage
HTTP


Negotiate language with the user's browser

HTTP::head
HTTP::redirect
HTTP
PHP Manual

HTTP::negotiateLanguage

(No version information available, might be only in CVS)

HTTP::negotiateLanguage — Negotiate language with the user's browser

funcsynopsis funcsynopsisinfo require_once 'HTTP.php'; /funcsynopsisinfo funcprototype funcdefstring HTTP::negotiateLanguage()/funcdef paramdefarray $supported /paramdef paramdefstring $default = 'en_US' /paramdef /funcprototype /funcsynopsis

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

Example #1 Usage example

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.

HTTP::head
HTTP::redirect
HTTP


redirects the client

HTTP
HTTP_Client
HTTP
PHP Manual

HTTP::redirect

(PECL pecl_http:0.1.0-1.5.5)

HTTP::redirect — redirects the client

funcsynopsis funcsynopsisinfo require_once 'HTTP.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP::redirect()/funcdef paramdefstring url /paramdef /funcprototype /funcsynopsis

Description

This function redirects the client. This is done by issuing a Location: header and exiting.

Example

Example #1 Redirecting to another site

require_once 'HTTP.php';

HTTP::redirect("http://example.com/");

Example #2 Local redirect

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.

HTTP
HTTP_Client
HTTP


HTTP_Client

HTTP::redirect
Class Summary HTTP_Client
HTTP


A simple HTTP client class.

HTTP_Client
constructor HTTP_Client::HTTP_Client()
HTTP_Client
PHP Manual

Class Summary HTTP_Client

(No version information available, might be only in CVS)

Class Summary — 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

HTTP_Client
constructor HTTP_Client::HTTP_Client()
HTTP_Client
PHP Manual


Constructor

Class Summary HTTP_Client
HTTP_Client::attach()
HTTP_Client
PHP Manual

constructor HTTP_Client::HTTP_Client()

(No version information available, might be only in CVS)

constructor HTTP_Client::HTTP_Client() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTTP_Client::HTTP_Client()/funcdef paramdefarray $defaultRequestParams = NULL /paramdef paramdefarray $defaultHeaders = NULL /paramdef /funcprototype /funcsynopsis

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.

Class Summary HTTP_Client
HTTP_Client::attach()
HTTP_Client


Adds a Listener to the list of listeners that are notified of the object's events

constructor HTTP_Client::HTTP_Client()
HTTP_Client::currentResponse()
HTTP_Client
PHP Manual

HTTP_Client::attach()

(No version information available, might be only in CVS)

HTTP_Client::attach() — Adds a Listener to the list of listeners that are notified of the object's events

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefboolean HTTP_Client::attach()/funcdef paramdefobject HTTP_Request_Listener &$listener /paramdef paramdefboolean $propagate = FALSE /paramdef /funcprototype /funcsynopsis

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.

constructor HTTP_Client::HTTP_Client()
HTTP_Client::currentResponse()
HTTP_Client


Returns the most recent HTTP response

HTTP_Client::attach()
HTTP_Client::detach()
HTTP_Client
PHP Manual

HTTP_Client::currentResponse()

(No version information available, might be only in CVS)

HTTP_Client::currentResponse() — Returns the most recent HTTP response

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefarray& HTTP_Client::currentResponse()/funcdef paramdef /funcprototype /funcsynopsis

Description

The returned array has the following keys: 'code', 'headers', 'body'.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTTP_Client::attach()
HTTP_Client::detach()
HTTP_Client


Removes a Listener from the list of listeners

HTTP_Client::currentResponse()
HTTP_Client::get()
HTTP_Client
PHP Manual

HTTP_Client::detach()

(No version information available, might be only in CVS)

HTTP_Client::detach() — Removes a Listener from the list of listeners

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefboolean HTTP_Client::detach()/funcdef paramdefobject HTTP_Request_Listener &$listener /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::currentResponse()
HTTP_Client::get()
HTTP_Client


Sends a 'GET' HTTP request

HTTP_Client::detach()
HTTP_Client::head()
HTTP_Client
PHP Manual

HTTP_Client::get()

(No version information available, might be only in CVS)

HTTP_Client::get() — Sends a 'GET' HTTP request

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefinteger HTTP_Client::get()/funcdef paramdefstring $url /paramdef paramdefmixed $data = NULL /paramdef paramdefboolean $preEncoded = FALSE /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::detach()
HTTP_Client::head()
HTTP_Client


Sends a 'HEAD' HTTP request

HTTP_Client::get()
HTTP_Client::post()
HTTP_Client
PHP Manual

HTTP_Client::head()

(No version information available, might be only in CVS)

HTTP_Client::head() — Sends a 'HEAD' HTTP request

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefinteger HTTP_Client::head()/funcdef paramdefstring $url /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::get()
HTTP_Client::post()
HTTP_Client


Sends a 'POST' HTTP request

HTTP_Client::head()
HTTP_Client::reset()
HTTP_Client
PHP Manual

HTTP_Client::post()

(No version information available, might be only in CVS)

HTTP_Client::post() — Sends a 'POST' HTTP request

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefinteger HTTP_Client::post()/funcdef paramdefstring $url /paramdef paramdefmixed $data /paramdef paramdefboolean $preEncoded = FALSE /paramdef paramdefarray $files = array() /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::head()
HTTP_Client::reset()
HTTP_Client


Clears object's internal properties

HTTP_Client::post()
HTTP_Client::setDefaultHeader()
HTTP_Client
PHP Manual

HTTP_Client::reset()

(No version information available, might be only in CVS)

HTTP_Client::reset() — Clears object's internal properties

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client::reset()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTTP_Client::post()
HTTP_Client::setDefaultHeader()
HTTP_Client


Sets default header(s) for HTTP requests

HTTP_Client::reset()
HTTP_Client::setMaxRedirects()
HTTP_Client
PHP Manual

HTTP_Client::setDefaultHeader()

(No version information available, might be only in CVS)

HTTP_Client::setDefaultHeader() — Sets default header(s) for HTTP requests

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client::setDefaultHeader()/funcdef paramdefmixed $name /paramdef paramdefstring $value = NULL /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::reset()
HTTP_Client::setMaxRedirects()
HTTP_Client


Sets the maximum number of redirects that will be processed.

HTTP_Client::setDefaultHeader()
HTTP_Client::setRequestParameter()
HTTP_Client
PHP Manual

HTTP_Client::setMaxRedirects()

(No version information available, might be only in CVS)

HTTP_Client::setMaxRedirects() — Sets the maximum number of redirects that will be processed.

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client::setMaxRedirects()/funcdef paramdefint $value /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::setDefaultHeader()
HTTP_Client::setRequestParameter()
HTTP_Client


Sets parameter(s) for HTTP requests

HTTP_Client::setMaxRedirects()
Class Summary HTTP_Client_CookieManager
HTTP_Client
PHP Manual

HTTP_Client::setRequestParameter()

(No version information available, might be only in CVS)

HTTP_Client::setRequestParameter() — Sets parameter(s) for HTTP requests

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client::setRequestParameter()/funcdef paramdefmixed $name /paramdef paramdefstring $value = NULL /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client::setMaxRedirects()
Class Summary HTTP_Client_CookieManager
HTTP_Client


Stores cookies and passes them between HTTP requests.

HTTP_Client::setRequestParameter()
constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()
HTTP_Client
PHP Manual

Class Summary HTTP_Client_CookieManager

(No version information available, might be only in CVS)

Class Summary — 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

HTTP_Client::setRequestParameter()
constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()
HTTP_Client


Constructor

Class Summary HTTP_Client_CookieManager
HTTP_Client_CookieManager::addCookie()
HTTP_Client
PHP Manual

constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()

(No version information available, might be only in CVS)

constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager() — Constructor

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client/CookieManager.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Class Summary HTTP_Client_CookieManager
HTTP_Client_CookieManager::addCookie()
HTTP_Client


Explicitly adds cookie to the list

constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()
HTTP_Client_CookieManager::passCookies()
HTTP_Client
PHP Manual

HTTP_Client_CookieManager::addCookie()

(No version information available, might be only in CVS)

HTTP_Client_CookieManager::addCookie() — Explicitly adds cookie to the list

funcsynopsis funcsynopsisinfo require_once 'ClientCookieManager.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client_CookieManager::addCookie()/funcdef paramdefarray $cookie /paramdef /funcprototype /funcsynopsis

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.

constructor HTTP_Client_CookieManager::HTTP_Client_CookieManager()
HTTP_Client_CookieManager::passCookies()
HTTP_Client


Adds cookies to the request

HTTP_Client_CookieManager::addCookie()
HTTP_Client_CookieManager::reset()
HTTP_Client
PHP Manual

HTTP_Client_CookieManager::passCookies()

(No version information available, might be only in CVS)

HTTP_Client_CookieManager::passCookies() — Adds cookies to the request

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client/CookieManager.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client_CookieManager::passCookies()/funcdef paramdefobject An &$request /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client_CookieManager::addCookie()
HTTP_Client_CookieManager::reset()
HTTP_Client


Clears the cookies list

HTTP_Client_CookieManager::passCookies()
HTTP_Client_CookieManager::updateCookies()
HTTP_Client
PHP Manual

HTTP_Client_CookieManager::reset()

(No version information available, might be only in CVS)

HTTP_Client_CookieManager::reset() — Clears the cookies list

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client/CookieManager.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client_CookieManager::reset()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

HTTP_Client_CookieManager::passCookies()
HTTP_Client_CookieManager::updateCookies()
HTTP_Client


Updates cookie list from HTTP server response

HTTP_Client
HTTP_Download
HTTP_Client
PHP Manual

HTTP_Client_CookieManager::updateCookies()

(No version information available, might be only in CVS)

HTTP_Client_CookieManager::updateCookies() — Updates cookie list from HTTP server response

funcsynopsis funcsynopsisinfo require_once 'HTTP/Client/CookieManager.php'; /funcsynopsisinfo funcprototype funcdefvoid HTTP_Client_CookieManager::updateCookies()/funcdef paramdefobject HTTP_Request &$request /paramdef /funcprototype /funcsynopsis

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.

HTTP_Client
HTTP_Download
HTTP_Client


HTTP_Download

Send HTTP Downloads

HTTP_Client_CookieManager::updateCookies()
Intro
HTTP


Introduction in usage of HTTP_Download

HTTP_Download
HTTP_Download::HTTP_Download
HTTP_Download
PHP Manual

Intro

(No version information available, might be only in CVS)

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:

Example #1 Static send:

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);

Example #2 Send a hidden file:

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();

Example #3 Send arbitrary data:

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();

Example #4 Limiting bandwidth:

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();

Example #5 Sending a PostgreSQL LOB:

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();
HTTP_Download
HTTP_Download::HTTP_Download
HTTP_Download


Constructor

Intro
HTTP_Download::setParams
HTTP_Download
PHP Manual

HTTP_Download::HTTP_Download()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinfo require_once 'HTTP/Download.php'; /funcsynopsisinfo funcprototype funcdef object new HTTP_Download() /funcdef paramdef array $params = array() /paramdef /funcprototype /funcsynopsis

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().

Intro
HTTP_Download::setParams
HTTP_Download


Set various parameters

HTTP_Download::HTTP_Download
HTTP_Download::setFile
HTTP_Download
PHP Manual

HTTP_Download::setParams()

(No version information available, might be only in CVS)

— Set various parameters

funcsynopsis funcprototype funcdef mixed HTTP_Download::setParams() /funcdef paramdef array $params /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::HTTP_Download
HTTP_Download::setFile
HTTP_Download


Set file path

HTTP_Download::setParams
HTTP_Download::setData
HTTP_Download
PHP Manual

HTTP_Download::setFile()

(No version information available, might be only in CVS)

— Set file path

funcsynopsis funcprototype funcdef mixed HTTP_Download::setFile() /funcdef paramdef string $file /paramdef paramdef bool $send_404 = true /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setParams
HTTP_Download::setData
HTTP_Download


Set raw data

HTTP_Download::setFile
HTTP_Download::setResource
HTTP_Download
PHP Manual

HTTP_Download::setData()

(No version information available, might be only in CVS)

— Set raw data

funcsynopsis funcprototype funcdef void HTTP_Download::setData() /funcdef paramdef mixed $data = null /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setFile
HTTP_Download::setResource
HTTP_Download


Set resource for download

HTTP_Download::setData
HTTP_Download::setGzip
HTTP_Download
PHP Manual

HTTP_Download::setResource()

(No version information available, might be only in CVS)

— Set resource for download

funcsynopsis funcprototype funcdef mixed HTTP_Download::setResource() /funcdef paramdef mixed $handle = null /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setData
HTTP_Download::setGzip
HTTP_Download


Whether to gzip the download on the fly or not. (requires ext/zlib)

HTTP_Download::setResource
HTTP_Download::setCache
HTTP_Download
PHP Manual

HTTP_Download::setGzip()

(No version information available, might be only in CVS)

— Whether to gzip the download on the fly or not. (requires ext/zlib)

funcsynopsis funcprototype funcdef mixed HTTP_Download::setGzip() /funcdef paramdef bool $gzip = false /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setResource
HTTP_Download::setCache
HTTP_Download


Whether to allow caching of the download on the clients side.

HTTP_Download::setGzip
HTTP_Download::setCacheControl
HTTP_Download
PHP Manual

HTTP_Download::setCache()

(No version information available, might be only in CVS)

— Whether to allow caching of the download on the clients side.

funcsynopsis funcprototype funcdef void HTTP_Download::setCache() /funcdef paramdef bool $cache = true /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setGzip
HTTP_Download::setCacheControl
HTTP_Download


Control cache privacy and validity.

HTTP_Download::setCache
HTTP_Download::setBufferSize
HTTP_Download
PHP Manual

HTTP_Download::setCacheControl()

(No version information available, might be only in CVS)

— Control cache privacy and validity.

funcsynopsis funcprototype funcdef void HTTP_Download::setCacheControl() /funcdef paramdef string $cache = "public" /paramdef paramdef int $maxage = 0 /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setCache
HTTP_Download::setBufferSize
HTTP_Download


Set size of buffer in bytes.

HTTP_Download::setCacheControl
HTTP_Download::setThrottleDelay
HTTP_Download
PHP Manual

HTTP_Download::setBufferSize()

(No version information available, might be only in CVS)

— Set size of buffer in bytes.

funcsynopsis funcprototype funcdef mixed HTTP_Download::setBufferSize() /funcdef paramdef int $size = 2097152 /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setCacheControl
HTTP_Download::setThrottleDelay
HTTP_Download


Set throttle delay in seconds

HTTP_Download::setBufferSize
HTTP_Download::setContentType
HTTP_Download
PHP Manual

HTTP_Download::setThrottleDelay()

(No version information available, might be only in CVS)

— Set throttle delay in seconds

funcsynopsis funcprototype funcdef void HTTP_Download::setThrottleDelay() /funcdef paramdef float $seconds = 0 /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setBufferSize
HTTP_Download::setContentType
HTTP_Download


Set content type

HTTP_Download::setThrottleDelay
HTTP_Download::setLastModified
HTTP_Download
PHP Manual

HTTP_Download::setContentType()

(No version information available, might be only in CVS)

— Set content type

funcsynopsis funcprototype funcdef mixed HTTP_Download::setContentType() /funcdef paramdef string $content_type = 'application/x-octetstream' /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setThrottleDelay
HTTP_Download::setLastModified
HTTP_Download


Set "Last-Modified"

HTTP_Download::setContentType
HTTP_Download::setContentDisposition
HTTP_Download
PHP Manual

HTTP_Download::setLastModified()

(No version information available, might be only in CVS)

— Set "Last-Modified"

funcsynopsis funcprototype funcdef void HTTP_Download::setLastModified() /funcdef paramdef int $last_modified /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setContentType
HTTP_Download::setContentDisposition
HTTP_Download


Set content disposition

HTTP_Download::setLastModified
HTTP_Download::guessContentType
HTTP_Download
PHP Manual

HTTP_Download::setContentDisposition()

(No version information available, might be only in CVS)

— Set content disposition

funcsynopsis funcprototype funcdef void HTTP_Download::setContentDisposition() /funcdef paramdef string $disposition = HTTP_DOWNLOAD_ATTACHMENT /paramdef paramdef string $file_name = null /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setLastModified
HTTP_Download::guessContentType
HTTP_Download


Guess content type of file

HTTP_Download::setContentDisposition
HTTP_Download::send
HTTP_Download
PHP Manual

HTTP_Download::guessContentType()

(No version information available, might be only in CVS)

— Guess content type of file

funcsynopsis funcprototype funcdef mixed HTTP_Download::guessContentType() /funcdef paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::setContentDisposition
HTTP_Download::send
HTTP_Download


Send file

HTTP_Download::guessContentType
HTTP_Download::staticSend
HTTP_Download
PHP Manual

HTTP_Download::send()

(No version information available, might be only in CVS)

— Send file

funcsynopsis funcprototype funcdef mixed HTTP_Download::send() /funcdef paramdef bool $autoSetContentDisposition = true /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::guessContentType
HTTP_Download::staticSend
HTTP_Download


Static send

HTTP_Download::send
HTTP_Download::sendArchive
HTTP_Download
PHP Manual

HTTP_Download::staticSend()

(No version information available, might be only in CVS)

— Static send

funcsynopsis funcprototype funcdef mixed HTTP_Download::staticSend() /funcdef paramdef array $params /paramdef paramdef bool $guess = false /paramdef /funcprototype /funcsynopsis

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.

HTTP_Download::send
HTTP_Download::sendArchive
HTTP_Download


Send an archive created on the fly

HTTP_Download
HTTP_Request
HTTP_Download
PHP Manual

HTTP_Download::sendArchive()

(No version information available, might be only in CVS)

— Send an archive created on the fly

funcsynopsis funcprototype funcdef mixed HTTP_Download::sendArchive() /funcdef paramdef string $name /paramdef paramdef mixed $files /paramdef paramdef string $type = HTTP_DOWNLOAD_TGZ /paramdef paramdef string $add_path = '' /paramdef paramdef string $strip_path = '' /paramdef /funcprototype /funcsynopsis

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 = HTTP_DOWNLOAD_TGZ - 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.

HTTP_Download
HTTP_Request
HTTP_Download


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.

HTTP_Download::sendArchive
Introduction
HTTP


Introduction to HTTP_Request

HTTP_Request
Basic Authentication
HTTP_Request
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Fetches » yahoo.com and displays it

require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://www.yahoo.com/");
if (!PEAR::isError($req->sendRequest())) {
    echo $req->getResponseBody();
}

Example #2 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.

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;
HTTP_Request
Basic Authentication
HTTP_Request


Authentication for protected websites

Introduction
Cookies
HTTP_Request
PHP Manual

Basic Authentication

(No version information available, might be only in CVS)

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

Example #1 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.

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();
}
Introduction
Cookies
HTTP_Request


Making use of Cookies within HTTP_Request.

Basic Authentication
File uploads
HTTP_Request
PHP Manual

Cookies

(No version information available, might be only in CVS)

Cookies — Making use of Cookies within HTTP_Request.

How to add Cookie to a HTTP request

Example #1 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.

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();
}

Example #2 Reading cookies from a HTTP response

Reading cookies that come with a HTTP response is shown in this following example.

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());
}
Basic Authentication
File uploads
HTTP_Request


Uploading files via HTTP

Cookies
Request headers
HTTP_Request
PHP Manual

File uploads

(No version information available, might be only in CVS)

File uploads — Uploading files via HTTP

How to use file uploads

Example #1 Upload a PDF document

In this example a file named /home/johndoe/text.pdf is uploaded to the remote machine upload.example.com under the name johndoe-text.pdf. Additionally Basic Authentication is used to ensure that John is allowed to upload something.

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("johndoe-txt.pdf", "/home/johndoe/text.pdf");
if (PEAR::isError($result)) {
    echo $result->getMessage();
} else {

    $response = $req->sendRequest();

    if (PEAR::isError($response)) {
        echo $response->getMessage();
    } else {
        echo $req->getResponseBody();
    }
}
Cookies
Request headers
HTTP_Request


Adding additional headers to the HTTP request.

File uploads
Proxy Authorization
HTTP_Request
PHP Manual

Request headers

(No version information available, might be only in CVS)

Request headers — Adding additional headers to the HTTP request.

How to add request headers

Example #1 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.

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.

File uploads
Proxy Authorization
HTTP_Request


Making use of a HTTP proxy

Request headers
Response Evaluation
HTTP_Request
PHP Manual

Proxy Authorization

(No version information available, might be only in CVS)

Proxy Authorization — Making use of a HTTP proxy

How to use Proxy Authorization

Example #1 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.

require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->setProxy("proxy.example.com", 8080);

Example #2 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.

require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://example.com/");
$req->setProxy("proxy.example.com", 8080, "johndoe", "foo");
Request headers
Response Evaluation
HTTP_Request


Evaluating the information from a HTTP response

Proxy Authorization
HTTP_Request_Listener
HTTP_Request
PHP Manual

Response Evaluation

(No version information available, might be only in CVS)

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.

Example #1 Checking the response code

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.

Example #2 Getting all headers from the response

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.

Example #3 Getting a specific header

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.

Proxy Authorization
HTTP_Request_Listener
HTTP_Request


attaching listeners to HTTP_Request operations

HTTP_Request
HTTP_Session
HTTP_Request
PHP Manual

HTTP_Request_Listener

(No version information available, might be only in CVS)

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.

Example #1 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;

            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)

HTTP_Request
HTTP_Session
HTTP_Request


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.

HTTP_Request_Listener
Introduction
HTTP


Introduction to HTTP_Session

HTTP_Session
Database container
HTTP_Session
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Setting some options and detection of a new session

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();

Example #2 Setting timeouts

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();
HTTP_Session
Database container
HTTP_Session


Store session data in a database with HTTP_Session

HTTP_Session
HTTP_Session2
HTTP_Session
PHP Manual

Database container

(No version information available, might be only in CVS)

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

Example #1 Using MDB2 to store session data in a database

/* 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();
HTTP_Session
HTTP_Session2
HTTP_Session


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.

Database container
Introduction
HTTP


An introduction to HTTP_Session2

HTTP_Session2
Using a database container
HTTP_Session2
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Setting options and detecting a new session

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

Example #2 Setting timeouts

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.

HTTP_Session2
Using a database container
HTTP_Session2


How to store session data in a database with HTTP_Session2

Introduction
Making a session persistent
HTTP_Session2
PHP Manual

Using a database container

(No version information available, might be only in CVS)

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

Example #1 Using MDB2 to store session data in a database

/* 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();
Introduction
Making a session persistent
HTTP_Session2


This example illustrates how to make a session persist over multiple browser sessions using a so called "session cookie".

HTTP_Session2
HTTP_Upload
HTTP_Session2
PHP Manual

Making a session persistent

(No version information available, might be only in CVS)

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

Example #1 Use of session_set_cookie_params

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(time() + 60*60*24); // set expire in 24 hours
HTTP_Session2::setIdle(time() + 60*60);      // set idle to 1 hour

if (HTTP_Session2::isExpired()) {
    HTTP_Session2::destroy();
}

if (HTTP_Session2::isIdle()) {
    HTTP_Session2::destroy();
}

HTTP_Session2::updateIdle();
HTTP_Session2
HTTP_Upload
HTTP_Session2


HTTP_Upload

Easy and secure managment of files submitted via HTML forms.

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

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:

Example #1 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>

Example #2 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.

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/";
    } else {
        echo $moved->getMessage();
    }
} elseif ($file->isMissing()) {
    echo "No file was provided.";
} elseif ($file->isError()) {
    echo $file->errorMsg();
}

Example #3 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>

Example #4 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.

$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());
}

Extensive information about uploaded files

HTTP_Upload provides extensive information about uploaded files via the getProp() method: funcsynopsis funcprototype funcdef mixed HTTP_Upload_File::getProp() /funcdef paramdef [name] /paramdef /funcprototype /funcsynopsis

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.

Example #5 Extensive information via getProp()

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"));
}

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 #6 Example

// 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 />";
    }
}
HTTP
Images
HTTP


Images

Table of Contents

  • Image_Barcode
  • Image_Canvas
  • Image_Graph
  • Image_Text
  • Image_Transform

Provides Packages for working with images

HTTP_Upload
Image_Barcode
Packages


Image_Barcode

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

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.

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.

Images
Image_Canvas
Images


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.

Image_Barcode
Example
Images


Usage example for Image_Canvas

Image_Canvas
Image_Graph
Image_Canvas
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Usage example for Image_Canvas

Example

Example #1 Generation of a sample image in PNG format

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();
Image_Canvas
Image_Graph
Image_Canvas


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.

Example
Image_Text
Images


Image_Text

Image_Graph
Class Summary Image_Text
Images


Image_Text
constructor Image_Text::Image_Text
Image_Text
PHP Manual

Class Summary Image_Text

(No version information available, might be only in CVS)

Class Summary — 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

Image_Text
constructor Image_Text::Image_Text
Image_Text


Constructor

Class Summary Image_Text
Image_Text::autoMeasurize
Image_Text
PHP Manual

constructor Image_Text::Image_Text()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Image_Text::Image_Text()/funcdef paramdefstring $text /paramdef paramdefarray $options = NULL /paramdef /funcprototype /funcsynopsis

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.

Class Summary Image_Text
Image_Text::autoMeasurize
Image_Text


Auto measurize text

constructor Image_Text::Image_Text
Image_Text::display
Image_Text
PHP Manual

Image_Text::autoMeasurize()

(No version information available, might be only in CVS)

— Auto measurize text

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefint Image_Text::autoMeasurize()/funcdef paramdefint $start = FALSE /paramdef paramdefint $end = FALSE /paramdef /funcprototype /funcsynopsis

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.

constructor Image_Text::Image_Text
Image_Text::display
Image_Text


Display the image (send it to the browser).

Image_Text::autoMeasurize
Image_Text::getImg
Image_Text
PHP Manual

Image_Text::display()

(No version information available, might be only in CVS)

— Display the image (send it to the browser).

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefbool Image_Text::display()/funcdef paramdefbool $save = FALSE /paramdef paramdefbool $free = FALSE /paramdef /funcprototype /funcsynopsis

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.

Image_Text::autoMeasurize
Image_Text::getImg
Image_Text


Return the image ressource.

Image_Text::display
Image_Text::init
Image_Text
PHP Manual

Image_Text::getImg()

(No version information available, might be only in CVS)

— Return the image ressource.

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefresource& Image_Text::getImg()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get the image canvas.

Return value

returns Used image resource

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Image_Text::display
Image_Text::init
Image_Text


Initialiaze the Image_Text object.

Image_Text::getImg
Image_Text::measurize
Image_Text
PHP Manual

Image_Text::init()

(No version information available, might be only in CVS)

— Initialiaze the Image_Text object.

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefbool Image_Text::init()/funcdef paramdef /funcprototype /funcsynopsis

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.

Image_Text::getImg
Image_Text::measurize
Image_Text


Measurize text into the text box

Image_Text::init
Image_Text::render
Image_Text
PHP Manual

Image_Text::measurize()

(No version information available, might be only in CVS)

— Measurize text into the text box

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefarray Image_Text::measurize()/funcdef paramdefbool $force = FALSE /paramdef /funcprototype /funcsynopsis

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.

Image_Text::init
Image_Text::render
Image_Text


Render the text in the canvas using the given options.

Image_Text::measurize
Image_Text::save
Image_Text
PHP Manual

Image_Text::render()

(No version information available, might be only in CVS)

— Render the text in the canvas using the given options.

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdef bool Image_Text::render() /funcdef paramdef bool $force = FALSE /paramdef /funcprototype /funcsynopsis

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.

Image_Text::measurize
Image_Text::save
Image_Text


Save image canvas.

Image_Text::render
Image_Text::set
Image_Text
PHP Manual

Image_Text::save()

(No version information available, might be only in CVS)

— Save image canvas.

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefbool Image_Text::save()/funcdef paramdefstring $destFile = FALSE /paramdef /funcprototype /funcsynopsis

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.

Image_Text::render
Image_Text::set
Image_Text


Set options

Image_Text::save
Image_Text::setColor
Image_Text
PHP Manual

Image_Text::set()

(No version information available, might be only in CVS)

— Set options

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefbool Image_Text::set()/funcdef paramdefmixed $option /paramdef paramdefmixed $value = NULL /paramdef /funcprototype /funcsynopsis

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.

Image_Text::save
Image_Text::setColor
Image_Text


Set a color

Image_Text::set
Image_Text::setColors
Image_Text
PHP Manual

Image_Text::setColor()

(No version information available, might be only in CVS)

— Set a color

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefbool Image_Text::setColor()/funcdef paramdefmixed $color /paramdef paramdefmixed $id = 0 /paramdef /funcprototype /funcsynopsis

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.

Image_Text::set
Image_Text::setColors
Image_Text


Set the color-set

Image_Text::setColor
Package Image_Text Constants
Image_Text
PHP Manual

Image_Text::setColors()

(No version information available, might be only in CVS)

— Set the color-set

funcsynopsis funcsynopsisinfo require_once 'ImageText.php'; /funcsynopsisinfo funcprototype funcdefbool Image_Text::setColors()/funcdef paramdefmixed $colors /paramdef /funcprototype /funcsynopsis

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.

Image_Text::setColor
Package Image_Text Constants
Image_Text


Constants defined in and used by Image_Text

Image_Text
Image_Transform
Image_Text
PHP Manual

Package Image_Text Constants

(No version information available, might be only in CVS)

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

Image_Text
Image_Transform
Image_Text


Image_Transform

Image_Transform main use case is to create thumbnails of images.

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().

Warning

You may not execute several scaling functions in a row without saving in between.

Example #1 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).

Example #2 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());
}
?>

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.

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.

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().

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
Images
Internationalization
Images


Internationalization

Table of Contents

  • I18Nv2
  • Translation2

Provides packages for internationalization and localization.

Image_Transform
I18Nv2
Packages


I18Nv2

Internationalization
Class Summary I18Nv2
Internationalization


I18Nv2
Intro
I18Nv2
PHP Manual

Class Summary I18Nv2

(No version information available, might be only in CVS)

Class Summary — 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.

Warning

This documentation is outdated and needs an overhaul.

I18Nv2
Intro
I18Nv2


Introduction to I18Nv2

Class Summary I18Nv2
Examples
I18Nv2
PHP Manual

Intro

(No version information available, might be only in CVS)

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.

Class Summary I18Nv2
Examples
I18Nv2


Usage example for I18Nv2

Intro
I18Nv2 Constants
I18Nv2
PHP Manual

Examples

(No version information available, might be only in CVS)

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.

Example #1 I18Nv2::setLocale()

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.

Example #2 I18Nv2::getInfo()

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().

Example #3 I18Nv2::autoConv()

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.

Example #4 I18Nv2_Locale

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.

Example #5 I18Nv2_Negotiator

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.

Example #6 I18Nv2_Language

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.

Example #7 I18Nv2_Country

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.

Example #8 I18Nv2_DecoratedList

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();

Example #9 I18Nv2_CommonList::toDecoratedList()

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();
Intro
I18Nv2 Constants
I18Nv2


Constants defined in and used by I18Nv2

Examples
I18Nv2::setLocale
I18Nv2
PHP Manual

I18Nv2 Constants

(No version information available, might be only in CVS)

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

Examples
I18Nv2::setLocale
I18Nv2


Set locale

I18Nv2 Constants
I18Nv2::lastLocale
I18Nv2
PHP Manual

I18Nv2::setLocale()

(No version information available, might be only in CVS)

— Set locale

funcsynopsis funcsynopsisinforequire_once 'I18Nv2.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2::setLocale()/funcdef paramdefstring $locale /paramdef paramdefint $cat = LC_ALL /paramdef /funcprototype /funcsynopsis

Description

Set environment to the specified locale.

Example #1 Set a locale:

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().

I18Nv2 Constants
I18Nv2::lastLocale
I18Nv2


Get current/prior locale

I18Nv2::setLocale
I18Nv2::getInfo
I18Nv2
PHP Manual

I18Nv2::lastLocale()

(No version information available, might be only in CVS)

— Get current/prior locale

funcsynopsis funcsynopsisinforequire_once 'I18Nv2.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2::lastLocale()/funcdef paramdefint $prior = 0 /paramdef paramdefbool $full = FALSE /paramdef /funcprototype /funcsynopsis

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().

I18Nv2::setLocale
I18Nv2::getInfo
I18Nv2


Get several locale specific information

I18Nv2::lastLocale
I18Nv2::autoConv
I18Nv2
PHP Manual

I18Nv2::getInfo()

(No version information available, might be only in CVS)

— Get several locale specific information

funcsynopsis funcsynopsisinforequire_once 'I18Nv2.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2::getInfo()/funcdef paramdefstring $part = NULL /paramdef /funcprototype /funcsynopsis

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.

Example #1 Retrieving specific locale information:

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().

I18Nv2::lastLocale
I18Nv2::autoConv
I18Nv2


Automatically transform output between character sets

I18Nv2::getInfo
I18Nv2::createLocale
I18Nv2
PHP Manual

I18Nv2::autoConv()

(No version information available, might be only in CVS)

— Automatically transform output between character sets

funcsynopsis funcsynopsisinfo require_once 'I18Nv2.php'; /funcsynopsisinfo funcprototype funcdefmixed I18Nv2::autoConv()/funcdef paramdefstring $ocs = 'UTF-8' /paramdef paramdefstring $ics = 'ISO-8859-1' /paramdef /funcprototype /funcsynopsis

Description

This method utilizes ob_iconv_handler(), so you should call it at the beginning of your script (prior to any output).

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().

I18Nv2::getInfo
I18Nv2::createLocale
I18Nv2


Create an I18Nv2_Locale object

I18Nv2::autoConv
I18Nv2::createNegotiator
I18Nv2
PHP Manual

I18Nv2::createLocale()

(No version information available, might be only in CVS)

— Create an I18Nv2_Locale object

funcsynopsis funcsynopsisinforequire_once 'I18Nv2.php';/funcsynopsisinfo funcprototype funcdef object I18Nv2_Locale &I18Nv2::createLocale() /funcdef paramdef string $locale = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2::autoConv
I18Nv2::createNegotiator
I18Nv2


Create an I18Nv2_Negotiator object

I18Nv2::createLocale
I18Nv2::langs2locales
I18Nv2
PHP Manual

I18Nv2::createNegotiator()

(No version information available, might be only in CVS)

— Create an I18Nv2_Negotiator object

funcsynopsis funcsynopsisinforequire_once 'I18Nv2.php';/funcsynopsisinfo funcprototype funcdef object I18Nv2_Negotiator &I18Nv2::createNegotiator() /funcdef paramdefstring $defLang = 'en' /paramdef paramdefstring $defCharset = 'iso-8859-1' /paramdef /funcprototype /funcsynopsis

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.

I18Nv2::createLocale
I18Nv2::langs2locales
I18Nv2


Transform languages to locales

I18Nv2::createNegotiator
I18Nv2::locales2langs
I18Nv2
PHP Manual

I18Nv2::langs2locales()

(No version information available, might be only in CVS)

— Transform languages to locales

funcsynopsis funcsynopsisinforequire_once 'I18Nv2.php';/funcsynopsisinfo funcprototype funcdefarray I18Nv2::langs2locales()/funcdef paramdefarray $languages /paramdef /funcprototype /funcsynopsis

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().

I18Nv2::createNegotiator
I18Nv2::locales2langs
I18Nv2


Transform locales to languages

I18Nv2::langs2locales
Class Summary I18Nv2_Locale
I18Nv2
PHP Manual

I18Nv2::locales2langs()

(No version information available, might be only in CVS)

— Transform locales to languages

funcsynopsis funcsynopsisinforequire_once '/I18Nv2.php';/funcsynopsisinfo funcprototype funcdefarray I18Nv2::locales2langs()/funcdef paramdefarray $locales /paramdef /funcprototype /funcsynopsis

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().

I18Nv2::langs2locales
Class Summary I18Nv2_Locale
I18Nv2


I18Nv2::locales2langs
I18Nv2_Locale::I18Nv2_Locale
I18Nv2
PHP Manual

Class Summary I18Nv2_Locale

(No version information available, might be only in CVS)

Class Summary — I18Nv2_Locale

I18Nv2_Locale

Represents a specific locale and provides routines for formatting date and time, numbers and currency.

I18Nv2::locales2langs
I18Nv2_Locale::I18Nv2_Locale
I18Nv2


Constructor

Class Summary I18Nv2_Locale
I18Nv2_Locale::initialize
I18Nv2
PHP Manual

I18Nv2_Locale::I18Nv2_Locale()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefobject I18Nv2_Locale::I18Nv2_Locale()/funcdef paramdefstring $locale = NULL /paramdef /funcprototype /funcsynopsis

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.

Class Summary I18Nv2_Locale
I18Nv2_Locale::initialize
I18Nv2


Initialize

I18Nv2_Locale::I18Nv2_Locale
I18Nv2_Locale::loadExtension
I18Nv2
PHP Manual

I18Nv2_Locale::initialize()

(No version information available, might be only in CVS)

— Initialize

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefvoid I18Nv2_Locale::initialize()/funcdef paramdef /funcprototype /funcsynopsis

Description

Initializes the I18Nv2_Locale object.

This method gets aumatically called by the constructor.

Note

This function can not be called statically.

I18Nv2_Locale::I18Nv2_Locale
I18Nv2_Locale::loadExtension
I18Nv2


Loads corresponding locale extension

I18Nv2_Locale::initialize
I18Nv2_Locale::setLocale
I18Nv2
PHP Manual

I18Nv2_Locale::loadExtension()

(No version information available, might be only in CVS)

— Loads corresponding locale extension

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefvoid I18Nv2_Locale::loadExtension()/funcdef paramdef /funcprototype /funcsynopsis

Description

Load available locale extensions.

This method gets called autmatically by the constructor.

Note

This function can not be called statically.

I18Nv2_Locale::initialize
I18Nv2_Locale::setLocale
I18Nv2


Set locale

I18Nv2_Locale::loadExtension
I18Nv2_Locale::setDefaults
I18Nv2
PHP Manual

I18Nv2_Locale::setLocale()

(No version information available, might be only in CVS)

— Set locale

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::setLocale()/funcdef paramdefstring $locale /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::loadExtension
I18Nv2_Locale::setDefaults
I18Nv2


Set defaults

I18Nv2_Locale::setLocale
I18Nv2_Locale::setCustomFormat
I18Nv2
PHP Manual

I18Nv2_Locale::setDefaults()

(No version information available, might be only in CVS)

— Set defaults

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefvoid I18Nv2_Locale::setDefaults()/funcdef paramdef /funcprototype /funcsynopsis

Description

Reset used formats to the default values.

Note

This function can not be called statically.

I18Nv2_Locale::setLocale
I18Nv2_Locale::setCustomFormat
I18Nv2


Set custom format

I18Nv2_Locale::setDefaults
I18Nv2_Locale::setCurrencyFormat
I18Nv2
PHP Manual

I18Nv2_Locale::setCustomFormat()

(No version information available, might be only in CVS)

— Set custom format

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefvoid I18Nv2_Locale::setCustomFormat()/funcdef paramdefmixed $type = NULL /paramdef paramdefmixed $format = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::setDefaults
I18Nv2_Locale::setCurrencyFormat
I18Nv2


Set currency format

I18Nv2_Locale::setCustomFormat
I18Nv2_Locale::setDateFormat
I18Nv2
PHP Manual

I18Nv2_Locale::setCurrencyFormat()

(No version information available, might be only in CVS)

— Set currency format

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::setCurrencyFormat()/funcdef paramdefint $format /paramdef paramdefbool $custom = FALSE /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::setCustomFormat
I18Nv2_Locale::setDateFormat
I18Nv2


Set date format

I18Nv2_Locale::setCurrencyFormat
I18Nv2_Locale::setNumberFormat
I18Nv2
PHP Manual

I18Nv2_Locale::setDateFormat()

(No version information available, might be only in CVS)

— Set date format

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::setDateFormat()/funcdef paramdefint $format /paramdef paramdefbool $custom = FALSE /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::setCurrencyFormat
I18Nv2_Locale::setNumberFormat
I18Nv2


Set number format

I18Nv2_Locale::setDateFormat
I18Nv2_Locale::setTimeFormat
I18Nv2
PHP Manual

I18Nv2_Locale::setNumberFormat()

(No version information available, might be only in CVS)

— Set number format

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::setNumberFormat()/funcdef paramdefint $format /paramdef paramdefbool $custom = FALSE /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::setDateFormat
I18Nv2_Locale::setTimeFormat
I18Nv2


Set time format

I18Nv2_Locale::setNumberFormat
I18Nv2_Locale::formatDate
I18Nv2
PHP Manual

I18Nv2_Locale::setTimeFormat()

(No version information available, might be only in CVS)

— Set time format

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::setTimeFormat()/funcdef paramdefint $format /paramdef paramdefbool $custom = FALSE /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::setNumberFormat
I18Nv2_Locale::formatDate
I18Nv2


Format a date

I18Nv2_Locale::setTimeFormat
I18Nv2_Locale::formatTime
I18Nv2
PHP Manual

I18Nv2_Locale::formatDate()

(No version information available, might be only in CVS)

— Format a date

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Locale::formatDate()/funcdef paramdefint $timestamp = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::setTimeFormat
I18Nv2_Locale::formatTime
I18Nv2


Format a time

I18Nv2_Locale::formatDate
I18Nv2_Locale::formatNumber
I18Nv2
PHP Manual

I18Nv2_Locale::formatTime()

(No version information available, might be only in CVS)

— Format a time

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Locale::formatTime()/funcdef paramdefint $timestamp = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::formatDate
I18Nv2_Locale::formatNumber
I18Nv2


Format a number

I18Nv2_Locale::formatTime
I18Nv2_Locale::formatCurrency
I18Nv2
PHP Manual

I18Nv2_Locale::formatNumber()

(No version information available, might be only in CVS)

— Format a number

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Locale::formatNumber()/funcdef paramdefnumeric $value /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::formatTime
I18Nv2_Locale::formatCurrency
I18Nv2


Format currency

I18Nv2_Locale::formatNumber
I18Nv2_Locale::date
I18Nv2
PHP Manual

I18Nv2_Locale::formatCurrency()

(No version information available, might be only in CVS)

— Format currency

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Locale::formatCurrency()/funcdef paramdefnumeric $value /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::formatNumber
I18Nv2_Locale::date
I18Nv2


Get local date

I18Nv2_Locale::formatCurrency
I18Nv2_Locale::time
I18Nv2
PHP Manual

I18Nv2_Locale::date()

(No version information available, might be only in CVS)

— Get local date

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Locale::date()/funcdef paramdefint $timestamp = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::formatCurrency
I18Nv2_Locale::time
I18Nv2


Get local time

I18Nv2_Locale::date
I18Nv2_Locale::dayName
I18Nv2
PHP Manual

I18Nv2_Locale::time()

(No version information available, might be only in CVS)

— Get local time

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Locale::time()/funcdef paramdefint $timestamp = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::date
I18Nv2_Locale::dayName
I18Nv2


Get local day name

I18Nv2_Locale::time
I18Nv2_Locale::monthName
I18Nv2
PHP Manual

I18Nv2_Locale::dayName()

(No version information available, might be only in CVS)

— Get local day name

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::dayName()/funcdef paramdefint $weekday /paramdef paramdefbool $short = FALSE /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::time
I18Nv2_Locale::monthName
I18Nv2


Get local month name

I18Nv2_Locale::dayName
Class Summary I18Nv2_Negotiator
I18Nv2
PHP Manual

I18Nv2_Locale::monthName()

(No version information available, might be only in CVS)

— Get local month name

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Locale.php';/funcsynopsisinfo funcprototype funcdefmixed I18Nv2_Locale::monthName()/funcdef paramdefint $month /paramdef paramdefbool $short = FALSE /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Locale::dayName
Class Summary I18Nv2_Negotiator
I18Nv2


I18Nv2_Locale::monthName
I18Nv2_Negotiator::I18Nv2_Negotiator
I18Nv2
PHP Manual

Class Summary I18Nv2_Negotiator

(No version information available, might be only in CVS)

Class Summary — I18Nv2_Negotiator

I18Nv2_Negotiator

Provides basic negotiation of user preferred locale, language and characterset.

I18Nv2_Locale::monthName
I18Nv2_Negotiator::I18Nv2_Negotiator
I18Nv2


Constructor

Class Summary I18Nv2_Negotiator
I18Nv2_Negotiator::getCharsetMatch
I18Nv2
PHP Manual

I18Nv2_Negotiator::I18Nv2_Negotiator()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'I18N/Negotiator.php';/funcsynopsisinfo funcprototype funcdef object I18Nv2_Negotiator I18Nv2_Negotiator::I18Nv2_Negotiator()/funcdef paramdefstring $defaultLanguage = 'en' /paramdef paramdefstring $defaultCharset = 'iso-8859-1' /paramdef paramdefstring $defaultCountry = '' /paramdef /funcprototype /funcsynopsis

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.

Class Summary I18Nv2_Negotiator
I18Nv2_Negotiator::getCharsetMatch
I18Nv2


Get character set match

I18Nv2_Negotiator::I18Nv2_Negotiator
I18Nv2_Negotiator::getCountryMatch
I18Nv2
PHP Manual

I18Nv2_Negotiator::getCharsetMatch()

(No version information available, might be only in CVS)

— Get character set match

funcsynopsis funcsynopsisinfo require_once 'I18Nv2/Negotiator.php'; /funcsynopsisinfo funcprototype funcdefstring I18Nv2_Negotiator::getCharsetMatch()/funcdef paramdefarray $charsets = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Negotiator::I18Nv2_Negotiator
I18Nv2_Negotiator::getCountryMatch
I18Nv2


Get country match

I18Nv2_Negotiator::getCharsetMatch
I18Nv2_Negotiator::getLanguageMatch
I18Nv2
PHP Manual

I18Nv2_Negotiator::getCountryMatch()

(No version information available, might be only in CVS)

— Get country match

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Negotiator.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Negotiator::getCountryMatch()/funcdef paramdefstring $lang /paramdef paramdefarray $countries = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Negotiator::getCharsetMatch
I18Nv2_Negotiator::getLanguageMatch
I18Nv2


Get language match

I18Nv2_Negotiator::getCountryMatch
I18Nv2_Negotiator::getLocaleMatch
I18Nv2
PHP Manual

I18Nv2_Negotiator::getLanguageMatch()

(No version information available, might be only in CVS)

— Get language match

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Negotiator.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Negotiator::getLanguageMatch()/funcdef paramdefarray $langs = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Negotiator::getCountryMatch
I18Nv2_Negotiator::getLocaleMatch
I18Nv2


Get locale match

I18Nv2_Negotiator::getLanguageMatch
I18Nv2_Negotiator::getVariantInfo
I18Nv2
PHP Manual

I18Nv2_Negotiator::getLocaleMatch()

(No version information available, might be only in CVS)

— Get locale match

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Negotiator.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Negotiator::getLocaleMatch()/funcdef paramdefarray $langs = NULL /paramdef paramdefarray $countries = NULL /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Negotiator::getLanguageMatch
I18Nv2_Negotiator::getVariantInfo
I18Nv2


Return variant info for passed parameter.

I18Nv2_Negotiator::getLocaleMatch
I18Nv2_Negotiator::singleI18NCountry
I18Nv2
PHP Manual

I18Nv2_Negotiator::getVariantInfo()

(No version information available, might be only in CVS)

— Return variant info for passed parameter.

funcsynopsis funcsynopsisinfo require_once '/Negotiator.php'; /funcsynopsisinfo funcprototype funcdefstring I18Nv2_Negotiator::getVariantInfo()/funcdef paramdefstring $lang /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $lang

Throws

throws no exceptions thrown

Note

This function can not be called statically.

I18Nv2_Negotiator::getLocaleMatch
I18Nv2_Negotiator::singleI18NCountry
I18Nv2


Create the Country helper object

I18Nv2_Negotiator::getVariantInfo
I18Nv2_Negotiator::singleI18NLanguage
I18Nv2
PHP Manual

I18Nv2_Negotiator::singleI18NCountry()

(No version information available, might be only in CVS)

— Create the Country helper object

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Negotiator.php';/funcsynopsisinfo funcprototype funcdefobject &I18Nv2_Negotiator::singleI18NCountry()/funcdef paramdef /funcprototype /funcsynopsis

Description

Singleton for I18Nv2_Country.

Return value

Returns object I18Nv2_Country.

Note

This function can not be called statically.

I18Nv2_Negotiator::getVariantInfo
I18Nv2_Negotiator::singleI18NLanguage
I18Nv2


Create the Language helper object

I18Nv2_Negotiator::singleI18NCountry
Class Summary I18Nv2_Country
I18Nv2
PHP Manual

I18Nv2_Negotiator::singleI18NLanguage()

(No version information available, might be only in CVS)

— Create the Language helper object

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Negotiator.php';/funcsynopsisinfo funcprototype funcdefobject &I18Nv2_Negotiator::singleI18NLanguage()/funcdef paramdef /funcprototype /funcsynopsis

Description

Singleton for I18Nv2_Language.

Return value

Returns object I18Nv2_Language.

Note

This function can not be called statically.

I18Nv2_Negotiator::singleI18NCountry
Class Summary I18Nv2_Country
I18Nv2


I18Nv2_Negotiator::singleI18NLanguage
I18Nv2_Country::I18Nv2_Country
I18Nv2
PHP Manual

Class Summary I18Nv2_Country

(No version information available, might be only in CVS)

Class Summary — I18Nv2_Country

I18Nv2_Country

List of two letter country code to country name mapping.

I18Nv2_Negotiator::singleI18NLanguage
I18Nv2_Country::I18Nv2_Country
I18Nv2


Constructor

Class Summary I18Nv2_Country
I18Nv2_Country::getAllCodes
I18Nv2
PHP Manual

I18Nv2_Country::I18Nv2_Country()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Country.php';/funcsynopsisinfo funcprototype funcdef object I18Nv2_Country I18Nv2_Country::I18Nv2_Country() /funcdef paramdef /funcprototype /funcsynopsis

Description

Instantiate a new I18Nv2_Country object.

Return value

Returns object I18Nv2_Country.

Class Summary I18Nv2_Country
I18Nv2_Country::getAllCodes
I18Nv2


Get all codes

I18Nv2_Country::I18Nv2_Country
I18Nv2_Country::getName
I18Nv2
PHP Manual

I18Nv2_Country::getAllCodes()

(No version information available, might be only in CVS)

— Get all codes

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Country.php';/funcsynopsisinfo funcprototype funcdefarray I18Nv2_Country::getAllCodes()/funcdef paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Country::I18Nv2_Country
I18Nv2_Country::getName
I18Nv2


Get country name

I18Nv2_Country::getAllCodes
I18Nv2_Country::isValidCode
I18Nv2
PHP Manual

I18Nv2_Country::getName()

(No version information available, might be only in CVS)

— Get country name

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Country.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Country::getName()/funcdef paramdefstring $code /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Country::getAllCodes
I18Nv2_Country::isValidCode
I18Nv2


Check if country code is valid

I18Nv2_Country::getName
Class Summary I18Nv2_Language
I18Nv2
PHP Manual

I18Nv2_Country::isValidCode()

(No version information available, might be only in CVS)

— Check if country code is valid

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Country.php';/funcsynopsisinfo funcprototype funcdefbool I18Nv2_Country::isValidCode()/funcdef paramdefstring $code /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Country::getName
Class Summary I18Nv2_Language
I18Nv2


I18Nv2_Country::isValidCode
I18Nv2_Language::I18Nv2_Language
I18Nv2
PHP Manual

Class Summary I18Nv2_Language

(No version information available, might be only in CVS)

Class Summary — I18Nv2_Language

I18Nv2_Language

List of ISO-639-1 two letter resp. ISO-639-2 three letter language code to language name mapping.

I18Nv2_Country::isValidCode
I18Nv2_Language::I18Nv2_Language
I18Nv2


Constructor

Class Summary I18Nv2_Language
I18Nv2_Language::getAllCodes
I18Nv2
PHP Manual

I18Nv2_Language::I18Nv2_Language()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Language.php';/funcsynopsisinfo funcprototype funcdef object object I18Nv2_Language I18Nv2_Language::I18Nv2_Language() /funcdef paramdefbool $threeLetters = FALSE /paramdef /funcprototype /funcsynopsis

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.

Class Summary I18Nv2_Language
I18Nv2_Language::getAllCodes
I18Nv2


Get all codes

I18Nv2_Language::I18Nv2_Language
I18Nv2_Language::getName
I18Nv2
PHP Manual

I18Nv2_Language::getAllCodes()

(No version information available, might be only in CVS)

— Get all codes

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Language.php';/funcsynopsisinfo funcprototype funcdefarray I18Nv2_Language::getAllCodes()/funcdef paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Language::I18Nv2_Language
I18Nv2_Language::getName
I18Nv2


Return name of the language for language code

I18Nv2_Language::getAllCodes
I18Nv2_Language::isValidCode
I18Nv2
PHP Manual

I18Nv2_Language::getName()

(No version information available, might be only in CVS)

— Return name of the language for language code

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Language.php';/funcsynopsisinfo funcprototype funcdefstring I18Nv2_Language::getName()/funcdef paramdefstring $code /paramdef /funcprototype /funcsynopsis

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.

I18Nv2_Language::getAllCodes
I18Nv2_Language::isValidCode
I18Nv2


Check if language code is valid

I18Nv2
Translation2
I18Nv2
PHP Manual

I18Nv2_Language::isValidCode()

(No version information available, might be only in CVS)

— Check if language code is valid

funcsynopsis funcsynopsisinforequire_once 'I18Nv2/Language.php';/funcsynopsisinfo funcprototype funcdefboolean I18Nv2_Language::isValidCode()/funcdef paramdefstring $code /paramdef /funcprototype /funcsynopsis

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.

I18Nv2
Translation2
I18Nv2


Translation2

Internationalization
Class Summary Translation2
Internationalization


Translation2
Introduction
Translation2
PHP Manual

Class Summary Translation2

(No version information available, might be only in CVS)

Class Summary — 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

Translation2
Introduction
Translation2


Usage of Translation2

Class Summary Translation2
Admin Introduction
Translation2
PHP Manual

Introduction

(No version information available, might be only in CVS)

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)

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:

// 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

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:

$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.

$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:

$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).

// "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:

$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:
$translations = array_merge(
    $tr->getPage('header'),
    $tr->getPage('body'),
    $tr->getPage('footer')
);

Class Summary Translation2
Admin Introduction
Translation2


Usage of Translation2_Admin

Introduction
Containers Overview
Translation2
PHP Manual

Admin Introduction

(No version information available, might be only in CVS)

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).

Adding a new language

This simple example will show how you can add a new language [addLang()], using the MDB2 driver:

// 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()]:

// 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

$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:
$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.

$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:

$tr->remove('smallTest', 'testGroup');

Introduction
Containers Overview
Translation2


Overview of the different Translation2 containers

Admin Introduction
constructor Translation2::Translation2
Translation2
PHP Manual

Containers Overview

(No version information available, might be only in CVS)

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).

// 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:

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.

$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);

Admin Introduction
constructor Translation2::Translation2
Translation2


Constructor

Containers Overview
Translation2::factory
Translation2
PHP Manual

constructor Translation2::Translation2()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Translation2::Translation2()/funcdef paramdefstring $storageDriver /paramdef paramdefmixed $options = '' /paramdef paramdefarray $params = array() /paramdef /funcprototype /funcsynopsis

Description

This constructor is deprecated in favour of the factory() method.

Note

This function can not be called statically.

Containers Overview
Translation2::factory
Translation2


Return an instanciated Translation2 object

constructor Translation2::Translation2
Translation2::get
Translation2
PHP Manual

Translation2::factory()

(No version information available, might be only in CVS)

— Return an instanciated Translation2 object

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefvoid Translation2::factory()/funcdef paramdefstring $storageDriver /paramdef paramdefmixed $options = '' /paramdef paramdefarray $params = array() /paramdef /funcprototype /funcsynopsis

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.

constructor Translation2::Translation2
Translation2::get
Translation2


Get translated string

Translation2::factory
Translation2::getDecorator
Translation2
PHP Manual

Translation2::get()

(No version information available, might be only in CVS)

— Get translated string

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefstring Translation2::get()/funcdef paramdefstring $stringID /paramdef paramdefstring $pageID = TRANSLATION2_DEFAULT_PAGEID /paramdef paramdefstring $langID = NULL /paramdef paramdefstring $defaultText = '' /paramdef /funcprototype /funcsynopsis

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.

Translation2::factory
Translation2::getDecorator
Translation2


Return an instance of a decorator

Translation2::get
Translation2::getLang
Translation2
PHP Manual

Translation2::getDecorator()

(No version information available, might be only in CVS)

— Return an instance of a decorator

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefobject Decorator& Translation2::getDecorator()/funcdef paramdefstring $decorator /paramdef paramdefobject [optional] 1 /paramdef /funcprototype /funcsynopsis

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.

Translation2::get
Translation2::getLang
Translation2


get lang info

Translation2::getDecorator
Translation2::getLangs
Translation2
PHP Manual

Translation2::getLang()

(No version information available, might be only in CVS)

— get lang info

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2::getLang()/funcdef paramdefstring $langID = NULL /paramdef paramdefstring $format = 'name' /paramdef /funcprototype /funcsynopsis

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.

Translation2::getDecorator
Translation2::getLangs
Translation2


get langs

Translation2::getLang
Translation2::getPage
Translation2
PHP Manual

Translation2::getLangs()

(No version information available, might be only in CVS)

— get langs

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefarray Translation2::getLangs()/funcdef paramdefstring $format = 'name' /paramdef /funcprototype /funcsynopsis

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.

Translation2::getLang
Translation2::getPage
Translation2


Get an entire group of strings

Translation2::getLangs
Translation2::getRaw
Translation2
PHP Manual

Translation2::getPage()

(No version information available, might be only in CVS)

— Get an entire group of strings

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefarray Translation2::getPage()/funcdef paramdefstring $pageID = TRANSLATION2_DEFAULT_PAGEID /paramdef paramdefstring $langID = NULL /paramdef /funcprototype /funcsynopsis

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.

Translation2::getLangs
Translation2::getRaw
Translation2


Get translated string (as-is)

Translation2::getPage
Translation2::getRawPage
Translation2
PHP Manual

Translation2::getRaw()

(No version information available, might be only in CVS)

— Get translated string (as-is)

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefstring Translation2::getRaw()/funcdef paramdefstring $stringID /paramdef paramdefstring $pageID = TRANSLATION2_DEFAULT_PAGEID /paramdef paramdefstring $langID = NULL /paramdef paramdefstring $defaultText = '' /paramdef /funcprototype /funcsynopsis

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.

Translation2::getPage
Translation2::getRawPage
Translation2


Get the array of strings in a page

Translation2::getRaw
Translation2::getStringID
Translation2
PHP Manual

Translation2::getRawPage()

(No version information available, might be only in CVS)

— Get the array of strings in a page

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefarray Translation2::getRawPage()/funcdef paramdefstring $pageID = TRANSLATION2_DEFAULT_PAGEID /paramdef paramdefstring $langID = NULL /paramdef /funcprototype /funcsynopsis

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.

Translation2::getRaw
Translation2::getStringID
Translation2


Get the stringID for a given string

Translation2::getRawPage
Translation2::replaceEmptyStringsWithKeys
Translation2
PHP Manual

Translation2::getStringID()

(No version information available, might be only in CVS)

— Get the stringID for a given string

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefstring Translation2::getStringID()/funcdef paramdefstring $string /paramdef paramdefmixed $pageID = TRANSLATION2_DEFAULT_PAGEID /paramdef /funcprototype /funcsynopsis

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.

Translation2::getRawPage
Translation2::replaceEmptyStringsWithKeys
Translation2


Replace the array values with their keys when empty

Translation2::getStringID
Translation2::setCharset
Translation2
PHP Manual

Translation2::replaceEmptyStringsWithKeys()

(No version information available, might be only in CVS)

— Replace the array values with their keys when empty

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefarray Translation2::replaceEmptyStringsWithKeys()/funcdef paramdefarray $strings /paramdef /funcprototype /funcsynopsis

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())

Translation2::getStringID
Translation2::setCharset
Translation2


Set the charset used to get/store the translations

Translation2::replaceEmptyStringsWithKeys
Translation2::setLang
Translation2
PHP Manual

Translation2::setCharset()

(No version information available, might be only in CVS)

— Set the charset used to get/store the translations

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2::setCharset()/funcdef paramdefstring $charset /paramdef /funcprototype /funcsynopsis

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.

Translation2::replaceEmptyStringsWithKeys
Translation2::setLang
Translation2


Set default lang

Translation2::setCharset
Translation2::setPageID
Translation2
PHP Manual

Translation2::setLang()

(No version information available, might be only in CVS)

— Set default lang

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefvoid Translation2::setLang()/funcdef paramdefstring $langID /paramdef /funcprototype /funcsynopsis

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.

Translation2::setCharset
Translation2::setPageID
Translation2


Set default page

Translation2::setLang
Translation2::setParams
Translation2
PHP Manual

Translation2::setPageID()

(No version information available, might be only in CVS)

— Set default page

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefvoid Translation2::setPageID()/funcdef paramdefmixed $pageID = NULL /paramdef paramdefstring $langID /paramdef /funcprototype /funcsynopsis

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.

Translation2::setLang
Translation2::setParams
Translation2


Set parameters for next string

Translation2::setPageID
Class Summary Translation2_Admin
Translation2
PHP Manual

Translation2::setParams()

(No version information available, might be only in CVS)

— Set parameters for next string

funcsynopsis funcsynopsisinfo require_once 'Translation2.php'; /funcsynopsisinfo funcprototype funcdefvoid Translation2::setParams()/funcdef paramdefparams $params = NULL /paramdef /funcprototype /funcsynopsis

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.

Translation2::setPageID
Class Summary Translation2_Admin
Translation2


Translation2::setParams
Translation2_Admin::addLang
Translation2
PHP Manual

Class Summary Translation2_Admin

(No version information available, might be only in CVS)

Class Summary — 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

Translation2::setParams
Translation2_Admin::addLang
Translation2


Prepare the storage container for a new lang.

Class Summary Translation2_Admin
Translation2_Admin::updateLang
Translation2
PHP Manual

Translation2_Admin::addLang()

(No version information available, might be only in CVS)

— Prepare the storage container for a new lang.

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::addLang()/funcdef paramdefarray $langData /paramdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Class Summary Translation2_Admin
Translation2_Admin::updateLang
Translation2


Update the language details.

Translation2_Admin::addLang
Translation2_Admin::removeLang
Translation2
PHP Manual

Translation2_Admin::updateLang()

(No version information available, might be only in CVS)

— Update the language details.

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::updateLang()/funcdef paramdefarray $langData /paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::addLang
Translation2_Admin::removeLang
Translation2


Remove the language from the langsAvail table and drop the strings table.

Translation2_Admin::updateLang
Translation2_Admin::add
Translation2
PHP Manual

Translation2_Admin::removeLang()

(No version information available, might be only in CVS)

— Remove the language from the langsAvail table and drop the strings table.

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::removeLang()/funcdef paramdefstring $langID = NULL /paramdef paramdefboolean $force = FALSE /paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::updateLang
Translation2_Admin::add
Translation2


add a new translation

Translation2_Admin::removeLang
Translation2_Admin::remove
Translation2
PHP Manual

Translation2_Admin::add()

(No version information available, might be only in CVS)

— add a new translation

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::add()/funcdef paramdefstring $stringID /paramdef paramdefstring $pageID = NULL /paramdef paramdefarray $stringArray /paramdef /funcprototype /funcsynopsis

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:

$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.

Translation2_Admin::removeLang
Translation2_Admin::remove
Translation2


remove a translated string

Translation2_Admin::add
Translation2_Admin::update
Translation2
PHP Manual

Translation2_Admin::remove()

(No version information available, might be only in CVS)

— remove a translated string

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::remove()/funcdef paramdefstring $stringID /paramdef paramdefstring $pageID = NULL /paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::add
Translation2_Admin::update
Translation2


Update an existing translation.

Translation2_Admin::remove
Translation2_Admin::removePage
Translation2
PHP Manual

Translation2_Admin::update()

(No version information available, might be only in CVS)

— Update an existing translation.

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::update()/funcdef paramdefstring $stringID /paramdef paramdefstring $pageID /paramdef paramdefarray $stringArray /paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::remove
Translation2_Admin::removePage
Translation2


remove all the translated strings in a page/group

Translation2_Admin::update
Translation2_Admin::cleanCache
Translation2
PHP Manual

Translation2_Admin::removePage()

(No version information available, might be only in CVS)

— remove all the translated strings in a page/group

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefmixed Translation2_Admin::removePage()/funcdef paramdefstring $pageID = NULL /paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::update
Translation2_Admin::cleanCache
Translation2


Clear the cache. Use with the CacheLiteFunction decorator only.

Translation2_Admin::removePage
Translation2_Admin::getPageNames
Translation2
PHP Manual

Translation2_Admin::cleanCache()

(No version information available, might be only in CVS)

— Clear the cache. Use with the CacheLiteFunction decorator only.

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefvoid Translation2_Admin::cleanCache()/funcdef paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::removePage
Translation2_Admin::getPageNames
Translation2


Get a list of all the pageIDs in any table.

Translation2_Admin::cleanCache
Translation2_Admin::getAdminDecorator
Translation2
PHP Manual

Translation2_Admin::getPageNames()

(No version information available, might be only in CVS)

— Get a list of all the pageIDs in any table.

funcsynopsis funcsynopsisinfo require_once 'Admin.php'; /funcsynopsisinfo funcprototype funcdefarray Translation2_Admin::getPageNames()/funcdef paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::cleanCache
Translation2_Admin::getAdminDecorator
Translation2


Return an instance of an admin decorator

Translation2_Admin::getPageNames
Class Summary Translation2_Decorator
Translation2
PHP Manual

Translation2_Admin::getAdminDecorator()

(No version information available, might be only in CVS)

— Return an instance of an admin decorator

funcsynopsis funcsynopsisinfo require_once 'Translation2/Admin.php'; /funcsynopsisinfo funcprototype funcdefobject Decorator& Translation2_Admin::getAdminDecorator()/funcdef paramdefstring $decorator /paramdef paramdefobject [optional] 1 /paramdef /funcprototype /funcsynopsis

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.

Translation2_Admin::getPageNames
Class Summary Translation2_Decorator
Translation2


Translation2_Admin::getAdminDecorator
Class Summary Translation2_Decorator_CacheLiteFunction
Translation2
PHP Manual

Class Summary Translation2_Decorator

(No version information available, might be only in CVS)

Class Summary — 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

Translation2_Admin::getAdminDecorator
Class Summary Translation2_Decorator_CacheLiteFunction
Translation2


Decorator to cache fetched data using Cache_Lite_Function class

Class Summary Translation2_Decorator
Class Summary Translation2_Decorator_CacheMemory
Translation2
PHP Manual

Class Summary Translation2_Decorator_CacheLiteFunction

(No version information available, might be only in CVS)

Class Summary — 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().
$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);

Class Summary Translation2_Decorator
Class Summary Translation2_Decorator_CacheMemory
Translation2


Decorator to cache fetched data in memory

Class Summary Translation2_Decorator_CacheLiteFunction
Class Summary Translation2_Decorator_DefaultText
Translation2
PHP Manual

Class Summary Translation2_Decorator_CacheMemory

(No version information available, might be only in CVS)

Class Summary — 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)

$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('CacheMemory');
$tr->setOption('prefetch', true); //default value is true

Class Summary Translation2_Decorator_CacheLiteFunction
Class Summary Translation2_Decorator_DefaultText
Translation2


Decorator to provide a fallback text for empty strings.

Class Summary Translation2_Decorator_CacheMemory
Class Summary Translation2_Decorator_ErrorText
Translation2
PHP Manual

Class Summary Translation2_Decorator_DefaultText

(No version information available, might be only in CVS)

Class Summary — 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.

$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

Class Summary Translation2_Decorator_CacheMemory
Class Summary Translation2_Decorator_ErrorText
Translation2


Decorator to provide a fallback error_text message for empty strings.

Class Summary Translation2_Decorator_DefaultText
Class Summary Translation2_Decorator_Lang
Translation2
PHP Manual

Class Summary Translation2_Decorator_ErrorText

(No version information available, might be only in CVS)

Class Summary — 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

$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('ErrorText');

Class Summary Translation2_Decorator_DefaultText
Class Summary Translation2_Decorator_Lang
Translation2


Decorator to provide a fallback language for empty strings.

Class Summary Translation2_Decorator_ErrorText
Class Summary Translation2_Decorator_Iconv
Translation2
PHP Manual

Class Summary Translation2_Decorator_Lang

(No version information available, might be only in CVS)

Class Summary — 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.

$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');

Class Summary Translation2_Decorator_ErrorText
Class Summary Translation2_Decorator_Iconv
Translation2


Decorator to switch from/to different encodings.

Class Summary Translation2_Decorator_Lang
Class Summary Translation2_Decorator_SpecialChars
Translation2
PHP Manual

Class Summary Translation2_Decorator_Iconv

(No version information available, might be only in CVS)

Class Summary — 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.

$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');

Class Summary Translation2_Decorator_Lang
Class Summary Translation2_Decorator_SpecialChars
Translation2


Decorator to replace special chars with the matching html entities.

Class Summary Translation2_Decorator_Iconv
Class Summary Translation2_Decorator_UTF8
Translation2
PHP Manual

Class Summary Translation2_Decorator_SpecialChars

(No version information available, might be only in CVS)

Class Summary — 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'):

$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('SpecialChars');
$tr->setOption('charset', 'UTF-8');

Class Summary Translation2_Decorator_Iconv
Class Summary Translation2_Decorator_UTF8
Translation2


Decorator to convert UTF-8 strings to ISO-8859-1

Class Summary Translation2_Decorator_SpecialChars
Package Translation2 Constants
Translation2
PHP Manual

Class Summary Translation2_Decorator_UTF8

(No version information available, might be only in CVS)

Class Summary — Decorator to convert UTF-8 strings to ISO-8859-1

UTF-8 Decorator Example

This decorator calls utf8_decode() on each string

$tr = new Translation2($driver, $dbinfo, $params);
$tr =& $tr->getDecorator('UTF8');

Class Summary Translation2_Decorator_SpecialChars
Package Translation2 Constants
Translation2


Constants defined in and used by Translation2

Translation2
Logging
Translation2
PHP Manual

Package Translation2 Constants

(No version information available, might be only in CVS)

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

Translation2
Logging
Translation2


Logging

Table of Contents

  • Log

Provides Packages for logging purposes

Package Translation2 Constants
Log
Packages


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/.

Logging
Mail
Logging


Mail
Packages
PHP Manual

Mail

Table of Contents

  • Mail
  • Mail_IMAP
  • Mail_Mbox
  • Mail_Mime
  • Mail_Queue

Provides Packages for creating and working with electronic mails

Log
Mail
Packages


Mail
Introduction
Mail
PHP Manual

Mail

An interface for sending EMails

Mail
Introduction
Mail
PHP Manual


How to send a mail and the mailer backends

Mail
Mail::factory()
Mail
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Mail
Mail::factory()
Mail


creates a mailer instance

Introduction
Mail::send()
Mail
PHP Manual

Mail::factory()

(No version information available, might be only in CVS)

Mail::factory() — creates a mailer instance

funcsynopsis funcsynopsisinfo require_once 'Mail.php'; /funcsynopsisinfo funcprototype funcdefobject &factory()/funcdef paramdef string $backend /paramdef paramdef array $params = array() /paramdef /funcprototype /funcsynopsis

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"

Introduction
Mail::send()
Mail


sends a mail

Mail::factory()
RFC822 - Introduction
Mail
PHP Manual

Mail::send()

(No version information available, might be only in CVS)

Mail::send() — sends a mail

funcsynopsis funcsynopsisinfo require_once 'Mail.php'; /funcsynopsisinfo funcprototype funcdefmixed send()/funcdef paramdefmixed $recipients /paramdef paramdefarray $headers /paramdef paramdefstring $body /paramdef /funcprototype /funcsynopsis

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: $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: $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()

Mail::factory()
RFC822 - Introduction
Mail


email address validation

Mail::send()
Mail_RFC822::parseAddressList()
Mail
PHP Manual

RFC822 - Introduction

(No version information available, might be only in CVS)

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.

Mail::send()
Mail_RFC822::parseAddressList()
Mail


extract the parts of a list of email addresses

Mail
Mail_IMAP
Mail
PHP Manual

Mail_RFC822::parseAddressList()

(No version information available, might be only in CVS)

Mail_RFC822::parseAddressList() — extract the parts of a list of email addresses

funcsynopsis funcsynopsisinfo require_once 'Mail/RFC822.php'; /funcsynopsisinfo funcprototype funcdefarray parseAddressList()/funcdef paramdef string $address = '' /paramdef paramdef string $defaultDomain = 'localhost' /paramdef paramdef boolean $nestGroups = NULL /paramdef paramdef boolean $validate = NULL /paramdef /funcprototype /funcsynopsis

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.

Warning

This class checks the string only. It does not check for the existence of an email address.

Example

Example #1 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);
?>

Mail
Mail_IMAP
Mail


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.

Mail_RFC822::parseAddressList()
Introduction
Mail


Mail_IMAP provides a simplified backend for working with the c-client (IMAP) extension.

Mail_IMAP
Mail_Mbox
Mail_IMAP
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Mail_IMAP
Mail_Mbox
Mail_IMAP


Mail_Mbox

Introduction
Class Summary Mail_Mbox
Mail


Class to read mbox mail files.

Mail_Mbox
Tutorial
Mail_Mbox
PHP Manual

Class Summary Mail_Mbox

(No version information available, might be only in CVS)

Class Summary — 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

Mail_Mbox
Tutorial
Mail_Mbox


Class Summary Mail_Mbox
constructor Mail_Mbox::Mail_Mbox
Mail_Mbox
PHP Manual

Tutorial

(No version information available, might be only in CVS)

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/.

Class Summary Mail_Mbox
constructor Mail_Mbox::Mail_Mbox
Mail_Mbox


Create a new Mbox class instance.

Tutorial
Mail_Mbox::close
Mail_Mbox
PHP Manual

constructor Mail_Mbox::Mail_Mbox()

(No version information available, might be only in CVS)

constructor — Create a new Mbox class instance.

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef void constructor Mail_Mbox::Mail_Mbox() /funcdef paramdef string $file /paramdef /funcprototype /funcsynopsis

Description

After creating a new instance, you should use open() to open an mbox file.

Parameter

string $file

Filename to open.

Tutorial
Mail_Mbox::close
Mail_Mbox


Close a Mbox

constructor Mail_Mbox::Mail_Mbox
Mail_Mbox::get
Mail_Mbox
PHP Manual

Mail_Mbox::close()

(No version information available, might be only in CVS)

— Close a Mbox

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef mixed Mail_Mbox::close() /funcdef paramdef /funcprototype /funcsynopsis

Description

Close the Mbox file opened by open().

Return value

returns true on success, else PEAR_Error

constructor Mail_Mbox::Mail_Mbox
Mail_Mbox::get
Mail_Mbox


Get a message from the mbox

Mail_Mbox::close
Mail_Mbox::getDebug
Mail_Mbox
PHP Manual

Mail_Mbox::get()

(No version information available, might be only in CVS)

— Get a message from the mbox

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef string Mail_Mbox::get() /funcdef paramdef int $message /paramdef /funcprototype /funcsynopsis

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.

Mail_Mbox::close
Mail_Mbox::getDebug
Mail_Mbox


Returns the debug flag setting

Mail_Mbox::get
Mail_Mbox::getTmpDir
Mail_Mbox
PHP Manual

Mail_Mbox::getDebug()

(No version information available, might be only in CVS)

— Returns the debug flag setting

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef boolean Mail_Mbox::getDebug() /funcdef paramdef /funcprototype /funcsynopsis

Description

Returns true if debugging is enabled.

Return value

returns true if debug is enabled.

Mail_Mbox::get
Mail_Mbox::getTmpDir
Mail_Mbox


Returns the temporary directory

Mail_Mbox::getDebug
Mail_Mbox::hasBeenModified
Mail_Mbox
PHP Manual

Mail_Mbox::getTmpDir()

(No version information available, might be only in CVS)

— Returns the temporary directory

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef string Mail_Mbox::getTmpDir() /funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the temporary directory.

Return value

returns The temporary directory.

Mail_Mbox::getDebug
Mail_Mbox::hasBeenModified
Mail_Mbox


Checks if the file was modified since it has been loaded.

Mail_Mbox::getTmpDir
Mail_Mbox::insert
Mail_Mbox
PHP Manual

Mail_Mbox::hasBeenModified()

(No version information available, might be only in CVS)

— Checks if the file was modified since it has been loaded.

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef boolean Mail_Mbox::hasBeenModified() /funcdef paramdef /funcprototype /funcsynopsis

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.

Mail_Mbox::getTmpDir
Mail_Mbox::insert
Mail_Mbox


Insert a message

Mail_Mbox::hasBeenModified
Mail_Mbox::open
Mail_Mbox
PHP Manual

Mail_Mbox::insert()

(No version information available, might be only in CVS)

— Insert a message

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef mixed Mail_Mbox::insert() /funcdef paramdef string $content /paramdef paramdef mixed $offset = NULL /paramdef /funcprototype /funcsynopsis

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.

Mail_Mbox::hasBeenModified
Mail_Mbox::open
Mail_Mbox


Open the mbox file

Mail_Mbox::insert
Mail_Mbox::remove
Mail_Mbox
PHP Manual

Mail_Mbox::open()

(No version information available, might be only in CVS)

— Open the mbox file

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef void Mail_Mbox::open() /funcdef paramdef /funcprototype /funcsynopsis

Description

Also, this function will process the mbox file and create a cache that tells each message start and end bytes.

Mail_Mbox::insert
Mail_Mbox::remove
Mail_Mbox


Remove a message from Mbox and save it.

Mail_Mbox::open
Mail_Mbox::setDebug
Mail_Mbox
PHP Manual

Mail_Mbox::remove()

(No version information available, might be only in CVS)

— Remove a message from Mbox and save it.

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef mixed Mail_Mbox::remove() /funcdef paramdef int $message /paramdef /funcprototype /funcsynopsis

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.

Mail_Mbox::open
Mail_Mbox::setDebug
Mail_Mbox


Set the debug flag

Mail_Mbox::remove
Mail_Mbox::setTmpDir
Mail_Mbox
PHP Manual

Mail_Mbox::setDebug()

(No version information available, might be only in CVS)

— Set the debug flag

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef void Mail_Mbox::setDebug() /funcdef paramdef boolean $debug /paramdef /funcprototype /funcsynopsis

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

Mail_Mbox::remove
Mail_Mbox::setTmpDir
Mail_Mbox


Set the directory for temporary files.

Mail_Mbox::setDebug
Mail_Mbox::size
Mail_Mbox
PHP Manual

Mail_Mbox::setTmpDir()

(No version information available, might be only in CVS)

— Set the directory for temporary files.

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef void Mail_Mbox::setTmpDir() /funcdef paramdef string $tmpdir /paramdef /funcprototype /funcsynopsis

Description

Sets the temporary directory in which new mbox files are stored.

Parameter

string $tmpdir

The new temporary directory.

See

see Mail_Mbox::$tmpdir

Mail_Mbox::setDebug
Mail_Mbox::size
Mail_Mbox


Get number of messages in this mbox

Mail_Mbox::setTmpDir
Mail_Mbox::update
Mail_Mbox
PHP Manual

Mail_Mbox::size()

(No version information available, might be only in CVS)

— Get number of messages in this mbox

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef int Mail_Mbox::size() /funcdef paramdef /funcprototype /funcsynopsis

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).

Mail_Mbox::setTmpDir
Mail_Mbox::update
Mail_Mbox


Update a message

Mail_Mbox::size
Mail_Mbox::_move
Mail_Mbox
PHP Manual

Mail_Mbox::update()

(No version information available, might be only in CVS)

— Update a message

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef mixed Mail_Mbox::update() /funcdef paramdef int $message /paramdef paramdef string $content /paramdef /funcprototype /funcsynopsis

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

Mail_Mbox::size
Mail_Mbox::_move
Mail_Mbox


Copy a file to another

Mail_Mbox::update
Mail_Mbox::_process
Mail_Mbox
PHP Manual

Mail_Mbox::_move()

(No version information available, might be only in CVS)

— Copy a file to another

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef void Mail_Mbox::_move() /funcdef paramdef string $ftempname /paramdef paramdef string $filename /paramdef /funcprototype /funcsynopsis

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

Mail_Mbox::update
Mail_Mbox::_process
Mail_Mbox


Process the Mbox

Mail_Mbox
Mail_Mime
Mail_Mbox
PHP Manual

Mail_Mbox::_process()

(No version information available, might be only in CVS)

— Process the Mbox

funcsynopsis funcsynopsisinforequire_once '/Mbox.php';/funcsynopsisinfo funcprototype funcdef void Mail_Mbox::_process() /funcdef paramdef /funcprototype /funcsynopsis

Description

  • Get start bytes and end bytes of each messages.

Mail_Mbox
Mail_Mime
Mail_Mbox


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.

Mail_Mbox::_process
Mail_Mime - Example
Mail


generation and sending of a MIME mail

Mail_Mime
Mail_mimeDecode - Example
Mail_Mime
PHP Manual

Mail_Mime - Example

(No version information available, might be only in CVS)

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);
?>
Mail_Mime
Mail_mimeDecode - Example
Mail_Mime


decode an email

Mail_Mime - Example
Mail_Mime::Mail_Mime()
Mail_Mime
PHP Manual

Mail_mimeDecode - Example

(No version information available, might be only in CVS)

Mail_mimeDecode - Example — decode an email

Example

Example #1 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);

?>
Mail_Mime - Example
Mail_Mime::Mail_Mime()
Mail_Mime


creates a new instance

Mail_mimeDecode - Example
Mail_Mime::addAttachment()
Mail_Mime
PHP Manual

Mail_Mime::Mail_Mime()

(No version information available, might be only in CVS)

Mail_Mime::Mail_Mime() — creates a new instance

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefMail_mime Mail_mime()/funcdef paramdefstring $crlf = "\r\n" /paramdef /funcprototype /funcsynopsis

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"

Mail_mimeDecode - Example
Mail_Mime::addAttachment()
Mail_Mime


add attachment

Mail_Mime::Mail_Mime()
Mail_Mime::addHTMLImage()
Mail_Mime
PHP Manual

Mail_Mime::addAttachment()

(No version information available, might be only in CVS)

Mail_Mime::addAttachment() — add attachment

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefboolean addAttachment()/funcdef paramdefstring $file /paramdef paramdef string $c_type = 'application/octet-stream' /paramdef paramdefstring $name = '' /paramdef paramdefboolean $isfile = TRUE /paramdef paramdefstring $encoding = 'base64' /paramdef /funcprototype /funcsynopsis

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.

Mail_Mime::Mail_Mime()
Mail_Mime::addHTMLImage()
Mail_Mime


add image to message

Mail_Mime::addAttachment()
Mail_Mime::get()
Mail_Mime
PHP Manual

Mail_Mime::addHTMLImage()

(No version information available, might be only in CVS)

Mail_Mime::addHTMLImage() — add image to message

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefboolean addHTMLImage()/funcdef paramdef string $file /paramdef paramdef string $c_type = 'application/octet-stream' /paramdef paramdef string $name = '' /paramdef paramdef boolean $isfile = TRUE /paramdef /funcprototype /funcsynopsis

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()

Mail_Mime::addAttachment()
Mail_Mime::get()
Mail_Mime


build the message

Mail_Mime::addHTMLImage()
Mail_Mime::headers()
Mail_Mime
PHP Manual

Mail_Mime::get()

(No version information available, might be only in CVS)

Mail_Mime::get() — build the message

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefstring &get()/funcdef paramdefarray $param = NULL /paramdef /funcprototype /funcsynopsis

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.

Warning

Mail_Mime::get() has to be called before Mail_Mime::headers().

See

Mail_Mime::headers()

Mail_Mime::addHTMLImage()
Mail_Mime::headers()
Mail_Mime


build the header lines

Mail_Mime::get()
Mail_Mime::setHTMLBody()
Mail_Mime
PHP Manual

Mail_Mime::headers()

(No version information available, might be only in CVS)

Mail_Mime::headers() — build the header lines

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefarray &headers()/funcdef paramdefarray $headerEx = NULL /paramdef paramdefboolean $overwrite = FALSE /paramdef /funcprototype /funcsynopsis

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.

Warning

Mail_Mime::headers() has to be called after Mail_Mime::get().

See

Mail_Mime::get()

Mail_Mime::get()
Mail_Mime::setHTMLBody()
Mail_Mime


set HTML part

Mail_Mime::headers()
Mail_Mime::setTxtBody()
Mail_Mime
PHP Manual

Mail_Mime::setHTMLBody()

(No version information available, might be only in CVS)

Mail_Mime::setHTMLBody() — set HTML part

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefboolean setHTMLBody()/funcdef paramdefstring $data /paramdef paramdefboolean $isfile = FALSE /paramdef /funcprototype /funcsynopsis

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()

Mail_Mime::headers()
Mail_Mime::setTxtBody()
Mail_Mime


set plain text part

Mail_Mime::setHTMLBody()
Mail_mimePart::Mail_mimePart()
Mail_Mime
PHP Manual

Mail_Mime::setTxtBody()

(No version information available, might be only in CVS)

Mail_Mime::setTxtBody() — set plain text part

funcsynopsis funcsynopsisinfo require_once 'Mail/mime.php'; /funcsynopsisinfo funcprototype funcdefboolean setTxtBody()/funcdef paramdefstring $data /paramdef paramdefboolean $isfile = FALSE /paramdef /funcprototype /funcsynopsis

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()

Mail_Mime::setHTMLBody()
Mail_mimePart::Mail_mimePart()
Mail_Mime


constructor

Mail_Mime::setTxtBody()
Mail_mimePart::addsubpart()
Mail_Mime
PHP Manual

Mail_mimePart::Mail_mimePart()

(No version information available, might be only in CVS)

Mail_mimePart::Mail_mimePart() — constructor

funcsynopsis funcsynopsisinfo require_once 'Mail/mimePart.php'; /funcsynopsisinfo funcprototype funcdefMail_mimePart Mail_mimePart()/funcdef paramdefstring $body = '' /paramdef paramdefarray $params = array() /paramdef /funcprototype /funcsynopsis

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.

Mail_Mime::setTxtBody()
Mail_mimePart::addsubpart()
Mail_Mime


add sub part to a MIME part

Mail_mimePart::Mail_mimePart()
Mail_mimePart::encode()
Mail_Mime
PHP Manual

Mail_mimePart::addsubpart()

(No version information available, might be only in CVS)

Mail_mimePart::addsubpart() — add sub part to a MIME part

funcsynopsis funcsynopsisinfo require_once 'Mail/mimePart.php'; /funcsynopsisinfo funcprototype funcdefresource &addSubPart()/funcdef paramdefstring $body /paramdef paramdefarray $params /paramdef /funcprototype /funcsynopsis

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

Example #1 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';

...
?>
Mail_mimePart::Mail_mimePart()
Mail_mimePart::encode()
Mail_Mime


encode a mail

Mail_mimePart::addsubpart()
Mail_mimeDecode::Mail_mimeDecode()
Mail_Mime
PHP Manual

Mail_mimePart::encode()

(No version information available, might be only in CVS)

Mail_mimePart::encode() — encode a mail

funcsynopsis funcsynopsisinfo require_once 'Mail/mimePart.php'; /funcsynopsisinfo funcprototype funcdefarray encode()/funcdef paramdef /funcprototype /funcsynopsis

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.

Mail_mimePart::addsubpart()
Mail_mimeDecode::Mail_mimeDecode()
Mail_Mime


constructor

Mail_mimePart::encode()
Mail_mimeDecode::decode()
Mail_Mime
PHP Manual

Mail_mimeDecode::Mail_mimeDecode()

(No version information available, might be only in CVS)

Mail_mimeDecode::Mail_mimeDecode() — constructor

funcsynopsis funcsynopsisinfo require_once 'Mail/mimeDecode.php'; /funcsynopsisinfo funcprototype funcdefvoid Mail_mimeDecode()/funcdef paramdefstring $input /paramdef /funcprototype /funcsynopsis

Description

Create a new Mail_mimeDecode object.

Parameter

  • string $input - the input to decode

Note

This function can be called statically.

Mail_mimePart::encode()
Mail_mimeDecode::decode()
Mail_Mime


perform decoding

Mail_mimeDecode::Mail_mimeDecode()
Mail_mimeDecode::uudecode()
Mail_Mime
PHP Manual

Mail_mimeDecode::decode()

(No version information available, might be only in CVS)

Mail_mimeDecode::decode() — perform decoding

funcsynopsis funcsynopsisinfo require_once 'Mail/mimeDecode.php'; /funcsynopsisinfo funcprototype funcdefobject decode()/funcdef paramdefarray $args = NULL /paramdef /funcprototype /funcsynopsis

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.

Mail_mimeDecode::Mail_mimeDecode()
Mail_mimeDecode::uudecode()
Mail_Mime


decode of UU-coded data

Mail_mimeDecode::decode()
Mail_mimeDecode::getXML()
Mail_Mime
PHP Manual

Mail_mimeDecode::uudecode()

(No version information available, might be only in CVS)

Mail_mimeDecode::uudecode() — decode of UU-coded data

funcsynopsis funcsynopsisinfo require_once 'Mail/mimeDecode.php'; /funcsynopsisinfo funcprototype funcdefarray &uudecode()/funcdef paramdefstring $input /paramdef /funcprototype /funcsynopsis

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.

Mail_mimeDecode::decode()
Mail_mimeDecode::getXML()
Mail_Mime


create XML representation of MIME parts

Mail_Mime
Mail_Queue
Mail_Mime
PHP Manual

Mail_mimeDecode::getXML()

(No version information available, might be only in CVS)

Mail_mimeDecode::getXML() — create XML representation of MIME parts

funcsynopsis funcsynopsisinfo require_once 'Mail/mimeDecode.php'; /funcsynopsisinfo funcprototype funcdefstring getXML()/funcdef paramdefarray $decoded /paramdef /funcprototype /funcsynopsis

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

Example #1 Create a XML representation

...
$output = $obj->decode();
$xml    = Mail_mimeDecode::getXML($output);
...
Mail_Mime
Mail_Queue
Mail_Mime


Mail_Queue

Mail
Class Summary Mail_Queue
Mail


Mail_Queue
Tutorial
Mail_Queue
PHP Manual

Class Summary Mail_Queue

(No version information available, might be only in CVS)

Class Summary — 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

Mail_Queue
Tutorial
Mail_Queue


A tutorial for Mail_Queue

Class Summary Mail_Queue
constructor Mail_Queue::Mail_Queue
Mail_Queue
PHP Manual

Tutorial

(No version information available, might be only in CVS)

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:

Example #1 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. Lets call it config.php

Example #2 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:

Example #3 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 );

?>

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:

Example #4 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:

Example #5 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);
}
?>

Class Summary Mail_Queue
constructor Mail_Queue::Mail_Queue
Mail_Queue


Mail_Queue constructor

Tutorial
Mail_Queue::deleteMail
Mail_Queue
PHP Manual

constructor Mail_Queue::Mail_Queue()

(No version information available, might be only in CVS)

constructor — Mail_Queue constructor

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefmixed constructor Mail_Queue::Mail_Queue()/funcdef paramdefarray $container_options /paramdef paramdefarray $mail_options /paramdef /funcprototype /funcsynopsis

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.

Tutorial
Mail_Queue::deleteMail
Mail_Queue


Delete a mail from queue.

constructor Mail_Queue::Mail_Queue
Mail_Queue::factorySendMail
Mail_Queue
PHP Manual

Mail_Queue::deleteMail()

(No version information available, might be only in CVS)

— Delete a mail from queue.

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefboolean Mail_Queue::deleteMail()/funcdef paramdefinteger $id /paramdef /funcprototype /funcsynopsis

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.

constructor Mail_Queue::Mail_Queue
Mail_Queue::factorySendMail
Mail_Queue


Creates the necessary Mail object.

Mail_Queue::deleteMail
Mail_Queue::get
Mail_Queue
PHP Manual

Mail_Queue::factorySendMail()

(No version information available, might be only in CVS)

— Creates the necessary Mail object.

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefvoid Mail_Queue::factorySendMail()/funcdef paramdef /funcprototype /funcsynopsis

Description

Creates the necessary Mail object.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Mail_Queue::deleteMail
Mail_Queue::get
Mail_Queue


Get next mail from queue.

Mail_Queue::factorySendMail
Mail_Queue::put
Mail_Queue
PHP Manual

Mail_Queue::get()

(No version information available, might be only in CVS)

— Get next mail from queue.

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefobject Mail_Queue_Container::get()/funcdef paramdef /funcprototype /funcsynopsis

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.

Mail_Queue::factorySendMail
Mail_Queue::put
Mail_Queue


Put a new mail into queue.

Mail_Queue::get
Mail_Queue::sendMail
Mail_Queue
PHP Manual

Mail_Queue::put()

(No version information available, might be only in CVS)

— Put a new mail into queue.

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefint Mail_Queue::put()/funcdef paramdefstring $from /paramdef paramdefstring $to /paramdef paramdefarray $hdrs /paramdef paramdefarray $body /paramdef paramdefinteger $sec_to_send = 0 /paramdef paramdefbool $delete_after_send = TRUE /paramdef paramdefinteger $id_user = MAILQUEUE_SYSTEM /paramdef /funcprototype /funcsynopsis

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.

Mail_Queue::get
Mail_Queue::sendMail
Mail_Queue


Sends mail object returned by Mail_Queue::get()

Mail_Queue::put
Mail_Queue::sendMailById
Mail_Queue
PHP Manual

Mail_Queue::sendMail()

(No version information available, might be only in CVS)

— Sends mail object returned by Mail_Queue::get()

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefmixed Mail_Queue::sendMail()/funcdef paramdefobject MailBody $mail /paramdef /funcprototype /funcsynopsis

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.

Mail_Queue::put
Mail_Queue::sendMailById
Mail_Queue


Send a specific mail.

Mail_Queue::sendMail
Mail_Queue::sendMailsInQueue
Mail_Queue
PHP Manual

Mail_Queue::sendMailById()

(No version information available, might be only in CVS)

— Send a specific mail.

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefbool Mail_Queue::sendMailById()/funcdef paramdefinteger $id /paramdef /funcprototype /funcsynopsis

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.

Mail_Queue::sendMail
Mail_Queue::sendMailsInQueue
Mail_Queue


Send mails from queue.

Mail_Queue
Math
Mail_Queue
PHP Manual

Mail_Queue::sendMailsInQueue()

(No version information available, might be only in CVS)

— Send mails from queue.

funcsynopsis funcsynopsisinfo require_once 'Mail/Queue.php'; /funcsynopsisinfo funcprototype funcdefmixed Mail_Queue::sendMailsInQueue()/funcdef paramdefinteger $limit = MAILQUEUE_ALL /paramdef paramdefinteger $offset = MAILQUEUE_START /paramdef paramdefinteger $try = MAILQUEUE_TRY /paramdef /funcprototype /funcsynopsis

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.

Mail_Queue
Math
Mail_Queue


Math

Table of Contents

  • Math_Complex
  • Math_TrigOp

Provides Packages for mathematical purposes

Mail_Queue::sendMailsInQueue
Math_Complex
Packages


Math_Complex

Math
Class Summary Math_Complex
Math


Math_Complex
constructor Math_Complex::Math_Complex
Math_Complex
PHP Manual

Class Summary Math_Complex

(No version information available, might be only in CVS)

Class Summary — 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

Math_Complex
constructor Math_Complex::Math_Complex
Math_Complex


Constructor for Math_Complex

Class Summary Math_Complex
Math_Complex::abs
Math_Complex
PHP Manual

constructor Math_Complex::Math_Complex()

(No version information available, might be only in CVS)

constructor — Constructor for Math_Complex

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef object Math_Complex constructor Math_Complex::Math_Complex() /funcdef paramdef float $real /paramdef paramdef float $im /paramdef /funcprototype /funcsynopsis

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.

Class Summary Math_Complex
Math_Complex::abs
Math_Complex


Returns the magnitude (also referred as norm) of the number

constructor Math_Complex::Math_Complex
Math_Complex::abs2
Math_Complex
PHP Manual

Math_Complex::abs()

(No version information available, might be only in CVS)

— Returns the magnitude (also referred as norm) of the number

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef float Math_Complex::abs() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

constructor Math_Complex::Math_Complex
Math_Complex::abs2
Math_Complex


Returns the square of the magnitude of the number

Math_Complex::abs
Math_Complex::angle
Math_Complex
PHP Manual

Math_Complex::abs2()

(No version information available, might be only in CVS)

— Returns the square of the magnitude of the number

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef float Math_Complex::abs2() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Math_Complex::abs
Math_Complex::angle
Math_Complex


Returns the angle (argument) associated with the complex number Alias of Math_Complex::arg()

Math_Complex::abs2
Math_Complex::arg
Math_Complex
PHP Manual

Math_Complex::angle()

(No version information available, might be only in CVS)

— Returns the angle (argument) associated with the complex number Alias of Math_Complex::arg()

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef mixed Math_Complex::angle() /funcdef paramdef /funcprototype /funcsynopsis

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.

Math_Complex::abs2
Math_Complex::arg
Math_Complex


Returns the argument of the complex number

Math_Complex::angle
Math_Complex::getIm
Math_Complex
PHP Manual

Math_Complex::arg()

(No version information available, might be only in CVS)

— Returns the argument of the complex number

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef float|PEAR_Error Math_Complex::arg() /funcdef paramdef /funcprototype /funcsynopsis

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.

Math_Complex::angle
Math_Complex::getIm
Math_Complex


Returns the imaginary part of the complex number

Math_Complex::arg
Math_Complex::getReal
Math_Complex
PHP Manual

Math_Complex::getIm()

(No version information available, might be only in CVS)

— Returns the imaginary part of the complex number

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef float Math_Complex::getIm() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Math_Complex::arg
Math_Complex::getReal
Math_Complex


Returns the real part of the complex number

Math_Complex::getIm
Math_Complex::norm
Math_Complex
PHP Manual

Math_Complex::getReal()

(No version information available, might be only in CVS)

— Returns the real part of the complex number

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef float Math_Complex::getReal() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Math_Complex::getIm
Math_Complex::norm
Math_Complex


Returns the norm of the number Alias of Math_Complex::abs()

Math_Complex::getReal
Math_Complex::toString
Math_Complex
PHP Manual

Math_Complex::norm()

(No version information available, might be only in CVS)

— Returns the norm of the number Alias of Math_Complex::abs()

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef float Math_Complex::norm() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Math_Complex::getReal
Math_Complex::toString
Math_Complex


Simple string representation of the number

Math_Complex::norm
Class Summary Math_ComplexOp
Math_Complex
PHP Manual

Math_Complex::toString()

(No version information available, might be only in CVS)

— Simple string representation of the number

funcsynopsis funcsynopsisinforequire_once '/Complex.php';/funcsynopsisinfo funcprototype funcdef string Math_Complex::toString() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Math_Complex::norm
Class Summary Math_ComplexOp
Math_Complex


Math_Complex::toString
Math_ComplexOp::acos
Math_Complex
PHP Manual

Class Summary Math_ComplexOp

(No version information available, might be only in CVS)

Class Summary — 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

Math_Complex::toString
Math_ComplexOp::acos
Math_Complex


Calculates the inverse cosine of a complex number: z = acos(c1)

Class Summary Math_ComplexOp
Math_ComplexOp::acosh
Math_Complex
PHP Manual

Math_ComplexOp::acos()

(No version information available, might be only in CVS)

— Calculates the inverse cosine of a complex number: z = acos(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::acos() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Class Summary Math_ComplexOp
Math_ComplexOp::acosh
Math_Complex


Calculates the inverse hyperbolic cosine of a complex number: z = acosh(c1)

Math_ComplexOp::acos
Math_ComplexOp::acot
Math_Complex
PHP Manual

Math_ComplexOp::acosh()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic cosine of a complex number: z = acosh(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::acosh() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::acos
Math_ComplexOp::acot
Math_Complex


Calculates the inverse cotangent of a complex number: z = acot(c1)

Math_ComplexOp::acosh
Math_ComplexOp::acoth
Math_Complex
PHP Manual

Math_ComplexOp::acot()

(No version information available, might be only in CVS)

— Calculates the inverse cotangent of a complex number: z = acot(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::acot() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::acosh
Math_ComplexOp::acoth
Math_Complex


Calculates the inverse hyperbolic cotangent of a complex number: z = acoth(c1)

Math_ComplexOp::acot
Math_ComplexOp::acsc
Math_Complex
PHP Manual

Math_ComplexOp::acoth()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic cotangent of a complex number: z = acoth(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::acoth() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::acot
Math_ComplexOp::acsc
Math_Complex


Calculates the inverse cosecant of a complex number: z = acsc(c1)

Math_ComplexOp::acoth
Math_ComplexOp::acsch
Math_Complex
PHP Manual

Math_ComplexOp::acsc()

(No version information available, might be only in CVS)

— Calculates the inverse cosecant of a complex number: z = acsc(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::acsc() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::acoth
Math_ComplexOp::acsch
Math_Complex


Calculates the inverse hyperbolic cosecant of a complex number: z = acsch(c1)

Math_ComplexOp::acsc
Math_ComplexOp::add
Math_Complex
PHP Manual

Math_ComplexOp::acsch()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic cosecant of a complex number: z = acsch(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::acsch() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::acsc
Math_ComplexOp::add
Math_Complex


Returns the sum of two complex numbers: z = c1 + c2

Math_ComplexOp::acsch
Math_ComplexOp::areEqual
Math_Complex
PHP Manual

Math_ComplexOp::add()

(No version information available, might be only in CVS)

— Returns the sum of two complex numbers: z = c1 + c2

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::add() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::acsch
Math_ComplexOp::areEqual
Math_Complex


Determines if is c1 == c2:

Math_ComplexOp::add
Math_ComplexOp::asec
Math_Complex
PHP Manual

Math_ComplexOp::areEqual()

(No version information available, might be only in CVS)

— Determines if is c1 == c2:

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef boolean|PEAR_Error& Math_ComplexOp::areEqual() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::add
Math_ComplexOp::asec
Math_Complex


Calculates the inverse secant of a complex number: z = asec(c1)

Math_ComplexOp::areEqual
Math_ComplexOp::asech
Math_Complex
PHP Manual

Math_ComplexOp::asec()

(No version information available, might be only in CVS)

— Calculates the inverse secant of a complex number: z = asec(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::asec() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::areEqual
Math_ComplexOp::asech
Math_Complex


Calculates the inverse hyperbolic secant of a complex number: z = asech(c1)

Math_ComplexOp::asec
Math_ComplexOp::asin
Math_Complex
PHP Manual

Math_ComplexOp::asech()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic secant of a complex number: z = asech(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::asech() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::asec
Math_ComplexOp::asin
Math_Complex


Calculates the inverse sine of a complex number: z = asin(c1)

Math_ComplexOp::asech
Math_ComplexOp::asinAlt
Math_Complex
PHP Manual

Math_ComplexOp::asin()

(No version information available, might be only in CVS)

— Calculates the inverse sine of a complex number: z = asin(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::asin() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::asech
Math_ComplexOp::asinAlt
Math_Complex


Calculates the inverse sine of a complex number: z = asinAlt(c1) Uses an alternative algorithm

Math_ComplexOp::asin
Math_ComplexOp::asinh
Math_Complex
PHP Manual

Math_ComplexOp::asinAlt()

(No version information available, might be only in CVS)

— Calculates the inverse sine of a complex number: z = asinAlt(c1) Uses an alternative algorithm

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::asinAlt() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::asin
Math_ComplexOp::asinh
Math_Complex


Calculates the inverse hyperbolic sine of a complex number: z = asinh(c1)

Math_ComplexOp::asinAlt
Math_ComplexOp::asinReal
Math_Complex
PHP Manual

Math_ComplexOp::asinh()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic sine of a complex number: z = asinh(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::asinh() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::asinAlt
Math_ComplexOp::asinReal
Math_Complex


Calculates the complex inverse sine of a real number: z = asinReal(r):

Math_ComplexOp::asinh
Math_ComplexOp::atan
Math_Complex
PHP Manual

Math_ComplexOp::asinReal()

(No version information available, might be only in CVS)

— Calculates the complex inverse sine of a real number: z = asinReal(r):

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex & Math_ComplexOp::asinReal() /funcdef paramdef float $r /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

float $r

Throws

No exceptions thrown.

Note

This function can be called statically.

Math_ComplexOp::asinh
Math_ComplexOp::atan
Math_Complex


Calculates the inverse tangent of a complex number: z = atan(c1):

Math_ComplexOp::asinReal
Math_ComplexOp::atanh
Math_Complex
PHP Manual

Math_ComplexOp::atan()

(No version information available, might be only in CVS)

— Calculates the inverse tangent of a complex number: z = atan(c1):

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::atan() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::asinReal
Math_ComplexOp::atanh
Math_Complex


Calculates the inverse hyperbolic tangent of a complex number: z = atanh(c1)

Math_ComplexOp::atan
Math_ComplexOp::conjugate
Math_Complex
PHP Manual

Math_ComplexOp::atanh()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic tangent of a complex number: z = atanh(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::atanh() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::atan
Math_ComplexOp::conjugate
Math_Complex


Calculates the conjugate of a complex number: z = conj(c1)

Math_ComplexOp::atanh
Math_ComplexOp::cos
Math_Complex
PHP Manual

Math_ComplexOp::conjugate()

(No version information available, might be only in CVS)

— Calculates the conjugate of a complex number: z = conj(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::conjugate() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::atanh
Math_ComplexOp::cos
Math_Complex


Calculates the cosine of a complex number: z = cos(c1)

Math_ComplexOp::conjugate
Math_ComplexOp::cosh
Math_Complex
PHP Manual

Math_ComplexOp::cos()

(No version information available, might be only in CVS)

— Calculates the cosine of a complex number: z = cos(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::cos() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::conjugate
Math_ComplexOp::cosh
Math_Complex


Calculates the hyperbolic cosine of a complex number: z = cosh(c1)

Math_ComplexOp::cos
Math_ComplexOp::cot
Math_Complex
PHP Manual

Math_ComplexOp::cosh()

(No version information available, might be only in CVS)

— Calculates the hyperbolic cosine of a complex number: z = cosh(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::cosh() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::cos
Math_ComplexOp::cot
Math_Complex


Calculates the cotangent of a complex number: z = cot(c1)

Math_ComplexOp::cosh
Math_ComplexOp::coth
Math_Complex
PHP Manual

Math_ComplexOp::cot()

(No version information available, might be only in CVS)

— Calculates the cotangent of a complex number: z = cot(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::cot() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::cosh
Math_ComplexOp::coth
Math_Complex


Calculates the hyperbolic cotangent of a complex number: z = coth(c1)

Math_ComplexOp::cot
Math_ComplexOp::createFromPolar
Math_Complex
PHP Manual

Math_ComplexOp::coth()

(No version information available, might be only in CVS)

— Calculates the hyperbolic cotangent of a complex number: z = coth(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::coth() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::cot
Math_ComplexOp::createFromPolar
Math_Complex


Converts a polar complex z = r*exp(theta*i) to z = a + b*i

Math_ComplexOp::coth
Math_ComplexOp::csc
Math_Complex
PHP Manual

Math_ComplexOp::createFromPolar()

(No version information available, might be only in CVS)

— Converts a polar complex z = r*exp(theta*i) to z = a + b*i

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex & Math_ComplexOp::createFromPolar() /funcdef paramdef float $r /paramdef paramdef float $theta /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

float $r

float $theta

Throws

No exceptions thrown.

Note

This function can be called statically.

Math_ComplexOp::coth
Math_ComplexOp::csc
Math_Complex


Calculates the cosecant of a complex number: z = csc(c1)

Math_ComplexOp::createFromPolar
Math_ComplexOp::csch
Math_Complex
PHP Manual

Math_ComplexOp::csc()

(No version information available, might be only in CVS)

— Calculates the cosecant of a complex number: z = csc(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::csc() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::createFromPolar
Math_ComplexOp::csch
Math_Complex


Calculates the hyperbolic cosecant of a complex number: z = csch(c1)

Math_ComplexOp::csc
Math_ComplexOp::div
Math_Complex
PHP Manual

Math_ComplexOp::csch()

(No version information available, might be only in CVS)

— Calculates the hyperbolic cosecant of a complex number: z = csch(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::csch() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::csc
Math_ComplexOp::div
Math_Complex


Returns the division of two complex numbers: z = c1 * c2

Math_ComplexOp::csch
Math_ComplexOp::exp
Math_Complex
PHP Manual

Math_ComplexOp::div()

(No version information available, might be only in CVS)

— Returns the division of two complex numbers: z = c1 * c2

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::div() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::csch
Math_ComplexOp::exp
Math_Complex


Calculates the exponential of a complex number: z = exp(c1)

Math_ComplexOp::div
Math_ComplexOp::inverse
Math_Complex
PHP Manual

Math_ComplexOp::exp()

(No version information available, might be only in CVS)

— Calculates the exponential of a complex number: z = exp(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::exp() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::div
Math_ComplexOp::inverse
Math_Complex


Calculates the inverse of a complex number: z = 1/c1

Math_ComplexOp::exp
Math_ComplexOp::isComplex
Math_Complex
PHP Manual

Math_ComplexOp::inverse()

(No version information available, might be only in CVS)

— Calculates the inverse of a complex number: z = 1/c1

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::inverse() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::exp
Math_ComplexOp::isComplex
Math_Complex


Checks if a given object is an instance of PEAR::Math_Complex

Math_ComplexOp::inverse
Math_ComplexOp::log
Math_Complex
PHP Manual

Math_ComplexOp::isComplex()

(No version information available, might be only in CVS)

— Checks if a given object is an instance of PEAR::Math_Complex

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef boolean Math_ComplexOp::isComplex() /funcdef paramdef mixed &$c1 /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

mixed &$c1

Throws

No exceptions thrown.

Note

This function can be called statically.

Math_ComplexOp::inverse
Math_ComplexOp::log
Math_Complex


Calculates the logarithm (base 2) of a complex number: z = log(c1)

Math_ComplexOp::isComplex
Math_ComplexOp::log10
Math_Complex
PHP Manual

Math_ComplexOp::log()

(No version information available, might be only in CVS)

— Calculates the logarithm (base 2) of a complex number: z = log(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::log() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::isComplex
Math_ComplexOp::log10
Math_Complex


Calculates the logarithm (base 10) of a complex number: z = log10(c1)

Math_ComplexOp::log
Math_ComplexOp::logBase
Math_Complex
PHP Manual

Math_ComplexOp::log10()

(No version information available, might be only in CVS)

— Calculates the logarithm (base 10) of a complex number: z = log10(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::log10() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::log
Math_ComplexOp::logBase
Math_Complex


Returns the logarithm of base c2 of the complex number c1

Math_ComplexOp::log10
Math_ComplexOp::mult
Math_Complex
PHP Manual

Math_ComplexOp::logBase()

(No version information available, might be only in CVS)

— Returns the logarithm of base c2 of the complex number c1

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::logBase() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::log10
Math_ComplexOp::mult
Math_Complex


Returns the product of two complex numbers: z = c1 * c2

Math_ComplexOp::logBase
Math_ComplexOp::multIm
Math_Complex
PHP Manual

Math_ComplexOp::mult()

(No version information available, might be only in CVS)

— Returns the product of two complex numbers: z = c1 * c2

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::mult() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::logBase
Math_ComplexOp::multIm
Math_Complex


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::mult
Math_ComplexOp::multReal
Math_Complex
PHP Manual

Math_ComplexOp::multIm()

(No version information available, might be only in CVS)

— 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)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::multIm() /funcdef paramdef Math_Complex $c1 /paramdef paramdef float $im /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::mult
Math_ComplexOp::multReal
Math_Complex


Multiplies a complex number by a real number: z = realnumber * c1

Math_ComplexOp::multIm
Math_ComplexOp::negative
Math_Complex
PHP Manual

Math_ComplexOp::multReal()

(No version information available, might be only in CVS)

— Multiplies a complex number by a real number: z = realnumber * c1

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::multReal() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef float $real /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::multIm
Math_ComplexOp::negative
Math_Complex


Calculates the negative of a complex number: z = -c1

Math_ComplexOp::multReal
Math_ComplexOp::pow
Math_Complex
PHP Manual

Math_ComplexOp::negative()

(No version information available, might be only in CVS)

— Calculates the negative of a complex number: z = -c1

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::negative() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::multReal
Math_ComplexOp::pow
Math_Complex


Returns the complex power of two complex numbers: z = c1^c2

Math_ComplexOp::negative
Math_ComplexOp::powReal
Math_Complex
PHP Manual

Math_ComplexOp::pow()

(No version information available, might be only in CVS)

— Returns the complex power of two complex numbers: z = c1^c2

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::pow() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::negative
Math_ComplexOp::powReal
Math_Complex


Returns the exponentiation of a complex numbers to a real power: z = c1^(real)

Math_ComplexOp::pow
Math_ComplexOp::sec
Math_Complex
PHP Manual

Math_ComplexOp::powReal()

(No version information available, might be only in CVS)

— Returns the exponentiation of a complex numbers to a real power: z = c1^(real)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::powReal() /funcdef paramdef Math_Complex $c1 /paramdef paramdef float $real /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::pow
Math_ComplexOp::sec
Math_Complex


Calculates the secant of a complex number: z = sec(c1)

Math_ComplexOp::powReal
Math_ComplexOp::sech
Math_Complex
PHP Manual

Math_ComplexOp::sec()

(No version information available, might be only in CVS)

— Calculates the secant of a complex number: z = sec(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::sec() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::powReal
Math_ComplexOp::sech
Math_Complex


Calculates the hyperbolic secant of a complex number: z = sech(c1)

Math_ComplexOp::sec
Math_ComplexOp::sin
Math_Complex
PHP Manual

Math_ComplexOp::sech()

(No version information available, might be only in CVS)

— Calculates the hyperbolic secant of a complex number: z = sech(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::sech() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::sec
Math_ComplexOp::sin
Math_Complex


Calculates the sine of a complex number: z = sin(c1)

Math_ComplexOp::sech
Math_ComplexOp::sinh
Math_Complex
PHP Manual

Math_ComplexOp::sin()

(No version information available, might be only in CVS)

— Calculates the sine of a complex number: z = sin(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::sin() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::sech
Math_ComplexOp::sinh
Math_Complex


Calculates the hyperbolic sine of a complex number: z = sinh(c1)

Math_ComplexOp::sin
Math_ComplexOp::sqrt
Math_Complex
PHP Manual

Math_ComplexOp::sinh()

(No version information available, might be only in CVS)

— Calculates the hyperbolic sine of a complex number: z = sinh(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::sinh() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::sin
Math_ComplexOp::sqrt
Math_Complex


Calculates the complex square root of a complex number: z = sqrt(c1)

Math_ComplexOp::sinh
Math_ComplexOp::sqrtReal
Math_Complex
PHP Manual

Math_ComplexOp::sqrt()

(No version information available, might be only in CVS)

— Calculates the complex square root of a complex number: z = sqrt(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::sqrt() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::sinh
Math_ComplexOp::sqrtReal
Math_Complex


Calculates the complex square root of a real number: z = sqrt(realnumber)

Math_ComplexOp::sqrt
Math_ComplexOp::sub
Math_Complex
PHP Manual

Math_ComplexOp::sqrtReal()

(No version information available, might be only in CVS)

— Calculates the complex square root of a real number: z = sqrt(realnumber)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex & Math_ComplexOp::sqrtReal() /funcdef paramdef float $realnum /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

float $realnum

A float

Throws

No exceptions thrown.

Note

This function can be called statically.

Math_ComplexOp::sqrt
Math_ComplexOp::sub
Math_Complex


Returns the difference of two complex numbers: z = c1 - c2

Math_ComplexOp::sqrtReal
Math_ComplexOp::tan
Math_Complex
PHP Manual

Math_ComplexOp::sub()

(No version information available, might be only in CVS)

— Returns the difference of two complex numbers: z = c1 - c2

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::sub() /funcdef paramdef Math_Complex &$c1 /paramdef paramdef Math_Complex &$c2 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::sqrtReal
Math_ComplexOp::tan
Math_Complex


Calculates the tangent of a complex number: z = tan(c1)

Math_ComplexOp::sub
Math_ComplexOp::tanh
Math_Complex
PHP Manual

Math_ComplexOp::tan()

(No version information available, might be only in CVS)

— Calculates the tangent of a complex number: z = tan(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::tan() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_ComplexOp::sub
Math_ComplexOp::tanh
Math_Complex


Calculates the hyperbolic tangent of a complex number: z = tanh(c1)

Math_Complex
Math_TrigOp
Math_Complex
PHP Manual

Math_ComplexOp::tanh()

(No version information available, might be only in CVS)

— Calculates the hyperbolic tangent of a complex number: z = tanh(c1)

funcsynopsis funcsynopsisinforequire_once '/ComplexOp.php';/funcsynopsisinfo funcprototype funcdef Math_Complex |PEAR_Error & Math_ComplexOp::tanh() /funcdef paramdef Math_Complex &$c1 /paramdef /funcprototype /funcsynopsis

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.

Math_Complex
Math_TrigOp
Math_Complex


Math_TrigOp

Math
Math_TrigOp::acoth
Math


Calculates the inverse hyperbolic cotangent of the parameter

Math_TrigOp
Math_TrigOp::acsch
Math_TrigOp
PHP Manual

Math_TrigOp::acoth()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic cotangent of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::acoth()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp
Math_TrigOp::acsch
Math_TrigOp


Calculates the inverse hyperbolic cosecant of the parameter

Math_TrigOp::acoth
Math_TrigOp::asech
Math_TrigOp
PHP Manual

Math_TrigOp::acsch()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic cosecant of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::acsch()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::acoth
Math_TrigOp::asech
Math_TrigOp


Calculates the inverse hyperbolic secant of the parameter

Math_TrigOp::acsch
Math_TrigOp::cot
Math_TrigOp
PHP Manual

Math_TrigOp::asech()

(No version information available, might be only in CVS)

— Calculates the inverse hyperbolic secant of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::asech()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::acsch
Math_TrigOp::cot
Math_TrigOp


Calculates the cotangent of the parameter

Math_TrigOp::asech
Math_TrigOp::coth
Math_TrigOp
PHP Manual

Math_TrigOp::cot()

(No version information available, might be only in CVS)

— Calculates the cotangent of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::cot()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::asech
Math_TrigOp::coth
Math_TrigOp


Calculates the hyperbolic cotangent of the parameter

Math_TrigOp::cot
Math_TrigOp::csc
Math_TrigOp
PHP Manual

Math_TrigOp::coth()

(No version information available, might be only in CVS)

— Calculates the hyperbolic cotangent of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::coth()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::cot
Math_TrigOp::csc
Math_TrigOp


Calculates the cosecant of the parameter

Math_TrigOp::coth
Math_TrigOp::csch
Math_TrigOp
PHP Manual

Math_TrigOp::csc()

(No version information available, might be only in CVS)

— Calculates the cosecant of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::csc()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::coth
Math_TrigOp::csch
Math_TrigOp


Calculates the hyperbolic cosecant of the parameter

Math_TrigOp::csc
Math_TrigOp::sec
Math_TrigOp
PHP Manual

Math_TrigOp::csch()

(No version information available, might be only in CVS)

— Calculates the hyperbolic cosecant of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::csch()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::csc
Math_TrigOp::sec
Math_TrigOp


Calculates the secant of the parameter

Math_TrigOp::csch
Math_TrigOp::sech
Math_TrigOp
PHP Manual

Math_TrigOp::sec()

(No version information available, might be only in CVS)

— Calculates the secant of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::sec()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp::csch
Math_TrigOp::sech
Math_TrigOp


Calculates the hyperbolic secant of the parameter

Math_TrigOp
Networking
Math_TrigOp
PHP Manual

Math_TrigOp::sech()

(No version information available, might be only in CVS)

— Calculates the hyperbolic secant of the parameter

funcsynopsis funcsynopsisinfo require_once 'TrigOp.php'; /funcsynopsisinfo funcprototype funcdefmixed Math_TrigOp::sech()/funcdef paramdeffloat $x /paramdef /funcprototype /funcsynopsis

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.

Math_TrigOp
Networking
Math_TrigOp


Networking

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_MAC
  • Net_URL
  • Net_NNTP
  • Net_Ping
  • Net_POP3
  • Net_Portscan
  • Net_Server
  • Net_SmartIrc
  • Net_SMTP
  • Net_Socket
  • Net_Traceroute
  • Net_Whois
  • Net_Wifi
  • URI_Template

Provides Packages for network-related working

Math_TrigOp::sech
Net_CheckIP
Packages


Net_CheckIP

Package to check the correct syntax of an IPv4 address.

Networking
Net_CheckIP::check_ip()
Networking


Validation of IPv4 addresses

Net_CheckIP
Net_DNS
Net_CheckIP
PHP Manual

Net_CheckIP::check_ip()

(No version information available, might be only in CVS)

Net_CheckIP::check_ip() — Validation of IPv4 addresses

funcsynopsis funcsynopsisinfo require_once 'Net/CheckIP.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_CheckIP::check_ip()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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

Example #1 Using check_ip()

require_once "Net_CheckIP/CheckIP.php";

if (Net_CheckIP::check_ip("your_ip_goes_here")) {
    // Syntax of the IP is ok
}
Net_CheckIP
Net_DNS
Net_CheckIP


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.

Net_CheckIP::check_ip()
Introduction
Networking


General purpose DNS querying and packet parsing

Net_DNS
Class Summary Net_DNS
Net_DNS
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Net_DNS
Class Summary Net_DNS
Net_DNS


Introduction
Class Summary Net_DNS_Resolver
Net_DNS
PHP Manual

Class Summary Net_DNS

(No version information available, might be only in CVS)

Class Summary — 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().

Introduction
Class Summary Net_DNS_Resolver
Net_DNS


Provides a resolver implementation to handle DNS queries

Class Summary Net_DNS
Net_DNS_Resolver::query()
Net_DNS
PHP Manual

Class Summary Net_DNS_Resolver

(No version information available, might be only in CVS)

Class Summary — 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.

Class Summary Net_DNS
Net_DNS_Resolver::query()
Net_DNS


Queries a nameserver and returns a response

Class Summary Net_DNS_Resolver
Net_DNS_Resolver::rawQuery()
Net_DNS
PHP Manual

Net_DNS_Resolver::query()

(No version information available, might be only in CVS)

Net_DNS_Resolver::query() — Queries a nameserver and returns a response

funcsynopsis funcsynopsisinfo require_once('Net/DNS.php'); /funcsynopsisinfo funcprototype funcdefNet_DNS_Packet Net_DNS_Resolver::query()/funcdef paramdefstring $hostname /paramdef paramdefstring $type = 'A' /paramdef paramdefstring $class = 'IN' /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Example #2 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.

Example #3 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.

Class Summary Net_DNS_Resolver
Net_DNS_Resolver::rawQuery()
Net_DNS


Queries a nameserver and returns a response

Net_DNS_Resolver::query()
Net_DNS_Resolver::axfr()
Net_DNS
PHP Manual

Net_DNS_Resolver::rawQuery()

(No version information available, might be only in CVS)

Net_DNS_Resolver::rawQuery() — Queries a nameserver and returns a response

funcsynopsis funcsynopsisinfo require_once('Net/DNS.php'); /funcsynopsisinfo funcprototype funcdefNet_DNS_Packet Net_DNS_Resolver::rawQuery()/funcdef paramdefstring $hostname /paramdef paramdefstring $type = 'A' /paramdef paramdefstring $class = 'IN' /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Net_DNS_Resolver::query()
Net_DNS_Resolver::axfr()
Net_DNS


Performs a zone transfer from a nameserver

Net_DNS_Resolver::rawQuery()
Class Summary Net_DNS_Packet
Net_DNS
PHP Manual

Net_DNS_Resolver::axfr()

(No version information available, might be only in CVS)

Net_DNS_Resolver::axfr() — Performs a zone transfer from a nameserver

funcsynopsis funcsynopsisinfo require_once('Net/DNS.php'); /funcsynopsisinfo funcprototype funcdefNet_DNS_Packet Net_DNS_Resolver::axfr()/funcdef paramdefstring $dname /paramdef paramdefstring $class = 'IN' /paramdef paramdefboolean $old = FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Example #2 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.

Net_DNS_Resolver::rawQuery()
Class Summary Net_DNS_Packet
Net_DNS


Provides an object abstraction of a DNS packet

Net_DNS_Resolver::axfr()
Class Summary Net_DNS_RR
Net_DNS
PHP Manual

Class Summary Net_DNS_Packet

(No version information available, might be only in CVS)

Class Summary — 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.

Net_DNS_Resolver::axfr()
Class Summary Net_DNS_RR
Net_DNS


Provides resource record parsing and creation

Class Summary Net_DNS_Packet
Examples -- DNS Updates
Net_DNS
PHP Manual

Class Summary Net_DNS_RR

(No version information available, might be only in CVS)

Class Summary — 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

Class Summary Net_DNS_Packet
Examples -- DNS Updates
Net_DNS


Net_DNS
Net_DNSBL
Net_DNS
PHP Manual

Examples -- DNS Updates

(No version information available, might be only in CVS)

Examples -- — 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.

Example #1 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);

}

?>
Net_DNS
Net_DNSBL
Net_DNS


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)

Examples -- DNS Updates
Introduction
Networking


Introduction to Net_DNSBL

Net_DNSBL
Net_Finger
Net_DNSBL
PHP Manual

Introduction

(No version information available, might be only in CVS)

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($addData['url'])) {
    // 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']);
}
?>

Net_DNSBL
Net_Finger
Net_DNSBL


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.

Introduction
Net_Finger::query()
Networking


does a finger query

Net_Finger
Net_FTP
Net_Finger
PHP Manual

Net_Finger::query()

(No version information available, might be only in CVS)

Net_Finger::query() — does a finger query

funcsynopsis funcsynopsisinfo require_once 'Net/Finger.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Finger::query() /funcdef paramdef string $server /paramdef paramdef string $query /paramdef /funcprototype /funcsynopsis

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

Example #1 Using query()

<?php

$server = "localhost" ; // or IP adress to use
$query  = "ralph" ;     // Username to look up

$data = Net_Finger::query( $server, $query) ;
echo $data ;

?>
Net_Finger
Net_FTP
Net_Finger


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.

Net_Finger::query()
Constants
Networking


predefined constants

Net_FTP
Net_FTP::Net_FTP()
Net_FTP
PHP Manual

Constants

(No version information available, might be only in CVS)

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().

Net_FTP
Net_FTP::Net_FTP()
Net_FTP


constructor

Constants
Net_FTP::connect()
Net_FTP
PHP Manual

Net_FTP::Net_FTP()

(No version information available, might be only in CVS)

Net_FTP::Net_FTP() — constructor

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefobject Net_FTP::Net_FTP()/funcdef paramdef string $host = null /paramdef paramdef int $port = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using Net_FTP()

<?php

  require_once 'Net/FTP.php';

  $test = new Net_FTP('ftp.mydomain.com', 21);

?>
Constants
Net_FTP::connect()
Net_FTP


connects to a given FTP server

Net_FTP::Net_FTP()
Net_FTP::disconnect()
Net_FTP
PHP Manual

Net_FTP::connect()

(No version information available, might be only in CVS)

Net_FTP::connect() — connects to a given FTP server

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::connect()/funcdef paramdef string $host = null /paramdef paramdef int $port = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using connect()

<?php

    $test->connect('192.168.0.1', 21);

?>
Net_FTP::Net_FTP()
Net_FTP::disconnect()
Net_FTP


disconnects from the FTP server

Net_FTP::connect()
Net_FTP::login()
Net_FTP
PHP Manual

Net_FTP::disconnect()

(No version information available, might be only in CVS)

Net_FTP::disconnect() — disconnects from the FTP server

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_FTP::disconnect()/funcdef paramdef /funcprototype /funcsynopsis

Description

Disconnect from the FTP server you're connected to.

Return value

void

Note

This function can not be called statically.

Example

Example #1 Using disconnect()

<?php

    $test->disconnect();

?>
Net_FTP::connect()
Net_FTP::login()
Net_FTP


logs into the FTP server you are connected to

Net_FTP::disconnect()
Net_FTP::cd()
Net_FTP
PHP Manual

Net_FTP::login()

(No version information available, might be only in CVS)

Net_FTP::login() — logs into the FTP server you are connected to

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::login()/funcdef paramdef string $username = null /paramdef paramdef int $password = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using login()

<?php

    $test->login('myuser', 'mypass');

?>
Net_FTP::disconnect()
Net_FTP::cd()
Net_FTP


changes the directory on the server.

Net_FTP::login()
Net_FTP::pwd()
Net_FTP
PHP Manual

Net_FTP::cd()

(No version information available, might be only in CVS)

Net_FTP::cd() — changes the directory on the server.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::cd()/funcdef paramdef string $directory /paramdef /funcprototype /funcsynopsis

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

Example #1 Using cd()

<?php

    $test->cd('../mydir');

?>
Net_FTP::login()
Net_FTP::pwd()
Net_FTP


returns the directory on the server you are currently in.

Net_FTP::cd()
Net_FTP::mkdir()
Net_FTP
PHP Manual

Net_FTP::pwd()

(No version information available, might be only in CVS)

Net_FTP::pwd() — returns the directory on the server you are currently in.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::pwd()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using pwd()

<?php

  echo $test->pwd();

?>
Net_FTP::cd()
Net_FTP::mkdir()
Net_FTP


creates a new directory.

Net_FTP::pwd()
Net_FTP::execute()
Net_FTP
PHP Manual

Net_FTP::mkdir()

(No version information available, might be only in CVS)

Net_FTP::mkdir() — creates a new directory.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::mkdir()/funcdef paramdef string $directory /paramdef paramdef bool $recursive = false /paramdef /funcprototype /funcsynopsis

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

Example #1 Using mkdir()

<?php

  $test->mkdir('../mydir');

?>
Net_FTP::pwd()
Net_FTP::execute()
Net_FTP


executes a command on the server.

Net_FTP::mkdir()
Net_FTP::mdtm()
Net_FTP
PHP Manual

Net_FTP::execute()

(No version information available, might be only in CVS)

Net_FTP::execute() — executes a command on the server.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::execute()/funcdef paramdef string $command /paramdef /funcprototype /funcsynopsis

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

Example #1 Using execute()

<?php

    $test->execute($myCommand);

?>
Net_FTP::mkdir()
Net_FTP::mdtm()
Net_FTP


returns the last modification date of a file.

Net_FTP::execute()
Net_FTP::size()
Net_FTP
PHP Manual

Net_FTP::mdtm()

(No version information available, might be only in CVS)

Net_FTP::mdtm() — returns the last modification date of a file.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::mdtm()/funcdef paramdef string $file /paramdef paramdef string $format = null /paramdef /funcprototype /funcsynopsis

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

Example #1 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'));

?>
Net_FTP::execute()
Net_FTP::size()
Net_FTP


returns the size in bytes of a file.

Net_FTP::mdtm()
Net_FTP::ls()
Net_FTP
PHP Manual

Net_FTP::size()

(No version information available, might be only in CVS)

Net_FTP::size() — returns the size in bytes of a file.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::size()/funcdef paramdef string $file /paramdef /funcprototype /funcsynopsis

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

Example #1 Using size()

<?php

    var_dump($test->size('/foo/bar'));

?>
Net_FTP::mdtm()
Net_FTP::ls()
Net_FTP


returns the listing of a directory in a specified way.

Net_FTP::size()
Net_FTP::rm()
Net_FTP
PHP Manual

Net_FTP::ls()

(No version information available, might be only in CVS)

Net_FTP::ls() — returns the listing of a directory in a specified way.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::ls()/funcdef paramdef string $dir = null /paramdef paramdef string $mode = NET_FTP_DIRS_FILES /paramdef /funcprototype /funcsynopsis

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 = NET_FTP_DIRS_FILES - 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

Example #1 Using ls()

<?php

  var_dump($test->ls('/foo/bar'));

?>
Net_FTP::size()
Net_FTP::rm()
Net_FTP


deletes a file or directory.

Net_FTP::ls()
Net_FTP::get()
Net_FTP
PHP Manual

Net_FTP::rm()

(No version information available, might be only in CVS)

Net_FTP::rm() — deletes a file or directory.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::rm()/funcdef paramdef string $path = null /paramdef paramdef string $recursive = false /paramdef /funcprototype /funcsynopsis

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

Example #1 Using rm()

<?php

    var_dump($test->rm('/foo/bar/', true));

?>
Net_FTP::ls()
Net_FTP::get()
Net_FTP


download a file to the computer your script runs on.

Net_FTP::rm()
Net_FTP::put()
Net_FTP
PHP Manual

Net_FTP::get()

(No version information available, might be only in CVS)

Net_FTP::get() — download a file to the computer your script runs on.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::get()/funcdef paramdef string $remote_file /paramdef paramdef string $local_file /paramdef paramdef bool $overwrite = false /paramdef paramdef int $mode = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using get()

<?php

    var_dump($test->get('foo/bar.zip', '/tmp/downloaded.zip', true, FTP_BINARY));

?>
Net_FTP::rm()
Net_FTP::put()
Net_FTP


upload a file to the FTP server.

Net_FTP::get()
Net_FTP::getRecursive()
Net_FTP
PHP Manual

Net_FTP::put()

(No version information available, might be only in CVS)

Net_FTP::put() — upload a file to the FTP server.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::put()/funcdef paramdef string $local_file /paramdef paramdef string $remote_file /paramdef paramdef bool $overwrite = false /paramdef paramdef int $mode = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using put()

<?php

  var_dump($test->put('/tmp/downloaded.zip', 'foo/bar.zip', true, FTP_BINARY));

?>
Net_FTP::get()
Net_FTP::getRecursive()
Net_FTP


download a whole directory to the computer your script runs on.

Net_FTP::put()
Net_FTP::putRecursive()
Net_FTP
PHP Manual

Net_FTP::getRecursive()

(No version information available, might be only in CVS)

Net_FTP::getRecursive() — download a whole directory to the computer your script runs on.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::getRecursive()/funcdef paramdef string $remote_path /paramdef paramdef string $local_path /paramdef paramdef bool $overwrite = false /paramdef paramdef int $mode = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getRecursive()

<?php

    var_dump($test->getRecursive('foo/', '/tmp/foo/', true));

?>
Net_FTP::put()
Net_FTP::putRecursive()
Net_FTP


upload a whole directory to the FTP server.

Net_FTP::getRecursive()
Net_FTP::checkFileExtension()
Net_FTP
PHP Manual

Net_FTP::putRecursive()

(No version information available, might be only in CVS)

Net_FTP::putRecursive() — upload a whole directory to the FTP server.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_FTP::putrecursive()/funcdef paramdef string $local_path /paramdef paramdef string $remote_path /paramdef paramdef bool $overwrite = false /paramdef paramdef int $mode = null /paramdef /funcprototype /funcsynopsis

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

Example #1 Using putRecursive()

<?php

  var_dump($test->putRecursive('/tmp/foo/', 'foo/', true));

?>
Net_FTP::getRecursive()
Net_FTP::checkFileExtension()
Net_FTP


check extensions.ini for the transfermode of a specific file.

Net_FTP
Net_GameServerQuery
Net_FTP
PHP Manual

Net_FTP::checkFileExtension()

(No version information available, might be only in CVS)

Net_FTP::checkFileExtension() — check extensions.ini for the transfermode of a specific file.

funcsynopsis funcsynopsisinfo require_once 'Net/FTP.php'; /funcsynopsisinfo funcprototype funcdefinteger Net_FTP::checkfileextension()/funcdef paramdef string $filename /paramdef /funcprototype /funcsynopsis

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

Example #1 Using checkFileExtension()

<?php

    var_dump($test->checkfileextension('foo/bar.zip'));

?>
Net_FTP
Net_GameServerQuery
Net_FTP


Net_GameServerQuery

An object for querying game servers and returning normalised output

Net_FTP::checkFileExtension()
Introduction
Networking


Provides a common API to query game servers

Net_GameServerQuery
Net_Geo
Net_GameServerQuery
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Net_GameServerQuery
Net_Geo
Net_GameServerQuery


Net_Geo

Package for polling Netgeo service retrieving the geographical location of IPs or addresses.

Introduction
Net_Geo - Example
Networking


tracking down the remote client IP

Net_Geo
Net_Geo::Net_Geo()
Net_Geo
PHP Manual

Net_Geo - Example

(No version information available, might be only in CVS)

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>";

?>
Net_Geo
Net_Geo::Net_Geo()
Net_Geo


constructor

Net_Geo - Example
Net_Geo::getRecord()
Net_Geo
PHP Manual

Net_Geo::Net_Geo()

(No version information available, might be only in CVS)

Net_Geo::Net_Geo() — constructor

funcsynopsis funcsynopsisinfo require_once('Net/Geo.php'); /funcsynopsisinfo funcprototype funcdefbool Net_Geo()()/funcdef paramdefstring $applicationName = '' /paramdef paramdefstring $alternateServerUrl = '' /paramdef /funcprototype /funcsynopsis

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.

Net_Geo - Example
Net_Geo::getRecord()
Net_Geo


get geographical information about IP

Net_Geo
Net_GeoIP
Net_Geo
PHP Manual

Net_Geo::getRecord()

(No version information available, might be only in CVS)

Net_Geo::getRecord() — get geographical information about IP

funcsynopsis funcsynopsisinfo require_once('Net/Geo.php'); /funcsynopsisinfo funcprototype funcdefarray getRecord()()/funcdef paramdefmixed $target /paramdef /funcprototype /funcsynopsis

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.

Net_Geo
Net_GeoIP
Net_Geo


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.

Net_Geo::getRecord()
Net_GeoIP::getInstance()
Networking


method to get an instance and avoid re-parsing the database

Net_GeoIP
Net_GeoIP::lookupCountryName()
Net_GeoIP
PHP Manual

Net_GeoIP::getInstance()

(No version information available, might be only in CVS)

Net_GeoIP::getInstance() — method to get an instance and avoid re-parsing the database

funcsynopsis funcsynopsisinfo require_once "Net/GeoIP.php"; /funcsynopsisinfo funcprototype funcdefobject getInstance()()/funcdef paramdef string $filename [, int $flags ] /paramdef /funcprototype /funcsynopsis

Description

This method is an implementation of the so-called singleton pattern and is the preferred way to create instances of Net_GeoIP.

Example #1 Creating an instance of Net_GeoIP

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.

Net_GeoIP
Net_GeoIP::lookupCountryName()
Net_GeoIP


returns full country name for specified IP address

Net_GeoIP::getInstance()
Net_GeoIP::lookupCountryCode()
Net_GeoIP
PHP Manual

Net_GeoIP::lookupCountryName()

(No version information available, might be only in CVS)

Net_GeoIP::lookupCountryName() — returns full country name for specified IP address

funcsynopsis funcsynopsisinfo require_once "Net/GeoIP.php"; /funcsynopsisinfo funcprototype funcdefstring lookupCountryName()()/funcdef paramdef string $addr /paramdef /funcprototype /funcsynopsis

Description

This method returns the full country name for the given IP address. It works with both the free and the non-free databases.

Example #1 Looking up the country name

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:

    $geoip->lookupCountryName(gethostbyname("example.com"));
    Or, if you don't know whether an address is a name or IP address, use application-level logic:
    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.

Net_GeoIP::getInstance()
Net_GeoIP::lookupCountryCode()
Net_GeoIP


returns 2-letter country code (e.g. CA) for specified IP address

Net_GeoIP::lookupCountryName()
Net_GeoIP::lookupRegion()
Net_GeoIP
PHP Manual

Net_GeoIP::lookupCountryCode()

(No version information available, might be only in CVS)

Net_GeoIP::lookupCountryCode() — returns 2-letter country code (e.g. "CA") for specified IP address

funcsynopsis funcsynopsisinfo require_once "Net/GeoIP.php"; /funcsynopsisinfo funcprototype funcdefstring lookupCountryCode()()/funcdef paramdef string $addr /paramdef /funcprototype /funcsynopsis

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.

Example #1 Looking up the country code

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.

Net_GeoIP::lookupCountryName()
Net_GeoIP::lookupRegion()
Net_GeoIP


returns the region for given IP address.

Net_GeoIP::lookupCountryCode()
Net_GeoIP::lookupLocation()
Net_GeoIP
PHP Manual

Net_GeoIP::lookupRegion()

(No version information available, might be only in CVS)

Net_GeoIP::lookupRegion() — returns the region for given IP address.

funcsynopsis funcsynopsisinfo require_once "Net/GeoIP.php"; /funcsynopsisinfo funcprototype funcdefarray lookupRegion()()/funcdef paramdef string $addr /paramdef /funcprototype /funcsynopsis

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.

Example #1 Looking up the region

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.

Net_GeoIP::lookupCountryCode()
Net_GeoIP::lookupLocation()
Net_GeoIP


returns the location record for specified IP address

Net_GeoIP::lookupRegion()
Net_GeoIP::lookupOrg()
Net_GeoIP
PHP Manual

Net_GeoIP::lookupLocation()

(No version information available, might be only in CVS)

Net_GeoIP::lookupLocation() — returns the location record for specified IP address

funcsynopsis funcsynopsisinfo require_once "Net/GeoIP.php"; /funcsynopsisinfo funcprototype funcdefobject lookupLocation()()/funcdef paramdef string $addr /paramdef /funcprototype /funcsynopsis

Description

This method returns an instance of Net_GeoIP_Location for the specified IP address. It works only with a non-free City database.

Example #1 Looking up the location record

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.

Net_GeoIP::lookupRegion()
Net_GeoIP::lookupOrg()
Net_GeoIP


returns the name of the organization or ISP for the given IP address.

Net_GeoIP
Net_IPv4
Net_GeoIP
PHP Manual

Net_GeoIP::lookupOrg()

(No version information available, might be only in CVS)

Net_GeoIP::lookupOrg() — returns the name of the organization or ISP for the given IP address.

funcsynopsis funcsynopsisinfo require_once "Net/GeoIP.php"; /funcsynopsisinfo funcprototype funcdefstring lookupOrg()()/funcdef paramdef string $addr /paramdef /funcprototype /funcsynopsis

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.

Example #1 Looking up organization name

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.

Net_GeoIP
Net_IPv4
Net_GeoIP


Net_IPv4

Provides several methods for working with IP addresses and netmasks.

Net_GeoIP::lookupOrg()
Net_IPv4::atoh()
Networking


Converts a dot-quad formatted IP address into a hexadecimal string

Net_IPv4
Net_IPv4::htoa()
Net_IPv4
PHP Manual

Net_IPv4::atoh()

(No version information available, might be only in CVS)

Net_IPv4::atoh() — Converts a dot-quad formatted IP address into a hexadecimal string

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdefmixed atoh()/funcdef paramdefstring $addr /paramdef /funcprototype /funcsynopsis

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.

Net_IPv4
Net_IPv4::htoa()
Net_IPv4


Converts a hexadecimal string into a dot-quad formatted IP address

Net_IPv4::atoh()
Net_IPv4::ip2double()
Net_IPv4
PHP Manual

Net_IPv4::htoa()

(No version information available, might be only in CVS)

Net_IPv4::htoa() — Converts a hexadecimal string into a dot-quad formatted IP address

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdefmixed htoa()/funcdef paramdefstring $addr /paramdef /funcprototype /funcsynopsis

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.

Net_IPv4::atoh()
Net_IPv4::ip2double()
Net_IPv4


Converts an IP address to a PHP double.

Net_IPv4::htoa()
Net_IPv4::validateIP()
Net_IPv4
PHP Manual

Net_IPv4::ip2double()

(No version information available, might be only in CVS)

Net_IPv4::ip2double() — Converts an IP address to a PHP double.

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdeffloat ip2double()/funcdef paramdefstring $ip_addr /paramdef /funcprototype /funcsynopsis

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.

Net_IPv4::htoa()
Net_IPv4::validateIP()
Net_IPv4


Validate the syntax of the given IP adress.

Net_IPv4::ip2double()
Net_IPv4::validateNetmask()
Net_IPv4
PHP Manual

Net_IPv4::validateIP()

(No version information available, might be only in CVS)

Net_IPv4::validateIP() — Validate the syntax of the given IP adress.

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdefbool validateIP()/funcdef paramdefstring $ip_addr /paramdef /funcprototype /funcsynopsis

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.

Net_IPv4::ip2double()
Net_IPv4::validateNetmask()
Net_IPv4


Validate the syntax of the given netmask.

Net_IPv4::validateIP()
Net_IPv4::parseAddress()
Net_IPv4
PHP Manual

Net_IPv4::validateNetmask()

(No version information available, might be only in CVS)

Net_IPv4::validateNetmask() — Validate the syntax of the given netmask.

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdefbool validateNetmask()/funcdef paramdefstring $netmask /paramdef /funcprototype /funcsynopsis

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.

Net_IPv4::validateIP()
Net_IPv4::parseAddress()
Net_IPv4


Parse a CIDR address (address/netmask combination).

Net_IPv4::validateNetmask()
Net_IPv4::calculate()
Net_IPv4
PHP Manual

Net_IPv4::parseAddress()

(No version information available, might be only in CVS)

Net_IPv4::parseAddress() — Parse a CIDR address (address/netmask combination).

funcsynopsis funcsynopsisinfo require_once('Net/IPv4.php'); /funcsynopsisinfo funcprototype funcdefbool parseAddress()/funcdef paramdefstring $address /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Net_IPv4::validateNetmask()
Net_IPv4::calculate()
Net_IPv4


Calculates network information based on an IP address and netmask.

Net_IPv4::parseAddress()
Net_IPv4::ipInNetwork()
Net_IPv4
PHP Manual

Net_IPv4::calculate()

(No version information available, might be only in CVS)

Net_IPv4::calculate() — Calculates network information based on an IP address and netmask.

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdefmixed calculate()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Net_IPv4::parseAddress()
Net_IPv4::ipInNetwork()
Net_IPv4


Determines whether or not the supplied IP is within the supplied network.

Net_IPv4
Net_IPv6
Net_IPv4
PHP Manual

Net_IPv4::ipInNetwork()

(No version information available, might be only in CVS)

Net_IPv4::ipInNetwork() — Determines whether or not the supplied IP is within the supplied network.

funcsynopsis funcsynopsisinfo require_once 'Net/IPv4.php'; /funcsynopsisinfo funcprototype funcdefbool validateIP()/funcdef paramdefstring $ip_addr /paramdef paramdefstring $cidr_block /paramdef /funcprototype /funcsynopsis

Description

Determines whether or not the supplied IP address is within the supplied network.

Example

Example #1 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.

Net_IPv4
Net_IPv6
Net_IPv4


Net_IPv6

Provides function to work with the 'Internet Protocol v6'

Net_IPv4::ipInNetwork()
Net_IPv6::checkIPv6()
Networking


Validation of IPv6 addresses

Net_IPv6
Net_IPv6::compress()
Net_IPv6
PHP Manual

Net_IPv6::checkIPv6()

(No version information available, might be only in CVS)

Net_IPv6::checkIPv6() — Validation of IPv6 addresses

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_IPv6::checkIPv6()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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.

Net_IPv6
Net_IPv6::compress()
Net_IPv6


compress an IPv6 address

Net_IPv6::checkIPv6()
Net_IPv6::uncompress()
Net_IPv6
PHP Manual

Net_IPv6::compress()

(No version information available, might be only in CVS)

Net_IPv6::compress() — compress an IPv6 address

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefstring Net_IPv6::compress()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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.

Net_IPv6::checkIPv6()
Net_IPv6::uncompress()
Net_IPv6


Uncompresses an IPv6 address

Net_IPv6::compress()
Net_IPv6::getAddressType()
Net_IPv6
PHP Manual

Net_IPv6::uncompress()

(No version information available, might be only in CVS)

Net_IPv6::uncompress() — Uncompresses an IPv6 address

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefstring Net_IPv6::uncompress()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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.

Net_IPv6::compress()
Net_IPv6::getAddressType()
Net_IPv6


Returns the type of an IP address

Net_IPv6::uncompress()
Net_IPv6::getNetmask()
Net_IPv6
PHP Manual

Net_IPv6::getAddressType()

(No version information available, might be only in CVS)

Net_IPv6::getAddressType() — Returns the type of an IP address

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefint Net_IPv6::getAddressType()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Net_IPv6::uncompress()
Net_IPv6::getNetmask()
Net_IPv6


Calculates the network prefix

Net_IPv6::getAddressType()
Net_IPv6::isInNetmask()
Net_IPv6
PHP Manual

Net_IPv6::getNetmask()

(No version information available, might be only in CVS)

Net_IPv6::getNetmask() — Calculates the network prefix

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefstring Net_IPv6::getNetmask()/funcdef paramdefstring $ip /paramdef paramdefint $bits = null /paramdef /funcprototype /funcsynopsis

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

Net_IPv6::getAddressType()
Net_IPv6::isInNetmask()
Net_IPv6


Checks if an IP is in a specific address space

Net_IPv6::getNetmask()
Net_IPv6::removeNetmaskSpec()
Net_IPv6
PHP Manual

Net_IPv6::isInNetmask()

(No version information available, might be only in CVS)

Net_IPv6::isInNetmask() — Checks if an IP is in a specific address space

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_IPv6::isInNetmask()/funcdef paramdefstring $ip /paramdef paramdefstring $netmask /paramdef paramdefint $bits = null /paramdef /funcprototype /funcsynopsis

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

Net_IPv6::getNetmask()
Net_IPv6::removeNetmaskSpec()
Net_IPv6


Removes the Netmask length specification

Net_IPv6::isInNetmask()
Net_IPv6::splitV64()
Net_IPv6
PHP Manual

Net_IPv6::removeNetmaskSpec()

(No version information available, might be only in CVS)

Net_IPv6::removeNetmaskSpec() — Removes the Netmask length specification

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefstring Net_IPv6::removeNetmaskSpec()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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

Net_IPv6::isInNetmask()
Net_IPv6::splitV64()
Net_IPv6


splits an IPv6 address in it IPv6 and IPv4 part

Net_IPv6
Net_LDAP
Net_IPv6
PHP Manual

Net_IPv6::splitV64()

(No version information available, might be only in CVS)

Net_IPv6::splitV64() — splits an IPv6 address in it IPv6 and IPv4 part

funcsynopsis funcsynopsisinfo require_once 'Net/IPv6.php'; /funcsynopsisinfo funcprototype funcdefarray Net_IPv6::splitV64()/funcdef paramdefstring $ip /paramdef /funcprototype /funcsynopsis

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.

Net_IPv6
Net_LDAP
Net_IPv6


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/

Net_IPv6::splitV64()
Introduction
Networking


What Net_LDAP is and general information

Net_LDAP
Error handling
Net_LDAP
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.
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.

Net_LDAP
Error handling
Net_LDAP


How handling errors works in Net_LDAP

Introduction
Configuration and connecting
Net_LDAP
PHP Manual

Error handling

(No version information available, might be only in CVS)

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.

Example #1 Dealing with errors

// 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
Introduction
Configuration and connecting
Net_LDAP


How to configure Net_LDAP and connect to an LDAP server

Error handling
Search
Net_LDAP
PHP Manual

Configuration and connecting

(No version information available, might be only in CVS)

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 | (objectClass=*)
scope | Default search scope, see Search | sub

Example #1 Connecting to an LDAP server

// 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());
}
Error handling
Search
Net_LDAP


Searching entries

Configuration and connecting
Fetching entries
Net_LDAP
PHP Manual

Search

(No version information available, might be only in CVS)

Search — Searching entries

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.

  • $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.

Example #1 Making a search query

// 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!";
Configuration and connecting
Fetching entries
Net_LDAP


Retrieving entries directly or from a searchresult

Search
Attributes
Net_LDAP
PHP Manual

Fetching entries

(No version information available, might be only in CVS)

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.

Example #1 Fetching an entry directly

// 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.

Example #2 Fetching all entries from searchresult

// return all entries:
$entry = $search->entries();

Example #3 Fetching all entries from searchresult: sorted

// return sorted by first 'sn' then 'gn', but descending:
$entry = $search->sorted(array('sn', 'gn'), SORT_DESC);

Example #4 Fetching entries one by one inside a while loop

// 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_LDAP_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.

Example #5 Fetching entries via foreach()

foreach ($search as $dn => $entry) {
    // do something:
    $sn = $entry->getValue('sn', 'single');
    echo "Fetched DN: $dn; Surname: $sn";
}
Search
Attributes
Net_LDAP


Reading/adding/changing/deleting attributes from entries

Fetching entries
Managing entries
Net_LDAP
PHP Manual

Attributes

(No version information available, might be only in CVS)

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)

Example #1 Reading attributes

// 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()

Example #2 Reading an entries DN

$dn = $entry->dn();

Regular expressions on attributes

PEAR::Net_LDAP features 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.

Example #3 Performing preg_match on attribute values

// 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.

Example #4 Adding attributes

// 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.

Example #5 Changing attributes

// 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.

Example #6 Deleting attributes

// 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')) );
Fetching entries
Managing entries
Net_LDAP


Adding/renaming/moving/deleting entries

Attributes
LDIF files
Net_LDAP
PHP Manual

Managing entries

(No version information available, might be only in CVS)

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.

Example #1 Adding a fresh entry

// 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.

Example #2 Moving an entry using Net_LDAP_Entry

// 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);

Example #3 Moving an entry using Net_LDAP and Net_LDAP_Entry

// 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);

Example #4 Renaming an entry using Net_LDAP and DNs

// 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);

Example #5 Performing a cross directory move

// $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.

Example #6 Deleting an entry

$dn  = 'cn=new-admin,o=example,dc=org';
$ldap->delete($dn);

Example #7 Deleting an entry using a Net_LDAP_Entry object

$entry->delete();
$entry->update();
Attributes
LDIF files
Net_LDAP


Converting between Net_LDAP_Entries and LDIF files

Net_LDAP
Net_MAC
Net_LDAP
PHP Manual

LDIF files

(No version information available, might be only in CVS)

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 #1 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 #2 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:

Example #3 Parsing a LDIF file into Net_LDAP_Entry objects

// 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.

Example #4 Writing entries

// 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.

Example #5 Writing entry changes

// 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.

Example #6 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.

Example #7 Reading LDIF lines

// 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();
Net_LDAP
Net_MAC
Net_LDAP


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.

LDIF files
Constants
Networking


Predefined Constants

Net_MAC
Net_MAC::check()
Net_MAC
PHP Manual

Constants

(No version information available, might be only in CVS)

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

Net_MAC
Net_MAC::check()
Net_MAC


Validates Media Access Control (MAC) addresses

Constants
Net_MAC::format()
Net_MAC
PHP Manual

Net_MAC::check()

(No version information available, might be only in CVS)

Net_MAC::check() — Validates Media Access Control (MAC) addresses

funcsynopsis funcsynopsisinfo require_once 'Net/MAC.php'; /funcsynopsisinfo funcprototype funcdefstring Net_MAC::check()/funcdef paramdefstring $input /paramdef paramdefstring $delimiter=':' /paramdef /funcprototype /funcsynopsis

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

Example #1 Using check()

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

Example #2 Using check() to get a MAC address with a different delimiter

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.

Constants
Net_MAC::format()
Net_MAC


Cleanly formats Media Access Control (MAC) addresses

Net_MAC::check()
Net_MAC::__construct()
Net_MAC
PHP Manual

Net_MAC::format()

(No version information available, might be only in CVS)

Net_MAC::format() — Cleanly formats Media Access Control (MAC) addresses

funcsynopsis funcsynopsisinfo require_once 'Net/MAC.php'; /funcsynopsisinfo funcprototype funcdefstring Net_MAC::format()/funcdef paramdefstring $input /paramdef paramdefstring $delimiter=':' /paramdef paramdefboolean $uppercase=TRUE /paramdef /funcprototype /funcsynopsis

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

Example #1 Using format()

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

Example #2 Using format() to get a MAC address with a different delimiter

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

Example #3 Using format() to get a MAC address with all capital alpha characters

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(),

Net_MAC::check()
Net_MAC::__construct()
Net_MAC


Constructor

Net_MAC::format()
setMAC()
Net_MAC
PHP Manual

Net_MAC::__construct()

(No version information available, might be only in CVS)

Net_MAC::__construct() — Constructor

funcsynopsis funcsynopsisinfo require_once 'Net/MAC.php'; /funcsynopsisinfo funcprototype funcdef Net_MAC::__construct()/funcdef paramdefobject $db /paramdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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

Example #1 Instantiating a Net_MAC object

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()

Net_MAC::format()
setMAC()
Net_MAC


Sets the MAC address in the object

Net_MAC::__construct()
importVendors()
Net_MAC
PHP Manual

setMAC()

(No version information available, might be only in CVS)

setMAC() — Sets the MAC address in the object

funcsynopsis funcsynopsisinfo require_once 'Net/MAC.php'; /funcsynopsisinfo funcprototype funcdefmixed setMAC()/funcdef paramdefstring $macaddr /paramdef paramdefstring $delimiter = ':' /paramdef /funcprototype /funcsynopsis

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

Example #1 Using setMAC()

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()

Net_MAC::__construct()
importVendors()
Net_MAC


Import a manufacturers' file to the database or to an array

setMAC()
findVendor()
Net_MAC
PHP Manual

importVendors()

(No version information available, might be only in CVS)

importVendors() — Import a manufacturers' file to the database or to an array

funcsynopsis funcsynopsisinfo require_once 'Net/MAC.php'; /funcsynopsisinfo funcprototype funcdefmixed importVendors()/funcdef paramdefstring $file /paramdef paramdefboolean $doReturn=FALSE /paramdef /funcprototype /funcsynopsis

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

Example #1 Using importVendors() with a URL

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.

Example #2 Using importVendors() with a file, returning an array

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()

setMAC()
findVendor()
Net_MAC


Finds the vendor of the MAC address stored in the object

importVendors()
Net_MAC_Exception
Net_MAC
PHP Manual

findVendor()

(No version information available, might be only in CVS)

findVendor() — Finds the vendor of the MAC address stored in the object

funcsynopsis funcsynopsisinfo require_once 'Net/MAC.php'; /funcsynopsisinfo funcprototype funcdefmixed findVendor()/funcdef paramdefstring $getDescription=FALSE /paramdef paramdefstring $macList=NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Using findVendor()

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()

importVendors()
Net_MAC_Exception
Net_MAC


Exception class for Net_MAC package

Net_MAC
Net_URL
Net_MAC
PHP Manual

Net_MAC_Exception

(No version information available, might be only in CVS)

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.

Net_MAC
Net_URL
Net_MAC


Net_URL

Provides an easy parsing of URLs

Net_MAC_Exception
Net_URL Instantiate
Networking


Instantiating Net_URL

Net_URL
Net_URL::setOption
Net_URL
PHP Manual

Net_URL Instantiate

(No version information available, might be only in CVS)

Net_URL Instantiate — Instantiating Net_URL

funcsynopsis funcsynopsisinfo require_once 'Net/URL.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Whois()/funcdef paramdefstring $url /paramdef paramdefstring $useBrackets /paramdef /funcprototype /funcsynopsis

Description

Instantiates a new Net_URL object

Parameter

  • string $url - The url to parse. By default this is getting $_SERVER['PHP_SELF']

  • string $useBrackets - Whether to use sqare brackets or not when there is multiple query variable names using the same name.

Example

Example #1 Using Net_URL

<?php
require_once 'Net/URL.php';
$url = new Net_URL;
print_r($url->querystring);
?>
Net_URL
Net_URL::setOption
Net_URL


Setting options with Net_URL

Net_URL
Net_NNTP
Net_URL
PHP Manual

Net_URL::setOption

(No version information available, might be only in CVS)

Net_URL::setOption — Setting options with Net_URL

funcsynopsis funcsynopsisinfo require_once 'Net/URL.php'; /funcsynopsisinfo funcprototype funcdefstring setOption()/funcdef paramdefstring $optionName /paramdef paramdefstring $value /paramdef /funcprototype /funcsynopsis

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

Example #1 Using Net_URL

<?php
require_once 'Net/URL.php';
$url = new Net_URL;
$url->setOption('encode_query_keys', true);
print_r($url->querystring);
?>
Net_URL
Net_NNTP
Net_URL


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.

Net_NNTP_Client

NNTP client implementation

Net_NNTP

Warning

This function is deprecated. That means that future versions of this package may not support it anymore.

The historical Net_NNTP class

Net_NNTP_Header

Warning

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.

Net_NNTP_Message

Warning

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.

Net_NNTP_Protocol_Client

Low level NNTP client implementation.

This package is not documented yet.

Net_URL::setOption
Constants
Networking


predefined constants

Net_URL::setOption
PHP Manual

Constants

(No version information available, might be only in CVS)

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

Net_URL::setOption


Authenticate

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: authenticate()

(PHP 4, PHP 5)

:: -- () — Authenticate

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()

Net_URL::setOption


Connects to a NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::connect()

(No version information available, might be only in CVS)

Net_NNTP_Client::connect() — Connects to a NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_NNTP_Client::connect()/funcdef paramdef string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST /paramdef paramdef integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT /paramdef /funcprototype /funcsynopsis

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

Example #1 Using connect()

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
}
Net_URL::setOption


Connect and authenticate to a NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::connectAuthenticated()

(No version information available, might be only in CVS)

Net_NNTP_Client::connectAuthenticated() — Connect and authenticate to a NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_NNTP_Client::connectAuthenticated()/funcdef paramdef integer $user = NULL /paramdef paramdef integer $pass = NULL /paramdef paramdef string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST /paramdef paramdef integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT /paramdef paramdef integer $authmode = NET_NNTP_AUTHORIGINAL /paramdef /funcprototype /funcsynopsis

Description

Connect and authenticate to a specific NNTP-server

Warning

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

Example #1 Using connectauthenticated()

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
}
Net_URL::setOption


Get the number of articles in the current newsgroup

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: count()

(PHP 4, PHP 5)

:: -- () — Get the number of articles in the current newsgroup

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

Example #1 Using count()

...
$nntp->selectGroup("php.pear.dev");
echo "number of articles: ".$nntp->count();
Net_URL::setOption


Net_NNTP_Client::getDescriptions()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: getDescriptions()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getDescriptions ( void )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Get the number of the first article in the current newsgroup

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: first()

(PHP 4, PHP 5)

:: -- () — Get the number of the first article in the current newsgroup

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

Example #1 Using first()

...
$nntp->selectGroup("php.pear.dev");
echo "lowest message number: ".$nntp->first();
Net_URL::setOption


Fetch an article from the NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getArticle()

(No version information available, might be only in CVS)

Net_NNTP_Client::getArticle() — Fetch an article from the NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_NNTP_Client::getArticle()/funcdef paramdef string $article /paramdef /funcprototype /funcsynopsis

Description

Warning

This function is currently not documented.

See

Net_NNTP_Client::getArticleRaw()

Net_URL::setOption


Fetch an article from the NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getArticleRaw()

(No version information available, might be only in CVS)

Net_NNTP_Client::getArticleRaw() — Fetch an article from the NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_NNTP_Client::getArticleRaw()/funcdef paramdef string $article /paramdef paramdef boolean $implode = false /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getArticleRaw()

...
$article = $nntp->getArticleRaw($msg_id);
if( PEAR::isError($article)) {
    // handle error
} else {
    // success
}
Net_URL::setOption


Net_NNTP_Client::getGroupArticles()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: getGroupArticles()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getGroupArticles ( string $$newsgroup )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Fetch the body of an article from the NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getBodyRaw()

(No version information available, might be only in CVS)

Net_NNTP_Client::getBodyRaw() — Fetch the body of an article from the NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_NNTP_Client::getBodyRaw()/funcdef paramdef string $article /paramdef paramdef boolean $implode = false /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getBodyRaw()

...

$body = $nntp->getBodyRaw($msgId);
if( PEAR::isError($body)) {
    // handle error
} else {
    // success - print body
    echo $body;
}
Net_URL::setOption


Get date from NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getDate()

(No version information available, might be only in CVS)

Net_NNTP_Client::getDate() — Get date from NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_NNTP_Client::getDate()/funcdef paramdef integer $format = 1 /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getDate()

...
$date = $nntp->getDate();
echo "Date: ".$date['m']."-".$date['d']."-".$date['y'];
Net_URL::setOption


Fetch list of avaible newsgroups

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getGroups()

(No version information available, might be only in CVS)

Net_NNTP_Client::getGroups() — Fetch list of avaible newsgroups

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP_Client::getGroups()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 Using getGroups()

...
$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>';
    }
}
Net_URL::setOption


Fetch the header of an article from the NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getHeader()

(No version information available, might be only in CVS)

Net_NNTP_Client::getHeader() — Fetch the header of an article from the NNTP-server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefobject Net_NNTP_Client::getHeader()/funcdef paramdef string $article /paramdef /funcprototype /funcsynopsis

Description

Warning

This function is currently not documented.

See

Net_NNTP_Client::getHeaderRaw()

Net_URL::setOption


fetch message header

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getHeaderRaw()

(No version information available, might be only in CVS)

Net_NNTP_Client::getHeaderRaw() — fetch message header

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP_Client::getHeaderRaw()/funcdef paramdef string $article /paramdef paramdef boolean $implode = false /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getHeaderRaw()

...

$headers = $nntp->getHeaderRaw($msgId);
if( PEAR::isError($headers)) {
    // handle error
} else {
    // success - split the string into a array
    $headersArray = explode( "\n", $headers);
}
Net_URL::setOption


Net_NNTP_Client::getNewGroups()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: getNewGroups()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getNewGroups ( mixed $$time )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Net_NNTP_Client::getNewNews()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: getNewNews()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getNewNews ( mixed $$time [, string $$pass ] )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Fetch newsgroup overview

Net_URL::setOption
PHP Manual

Net_NNTP_Client::getOverview()

(No version information available, might be only in CVS)

Net_NNTP_Client::getOverview() — Fetch newsgroup overview

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP_Client::getOverview()/funcdef paramdef string $first /paramdef paramdef string $last /paramdef /funcprototype /funcsynopsis

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

$msgs[message_id][headername] = headercontent

Note

This function can not be called statically.

Warning

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

Example #1 Using getOverview()

...
$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>';
 }
}
Net_URL::setOption


Net_NNTP_Client::getReferencesOverview()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: getReferencesOverview()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::getReferencesOverview ( integer $$first , integer $$last )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Net_NNTP_Client::group()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: group()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::group ( string $$user , string $$pass [, integer $$authmode = NET_NNTP_AUTHORIGINAL ] )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Connected?

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: isConnected()

(PHP 4, PHP 5)

:: -- () — Connected?

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::isConnected ( void )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Get the number of the last article in the current newsgroup

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: last()

(PHP 4, PHP 5)

:: -- () — Get the number of the last article in the current newsgroup

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

Example #1 Using last()

...
$nntp->selectGroup("php.pear.dev");
echo "highest message number: ".$nntp->last();
Net_URL::setOption


Net_NNTP_Client::post()

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: post()

(PHP 4, PHP 5)

:: -- () —

require_once 'Net/NNTP/Client.php';

public boolean Net_NNTP_Client::post ( string $$newsgroups , string $$subject , string $$body , string $$from [, integer $$additional = '' ] )
Warning

This method is currently not documented.

Warning

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

Net_URL::setOption


Close the connection to the NNTP-server

Net_URL::setOption
PHP Manual

Net_NNTP_Client:: quit()

(PHP 4, PHP 5)

:: -- () — Close the connection to the NNTP-server

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

Net_URL::setOption


select a newsgroup

Net_URL::setOption
PHP Manual

Net_NNTP_Client::selectGroup()

(No version information available, might be only in CVS)

Net_NNTP_Client::selectGroup() — select a newsgroup

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP/Client.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP_Client::selectGroup()/funcdef paramdef string $newsgroup /paramdef /funcprototype /funcsynopsis

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

Example #1 Using selectGroup()

...
$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'];
}
Net_URL::setOption


predefined constants

Net_URL::setOption
PHP Manual

Constants

(No version information available, might be only in CVS)

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)

Net_URL::setOption


send a command to a newsserver

Net_URL::setOption
PHP Manual

Net_NNTP::command()

(No version information available, might be only in CVS)

Net_NNTP::command() — send a command to a newsserver

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP::command()/funcdef paramdef string $cmd /paramdef paramdef boolean $auth /paramdef /funcprototype /funcsynopsis

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.

Warning

Command() does no checks on the given command and/ or proccesses the server response. So you should know what are you doing.

Example

Example #1 Using command()

...
$response = $nntp->command("ARTICLE 1004853");
Net_URL::setOption


Connects to a newsserver

Net_URL::setOption
PHP Manual

Net_NNTP::connect()

(No version information available, might be only in CVS)

Net_NNTP::connect() — Connects to a newsserver

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_NNTP::connect()/funcdef paramdefstring $host = NET_NNTP_PROTOCOL_DEFAULT_HOST /paramdef paramdef integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT /paramdef /funcprototype /funcsynopsis

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

Example #1 Using connect()

require_once "Net/NNTP.php";

$nntp = new Net_NNTP;
$ret = $nntp->connect("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
}
Net_URL::setOption


Connects and authenticates to a newsserver

Net_URL::setOption
PHP Manual

Net_NNTP::connectAuthenticated()

(No version information available, might be only in CVS)

Net_NNTP::connectAuthenticated() — Connects and authenticates to a newsserver

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_NNTP::connectAuthenticated()/funcdef paramdef integer $user = NULL /paramdef paramdef integer $pass = NULL /paramdef paramdef string $host = NET_NNTP_PROTOCOL_DEFAULT_HOST /paramdef paramdef integer $port = NET_NNTP_PROTOCOL_DEFAULT_PORT /paramdef paramdef integer $authmode = NET_NNTP_AUTHORIGINAL /paramdef /funcprototype /funcsynopsis

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

Example #1 Using connectauthenticated()

require_once "Net/NNTP.php";

$nntp = new Net_NNTP;
$ret = $nntp->connectAuthenticated("news.php.net");
if( PEAR::isError($ret)) {
 // handle error
} else {
 // success
}
Net_URL::setOption


get date from news server

Net_URL::setOption
PHP Manual

Net_NNTP::date()

(No version information available, might be only in CVS)

Net_NNTP::date() — get date from news server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::date()/funcdef paramdef /funcprototype /funcsynopsis

Description

Warning

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

Example #1 Using date()

...
$date = $nntp->date();
echo "Date: ".$date['m']."-".$date['d']."-".$date['y'];
Net_URL::setOption


get lowest message number

Net_URL::setOption
PHP Manual

Net_NNTP::first()

(No version information available, might be only in CVS)

Net_NNTP::first() — get lowest message number

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefinteger Net_NNTP::first()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 Using first()

...
$nntp->selectGroup("php.pear.dev");
echo "lowest message number: ".$nntp->first();
Net_URL::setOption


fetch an article from a new server

Net_URL::setOption
PHP Manual

Net_NNTP::getArticle()

(No version information available, might be only in CVS)

Net_NNTP::getArticle() — fetch an article from a new server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_NNTP::getArticle()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

Description

Returns the whole article from the current selected newsgroup

Warning

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

Example #1 Using getArticle()

...
$article = $nntp->getArticle($msg_id);
if( PEAR::isError($article)) {
 // handle error
} else {
 // success
}
Net_URL::setOption


fetch an article from a new server

Net_URL::setOption
PHP Manual

Net_NNTP::getArticleRaw()

(No version information available, might be only in CVS)

Net_NNTP::getArticleRaw() — fetch an article from a new server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_NNTP::getArticleRaw()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getArticleRaw()

...
$article = $nntp->getArticleRaw($msg_id);
if( PEAR::isError($article)) {
 // handle error
} else {
 // success
}
Net_URL::setOption


fetch the body of an article

Net_URL::setOption
PHP Manual

Net_NNTP::getBody()

(No version information available, might be only in CVS)

Net_NNTP::getBody() — fetch the body of an article

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP::getBody()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

Description

Returns the whole body of an article in the current selected newsgroup from the webserver

Warning

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

Example #1 Using getBody()

...

$body = $nntp->getBody($msgId);
if( PEAR::isError($body)) {
 // handle error
} else {
 // success - print body
 echo $body;
}
Net_URL::setOption


fetch the body of an article

Net_URL::setOption
PHP Manual

Net_NNTP::getBodyRaw()

(No version information available, might be only in CVS)

Net_NNTP::getBodyRaw() — fetch the body of an article

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP::getBodyRaw()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getBodyRaw()

...

$body = $nntp->getBodyRaw($msgId);
if( PEAR::isError($body)) {
 // handle error
} else {
 // success - print body
 echo $body;
}
Net_URL::setOption


get date from news server

Net_URL::setOption
PHP Manual

Net_NNTP::getDate()

(No version information available, might be only in CVS)

Net_NNTP::getDate() — get date from news server

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::getDate()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using getDate()

...
$date = $nntp->getDate();
echo "Date: ".$date['m']."-".$date['d']."-".$date['y'];
Net_URL::setOption


fetch list of avaible newsgroups

Net_URL::setOption
PHP Manual

Net_NNTP::getGroups()

(No version information available, might be only in CVS)

Net_NNTP::getGroups() — fetch list of avaible newsgroups

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::getGroups()/funcdef paramdef string $fetch = TRUE /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 Using getGroups()

...
$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>';
 }
}
Net_URL::setOption


fetch message header

Net_URL::setOption
PHP Manual

Net_NNTP::getHeaderRaw()

(No version information available, might be only in CVS)

Net_NNTP::getHeaderRaw() — fetch message header

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP::getHeaderRaw()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getHeaderRaw()

...

$headers = $nntp->getHeaderRaw($msgId);
if( PEAR::isError($headers)) {
 // handle error
} else {
 // success - split the string into a array
 $headersArray = explode( "\n", $headers);
}
Net_URL::setOption


fetch message headers

Net_URL::setOption
PHP Manual

Net_NNTP::getHeaders()

(No version information available, might be only in CVS)

Net_NNTP::getHeaders() — fetch message headers

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP::getHeaders()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

Description

Returns all avaible header lines of a specified message in the current selected newsgroup

Warning

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

Example #1 Using getHeaders()

...

$headers = $nntp->getHeaders($msgId);
if( PEAR::isError($headers)) {
 // handle error
} else {
 // success - split the string into a array
 $headersArray = explode( "\n", $headers);
}
Net_URL::setOption


fetch a number of message headers

Net_URL::setOption
PHP Manual

Net_NNTP::getOverview()

(No version information available, might be only in CVS)

Net_NNTP::getOverview() — fetch a number of message headers

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::getOverview()/funcdef paramdef string $first /paramdef paramdef string $last /paramdef /funcprototype /funcsynopsis

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

$msgs[message_id][headername] = headercontent

Note

This function can not be called statically.

Warning

Be careful with choosing the range. It could requires some time to get a huge number of message headers.

See

Net_NNTP::getOverviewFmt()

Example

Example #1 Using getOverview()

...
$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>';
 }
}
Net_URL::setOption


fetch the name of message headers

Net_URL::setOption
PHP Manual

Net_NNTP::getOverviewFmt()

(No version information available, might be only in CVS)

Net_NNTP::getOverviewFmt() — fetch the name of message headers

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::getOverviewFmt()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getOverviewFmt()

...
$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>';
Net_URL::setOption


fetch the name of message headers

Net_URL::setOption
PHP Manual

Net_NNTP::getOverviewFormat()

(No version information available, might be only in CVS)

Net_NNTP::getOverviewFormat() — fetch the name of message headers

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::getOverviewFormat()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 Using getOverviewFmt()

...
$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>';
Net_URL::setOption


check connection status

Net_URL::setOption
PHP Manual

Net_NNTP::isConnected()

(No version information available, might be only in CVS)

Net_NNTP::isConnected() — check connection status

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_NNTP::isConnected()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns the status of the connection

Return value

boolean - TRUE, if connected

Note

This function can not be called statically.

Example

Example #1 Using isConnected()

...
if(PEAR::isError($response)) {
    // something goes wrong, check if we are still connected
    if($nntp->isConnected()) {
        echo "disconnected from newsserver!"
        ...
    }
}
Net_URL::setOption


get highest message number

Net_URL::setOption
PHP Manual

Net_NNTP::last()

(No version information available, might be only in CVS)

Net_NNTP::last() — get highest message number

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefinteger Net_NNTP::last()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

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

Example #1 Using last()

...
$nntp->selectGroup("php.pear.dev");
echo "highest message number: ".$nntp->last();
Net_URL::setOption


get highest message number

Net_URL::setOption
PHP Manual

Net_NNTP::max()

(No version information available, might be only in CVS)

Net_NNTP::max() — get highest message number

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefinteger Net_NNTP::max()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

Warning

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

Example #1 Using max()

...
$nntp->selectGroup("php.pear.dev");
echo "highest message number: ".$nntp->max();
Net_URL::setOption


get lowest message number

Net_URL::setOption
PHP Manual

Net_NNTP::min()

(No version information available, might be only in CVS)

Net_NNTP::min() — get lowest message number

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefinteger Net_NNTP::min()/funcdef paramdef /paramdef /funcprototype /funcsynopsis

Description

Warning

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

Example #1 Using min()

...
$nntp->selectGroup("php.pear.dev");
echo "lowest message number: ".$nntp->min();
Net_URL::setOption


post a message

Net_URL::setOption
PHP Manual

Net_NNTP::post()

(No version information available, might be only in CVS)

Net_NNTP::post() — post a message

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefstring Net_NNTP::post()/funcdef paramdef string $subject /paramdef paramdef string $newsgroup /paramdef paramdef string $from /paramdef paramdef string $body /paramdef paramdef string $additional /paramdef /funcprototype /funcsynopsis

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.

Warning

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

Example #1 Using post()

...

$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);
...
Net_URL::setOption


connects to a newsgroup on a newsserver

Net_URL::setOption
PHP Manual

Net_NNTP::prepareConnection()

(No version information available, might be only in CVS)

Net_NNTP::prepareConnection() — connects to a newsgroup on a newsserver

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_NNTP::prepareConnection()/funcdef paramdefstring $nntpserver /paramdef paramdef integer $port = 119 /paramdef paramdef integer $newsgroup /paramdef paramdef integer $user = NULL /paramdef paramdef integer $pass = NULL /paramdef paramdef integer $authmode = PEAR_NNTP_ORIGINAL /paramdef /funcprototype /funcsynopsis

Description

Connect to a specific newsserver and access the given newsgroup

Warning

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.

Warning

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

Example #1 Using prepareConnection()

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
}
Net_URL::setOption


disconnect from a newsserver

Net_URL::setOption
PHP Manual

Net_NNTP::quit()

(No version information available, might be only in CVS)

Net_NNTP::quit() — disconnect from a newsserver

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_NNTP::quit()/funcdef paramdef /funcprototype /funcsynopsis

Description

Close connection to a newsserver

Note

This function can not be called statically.

See

Net_NNTP::connect(), Net_NNTP::prepareConnection()

Net_URL::setOption


select a newsgroup

Net_URL::setOption
PHP Manual

Net_NNTP::selectGroup()

(No version information available, might be only in CVS)

Net_NNTP::selectGroup() — select a newsgroup

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::selectGroup()/funcdef paramdef string $newsgroup /paramdef /funcprototype /funcsynopsis

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

Example #1 Using selectGroup()

...
$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'];
}
Net_URL::setOption


setting debug mode

Net_URL::setOption
PHP Manual

Net_NNTP::setDebug()

(No version information available, might be only in CVS)

Net_NNTP::setDebug() — setting debug mode

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_NNTP::setDebug()/funcdef paramdef boolean $on = TRUE /paramdef /funcprototype /funcsynopsis

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.

Net_URL::setOption


fetch message headers into in array

Net_URL::setOption
PHP Manual

Net_NNTP::splitHeaders()

(No version information available, might be only in CVS)

Net_NNTP::splitHeaders() — fetch message headers into in array

funcsynopsis funcsynopsisinfo require_once 'Net/NNTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_NNTP::splitHeaders()/funcdef paramdef string $articleId /paramdef /funcprototype /funcsynopsis

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

Example #1 Using splitHeaders()

...

$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>';
 }
}
Net_URL::setOption


predefined constants

Net_URL::setOption
PHP Manual

Constants

(No version information available, might be only in CVS)

Constants — predefined constants

NET_NNTP_PROTOCOL_CLIENT_DEFAULT_HOST

default NNTP hostname: localhost

NET_NNTP_PROTOCOL_CLIENT_DEFAULT_PORT

default NNTP port: 119

Net_URL::setOption


Net_Ping

API for the Ping command

Constants
Net_Ping::Net_Ping()
Networking


constructor

Net_Ping
Net_Ping::ping()
Net_Ping
PHP Manual

Net_Ping::Net_Ping()

(No version information available, might be only in CVS)

Net_Ping::Net_Ping() — constructor

funcsynopsis funcsynopsisinfo require_once 'Net/Ping.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Ping::Net_Ping() /funcdef paramdef /funcprototype /funcsynopsis

Description

Please use Net_Ping::factory() instead of using this constructor directly.

Net_Ping
Net_Ping::ping()
Net_Ping


executes a ping command

Net_Ping::Net_Ping()
Net_Ping::setArgs()
Net_Ping
PHP Manual

Net_Ping::ping()

(No version information available, might be only in CVS)

Net_Ping::ping() — executes a ping command

funcsynopsis funcsynopsisinfo require_once 'Net/Ping.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Ping::ping()/funcdef paramdefstring host /paramdef /funcprototype /funcsynopsis

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

Example #1 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'));
}
?>
Net_Ping::Net_Ping()
Net_Ping::setArgs()
Net_Ping


set arguments for a ping command

Net_Ping
Net_POP3
Net_Ping
PHP Manual

Net_Ping::setArgs()

(No version information available, might be only in CVS)

Net_Ping::setArgs() — set arguments for a ping command

funcsynopsis funcsynopsisinfo require_once 'Net/Ping.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Ping::setArgs()/funcdef paramdefarray $args /paramdef /funcprototype /funcsynopsis

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.

Net_Ping
Net_POP3
Net_Ping


Net_POP3

Provides a POP3 class to access POP3 server.

Net_Ping::setArgs()
Introduction to Net_POP3
Networking


Introduction to Net_POP3

(No version information available, might be only in CVS)

Introduction to —

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

Example #1 Usage

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();
Net_POP3
Net_POP3::Net_POP3()
Net_POP3


Constructor

Introduction to Net_POP3
Net_POP3::connect()
Net_POP3
PHP Manual

Net_POP3::Net_POP3()

(No version information available, might be only in CVS)

Net_POP3::Net_POP3() — Constructor

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdef Net_POP3::Net_POP3()/funcdef paramdef /funcprototype /funcsynopsis

Description

Constructor. Sets up the object variables, and instantiates the socket object.

Note

This function can not be called statically.

Introduction to Net_POP3
Net_POP3::connect()
Net_POP3


Connection to POP3 server

Net_POP3::Net_POP3()
Net_POP3::deleteMsg()
Net_POP3
PHP Manual

Net_POP3::connect()

(No version information available, might be only in CVS)

Net_POP3::connect() — Connection to POP3 server

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_POP3::connect()/funcdef paramdef string $host /paramdef paramdef integer $port /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::Net_POP3()
Net_POP3::deleteMsg()
Net_POP3


Marks a message for deletion

Net_POP3::connect()
Net_POP3::disconnect()
Net_POP3
PHP Manual

Net_POP3::deleteMsg()

(No version information available, might be only in CVS)

Net_POP3::deleteMsg() — Marks a message for deletion

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_POP3::deleteMsg()/funcdef paramdef integer $msg_id /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::connect()
Net_POP3::disconnect()
Net_POP3


Disconnection to POP3 server

Net_POP3::deleteMsg()
Net_POP3::getBody()
Net_POP3
PHP Manual

Net_POP3::disconnect()

(No version information available, might be only in CVS)

Net_POP3::disconnect() — Disconnection to POP3 server

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_POP3::disconnect()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_POP3::deleteMsg()
Net_POP3::getBody()
Net_POP3


Returns the body of the message

Net_POP3::disconnect()
Net_POP3::getListing()
Net_POP3
PHP Manual

Net_POP3::getBody()

(No version information available, might be only in CVS)

Net_POP3::getBody() — Returns the body of the message

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::getBody()/funcdef paramdef integer $msg_id /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::disconnect()
Net_POP3::getListing()
Net_POP3


Listing message in maildrop

Net_POP3::getBody()
Net_POP3::getMsg()
Net_POP3
PHP Manual

Net_POP3::getListing()

(No version information available, might be only in CVS)

Net_POP3::getListing() — Listing message in maildrop

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::getListing()/funcdef paramdef integer $msg_id /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::getBody()
Net_POP3::getMsg()
Net_POP3


Returns the entire message

Net_POP3::getListing()
Net_POP3::getParsedHeaders()
Net_POP3
PHP Manual

Net_POP3::getMsg()

(No version information available, might be only in CVS)

Net_POP3::getMsg() — Returns the entire message

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::getMsg()/funcdef paramdef integer $msg_id /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::getListing()
Net_POP3::getParsedHeaders()
Net_POP3


Returns the parsed headers of the specified message

Net_POP3::getMsg()
Net_POP3::getRawHeaders()
Net_POP3
PHP Manual

Net_POP3::getParsedHeaders()

(No version information available, might be only in CVS)

Net_POP3::getParsedHeaders() — Returns the parsed headers of the specified message

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::getParsedHeaders()/funcdef paramdef integer $msg_id /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::getMsg()
Net_POP3::getRawHeaders()
Net_POP3


Returns the raw headers of the specified message

Net_POP3::getParsedHeaders()
Net_POP3::getSize()
Net_POP3
PHP Manual

Net_POP3::getRawHeaders()

(No version information available, might be only in CVS)

Net_POP3::getRawHeaders() — Returns the raw headers of the specified message

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::getRawHeaders()/funcdef paramdef integer $msg_id /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::getParsedHeaders()
Net_POP3::getSize()
Net_POP3


Returns the size of the maildrop

Net_POP3::getRawHeaders()
Net_POP3::login()
Net_POP3
PHP Manual

Net_POP3::getSize()

(No version information available, might be only in CVS)

Net_POP3::getSize() — Returns the size of the maildrop

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::getSize()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_POP3::getRawHeaders()
Net_POP3::login()
Net_POP3


Performs the login procedure

Net_POP3::getSize()
Net_POP3::numMsg()
Net_POP3
PHP Manual

Net_POP3::login()

(No version information available, might be only in CVS)

Net_POP3::login() — Performs the login procedure

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_POP3::login()/funcdef paramdef string $user string $pass boolean $apop /paramdef /funcprototype /funcsynopsis

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.

Net_POP3::getSize()
Net_POP3::numMsg()
Net_POP3


number of messages in this maildrop

Net_POP3
Net_Portscan
Net_POP3
PHP Manual

Net_POP3::numMsg()

(No version information available, might be only in CVS)

Net_POP3::numMsg() — number of messages in this maildrop

funcsynopsis funcsynopsisinfo require_once 'Net/POP3.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_POP3::numMsg()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_POP3
Net_Portscan
Net_POP3


Net_Portscan

Provides an API for scanning ports

Net_POP3::numMsg()
Net_Portscan::checkPort()
Networking


check for available service

Net_Portscan
Net_Portscan::checkPortRange()
Net_Portscan
PHP Manual

Net_Portscan::checkPort()

(No version information available, might be only in CVS)

Net_Portscan::checkPort() — check for available service

funcsynopsis funcsynopsisinfo require_once 'Net/Portscan.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Portscan::checkPort()/funcdef paramdefstring $host /paramdef paramdefinteger $port /paramdef paramdefinteger $timeout = 30 /paramdef /funcprototype /funcsynopsis

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.

    /important

Return value

boolean - Returns TRUE on success, FALSE on failure.

Note

This function can be called statically.

Example

Example #1 Using checkPort

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";
}
Net_Portscan
Net_Portscan::checkPortRange()
Net_Portscan


check for available services

Net_Portscan::checkPort()
Net_Portscan::getPort()
Net_Portscan
PHP Manual

Net_Portscan::checkPortRange()

(No version information available, might be only in CVS)

Net_Portscan::checkPortRange() — check for available services

funcsynopsis funcsynopsisinfo require_once 'Net/Portscan.php'; /funcsynopsisinfo funcprototype funcdefarray Net_Portscan::checkPortRange()/funcdef paramdefstring $host /paramdef paramdefinteger $minPort /paramdef paramdefinteger $maxPort /paramdef paramdefinteger $timeout = 30 /paramdef /funcprototype /funcsynopsis

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.

    /important

Return value

array - An associative array containing the scanning results for each port.

Note

This function can be called statically.

Example

Example #1 Using checkPortRange

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";
    }
}
Net_Portscan::checkPort()
Net_Portscan::getPort()
Net_Portscan


port number of a service

Net_Portscan::checkPortRange()
Net_Portscan::getService()
Net_Portscan
PHP Manual

Net_Portscan::getPort()

(No version information available, might be only in CVS)

Net_Portscan::getPort() — port number of a service

funcsynopsis funcsynopsisinfo require_once 'Net/Portscan.php'; /funcsynopsisinfo funcprototype funcdefinteger Net_Portscan::getPort()/funcdef paramdefstring $service /paramdef paramdefstring $protocol = 'tcp' /paramdef /funcprototype /funcsynopsis

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().

Net_Portscan::checkPortRange()
Net_Portscan::getService()
Net_Portscan


name of the service

Net_Portscan
Net_Server
Net_Portscan
PHP Manual

Net_Portscan::getService()

(No version information available, might be only in CVS)

Net_Portscan::getService() — name of the service

funcsynopsis funcsynopsisinfo require_once 'Net/Portscan.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Portscan::checkPortRange()/funcdef paramdefinteger $port /paramdef paramdefstring $protocol = 'tcp' /paramdef /funcprototype /funcsynopsis

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().

Net_Portscan
Net_Server
Net_Portscan


Net_Server

Generic server package for creating daemons.

Net_Portscan::getService()
Introduction
Networking


Net_Server
Example
Net_Server
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Net_Server
Example
Net_Server


using Net_Server

Introduction
Class Summary Net_Server
Net_Server
PHP Manual

Example

(No version information available, might be only in CVS)

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.

Example #1 Creating a simple talkback daemon

<?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();
?>
Introduction
Class Summary Net_Server
Net_Server


Example
Net_Server::create
Net_Server
PHP Manual

Class Summary Net_Server

(No version information available, might be only in CVS)

Class Summary — 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

Example
Net_Server::create
Net_Server


create a new server

Class Summary Net_Server
Class Summary Net_Server_Driver
Net_Server
PHP Manual

Net_Server::create()

(No version information available, might be only in CVS)

— create a new server

funcsynopsis funcsynopsisinfo require_once 'Server.php'; /funcsynopsisinfo funcprototype funcdefvoid& Net_Server::create()/funcdef paramdefstring $type /paramdef paramdefstring $host /paramdef paramdefinteger $port /paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Server
Class Summary Net_Server_Driver
Net_Server


Net_Server::create
Net_Server_Driver::getLastSocketError
Net_Server
PHP Manual

Class Summary Net_Server_Driver

(No version information available, might be only in CVS)

Class Summary — 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.

Net_Server::create
Net_Server_Driver::getLastSocketError
Net_Server


return string for last socket error

Class Summary Net_Server_Driver
Net_Server_Driver::setCallbackObject
Net_Server
PHP Manual

Net_Server_Driver::getLastSocketError()

(No version information available, might be only in CVS)

— return string for last socket error

funcsynopsis funcsynopsisinfo require_once 'ServerDriver.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Server_Driver::getLastSocketError()/funcdef paramdefmixed &$fd /paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Server_Driver
Net_Server_Driver::setCallbackObject
Net_Server


register a callback object, that is used to handle all events

Net_Server_Driver::getLastSocketError
Net_Server_Driver::setDebugMode
Net_Server
PHP Manual

Net_Server_Driver::setCallbackObject()

(No version information available, might be only in CVS)

— register a callback object, that is used to handle all events

funcsynopsis funcsynopsisinfo require_once 'ServerDriver.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver::setCallbackObject()/funcdef paramdefobject &$object /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver::getLastSocketError
Net_Server_Driver::setDebugMode
Net_Server


set debug mode

Net_Server_Driver::setCallbackObject
Class Summary Net_Server_Driver_Fork
Net_Server
PHP Manual

Net_Server_Driver::setDebugMode()

(No version information available, might be only in CVS)

— set debug mode

funcsynopsis funcsynopsisinfo require_once 'ServerDriver.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver::setDebugMode()/funcdef paramdefmixed $debug /paramdef paramdefstring $dest = "stdout" /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver::setCallbackObject
Class Summary Net_Server_Driver_Fork
Net_Server


Net_Server_Driver::setDebugMode
Net_Server_Driver_Fork::broadcastData
Net_Server
PHP Manual

Class Summary Net_Server_Driver_Fork

(No version information available, might be only in CVS)

Class Summary — 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

Net_Server_Driver::setDebugMode
Net_Server_Driver_Fork::broadcastData
Net_Server


send data to all clients

Class Summary Net_Server_Driver_Fork
Net_Server_Driver_Fork::closeConnection
Net_Server
PHP Manual

Net_Server_Driver_Fork::broadcastData()

(No version information available, might be only in CVS)

— send data to all clients

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::broadcastData()/funcdef paramdefstring $data /paramdef paramdefarray $exclude = array() /paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Server_Driver_Fork
Net_Server_Driver_Fork::closeConnection
Net_Server


close the current connection

Net_Server_Driver_Fork::broadcastData
Net_Server_Driver_Fork::getClientInfo
Net_Server
PHP Manual

Net_Server_Driver_Fork::closeConnection()

(No version information available, might be only in CVS)

— close the current connection

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::closeConnection()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::broadcastData
Net_Server_Driver_Fork::getClientInfo
Net_Server


get current information about a client

Net_Server_Driver_Fork::closeConnection
Net_Server_Driver_Fork::getClients
Net_Server
PHP Manual

Net_Server_Driver_Fork::getClientInfo()

(No version information available, might be only in CVS)

— get current information about a client

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefarray Net_Server_Driver_Fork::getClientInfo()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Fork::closeConnection
Net_Server_Driver_Fork::getClients
Net_Server


get current amount of clients

Net_Server_Driver_Fork::getClientInfo
Net_Server_Driver_Fork::isConnected
Net_Server
PHP Manual

Net_Server_Driver_Fork::getClients()

(No version information available, might be only in CVS)

— get current amount of clients

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefPEAR_Error Net_Server_Driver_Fork::getClients()/funcdef paramdef /funcprototype /funcsynopsis

Description

not possible with forking

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::getClientInfo
Net_Server_Driver_Fork::isConnected
Net_Server


check, whether a client is still connected

Net_Server_Driver_Fork::getClients
Net_Server_Driver_Fork::sendData
Net_Server
PHP Manual

Net_Server_Driver_Fork::isConnected()

(No version information available, might be only in CVS)

— check, whether a client is still connected

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Server_Driver_Fork::isConnected()/funcdef paramdefinteger $id /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Fork::getClients
Net_Server_Driver_Fork::sendData
Net_Server


send data to a client

Net_Server_Driver_Fork::isConnected
Net_Server_Driver_Fork::serviceRequest
Net_Server
PHP Manual

Net_Server_Driver_Fork::sendData()

(No version information available, might be only in CVS)

— send data to a client

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::sendData()/funcdef paramdefstring $data /paramdef paramdefboolean $debugData = TRUE /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Fork::isConnected
Net_Server_Driver_Fork::serviceRequest
Net_Server


service the current request

Net_Server_Driver_Fork::sendData
Net_Server_Driver_Fork::setMaxClients
Net_Server
PHP Manual

Net_Server_Driver_Fork::serviceRequest()

(No version information available, might be only in CVS)

— service the current request

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::serviceRequest()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::sendData
Net_Server_Driver_Fork::setMaxClients
Net_Server


set maximum amount of simultaneous connections

Net_Server_Driver_Fork::serviceRequest
Net_Server_Driver_Fork::shutDown
Net_Server
PHP Manual

Net_Server_Driver_Fork::setMaxClients()

(No version information available, might be only in CVS)

— set maximum amount of simultaneous connections

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::setMaxClients()/funcdef paramdefint $maxClients /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Fork::serviceRequest
Net_Server_Driver_Fork::shutDown
Net_Server


shutdown server

Net_Server_Driver_Fork::setMaxClients
Net_Server_Driver_Fork::start
Net_Server
PHP Manual

Net_Server_Driver_Fork::shutDown()

(No version information available, might be only in CVS)

— shutdown server

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::shutDown()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::setMaxClients
Net_Server_Driver_Fork::start
Net_Server


start the server

Net_Server_Driver_Fork::shutDown
Class Summary Net_Server_Driver_Sequential
Net_Server
PHP Manual

Net_Server_Driver_Fork::start()

(No version information available, might be only in CVS)

— start the server

funcsynopsis funcsynopsisinfo require_once 'ServerDriverFork.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Fork::start()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Fork::shutDown
Class Summary Net_Server_Driver_Sequential
Net_Server


Net_Server_Driver_Fork::start
Net_Server_Driver_Sequential::acceptConnection
Net_Server
PHP Manual

Class Summary Net_Server_Driver_Sequential

(No version information available, might be only in CVS)

Class Summary — 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

Net_Server_Driver_Fork::start
Net_Server_Driver_Sequential::acceptConnection
Net_Server


accept a new connection

Class Summary Net_Server_Driver_Sequential
Net_Server_Driver_Sequential::broadcastData
Net_Server
PHP Manual

Net_Server_Driver_Sequential::acceptConnection()

(No version information available, might be only in CVS)

— accept a new connection

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefint Net_Server_Driver_Sequential::acceptConnection()/funcdef paramdefresource &$socket /paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Server_Driver_Sequential
Net_Server_Driver_Sequential::broadcastData
Net_Server


send data to all clients

Net_Server_Driver_Sequential::acceptConnection
Net_Server_Driver_Sequential::closeConnection
Net_Server
PHP Manual

Net_Server_Driver_Sequential::broadcastData()

(No version information available, might be only in CVS)

— send data to all clients

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Sequential::broadcastData()/funcdef paramdefstring $data /paramdef paramdefarray $exclude = array() /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Sequential::acceptConnection
Net_Server_Driver_Sequential::closeConnection
Net_Server


close connection to a client

Net_Server_Driver_Sequential::broadcastData
Net_Server_Driver_Sequential::getClientInfo
Net_Server
PHP Manual

Net_Server_Driver_Sequential::closeConnection()

(No version information available, might be only in CVS)

— close connection to a client

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Sequential::closeConnection()/funcdef paramdefmixed $id = 0 /paramdef paramdefint $clientID /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Sequential::broadcastData
Net_Server_Driver_Sequential::getClientInfo
Net_Server


get current information about a client

Net_Server_Driver_Sequential::closeConnection
Net_Server_Driver_Sequential::getClients
Net_Server
PHP Manual

Net_Server_Driver_Sequential::getClientInfo()

(No version information available, might be only in CVS)

— get current information about a client

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefarray Net_Server_Driver_Sequential::getClientInfo()/funcdef paramdefint $clientId /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Sequential::closeConnection
Net_Server_Driver_Sequential::getClients
Net_Server


get current amount of clients

Net_Server_Driver_Sequential::getClientInfo
Net_Server_Driver_Sequential::isConnected
Net_Server
PHP Manual

Net_Server_Driver_Sequential::getClients()

(No version information available, might be only in CVS)

— get current amount of clients

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefint Net_Server_Driver_Sequential::getClients()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Sequential::getClientInfo
Net_Server_Driver_Sequential::isConnected
Net_Server


check, whether a client is still connected

Net_Server_Driver_Sequential::getClients
Net_Server_Driver_Sequential::sendData
Net_Server
PHP Manual

Net_Server_Driver_Sequential::isConnected()

(No version information available, might be only in CVS)

— check, whether a client is still connected

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Server_Driver_Sequential::isConnected()/funcdef paramdefinteger $id /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Sequential::getClients
Net_Server_Driver_Sequential::sendData
Net_Server


send data to a client

Net_Server_Driver_Sequential::isConnected
Net_Server_Driver_Sequential::setMaxClients
Net_Server
PHP Manual

Net_Server_Driver_Sequential::sendData()

(No version information available, might be only in CVS)

— send data to a client

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Sequential::sendData()/funcdef paramdefint $clientId /paramdef paramdefstring $data /paramdef paramdefboolean $debugData = TRUE /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Driver_Sequential::isConnected
Net_Server_Driver_Sequential::setMaxClients
Net_Server


set maximum amount of simultaneous connections

Net_Server_Driver_Sequential::sendData
Net_Server_Driver_Sequential::shutDown
Net_Server
PHP Manual

Net_Server_Driver_Sequential::setMaxClients()

(No version information available, might be only in CVS)

— set maximum amount of simultaneous connections

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Sequential::setMaxClients()/funcdef paramdefint $maxClients /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

integer $maxClients

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::sendData
Net_Server_Driver_Sequential::shutDown
Net_Server


shutdown server

Net_Server_Driver_Sequential::setMaxClients
Net_Server_Driver_Sequential::start
Net_Server
PHP Manual

Net_Server_Driver_Sequential::shutDown()

(No version information available, might be only in CVS)

— shutdown server

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Sequential::shutDown()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::setMaxClients
Net_Server_Driver_Sequential::start
Net_Server


start the server

Net_Server_Driver_Sequential::shutDown
Class Summary Net_Server_Handler
Net_Server
PHP Manual

Net_Server_Driver_Sequential::start()

(No version information available, might be only in CVS)

— start the server

funcsynopsis funcsynopsisinfo require_once 'ServerDriverSequential.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Driver_Sequential::start()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Net_Server_Driver_Sequential::shutDown
Class Summary Net_Server_Handler
Net_Server


Net_Server_Driver_Sequential::start
Net_Server_Handler::onClose
Net_Server
PHP Manual

Class Summary Net_Server_Handler

(No version information available, might be only in CVS)

Class Summary — 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

Net_Server_Driver_Sequential::start
Net_Server_Handler::onClose
Net_Server


onClose handler

Class Summary Net_Server_Handler
Net_Server_Handler::onConnect
Net_Server
PHP Manual

Net_Server_Handler::onClose()

(No version information available, might be only in CVS)

— onClose handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onClose()/funcdef paramdefinteger $clientId = 0 /paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Server_Handler
Net_Server_Handler::onConnect
Net_Server


onConnect handler

Net_Server_Handler::onClose
Net_Server_Handler::onConnectionRefused
Net_Server
PHP Manual

Net_Server_Handler::onConnect()

(No version information available, might be only in CVS)

— onConnect handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onConnect()/funcdef paramdefinteger $clientId = 0 /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onClose
Net_Server_Handler::onConnectionRefused
Net_Server


onConnectionRefused handler

Net_Server_Handler::onConnect
Net_Server_Handler::onIdle
Net_Server
PHP Manual

Net_Server_Handler::onConnectionRefused()

(No version information available, might be only in CVS)

— onConnectionRefused handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onConnectionRefused()/funcdef paramdefinteger $clientId = 0 /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onConnect
Net_Server_Handler::onIdle
Net_Server


onIdle handler

Net_Server_Handler::onConnectionRefused
Net_Server_Handler::onReceiveData
Net_Server
PHP Manual

Net_Server_Handler::onIdle()

(No version information available, might be only in CVS)

— onIdle handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onIdle()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onConnectionRefused
Net_Server_Handler::onReceiveData
Net_Server


onReceiveData handler

Net_Server_Handler::onIdle
Net_Server_Handler::onShutdown
Net_Server
PHP Manual

Net_Server_Handler::onReceiveData()

(No version information available, might be only in CVS)

— onReceiveData handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onReceiveData()/funcdef paramdefinteger $clientId = 0 /paramdef paramdefstring $data = "" /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onIdle
Net_Server_Handler::onShutdown
Net_Server


onShutdown handler

Net_Server_Handler::onReceiveData
Net_Server_Handler::onStart
Net_Server
PHP Manual

Net_Server_Handler::onShutdown()

(No version information available, might be only in CVS)

— onShutdown handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onShutdown()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onReceiveData
Net_Server_Handler::onStart
Net_Server


onStart handler

Net_Server_Handler::onShutdown
Net_Server_Handler::setServerReference
Net_Server
PHP Manual

Net_Server_Handler::onStart()

(No version information available, might be only in CVS)

— onStart handler

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::onStart()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onShutdown
Net_Server_Handler::setServerReference
Net_Server


set a reference to the server object

Net_Server_Handler::onStart
Package Net_Server Constants
Net_Server
PHP Manual

Net_Server_Handler::setServerReference()

(No version information available, might be only in CVS)

— set a reference to the server object

funcsynopsis funcsynopsisinfo require_once 'ServerHandler.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Server_Handler::setServerReference()/funcdef paramdefobject Net_Server_* &$server /paramdef /funcprototype /funcsynopsis

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.

Net_Server_Handler::onStart
Package Net_Server Constants
Net_Server


Constants defined in and used by Net_Server

Net_Server
Net_SmartIrc
Net_Server
PHP Manual

Package Net_Server Constants

(No version information available, might be only in CVS)

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

Net_Server
Net_SmartIrc
Net_Server


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.

Package Net_Server Constants
Introduction
Networking


Net_SmartIRC is a PHP class for communication with IRC networks, which conforms to the RFC 2812 (IRC protocol).

Net_SmartIrc
Net_SMTP
Net_SmartIrc
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Net_SmartIrc
Net_SMTP
Net_SmartIrc


Net_SMTP

Introduction
Class Summary Net_SMTP
Networking


Net_SMTP
Introduction and Guide
Net_SMTP
PHP Manual

Class Summary Net_SMTP

(No version information available, might be only in CVS)

Class Summary — 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

Net_SMTP
Introduction and Guide
Net_SMTP


Provides an implementation of the SMTP protocol

Class Summary Net_SMTP
constructor Net_SMTP::Net_SMTP
Net_SMTP
PHP Manual

Introduction and Guide

(No version information available, might be only in CVS)

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:

$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:

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:

$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();
?>
Class Summary Net_SMTP
constructor Net_SMTP::Net_SMTP
Net_SMTP


Instantiates a new Net_SMTP object, overriding any networkings with parameters that are passed in.

Introduction and Guide
Net_SMTP::auth
Net_SMTP
PHP Manual

constructor Net_SMTP::Net_SMTP()

(No version information available, might be only in CVS)

constructor — Instantiates a new Net_SMTP object, overriding any networkings with parameters that are passed in.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor Net_SMTP::Net_SMTP()/funcdef paramdefstring $host = NULL /paramdef paramdefint $port = NULL /paramdef paramdefstring $localhost = NULL /paramdef /funcprototype /funcsynopsis

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.

Introduction and Guide
Net_SMTP::auth
Net_SMTP


Attempt to do SMTP authentication.

constructor Net_SMTP::Net_SMTP
Net_SMTP::connect
Net_SMTP
PHP Manual

Net_SMTP::auth()

(No version information available, might be only in CVS)

— Attempt to do SMTP authentication.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::auth()/funcdef paramdefstring $uid /paramdef paramdefstring $pwd /paramdef paramdefstring $method = '' /paramdef /funcprototype /funcsynopsis

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.

constructor Net_SMTP::Net_SMTP
Net_SMTP::connect
Net_SMTP


Attempt to connect to the SMTP server.

Net_SMTP::auth
Net_SMTP::data
Net_SMTP
PHP Manual

Net_SMTP::connect()

(No version information available, might be only in CVS)

— Attempt to connect to the SMTP server.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_SMTP::connect()/funcdef paramdefint $timeout = NULL /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::auth
Net_SMTP::data
Net_SMTP


Send the DATA command to start message body

Net_SMTP::connect
Net_SMTP::disconnect
Net_SMTP
PHP Manual

Net_SMTP::data()

(No version information available, might be only in CVS)

— Send the DATA command to start message body

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::data()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::connect
Net_SMTP::disconnect
Net_SMTP


Attempt to disconnect from the SMTP server.

Net_SMTP::data
Net_SMTP::getResponse
Net_SMTP
PHP Manual

Net_SMTP::disconnect()

(No version information available, might be only in CVS)

— Attempt to disconnect from the SMTP server.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::disconnect()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::data
Net_SMTP::getResponse
Net_SMTP


Return a 2-tuple containing the last response from the SMTP server.

Net_SMTP::disconnect
Net_SMTP::helo
Net_SMTP
PHP Manual

Net_SMTP::getResponse()

(No version information available, might be only in CVS)

— Return a 2-tuple containing the last response from the SMTP server.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefarray Net_SMTP::getResponse()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::disconnect
Net_SMTP::helo
Net_SMTP


Send the HELO command.

Net_SMTP::getResponse
Net_SMTP::identifySender
Net_SMTP
PHP Manual

Net_SMTP::helo()

(No version information available, might be only in CVS)

— Send the HELO command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_SMTP::helo()/funcdef paramdefstring $domain /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::getResponse
Net_SMTP::identifySender
Net_SMTP


Backwards-compatibility method.identifySender()'s functionality is now handled internally.

Net_SMTP::helo
Net_SMTP::mailFrom
Net_SMTP
PHP Manual

Net_SMTP::identifySender()

(No version information available, might be only in CVS)

— Backwards-compatibility method.identifySender()'s functionality is now handled internally.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefbooleanNet_SMTP::identifySender()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::helo
Net_SMTP::mailFrom
Net_SMTP


Send the MAIL FROM: command.

Net_SMTP::identifySender
Net_SMTP::noop
Net_SMTP
PHP Manual

Net_SMTP::mailFrom()

(No version information available, might be only in CVS)

— Send the MAIL FROM: command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::mailFrom()/funcdef paramdefstring $sender /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::identifySender
Net_SMTP::noop
Net_SMTP


Send the NOOP command.

Net_SMTP::mailFrom
Net_SMTP::quotedata
Net_SMTP
PHP Manual

Net_SMTP::noop()

(No version information available, might be only in CVS)

— Send the NOOP command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::noop()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::mailFrom
Net_SMTP::quotedata
Net_SMTP


Quote the data so that it meets SMTP standards.

Net_SMTP::noop
Net_SMTP::rcptTo
Net_SMTP
PHP Manual

Net_SMTP::quotedata()

(No version information available, might be only in CVS)

— Quote the data so that it meets SMTP standards.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_SMTP::quotedata()/funcdef paramdefstring &$data /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::noop
Net_SMTP::rcptTo
Net_SMTP


Send the RCPT TO: command.

Net_SMTP::quotedata
Net_SMTP::rset
Net_SMTP
PHP Manual

Net_SMTP::rcptTo()

(No version information available, might be only in CVS)

— Send the RCPT TO: command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::rcptTo()/funcdef paramdefstring $recipient /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::quotedata
Net_SMTP::rset
Net_SMTP


Send the RSET command.

Net_SMTP::rcptTo
Net_SMTP::saml_from
Net_SMTP
PHP Manual

Net_SMTP::rset()

(No version information available, might be only in CVS)

— Send the RSET command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_SMTP::rset()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::rcptTo
Net_SMTP::saml_from
Net_SMTP


Send the SAML FROM: command.

Net_SMTP::rset
Net_SMTP::send_from
Net_SMTP
PHP Manual

Net_SMTP::saml_from()

(No version information available, might be only in CVS)

— Send the SAML FROM: command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixedNet_SMTP::saml_from()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::rset
Net_SMTP::send_from
Net_SMTP


Send the SEND FROM: command.

Net_SMTP::saml_from
Net_SMTP::setDebug
Net_SMTP
PHP Manual

Net_SMTP::send_from()

(No version information available, might be only in CVS)

— Send the SEND FROM: command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_SMTP::send_from()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::saml_from
Net_SMTP::setDebug
Net_SMTP


Set the value of the debugging flag.

Net_SMTP::send_from
Net_SMTP::soml_from
Net_SMTP
PHP Manual

Net_SMTP::setDebug()

(No version information available, might be only in CVS)

— Set the value of the debugging flag.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefvoidNet_SMTP::setDebug()/funcdef paramdefboolean $debug /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::send_from
Net_SMTP::soml_from
Net_SMTP


Send the SOML FROM: command.

Net_SMTP::setDebug
Net_SMTP::vrfy
Net_SMTP
PHP Manual

Net_SMTP::soml_from()

(No version information available, might be only in CVS)

— Send the SOML FROM: command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_SMTP::soml_from()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP::setDebug
Net_SMTP::vrfy
Net_SMTP


Send the VRFY command.

Net_SMTP
Net_Socket
Net_SMTP
PHP Manual

Net_SMTP::vrfy()

(No version information available, might be only in CVS)

— Send the VRFY command.

funcsynopsis funcsynopsisinfo require_once 'NET/SMTP.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_SMTP::vrfy()/funcdef paramdefstring $string /paramdef /funcprototype /funcsynopsis

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.

Net_SMTP
Net_Socket
Net_SMTP


Net_Socket

Net_Socket provides a generic API for communication over TCP/IP-sockets.

Net_SMTP::vrfy
Net_Socket::connect()
Networking


connects to a server

Net_Socket
Net_Socket::disconnect()
Net_Socket
PHP Manual

Net_Socket::connect()

(No version information available, might be only in CVS)

Net_Socket::connect() — connects to a server

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::connect()/funcdef paramdefstring $addr /paramdef paramdefinteger $port /paramdef paramdefboolean $persistent = NULL /paramdef paramdefinteger $timeout = NULL /paramdef paramdefarray $options = NULL /paramdef /funcprototype /funcsynopsis

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()

Net_Socket
Net_Socket::disconnect()
Net_Socket


disconnects from a server

Net_Socket::connect()
Net_Socket::eof()
Net_Socket
PHP Manual

Net_Socket::disconnect()

(No version information available, might be only in CVS)

Net_Socket::disconnect() — disconnects from a server

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::disconnect()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::connect()
Net_Socket::eof()
Net_Socket


test for end-of-file

Net_Socket::disconnect()
Net_Socket::gets()
Net_Socket
PHP Manual

Net_Socket::eof()

(No version information available, might be only in CVS)

Net_Socket::eof() — test for end-of-file

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::eof()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Socket::disconnect()
Net_Socket::gets()
Net_Socket


retrieve a string

Net_Socket::eof()
Net_Socket::getStatus()
Net_Socket
PHP Manual

Net_Socket::gets()

(No version information available, might be only in CVS)

Net_Socket::gets() — retrieve a string

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::gets()/funcdef paramdefinteger $size /paramdef /funcprototype /funcsynopsis

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()

Net_Socket::eof()
Net_Socket::getStatus()
Net_Socket


retrieve information about a connection

Net_Socket::gets()
Net_Socket::isBlocking()
Net_Socket
PHP Manual

Net_Socket::getStatus()

(No version information available, might be only in CVS)

Net_Socket::getStatus() — retrieve information about a connection

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefarray Net_Socket::getStatus()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Socket::gets()
Net_Socket::isBlocking()
Net_Socket


check for blocking mode

Net_Socket::getStatus()
Net_Socket::read()
Net_Socket
PHP Manual

Net_Socket::isBlocking()

(No version information available, might be only in CVS)

Net_Socket::isBlocking() — check for blocking mode

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::isBlocking()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::getStatus()
Net_Socket::read()
Net_Socket


retrieve data

Net_Socket::isBlocking()
Net_Socket::readAll()
Net_Socket
PHP Manual

Net_Socket::read()

(No version information available, might be only in CVS)

Net_Socket::read() — retrieve data

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::read()/funcdef paramdefinteger $size /paramdef /funcprototype /funcsynopsis

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()

Net_Socket::isBlocking()
Net_Socket::readAll()
Net_Socket


retrieve data until connection closes

Net_Socket::read()
Net_Socket::readByte()
Net_Socket
PHP Manual

Net_Socket::readAll()

(No version information available, might be only in CVS)

Net_Socket::readAll() — retrieve data until connection closes

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::readAll()/funcdef paramdef /funcprototype /funcsynopsis

Description

Read until the socket closes.

Warning

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()

Net_Socket::read()
Net_Socket::readByte()
Net_Socket


read a byte

Net_Socket::readAll()
Net_Socket::readInt()
Net_Socket
PHP Manual

Net_Socket::readByte()

(No version information available, might be only in CVS)

Net_Socket::readByte() — read a byte

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::readByte()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readAll()
Net_Socket::readInt()
Net_Socket


read an integer

Net_Socket::readByte()
Net_Socket::readIPAddress()
Net_Socket
PHP Manual

Net_Socket::readInt()

(No version information available, might be only in CVS)

Net_Socket::readInt() — read an integer

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::readInt()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readByte()
Net_Socket::readIPAddress()
Net_Socket


read an IP-address

Net_Socket::readInt()
Net_Socket::readLine()
Net_Socket
PHP Manual

Net_Socket::readIPAddress()

(No version information available, might be only in CVS)

Net_Socket::readIPAddress() — read an IP-address

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Socket::readIPAddress()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readInt()
Net_Socket::readLine()
Net_Socket


retrieve data until line end

Net_Socket::readIPAddress()
Net_Socket::readString()
Net_Socket
PHP Manual

Net_Socket::readLine()

(No version information available, might be only in CVS)

Net_Socket::readLine() — retrieve data until line end

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::readLine()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readIPAddress()
Net_Socket::readString()
Net_Socket


read a string

Net_Socket::readLine()
Net_Socket::readWord()
Net_Socket
PHP Manual

Net_Socket::readString()

(No version information available, might be only in CVS)

Net_Socket::readString() — read a string

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::readString()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readLine()
Net_Socket::readWord()
Net_Socket


read a word

Net_Socket::readString()
Net_Socket::setBlocking()
Net_Socket
PHP Manual

Net_Socket::readWord()

(No version information available, might be only in CVS)

Net_Socket::readWord() — read a word

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Socket::readWord()/funcdef paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readString()
Net_Socket::setBlocking()
Net_Socket


sets blocking mode

Net_Socket::readWord()
Net_Socket::setTimeout()
Net_Socket
PHP Manual

Net_Socket::setBlocking()

(No version information available, might be only in CVS)

Net_Socket::setBlocking() — sets blocking mode

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::setBlocking()/funcdef paramdefboolean $mode /paramdef /funcprototype /funcsynopsis

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()

Net_Socket::readWord()
Net_Socket::setTimeout()
Net_Socket


sets timeout

Net_Socket::setBlocking()
Net_Socket::write()
Net_Socket
PHP Manual

Net_Socket::setTimeout()

(No version information available, might be only in CVS)

Net_Socket::setTimeout() — sets timeout

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::setTimeout()/funcdef paramdefinteger $seconds /paramdef paramdefinteger $microseconds /paramdef /funcprototype /funcsynopsis

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.

Net_Socket::setBlocking()
Net_Socket::write()
Net_Socket


write data

Net_Socket::setTimeout()
Net_Socket::writeLine()
Net_Socket
PHP Manual

Net_Socket::write()

(No version information available, might be only in CVS)

Net_Socket::write() — write data

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::write()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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()

Net_Socket::setTimeout()
Net_Socket::writeLine()
Net_Socket


write data including EOL

Net_Socket::write()
Example
Net_Socket
PHP Manual

Net_Socket::writeLine()

(No version information available, might be only in CVS)

Net_Socket::writeLine() — write data including EOL

funcsynopsis funcsynopsisinfo require_once 'Net/Socket.php'; /funcsynopsisinfo funcprototype funcdefboolean Net_Socket::writeLine()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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()

Net_Socket::write()
Example
Net_Socket


using Net_Socket

Net_Socket
Net_Traceroute
Net_Socket
PHP Manual

Example

(No version information available, might be only in CVS)

Example — using Net_Socket

Example

Example #1 Sending and recieving data

$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();
Net_Socket
Net_Traceroute
Net_Socket


Net_Traceroute

Example
Class Summary Net_Traceroute
Networking


Net_Traceroute
Net_Traceroute::factory
Net_Traceroute
PHP Manual

Class Summary Net_Traceroute

(No version information available, might be only in CVS)

Class Summary — Wrapper class for traceroute calls

Wrapper class for traceroute calls

This package is not documented yet.

Class Trees for Net_Traceroute

  • Net_Traceroute

Net_Traceroute
Net_Traceroute::factory
Net_Traceroute


Factory for Net_Traceroute

Class Summary Net_Traceroute
Net_Traceroute::setArgs
Net_Traceroute
PHP Manual

Net_Traceroute::factory()

(No version information available, might be only in CVS)

— Factory for Net_Traceroute

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdef object Net_Traceroute Net_Traceroute::factory()/funcdef paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Traceroute
Net_Traceroute::setArgs
Net_Traceroute


Set the arguments array

Net_Traceroute::factory
Net_Traceroute::traceroute
Net_Traceroute
PHP Manual

Net_Traceroute::setArgs()

(No version information available, might be only in CVS)

— Set the arguments array

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Traceroute::setArgs()/funcdef paramdefarray $args /paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute::factory
Net_Traceroute::traceroute
Net_Traceroute


Execute traceroute

Net_Traceroute::setArgs
Class Summary Net_Traceroute_Result
Net_Traceroute
PHP Manual

Net_Traceroute::traceroute()

(No version information available, might be only in CVS)

— Execute traceroute

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdef object Net_Traceroute_Result Net_Traceroute::traceroute()/funcdef paramdefstring $host /paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute::setArgs
Class Summary Net_Traceroute_Result
Net_Traceroute


Net_Traceroute::traceroute
Net_Traceroute_Result::factory
Net_Traceroute
PHP Manual

Class Summary Net_Traceroute_Result

(No version information available, might be only in CVS)

Class Summary — 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

Net_Traceroute::traceroute
Net_Traceroute_Result::factory
Net_Traceroute


Factory for Net_Traceroute_Result

Class Summary Net_Traceroute_Result
Net_Traceroute_Result::getHops
Net_Traceroute
PHP Manual

Net_Traceroute_Result::factory()

(No version information available, might be only in CVS)

— Factory for Net_Traceroute_Result

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefvoid Net_Traceroute_Result::factory()/funcdef paramdefarray $result /paramdef paramdefstring $sysname /paramdef /funcprototype /funcsynopsis

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.

Class Summary Net_Traceroute_Result
Net_Traceroute_Result::getHops
Net_Traceroute


Returns hops from parsed result

Net_Traceroute_Result::factory
Net_Traceroute_Result::getRawData
Net_Traceroute
PHP Manual

Net_Traceroute_Result::getHops()

(No version information available, might be only in CVS)

— Returns hops from parsed result

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefarray Net_Traceroute_Result::getHops()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute_Result::factory
Net_Traceroute_Result::getRawData
Net_Traceroute


Returns raw data that was returned by traceroute

Net_Traceroute_Result::getHops
Net_Traceroute_Result::getSystemName
Net_Traceroute
PHP Manual

Net_Traceroute_Result::getRawData()

(No version information available, might be only in CVS)

— Returns raw data that was returned by traceroute

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefarray Net_Traceroute_Result::getRawData()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute_Result::getHops
Net_Traceroute_Result::getSystemName
Net_Traceroute


Returns sysname that was "guessed" (OS on which class is running)

Net_Traceroute_Result::getRawData
Net_Traceroute_Result::getTargetIp
Net_Traceroute
PHP Manual

Net_Traceroute_Result::getSystemName()

(No version information available, might be only in CVS)

— Returns sysname that was "guessed" (OS on which class is running)

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Traceroute_Result::getSystemName()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute_Result::getRawData
Net_Traceroute_Result::getTargetIp
Net_Traceroute


Returns the target IP from parsed result

Net_Traceroute_Result::getSystemName
Net_Traceroute_Result::getTTL
Net_Traceroute
PHP Manual

Net_Traceroute_Result::getTargetIp()

(No version information available, might be only in CVS)

— Returns the target IP from parsed result

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Traceroute_Result::getTargetIp()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute_Result::getSystemName
Net_Traceroute_Result::getTTL
Net_Traceroute


Returns TTL from parsed result

Net_Traceroute_Result::getTargetIp
Net_Traceroute_Result::getValue
Net_Traceroute
PHP Manual

Net_Traceroute_Result::getTTL()

(No version information available, might be only in CVS)

— Returns TTL from parsed result

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefint Net_Traceroute_Result::getTTL()/funcdef paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute_Result::getTargetIp
Net_Traceroute_Result::getValue
Net_Traceroute


Returns a Traceroute_Result property

Net_Traceroute_Result::getTTL
Package Net_Traceroute Constants
Net_Traceroute
PHP Manual

Net_Traceroute_Result::getValue()

(No version information available, might be only in CVS)

— Returns a Traceroute_Result property

funcsynopsis funcsynopsisinfo require_once '/Traceroute.php'; /funcsynopsisinfo funcprototype funcdefmixed Net_Traceroute_Result::getValue()/funcdef paramdefstring $name /paramdef /funcprototype /funcsynopsis

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.

Net_Traceroute_Result::getTTL
Package Net_Traceroute Constants
Net_Traceroute


Constants defined in and used by Net_Traceroute

Net_Traceroute
Net_Whois
Net_Traceroute
PHP Manual

Package Net_Traceroute Constants

(No version information available, might be only in CVS)

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

Net_Traceroute
Net_Whois
Net_Traceroute


Net_Whois

Provides an API for accessing Whois services

Package Net_Traceroute Constants
Net_Whois::query()
Networking


does a whois query

Net_Whois
Net_Wifi
Net_Whois
PHP Manual

Net_Whois::query()

(No version information available, might be only in CVS)

Net_Whois::query() — does a whois query

funcsynopsis funcsynopsisinfo require_once 'Net/Whois.php'; /funcsynopsisinfo funcprototype funcdefstring Net_Whois::query()/funcdef paramdefstring $query /paramdef paramdefstring $server /paramdef /funcprototype /funcsynopsis

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

Example #1 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;
?>
Net_Whois
Net_Wifi
Net_Whois


Net_Wifi

Scans for wireless networks

Net_Whois::query()
Setup
Networking


Making it work

Net_Wifi
Local info
Net_Wifi
PHP Manual

Setup

(No version information available, might be only in CVS)

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().

Net_Wifi
Local info
Net_Wifi


Current interface configuration

Setup
Scanning
Net_Wifi
PHP Manual

Local info

(No version information available, might be only in CVS)

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"
}

Setup
Scanning
Net_Wifi


Net_Wifi
URI_Template
Net_Wifi
PHP Manual

Scanning

(No version information available, might be only in CVS)

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"
}

Net_Wifi
URI_Template
Net_Wifi


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.

Warning

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.

Networking
Introduction
Networking


Introduction to URI_Template

URI_Template
Numbers
URI_Template
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

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/ */
URI_Template
Numbers
URI_Template


Numbers

Table of Contents

  • Numbers_Roman

Provides Packages for working with numbers

Introduction
Numbers_Roman
Packages


Numbers_Roman

Numbers_Roman provides methods to convert Arabic numbers like 23 into Roman numerals like XXIII and back.

Note: Both class methods are static; you do not need to instantiate an object.

Converting Arabic to Roman Numerals

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 _.

Example #1 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
?>

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

Example #2 Converting Roman numerals to Arabic numbers

<?php
require_once 'Numbers/Roman.php';

echo Numbers_Roman::toNumber('XLII');
//returns: 42
?>
Numbers
Payment
Numbers


Payment

Provides Packages for payment-related standards and offerer

Numbers_Roman
PEAR
Packages


PEAR

Table of Contents

  • PEAR_Frontend_Gtk
  • PEAR_Frontend_Gtk2
  • PEAR_Info
  • PEAR_PackageFileManager
  • PEAR_PackageUpdate
  • PEAR_Size

Provides Packages to work with/get info from the PEAR core

Payment
PEAR_Frontend_Gtk
Packages


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.

PEAR
PEAR_Frontend_Gtk2
PEAR


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/.

PEAR_Frontend_Gtk
PEAR_Info
PEAR


PEAR_Info

Displays Information about your current PEAR install. Akin to PHP's » phpinfo().

Summary

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

System Requirements

Mandatory resources :

  • » PHP 4.3.0 or newer.

  • » PEAR 1.5.4 or newer.

Optional resources :

  • » PHPUnit 3.1.4 or newer.

About

Reference guide

PEAR_Frontend_Gtk2
FAQ
PEAR


Answers to most Frequently Asked Questions

Constants
PHP Manual

FAQ

(No version information available, might be only in CVS)

FAQ — Answers to most Frequently Asked Questions

PEAR_Info FAQ

  1. What does it cost ?
  2. Do you offer support ?
  3. I found a bug, what shall I do ?
  4. What is PEAR ?
  5. I want to display my system configuration, but this one is not detected ?
  6. I want to change the look an feel (colors) of PEAR_Info output ?
  7. I want to display packages from all my channels ?
  8. I want to check if a package is installed or not ?
qandadiv

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 » 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.

/qandadiv qandadiv

How to

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';
}
?>

/qandadiv
Constants


What is New in version ?

Constants
PHP Manual

News

(No version information available, might be only in CVS)

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.

Constants


Constants
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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();
?>
Constants


PHP 4 style constructor (ZE1)

Introduction
PHP Manual

constructor PEAR_Info::PEAR_Info()

(No version information available, might be only in CVS)

constructor — PHP 4 style constructor (ZE1)

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor PEAR_Info::PEAR_Info()/funcdef paramdefstring $pear_dir = '' /paramdef paramdefstring $user_file = '' /paramdef paramdefstring $system_file = '' /paramdef paramdefarray $options = NULL /paramdef /funcprototype /funcsynopsis

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().

/important

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();

?>

Introduction


Displays PEAR_Info output

Introduction
PHP Manual

PEAR_Info::display()

(No version information available, might be only in CVS)

— Displays PEAR_Info output

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Info::display()/funcdef paramdef /funcprototype /funcsynopsis

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()

Introduction


Returns a members list depending of its category (group, docs, website)

Introduction
PHP Manual

PEAR_Info::getMembers()

(No version information available, might be only in CVS)

— Returns a members list depending of its category (group, docs, website)

funcsynopsis funcsynopsisinforequire_once 'PEAR/Info.php';/funcsynopsisinfo funcprototype funcdef array PEAR_Info::getMembers() /funcdef paramdef string $group = 'all' /paramdef paramdef bool $sort = TRUE /paramdef /funcprototype /funcsynopsis

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.

Introduction


Returns the custom style sheet to use for presentation

Introduction
PHP Manual

PEAR_Info::getStyleSheet()

(No version information available, might be only in CVS)

— Returns the custom style sheet to use for presentation

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Info::getStyleSheet()/funcdef paramdefboolean $content = TRUE /paramdef /funcprototype /funcsynopsis

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 xmlns:xlink="http://www.w3.org/1999/xlink" rel="stylesheet" type="text/css" href="$styles" />
</head>
<body>

<div xml:id="header">
<h1>Laurent-Laville.org</h1>
</div>

<div xml:id="footer">
</div>

<div xml: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();
?>

Introduction


Check if a package is installed

Introduction
PHP Manual

PEAR_Info::packageInstalled()

(No version information available, might be only in CVS)

— Check if a package is installed

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Info::packageInstalled()/funcdef paramdefstring $name /paramdef paramdefstring $version = NULL /paramdef paramdefstring $channel = NULL /paramdef paramdefstring $user_file = '' /paramdef paramdefstring $system_file = '' /paramdef /funcprototype /funcsynopsis

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";
}
?>

Introduction


Display the PEAR logo

Introduction
PHP Manual

PEAR_Info::pearImage()

(No version information available, might be only in CVS)

— Display the PEAR logo

funcsynopsis funcsynopsisinforequire_once 'PEAR/Info.php';/funcsynopsisinfo funcprototype funcdef void PEAR_Info::pearImage() /funcdef paramdef /funcprototype /funcsynopsis

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.

Introduction


Sets PEAR HTTP Proxy Server Address

Introduction
PHP Manual

PEAR_Info::setProxy()

(No version information available, might be only in CVS)

— Sets PEAR HTTP Proxy Server Address

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Info::setProxy()/funcdef paramdefstring $proxy /paramdef /funcprototype /funcsynopsis

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.

Introduction


Sets the custom style sheet to use your own styles

Introduction
PHP Manual

PEAR_Info::setStyleSheet()

(No version information available, might be only in CVS)

— Sets the custom style sheet to use your own styles

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_Info::setStyleSheet()/funcdef paramdefstring $css = NULL /paramdef /funcprototype /funcsynopsis

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();
?>

Introduction


Shows PEAR_Info output

Introduction
PHP Manual

PEAR_Info::show()

(No version information available, might be only in CVS)

— Shows PEAR_Info output

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_Info::show()/funcdef paramdef /funcprototype /funcsynopsis

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()

Introduction


Returns PEAR_Info output (html code)

Introduction
PHP Manual

PEAR_Info::toHtml()

(No version information available, might be only in CVS)

— Returns PEAR_Info output (html code)

funcsynopsis funcsynopsisinfo require_once 'PEAR/Info.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_Info::toHtml()/funcdef paramdef /funcprototype /funcsynopsis

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()

Introduction


PEAR_PackageFileManager

PEAR_Info::toHtml
Class Summary PEAR_PackageFileManager
PEAR


PEAR :: PackageFileManager updates the

PEAR_PackageFileManager
constructor PEAR_PackageFileManager::PEAR_PackageFileManager
PEAR_PackageFileManager
PHP Manual

Class Summary PEAR_PackageFileManager

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_PackageFileManager
constructor PEAR_PackageFileManager::PEAR_PackageFileManager
PEAR_PackageFileManager


Does nothing, use setOptions

Class Summary PEAR_PackageFileManager
PEAR_PackageFileManager::addConfigureOption
PEAR_PackageFileManager
PHP Manual

constructor PEAR_PackageFileManager::PEAR_PackageFileManager()

(No version information available, might be only in CVS)

constructor — Does nothing, use setOptions

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor PEAR_PackageFileManager::PEAR_PackageFileManager()/funcdef paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_PackageFileManager
PEAR_PackageFileManager::addConfigureOption
PEAR_PackageFileManager


Add an install-time configuration option for building of source

constructor PEAR_PackageFileManager::PEAR_PackageFileManager
PEAR_PackageFileManager::addDependency
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addConfigureOption()

(No version information available, might be only in CVS)

— Add an install-time configuration option for building of source

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error PEAR_PackageFileManager::addConfigureOption()/funcdef paramdefstring $name /paramdef paramdefstring $prompt /paramdef paramdefstring $default = NULL /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_PackageFileManager::PEAR_PackageFileManager
PEAR_PackageFileManager::addDependency
PEAR_PackageFileManager


Add a dependency on another package, or an extension/php

PEAR_PackageFileManager::addConfigureOption
PEAR_PackageFileManager::addMaintainer
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addDependency()

(No version information available, might be only in CVS)

— Add a dependency on another package, or an extension/php

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error PEAR_PackageFileManager::addDependency()/funcdef paramdefstring $name /paramdef paramdefstring $version = FALSE /paramdef paramdefstring $operator = 'ge' /paramdef paramdefstring $type = 'pkg' /paramdef paramdefboolean $optional = FALSE /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addConfigureOption
PEAR_PackageFileManager::addMaintainer
PEAR_PackageFileManager


Add a maintainer to the list of maintainers.

PEAR_PackageFileManager::addDependency
PEAR_PackageFileManager::addPlatformException
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addMaintainer()

(No version information available, might be only in CVS)

— Add a maintainer to the list of maintainers.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::addMaintainer()/funcdef paramdefstring $handle /paramdef paramdeflead|developer|contributor|helper $role /paramdef paramdefstring $name /paramdef paramdefstring $email /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addDependency
PEAR_PackageFileManager::addPlatformException
PEAR_PackageFileManager


Add an install-time platform conditional install for a file

PEAR_PackageFileManager::addMaintainer
PEAR_PackageFileManager::addGlobalReplacement
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addPlatformException()

(No version information available, might be only in CVS)

— Add an install-time platform conditional install for a file

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::addPlatformException()/funcdef paramdefstring $path /paramdef paramdefstring $platform /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addMaintainer
PEAR_PackageFileManager::addGlobalReplacement
PEAR_PackageFileManager


Add a replacement option for all files

PEAR_PackageFileManager::addPlatformException
PEAR_PackageFileManager::addReplacement
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addGlobalReplacement()

(No version information available, might be only in CVS)

— Add a replacement option for all files

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::addglobalreplacement()/funcdef paramdefstring $type /paramdef paramdefstring $from /paramdef paramdefstring $to /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addPlatformException
PEAR_PackageFileManager::addReplacement
PEAR_PackageFileManager


Add a replacement option for a file

PEAR_PackageFileManager::addGlobalReplacement
PEAR_PackageFileManager::addRole
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addReplacement()

(No version information available, might be only in CVS)

— Add a replacement option for a file

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::addReplacement()/funcdef paramdefstring $path /paramdef paramdefstring $type /paramdef paramdefstring $from /paramdef paramdefstring $to /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addGlobalReplacement
PEAR_PackageFileManager::addRole
PEAR_PackageFileManager


Add an extension/role mapping to the role mapping option

PEAR_PackageFileManager::addReplacement
PEAR_PackageFileManager::detectDependencies
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::addRole()

(No version information available, might be only in CVS)

— Add an extension/role mapping to the role mapping option

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::addRole()/funcdef paramdefstring $extension /paramdef paramdefstring $role /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addReplacement
PEAR_PackageFileManager::detectDependencies
PEAR_PackageFileManager


use PHP_CompatInfo to auto-detect PHP and extension dependencies.

PEAR_PackageFileManager::addRole
PEAR_PackageFileManager::debugPackageFile
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::detectDependencies()

(No version information available, might be only in CVS)

— use PHP_CompatInfo to auto-detect PHP and extension dependencies.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error PEAR_PackageFileManager::detectDependencies()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::addRole
PEAR_PackageFileManager::debugPackageFile
PEAR_PackageFileManager


ALWAYS use this to test output before overwriting your package.xml!!

PEAR_PackageFileManager::detectDependencies
PEAR_PackageFileManager::getWarnings
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::debugPackageFile()

(No version information available, might be only in CVS)

— ALWAYS use this to test output before overwriting your package.xml!!

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::debugPackageFile()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::detectDependencies
PEAR_PackageFileManager::getWarnings
PEAR_PackageFileManager


Retrieve the list of warnings

PEAR_PackageFileManager::debugPackageFile
PEAR_PackageFileManager::isIncludeable
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::getWarnings()

(No version information available, might be only in CVS)

— Retrieve the list of warnings

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_PackageFileManager::getWarnings()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

PEAR_PackageFileManager::debugPackageFile
PEAR_PackageFileManager::isIncludeable
PEAR_PackageFileManager


calls http://www.php.net/file_exists for each value in include_path,

PEAR_PackageFileManager::getWarnings
PEAR_PackageFileManager::pushWarning
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::isIncludeable()

(No version information available, might be only in CVS)

— calls » http://www.php.net/file_exists for each value in include_path,

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageFileManager::isIncludeable()/funcdef paramdefstring $filename /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::getWarnings
PEAR_PackageFileManager::pushWarning
PEAR_PackageFileManager


Store a warning on the warning stack

PEAR_PackageFileManager::isIncludeable
PEAR_PackageFileManager::raiseError
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::pushWarning()

(No version information available, might be only in CVS)

— Store a warning on the warning stack

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid PEAR_PackageFileManager::pushWarning()/funcdef paramdefmixed $code /paramdef paramdefmixed $info /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::isIncludeable
PEAR_PackageFileManager::raiseError
PEAR_PackageFileManager


Utility function to shorten error generation code

PEAR_PackageFileManager::pushWarning
PEAR_PackageFileManager::setOptions
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::raiseError()

(No version information available, might be only in CVS)

— Utility function to shorten error generation code

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefPEAR_Error PEAR_PackageFileManager::raiseError()/funcdef paramdefmixed $code /paramdef paramdefmixed $i1 = '' /paramdef paramdefmixed $i2 = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::pushWarning
PEAR_PackageFileManager::setOptions
PEAR_PackageFileManager


Set package.xml generation options

PEAR_PackageFileManager::raiseError
PEAR_PackageFileManager::writePackageFile
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::setOptions()

(No version information available, might be only in CVS)

— Set package.xml generation options

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error PEAR_PackageFileManager::setOptions()/funcdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::raiseError
PEAR_PackageFileManager::writePackageFile
PEAR_PackageFileManager


Writes the package.xml file out with the newly created

PEAR_PackageFileManager::setOptions
Class Summary PEAR_PackageFileManager_CVS
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager::writePackageFile()

(No version information available, might be only in CVS)

— Writes the package.xml file out with the newly created <release></release> tag

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager.php'; /funcsynopsisinfo funcprototype funcdefvoid|PEAR_Error PEAR_PackageFileManager::writePackageFile()/funcdef paramdefboolean $debuginterface = NULL /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager::setOptions
Class Summary PEAR_PackageFileManager_CVS
PEAR_PackageFileManager


PEAR_PackageFileManager::writePackageFile
PEAR_PackageFileManager_CVS::dirList
PEAR_PackageFileManager
PHP Manual

Class Summary PEAR_PackageFileManager_CVS

(No version information available, might be only in CVS)

Class Summary — 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.

PEAR_PackageFileManager::writePackageFile
PEAR_PackageFileManager_CVS::dirList
PEAR_PackageFileManager


Return a list of all files in the CVS repository

Class Summary PEAR_PackageFileManager_CVS
Class Summary PEAR_PackageFileManager_File
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager_CVS::dirList()

(No version information available, might be only in CVS)

— Return a list of all files in the CVS repository

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager/Cvs.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_PackageFileManager_CVS::dirList()/funcdef paramdefstring $directory /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_PackageFileManager_CVS
Class Summary PEAR_PackageFileManager_File
PEAR_PackageFileManager


PEAR_PackageFileManager_CVS::dirList
constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File
PEAR_PackageFileManager
PHP Manual

Class Summary PEAR_PackageFileManager_File

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_PackageFileManager_CVS::dirList
constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File
PEAR_PackageFileManager


Set up the File filelist generator

Class Summary PEAR_PackageFileManager_File
PEAR_PackageFileManager_File::dirList
PEAR_PackageFileManager
PHP Manual

constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File()

(No version information available, might be only in CVS)

constructor — Set up the File filelist generator

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager/File.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File()/funcdef paramdefPEAR_PackageFileManager &$parent /paramdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

Class Summary PEAR_PackageFileManager_File
PEAR_PackageFileManager_File::dirList
PEAR_PackageFileManager


Retrieve a listing of every file in $directory and all subdirectories.

constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File
PEAR_PackageFileManager_File::getFileList
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager_File::dirList()

(No version information available, might be only in CVS)

— Retrieve a listing of every file in $directory and all subdirectories.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager/File.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_PackageFileManager_File::dirList()/funcdef paramdefstring $directory /paramdef /funcprototype /funcsynopsis

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.

constructor PEAR_PackageFileManager_File::PEAR_PackageFileManager_File
PEAR_PackageFileManager_File::getFileList
PEAR_PackageFileManager


Generate the

PEAR_PackageFileManager_File::dirList
Class Summary PEAR_PackageFileManager_XMLOutput
PEAR_PackageFileManager
PHP Manual

PEAR_PackageFileManager_File::getFileList()

(No version information available, might be only in CVS)

— Generate the <filelist></filelist> section of the package file.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageFileManager/File.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_PackageFileManager_File::getFileList()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageFileManager_File::dirList
Class Summary PEAR_PackageFileManager_XMLOutput
PEAR_PackageFileManager


PEAR_PackageFileManager_File::getFileList
Package PEAR_PackageFileManager Constants
PEAR_PackageFileManager
PHP Manual

Class Summary PEAR_PackageFileManager_XMLOutput

(No version information available, might be only in CVS)

Class Summary — 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

PEAR_PackageFileManager_File::getFileList
Package PEAR_PackageFileManager Constants
PEAR_PackageFileManager


Constants defined in and used by PEAR_PackageFileManager

Class Summary PEAR_PackageFileManager_XMLOutput
Package PEAR_PackageFileManager Global Variables
PEAR_PackageFileManager
PHP Manual

Package PEAR_PackageFileManager Constants

(No version information available, might be only in CVS)

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

Class Summary PEAR_PackageFileManager_XMLOutput
Package PEAR_PackageFileManager Global Variables
PEAR_PackageFileManager


Global Variables defined in and used by PEAR_PackageFileManager

PEAR_PackageFileManager
PEAR_PackageUpdate
PEAR_PackageFileManager
PHP Manual

Package PEAR_PackageFileManager Global Variables

(No version information available, might be only in CVS)

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

PEAR_PackageFileManager
PEAR_PackageUpdate
PEAR_PackageFileManager


PEAR_PackageUpdate

Package PEAR_PackageFileManager Global Variables
Introduction to PEAR_PackageUpdate
PEAR


A package to make adding self updating functionality to other packages or applications easy.

PEAR_PackageUpdate
PEAR_PackageUpdate::factory
PEAR_PackageUpdate
PHP Manual

Introduction to PEAR_PackageUpdate

(No version information available, might be only in CVS)

Introduction to — 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:

Warning

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();
                        }
                    }
                }
            }
        }
        // ...
    }
    // ...
}
?>

PEAR_PackageUpdate
PEAR_PackageUpdate::factory
PEAR_PackageUpdate


Factory method for creating PEAR_PackageUpdate frontend instances.

Introduction to PEAR_PackageUpdate
PEAR_PackageUpdate::isIncludable
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::factory

(No version information available, might be only in CVS)

PEAR_PackageUpdate::factory — Factory method for creating PEAR_PackageUpdate frontend instances.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_PackageUpdate::factory()/funcdef paramdefstring $driver /paramdef paramdefstring $packageName /paramdef paramdefstring $channel /paramdef paramdefstring $user_file = '' /paramdef paramdefstring $system_file = '' /paramdef paramdefstring $pref_file = '' /paramdef /funcprototype /funcsynopsis

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).

Introduction to PEAR_PackageUpdate
PEAR_PackageUpdate::isIncludable
PEAR_PackageUpdate


Determines whether or not a file is includable.

PEAR_PackageUpdate::factory
PEAR_PackageUpdate::loadPreferences
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::isIncludable

(No version information available, might be only in CVS)

PEAR_PackageUpdate::isIncludable — Determines whether or not a file is includable.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::isIncludable()/funcdef paramdefstring $path /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::factory
PEAR_PackageUpdate::loadPreferences
PEAR_PackageUpdate


Loads the user's preferences from the preference file.

PEAR_PackageUpdate::isIncludable
PEAR_PackageUpdate::determinePrefFile
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::loadPreferences

(No version information available, might be only in CVS)

PEAR_PackageUpdate::loadPreferences — Loads the user's preferences from the preference file.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::loadPreferences()/funcdef paramdefstring $pref_file = '' /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::isIncludable
PEAR_PackageUpdate::determinePrefFile
PEAR_PackageUpdate


Returns the path to the preferences file.

PEAR_PackageUpdate::loadPreferences
PEAR_PackageUpdate::checkUpdate
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::determinePrefFile

(No version information available, might be only in CVS)

PEAR_PackageUpdate::determinePrefFile — Returns the path to the preferences file.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_PackageUpdate::determinePrefFile()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::loadPreferences
PEAR_PackageUpdate::checkUpdate
PEAR_PackageUpdate


Checks to see if an update is available and the user has asked not to be notified about the update.

PEAR_PackageUpdate::determinePrefFile
PEAR_PackageUpdate::getPackageInfo
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::checkUpdate

(No version information available, might be only in CVS)

PEAR_PackageUpdate::checkUpdate — Checks to see if an update is available and the user has asked not to be notified about the update.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::checkUpdate()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::determinePrefFile
PEAR_PackageUpdate::getPackageInfo
PEAR_PackageUpdate


Loads the latest package information from the channel server.

PEAR_PackageUpdate::checkUpdate
PEAR_PackageUpdate::getPackagePreferences
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::getPackageInfo

(No version information available, might be only in CVS)

PEAR_PackageUpdate::getPackageInfo — Loads the latest package information from the channel server.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::getPackageInfo()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::checkUpdate
PEAR_PackageUpdate::getPackagePreferences
PEAR_PackageUpdate


Returns the update preferences for the current package.

PEAR_PackageUpdate::getPackageInfo
PEAR_PackageUpdate::savePreferences
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::getPackagePreferences

(No version information available, might be only in CVS)

PEAR_PackageUpdate::getPackagePreferences — Returns the update preferences for the current package.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_PackageUpdate::getPackagePreferences()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::getPackageInfo
PEAR_PackageUpdate::savePreferences
PEAR_PackageUpdate


Saves the user preferences to the preference file.

PEAR_PackageUpdate::getPackagePreferences
PEAR_PackageUpdate::preferencesAllowUpdate
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::savePreferences

(No version information available, might be only in CVS)

PEAR_PackageUpdate::savePreferences — Saves the user preferences to the preference file.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::savePreferences()/funcdef paramdefstring $pref_file = '' /paramdef /funcprototype /funcsynopsis

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()

PEAR_PackageUpdate::getPackagePreferences
PEAR_PackageUpdate::preferencesAllowUpdate
PEAR_PackageUpdate


Checks whether or not the user's preferences allow an update to the latest version of the package.

PEAR_PackageUpdate::savePreferences
PEAR_PackageUpdate::releaseType
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::preferencesAllowUpdate

(No version information available, might be only in CVS)

PEAR_PackageUpdate::preferencesAllowUpdate — Checks whether or not the user's preferences allow an update to the latest version of the package.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::preferencesAllowUpdate()/funcdef paramdef /funcprototype /funcsynopsis

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()

PEAR_PackageUpdate::savePreferences
PEAR_PackageUpdate::releaseType
PEAR_PackageUpdate


Returns the release type of the most recent version of the package compared to the installed version.

PEAR_PackageUpdate::preferencesAllowUpdate
PEAR_PackageUpdate::getInstalledRelease
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::releaseType

(No version information available, might be only in CVS)

PEAR_PackageUpdate::releaseType — Returns the release type of the most recent version of the package compared to the installed version.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefstring PEAR_PackageUpdate::releaseType()/funcdef paramdef /funcprototype /funcsynopsis

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).

PEAR_PackageUpdate::preferencesAllowUpdate
PEAR_PackageUpdate::getInstalledRelease
PEAR_PackageUpdate


Loads the latest package information from the current installation.

PEAR_PackageUpdate::releaseType
PEAR_PackageUpdate::getLatestRelease
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::getInstalledRelease

(No version information available, might be only in CVS)

PEAR_PackageUpdate::getInstalledRelease — Loads the latest package information from the current installation.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_PackageUpdate::getInstalledRelease()/funcdef paramdef /funcprototype /funcsynopsis

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).

PEAR_PackageUpdate::releaseType
PEAR_PackageUpdate::getLatestRelease
PEAR_PackageUpdate


Loads the latest package information from the channel server.

PEAR_PackageUpdate::getInstalledRelease
PEAR_PackageUpdate::setDontAskAgain
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::getLatestRelease

(No version information available, might be only in CVS)

PEAR_PackageUpdate::getLatestRelease — Loads the latest package information from the channel server.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefmixed PEAR_PackageUpdate::getLatestRelease()/funcdef paramdef /funcprototype /funcsynopsis

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).

PEAR_PackageUpdate::getInstalledRelease
PEAR_PackageUpdate::setDontAskAgain
PEAR_PackageUpdate


Sets the user's "Don't Ask Again" preference for the package.

PEAR_PackageUpdate::getLatestRelease
PEAR_PackageUpdate::setDontAskUntilNextRelease
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::setDontAskAgain

(No version information available, might be only in CVS)

PEAR_PackageUpdate::setDontAskAgain — Sets the user's "Don't Ask Again" preference for the package.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::setDontAskAgain()/funcdef paramdefboolean $dontAsk /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::getLatestRelease
PEAR_PackageUpdate::setDontAskUntilNextRelease
PEAR_PackageUpdate


Sets the user's "Don't Ask Again Until Next Release" preference for the package.

PEAR_PackageUpdate::setDontAskAgain
PEAR_PackageUpdate::setMinimumReleaseType
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::setDontAskUntilNextRelease

(No version information available, might be only in CVS)

PEAR_PackageUpdate::setDontAskUntilNextRelease — Sets the user's "Don't Ask Again Until Next Release" preference for the package.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::setDontAskUntilNextRelease()/funcdef paramdefboolean $dontAsk /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::setDontAskAgain
PEAR_PackageUpdate::setMinimumReleaseType
PEAR_PackageUpdate


Sets the user's preference for asking about release types.

PEAR_PackageUpdate::setDontAskUntilNextRelease
PEAR_PackageUpdate::setMinimumState
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::setMinimumReleaseType

(No version information available, might be only in CVS)

PEAR_PackageUpdate::setMinimumReleaseType — Sets the user's preference for asking about release types.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::setMinimumReleaseType()/funcdef paramdefstring $minType /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::setDontAskUntilNextRelease
PEAR_PackageUpdate::setMinimumState
PEAR_PackageUpdate


Sets the user's preference for asking about release states.

PEAR_PackageUpdate::setMinimumReleaseType
PEAR_PackageUpdate::setPreference
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::setMinimumState

(No version information available, might be only in CVS)

PEAR_PackageUpdate::setMinimumState — Sets the user's preference for asking about release states.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::setMinimumState()/funcdef paramdefstring $minState /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::setMinimumReleaseType
PEAR_PackageUpdate::setPreference
PEAR_PackageUpdate


Sets the given preference to the given value.

PEAR_PackageUpdate::setMinimumState
PEAR_PackageUpdate::setPreferences
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::setPreference

(No version information available, might be only in CVS)

PEAR_PackageUpdate::setPreference — Sets the given preference to the given value.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::setPreference()/funcdef paramdefstring $pref /paramdef paramdefstring $value /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::setMinimumState
PEAR_PackageUpdate::setPreferences
PEAR_PackageUpdate


Sets all preferences at once.

PEAR_PackageUpdate::setPreference
PEAR_PackageUpdate::update
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::setPreferences

(No version information available, might be only in CVS)

PEAR_PackageUpdate::setPreferences — Sets all preferences at once.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::setPreferences()/funcdef paramdefarray $preferences /paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::setPreference
PEAR_PackageUpdate::update
PEAR_PackageUpdate


Updates the source for the package.

PEAR_PackageUpdate::setPreferences
PEAR_PackageUpdate::popError
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::update

(No version information available, might be only in CVS)

PEAR_PackageUpdate::update — Updates the source for the package.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::update()/funcdef paramdef /funcprototype /funcsynopsis

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.

PEAR_PackageUpdate::setPreferences
PEAR_PackageUpdate::popError
PEAR_PackageUpdate


Pops an error off the error stack.

PEAR_PackageUpdate::update
PEAR_PackageUpdate::hasErrors
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::popError

(No version information available, might be only in CVS)

PEAR_PackageUpdate::popError — Pops an error off the error stack.

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefarray PEAR_PackageUpdate::popError()/funcdef paramdef /funcprototype /funcsynopsis

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()

PEAR_PackageUpdate::update
PEAR_PackageUpdate::hasErrors
PEAR_PackageUpdate


Returns whether or not errors have occurred (and been captured).

PEAR_PackageUpdate
PEAR_Size
PEAR_PackageUpdate
PHP Manual

PEAR_PackageUpdate::hasErrors

(No version information available, might be only in CVS)

PEAR_PackageUpdate::hasErrors — Returns whether or not errors have occurred (and been captured).

funcsynopsis funcsynopsisinfo require_once 'PEAR/PackageUpdate.php'; /funcsynopsisinfo funcprototype funcdefboolean PEAR_PackageUpdate::hasErrors()/funcdef paramdefmixed $level = FALSE /paramdef /funcprototype /funcsynopsis

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()

PEAR_PackageUpdate
PEAR_Size
PEAR_PackageUpdate


PEAR_Size

The pearsize script 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.

PEAR
Introduction
PEAR


PEAR_Size
Re-using PEAR_Size
PEAR_Size
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

PEAR_Size
Re-using PEAR_Size
PEAR_Size


Embedding it in your own application

PEAR_Size
PHP
PEAR_Size
PHP Manual

Re-using PEAR_Size

(No version information available, might be only in CVS)

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 which 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.

PEAR_Size
PHP
PEAR_Size


PHP

Table of Contents

  • PHP_Archive
  • phpDocumentor
  • PHP_CodeSniffer
  • PHP_Compat
  • PHP_CompatInfo
  • PHP_FunctionCallTracer
  • PHPUnit
  • PHPUnit2

Tools to help your development process.

Re-using PEAR_Size
PHP_Archive
Packages


PHP_Archive

The PHP_Archive package allows creation of self-contained cross-platform PHP libraries or applications, similar to Java jar files. PHP_Archive

PHP
Introduction
PHP


The PHP_Archive package allows creation of self-contained cross-platform PHP libraries or applications, similar to Java jar files.

PHP_Archive
phpDocumentor
PHP_Archive
PHP Manual

Introduction

(No version information available, might be only in CVS)

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
PHP_Archive
phpDocumentor
PHP_Archive


phpDocumentor

The phpDocumentor package provides automatic documenting of php api directly from the source.

Introduction
Introduction
PHP


The phpDocumentor package provides automatic documenting of PHP code API directly from the source.

phpDocumentor
PHP_CodeSniffer
phpDocumentor
PHP Manual

Introduction

(No version information available, might be only in CVS)

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
phpDocumentor
PHP_CodeSniffer
phpDocumentor


PHP_CodeSniffer

PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP code to detect violations of a defined set of coding standards. It is an essential development tool that ensures that your code remains clean and consistent. It can even help prevent some common semantic errors made by developers.

Introduction
Introduction
PHP


Description and simple usage example

PHP_CodeSniffer
Usage
PHP_CodeSniffer
PHP Manual

Introduction

(No version information available, might be only in CVS)

Introduction — Description and simple usage example

Description

PHP_CodeSniffer is a PHP5 script that tokenises and "sniffs" PHP code to detect violations of a defined set of coding standards. It is an essential development tool that ensures that your code remains clean and consistent. It can even 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.

Example #1 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.

Example #2 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
--------------------------------------------------------------------------------
PHP_CodeSniffer
Usage
PHP_CodeSniffer


Standard usage information

Introduction
Advanced Usage
PHP_CodeSniffer
PHP Manual

Usage

(No version information available, might be only in CVS)

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 [-nwlvi] [--report=<report>] [--standard=<standard>]
    [--config-set key value] [--config-delete key] [--config-show]
    [--generator=<generator>] [--extensions=<extensions>]
    [--ignore=<patterns>] [--tab-width=<width>] <file> ...
        -n           Do not print warnings
        -w           Print both warnings and errors (on by default)
        -l           Local directory only, no recursion
        -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
        <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" or "summary" report
                     (the "full" report is printed by default)

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.

Example #1 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.

Example #2 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:

Example #3 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.

Example #4 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:

Example #5 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.

Example #6 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:

Example #7 Sample PHP_CodeSniffer verbose output

$ phpcs /path/to/code/CodeSniffer -v
Registering sniffs... DONE (22 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).

Example #8 Specifying a coding standard to use

$ phpcs --standard=PEAR /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.

Example #9 Generating a list of installed coding standards

$ phpcs -i
The installed coding standards are MySource, PEAR, PHPCS and Squiz.
Introduction
Advanced Usage
PHP_CodeSniffer


Advanced usage information

Usage
Configuration Options
PHP_CodeSniffer
PHP Manual

Advanced Usage

(No version information available, might be only in CVS)

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.

Example #1 Checking .php files only

$ phpcs --extensions=php /path/to/code

Example #2 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.

Example #3 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.

Example #4 Ignoring test and data files

$ phpcs --ignore=*/tests/*,*/data/* /path/to/code

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.

Example #5 Converting tabs to spaces

$ phpcs --tab-width=4 /path/to/code

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:

Example #6 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="5" warnings="1">
  <error line="2" column="1">Missing file doc comment</error>
  <error line="20" column="43">PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;</error>
  <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error>
  <warning line="47" column="20">Equals sign not aligned with surrounding assignments</warning>
  <error line="51" column="4">Missing function doc comment</error>
  <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error>
 </file>
</phpcs>

As with the full report, you can suppress the printing of warnings with the -n command line argument.

Example #7 Sample PHP_CodeSniffer XML output with no warnings

$ phpcs -n --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="5" warnings="0">
  <error line="2" column="1">Missing file doc comment</error>
  <error line="20" column="43">PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;</error>
  <error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error>
  <error line="51" column="4">Missing function doc comment</error>
  <error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</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:

Example #8 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"/>
  <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;"/>
  <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/>
  <error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments"/>
  <error line="51" column="4" severity="error" message="Missing function doc comment"/>
  <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/>
 </file>
</checkstyle>

As with the full report, you can suppress the printing of warnings with the -n command line argument.

Example #9 Sample PHP_CodeSniffer Checkstyle output with no warnings

$ phpcs -n --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"/>
  <error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected &quot;false&quot; but found &quot;FALSE&quot;"/>
  <error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/>
  <error line="51" column="4" severity="error" message="Missing function doc comment"/>
  <error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/>
 </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:

Example #10 Sample PHP_CodeSniffer CSV output

$ phpcs --report=csv /path/to/code

File,Line,Column,Severity,Message
"/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"
"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6"

As with the full report, you can suppress the printing of warnings with the -n command line argument.

Example #11 Sample PHP_CodeSniffer CSV output with no warnings

$ phpcs -n --report=csv /path/to/code

File,Line,Column,Severity,Message
"/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",51,4,error,"Missing function doc comment"
"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6"

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.

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.

Example #12 Setting a configuration option

$ phpcs --config-set  <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.

Example #13 Deleting a configuration option

$ phpcs --config-delete

Viewing Configuration Options

To view the currently set configuration options, use the --config-show command line argument.

Example #14 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:

Example #15 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:

Example #16 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:

Example #17 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.

Usage
Configuration Options
PHP_CodeSniffer


A list of configuration options

Advanced Usage
Coding Standard Tutorial
PHP_CodeSniffer
PHP Manual

Configuration Options

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.

Example #3 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.

Example #4 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.

Example #5 Disabling the replacement of tabs with spaces

$ phpcs --tab-width=0 /path/to/code

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.

Example #6 Setting the path to Zend Code Analyzer

$ phpcs --config-set zend_ca_path /path/to/ZendCodeAnalyzer
Advanced Usage
Coding Standard Tutorial
PHP_CodeSniffer


A guide to writing your own code sniffs

Configuration Options
Coding Standard Class Methods
PHP_CodeSniffer
PHP Manual

Coding Standard Tutorial

(No version information available, might be only in CVS)

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 inside PHP_CodeSniffer 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:

$ cd /path/to/PHP_CodeSniffer/CodeSniffer/Standards
$ mkdir MyStandard
$ mkdir MyStandard/Sniffs

The MyStandard directory represents our coding standard and is the name we will use on the command line to specify the new coding standard to use for checking. 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 /path/to/PHP_CodeSniffer/CodeSniffer/Standards/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.6 2007/10/15 03:28:17 squiz Exp $
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

require_once 'PHP/CodeSniffer/Standards/CodingStandard.php';

/**
 * 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 /path/to/PHP_CodeSniffer/CodeSniffer/Standards/MyStandard/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 the 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 may wish 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 (eg. '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 list of tokens and their axillary indicies.

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
/**
 * PHP_CodeSniffer tokenises PHP code and detects violations of a
 * defined set of coding standards.
 *
 * 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.6 2007/10/15 03:28:17 squiz Exp $
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

require_once 'PHP/CodeSniffer/Sniff.php';

/**
 * 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

?>

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=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
--------------------------------------------------------------------------------

Configuration Options
Coding Standard Class Methods
PHP_CodeSniffer


Information about overriding coding standard class methods

Coding Standard Tutorial
FAQ
PHP_CodeSniffer
PHP Manual

Coding Standard Class Methods

(No version information available, might be only in CVS)

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()
?>

Coding Standard Tutorial
FAQ
PHP_CodeSniffer


Frequently asked questions

PHP_CodeSniffer
PHP_Compat
PHP_CodeSniffer
PHP Manual

FAQ

(No version information available, might be only in CVS)

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 tell if your code contains parse errors. PHP_CodeSniffer may return an incorrect number of errors if 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 a couple of sample coding standards to help developers get started on projects where they do not have a standard. If you want to write your own standards, 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 we 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 PHP code?

PHP_CodeSniffer uses » PHP's inbuilt tokenizer functions to parse your PHP code.

PHP_CodeSniffer
PHP_Compat
PHP_CodeSniffer


PHP_Compat

Provides missing functionality for older versions of PHP.

FAQ
Introduction
PHP


Purpose and simple usage example

PHP_Compat
Components
PHP_Compat
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Loading a component with PHP_Compat:

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.

Example #2 Loading a component manually:

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.

PHP_Compat
Components
PHP_Compat


List of replicated components

Introduction
Advanced usage
PHP_Compat
PHP Manual

Components

(No version information available, might be only in CVS)

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
Introduction
Advanced usage
PHP_Compat


Describe techniques for advanced usage

Components
PHP_Compat::loadFunction
PHP_Compat
PHP Manual

Advanced usage

(No version information available, might be only in CVS)

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.

Components
PHP_Compat::loadFunction
PHP_Compat


Load a function, or an array of functions

Advanced usage
PHP_Compat::loadConstant
PHP_Compat
PHP Manual

PHP_Compat::loadFunction()

(No version information available, might be only in CVS)

— Load a function, or an array of functions

funcsynopsis funcsynopsisinfo require_once 'PHP/Compat.php'; /funcsynopsisinfo funcprototype funcdefmixed PHP_Compat::loadFunction()/funcdef paramdefmixed $function /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Example #2 Loading a function manually:

<?php
require_once 'PHP/Compat/Function/file_put_contents.php';
?>

Note

This function should be called statically.

Advanced usage
PHP_Compat::loadConstant
PHP_Compat


Load a constant, or an array of constants

PHP_Compat::loadFunction
PHP_Compat::loadVersion
PHP_Compat
PHP Manual

PHP_Compat::loadConstant()

(No version information available, might be only in CVS)

— Load a constant, or an array of constants

funcsynopsis funcsynopsisinfo require_once 'PHP/Compat.php'; /funcsynopsisinfo funcprototype funcdefmixed PHP_Compat::loadConstant()/funcdef paramdefmixed $constant /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Example #2 Loading a constant manually:

<?php
require_once 'PHP/Compat/Constant/E_STRICT.php';
?>

Note

This function should be called statically.

PHP_Compat::loadFunction
PHP_Compat::loadVersion
PHP_Compat


Load all components, or all components until a given version of PHP

PHP_Compat
PHP_CompatInfo
PHP_Compat
PHP Manual

PHP_Compat::loadVersion()

(No version information available, might be only in CVS)

— Load all components, or all components until a given version of PHP

funcsynopsis funcsynopsisinfo require_once 'PHP/Compat.php'; /funcsynopsisinfo funcprototype funcdefarray PHP_Compat::loadVersion()/funcdef paramdefstring $version /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Example #2 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.

PHP_Compat
PHP_CompatInfo
PHP_Compat


PHP_CompatInfo

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

Summary

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

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::XML_Util 1.1.4 or newer.

  • » PEAR::File_Find 1.3.0 or newer.

  • » tokenizer extension.

Optional resources :

  • » PHPUnit 3.2.0 or newer.

  • » PEAR::XML_Beautifier 1.1 or newer.

  • » PEAR::Console_ProgressBar 0.5.2beta or newer.

About

Reference guide

PHP_Compat::loadVersion
FAQ
PHP


Answers to most Frequently Asked Questions

PEAR_Info::toHtml
PHP Manual

FAQ

(No version information available, might be only in CVS)

FAQ — Answers to most Frequently Asked Questions

PHP_CompatInfo FAQ

  1. What does it cost ?
  2. Do you offer support ?
  3. I found a bug, what shall i do ?
  4. What is PEAR ?
  5. I have a compatible PHP4/5 application with optional PHP5 code. How to ignore only PHP 5 code ?
qandadiv

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 » 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.

/qandadiv qandadiv

How to do

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);
?>

/qandadiv
PEAR_Info::toHtml


What is New in version ?

PEAR_Info::toHtml
PHP Manual

News

(No version information available, might be only in CVS)

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)

    Warning

    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

  • Show a progress bar when parsing directories from CLI

  • Support of error_reporting constant E_RECOVERABLE_ERROR introduced with PHP 5.2.0

PEAR_Info::toHtml


The console command

PHP_Compat::loadVersion
PHP Manual

CLI

(No version information available, might be only in CVS)

CLI — The console command

Switchs

The PHP_CompatInfo_Cli class, also known under it's wrapper name "pci", get the compatibility info from PHP Command Line Interpreter, on existing script or folder.

Overview

pci [options]  -f FILE | -d DIR | -s STRING
Usage is to run pci with at least the -s (--string), -f (--file) or -d (--dir) switch and perharps some additional and optional options.

Reference

-d | --dir

Identify the directory to parse to get compatibility info of its files contents.

-f | --file

Identify the file name (path) to parse to get compatibility info.

-s | --string

Content of a simple php code string without script tags <?php ... ?>

-n | --no-recurse

Do not recursively parse files into subdirectories when using --dir .

-v | --verbose

Set the verbose level. From 0 (no extra information) to 7 (full extra details).

In level 0, pci give only results related to -d or -f. See first line of the console table. If there are more than one line, next ones are details for each file of a directory/branch.

+-----------------------------+---------+---+------------+--------------------+
| Path                        | Version | C | Extensions | Constants/Tokens   |
+-----------------------------+---------+---+------------+--------------------+
| ...amp\tmp\HTML_CSS-1.5.1\* | 5.0.0   | 5 | pcre       | __FILE__           |
|                             |         |   | date       | ...CTORY_SEPARATOR |
|                             |         |   |            | PHP_EOL            |
|                             |         |   |            | public             |
|                             |         |   |            | protected          |
+-----------------------------+---------+---+------------+--------------------+
| ...p\HTML_CSS-1.5.1\CSS.php | 5.0.0   | 1 | pcre       |                    |
|                             |         |   | date       |                    |
+-----------------------------+---------+---+------------+--------------------+
| ...1.5.1\tests\AllTests.php | 5.0.0   | 4 |            | __FILE__           |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...L_CSS_TestSuite_Bugs.php | 5.0.0   | 4 |            | protected          |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...S_TestSuite_Standard.php | 5.0.0   | 4 |            | __FILE__           |
|                             |         |   |            | ...CTORY_SEPARATOR |
|                             |         |   |            | protected          |
|                             |         |   |            | public             |
+-----------------------------+---------+---+------------+--------------------+
| ...xamples\CSS_Advanced.php | 3.0.0   | 0 |            |                    |
+-----------------------------+---------+---+------------+--------------------+

In level 1, pci give results of level 0 with a summary of command line arguments. For example

pci -v 1 -d C:\wamp\tmp\HTML_CSS-1.5.1
give table of level 0 (see previous), plus :
Command Line resume :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+
| verbose                 | 1                                                 |
| dir                     | C:\wamp\tmp\HTML_CSS-1.5.1                        |
+-------------------------+---------------------------------------------------+

In level 2, pci give results of level 0 with the list of options used to parse file or directory. For example

pci -v 2 -d C:\wamp\tmp\HTML_CSS-1.5.1
give table of level 0 (see previous), plus :
Parser options :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+
| debug                   | FALSE                                             |
+-------------------------+---------------------------------------------------+

Note: Even when none option are used, the summary table is displayed.

In level 3, pci give results of level 0, 1 and 2. For example

pci -v 3 -n -d C:\wamp\tmp\HTML_CSS-1.5.1
give table of level 0 (see previous), plus :
Command Line resume :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+
| verbose                 | 3                                                 |
| no-recurse              | 1                                                 |
| dir                     | C:\wamp\tmp\HTML_CSS-1.5.1                        |
+-------------------------+---------------------------------------------------+

Parser options :

+-------------------------+---------------------------------------------------+
| Option                  | Value                                             |
+-------------------------+---------------------------------------------------+
| debug                   | FALSE                                             |
| recurse_dir             | FALSE                                             |
+-------------------------+---------------------------------------------------+

In level 4, useless when using --dir , pci give results of level 0 with a list of functions implemented and their versions. For example

pci -v 4 -f C:\wamp\tmp\HTML_CSS-1.5.1\CSS.php
give :
+-----------------------------+---------+---+------------+--------------------+
| File                        | Version | C | Extensions | Constants/Tokens   |
+-----------------------------+---------+---+------------+--------------------+
| ...p\HTML_CSS-1.5.1\CSS.php | 5.0.0   | 1 | pcre       |                    |
|                             |         |   | date       |                    |
+-----------------------------+---------+---+------------+--------------------+

Debug:

+---------+----------------------+-----------+------+
| Version | Function             | Extension | PECL |
+---------+----------------------+-----------+------+
| 4.0.0   | define               |           | no   |
| 4.0.0   | is_array             |           | no   |
| 4.0.0   | strtolower           |           | no   |
| 4.0.0   | substr               |           | no   |
... (more lines not displayed here) ...
| 4.0.0   | func_get_args        |           | no   |
| 4.0.4   | call_user_func_array |           | no   |
| 4.0.6   | is_callable          |           | no   |
| 4.0.7   | version_compare      |           | no   |
| 4.3.0   | debug_backtrace      |           | no   |
| 5.0.0   | file_put_contents    |           | no   |
+---------+----------------------+-----------+------+

Level 5 is equivalent to level 4 + level 1.

Level 6 is equivalent to level 4 + level 2.

And finally, level 7 is equivalent to level 4 + level 2 + level 1.

-if | --ignore-files

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

-id | --ignore-dirs

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

-in | --ignore-functions

Identify the file name (path) to a text file that contains on each line the name of each PHP function to ignore when parsing a directory or a single file.

-ic | --ignore-constants

Identify the file name (path) to a text file that contains on each line the name of each PHP constant to ignore when parsing a directory or a single file.

-ie | --ignore-extensions

Identify the file name (path) to a text file that contains on each line the name of each PHP extension to ignore (all extension.functions) when parsing a directory or a single file.

-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 | -d DIR  -iv 5.0.0 5.2.0
pci -f FILE | -d DIR  -iv 5.0.0

-inm | --ignore-functions-match

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

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 file name (path) to a text file that contains on each line a pattern (match a regular expression) of PHP extension to ignore when parsing a directory, a single file, or a string.

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 file name (path) to a 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.

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.

-h | --help

Show full help usage with all switchs explained.

-r | --report

Print either an xml or text report (default).

For example:

pci -r xml -f C:\wamp\tmp\PHP_CodeSniffer-1.0.1\CodeSniffer.php
give these results (when package XML_Beautifier is available)

<?xml version="1.0" encoding="UTF-8"?>
<pci version="1.7.0">
 <files count="1">
  <file name="C:\wamp\tmp\PHP_CodeSniffer-1.0.1\CodeSniffer.php">
   <version>5.1.2</version>
   <conditions level="0" />
   <extensions count="5">
    <extension>spl</extension>
    <extension>pcre</extension>
    <extension>date</extension>
    <extension>xml</extension>
    <extension>tokenizer</extension>
   </extensions>
   <constants count="3">
    __FILE__
    PHP_EOL
    DIRECTORY_SEPARATOR
   </constants>
   <tokens count="3">
    <token>throw</token>
    <token>protected</token>
    <token>public</token>
   </tokens>
   <ignored>
    <functions count="0" />
    <extensions count="0" />
    <constants count="0" />
   </ignored>
  </file>
 </files>
</pci>
And with little debug option ( -v4 )
pci -r xml -v4 -f C:\wamp\php\PEAR\PHP\CodeSniffer.php
results became

<?xml version="1.0" encoding="UTF-8"?>
<pci version="1.7.0">
 <files count="1">
  <file name="C:\wamp\tmp\PHP_CodeSniffer-1.0.1\CodeSniffer.php">
   <version>5.1.2</version>
   <conditions count="0" level="0" />
   <extensions count="5">
    <extension>spl</extension>
    <extension>pcre</extension>
    <extension>date</extension>
    <extension>xml</extension>
    <extension>tokenizer</extension>
   </extensions>
   <constants count="3">
    __FILE__
    PHP_EOL
    DIRECTORY_SEPARATOR
   </constants>
   <tokens count="3">
    <token>throw</token>
    <token>protected</token>
    <token>public</token>
   </tokens>
   <ignored>
    <functions count="0" />
    <extensions count="0" />
    <constants count="0" />
   </ignored>
   <functions count="40">
    <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">is_dir</function>
    <function version="4.0.0">basename</function>
    <function version="4.0.0">realpath</function>
    <function version="4.0.0">count</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">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>
  </file>
 </files>
</pci>

-fe | --file-ext

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

PHP_Compat::loadVersion


Application Programming Interface

PHP_Compat::loadVersion
PHP Manual

API

(No version information available, might be only in CVS)

API — Application Programming Interface

Parsing data sources

You can parse multiple data sources :

  • A single file with PHP_CompatInfo::parseFile() .

  • A chunk of code into a string with PHP_CompatInfo::parseString() .

  • A full directory (with or without sub dir) with PHP_CompatInfo::parseDir() , or its alias PHP_CompatInfo::parseFolder() .

  • A mix of files and strings with PHP_CompatInfo::parseArray() .

Call one of these five functions, with or without options, and you will retrieve a hash which contains information:

  • ignored_functions, PHP functions list that were ignored during source code parsing.

  • ignored_extensions, PHP extensions list that were ignored during source code parsing.

  • ignored_constants, PHP constants list that were ignored during source code parsing.

  • max_version, maximum PHP version to run source code.

  • version, minimum PHP version to run source code.

  • extensions, PHP modules/extensions functions found in source code.

  • constants, PHP constants found in source code.

  • tokens, PHP5 tokens (public, final, abstract, etc )

  • cond_code, A level (and details) of warning about conditional code found during parsing source code: from 0=none, 1=function_exists, 2=extension_loaded, 4=defined

    Its binary value, so 5 means defined+function_exists, and so on ...

Parser options

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

Excludes from scope all functions that match (full or partially) the pattern(s).

ignore_extensions_match

Excludes from scope all extensions that match (full or partially) the pattern(s).

ignore_constants_match

Excludes from scope all constants that match (full or partially) the pattern(s).

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.

PHP_Compat::loadVersion


Load components list

PHP_Compat::loadVersion
PHP Manual

PHP_CompatInfo::loadVersion()

(No version information available, might be only in CVS)

— Load components list

funcsynopsis funcsynopsisinfo require_once 'PHP/CompatInfo.php'; /funcsynopsisinfo funcprototype funcdefarray PHP_CompatInfo::loadVersion()/funcdef paramdefstring $min /paramdef paramdefstring|boolean $max = FALSE /paramdef paramdefboolean $include_const = FALSE /paramdef /funcprototype /funcsynopsis

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

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 24 functions
array (
  0 => 'cachingiterator::count',
  1 => 'directoryiterator::getbasename',
  2 => 'imagegrabscreen',
  3 => 'imagegrabwindow',
  4 => 'ming_setswfcompression',
  5 => 'mysql_set_charset',
  6 => 'openssl_pkcs12_export',
  7 => 'openssl_pkcs12_export_to_file',
  8 => 'openssl_pkcs12_read',
  9 => 'php_ini_loaded_file',
  10 => 'reflectionextension::info',
  11 => 'regexiterator::setpregflags',
  12 => 'splfileinfo::getbasename',
  13 => 'splfileinfo::getlinktarget',
  14 => 'splfileinfo::getrealpath',
  15 => 'splobjectstorage::serialize',
  16 => 'splobjectstorage::unserialize',
  17 => 'stream_is_local',
  18 => 'stream_socket_shutdown',
  19 => 'swfmovie::namedanchor',
  20 => 'swfmovie::protect',
  21 => 'swfmovie::remove',
  22 => 'sys_get_temp_dir',
  23 => 'tidynode::getparent',
)

PHP_Compat::loadVersion


Parse an Array of Files

PHP_Compat::loadVersion
PHP Manual

PHP_CompatInfo::parseArray()

(No version information available, might be only in CVS)

— Parse an Array of Files

funcsynopsis funcsynopsisinfo require_once 'PHP/CompatInfo.php'; /funcsynopsisinfo funcprototype funcdef array|false PHP_CompatInfo::parseArray()/funcdef paramdefarray $files /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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

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);
?>

We get such result.

array (
  'ignored_files' =>
  array (
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '4.3.0',
  'extensions' =>
  array (
    0 => 'sapi_cgi',
    1 => 'pcre',
    2 => 'tokenizer',
  ),
  'constants' =>
  array (
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 7,
    1 =>
    array (
      0 =>
      array (
      ),
      1 =>
      array (
      ),
      2 =>
      array (
      ),
    ),
  ),
  '/opt/lampp/etc/pear/PEAR.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.0',
    'extensions' =>
    array (
      0 => 'sapi_cgi',
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 7,
      1 =>
      array (
        0 =>
        array (
        ),
        1 =>
        array (
        ),
        2 =>
        array (
        ),
      ),
    ),
  ),
  '/opt/lampp/etc/pear/PHP/CompatInfo.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.0',
    'extensions' =>
    array (
      0 => 'pcre',
      1 => 'tokenizer',
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 0,
      1 =>
      array (
        0 =>
        array (
        ),
        1 =>
        array (
        ),
        2 =>
        array (
        ),
      ),
    ),
  ),
)
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.

PHP_Compat::loadVersion


Parse a directory

PHP_Compat::loadVersion
PHP Manual

PHP_CompatInfo::parseDir()

(No version information available, might be only in CVS)

— Parse a directory

funcsynopsis funcsynopsisinfo require_once 'PHP/CompatInfo.php'; /funcsynopsisinfo funcprototype funcdefarray PHP_CompatInfo::parseDir()/funcdef paramdefstring $dir /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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()

see PHP_CompatInfo::_fileList()

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);
?>

We get such result.

array (
  'ignored_files' =>
  array (
  ),
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '5.2.0',
  'extensions' =>
  array (
    0 => 'xdebug',
    1 => 'gd',
    2 => 'sapi_apache',
    3 => 'sapi_cgi',
    4 => 'sqlite',
  ),
  'constants' =>
  array (
    0 => 'UPLOAD_ERR_INI_SIZE',
    1 => 'UPLOAD_ERR_FORM_SIZE',
    2 => 'UPLOAD_ERR_PARTIAL',
    3 => 'UPLOAD_ERR_NO_FILE',
    4 => 'UPLOAD_ERR_NO_TMP_DIR',
    5 => 'UPLOAD_ERR_CANT_WRITE',
    6 => 'UPLOAD_ERR_EXTENSION',
    7 => 'UPLOAD_ERR_OK',
  ),
  'tokens' =>
  array (
    0 => 'abstract',
    1 => 'protected',
    2 => 'interface',
    3 => 'public',
    4 => 'implements',
    5 => 'private',
    6 => 'clone',
    7 => 'instanceof',
    8 => 'try',
    9 => 'throw',
    10 => 'catch',
    11 => 'final',
  ),
  'cond_code' =>
  array (
    0 => 2,
    1 =>
    array (
      0 =>
      array (
      ),
      1 =>
      array (
      ),
      2 =>
      array (
      ),
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/extensions.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.3.2',
    'extensions' =>
    array (
      0 => 'xdebug',
      1 => 'gd',
      2 => 'sapi_apache',
      3 => 'sapi_cgi',
      4 => 'sqlite',
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 2,
      1 =>
      array (
        0 =>
        array (
        ),
        1 =>
        array (
        ),
        2 =>
        array (
        ),
      ),
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/phpinfo.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '4.0.0',
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
    ),
    'cond_code' =>
    array (
      0 => 0,
      1 =>
      array (
        0 =>
        array (
        ),
        1 =>
        array (
        ),
        2 =>
        array (
        ),
      ),
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/PHP5/tokens.php5' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '5.0.0',
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
    ),
    'tokens' =>
    array (
      0 => 'abstract',
      1 => 'protected',
      2 => 'interface',
      3 => 'public',
      4 => 'implements',
      5 => 'private',
      6 => 'clone',
      7 => 'instanceof',
      8 => 'try',
      9 => 'throw',
      10 => 'catch',
      11 => 'final',
    ),
    'cond_code' =>
    array (
      0 => 0,
      1 =>
      array (
        0 =>
        array (
        ),
        1 =>
        array (
        ),
        2 =>
        array (
        ),
      ),
    ),
  ),
  'PHP_CompatInfo/tests/parseDir/PHP5/upload_error.php' =>
  array (
    'ignored_functions' =>
    array (
    ),
    'ignored_extensions' =>
    array (
    ),
    'ignored_constants' =>
    array (
    ),
    'max_version' => '',
    'version' => '5.2.0',
    'extensions' =>
    array (
    ),
    'constants' =>
    array (
      0 => 'UPLOAD_ERR_INI_SIZE',
      1 => 'UPLOAD_ERR_FORM_SIZE',
      2 => 'UPLOAD_ERR_PARTIAL',
      3 => 'UPLOAD_ERR_NO_FILE',
      4 => 'UPLOAD_ERR_NO_TMP_DIR',
      5 => 'UPLOAD_ERR_CANT_WRITE',
      6 => 'UPLOAD_ERR_EXTENSION',
      7 => 'UPLOAD_ERR_OK',
    ),
    'tokens' =>
    array (
      0 => 'throw',
    ),
    'cond_code' =>
    array (
      0 => 0,
      1 =>
      array (
        0 =>
        array (
        ),
        1 =>
        array (
        ),
        2 =>
        array (
        ),
      ),
    ),
  ),
)
We have global result, then follow by each file parsed in sub-directories.

PHP_Compat::loadVersion


Alias of parseDir

PHP_Compat::loadVersion
PHP Manual

PHP_CompatInfo::parseFolder()

(No version information available, might be only in CVS)

— Alias of parseDir

funcsynopsis funcsynopsisinfo require_once 'PHP/CompatInfo.php'; /funcsynopsisinfo funcprototype funcdefvoid PHP_CompatInfo::parseFolder()/funcdef paramdefstring $folder /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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()

Since

since version 0.7.0 (2004-03-09)

Note

This function can not be called statically.

Return value

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

Example

See PHP_CompatInfo::parseDir() example.

PHP_Compat::loadVersion


Parse a single file

PHP_Compat::loadVersion
PHP Manual

PHP_CompatInfo::parseFile()

(No version information available, might be only in CVS)

— Parse a single file

funcsynopsis funcsynopsisinfo require_once 'PHP/CompatInfo.php'; /funcsynopsisinfo funcprototype funcdefArray PHP_CompatInfo::parseFile()/funcdef paramdefstring $file /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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

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);
?>

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',
  'extensions' =>
  array (
    0 => 'date',
  ),
  'constants' =>
  array (
    0 => 'PHP_EOL',
    1 => 'DIRECTORY_SEPARATOR',
    2 => '__FILE__',
    3 => 'DATE_W3C',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 5,
    1 =>
    array (
    ),
  ),
)
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)
Warning

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

PHP_Compat::loadVersion


Parse a string

PHP_Compat::loadVersion
PHP Manual

PHP_CompatInfo::parseString()

(No version information available, might be only in CVS)

— Parse a string

funcsynopsis funcsynopsisinfo require_once 'PHP/CompatInfo.php'; /funcsynopsisinfo funcprototype funcdefArray PHP_CompatInfo::parseString()/funcdef paramdefstring $string /paramdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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

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);
?>

We get such result.

array (
  'ignored_functions' =>
  array (
  ),
  'ignored_extensions' =>
  array (
  ),
  'ignored_constants' =>
  array (
  ),
  'max_version' => '',
  'version' => '5.1.3',
  'extensions' =>
  array (
  ),
  'constants' =>
  array (
    0 => 'DATE_RFC3339',
    1 => 'DATE_RSS',
  ),
  'tokens' =>
  array (
  ),
  'cond_code' =>
  array (
    0 => 0,
    1 =>
    array (
      0 =>
      array (
      ),
      1 =>
      array (
      ),
      2 =>
      array (
      ),
    ),
  ),
)
That means we need PHP 5.1.3 minimum to run this chunk of code, due to usage of DATE_RFC3339 constant.

PHP_Compat::loadVersion


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.

PHP_CompatInfo::parseString
Introduction
PHP


PHP_FunctionCallTracer creates function calls debug trace.

PHP_FunctionCallTracer
Basic Use
PHP_FunctionCallTracer
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.
PHP_FunctionCallTracer
Basic Use
PHP_FunctionCallTracer


Simple trace of function arguments and returned variables.

PHP_FunctionCallTracer
PHPUnit
PHP_FunctionCallTracer
PHP Manual

Basic Use

(No version information available, might be only in CVS)

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.

Example #1 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.

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;
    }
}

Example #2 The application trace.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);

Example #3 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
        )

)
PHP_FunctionCallTracer
PHPUnit
PHP_FunctionCallTracer


PHPUnit

Provides a simple framework for creating a test application to automate testing of functions and classes.

Basic Use
Tutorial
PHP


A short tutorial about PHPUnit

PHPUnit
PHPUnit::run()
PHPUnit
PHP Manual

Tutorial

(No version information available, might be only in CVS)

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
$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.

PHPUnit
PHPUnit::run()
PHPUnit


runs a TestSuite and returns a TestResult object.

Tutorial
PHPUnit::TestCase
PHPUnit
PHP Manual

PHPUnit::run()

(No version information available, might be only in CVS)

PHPUnit::run() — runs a TestSuite and returns a TestResult object.

funcsynopsis funcsynopsisinfo require_once 'PHPUnit.php'; /funcsynopsisinfo funcprototype funcdefobject PHPUnit::run()/funcdef paramdef object $suite /paramdef /funcprototype /funcsynopsis

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

Example #1 Using PHPUnit::run()

<?php
require_once "PHPUnit.php";
$suite  = New PHPUnit_TestSuite('Mathtest');
$result = PHPUnit::run($suite);
echo $result->toHtml();
?>
Tutorial
PHPUnit::TestCase
PHPUnit


A TestCase defines the fixture to run multiple tests.

PHPUnit
PHPUnit2
PHPUnit
PHP Manual

PHPUnit::TestCase

(No version information available, might be only in CVS)

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.

function testPass() {
      $this->assertTrue($this->fValue1 + $this->fValue2 == 5);
    }

PHPUnit
PHPUnit2
PHPUnit


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.

PHP
Summary
PHP


Summary

(No version information available, might be only in CVS)

Summary — Summary

Where to find more information

You can find more information about this package at the following url » PHPUnit wiki

PHPUnit2
QA Tools
PHPUnit2


QA Tools

Table of Contents

  • QA_Peardoc_Coverage
  • QA_Pear_PackageStatus

Tools to ensure the quality of something.

Summary
QA_Peardoc_Coverage
Packages


QA_Peardoc_Coverage

Documentation coverage analysis for the PEAR packages documentation.

Daily updated pear documentation stats can be found at » pear.cweiske.de/coverage/.

QA Tools
Introduction
QA Tools


What QA_Peardoc_Coverage is good for

QA_Peardoc_Coverage
How it works
QA_Peardoc_Coverage
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

QA_Peardoc_Coverage
How it works
QA_Peardoc_Coverage


The global picture

Introduction
Generating coverage analysis
QA_Peardoc_Coverage
PHP Manual

How it works

(No version information available, might be only in CVS)

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.

Introduction
Generating coverage analysis
QA_Peardoc_Coverage


Step by step

QA_Peardoc_Coverage
QA_Pear_PackageStatus
QA_Peardoc_Coverage
PHP Manual

Generating coverage analysis

(No version information available, might be only in CVS)

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.

QA_Peardoc_Coverage
QA_Pear_PackageStatus
QA_Peardoc_Coverage


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/.

QA Tools
Science
QA Tools


Science

provides Packages for scientific purposes

QA_Pear_PackageStatus
Streams
Packages


Streams

Table of Contents

  • Stream_Var

Provides Packages for streams API. For more information on stream wrappers see the » PHP Manual.

Science
Stream_Var
Packages


Stream_Var

Allows stream based access to variables.

Streams
Introduction
Streams


Stream_Var
Example
Stream_Var
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Stream_Var
Example
Stream_Var


Example for the usage of Stream_Var

Stream_Var
Structures
Stream_Var
PHP Manual

Example

(No version information available, might be only in CVS)

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.

Example #1 Registering Stream_Var

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().

Example #2 Accessing scalar variables

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.

Example #3 Accessing an array

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.

Stream_Var
Structures
Stream_Var


Structures

Table of Contents

  • Structures_BibTex
  • Structures_DataGrid
  • Games_Chess
  • Structures_Graph
  • Structures_LinkedList
  • Structures_Tree

Provides structures-related Packages

Example
Structures_BibTex
Packages


Structures_BibTex

Parsing BibTex Data to an array and exporting to BibTex and RTF.

Structures
Introduction
Structures


Introduction to Structures_BibTex

Structures_BibTex
Warnings
Structures_BibTex
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 Loading a BibTex File and printing the parsed array

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:

Example #2 Setting options in the constructor

$bibtex = new Structures_BibTex(array('validate'=>false, 'unwrap'=>true));
Example of setting options using the method setOption():

Example #3 Setting options using setOption

$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().

Example #4 Adding an entry

$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);

Structures_BibTex
Warnings
Structures_BibTex


Usage of warnings when using Structures_BibTex

Introduction
Exporting
Structures_BibTex
PHP Manual

Warnings

(No version information available, might be only in CVS)

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.

Example #1 Switching off creation of warnings

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.

Example #2 Checking for warnings

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:

Example #3 Checking for warnings

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.

Introduction
Exporting
Structures_BibTex


Possibility to export the data using Structures_BibTex

Warnings
Miscellaneous
Structures_BibTex
PHP Manual

Exporting

(No version information available, might be only in CVS)

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:

Example #1 Changing author format

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.

Example #2 Exporting in BibTeX format

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().

Example #3 Exporting in RTF format

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.

Example #4 Exporting in RTF format with different RTF string

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().

Example #5 Exporting in HTML format

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 />
.

Example #6 Exporting in HTML format with different HTML string

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();

Warnings
Miscellaneous
Structures_BibTex


Miscellaneous methods in the class Structures_BibTex

Structures_BibTex
Structures_DataGrid
Structures_BibTex
PHP Manual

Miscellaneous

(No version information available, might be only in CVS)

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.

Structures_BibTex
Structures_DataGrid
Structures_BibTex


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.

Introduction and Features

Class Structures_DataGrid

Class Structures_DataGrid_Column

DataSource drivers

Renderer drivers

Miscellaneous
Introduction
Structures


What can I do with Structures_DataGrid?

Miscellaneous
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Miscellaneous


Answers to most Frequently Asked Questions

Miscellaneous
PHP Manual

FAQ

(No version information available, might be only in CVS)

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

  1. I'm using the HTML_Table Renderer. How can I use multiple grids on the same page?
  2. Which DataSource drivers are recommended?
  3. I'd like to add row numbers to my DataGrid. How can I do this?
  4. 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?
  5. Streaming is a nice feature. Why isn't streaming the default behaviour?
  6. I have used $renderer->toHtml(); with older versions of Structures_DataGrid, but this does not work anymore. How can I fix my code?
  7. All the rows are displayed on one page. Why isn't it paging the data?
  8. Sorting doesn't work with MDB2 DataSource driver if I have column names in uppercase letters. Why?

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:

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):

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:

$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:
$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:

$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.

Miscellaneous


How to install the core and drivers packages

Miscellaneous
PHP Manual

Installation

(No version information available, might be only in CVS)

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
Miscellaneous


What is a DataSource driver?

Miscellaneous
PHP Manual

DataSources

(No version information available, might be only in CVS)

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?

Miscellaneous


What formats can I render the output?

Miscellaneous
PHP Manual

Rendering the output

(No version information available, might be only in CVS)

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.

Miscellaneous


How to stream large recordsets

Miscellaneous
PHP Manual

Streaming

(No version information available, might be only in CVS)

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.

Example #1 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.

Miscellaneous


What can I do with the column formatter?

Miscellaneous
PHP Manual

Column Formatter

(No version information available, might be only in CVS)

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.

Example #1 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.

Miscellaneous


Quickly retrieve data from a database table

Miscellaneous
PHP Manual

Example - Quick

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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();
}

?>
Miscellaneous


How to build a datagrid using many of the features

Miscellaneous
PHP Manual

Example - Complex

(No version information available, might be only in CVS)

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.

Example #1 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\n";
    }
    $html .= '</select>';

    return $html;
}
function printEditLink($params)
{
    extract($params);
    return '<a href="edit.php?id=' . $record['id'] . '">Edit</a>';
}
?>
Miscellaneous


How to write your own DataSource driver.

Miscellaneous
PHP Manual

Custom DataSources

(No version information available, might be only in CVS)

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

funcsynopsis funcprototype funcdef constructor()/funcdef ( void /funcprototype /funcsynopsis The constructor must set default options, if any, and call the parent constructor. This method is optional.

funcsynopsis funcprototype funcdefobject bind()/funcdef paramdefmixed container /paramdef paramdefarray options /paramdef /funcprototype /funcsynopsis 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.

funcsynopsis funcprototype funcdefobject count()/funcdef ( void /funcprototype /funcsynopsis 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.

funcsynopsis funcprototype funcdefobject sort()/funcdef paramdefmixed sortSpec /paramdef paramdefarray sortDir /paramdef /funcprototype /funcsynopsis 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.

funcsynopsis funcprototype funcdefmixed fetch()/funcdef paramdefinteger offset /paramdef paramdefinteger len /paramdef /funcprototype /funcsynopsis 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

funcsynopsis funcprototype funcdefvoid _addDefaultOptions()/funcdef paramdefarray options /paramdef /funcprototype /funcsynopsis _addDefaultOptions() is used to declare the driver-specific options, if any, as well as their default values. It must be called from the constructor.

funcsynopsis funcprototype funcdefvoid setOptions()/funcdef paramdefarray options /paramdef /funcprototype /funcsynopsis 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.

Example #1 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.

Example #2 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.

Example #3 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...

Miscellaneous


How to write your own Rendering driver.

Miscellaneous
PHP Manual

Custom Renderers

(No version information available, might be only in CVS)

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.

funcsynopsis funcprototype funcdef constructor()/funcdef ( void /funcprototype /funcsynopsis The constructor must set default options via _addDefaultOptions(), if any, and call the parent constructor.

funcsynopsis funcprototype funcdefobject setContainer()/funcdef paramdefmixed container /paramdef /funcprototype /funcsynopsis setContainer() is responsible for attaching a rendering container provided by the user. It must return a PEAR_Error object in case of failure.

funcsynopsis funcprototype funcdefobject getContainer()/funcdef ( void /funcprototype /funcsynopsis getContainer() must return a reference to the container used by the driver. It must return a PEAR_Error object in case of failure.

funcsynopsis funcprototype funcdefvoid init()/funcdef ( void /funcprototype /funcsynopsis init() must initialize the rendering process. This method is also responsible for creating the container if it has not already been provided with setContainer().

funcsynopsis funcprototype funcdefvoid buildHeader()/funcdef paramdefarray columns /paramdef /funcprototype /funcsynopsis buildHeader() must build the header. $columns is a convenient reference to the $_columns property.

Protected methods that drivers can use

funcsynopsis funcprototype funcdefvoid _addDefaultOptions()/funcdef paramdefarray options /paramdef /funcprototype /funcsynopsis _addDefaultOptions() is used to declare the driver-specific options, if any, as well as their default values. It must be called from the constructor.

funcsynopsis funcprototype funcdefvoid setOptions()/funcdef paramdefarray options /paramdef /funcprototype /funcsynopsis 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

Miscellaneous


Constructor

Miscellaneous
PHP Manual

constructor Structures_DataGrid::Structures_DataGrid()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void constructor Structures_DataGrid::Structures_DataGrid() /funcdef paramdef string $limit = NULL /paramdef paramdef int $page = NULL /paramdef paramdef string $rendererType = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Instantiation

<?php
// Don't forget the ampersand
$datagrid =& new Structures_DataGrid();
?>

Note

This function can not be called statically.

Miscellaneous


Add a column, with optional position

Miscellaneous
PHP Manual

Structures_DataGrid::addColumn()

(No version information available, might be only in CVS)

— Add a column, with optional position

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::addColumn() /funcdef paramdef &$column /paramdef paramdef string $position = 'last' /paramdef paramdef string $relativeTo = NULL /paramdef paramdef object $column /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Miscellaneous


Attach an already instantiated Rendering driver

Miscellaneous
PHP Manual

Structures_DataGrid::attachRenderer()

(No version information available, might be only in CVS)

— Attach an already instantiated Rendering driver

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed& Structures_DataGrid::attachRenderer() /funcdef paramdef &$renderer /paramdef paramdef object $renderer /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


A simple way to add a record set to the datagrid

Miscellaneous
PHP Manual

Structures_DataGrid::bind()

(No version information available, might be only in CVS)

— A simple way to add a record set to the datagrid

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef bool Structures_DataGrid::bind() /funcdef paramdef mixed $container /paramdef paramdef array $options = array() /paramdef paramdef string $type = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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();
}
?>

Example #2 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.

Miscellaneous


Bind an already instantiated DataSource driver

Miscellaneous
PHP Manual

Structures_DataGrid::bindDataSource()

(No version information available, might be only in CVS)

— Bind an already instantiated DataSource driver

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::bindDataSource() /funcdef paramdef mixed &$source /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Build the datagrid

Miscellaneous
PHP Manual

Structures_DataGrid::build()

(No version information available, might be only in CVS)

— Build the datagrid

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::build() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Datasource driver Factory

Miscellaneous
PHP Manual

Structures_DataGrid::dataSourceFactory()

(No version information available, might be only in CVS)

— Datasource driver Factory

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef Structures_DataGrid_DataSource|PEAR_Error& Structures_DataGrid::dataSourceFactory() /funcdef paramdef mixed $source /paramdef paramdef array $options = array() /paramdef paramdef string $type = NULL /paramdef /funcprototype /funcsynopsis

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:

$driver =& Structures_DataGrid::dataSourceFactory($source);

Detect the source type and load the appropriate driver with custom options:

$driver =& Structures_DataGrid::dataSourceFactory($source, $options);

Load a driver for an explicit type (faster, bypasses detection routine):

$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.

Miscellaneous


Method used for debugging purposes only. Displays a dump of the DataGrid object.

Miscellaneous
PHP Manual

Structures_DataGrid::dump()

(No version information available, might be only in CVS)

— Method used for debugging purposes only. Displays a dump of the DataGrid object.

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::dump() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Miscellaneous


Enable streaming support for reading from DataSources and writing with Renderers and set the buffer size (number of records)

Miscellaneous
PHP Manual

Structures_DataGrid::enableStreaming()

(No version information available, might be only in CVS)

— Enable streaming support for reading from DataSources and writing with Renderers and set the buffer size (number of records)

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::enableStreaming() /funcdef paramdef integer $bufferSize = 500 /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Fill a rendering container with data

Miscellaneous
PHP Manual

Structures_DataGrid::fill()

(No version information available, might be only in CVS)

— Fill a rendering container with data

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::fill() /funcdef paramdef object &$container /paramdef paramdef array $options = array() /paramdef paramdef string $type = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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();

?>

Example #2 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.

Miscellaneous


Generate columns from a fields list

Miscellaneous
PHP Manual

Structures_DataGrid::generateColumns()

(No version information available, might be only in CVS)

— Generate columns from a fields list

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::generateColumns() /funcdef paramdef array $fields = array() /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Find a column by field name

Miscellaneous
PHP Manual

Structures_DataGrid::getColumnByField()

(No version information available, might be only in CVS)

— Find a column by field name

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef object Either& Structures_DataGrid::getColumnByField() /funcdef paramdef string $fieldName /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Find a column by name (label)

Miscellaneous
PHP Manual

Structures_DataGrid::getColumnByName()

(No version information available, might be only in CVS)

— Find a column by name (label)

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef object Either& Structures_DataGrid::getColumnByName() /funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Returns the number of columns

Miscellaneous
PHP Manual

Structures_DataGrid::getColumnCount()

(No version information available, might be only in CVS)

— Returns the number of columns

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef int Structures_DataGrid::getColumnCount() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Return the current columns

Miscellaneous
PHP Manual

Structures_DataGrid::getColumns()

(No version information available, might be only in CVS)

— Return the current columns

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef array Structures_DataGrid::getColumns() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Retrieves the current page number when paging is implemented

Miscellaneous
PHP Manual

Structures_DataGrid::getCurrentPage()

(No version information available, might be only in CVS)

— Retrieves the current page number when paging is implemented

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef int Structures_DataGrid::getCurrentPage() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Returns the number of the last record of the current page

Miscellaneous
PHP Manual

Structures_DataGrid::getCurrentRecordNumberEnd()

(No version information available, might be only in CVS)

— Returns the number of the last record of the current page

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef int Structures_DataGrid::getCurrentRecordNumberEnd() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Returns the number of the first record of the current page

Miscellaneous
PHP Manual

Structures_DataGrid::getCurrentRecordNumberStart()

(No version information available, might be only in CVS)

— Returns the number of the first record of the current page

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef int Structures_DataGrid::getCurrentRecordNumberStart() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Get the currently loaded DataSource driver

Miscellaneous
PHP Manual

Structures_DataGrid::getDataSource()

(No version information available, might be only in CVS)

— Get the currently loaded DataSource driver

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef object DataSource& Structures_DataGrid::getDataSource() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Return the datagrid output

Miscellaneous
PHP Manual

Structures_DataGrid::getOutput()

(No version information available, might be only in CVS)

— Return the datagrid output

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::getOutput() /funcdef paramdef int $type = NULL /paramdef paramdef array $options = array() /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Returns the total number of pages

Miscellaneous
PHP Manual

Structures_DataGrid::getPageCount()

(No version information available, might be only in CVS)

— Returns the total number of pages

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef int Structures_DataGrid::getPageCount() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Returns the total number of records

Miscellaneous
PHP Manual

Structures_DataGrid::getRecordCount()

(No version information available, might be only in CVS)

— Returns the total number of records

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef int Structures_DataGrid::getRecordCount() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Get the current or default Rendering driver

Miscellaneous
PHP Manual

Structures_DataGrid::getRenderer()

(No version information available, might be only in CVS)

— Get the current or default Rendering driver

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef object Renderer& Structures_DataGrid::getRenderer() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Remove a column

Miscellaneous
PHP Manual

Structures_DataGrid::removeColumn()

(No version information available, might be only in CVS)

— Remove a column

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::removeColumn() /funcdef paramdef &$column /paramdef paramdef object $column /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

&$column

object $column

The Structures_DataGrid_Column object (reference to)

Throws

throws no exceptions thrown

Examples

Example #1 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.

Miscellaneous


Render the datagrid

Miscellaneous
PHP Manual

Structures_DataGrid::render()

(No version information available, might be only in CVS)

— Render the datagrid

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::render() /funcdef paramdef mixed $renderer = NULL /paramdef paramdef array $options = array() /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Define the current page number.

Miscellaneous
PHP Manual

Structures_DataGrid::setCurrentPage()

(No version information available, might be only in CVS)

— Define the current page number.

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setCurrentPage() /funcdef paramdef mixed $page /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set a single datasource option

Miscellaneous
PHP Manual

Structures_DataGrid::setDataSourceOption()

(No version information available, might be only in CVS)

— Set a single datasource option

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setDataSourceOption() /funcdef paramdef string $name /paramdef paramdef mixed $value /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set multiple datasource options

Miscellaneous
PHP Manual

Structures_DataGrid::setDataSourceOptions()

(No version information available, might be only in CVS)

— Set multiple datasource options

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setDataSourceOptions() /funcdef paramdef array $options /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set default sorting specification

Miscellaneous
PHP Manual

Structures_DataGrid::setDefaultSort()

(No version information available, might be only in CVS)

— Set default sorting specification

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid::setDefaultSort() /funcdef paramdef array $sortSpec /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set Renderer

Miscellaneous
PHP Manual

Structures_DataGrid::setRenderer()

(No version information available, might be only in CVS)

— Set Renderer

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef mixed& Structures_DataGrid::setRenderer() /funcdef paramdef string $type /paramdef paramdef array $options = array() /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set a single renderer option

Miscellaneous
PHP Manual

Structures_DataGrid::setRendererOption()

(No version information available, might be only in CVS)

— Set a single renderer option

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setRendererOption() /funcdef paramdef string $name /paramdef paramdef mixed $value /paramdef paramdef bool $common = FALSE /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set multiple renderer options

Miscellaneous
PHP Manual

Structures_DataGrid::setRendererOptions()

(No version information available, might be only in CVS)

— Set multiple renderer options

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setRendererOptions() /funcdef paramdef array $options /paramdef paramdef bool $common = FALSE /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set the global GET/POST variables prefix

Miscellaneous
PHP Manual

Structures_DataGrid::setRequestPrefix()

(No version information available, might be only in CVS)

— Set the global GET/POST variables prefix

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setRequestPrefix() /funcdef paramdef string $prefix /paramdef /funcprototype /funcsynopsis

Description

If you need to change the request variables, you can define a prefix. This is extra useful when using multiple datagrids.

This methods need 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.

Miscellaneous


Enable and configure URL mapping

Miscellaneous
PHP Manual

Structures_DataGrid::setUrlFormat()

(No version information available, might be only in CVS)

— Enable and configure URL mapping

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::setUrlFormat() /funcdef paramdef mixed $format /paramdef paramdef string $prefix = NULL /paramdef paramdef string $scriptname = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Miscellaneous


Sorts the records by the defined field.

Miscellaneous
PHP Manual

Structures_DataGrid::sortRecordSet()

(No version information available, might be only in CVS)

— Sorts the records by the defined field.

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid::sortRecordSet() /funcdef paramdef array $sortSpec /paramdef paramdef string $direction = 'ASC' /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Miscellaneous
PHP Manual

Class Summary Structures_DataGrid_Column

(No version information available, might be only in CVS)

Class Summary — 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

Miscellaneous


Constructor

Miscellaneous
PHP Manual

constructor Structures_DataGrid_Column::Structures_DataGrid_Column()

(No version information available, might be only in CVS)

constructor — Constructor

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void constructor Structures_DataGrid_Column::Structures_DataGrid_Column() /funcdef paramdef string $label /paramdef paramdef string $field = NULL /paramdef paramdef string $orderBy = NULL /paramdef paramdef array $attributes = array() /paramdef paramdef string $autoFillValue = NULL /paramdef paramdef mixed $formatter = NULL /paramdef paramdef array $formatterArgs = array() /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Choose a format preset

Miscellaneous
PHP Manual

Structures_DataGrid_Column::format()

(No version information available, might be only in CVS)

— Choose a format preset

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::format() /funcdef paramdef $type /paramdef paramdef mixed $type,... /paramdef /funcprototype /funcsynopsis

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

Example #1 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.

Miscellaneous


Formatter

Miscellaneous
PHP Manual

Structures_DataGrid_Column::formatter()

(No version information available, might be only in CVS)

— Formatter

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::formatter() /funcdef paramdef $record /paramdef paramdef $row /paramdef paramdef $col /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Get the column XML/HTML attributes

Miscellaneous
PHP Manual

Structures_DataGrid_Column::getAttributes()

(No version information available, might be only in CVS)

— Get the column XML/HTML attributes

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef array Structures_DataGrid_Column::getAttributes() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Get auto fill value

Miscellaneous
PHP Manual

Structures_DataGrid_Column::getAutoFillValue()

(No version information available, might be only in CVS)

— Get auto fill value

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef string Structures_DataGrid_Column::getAutoFillValue() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Return the default direction to order this column by

Miscellaneous
PHP Manual

Structures_DataGrid_Column::getDefaultDirection()

(No version information available, might be only in CVS)

— Return the default direction to order this column by

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef string Structures_DataGrid_Column::getDefaultDirection() /funcdef paramdef $str /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Get name of the field for the column to be mapped to

Miscellaneous
PHP Manual

Structures_DataGrid_Column::getField()

(No version information available, might be only in CVS)

— Get name of the field for the column to be mapped to

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef string Structures_DataGrid_Column::getField() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Get column label

Miscellaneous
PHP Manual

Structures_DataGrid_Column::getLabel()

(No version information available, might be only in CVS)

— Get column label

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef string Structures_DataGrid_Column::getLabel() /funcdef paramdef /funcprototype /funcsynopsis

Description

The label is the text rendered into the column header.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

Miscellaneous


Get the field name to order the data by

Miscellaneous
PHP Manual

Structures_DataGrid_Column::getOrderBy()

(No version information available, might be only in CVS)

— Get the field name to order the data by

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef string Structures_DataGrid_Column::getOrderBy() /funcdef paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set the column XML/HTML attributes

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setAttributes()

(No version information available, might be only in CVS)

— Set the column XML/HTML attributes

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::setAttributes() /funcdef paramdef array $attributes /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set auto fill value

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setAutoFillValue()

(No version information available, might be only in CVS)

— Set auto fill value

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::setAutoFillValue() /funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set the default direction to order this column by

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setDefaultDirection()

(No version information available, might be only in CVS)

— Set the default direction to order this column by

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::setDefaultDirection() /funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set name of the field for the column to be mapped to

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setField()

(No version information available, might be only in CVS)

— Set name of the field for the column to be mapped to

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::setField() /funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set Formatter Callback

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setFormatter()

(No version information available, might be only in CVS)

— Set Formatter Callback

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef mixed Structures_DataGrid_Column::setFormatter() /funcdef paramdef mixed $formatter /paramdef paramdef array $arguments = array() /paramdef /funcprototype /funcsynopsis

Description

Define a formatting callback function with optional arguments for this column.

The callback function receives the following array as its first argument:

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.

Miscellaneous


Set column label

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setLabel()

(No version information available, might be only in CVS)

— Set column label

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::setLabel() /funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Set the field name to order the data by

Miscellaneous
PHP Manual

Structures_DataGrid_Column::setOrderBy()

(No version information available, might be only in CVS)

— Set the field name to order the data by

funcsynopsis funcsynopsisinforequire_once 'Structures/DataGrid/Column.php';/funcsynopsisinfo funcprototype funcdef void Structures_DataGrid_Column::setOrderBy() /funcdef paramdef string $str /paramdef /funcprototype /funcsynopsis

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.

Miscellaneous


Array Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_Array

(No version information available, might be only in CVS)

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.

Miscellaneous


Comma Seperated Value (CSV) Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_CSV

(No version information available, might be only in CVS)

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
Miscellaneous


PEAR::DB_DataObject Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_DataObject

(No version information available, might be only in CVS)

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

Example #1 Bind a DB_DataObject to Structures_DataGrid

<?php
$person = new DataObjects_Person;

$person->hair = 'red';
$person->has_glasses = 1;

$datagrid->bind($person);
?>
Miscellaneous


PEAR::DB Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_DB

(No version information available, might be only in CVS)

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
Miscellaneous


PEAR::DB SQL Query Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_DBQuery

(No version information available, might be only in CVS)

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().

Miscellaneous


PEAR::DB_Table Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_DBTable

(No version information available, might be only in CVS)

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

Example #1 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();
}
?>
Miscellaneous


Excel Spreadsheet Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_Excel

(No version information available, might be only in CVS)

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.

Miscellaneous


PEAR::MDB2 SQL Query Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_MDB2

(No version information available, might be only in CVS)

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().

Miscellaneous


PDO SQL Query Data Source Driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_PDO

(No version information available, might be only in CVS)

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().

Miscellaneous


RSS data source driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_RSS

(No version information available, might be only in CVS)

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
Miscellaneous


XML DataSource driver

Miscellaneous
PHP Manual

Structures_DataGrid_DataSource_XML

(No version information available, might be only in CVS)

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

Example #1 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();
}
?>

Example #2 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();
}
?>
Miscellaneous


HTML table rendering driver with a checkbox for each row of the grid

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_CheckableHTMLTable

(No version information available, might be only in CVS)

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

Example #1 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());
}
?>
Miscellaneous


Console Table Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_Console

(No version information available, might be only in CVS)

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
Miscellaneous


CSV Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_CSV

(No version information available, might be only in CVS)

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'
Miscellaneous


Flexy Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_Flexy

(No version information available, might be only in CVS)

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();

Miscellaneous


HTML form to edit a record

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_HTMLEditForm

(No version information available, might be only in CVS)

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

Example #1 Basic usage

<?php
require_once 'Structures/DataGrid.php';

$datagrid =& new Structures_DataGrid();
$datagrid->bind(...);  // bind your data here

$datagrid->setRenderer('HTMLEditForm');

$datagrid->render();
?>

Example #2 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();
?>
Miscellaneous


Multiple fields sorting form rendering driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_HTMLSortForm

(No version information available, might be only in CVS)

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

Example #1 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();

?>
Miscellaneous


HTML Table Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_HTMLTable

(No version information available, might be only in CVS)

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

Example #1 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 xml:id="pager"><?php $datagrid->render('Pager'); ?></span>
<div xml:id="grid"><?php $datagrid->render(); ?></div>
</body>

</html>
Miscellaneous


Pager rendering driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_Pager

(No version information available, might be only in CVS)

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. |
Miscellaneous


Smarty Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_Smarty

(No version information available, might be only in CVS)

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

Example #1 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');
?>

Example #2 Smarty template with sorting and paging (smarty-simple.tpl)

<!-- 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>
Miscellaneous


Excel Spreadsheet Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_XLS

(No version information available, might be only in CVS)

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);

Miscellaneous


XML Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_XML

(No version information available, might be only in CVS)

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'
Miscellaneous


XUL Rendering Driver

Miscellaneous
PHP Manual

Structures_DataGrid_Renderer_XUL

(No version information available, might be only in CVS)

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

Example #1 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";
?>
Miscellaneous


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)

Structures_DataGrid_Renderer_XUL
Introduction
Structures


Basic usage of Games_Chess

Games_Chess
Structures_Graph
Games_Chess
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Games_Chess
Structures_Graph
Games_Chess


Structures_Graph

Graph datastructure manipulation library

Introduction
Introduction
Structures


Graph datastructure manipulation library

Structures_Graph
Structures_LinkedList
Structures_Graph
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Structures_Graph
Structures_LinkedList
Structures_Graph


Structures_LinkedList

This package implements linked list structures. It supports both singly-linked lists (Structures_LinkedList_Single) and doubly-linked lists (Structures_LinkedList_Double).

Introduction
Structures_Tree
Structures


Structures_Tree

Generic tree management, currently supports DB and XML as data sources

Structures
Introduction
Structures


Generic tree management, currently supports DB and XML as data sources

Structures_Tree
System
Structures_Tree
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Structures_Tree
System
Structures_Tree


System

Table of Contents

  • System_Folders
  • System_Mount
  • System_ProcWatch
  • System_WinDrives

System Utilities

Introduction
System_Folders
Packages


System_Folders

Returns locations of system folders like home, desktop, documents and others.

System
Introduction
System


Get system folder locations.

System_Folders
Example
System_Folders
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

System_Folders
Example
System_Folders


How to use System_Folders

System_Folders
System_Mount
System_Folders
PHP Manual

Example

(No version information available, might be only in CVS)

Example — How to use System_Folders

Using System_Folders

Example #1 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

Example #2 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.

System_Folders
System_Mount
System_Folders


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.

Example
Introduction
System


Mount and Unmount filesystems

System_Mount
System_ProcWatch
System_Mount
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Example #1 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.

System_Mount
System_ProcWatch
System_Mount


System_ProcWatch

The package provides methods to monitor system process on Unix-like systems.

Introduction and Features

Configuration

Parser Information

Introduction
Intro
System


Introduction to System::ProcWatch

Introduction
PHP Manual

Intro

(No version information available, might be only in CVS)

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

Example #1 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

Example #2 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

Example #3 PHP configuration array

$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();
// ...
Introduction


Constants defined in and used by System_ProcWatch

Introduction
PHP Manual

Constants

(No version information available, might be only in CVS)

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

Introduction


System_ProcWatch

(No version information available, might be only in CVS)

— System_ProcWatch

System_ProcWatch

Monitor processes

Usage:

1  require_once 'System/ProcWatch.php';
2  require_once 'System/ProcWatch/Config.php';
3
4  $cf =
System_ProcWatch_Config
::
fromXmlFile
('/etc/procwatch.xml');
5  $pw = &new
System_ProcWatch
($cf);
6  $pw->
run
();

Introduction


Constructor

Introduction
PHP Manual

System_ProcWatch::System_ProcWatch()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinfo require_once 'System/ProcWatch.php'; /funcsynopsisinfo funcprototype funcdefobject &new System_ProcWatch() /funcdef paramdefarray $config /paramdef /funcprototype /funcsynopsis

Description

Instantiate a new System_ProcWatch object configured by the supplied configuration array.

Parameter

array $config

config array from System_ProcWatch_Config

Introduction


Run once

Introduction
PHP Manual

System_ProcWatch::run()

(No version information available, might be only in CVS)

— Run once

funcsynopsis funcprototype funcdefvoid System_ProcWatch::run()/funcdef paramdefstring $ps_args = 'aux' /paramdef /funcprototype /funcsynopsis

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.

Introduction


Run in daemon mode

Introduction
PHP Manual

System_ProcWatch::daemon()

(No version information available, might be only in CVS)

— Run in daemon mode

funcsynopsis funcprototype funcdefvoid System_ProcWatch::daemon()/funcdef paramdefint $interval /paramdef paramdefstring $ps_args = 'aux' /paramdef /funcprototype /funcsynopsis

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.

Introduction


Set configuration

Introduction
PHP Manual

System_ProcWatch::setConfig()

(No version information available, might be only in CVS)

— Set configuration

funcsynopsis funcprototype funcdefvoid System_ProcWatch::setConfig()/funcdef paramdefarray $config /paramdef /funcprototype /funcsynopsis

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.

Introduction


System_ProcWatch_Config

(No version information available, might be only in CVS)

— 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);

Introduction


Get config array from XML string

Introduction
PHP Manual

System_ProcWatch_Config::fromXml()

(No version information available, might be only in CVS)

— Get config array from XML string

funcsynopsis funcsynopsisinfo require_once 'System/ProcWatch/Config.php'; /funcsynopsisinfo funcprototype funcdefmixed System_ProcWatch_Config::fromXml()/funcdef paramdefstring $xml /paramdef /funcprototype /funcsynopsis

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.

Introduction


Get config array from XML file

Introduction
PHP Manual

System_ProcWatch_Config::fromXmlFile()

(No version information available, might be only in CVS)

— Get config array from XML file

funcsynopsis funcsynopsisinfo require_once 'System/ProcWatch/Config.php'; /funcsynopsisinfo funcprototype funcdefmixed System_ProcWatch_Config::fromXmlFile()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

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.

Introduction


Get config array from INI file

Introduction
PHP Manual

System_ProcWatch_Config::fromIniFile()

(No version information available, might be only in CVS)

— Get config array from INI file

funcsynopsis funcsynopsisinfo require_once 'System/ProcWatch/Config.php'; /funcsynopsisinfo funcprototype funcdefmixed System_ProcWatch_Config::fromIniFile()/funcdef paramdefstring $file /paramdef /funcprototype /funcsynopsis

Description

Parses an INI file into an array to configure System_ProcWatch with.

Example #1 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.

Introduction


Get config array from an array

Introduction
PHP Manual

System_ProcWatch_Config::fromArray()

(No version information available, might be only in CVS)

— Get config array from an array

funcsynopsis funcsynopsisinfo require_once 'System/ProcWatch/Config.php'; /funcsynopsisinfo funcprototype funcdefmixed System_ProcWatch_Config::fromArray()/funcdef paramdefmixed $array /paramdef /funcprototype /funcsynopsis

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.

Introduction


System_ProcWatch_Parser

(No version information available, might be only in CVS)

— 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
();

Introduction


Constructor

Introduction
PHP Manual

System_ProcWatch_Parser::System_ProcWatch_Parser()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinfo require_once 'System/ProcWatch/Parser.php'; /funcsynopsisinfo funcprototype funcdefobject &new System_ProcWatch_Parser() /funcdef paramdefstring $ps_args = 'aux' /paramdef /funcprototype /funcsynopsis

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.

Introduction


Get parsed data

Introduction
PHP Manual

System_ProcWatch_Parser::getParsedData()

(No version information available, might be only in CVS)

— Get parsed data

funcsynopsis funcprototype funcdefarray &System_ProcWatch_Parser::getParsedData()/funcdef paramdefstring $ps_args = 'aux' /paramdef paramdefbool $refresh = FALSE /paramdef /funcprototype /funcsynopsis

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.

Introduction


Fetch ps' data

Introduction
PHP Manual

System_ProcWatch_Parser::fetch()

(No version information available, might be only in CVS)

— Fetch ps' data

funcsynopsis funcprototype funcdefstring System_ProcWatch_Parser::fetch()/funcdef paramdefstring $ps_args = '' /paramdef /funcprototype /funcsynopsis

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.

Introduction


Parse

Introduction
PHP Manual

System_ProcWatch_Parser::parse()

(No version information available, might be only in CVS)

— Parse

funcsynopsis funcprototype funcdefarray System_ProcWatch_Parser::parse()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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.

Introduction


Get info about a process by its PID

Introduction
PHP Manual

System_ProcWatch_Parser::getProcByPid()

(No version information available, might be only in CVS)

— Get info about a process by its PID

funcsynopsis funcprototype funcdefarray System_ProcWatch_Parser::getProcByPid()/funcdef paramdefint $pid /paramdef /funcprototype /funcsynopsis

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.

Introduction


Get information about processes

Introduction
PHP Manual

System_ProcWatch_Parser::getProcInfo()

(No version information available, might be only in CVS)

— Get information about processes

funcsynopsis funcprototype funcdefarray System_ProcWatch_Parser::getProcInfo()/funcdef paramdefstring $pattern /paramdef paramdefstring $search /paramdef /funcprototype /funcsynopsis

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.

Introduction


System_WinDrives

Provides functions to enumerate root directories ("Drives") on Windows systems by using win32 api calls.

System
Introduction
System


Enumerating drives on Windows systems

System_WinDrives
Example
System_WinDrives
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

System_WinDrives
Example
System_WinDrives


How to use System_WinDrives

Introduction
Constants
System_WinDrives
PHP Manual

Example

(No version information available, might be only in CVS)

Example — How to use System_WinDrives

Using System_WinDrives

Example #1 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.

Introduction
Constants
System_WinDrives


Constants defined and used in System_WinDrives

Example
System_WinDrives()
System_WinDrives
PHP Manual

Constants

(No version information available, might be only in CVS)

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

Example
System_WinDrives()
System_WinDrives


Outputs short description of the method

Constants
System_WinDrives::getDriveList()
System_WinDrives
PHP Manual

System_WinDrives()

(No version information available, might be only in CVS)

System_WinDrives() — Outputs short description of the method

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefSystem_WinDrives System_WinDrives()/funcdef paramdef boolean $bReadName = false /paramdef /funcprototype /funcsynopsis

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()

Constants
System_WinDrives::getDriveList()
System_WinDrives


Gets array with path of all drives

System_WinDrives()
System_WinDrives::getDriveName()
System_WinDrives
PHP Manual

System_WinDrives::getDriveList()

(No version information available, might be only in CVS)

System_WinDrives::getDriveList() — Gets array with path of all drives

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefarray System_WinDrives::getDriveList()/funcdef paramdefvoid/paramdef /funcprototype /funcsynopsis

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

Example #1 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()

System_WinDrives()
System_WinDrives::getDriveName()
System_WinDrives


Returns the user-defined name for a drive

System_WinDrives::getDriveList()
System_WinDrives::getDrivesInformation()
System_WinDrives
PHP Manual

System_WinDrives::getDriveName()

(No version information available, might be only in CVS)

System_WinDrives::getDriveName() — Returns the user-defined name for a drive

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefstring System_WinDrives::getDriveName()/funcdef paramdef string $strDrive /paramdef /funcprototype /funcsynopsis

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

Example #1 Using myFunction()

<?php
require_once 'System/WinDrives.php';

$swd = new System_WinDrives();
echo $swd->getDriveName('C:\\');
?>

Output:

Windrive
System_WinDrives::getDriveList()
System_WinDrives::getDrivesInformation()
System_WinDrives


Gets information about all drives

System_WinDrives::getDriveName()
System_WinDrives::getDriveType()
System_WinDrives
PHP Manual

System_WinDrives::getDrivesInformation()

(No version information available, might be only in CVS)

System_WinDrives::getDrivesInformation() — Gets information about all drives

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefarray System_WinDrives::getDrivesInformation()/funcdef paramdefvoid/paramdef /funcprototype /funcsynopsis

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

Example #1 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
System_WinDrives::getDriveName()
System_WinDrives::getDriveType()
System_WinDrives


Gets the type of a drive

System_WinDrives::getDrivesInformation()
System_WinDrives::getReadName()
System_WinDrives
PHP Manual

System_WinDrives::getDriveType()

(No version information available, might be only in CVS)

System_WinDrives::getDriveType() — Gets the type of a drive

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefint System_WinDrives::getDriveType()/funcdef paramdef string $strDrive /paramdef /funcprototype /funcsynopsis

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()

System_WinDrives::getDrivesInformation()
System_WinDrives::getReadName()
System_WinDrives


Returns if drive names shall be read or not

System_WinDrives::getDriveType()
System_WinDrives::getTypeTitle()
System_WinDrives
PHP Manual

System_WinDrives::getReadName()

(No version information available, might be only in CVS)

System_WinDrives::getReadName() — Returns if drive names shall be read or not

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefboolean System_WinDrives::getReadName()/funcdef paramdefvoid/paramdef /funcprototype /funcsynopsis

Description

Returns of drive names should be read or not.

Return value

boolean - true if they shall be read, false if not.

See

setReadName()

System_WinDrives::getDriveType()
System_WinDrives::getTypeTitle()
System_WinDrives


Gets the readable name to a drive type

System_WinDrives::getReadName()
System_WinDrives::guessDriveList()
System_WinDrives
PHP Manual

System_WinDrives::getTypeTitle()

(No version information available, might be only in CVS)

System_WinDrives::getTypeTitle() — Gets the readable name to a drive type

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefstring System_WinDrives::getTypeTitle()/funcdef paramdef int $nType /paramdef /funcprototype /funcsynopsis

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

System_WinDrives::getReadName()
System_WinDrives::guessDriveList()
System_WinDrives


Tries to guess the drive list

System_WinDrives::getTypeTitle()
System_WinDrives::isApiAvailable()
System_WinDrives
PHP Manual

System_WinDrives::guessDriveList()

(No version information available, might be only in CVS)

System_WinDrives::guessDriveList() — Tries to guess the drive list

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefarray System_WinDrives::guessDriveList()/funcdef paramdefvoid/paramdef /funcprototype /funcsynopsis

Description

Tries to guess the drive list by brute-force checking all letters.

Return value

array - Array with all found drive paths.

System_WinDrives::getTypeTitle()
System_WinDrives::isApiAvailable()
System_WinDrives


Checks if the API is available

System_WinDrives::guessDriveList()
System_WinDrives::setReadName()
System_WinDrives
PHP Manual

System_WinDrives::isApiAvailable()

(No version information available, might be only in CVS)

System_WinDrives::isApiAvailable() — Checks if the API is available

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdefboolean System_WinDrives::isApiAvailable()/funcdef paramdefvoid/paramdef /funcprototype /funcsynopsis

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.

System_WinDrives::guessDriveList()
System_WinDrives::setReadName()
System_WinDrives


Sets the readName setting

System_WinDrives
Text
System_WinDrives
PHP Manual

System_WinDrives::setReadName()

(No version information available, might be only in CVS)

System_WinDrives::setReadName() — Sets the readName setting

funcsynopsis funcsynopsisinfo require_once 'System/WinDrives.php'; /funcsynopsisinfo funcprototype funcdef System_WinDrives::setReadName()/funcdef paramdef boolean $bReadName /paramdef /funcprototype /funcsynopsis

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

System_WinDrives
Text
System_WinDrives


Text

Table of Contents

  • Text_CAPTCHA
  • Text_CAPTCHA_Numeral
  • Text_Figlet
  • Text_Highlighter
  • Text_LanguageDetect
  • Text_Password
  • Text_Statistics
  • Text_Wiki

Packages for text manipulation and analysis.

System_WinDrives::setReadName()
Text_CAPTCHA
Packages


Text_CAPTCHA

Implementation of CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart).

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.

Example

The following example implements the standard use of a CAPTCHA: Submitted form data is only evaluated when a CAPTCHA has been solved correctly.

Example #1 Creating a CAPTCHA

The following code creates a CAPTCHA, provides the relevant information for the package, anhd retrieves the CAPTCHA as a PNG image.

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);

Example #2 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.

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).

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.
Text
Text_CAPTCHA_Numeral
Text


Text_CAPTCHA_Numeral

Implementation of mathematic operation CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart).

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.

Example

The following example implements the standard use of a CAPTCHA: Submitted form data is only evaluated when a CAPTCHA has been solved correctly.

Example #1 Creating a Numeral CAPTCHA

This example is just to show you how to generate a simple mathematic operation with Text_CAPTCHA_Numeral.

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;

Example #2 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.

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();

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.
Text_CAPTCHA
Text_Figlet
Text


Text_Figlet

Render text using FIGlet fonts.

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).

Example #1 "Hello, world!" written using a FIGlet font

.
   / / / /__  / / /___       _      ______  _____/ /___/ / /
  / /_/ / _ \/ / / __ \     | | /| / / __ \/ ___/ / __  / /
 / __  /  __/ / / /_/ /     | |/ |/ / /_/ / /  / / /_/ /_/
/_/ /_/\___/_/_/\____( )    |__/|__/\____/_/  /_/\__,_(_)
                     |/

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.

Example #2 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.

Text_CAPTCHA_Numeral
Text_Highlighter
Text


Text_Highlighter

Provides functionality to perform syntax highlighting for different file formats.

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

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:

Example #1 Highlighting a SQL query

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.

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:

Example #2 Using the console renderer

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:

Example #3 Options for the HTML renderer

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.)
Text_Figlet
Text_LanguageDetect
Text


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".

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.

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
)
Text_Highlighter
Text_Password
Text


Text_Password

Creating passwords with PHP.

Text_LanguageDetect
Introduction
Text


Introduction to Text_Password

Text_Password
Supported types of passwords
Text_Password
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Text_Password
Supported types of passwords
Text_Password


This part of the documentation introduces the different supported types of passwords and gives examples for their usage.

Text_Password
Text_Statistics
Text_Password
PHP Manual

Supported types of passwords

(No version information available, might be only in CVS)

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.

Example #1 Creating a pronounceable password:

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.

Example #2 Creating a unpronounceable password:

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.

Example #3 Creating passwords based on a given string:

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

Text_Password
Text_Statistics
Text_Password


Text_Statistics

computation of readability scores for text documents.

Supported types of passwords
Introduction
Text


computation of readability scores for text documents.

Text_Statistics
Text_Wiki
Text_Statistics
PHP Manual

Introduction

(No version information available, might be only in CVS)

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 #1 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 #2 Example numSyllables()

<?php
 require_once 'Text/Word.php'
 $word = new Text_Word('word');
 $word->numSyllables();  // returns 1
?>

Text_Statistics
Text_Wiki
Text_Statistics


Text_Wiki

Abstracts parsing and rendering rules for Wiki markup in structured plain text

Text
Introduction
Text


Abstracts parsing and rendering rules for Wiki markup in structured plain text

Text_Wiki
Tools and Utilities
Text_Wiki
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

Text_Wiki
Tools and Utilities
Text_Wiki


Tools and Utilities

Table of Contents

  • MIME_Type
  • VersionControl_SVN

Introduction
MIME_Type
Packages


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.

Tools and Utilities
Detecting MIME types
Tools and Utilities


How to determine the MIME type of a file

MIME_Type
Getting infos about a MIME type
MIME_Type
PHP Manual

Detecting MIME types

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.';
}
?>
MIME_Type
Getting infos about a MIME type
MIME_Type


How to get more information about a MIME type

Detecting MIME types
Editing MIME types
MIME_Type
PHP Manual

Getting infos about a MIME type

(No version information available, might be only in CVS)

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/*).

Detecting MIME types
Editing MIME types
MIME_Type


How to change things

MIME_Type
VersionControl_SVN
MIME_Type
PHP Manual

Editing MIME types

(No version information available, might be only in CVS)

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.

MIME_Type
VersionControl_SVN
MIME_Type


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.

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.

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.

Example #1 Reading the content of a Subversion repository

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:

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.

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.

Example #2 Getting the list of current files in a repository

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.

Example #3 Recursively getting the list of current files in a repository

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.

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.

Tools and Utilities
Validate
Tools and Utilities


Validate

Table of Contents

  • 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

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

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

VersionControl_SVN
Validate features
Packages


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

Validate
Validate_AR
Validate


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

Validate features
Validate_AT
Validate


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

Validate_AR
Validate_AU
Validate


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

Validate_AT
Introduction
Validate


introduction to Validate_AU

Validate_AU
List of available validations
Validate_AU
PHP Manual

Introduction

(No version information available, might be only in CVS)

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';
?>

Validate_AU
List of available validations
Validate_AU


available validation in Validate_AU

Introduction
Package Validate_AU Constants
Validate_AU
PHP Manual

List of available validations

(No version information available, might be only in CVS)

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

Introduction
Package Validate_AU Constants
Validate_AU


Constants defined in and used by Validate_AU

List of available validations
Validate_AU::abn
Validate_AU
PHP Manual

Package Validate_AU Constants

(No version information available, might be only in CVS)

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

List of available validations
Validate_AU::abn
Validate_AU


Australian Business Number (ABN).

Package Validate_AU Constants
Validate_AU::acn
Validate_AU
PHP Manual

Validate_AU::abn()

(No version information available, might be only in CVS)

— Australian Business Number (ABN).

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::abn()/funcdef paramdefstring $abn /paramdef /funcprototype /funcsynopsis

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.

Package Validate_AU Constants
Validate_AU::acn
Validate_AU


Validate an Australian Company Number (ACN)

Validate_AU::abn
Validate_AU::phoneNumber
Validate_AU
PHP Manual

Validate_AU::acn()

(No version information available, might be only in CVS)

— Validate an Australian Company Number (ACN)

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::acn()/funcdef paramdefstring $acn /paramdef /funcprototype /funcsynopsis

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.

Validate_AU::abn
Validate_AU::phoneNumber
Validate_AU


Validate a telephone number.

Validate_AU::acn
Validate_AU::postalCode
Validate_AU
PHP Manual

Validate_AU::phoneNumber()

(No version information available, might be only in CVS)

— Validate a telephone number.

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::phoneNumber()/funcdef paramdefstring $number /paramdef paramdefint $flags = VALIDATE_AU_PHONENUMBER_NATIONAL /paramdef /funcprototype /funcsynopsis

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.

Validate_AU::acn
Validate_AU::postalCode
Validate_AU


Validate Austrialian postal codes.

Validate_AU::phoneNumber
Validate_AU::region
Validate_AU
PHP Manual

Validate_AU::postalCode()

(No version information available, might be only in CVS)

— Validate Austrialian postal codes.

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::postalCode()/funcdef paramdefstring $postcode /paramdef paramdefbool $strong = FALSE /paramdef /funcprototype /funcsynopsis

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.

Validate_AU::phoneNumber
Validate_AU::region
Validate_AU


Validates Australian Regional Codes

Validate_AU::postalCode
Validate_AU::ssn
Validate_AU
PHP Manual

Validate_AU::region()

(No version information available, might be only in CVS)

— Validates Australian Regional Codes

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::region()/funcdef paramdefstring $region /paramdef /funcprototype /funcsynopsis

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.

Validate_AU::postalCode
Validate_AU::ssn
Validate_AU


Social Security Number.

Validate_AU::region
Validate_AU::tfn
Validate_AU
PHP Manual

Validate_AU::ssn()

(No version information available, might be only in CVS)

— Social Security Number.

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::ssn()/funcdef paramdefstring $ssn /paramdef /funcprototype /funcsynopsis

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.

Validate_AU::region
Validate_AU::tfn
Validate_AU


Tax File Number (TFN)

Validate_AU
Validate_BE
Validate_AU
PHP Manual

Validate_AU::tfn()

(No version information available, might be only in CVS)

— Tax File Number (TFN)

funcsynopsis funcsynopsisinfo require_once '/Validate/AU.php'; /funcsynopsisinfo funcprototype funcdefbool Validate_AU::tfn()/funcdef paramdefstring $tfn /paramdef /funcprototype /funcsynopsis

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.

Validate_AU
Validate_BE
Validate_AU


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

Validate_AU::tfn
Introduction
Validate


Introduction to validate_BE

Validate_BE
List of aivailable validations
Validate_BE
PHP Manual

Introduction

(No version information available, might be only in CVS)

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';
?>

Validate_BE
List of aivailable validations
Validate_BE


aivailable validation in validate_be

Validate_BE
Validate_CA
Validate_BE
PHP Manual

List of aivailable validations

(No version information available, might be only in CVS)

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

Validate_BE
Validate_CA
Validate_BE


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

List of aivailable validations
Introduction
Validate


Introduction to validate_CA

Validate_CA
List of aivailable validations
Validate_CA
PHP Manual

Introduction

(No version information available, might be only in CVS)

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';
?>

Validate_CA
List of aivailable validations
Validate_CA


available validation in validate_ca

Validate_CA
Validate_CH
Validate_CA
PHP Manual

List of aivailable validations

(No version information available, might be only in CVS)

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

Validate_CA
Validate_CH
Validate_CA


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

List of aivailable validations
Validate_DE
Validate


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

Validate_CH
Validate_DK
Validate


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

Validate_DE
Validate_ES
Validate


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

Validate_DK
Validate_esMX
Validate


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

Validate_ES
Validate_FI
Validate


Validate_FI

Specific validation methods for data used in Finland.

See also:

  • » Latest auto-generated API documentation

  • » Package information on pear.php.net

Validate_esMX
Introduction
Validate


introduction to Validate_FI

Validate_FI
Validate_FI::postalCode
Validate_FI
PHP Manual

Introduction

(No version information available, might be only in CVS)

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
Validate_FI
Validate_FI::postalCode
Validate_FI


Validate Finnish postal code

Introduction
Validate_FI::phoneNumber
Validate_FI
PHP Manual

Validate_FI::postalCode()

(No version information available, might be only in CVS)

— Validate Finnish postal code

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::postalCode() /funcdef paramdef string $number /paramdef paramdef bool $strong /paramdef /funcprototype /funcsynopsis

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

Example #1 Using postalCode()

<?php
// Include the package
require_once 'Validate/FI.php';

$postalCode = '00100';
if ( Validate_FI::postalCode($postalCode) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Introduction
Validate_FI::phoneNumber
Validate_FI


Validate Finnish telephone number

Validate_FI::postalCode
Validate_FI::carLicensePlate
Validate_FI
PHP Manual

Validate_FI::phoneNumber()

(No version information available, might be only in CVS)

— Validate Finnish telephone number

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::phoneNumber() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>
Validate_FI::postalCode
Validate_FI::carLicensePlate
Validate_FI


Validate Finnish car license plate number

Validate_FI::phoneNumber
Validate_FI::bikeLicensePlate
Validate_FI
PHP Manual

Validate_FI::carLicensePlate()

(No version information available, might be only in CVS)

— Validate Finnish car license plate number

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::carLicensePlate() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>
Validate_FI::phoneNumber
Validate_FI::bikeLicensePlate
Validate_FI


Validate Finnish motorbike license plate number

Validate_FI::carLicensePlate
Validate_FI::pin
Validate_FI
PHP Manual

Validate_FI::bikeLicensePlate()

(No version information available, might be only in CVS)

— Validate Finnish motorbike license plate number

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::bikeLicensePlate() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 Using bikeLicensePlate()

<?php
// Include the package
require_once 'Validate/FI.php';

$bikeLicensePlate = 'ABC123';
if ( Validate_FI::bikeLicensePlate($bikeLicensePlate) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Validate_FI::carLicensePlate
Validate_FI::pin
Validate_FI


Validate Personal Identity Number (HETU)

Validate_FI::bikeLicensePlate
Validate_FI::finuid
Validate_FI
PHP Manual

Validate_FI::pin()

(No version information available, might be only in CVS)

— Validate Personal Identity Number (HETU)

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef mixed Validate_FI::pin() /funcdef paramdef string $number /paramdef paramdef bool $info /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>

Example #2 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
)
Validate_FI::bikeLicensePlate
Validate_FI::finuid
Validate_FI


Validate Finnish Unique Identification Number (SATU)

Validate_FI::pin
Validate_FI::businessId
Validate_FI
PHP Manual

Validate_FI::finuid()

(No version information available, might be only in CVS)

— Validate Finnish Unique Identification Number (SATU)

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::finuid() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 Using finuid()

<?php
// Include the package
require_once 'Validate/FI.php';

$finuid = '10011187H';
if ( Validate_FI::finuid($finuid) ) {{
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Validate_FI::pin
Validate_FI::businessId
Validate_FI


Validate Finnish Business ID (Y-tunnus)

Validate_FI::finuid
Validate_FI::partyId
Validate_FI
PHP Manual

Validate_FI::businessId()

(No version information available, might be only in CVS)

— Validate Finnish Business ID (Y-tunnus)

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::businessId() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>
Validate_FI::finuid
Validate_FI::partyId
Validate_FI


Validate Finnish Party Identification number (OVT-tunnus)

Validate_FI::businessId
Validate_FI::vatNumber
Validate_FI
PHP Manual

Validate_FI::partyId()

(No version information available, might be only in CVS)

— Validate Finnish Party Identification number (OVT-tunnus)

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::partyId() /funcdef paramdef integer $number /paramdef /funcprototype /funcsynopsis

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

Example #1 Using partyId()

<?php
// Include the package
require_once 'Validate/FI.php';

$partyId = '003715728600';
if ( Validate_FI::partyId($partyId) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Validate_FI::businessId
Validate_FI::vatNumber
Validate_FI


Validate Finnish Value Added Tax number (ALV-numero)

Validate_FI::partyId
Validate_FI::bankAccount
Validate_FI
PHP Manual

Validate_FI::vatNumber()

(No version information available, might be only in CVS)

— Validate Finnish Value Added Tax number (ALV-numero)

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::vatNumber() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 Using vatNumber()

<?php
// Include the package
require_once 'Validate/FI.php';

$vatNumber = 'FI15728600';
if ( Validate_FI::vatNumber($vatNumber) ) {
    print 'Valid';
} else {
    print 'Not valid!';
}
?>
Validate_FI::partyId
Validate_FI::bankAccount
Validate_FI


Validate Finnish bank account number

Validate_FI::vatNumber
Validate_FI::refNum
Validate_FI
PHP Manual

Validate_FI::bankAccount()

(No version information available, might be only in CVS)

— Validate Finnish bank account number

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::bankAccount() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>
Validate_FI::vatNumber
Validate_FI::refNum
Validate_FI


Validate Finnish bank reference number

Validate_FI::bankAccount
Validate_FI::creditCard
Validate_FI
PHP Manual

Validate_FI::refNum()

(No version information available, might be only in CVS)

— Validate Finnish bank reference number

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::refNum() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>
Validate_FI::bankAccount
Validate_FI::creditCard
Validate_FI


Validate credit card number

Validate_FI
Validate_FR
Validate_FI
PHP Manual

Validate_FI::creditCard()

(No version information available, might be only in CVS)

— Validate credit card number

funcsynopsis funcsynopsisinfo require_once 'Validate/FI.php'; /funcsynopsisinfo funcprototype funcdef bool Validate_FI::creditCard() /funcdef paramdef string $number /paramdef /funcprototype /funcsynopsis

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

Example #1 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!';
}
?>
Validate_FI
Validate_FR
Validate_FI


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

Validate_FI::creditCard
Validate_IE
Validate


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

Validate_FR
Introduction
Validate


Introduction to validate_IE

Validate_IE
List of available validations
Validate_IE
PHP Manual

Introduction

(No version information available, might be only in CVS)

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';
?>

Validate_IE
List of available validations
Validate_IE


available validation in validate_ie

Validate_IE
Validate_IN
Validate_IE
PHP Manual

List of available validations

(No version information available, might be only in CVS)

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

Validate_IE
Validate_IN
Validate_IE


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

List of available validations
Validate_IS
Validate


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

Validate_IN
Validate_NL
Validate


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

Validate_IS
Validate_NZ
Validate


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

Validate_NL
Validate_PL
Validate


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

Validate_NZ
Validate_ptBR
Validate


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

Validate_PL
Validate_UK
Validate


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

Validate_ptBR
Validate_US
Validate


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

Validate_UK
Validate_ZA
Validate


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

Validate_US
Validate_Finance
Validate


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

Validate_ZA
Validate_Finance_CreditCard
Validate


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

Validate_Finance
Validate_ISPN
Validate


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

Validate
Web Services
Validate


Web Services

Table of Contents

  • Services_Blogging
  • Services_Delicious
  • Services_Ebay
  • Services_Google
  • Services_Technorati
  • Services_W3C_HTMLValidator
  • Services_Weather
  • Services_Yahoo
  • Services_YouTube
  • UDDI
  • XML_RPC
  • XML_RPC2

Validate_ISPN
Services_Blogging
Packages


Services_Blogging

Generic driver-based package to post and read blog entries.

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

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.

Example #1 Instantiating a driver using Services_Blogging::factory()

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.

Example #2 Auto-discovering settings

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.

Example #3 Creating a driver automatically

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).

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.

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.

Example

Example #4 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());

?>
Web Services
Services_Delicious
Web Services


Services_Delicious

Object-oriented abstraction for del.icio.us XML API.

Services_Blogging
Introduction
Web Services


Services_Delicious
Example
Services_Delicious
PHP Manual

Introduction

(No version information available, might be only in CVS)

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().

Services_Delicious
Example
Services_Delicious


Services_Delicious
Services_Ebay
Services_Delicious
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Basic examples of Services_Delicious

Basic examples of Services_Delicious

The following examples show how to use some basic features of Services_Delicious:

Example #1 Fetching your recent posts

require_once 'Services/Delicious.php';

$dlc = &new Services_Delicious($username, $password);

$posts = $dlc->getRecentPosts();
echo '<pre>';
print_r($posts);
echo '</pre>';

Example #2 Getting all tags that you used in your bookmarks

require_once 'Services/Delicious.php';

$dlc = &new Services_Delicious($username, $password);

$tags = $dlc->getTags();
echo '<pre>';
print_r($tags);
echo '</pre>';

Example #3 Adding a new bookmark

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';
}
Services_Delicious
Services_Ebay
Services_Delicious


Services_Ebay

Object-oriented abstraction for eBay's XML API.

Example
Introduction
Web Services


Services_Ebay
Getting started
Services_Ebay
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Services_Ebay
Getting started
Services_Ebay


Getting started with the eBay webservice

Introduction
XML encoding
Services_Ebay
PHP Manual

Getting started

(No version information available, might be only in CVS)

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.

Example #1 The configuration file

// 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**';
Introduction
XML encoding
Services_Ebay


Getting started
Error Handling
Services_Ebay
PHP Manual

XML encoding

(No version information available, might be only in CVS)

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.

Example #1 Using ISO-8859-1 in your script

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.

Example #2 Using UTF-8 in your script

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.

Getting started
Error Handling
Services_Ebay


Error Handling in Services_Ebay

XML encoding
Architecture
Services_Ebay
PHP Manual

Error Handling

(No version information available, might be only in CVS)

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:

Example #1 Exception handling

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.

Example #2 Handling warnings

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());
    }
}
XML encoding
Architecture
Services_Ebay


The architecture of Services_Ebay

Error Handling
Example
Services_Ebay
PHP Manual

Architecture

(No version information available, might be only in CVS)

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.

Example #1 Using the session class

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.

Error Handling
Example
Services_Ebay
PHP Manual


Services_Ebay
Services_Google
Services_Ebay
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Basic example of Services_Ebay

Basic example of Services_Ebay

The following examples show how to use some basic features of Services_Ebay:

Example #1 Using a proxy object

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();

Example #2 Working directly with a Call object

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;

Example #3 Using the model classes

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);
Services_Ebay
Services_Google
Services_Ebay


Services_Google

Provides access to the Google SOAP Web APIs

Example
Introduction
Web Services


Services_Google
Example
Services_Google
PHP Manual

Introduction

(No version information available, might be only in CVS)

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().

Services_Google
Example
Services_Google


Services_Google
Services_Technorati
Services_Google
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Basic examples of Services_Google

Basic examples of Services_Google

The following examples show how to use some basic features of Services_Google:

Example #1 Search Google for PEAR

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";
}

Example #2 Spell Checking

require_once 'Services/Google.php';

$google = new Services_Google($key);

echo $google->spellingSuggestion("wahll")."\n";
Services_Google
Services_Technorati
Services_Google


Services_Technorati

A class for interacting with the Technorati API

Example
Introduction and Quick Start
Web Services


Overview of Services_Technorati

Services_Technorati
Services_W3C_HTMLValidator
Services_Technorati
PHP Manual

Introduction and Quick Start

(No version information available, might be only in CVS)

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:

$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:

$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.

Example #1 An example return from the blogInfo query (for 'jystewart') is:

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

Services_Technorati
Services_W3C_HTMLValidator
Services_Technorati


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.

Introduction and Quick Start
Introduction
Web Services


Introduction to Services_W3C_HTMLValidator

Services_W3C_HTMLValidator
Examples
Services_W3C_HTMLValidator
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Services_W3C_HTMLValidator
Examples
Services_W3C_HTMLValidator


Using Services_W3C_HTMLValidator

Services_W3C_HTMLValidator
Services_Weather
Services_W3C_HTMLValidator
PHP Manual

Examples

(No version information available, might be only in CVS)

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.

Example #1 Validate by URI

This is a simple example which shows how to validate a URI and return whether the page is valid or not.

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!';
}
Services_W3C_HTMLValidator
Services_Weather
Services_W3C_HTMLValidator


Services_Weather

Examples
Class Summary Services_Weather
Web Services


Services_Weather
Services_Weather::apiVersion
Services_Weather
PHP Manual

Class Summary Services_Weather

(No version information available, might be only in CVS)

Class Summary — 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

Services_Weather
Services_Weather::apiVersion
Services_Weather


For your convenience, when I come up with changes in the API...

Class Summary Services_Weather
Services_Weather::isError
Services_Weather
PHP Manual

Services_Weather::apiVersion()

(No version information available, might be only in CVS)

— For your convenience, when I come up with changes in the API...

funcsynopsis funcsynopsisinforequire_once '/Weather.php';/funcsynopsisinfo funcprototype funcdef string Services_Weather::apiVersion() /funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Class Summary Services_Weather
Services_Weather::isError
Services_Weather


Checks for an error object, same as in PEAR

Services_Weather::apiVersion
Services_Weather::service
Services_Weather
PHP Manual

Services_Weather::isError()

(No version information available, might be only in CVS)

— Checks for an error object, same as in PEAR

funcsynopsis funcsynopsisinforequire_once '/Weather.php';/funcsynopsisinfo funcprototype funcdef bool Services_Weather::isError() /funcdef paramdef PEAR_Error|mixed $value /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

PEAR_Error|mixed $value

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather::apiVersion
Services_Weather::service
Services_Weather


Factory for creating the services-objects

Services_Weather::isError
Class Summary Services_Weather_Common
Services_Weather
PHP Manual

Services_Weather::service()

(No version information available, might be only in CVS)

— Factory for creating the services-objects

funcsynopsis funcsynopsisinforequire_once '/Weather.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|object& Services_Weather::service() /funcdef paramdef string $service /paramdef paramdef array $options = NULL /paramdef /funcprototype /funcsynopsis

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.

Services_Weather::isError
Class Summary Services_Weather_Common
Services_Weather


Services_Weather::service
Services_Weather_Common::calculateDewPoint
Services_Weather
PHP Manual

Class Summary Services_Weather_Common

(No version information available, might be only in CVS)

Class Summary — 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

Services_Weather::service
Services_Weather_Common::calculateDewPoint
Services_Weather


Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula

Class Summary Services_Weather_Common
Services_Weather_Common::calculateHumidity
Services_Weather
PHP Manual

Services_Weather_Common::calculateDewPoint()

(No version information available, might be only in CVS)

— Calculate dewpoint from temperature and humidity This is only an approximation, there is no exact formula, this one here is called Magnus-Formula

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::calculateDewPoint() /funcdef paramdef float $temperature /paramdef paramdef float $humidity /paramdef /funcprototype /funcsynopsis

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.

Class Summary Services_Weather_Common
Services_Weather_Common::calculateHumidity
Services_Weather


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::calculateDewPoint
Services_Weather_Common::calculateWindChill
Services_Weather
PHP Manual

Services_Weather_Common::calculateHumidity()

(No version information available, might be only in CVS)

— Calculate humidity from temperature and dewpoint This is only an approximation, there is no exact formula, this one here is called Magnus-Formula

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::calculateHumidity() /funcdef paramdef float $temperature /paramdef paramdef float $dewPoint /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::calculateDewPoint
Services_Weather_Common::calculateWindChill
Services_Weather


Calculate windchill from temperature and windspeed (enhanced formula)

Services_Weather_Common::calculateHumidity
Services_Weather_Common::convertDistance
Services_Weather
PHP Manual

Services_Weather_Common::calculateWindChill()

(No version information available, might be only in CVS)

— Calculate windchill from temperature and windspeed (enhanced formula)

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::calculateWindChill() /funcdef paramdef float $temperature /paramdef paramdef float $speed /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::calculateHumidity
Services_Weather_Common::convertDistance
Services_Weather


Convert distance between km, ft and sm

Services_Weather_Common::calculateWindChill
Services_Weather_Common::convertPressure
Services_Weather
PHP Manual

Services_Weather_Common::convertDistance()

(No version information available, might be only in CVS)

— Convert distance between km, ft and sm

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::convertDistance() /funcdef paramdef float $distance /paramdef paramdef string $from /paramdef paramdef string $to /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::calculateWindChill
Services_Weather_Common::convertPressure
Services_Weather


Convert pressure between in, hpa, mb, mm and atm

Services_Weather_Common::convertDistance
Services_Weather_Common::convertSpeed
Services_Weather
PHP Manual

Services_Weather_Common::convertPressure()

(No version information available, might be only in CVS)

— Convert pressure between in, hpa, mb, mm and atm

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::convertPressure() /funcdef paramdef float $pressure /paramdef paramdef string $from /paramdef paramdef string $to /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::convertDistance
Services_Weather_Common::convertSpeed
Services_Weather


Convert speed between mph, kmh, kt, mps and fps

Services_Weather_Common::convertPressure
Services_Weather_Common::convertTemperature
Services_Weather
PHP Manual

Services_Weather_Common::convertSpeed()

(No version information available, might be only in CVS)

— Convert speed between mph, kmh, kt, mps and fps

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::convertSpeed() /funcdef paramdef float $speed /paramdef paramdef string $from /paramdef paramdef string $to /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::convertPressure
Services_Weather_Common::convertTemperature
Services_Weather


Convert temperature between f and c

Services_Weather_Common::convertSpeed
Services_Weather_Common::getUnitsFormat
Services_Weather
PHP Manual

Services_Weather_Common::convertTemperature()

(No version information available, might be only in CVS)

— Convert temperature between f and c

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef float Services_Weather_Common::convertTemperature() /funcdef paramdef float $temperature /paramdef paramdef string $from /paramdef paramdef string $to /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::convertSpeed
Services_Weather_Common::getUnitsFormat
Services_Weather


Returns the selected units format

Services_Weather_Common::convertTemperature
Services_Weather_Common::polar2cartesian
Services_Weather
PHP Manual

Services_Weather_Common::getUnitsFormat()

(No version information available, might be only in CVS)

— Returns the selected units format

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef array Services_Weather_Common::getUnitsFormat() /funcdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $unitsFormat

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather_Common::convertTemperature
Services_Weather_Common::polar2cartesian
Services_Weather


Convert polar coordinates to cartesian coordinates

Services_Weather_Common::getUnitsFormat
Services_Weather_Common::setCache
Services_Weather
PHP Manual

Services_Weather_Common::polar2cartesian()

(No version information available, might be only in CVS)

— Convert polar coordinates to cartesian coordinates

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef array Services_Weather_Common::polar2cartesian() /funcdef paramdef float $latitude /paramdef paramdef float $longitude /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

float $latitude

float $longitude

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather_Common::getUnitsFormat
Services_Weather_Common::setCache
Services_Weather


Enables caching the data, usage strongly recommended

Services_Weather_Common::polar2cartesian
Services_Weather_Common::setDateTimeFormat
Services_Weather
PHP Manual

Services_Weather_Common::setCache()

(No version information available, might be only in CVS)

— Enables caching the data, usage strongly recommended

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|bool Services_Weather_Common::setCache() /funcdef paramdef string $cacheType = "file" /paramdef paramdef array $cacheOptions = array() /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Common::polar2cartesian
Services_Weather_Common::setDateTimeFormat
Services_Weather


Changes the representation of time and dates (see http://www.php.net/date)

Services_Weather_Common::setCache
Services_Weather_Common::setHttpTimeout
Services_Weather
PHP Manual

Services_Weather_Common::setDateTimeFormat()

(No version information available, might be only in CVS)

— Changes the representation of time and dates (see http://www.php.net/date)

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef void Services_Weather_Common::setDateTimeFormat() /funcdef paramdef string $dateFormat = "" /paramdef paramdef string $timeFormat = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $dateFormat

string $timeFormat

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather_Common::setCache
Services_Weather_Common::setHttpTimeout
Services_Weather


Sets the timeout in seconds for HTTP requests

Services_Weather_Common::setDateTimeFormat
Services_Weather_Common::setUnitsFormat
Services_Weather
PHP Manual

Services_Weather_Common::setHttpTimeout()

(No version information available, might be only in CVS)

— Sets the timeout in seconds for HTTP requests

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef void Services_Weather_Common::setHttpTimeout() /funcdef paramdef int $httpTimeout /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

integer $httpTimeout

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather_Common::setDateTimeFormat
Services_Weather_Common::setUnitsFormat
Services_Weather


Changes the representation of the units (standard/metric)

Services_Weather_Common::setHttpTimeout
Class Summary Services_Weather_Ejse
Services_Weather
PHP Manual

Services_Weather_Common::setUnitsFormat()

(No version information available, might be only in CVS)

— Changes the representation of the units (standard/metric)

funcsynopsis funcsynopsisinforequire_once '/Weather/Common.php';/funcsynopsisinfo funcprototype funcdef void Services_Weather_Common::setUnitsFormat() /funcdef paramdef string $unitsFormat /paramdef paramdef array $customUnitsFormat = array() /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $unitsFormat

array $customUnitsFormat

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather_Common::setHttpTimeout
Class Summary Services_Weather_Ejse
Services_Weather


Services_Weather_Common::setUnitsFormat
Services_Weather_Ejse::getForecast
Services_Weather
PHP Manual

Class Summary Services_Weather_Ejse

(No version information available, might be only in CVS)

Class Summary — 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)

Services_Weather_Common::setUnitsFormat
Services_Weather_Ejse::getForecast
Services_Weather


Get the forecast for the next days

Class Summary Services_Weather_Ejse
Services_Weather_Ejse::getLocation
Services_Weather
PHP Manual

Services_Weather_Ejse::getForecast()

(No version information available, might be only in CVS)

— Get the forecast for the next days

funcsynopsis funcsynopsisinforequire_once '/Weather/Ejse.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Ejse::getForecast() /funcdef paramdef mixed $id = "" /paramdef paramdef int $days = 2 /paramdef paramdef string $unitsFormat = "" /paramdef paramdef string $int /paramdef /funcprototype /funcsynopsis

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.

Class Summary Services_Weather_Ejse
Services_Weather_Ejse::getLocation
Services_Weather


Returns the data for the location belonging to the ID

Services_Weather_Ejse::getForecast
Services_Weather_Ejse::getUnits
Services_Weather
PHP Manual

Services_Weather_Ejse::getLocation()

(No version information available, might be only in CVS)

— Returns the data for the location belonging to the ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Ejse.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Ejse::getLocation() /funcdef paramdef string $id = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Ejse::getForecast
Services_Weather_Ejse::getUnits
Services_Weather


Returns the units for the current query

Services_Weather_Ejse::getLocation
Services_Weather_Ejse::getWeather
Services_Weather
PHP Manual

Services_Weather_Ejse::getUnits()

(No version information available, might be only in CVS)

— Returns the units for the current query

funcsynopsis funcsynopsisinforequire_once '/Weather/Ejse.php';/funcsynopsisinfo funcprototype funcdef array Services_Weather_Ejse::getUnits() /funcdef paramdef string $id = NULL /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Ejse::getLocation
Services_Weather_Ejse::getWeather
Services_Weather


Returns the weather-data for the supplied location

Services_Weather_Ejse::getUnits
Services_Weather_Ejse::searchLocation
Services_Weather
PHP Manual

Services_Weather_Ejse::getWeather()

(No version information available, might be only in CVS)

— Returns the weather-data for the supplied location

funcsynopsis funcsynopsisinforequire_once '/Weather/Ejse.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Ejse::getWeather() /funcdef paramdef string $id = "" /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Ejse::getUnits
Services_Weather_Ejse::searchLocation
Services_Weather


EJSE offers no search function to date, so this function is disabled.

Services_Weather_Ejse::getWeather
Services_Weather_Ejse::searchLocationByCountry
Services_Weather
PHP Manual

Services_Weather_Ejse::searchLocation()

(No version information available, might be only in CVS)

— EJSE offers no search function to date, so this function is disabled.

funcsynopsis funcsynopsisinforequire_once '/Weather/Ejse.php';/funcsynopsisinfo funcprototype funcdef bool Services_Weather_Ejse::searchLocation() /funcdef paramdef string $location = NULL /paramdef paramdef bool $useFirst = NULL /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Ejse::getWeather
Services_Weather_Ejse::searchLocationByCountry
Services_Weather


EJSE offers no search function to date, so this function is disabled.

Services_Weather_Ejse::searchLocation
Class Summary Services_Weather_Globalweather
Services_Weather
PHP Manual

Services_Weather_Ejse::searchLocationByCountry()

(No version information available, might be only in CVS)

— EJSE offers no search function to date, so this function is disabled.

funcsynopsis funcsynopsisinforequire_once '/Weather/Ejse.php';/funcsynopsisinfo funcprototype funcdef bool Services_Weather_Ejse::searchLocationByCountry() /funcdef paramdef string $country = NULL /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Ejse::searchLocation
Class Summary Services_Weather_Globalweather
Services_Weather


Services_Weather_Ejse::searchLocationByCountry
Services_Weather_Globalweather::getForecast
Services_Weather
PHP Manual

Class Summary Services_Weather_Globalweather

(No version information available, might be only in CVS)

Class Summary — 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)

Services_Weather_Ejse::searchLocationByCountry
Services_Weather_Globalweather::getForecast
Services_Weather


GlobalWeather has no forecast per se, so this function is just for compatibility purposes.

Class Summary Services_Weather_Globalweather
Services_Weather_Globalweather::getLocation
Services_Weather
PHP Manual

Services_Weather_Globalweather::getForecast()

(No version information available, might be only in CVS)

— GlobalWeather has no forecast per se, so this function is just for compatibility purposes.

funcsynopsis funcsynopsisinforequire_once '/Weather/Globalweather.php';/funcsynopsisinfo funcprototype funcdef bool Services_Weather_Globalweather::getForecast() /funcdef paramdef mixed $id = NULL /paramdef paramdef int $days = NULL /paramdef paramdef string $unitsFormat = NULL /paramdef paramdef string $int /paramdef /funcprototype /funcsynopsis

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.

Class Summary Services_Weather_Globalweather
Services_Weather_Globalweather::getLocation
Services_Weather


Returns the data for the location belonging to the ID

Services_Weather_Globalweather::getForecast
Services_Weather_Globalweather::getUnits
Services_Weather
PHP Manual

Services_Weather_Globalweather::getLocation()

(No version information available, might be only in CVS)

— Returns the data for the location belonging to the ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Globalweather.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Globalweather::getLocation() /funcdef paramdef string $id = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Globalweather::getForecast
Services_Weather_Globalweather::getUnits
Services_Weather


Returns the units for the current query

Services_Weather_Globalweather::getLocation
Services_Weather_Globalweather::getWeather
Services_Weather
PHP Manual

Services_Weather_Globalweather::getUnits()

(No version information available, might be only in CVS)

— Returns the units for the current query

funcsynopsis funcsynopsisinforequire_once '/Weather/Globalweather.php';/funcsynopsisinfo funcprototype funcdef array Services_Weather_Globalweather::getUnits() /funcdef paramdef string $id = NULL /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Globalweather::getLocation
Services_Weather_Globalweather::getWeather
Services_Weather


Returns the weather-data for the supplied location

Services_Weather_Globalweather::getUnits
Services_Weather_Globalweather::searchLocation
Services_Weather
PHP Manual

Services_Weather_Globalweather::getWeather()

(No version information available, might be only in CVS)

— Returns the weather-data for the supplied location

funcsynopsis funcsynopsisinforequire_once '/Weather/Globalweather.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Globalweather::getWeather() /funcdef paramdef string $id = "" /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Globalweather::getUnits
Services_Weather_Globalweather::searchLocation
Services_Weather


Searches IDs for given location, returns array of possible locations or single ID

Services_Weather_Globalweather::getWeather
Services_Weather_Globalweather::searchLocationByCountry
Services_Weather
PHP Manual

Services_Weather_Globalweather::searchLocation()

(No version information available, might be only in CVS)

— Searches IDs for given location, returns array of possible locations or single ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Globalweather.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array|string Services_Weather_Globalweather::searchLocation() /funcdef paramdef string $location /paramdef paramdef bool $useFirst = FALSE /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Globalweather::getWeather
Services_Weather_Globalweather::searchLocationByCountry
Services_Weather


Returns IDs with location-name for a given country or all available countries, if no value was given

Services_Weather_Globalweather::searchLocation
Class Summary Services_Weather_Metar
Services_Weather
PHP Manual

Services_Weather_Globalweather::searchLocationByCountry()

(No version information available, might be only in CVS)

— Returns IDs with location-name for a given country or all available countries, if no value was given

funcsynopsis funcsynopsisinforequire_once '/Weather/Globalweather.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Globalweather::searchLocationByCountry() /funcdef paramdef string $country = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Globalweather::searchLocation
Class Summary Services_Weather_Metar
Services_Weather


Services_Weather_Globalweather::searchLocationByCountry
Services_Weather_Metar::getForecast
Services_Weather
PHP Manual

Class Summary Services_Weather_Metar

(No version information available, might be only in CVS)

Class Summary — 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)

Services_Weather_Globalweather::searchLocationByCountry
Services_Weather_Metar::getForecast
Services_Weather


METAR has no forecast per se, so this function is just for compatibility purposes.

Class Summary Services_Weather_Metar
Services_Weather_Metar::getLocation
Services_Weather
PHP Manual

Services_Weather_Metar::getForecast()

(No version information available, might be only in CVS)

— METAR has no forecast per se, so this function is just for compatibility purposes.

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef bool Services_Weather_Metar::getForecast() /funcdef paramdef mixed $id = NULL /paramdef paramdef int $days = NULL /paramdef paramdef string $unitsFormat = NULL /paramdef paramdef string $int /paramdef /funcprototype /funcsynopsis

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.

Class Summary Services_Weather_Metar
Services_Weather_Metar::getLocation
Services_Weather


Returns the data for the location belonging to the ID

Services_Weather_Metar::getForecast
Services_Weather_Metar::getUnits
Services_Weather
PHP Manual

Services_Weather_Metar::getLocation()

(No version information available, might be only in CVS)

— Returns the data for the location belonging to the ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Metar::getLocation() /funcdef paramdef string $id = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Metar::getForecast
Services_Weather_Metar::getUnits
Services_Weather


Returns the units for the current query

Services_Weather_Metar::getLocation
Services_Weather_Metar::getWeather
Services_Weather
PHP Manual

Services_Weather_Metar::getUnits()

(No version information available, might be only in CVS)

— Returns the units for the current query

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef array Services_Weather_Metar::getUnits() /funcdef paramdef string $id = NULL /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Metar::getLocation
Services_Weather_Metar::getWeather
Services_Weather


Returns the weather-data for the supplied location

Services_Weather_Metar::getUnits
Services_Weather_Metar::searchAirport
Services_Weather
PHP Manual

Services_Weather_Metar::getWeather()

(No version information available, might be only in CVS)

— Returns the weather-data for the supplied location

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef PHP_Error|array Services_Weather_Metar::getWeather() /funcdef paramdef string $id = "" /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PHP_Error

Note

This function can not be called statically.

Services_Weather_Metar::getUnits
Services_Weather_Metar::searchAirport
Services_Weather


Searches the nearest airport(s) for given coordinates, returns array of IDs or single ID

Services_Weather_Metar::getWeather
Services_Weather_Metar::searchLocation
Services_Weather
PHP Manual

Services_Weather_Metar::searchAirport()

(No version information available, might be only in CVS)

— Searches the nearest airport(s) for given coordinates, returns array of IDs or single ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array|string Services_Weather_Metar::searchAirport() /funcdef paramdef float $latitude /paramdef paramdef float $longitude /paramdef paramdef int $numResults = 1 /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Metar::getWeather
Services_Weather_Metar::searchLocation
Services_Weather


Searches IDs for given location, returns array of possible locations or single ID

Services_Weather_Metar::searchAirport
Services_Weather_Metar::searchLocationByCountry
Services_Weather
PHP Manual

Services_Weather_Metar::searchLocation()

(No version information available, might be only in CVS)

— Searches IDs for given location, returns array of possible locations or single ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array|string Services_Weather_Metar::searchLocation() /funcdef paramdef string|array $location /paramdef paramdef bool $useFirst = FALSE /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Metar::searchAirport
Services_Weather_Metar::searchLocationByCountry
Services_Weather


Returns IDs with location-name for a given country or all available countries, if no value was given

Services_Weather_Metar::searchLocation
Services_Weather_Metar::setMetarDB
Services_Weather
PHP Manual

Services_Weather_Metar::searchLocationByCountry()

(No version information available, might be only in CVS)

— Returns IDs with location-name for a given country or all available countries, if no value was given

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Metar::searchLocationByCountry() /funcdef paramdef string $country = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Metar::searchLocation
Services_Weather_Metar::setMetarDB
Services_Weather


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::searchLocationByCountry
Services_Weather_Metar::setMetarSource
Services_Weather
PHP Manual

Services_Weather_Metar::setMetarDB()

(No version information available, might be only in CVS)

— 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.

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef DB_Error|bool Services_Weather_Metar::setMetarDB() /funcdef paramdef string $dsn /paramdef paramdef array $dbOptions = array() /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Metar::searchLocationByCountry
Services_Weather_Metar::setMetarSource
Services_Weather


Sets the source, where the class tries to locate the METAR data

Services_Weather_Metar::setMetarDB
Class Summary Services_Weather_Weatherdotcom
Services_Weather
PHP Manual

Services_Weather_Metar::setMetarSource()

(No version information available, might be only in CVS)

— Sets the source, where the class tries to locate the METAR data

funcsynopsis funcsynopsisinforequire_once '/Weather/Metar.php';/funcsynopsisinfo funcprototype funcdef void Services_Weather_Metar::setMetarSource() /funcdef paramdef string $source /paramdef paramdef string $sourcePath = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Metar::setMetarDB
Class Summary Services_Weather_Weatherdotcom
Services_Weather


Services_Weather_Metar::setMetarSource
Services_Weather_Weatherdotcom::getForecast
Services_Weather
PHP Manual

Class Summary Services_Weather_Weatherdotcom

(No version information available, might be only in CVS)

Class Summary — 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)

Services_Weather_Metar::setMetarSource
Services_Weather_Weatherdotcom::getForecast
Services_Weather


Get the forecast for the next days

Class Summary Services_Weather_Weatherdotcom
Services_Weather_Weatherdotcom::getLocation
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::getForecast()

(No version information available, might be only in CVS)

— Get the forecast for the next days

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Weatherdotcom::getForecast() /funcdef paramdef string $id = "" /paramdef paramdef int $days = 2 /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

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.

Class Summary Services_Weather_Weatherdotcom
Services_Weather_Weatherdotcom::getLocation
Services_Weather


Returns the data for the location belonging to the ID

Services_Weather_Weatherdotcom::getForecast
Services_Weather_Weatherdotcom::getUnits
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::getLocation()

(No version information available, might be only in CVS)

— Returns the data for the location belonging to the ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Weatherdotcom::getLocation() /funcdef paramdef string $id = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Weatherdotcom::getForecast
Services_Weather_Weatherdotcom::getUnits
Services_Weather


Returns the units for the current query

Services_Weather_Weatherdotcom::getLocation
Services_Weather_Weatherdotcom::getWeather
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::getUnits()

(No version information available, might be only in CVS)

— Returns the units for the current query

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef array Services_Weather_Weatherdotcom::getUnits() /funcdef paramdef string $id = NULL /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Weatherdotcom::getLocation
Services_Weather_Weatherdotcom::getWeather
Services_Weather


Returns the weather-data for the supplied location

Services_Weather_Weatherdotcom::getUnits
Services_Weather_Weatherdotcom::searchLocation
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::getWeather()

(No version information available, might be only in CVS)

— Returns the weather-data for the supplied location

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array Services_Weather_Weatherdotcom::getWeather() /funcdef paramdef string $id = "" /paramdef paramdef string $unitsFormat = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $id

string $unitsFormat

Throws

throws PEAR_Error

Note

This function can not be called statically.

Services_Weather_Weatherdotcom::getUnits
Services_Weather_Weatherdotcom::searchLocation
Services_Weather


Searches IDs for given location, returns array of possible locations or single ID

Services_Weather_Weatherdotcom::getWeather
Services_Weather_Weatherdotcom::searchLocationByCountry
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::searchLocation()

(No version information available, might be only in CVS)

— Searches IDs for given location, returns array of possible locations or single ID

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef PEAR_Error|array|string Services_Weather_Weatherdotcom::searchLocation() /funcdef paramdef string $location /paramdef paramdef bool $useFirst = FALSE /paramdef /funcprototype /funcsynopsis

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.

Services_Weather_Weatherdotcom::getWeather
Services_Weather_Weatherdotcom::searchLocationByCountry
Services_Weather


Returns only false, as weather.com offers no country listing via its XML services

Services_Weather_Weatherdotcom::searchLocation
Services_Weather_Weatherdotcom::setAccountData
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::searchLocationByCountry()

(No version information available, might be only in CVS)

— Returns only false, as weather.com offers no country listing via its XML services

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef bool Services_Weather_Weatherdotcom::searchLocationByCountry() /funcdef paramdef string $country = "" /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $country

Throws

No exceptions thrown.

Deprecated

deprecated

Note

This function can not be called statically.

Services_Weather_Weatherdotcom::searchLocation
Services_Weather_Weatherdotcom::setAccountData
Services_Weather


Sets the neccessary account-information for weather.com, you'll receive them after registering for the XML-stream

Services_Weather_Weatherdotcom::searchLocationByCountry
Package Services_Weather Constants
Services_Weather
PHP Manual

Services_Weather_Weatherdotcom::setAccountData()

(No version information available, might be only in CVS)

— Sets the neccessary account-information for weather.com, you'll receive them after registering for the XML-stream

funcsynopsis funcsynopsisinforequire_once '/Weather/Weatherdotcom.php';/funcsynopsisinfo funcprototype funcdef void Services_Weather_Weatherdotcom::setAccountData() /funcdef paramdef string $partnerID /paramdef paramdef string $licenseKey /paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Parameter

string $partnerID

string $licenseKey

Throws

No exceptions thrown.

Note

This function can not be called statically.

Services_Weather_Weatherdotcom::searchLocationByCountry
Package Services_Weather Constants
Services_Weather


Constants defined in and used by Services_Weather

Services_Weather
Services_Yahoo
Services_Weather
PHP Manual

Package Services_Weather Constants

(No version information available, might be only in CVS)

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

Services_Weather
Services_Yahoo
Services_Weather


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.

Package Services_Weather Constants
Introduction
Web Services


Introduction to Services_Yahoo

Services_Yahoo
Examples
Services_Yahoo
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Services_Yahoo
Examples
Services_Yahoo


Using Services_Yahoo

Introduction
Design
Services_Yahoo
PHP Manual

Examples

(No version information available, might be only in CVS)

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.

Example #1 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.

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():

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");

    /* ... */

Example #2 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.

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";
    }
}

Example #3 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!.

Example #4 Term Extraction Service

The Term Extraction service provides a list of significant words or phrases extracted from a larger content.

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.

Example #5 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.

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";
    }
}
Introduction
Design
Services_Yahoo


Services_Yahoo's design

Services_Yahoo
Services_YouTube
Services_Yahoo
PHP Manual

Design

(No version information available, might be only in CVS)

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.

Services_Yahoo
Services_YouTube
Services_Yahoo


Services_YouTube

Object-oriented abstraction for YouTube API.

Design
Introduction
Web Services


Services_YouTube
Example
Services_YouTube
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Services_YouTube
Example
Services_YouTube


Services_YouTube
UDDI
Services_YouTube
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Basic examples of Services_YouTube

Basic examples of Services_YouTube

The following examples show how to use some basic features of Services_YouTube:

Example #1 Retrieves the public parts of a user profile.

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";

Example #2 Lists a user's favorite videos.

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";
}

Example #3 Lists a user's friends.

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}";
}

Example #4 Lists all videos that have the specified tag.

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";
}

Example #5 Lists all videos that were uploaded by the specified user.

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";
}

Example #6 Lists the most recent 25 videos that have been featured on the front page of the YouTube site.

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";
}

Example #7 Displays the details for a video.

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 />";
}
Services_YouTube
UDDI
Services_YouTube


UDDI

UDDI implementation for PHP

Example
Introduction
Web Services


UDDI implementation for PHP

UDDI
XML_RPC
UDDI
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

UDDI
XML_RPC
UDDI


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.

Introduction
Introduction
Web Services


Introduction

(No version information available, might be only in CVS)

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 emailjimw at php dot net/email

  • Peter Kocks emailpeter.kocks at baygate dot com/email

  • Nicolay Mausz emailmausz at flying-dog dot com/email

  • Ben Margolin emailben at wendy.auctionwatch dot com/email

  • Dan Libby emaildan at libby dot com/email

  • Gaetano Giunta emailg.giunta at libero dot it/email

  • Idan Sofer emaili_sofer at yahoo dot com/email

  • Giancarlo Pinerolo emailping at alt dot it/email

  • Justin Miller emailjustin at voxel dot net/email

Manifest - Files in the package

glosslist glossentry Server.php glossdef

the XML-RPC server class. include() this to get server functionality.

/glossdef /glossentry glossentry RPC.php glossdef

the XML-RPC client classes. include() this to get client functionality.

/glossdef /glossentry /glosslist
XML_RPC
Support
XML_RPC


Getting support for XML_RPC

Introduction
Examples
XML_RPC
PHP Manual

Support

(No version information available, might be only in CVS)

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!

Introduction
Examples
XML_RPC


Usage examples for the XML_RPC package

Support
API
XML_RPC
PHP Manual

Examples

(No version information available, might be only in CVS)

Examples — Usage examples for the XML_RPC package

Using a Client to Get Info About the Latest PEAR Release

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:

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:

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.

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...
Support
API
XML_RPC


Class documentation of the package

XML_RPC
XML_RPC2
XML_RPC
PHP Manual

API

(No version information available, might be only in CVS)

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:

funcsynopsis funcprototype funcdef$client = new XML_RPC_Client/funcdef paramdef string $path /paramdef paramdef string $server /paramdef paramdef integer $port /paramdef paramdef string $proxy /paramdef paramdef integer $proxy_port /paramdef paramdef string $proxy_user /paramdef paramdef string $proxy_pass /paramdef /funcprototype /funcsynopsis

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:

$client = new XML_RPC_Client('/RPC2', 'betty.userland.com');

Methods

This class supports the following methods.

send()

This method takes the form:

funcsynopsis funcprototype funcdef$response = $client->send/funcdef paramdef$xmlrpc_message /paramdef paramdef$timeout /paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$client->setCredentials/funcdef paramdef$username /paramdef paramdef$password /paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$client->setDebug/funcdef paramdef$debugOn /paramdef /funcprototype /funcsynopsis

$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:

funcsynopsis funcprototype funcdef$msg = new XML_RPC_Message/funcdef paramdef$methodName /paramdef paramdef$parameterArray /paramdef /funcprototype /funcsynopsis

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:

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()
funcsynopsis funcprototype funcdef$outString = $msg->serialize/funcdef paramdef /funcprototype /funcsynopsis

Returns the an XML string representing the XML-RPC message.

addParam()
funcsynopsis funcprototype funcdef$msg->addParam/funcdef paramdef$xmlrpcVal /paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$xmlrpcVal = $msg->getParam/funcdef paramdef$n /paramdef /funcprototype /funcsynopsis

Gets the $n th parameter in the message. Use this method in server implementations. Returns the undef value if no such parameter exists.

getNumParams()
funcsynopsis funcprototype funcdef$n = $msg->getNumParams/funcdef paramdef /funcprototype /funcsynopsis

Returns the number of parameters attached to this message.

method()
funcsynopsis funcprototype funcdef$methName=$msg->method/funcdef paramdef /funcprototype funcprototype funcdef$msg->method/funcdef paramdef$methName /paramdef /funcprototype /funcsynopsis

Gets or sets the method contained in the XML-RPC message.

parseResponse()
funcsynopsis funcprototype funcdef$response = $msg->parseResponse/funcdef paramdef$xmlString /paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$response = $msg->parseResponseFile/funcdef paramdef$fileHandle /paramdef /funcprototype /funcsynopsis

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

funcsynopsis funcprototype funcdef$resp = new XML_RPC_Response/funcdef paramdef$xmlrpcval /paramdef /funcprototype funcprototype funcdef$resp = new XML_RPC_Response/funcdef paramdef 0 /paramdef paramdef$errcode /paramdef paramdef$errstring /paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$fn = $resp->faultCode/funcdef paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$fs = $resp->faultString/funcdef paramdef /funcprototype /funcsynopsis

Returns the human readable explanation of the fault indicated by $resp->faultCode.

value()
funcsynopsis funcprototype funcdef$xmlrpcVal = $resp->value/funcdef paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$outString = $resp->serialize/funcdef paramdef /funcprototype /funcsynopsis

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:

funcsynopsis funcprototype funcdef$myVal = new XML_RPC_Value/funcdef paramdef /funcprototype funcprototype funcdef$myVal = new XML_RPC_Value/funcdef paramdef$stringVal /paramdef /funcprototype funcprototype funcdef$myVal = new XML_RPC_Value/funcdef paramdef$scalarVal /paramdef paramdef'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64' /paramdef /funcprototype funcprototype funcdef$myVal = new XML_RPC_Value/funcdef paramdef$arrayVal /paramdef paramdef'array' | 'struct' /paramdef /funcprototype /funcsynopsis

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:

$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()
funcsynopsis funcprototype funcdef$ok = $val->addScalar/funcdef paramdef$stringVal /paramdef /funcprototype funcprototype funcdef$ok = $val->addScalar/funcdef paramdef$scalarVal /paramdef paramdef'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64' /paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$ok = $val->addArray/funcdef paramdef$arrayVal /paramdef /funcprototype /funcsynopsis

Turns an empty XML_RPC_Value into an array with contents as specified by $arrayVal . See the fourth constructor form for more information.

addStruct()
funcsynopsis funcprototype funcdef$ok = $val->addStruct/funcdef paramdef$assocArrayVal /paramdef /funcprototype /funcsynopsis

Turns an empty XML_RPC_Value into a struct with contents as specified by $assocArrayVal . See the fourth constructor form for more information.

kindOf()
funcsynopsis funcprototype funcdef$kind = $val->kindOf/funcdef paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$outString = $val->serialize/funcdef paramdef /funcprototype /funcsynopsis

Returns a string containing the XML-RPC representation of this value.

scalarval()
funcsynopsis funcprototype funcdef$scalarVal = $val->scalarval/funcdef paramdef /funcprototype /funcsynopsis

If $val->kindOf() == 'scalar', this method returns the actual PHP-language value of the scalar (base 64 decoding is automatically handled here).

scalartyp()
funcsynopsis funcprototype funcdef$typeName = $val->scalartyp/funcdef paramdef /funcprototype /funcsynopsis

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()
funcsynopsis funcprototype funcdef$xmlrpcVal = $val->arraymem/funcdef paramdef$n /paramdef /funcprototype /funcsynopsis

Returns the $n th element in the array represented by the value $val . The value returned is an XML_RPC_Value object.

arraysize()
funcsynopsis funcprototype funcdef$len = $val->arraysize/funcdef paramdef /funcprototype /funcsynopsis

If $val is an array, returns the number of elements in that array.

structmem()
funcsynopsis funcprototype funcdef$xmlrpcVal = $val->structmem/funcdef paramdef$memberName /paramdef /funcprototype /funcsynopsis

Returns the element called $memberName from the struct represented by the value $val . The value returned is an XML_RPC_Value object.

structeach()
funcsynopsis funcprototype funcdeflist($key,$value) = $val->structeach/funcdef paramdef /funcprototype /funcsynopsis

Returns the next (key,value) pair from the struct, when $val is a struct. See also API.

structreset()
funcsynopsis funcprototype funcdef$val->structreset/funcdef paramdef /funcprototype /funcsynopsis

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:

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:

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:

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:

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:

array(
    array('boolean', 'int'),
    array('boolean', 'int', 'boolean'),
    array('boolean', 'string'),
    array('boolean', 'string', 'boolean'),
)

The server could be instatiated like this:

$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:

$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:

$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 phraseUnknown method/phrase

Returned if the server was asked to dispatch a method it didn't know about

2 phraseInvalid return payload/phrase

This error is actually generated by the client, not server, code, but signifies that a server returned something it couldn't understand.

3 phraseIncorrect parameters/phrase

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 phraseCan't introspect: method unknown/phrase

This error is generated by the builtin system.*() methods when any kind of introspection is attempted on a method undefined by the server.

5 phraseDidn't receive 200 OK from remote server/phrase

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- phraseXML parse errors/phrase

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()

funcsynopsis funcprototype funcdef$rpc = XML_RPC_encode/funcdef paramdef$php_val /paramdef /funcprototype /funcsynopsis

Takes native php types and encodes them into XML_RPC PHP object format.

XML_RPC_decode()

funcsynopsis funcprototype funcdef$values = XML_RPC_decode/funcdef paramdef$XML_RPC_val /paramdef /funcprototype /funcsynopsis

Takes a message in PHP XML_RPC object format and translates it into native PHP types.

XML_RPC
XML_RPC2
XML_RPC


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.

Web Services
Introduction
Web Services


Introduction

(No version information available, might be only in CVS)

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();

?>

XML_RPC2
Client Side
XML_RPC2


Client Side

(No version information available, might be only in CVS)

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).

require_once 'XML/RPC2/Client.php';

Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...).

$options = array(
    'prefix' => 'package.'
);

Third, you make a XML_RPC2_Client object with the server URL and the with the options array.

$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.

$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 :

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 :

// $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 :

// 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 :

$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"

?>

Introduction
Server Side
XML_RPC2


Server Side

(No version information available, might be only in CVS)

Server Side —

to be written

to be written

Client Side
Client Side with cache
XML_RPC2


Client Side with cache

(No version information available, might be only in CVS)

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).

require_once 'XML/RPC2/CachedClient.php';

Second, you make an assocative arrays of options to tune XML_RPC2 (prefix, proxy, manual backend choice...).

$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.

$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.

$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 :

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 :

// $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).

Server Side
Server Side with cache
XML_RPC2


Server Side with cache

(No version information available, might be only in CVS)

Server Side with cache —

to be written

to be written

XML_RPC2
XML
XML_RPC2


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

Provides Packages for creating and working with XML

Packages
XML_Beautifier
Packages


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.

XML
Introduction
XML


XML_Beautifier
Example
XML_Beautifier
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

XML_Beautifier
Example
XML_Beautifier


Example for the usage of XML_Beautifier

Introduction
Options
XML_Beautifier
PHP Manual

Example

(No version information available, might be only in CVS)

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 xmlns:xlink="http://www.w3.org/1999/xlink" url=
         "/about/project.xml">
         "About Pat"</link>
or
check out the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/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:

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 xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/about/project.xml">&quot;About Pat&quot;</link>
                or check out the
                <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/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>
Introduction
Options
XML_Beautifier


List of all XML_Beautifier options

Example
XML_Beautifier::XML_Beautifier
XML_Beautifier
PHP Manual

Options

(PECL maxdb:7.5.00.24-7.6.00.38)

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.

Example #1 Using setOptions() and setOption()

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.

Example #2 XML_Beautifier options

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');
Example
XML_Beautifier::XML_Beautifier
XML_Beautifier


create new instance

Options
XML_Beautifier::setOption
XML_Beautifier
PHP Manual

XML_Beautifier::XML_Beautifier()

(No version information available, might be only in CVS)

— create new instance

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefobject XML_Beautifier::XML_Beautifier()/funcdef paramdefarray $options = array() /paramdef /funcprototype /funcsynopsis

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.

Options
XML_Beautifier::setOption
XML_Beautifier


set an option

XML_Beautifier::XML_Beautifier
XML_Beautifier::setOptions
XML_Beautifier
PHP Manual

XML_Beautifier::setOption()

(No version information available, might be only in CVS)

— set an option

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Beautifier::setOption()/funcdef paramdefstring $option /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

XML_Beautifier::XML_Beautifier
XML_Beautifier::setOptions
XML_Beautifier


set several options

XML_Beautifier::setOption
XML_Beautifier::resetOptions
XML_Beautifier
PHP Manual

XML_Beautifier::setOptions()

(No version information available, might be only in CVS)

— set several options

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Beautifier::setOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

XML_Beautifier::setOption
XML_Beautifier::resetOptions
XML_Beautifier


reset options to default

XML_Beautifier::setOptions
XML_Beautifier::apiVersion
XML_Beautifier
PHP Manual

XML_Beautifier::resetOptions()

(No version information available, might be only in CVS)

— reset options to default

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Beautifier::resetOptions()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Beautifier::setOptions
XML_Beautifier::apiVersion
XML_Beautifier


return API version

XML_Beautifier::resetOptions
XML_Beautifier::formatFile
XML_Beautifier
PHP Manual

XML_Beautifier::apiVersion()

(No version information available, might be only in CVS)

— return API version

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Beautifier::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns API version of XML_Beautifier.

Return value

string API version

Note

This function can be called statically.

XML_Beautifier::resetOptions
XML_Beautifier::formatFile
XML_Beautifier


beautify a file

XML_Beautifier::apiVersion
XML_Beautifier::formatString
XML_Beautifier
PHP Manual

XML_Beautifier::formatFile()

(No version information available, might be only in CVS)

— beautify a file

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefobject XML_Beautifier::formatFile()/funcdef paramdefstring $file /paramdef paramdefstring $newFile = NULL /paramdef paramdefstring $renderer = "Plain" /paramdef /funcprototype /funcsynopsis

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.

XML_Beautifier::apiVersion
XML_Beautifier::formatString
XML_Beautifier


beautify a string

XML_Beautifier
XML_DTD
XML_Beautifier
PHP Manual

XML_Beautifier::formatString()

(No version information available, might be only in CVS)

— beautify a string

funcsynopsis funcsynopsisinfo require_once 'XML/Beautifier.php'; /funcsynopsisinfo funcprototype funcdefobject XML_Beautifier::formatString()/funcdef paramdefstring $string /paramdef paramdefstring $renderer = "Plain" /paramdef /funcprototype /funcsynopsis

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.

XML_Beautifier
XML_DTD
XML_Beautifier


XML_DTD

Parses DTD files and does DTD validation of XML documents.

XML_Beautifier::formatString
Introduction
XML


XML_DTD
XML_Feed_Parser
XML_DTD
PHP Manual

Introduction

(No version information available, might be only in CVS)

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 two 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

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.

XML_DTD
XML_Feed_Parser
XML_DTD


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.

Introduction
Introduction and Quick Start
XML


Overview of XML_Feed_Parser

XML_Feed_Parser
XML_Feed_Parser and Extensions
XML_Feed_Parser
PHP Manual

Introduction and Quick Start

(No version information available, might be only in CVS)

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:

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:

/* 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.

$title = $feed->title;

You can also access elements by iterating over the feed, or directly by offset or id.

foreach ($feed as $entry) {
    print $entry->title . "\n";
}

$first_entry = $feed->getEntryByOffset(0);

$particular_entry = $feed->getEntryById('http://jystewart.net/entry/1');

XML_Feed_Parser
XML_Feed_Parser and Extensions
XML_Feed_Parser


Handling extensions with XML_Feed_Parser

XML_Feed_Parser
XML_Parser
XML_Feed_Parser
PHP Manual

XML_Feed_Parser and Extensions

(No version information available, might be only in CVS)

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:

$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;
}

XML_Feed_Parser
XML_Parser
XML_Feed_Parser


XML_Parser

Object-oriented abstraction for PHP's xml extension.

XML_Feed_Parser and Extensions
Introduction
XML


XML_Parser
Example
XML_Parser
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

XML_Parser
Example
XML_Parser


Example for the usage of XML_Parser

Introduction
Modes
XML_Parser
PHP Manual

Example

(No version information available, might be only in CVS)

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).

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.

Introduction
Modes
XML_Parser


Explanation of possible parsing modes

Example
Choosing input
XML_Parser
PHP Manual

Modes

(No version information available, might be only in CVS)

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().

Example
Choosing input
XML_Parser


Explanation of different types of input data

XML_Parser
XML_Query2XML
XML_Parser
PHP Manual

Choosing input

(No version information available, might be only in CVS)

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().

XML_Parser
XML_Query2XML
XML_Parser


XML_Query2XML

Allows you to transform records retrieved with one or more SQL SELECT queries into XML data.

Choosing input
Introduction
XML


Start here

XML_Query2XML
XML_RDDL
XML_Query2XML
PHP Manual

Introduction

(No version information available, might be only in CVS)

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
XML_Query2XML
XML_RDDL
XML_Query2XML


XML_RDDL

Class to read RDDL (Resource Directory Description Language) documents.

Introduction
Introduction
XML


XML_RDDL
Example
XML_RDDL
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

XML_RDDL
Example
XML_RDDL


Example for the usage of XML_RDDL

Introduction
XML_RDDL::XML_RDDL
XML_RDDL
PHP Manual

Example

(No version information available, might be only in CVS)

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.

Example #1 Fetching resources from www.rddl.org

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>";
Introduction
XML_RDDL::XML_RDDL
XML_RDDL


Constructor

Example
XML_RDDL::parseRDDL
XML_RDDL
PHP Manual

XML_RDDL::XML_RDDL()

(No version information available, might be only in CVS)

— Constructor

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefobject XML_RDDL::XML_RDDL()/funcdef paramdefstring $rddlNamespace = "rddl" /paramdef paramdefstring $xlinkNamespace = "xlink" /paramdef /funcprototype /funcsynopsis

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.

Example
XML_RDDL::parseRDDL
XML_RDDL


parse a document that contains RDDL resources

XML_RDDL::XML_RDDL
XML_RDDL::getAllResources
XML_RDDL
PHP Manual

XML_RDDL::parseRDDL()

(No version information available, might be only in CVS)

— parse a document that contains RDDL resources

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefboolean XML_RDDL::parseRDDL()/funcdef paramdefstring $input /paramdef paramdefboolean $isFile = true /paramdef /funcprototype /funcsynopsis

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.

XML_RDDL::XML_RDDL
XML_RDDL::getAllResources
XML_RDDL


return all resources that have been found

XML_RDDL::parseRDDL
XML_RDDL::getResourceById
XML_RDDL
PHP Manual

XML_RDDL::getAllResources()

(No version information available, might be only in CVS)

— return all resources that have been found

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefarray XML_RDDL::getAllResources()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_RDDL::parseRDDL
XML_RDDL::getResourceById
XML_RDDL


get one resource from the document

XML_RDDL::getAllResources
XML_RDDL::getResourcesByNature
XML_RDDL
PHP Manual

XML_RDDL::getResourceById()

(No version information available, might be only in CVS)

— get one resource from the document

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefarray XML_RDDL::getResourceById()/funcdef paramdefstring $id /paramdef /funcprototype /funcsynopsis

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.

XML_RDDL::getAllResources
XML_RDDL::getResourcesByNature
XML_RDDL


selects all resources of a specified nature

XML_RDDL::getResourceById
XML_RDDL::getResourcesByPurpose
XML_RDDL
PHP Manual

XML_RDDL::getResourcesByNature()

(No version information available, might be only in CVS)

— selects all resources of a specified nature

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefarray XML_RDDL::getResourcesByNature()/funcdef paramdefstring $nature /paramdef /funcprototype /funcsynopsis

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

Example #1 Getting all stylesheets from a document

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>";
XML_RDDL::getResourceById
XML_RDDL::getResourcesByPurpose
XML_RDDL


selects all resources of a specified nature

XML_RDDL::getResourcesByNature
XML_RDDL::getResourcesByLanguage
XML_RDDL
PHP Manual

XML_RDDL::getResourcesByPurpose()

(No version information available, might be only in CVS)

— selects all resources of a specified nature

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefarray XML_RDDL::getResourcesByPurpose()/funcdef paramdefstring $purpose /paramdef /funcprototype /funcsynopsis

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

Example #1 Getting all normative references

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>";
XML_RDDL::getResourcesByNature
XML_RDDL::getResourcesByLanguage
XML_RDDL


selects all resources of a specified language

XML_RDDL::getResourcesByPurpose
XML_RDDL::apiVersion
XML_RDDL
PHP Manual

XML_RDDL::getResourcesByLanguage()

(No version information available, might be only in CVS)

— selects all resources of a specified language

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefarray XML_RDDL::getResourcesByLanguage()/funcdef paramdefstring $language /paramdef /funcprototype /funcsynopsis

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

Example #1 Getting all english resource

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>";
XML_RDDL::getResourcesByPurpose
XML_RDDL::apiVersion
XML_RDDL


return API version

XML_RDDL
XML_RSS
XML_RDDL
PHP Manual

XML_RDDL::apiVersion()

(No version information available, might be only in CVS)

— return API version

funcsynopsis funcsynopsisinfo require_once 'XML/RDDL.php'; /funcsynopsisinfo funcprototype funcdefstring XML_RDDL::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns API version of XML_RDDL.

Return value

string API version

Note

This function can be called statically.

XML_RDDL
XML_RSS
XML_RDDL


XML_RSS

Parser for Resource Description Framework (RDF) Site Summary (RSS) documents.

XML_RDDL::apiVersion
Introduction
XML


XML_RSS
Requirements
XML_RSS
PHP Manual

Introduction

(No version information available, might be only in CVS)

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).

Example #1 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 xmlns:xlink="http://www.w3.org/1999/xlink">http://example.com/</link>
 <description>abcd, xyz, 123</description>
</channel>

<image>
 <title>FooBar</title>
 <url>http://example.com/images/rssicon.gif</url>
 <link xmlns:xlink="http://www.w3.org/1999/xlink">http://example.com/</link>
</image>

<item>
 <title>Headline 1</title>
 <link xmlns:xlink="http://www.w3.org/1999/xlink">http://example.com/news.php?h=1</link>
</item>

<item>
 <title>Headline 2</title>
 <link xmlns:xlink="http://www.w3.org/1999/xlink">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 xmlns:xlink="http://www.w3.org/1999/xlink">http://example.com/search.php</link>
</textinput>

</rdf:RDF>
XML_RSS
Requirements
XML_RSS


Requirements for running XML_RSS

Introduction
Example
XML_RSS
PHP Manual

Requirements

(No version information available, might be only in CVS)

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.

Introduction
Example
XML_RSS


Example for the usage of XML_RSS

Requirements
XML_RSS::XML_RSS
XML_RSS
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Example for the usage of XML_RSS

Usage example

The following script fetches the latest headlines from Slashdot.org via RSS.

Example #1 Fetching headlines from Slashdot

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";
Requirements
XML_RSS::XML_RSS
XML_RSS


Constructor

Example
XML_RSS::getStructure
XML_RSS
PHP Manual

XML_RSS::XML_RSS

(No version information available, might be only in CVS)

XML_RSS::XML_RSS — Constructor

funcsynopsis funcsynopsisinfo require_once "XML/RSS.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_RSS::XML_RSS()/funcdef paramdef mixed $handle='' /paramdef /funcprototype /funcsynopsis

Description

Constructor

Parameter

  • mixed $handle - file pointer or name of the RDF file.

Note

This function can not be called statically.

Example

Example #1 Using XML_RSS()

$r =& new XML_RSS("test.rss");
Example
XML_RSS::getStructure
XML_RSS


Get complete structure of RSS file

XML_RSS::XML_RSS
XML_RSS::getChannelInfo
XML_RSS
PHP Manual

XML_RSS::getStructure

(No version information available, might be only in CVS)

XML_RSS::getStructure — Get complete structure of RSS file

funcsynopsis funcsynopsisinfo require_once "XML/RSS.php"; /funcsynopsisinfo funcprototype funcdefarray XML_RSS::getStructure()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_RSS::XML_RSS
XML_RSS::getChannelInfo
XML_RSS


Get general information about current channel

XML_RSS::getStructure
XML_RSS::getItems
XML_RSS
PHP Manual

XML_RSS::getChannelInfo

(No version information available, might be only in CVS)

XML_RSS::getChannelInfo — Get general information about current channel

funcsynopsis funcsynopsisinfo require_once "XML/RSS.php"; /funcsynopsisinfo funcprototype funcdefarray XML_RSS::getChannelInfo()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_RSS::getStructure
XML_RSS::getItems
XML_RSS


Get items from RSS file

XML_RSS::getChannelInfo
XML_RSS::getImages
XML_RSS
PHP Manual

XML_RSS::getItems

(No version information available, might be only in CVS)

XML_RSS::getItems — Get items from RSS file

funcsynopsis funcsynopsisinfo require_once "XML/RSS.php"; /funcsynopsisinfo funcprototype funcdefarray XML_RSS::getItems()/funcdef paramdef /funcprototype /funcsynopsis

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

Example #1 Using getItems()

foreach ($r->getItems() as $value) {
    echo $value['title'] . ": " . $value['link'] . "\n";
}
XML_RSS::getChannelInfo
XML_RSS::getImages
XML_RSS


Get images from RSS document

XML_RSS::getItems
XML_RSS::getTextinputs
XML_RSS
PHP Manual

XML_RSS::getImages

(No version information available, might be only in CVS)

XML_RSS::getImages — Get images from RSS document

funcsynopsis funcsynopsisinfo require_once "XML/RSS.php"; /funcsynopsisinfo funcprototype funcdefarray XML_RSS::getImages()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_RSS::getItems
XML_RSS::getTextinputs
XML_RSS


Get text input fields from RSS document

XML_RSS
XML_Serializer
XML_RSS
PHP Manual

XML_RSS::getTextinputs

(No version information available, might be only in CVS)

XML_RSS::getTextinputs — Get text input fields from RSS document

funcsynopsis funcsynopsisinfo require_once "XML/RSS.php"; /funcsynopsisinfo funcprototype funcdefarray XML_RSS::getTextinputs()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_RSS
XML_Serializer
XML_RSS


XML_Serializer

XML_RSS::getTextinputs
Introduction
XML


XML_Serializer
Package XML_Serializer Constants
XML_Serializer
PHP Manual

Introduction

(No version information available, might be only in CVS)

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

XML_Serializer
Package XML_Serializer Constants
XML_Serializer


Constants defined in and used by XML_Serializer

Introduction
Class Summary XML_Serializer
XML_Serializer
PHP Manual

Package XML_Serializer Constants

(No version information available, might be only in CVS)

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 | Line Number
XML_SERIALIZER_ERROR_NO_SERIALIZATION | 51 | 34

Constants defined in Unserializer.php

Constants defined in Unserializer.php
Name | Value | Line Number
XML_UNSERIALIZER_ERROR_NO_UNSERIALIZATION | 151 | 34

Introduction
Class Summary XML_Serializer
XML_Serializer


Package XML_Serializer Constants
constructor XML_Serializer::XML_Serializer
XML_Serializer
PHP Manual

Class Summary XML_Serializer

(No version information available, might be only in CVS)

Class Summary — 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.

Package XML_Serializer Constants
constructor XML_Serializer::XML_Serializer
XML_Serializer


constructor

Class Summary XML_Serializer
XML_Serializer::apiVersion
XML_Serializer
PHP Manual

constructor XML_Serializer::XML_Serializer()

(No version information available, might be only in CVS)

constructor — constructor

funcsynopsis funcsynopsisinfo require_once 'Serializer.php'; /funcsynopsisinfo funcprototype funcdefvoid constructor XML_Serializer::XML_Serializer()/funcdef paramdefmixed $options = NULL /paramdef /funcprototype /funcsynopsis

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.

Class Summary XML_Serializer
XML_Serializer::apiVersion
XML_Serializer


return API version

constructor XML_Serializer::XML_Serializer
XML_Serializer::serialize
XML_Serializer
PHP Manual

XML_Serializer::apiVersion()

(No version information available, might be only in CVS)

— return API version

funcsynopsis funcsynopsisinfo require_once 'Serializer.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Serializer::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

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.

constructor XML_Serializer::XML_Serializer
XML_Serializer::serialize
XML_Serializer


serialize data

XML_Serializer::apiVersion
XML_Serializer::getSerializedData
XML_Serializer
PHP Manual

XML_Serializer::serialize()

(No version information available, might be only in CVS)

— serialize data

funcsynopsis funcsynopsisinfo require_once 'Serializer.php'; /funcsynopsisinfo funcprototype funcdefboolean XML_Serializer::serialize()/funcdef paramdefmixed $data /paramdef paramdefmixed $options = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Serializer::apiVersion
XML_Serializer::getSerializedData
XML_Serializer


get the result of the serialization

XML_Serializer::serialize
XML_Serializer::resetOptions
XML_Serializer
PHP Manual

XML_Serializer::getSerializedData()

(No version information available, might be only in CVS)

— get the result of the serialization

funcsynopsis funcsynopsisinfo require_once 'Serializer.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Serializer::getSerializedData()/funcdef paramdef /funcprototype /funcsynopsis

Description

This package is not documented yet.

Throws

throws no exceptions thrown

Note

This function can not be called statically.

XML_Serializer::serialize
XML_Serializer::resetOptions
XML_Serializer


reset all options to default options

XML_Serializer::getSerializedData
XML_Serializer::setOption
XML_Serializer
PHP Manual

XML_Serializer::resetOptions()

(No version information available, might be only in CVS)

— reset all options to default options

funcsynopsis funcsynopsisinfo require_once 'Serializer.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Serializer::resetOptions()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Serializer::getSerializedData
XML_Serializer::setOption
XML_Serializer


set an option

XML_Serializer::resetOptions
Example
XML_Serializer
PHP Manual

XML_Serializer::setOption()

(No version information available, might be only in CVS)

— set an option

funcsynopsis funcsynopsisinfo require_once 'Serializer.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Serializer::setOption()/funcdef paramdefmixed $name /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

XML_Serializer::resetOptions
Example
XML_Serializer


Example for the usage of XML_Serializer

XML_Serializer::setOption
Tutorial: Create an RSS Feed
XML_Serializer
PHP Manual

Example

(No version information available, might be only in CVS)

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.

$serializer = &new XML_Serializer($options);
$foo = PEAR::raiseError('Just a test', 1234);
$result = $serializer->serialize($foo);
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.

$serializer = new XML_Serializer($options);
    $result = $serializer->serialize($rdf);
    echo    htmlentities($serializer->getSerializedData());
/**
   * @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 xmlns:xlink="http://www.w3.org/1999/xlink">http://www.php-tools.de</link>
        <image>
            <title>Example image</title>
            <url>http://www.php-tools.de/image.gif</url>
            <link xmlns:xlink="http://www.w3.org/1999/xlink">http://www.php-tools.de</link>
        </image>
        <item rdf:about="http://example.com/foobar.html">
            <title>Example item</title>
            <link xmlns:xlink="http://www.w3.org/1999/xlink">http://example.com</link>
        </item>
        <item rdf:about="http://example.com/foobar.html">
            <title>Another item</title>
            <link xmlns:xlink="http://www.w3.org/1999/xlink">http://example.com</link>
        </item>
        <item rdf:about="http://example.com/foobar.html">
            <title>I think you get it...</title>
            <link xmlns:xlink="http://www.w3.org/1999/xlink">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.

$serializer = new XML_Serializer($options);
    $result = $serializer->serialize($rdf);
    echo    htmlentities($serializer->getSerializedData());
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

XML_Serializer::setOption
Tutorial: Create an RSS Feed
XML_Serializer


How to use XML_Serializer to build an RSS Newsfeed

Example
Class Summary XML_Unserializer
XML_Serializer
PHP Manual

Tutorial: Create an RSS Feed

(No version information available, might be only in CVS)

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 xmlns:xlink="http://www.w3.org/1999/xlink">http://freedomink.org/</link>
        <item>
            <item>
                <title>First Article</title>
                <link xmlns:xlink="http://www.w3.org/1999/xlink">http://freedomink.org/node/view/55</link>
                <description>Short blurb about article........</description>
            </item>
            <item>
                <title>Second Article</title>
                <link xmlns:xlink="http://www.w3.org/1999/xlink">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",
    "tagName"   => "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.

$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.

$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.

$data['channel'] = array(
    "title" => "Freedom Ink",
    "link"  => "http://freedomink.org/",
    $stories
);

Now we generate the XML using the PEAR XML_Serializer package.

$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.

Example
Class Summary XML_Unserializer
XML_Serializer


Tutorial: Create an RSS Feed
XML_Unserializer Options
XML_Serializer
PHP Manual

Class Summary XML_Unserializer

(No version information available, might be only in CVS)

Class Summary — 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.

Tutorial: Create an RSS Feed
XML_Unserializer Options
XML_Serializer


List of all XML_Unserializer options

Class Summary XML_Unserializer
XML_Unserializer::XML_Unserializer
XML_Serializer
PHP Manual

XML_Unserializer Options

(No version information available, might be only in CVS)

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
Option | Possible values | Default | Description
complexType | 'array' or 'object' | 'array' | Defines, whether nested tags should be returned as associative arrays or objects
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, that class defined by 'defaultClass' is used.
defaultClass | any string | stdClass | Defines the class that is used to create objects, if the complexType option is set to 'object'.
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.
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
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.
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.
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
prependAttributes | any string | '' | Allows you to specify a prefix for attribute names.
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.
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.
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 a some if conditions in your code.
encoding | any valid encoding string | null | Defines the encoding of the original document.
targetEncoding | any valid encoding string | null | Defines the target encoding of the resulting data.
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.
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.

Options example

The following examples shows how to set options for XML_Unserializer.

Example #1 Using the constructor

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, if the instance already has been created.

Example #2 Using setOption() and setOptions()

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);
Class Summary XML_Unserializer
XML_Unserializer::XML_Unserializer
XML_Serializer


Constructor for XML_Unserializer

XML_Unserializer Options
XML_Unserializer::apiVersion
XML_Serializer
PHP Manual

XML_Unserializer::XML_Unserializer()

(No version information available, might be only in CVS)

— Constructor for XML_Unserializer

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdef XML_Unserializer::XML_Unserializer()/funcdef paramdefarray $options = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer Options
XML_Unserializer::apiVersion
XML_Serializer


return API version

XML_Unserializer::XML_Unserializer
XML_Unserializer::unserialize
XML_Serializer
PHP Manual

XML_Unserializer::apiVersion()

(No version information available, might be only in CVS)

— return API version

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Unserializer::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer::XML_Unserializer
XML_Unserializer::unserialize
XML_Serializer


unserialize data

XML_Unserializer::apiVersion
XML_Unserializer::getUnserializedData
XML_Serializer
PHP Manual

XML_Unserializer::unserialize()

(No version information available, might be only in CVS)

— unserialize data

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefboolean XML_Unserializer::unserialize()/funcdef paramdefstring $data /paramdef paramdefboolean $isFile = FALSE /paramdef paramdefarray $options = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer::apiVersion
XML_Unserializer::getUnserializedData
XML_Serializer


get the result of the unserialization

XML_Unserializer::unserialize
XML_Unserializer::getRootName
XML_Serializer
PHP Manual

XML_Unserializer::getUnserializedData()

(No version information available, might be only in CVS)

— get the result of the unserialization

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Unserializer::getUnserializedData()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer::unserialize
XML_Unserializer::getRootName
XML_Serializer


get the name of the root tag of the parsed document.

XML_Unserializer::getUnserializedData
XML_Unserializer::setOption
XML_Serializer
PHP Manual

XML_Unserializer::getRootName()

(No version information available, might be only in CVS)

— get the name of the root tag of the parsed document.

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Unserializer::getRootName()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer::getUnserializedData
XML_Unserializer::setOption
XML_Serializer


set an option

XML_Unserializer::getRootName
XML_Unserializer::setoptions
XML_Serializer
PHP Manual

XML_Unserializer::setOption()

(No version information available, might be only in CVS)

— set an option

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Unserializer::setOption()/funcdef paramdefstring $name /paramdef paramdefmixed $value /paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer::getRootName
XML_Unserializer::setoptions
XML_Serializer


set several options

XML_Unserializer::setOption
XML_Unserializer::resetOptions
XML_Serializer
PHP Manual

XML_Unserializer::setoptions()

(No version information available, might be only in CVS)

— set several options

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Unserializer::setOptions()/funcdef paramdefarray $options /paramdef /funcprototype /funcsynopsis

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.

XML_Unserializer::setOption
XML_Unserializer::resetOptions
XML_Serializer


reset all options to default options

XML_Serializer
XML_sql2xml
XML_Serializer
PHP Manual

XML_Unserializer::resetOptions()

(No version information available, might be only in CVS)

— reset all options to default options

funcsynopsis funcsynopsisinfo require_once 'Unserializer.php'; /funcsynopsisinfo funcprototype funcdefvoid XML_Unserializer::resetOptions()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Serializer
XML_sql2xml
XML_Serializer


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

XML_Unserializer::resetOptions
Introduction
XML


Simple transformations

XML_sql2xml
Introduction
XML_sql2xml
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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.

Example #2 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.

Example #3 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>
XML_sql2xml
Introduction
XML_sql2xml


Passing the data to transform

Introduction
Introduction
XML_sql2xml
PHP Manual

Introduction

(No version information available, might be only in CVS)

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().

Example #1 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.

Example #2 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.

Example #3 Adding result sets

$sql2xmlclass->add("select * from bands");
$sql2xmlclass->add("select * from albums");
$xmlstring= $sql2xmlclass->getxml();
Introduction
Introduction
XML_sql2xml


Using XPath

Introduction
XML_sql2xml::XML_sql2xml
XML_sql2xml
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

Example #1 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'

Example #2 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.

Example #3 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>
Introduction
XML_sql2xml::XML_sql2xml
XML_sql2xml


Constructor

Introduction
XML_sql2xml::add
XML_sql2xml
PHP Manual

XML_sql2xml::XML_sql2xml

(No version information available, might be only in CVS)

XML_sql2xml::XML_sql2xml — Constructor

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::XML_sql2xml()/funcdef paramdef mixed $dsn = NULL /paramdef paramdef string $root="root" /paramdef /funcprototype /funcsynopsis

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

Example #1 Using XML_sql2xml()

$sql2xml = new xml_sql2xml("mysql://root@localhost/xmltest");
$sql2xml->Add("select * from bands");
Introduction
XML_sql2xml::add
XML_sql2xml


General method for adding new result sets

XML_sql2xml::XML_sql2xml
XML_sql2xml::addXmlFile
XML_sql2xml
PHP Manual

XML_sql2xml::add

(No version information available, might be only in CVS)

XML_sql2xml::add — General method for adding new result sets

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::add()/funcdef paramdef string $resultset /paramdef paramdef mixed $params = NULL /paramdef /funcprototype /funcsynopsis

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

Example #1 Using add()

$sql2xml->Add("select * from bands");
XML_sql2xml::XML_sql2xml
XML_sql2xml::addXmlFile
XML_sql2xml


Adds a XML file

XML_sql2xml::add
XML_sql2xml::addXmlString
XML_sql2xml
PHP Manual

XML_sql2xml::addXmlFile

(No version information available, might be only in CVS)

XML_sql2xml::addXmlFile — Adds a XML file

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::addXmlFile()/funcdef paramdef string $file /paramdef paramdef mixed $xpath = NULL /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml::add
XML_sql2xml::addXmlString
XML_sql2xml


Adds XML string

XML_sql2xml::addXmlFile
XML_sql2xml::addResult
XML_sql2xml
PHP Manual

XML_sql2xml::addXmlString

(No version information available, might be only in CVS)

XML_sql2xml::addXmlString — Adds XML string

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::addXmlString()/funcdef paramdef string $string /paramdef paramdef mixed $xpath = NULL /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml::addXmlFile
XML_sql2xml::addResult
XML_sql2xml


Adds an PEAR::DB result set

XML_sql2xml::addXmlString
XML_sql2xml::addSql
XML_sql2xml
PHP Manual

XML_sql2xml::addResult

(No version information available, might be only in CVS)

XML_sql2xml::addResult — Adds an PEAR::DB result set

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::addResult()/funcdef paramdef Object $result /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml::addXmlString
XML_sql2xml::addSql
XML_sql2xml


Adds an result set from a SQL statement

XML_sql2xml::addResult
XML_sql2xml::addArray
XML_sql2xml
PHP Manual

XML_sql2xml::addSql

(No version information available, might be only in CVS)

XML_sql2xml::addSql — Adds an result set from a SQL statement

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::addSql()/funcdef paramdef string $sql /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml::addResult
XML_sql2xml::addArray
XML_sql2xml


Adds an aditional result set from an array

XML_sql2xml::addSql
XML_sql2xml::getXML
XML_sql2xml
PHP Manual

XML_sql2xml::addArray

(No version information available, might be only in CVS)

XML_sql2xml::addArray — Adds an aditional result set from an array

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::addArray()/funcdef paramdef array $array /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml::addSql
XML_sql2xml::getXML
XML_sql2xml


Returns a XML representation of the result set.

XML_sql2xml::addArray
XML_sql2xml::getXMLObject
XML_sql2xml
PHP Manual

XML_sql2xml::getXML

(No version information available, might be only in CVS)

XML_sql2xml::getXML — Returns a XML representation of the result set.

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefstring XML_sql2xml::getXML()/funcdef paramdef mixed $result = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_sql2xml::addArray
XML_sql2xml::getXMLObject
XML_sql2xml


return an XML DomDocument object

XML_sql2xml::getXML
XML_sql2xml::setOptions
XML_sql2xml
PHP Manual

XML_sql2xml::getXMLObject

(No version information available, might be only in CVS)

XML_sql2xml::getXMLObject — return an XML DomDocument object

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefObject XML_sql2xml::getXMLObject()/funcdef paramdef mixed $result = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_sql2xml::getXML
XML_sql2xml::setOptions
XML_sql2xml


set options for the instance

XML_sql2xml::getXMLObject
XML_sql2xml::setEncoding
XML_sql2xml
PHP Manual

XML_sql2xml::setOptions

(No version information available, might be only in CVS)

XML_sql2xml::setOptions — set options for the instance

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::setOptions()/funcdef paramdef array $options /paramdef paramdef constant $delete=FALSE /paramdef /funcprototype /funcsynopsis

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.

XML_sql2xml::getXMLObject
XML_sql2xml::setEncoding
XML_sql2xml


set encoding charset

XML_sql2xml::setOptions
XML_sql2xml::getXpathValue
XML_sql2xml
PHP Manual

XML_sql2xml::setEncoding

(No version information available, might be only in CVS)

XML_sql2xml::setEncoding — set encoding charset

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_sql2xml::setEncoding()/funcdef paramdef string $encoding_from="ISO-8859-1" /paramdef paramdef string $encoding_to="UTF-8" /paramdef /funcprototype /funcsynopsis

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.

XML_sql2xml::setOptions
XML_sql2xml::getXpathValue
XML_sql2xml


return match of a XPath expression

XML_sql2xml::setEncoding
XML_sql2xml::getXpathChildValues
XML_sql2xml
PHP Manual

XML_sql2xml::getXpathValue

(No version information available, might be only in CVS)

XML_sql2xml::getXpathValue — return match of a XPath expression

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefmixed XML_sql2xml::getXpathValue()/funcdef paramdef string $expr /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml::setEncoding
XML_sql2xml::getXpathChildValues
XML_sql2xml


return child tags from match of a XPath expression

XML_sql2xml
XML_Statistics
XML_sql2xml
PHP Manual

XML_sql2xml::getXpathChildValues

(No version information available, might be only in CVS)

XML_sql2xml::getXpathChildValues — return child tags from match of a XPath expression

funcsynopsis funcsynopsisinfo require_once "XML/sql2xml.php"; /funcsynopsisinfo funcprototype funcdefarray XML_sql2xml::getXpathChildValues()/funcdef paramdef string $expr /paramdef /funcprototype /funcsynopsis

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()

XML_sql2xml
XML_Statistics
XML_sql2xml


XML_Statistics

Package to statistically analyze an XML document.

XML_sql2xml::getXpathChildValues
Introduction
XML


XML_Statistics
Example
XML_Statistics
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

XML_Statistics
Example
XML_Statistics


Example for the usage of XML_Statistics

Introduction
XML_Statistics::apiVersion
XML_Statistics
PHP Manual

Example

(No version information available, might be only in CVS)

Example — Example for the usage of XML_Statistics

Usage example

The following examples shows how XML_Statistics can be used to analyze a document.

Example #1 Basic example

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 />";
Introduction
XML_Statistics::apiVersion
XML_Statistics


return API version

Example
XML_Statistics::analyzeFile
XML_Statistics
PHP Manual

XML_Statistics::apiVersion()

(No version information available, might be only in CVS)

— return API version

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Statistics::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns API version of XML_Statistics.

Return value

string API version

Note

This function can be called statically.

Example
XML_Statistics::analyzeFile
XML_Statistics


Analyze an XML file

XML_Statistics::apiVersion
XML_Statistics::analyzeString
XML_Statistics
PHP Manual

XML_Statistics::analyzeFile()

(No version information available, might be only in CVS)

— Analyze an XML file

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Statistics::analyzeFile()/funcdef paramdefstring $filename /paramdef /funcprototype /funcsynopsis

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()

XML_Statistics::apiVersion
XML_Statistics::analyzeString
XML_Statistics


Analyze an XML string

XML_Statistics::analyzeFile
XML_Statistics::countTag
XML_Statistics
PHP Manual

XML_Statistics::analyzeString()

(No version information available, might be only in CVS)

— Analyze an XML string

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Statistics::analyzeString()/funcdef paramdefstring $string /paramdef /funcprototype /funcsynopsis

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()

XML_Statistics::analyzeFile
XML_Statistics::countTag
XML_Statistics


count the occurences of a tag

XML_Statistics::analyzeString
XML_Statistics::countTagsInDepth
XML_Statistics
PHP Manual

XML_Statistics::countTag()

(No version information available, might be only in CVS)

— count the occurences of a tag

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::countTag()/funcdef paramdefstring $tagname = null /paramdef /funcprototype /funcsynopsis

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()

XML_Statistics::analyzeString
XML_Statistics::countTagsInDepth
XML_Statistics


count the tags in a certain depth

XML_Statistics::countTag
XML_Statistics::countPI
XML_Statistics
PHP Manual

XML_Statistics::countTagsInDepth()

(No version information available, might be only in CVS)

— count the tags in a certain depth

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::counttagsindepth()/funcdef paramdefinteger $depth /paramdef /funcprototype /funcsynopsis

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()

XML_Statistics::countTag
XML_Statistics::countPI
XML_Statistics


count the occurences of a processing instruction

XML_Statistics::countTagsInDepth
XML_Statistics::countExternalEntity
XML_Statistics
PHP Manual

XML_Statistics::countPI()

(No version information available, might be only in CVS)

— count the occurences of a processing instruction

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::countPI()/funcdef paramdefstring $target = null /paramdef /funcprototype /funcsynopsis

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.

XML_Statistics::countTagsInDepth
XML_Statistics::countExternalEntity
XML_Statistics


count the occurences of an external entitity

XML_Statistics::countPI
XML_Statistics::getMaxDepth
XML_Statistics
PHP Manual

XML_Statistics::countExternalEntity()

(No version information available, might be only in CVS)

— count the occurences of an external entitity

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::countExternalEntity()/funcdef paramdefstring $name = null /paramdef /funcprototype /funcsynopsis

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.

XML_Statistics::countPI
XML_Statistics::getMaxDepth
XML_Statistics


get the maximum nesting level

XML_Statistics::countExternalEntity
XML_Statistics::countAttribute
XML_Statistics
PHP Manual

XML_Statistics::getMaxDepth()

(No version information available, might be only in CVS)

— get the maximum nesting level

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::getMaxDepth()/funcdef paramdef /funcprototype /funcsynopsis

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.

XML_Statistics::countExternalEntity
XML_Statistics::countAttribute
XML_Statistics


count the occurences of an attribute

XML_Statistics::getMaxDepth
XML_Statistics::countDataChunks
XML_Statistics
PHP Manual

XML_Statistics::countAttribute()

(No version information available, might be only in CVS)

— count the occurences of an attribute

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::countAttribute()/funcdef paramdefstring $attribute = null /paramdef paramdefstring $tagname = null /paramdef /funcprototype /funcsynopsis

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()

XML_Statistics::getMaxDepth
XML_Statistics::countDataChunks
XML_Statistics


count the occurences of a data blocks

XML_Statistics::countAttribute
XML_Statistics::getCDataLength
XML_Statistics
PHP Manual

XML_Statistics::countDataChunks()

(No version information available, might be only in CVS)

— count the occurences of a data blocks

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::countDataChunks()/funcdef paramdef /funcprototype /funcsynopsis

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()

XML_Statistics::countAttribute
XML_Statistics::getCDataLength
XML_Statistics


get the combined length of all CData sections

XML_Statistics
XML_Transformer
XML_Statistics
PHP Manual

XML_Statistics::getCDataLength()

(No version information available, might be only in CVS)

— get the combined length of all CData sections

funcsynopsis funcsynopsisinfo require_once 'XML/Statistics.php'; /funcsynopsisinfo funcprototype funcdefinteger XML_Statistics::getCDataLength()/funcdef paramdef /funcprototype /funcsynopsis

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()

XML_Statistics
XML_Transformer
XML_Statistics


XML_Transformer

XML Transformations in PHP.

XML_Statistics::getCDataLength
Introduction
XML


XML_Transformer
XML_Transformer::XML_Transformer
XML_Transformer
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

XML_Transformer
XML_Transformer::XML_Transformer
XML_Transformer


XML_Transformer::XML_Transformer

(No version information available, might be only in CVS)

XML_Transformer::XML_Transformer —

funcsynopsis funcprototype funcdefvoid XML_Transformer::XML_Transformer()/funcdef paramdefarray parameters /paramdef /funcprototype /funcsynopsis

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.

Introduction
XML_Transformer::overloadElement
XML_Transformer


XML_Transformer::overloadElement

(No version information available, might be only in CVS)

XML_Transformer::overloadElement —

funcsynopsis funcprototype funcdefvoid XML_Transformer::overloadElement()/funcdef paramdefstring element /paramdef paramdefstring startHandler /paramdef paramdefstring endHandler /paramdef paramdefboolean recursiveOperation /paramdef /funcprototype /funcsynopsis

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.

XML_Transformer::XML_Transformer
XML_Transformer::overloadNamespace
XML_Transformer


XML_Transformer::overloadNamespace

(No version information available, might be only in CVS)

XML_Transformer::overloadNamespace —

funcsynopsis funcprototype funcdefvoid XML_Transformer::overloadNamespace()/funcdef paramdefstring namespacePrefix /paramdef paramdefobject object /paramdef paramdefboolean recursiveOperation /paramdef /funcprototype /funcsynopsis

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.

XML_Transformer::overloadElement
XML_Transformer::isOverloadedElement
XML_Transformer


XML_Transformer::isOverloadedElement

(No version information available, might be only in CVS)

XML_Transformer::isOverloadedElement —

funcsynopsis funcprototype funcdefboolean XML_Transformer::isOverloadedElement()/funcdef paramdefstring element /paramdef /funcprototype /funcsynopsis

Description

Returns TRUE if the given element is overloaded, FALSE otherwise.

XML_Transformer::overloadNamespace
XML_Transformer::isOverloadedNamespace
XML_Transformer


XML_Transformer::isOverloadedNamespace

(No version information available, might be only in CVS)

XML_Transformer::isOverloadedNamespace —

funcsynopsis funcprototype funcdefboolean XML_Transformer::isOverloadedNamespace()/funcdef paramdefstring namespacePrefix /paramdef /funcprototype /funcsynopsis

Description

Returns TRUE if the given namespace is overloaded, FALSE otherwise.

XML_Transformer::isOverloadedElement
XML_Transformer::unOverloadElement
XML_Transformer


XML_Transformer::unOverloadElement

(No version information available, might be only in CVS)

XML_Transformer::unOverloadElement —

funcsynopsis funcprototype funcdefboolean XML_Transformer::unOverloadElement()/funcdef paramdefstring element /paramdef /funcprototype /funcsynopsis

Description

Reverts overloading of the given element.

XML_Transformer::isOverloadedNamespace
XML_Transformer::unOverloadNamespace
XML_Transformer


XML_Transformer::unOverloadNamespace

(No version information available, might be only in CVS)

XML_Transformer::unOverloadNamespace —

funcsynopsis funcprototype funcdefboolean XML_Transformer::unOverloadNamespace()/funcdef paramdefstring namespacePrefix /paramdef /funcprototype /funcsynopsis

Description

Reverts overloading of the given namespace.

XML_Transformer::unOverloadElement
XML_Transformer::start
XML_Transformer


XML_Transformer::start

(No version information available, might be only in CVS)

XML_Transformer::start —

funcsynopsis funcprototype funcdefvoid XML_Transformer::start()/funcdef paramdef /funcprototype /funcsynopsis

Description

Starts the transformation, if it has not yet been started, for instance by the constructor.

XML_Transformer::unOverloadNamespace
XML_Transformer::transform
XML_Transformer


XML_Transformer::transform

(No version information available, might be only in CVS)

XML_Transformer::transform —

funcsynopsis funcprototype funcdefstring XML_Transformer::transform()/funcdef paramdefstring xml /paramdef /funcprototype /funcsynopsis

Description

Transforms a given XML string.

XML_Transformer::start
XML_Transformer::setCaseFolding
XML_Transformer


XML_Transformer::setCaseFolding

(No version information available, might be only in CVS)

XML_Transformer::setCaseFolding —

funcsynopsis funcprototype funcdefvoid XML_Transformer::setCaseFolding()/funcdef paramdefboolean caseFolding /paramdef paramdefinteger caseFoldingTo /paramdef /funcprototype /funcsynopsis

Description

Sets the XML parser's case-folding option.

XML_Transformer::transform
XML_Transformer::setDebug
XML_Transformer


XML_Transformer::setDebug
XML_Transformer
PHP Manual

XML_Transformer::setDebug

(No version information available, might be only in CVS)

XML_Transformer::setDebug —

funcsynopsis funcprototype funcdefvoid XML_Transformer::setDebug() /funcdef paramdefmixed debug /paramdef /funcprototype /funcsynopsis

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.

XML_Transformer::setCaseFolding
XML_Transformer::setDebug
XML_Transformer


XML_Transformer::setDebug
XML_Transformer::stackdump
XML_Transformer
PHP Manual

XML_Transformer::setDebug

(No version information available, might be only in CVS)

XML_Transformer::setDebug —

funcsynopsis funcprototype funcdefvoid XML_Transformer::setRecursiveOperation()/funcdef paramdefboolean recursiveOperation /paramdef /funcprototype /funcsynopsis

Description

Enables or disables the recursive operation.

XML_Transformer::setDebug
XML_Transformer::stackdump
XML_Transformer


XML_Transformer::stackdump

(No version information available, might be only in CVS)

XML_Transformer::stackdump —

funcsynopsis funcprototype funcdefstring XML_Transformer::stackdump()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns a stack dump as a debugging aid.

XML_Transformer::setDebug
XML_Transformer::attributesToString
XML_Transformer


XML_Transformer::attributesToString

(No version information available, might be only in CVS)

XML_Transformer::attributesToString —

funcsynopsis funcprototype funcdefstring XML_Transformer::attributesToString()/funcdef paramdefarray attributes /paramdef /funcprototype /funcsynopsis

Description

Returns string representation of attributes array.

XML_Transformer::stackdump
XML_Transformer::canonicalize
XML_Transformer


XML_Transformer::canonicalize

(No version information available, might be only in CVS)

XML_Transformer::canonicalize —

funcsynopsis funcprototype funcdefmixed XML_Transformer::canonicalName()/funcdef paramdefmixed target /paramdef /funcprototype /funcsynopsis

Description

Canonicalizes XML attribute arrays and element names.

XML_Transformer
XML_Tree
XML_Transformer


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.

XML_Transformer::canonicalize
XML_Tree::XML_Tree
XML


Constructor

XML_Tree
XML_Tree::&addRoot
XML_Tree
PHP Manual

XML_Tree::XML_Tree

(No version information available, might be only in CVS)

XML_Tree::XML_Tree — Constructor

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_Tree::XML_Tree()/funcdef paramdef string $filename='' /paramdef paramdef string $version='1.0' /paramdef /funcprototype /funcsynopsis

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.

XML_Tree
XML_Tree::&addRoot
XML_Tree


add root node

XML_Tree::XML_Tree
XML_Tree::&insertChild
XML_Tree
PHP Manual

XML_Tree::&addRoot

(No version information available, might be only in CVS)

XML_Tree::&addRoot — add root node

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefobject XML_Tree_Node XML_Tree::&addRoot()/funcdef paramdef string $name /paramdef paramdef string $content='' /paramdef paramdef array $attributes=array() /paramdef /funcprototype /funcsynopsis

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

Example #1 Using &addRoot()

$tree  = new XML_Tree;
$root =& $tree->addRoot("root");
XML_Tree::XML_Tree
XML_Tree::&insertChild
XML_Tree


inserts a child/tree

XML_Tree::&addRoot
XML_Tree::&removeChild
XML_Tree
PHP Manual

XML_Tree::&insertChild

(No version information available, might be only in CVS)

XML_Tree::&insertChild — inserts a child/tree

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefobject XML_Tree_Node XML_Tree::&insertChild()/funcdef paramdef array $path /paramdef paramdef integer $pos /paramdef paramdef mixed $child /paramdef paramdef string $content='' /paramdef paramdef array $attributes=array() /paramdef /funcprototype /funcsynopsis

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()

XML_Tree::&addRoot
XML_Tree::&removeChild
XML_Tree


remove child from tree

XML_Tree::&insertChild
XML_Tree::&getTreeFromFile
XML_Tree
PHP Manual

XML_Tree::&removeChild

(No version information available, might be only in CVS)

XML_Tree::&removeChild — remove child from tree

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefobject XML_Tree_Node XML_Tree::&removeChild()/funcdef paramdef array $path /paramdef paramdef integer $pos /paramdef /funcprototype /funcsynopsis

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()

XML_Tree::&insertChild
XML_Tree::&getTreeFromFile
XML_Tree


map XML file to tree

XML_Tree::&removeChild
XML_Tree::clone
XML_Tree
PHP Manual

XML_Tree::&getTreeFromFile

(No version information available, might be only in CVS)

XML_Tree::&getTreeFromFile — map XML file to tree

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefobject XML_Tree XML_Tree::&getTreeFromFile()/funcdef paramdef /funcprototype /funcsynopsis

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()

XML_Tree::&removeChild
XML_Tree::clone
XML_Tree


copy tree

XML_Tree::&getTreeFromFile
XML_Tree::dump
XML_Tree
PHP Manual

XML_Tree::clone

(No version information available, might be only in CVS)

XML_Tree::clone — copy tree

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefobject XML_Tree XML_Tree::clone()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get a copy of this tree instance.

Return value

object XML_Tree - the copied object

Note

This function can not be called statically.

XML_Tree::&getTreeFromFile
XML_Tree::dump
XML_Tree


print XML tree.

XML_Tree::clone
XML_Tree::&get
XML_Tree
PHP Manual

XML_Tree::dump

(No version information available, might be only in CVS)

XML_Tree::dump — print XML tree.

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_Tree::dump()/funcdef paramdef /funcprototype /funcsynopsis

Description

Print text representation of XML tree.

Note

This function can not be called statically.

See

XML_Tree::get()

XML_Tree::clone
XML_Tree::&get
XML_Tree


get XML tree.

XML_Tree::dump
XML_Tree::&getName
XML_Tree
PHP Manual

XML_Tree::&get

(No version information available, might be only in CVS)

XML_Tree::&get — get XML tree.

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefstring XML_Tree::&get()/funcdef paramdef /funcprototype /funcsynopsis

Description

Get text representation of XML tree.

Return value

string - XML document

Note

This function can not be called statically.

See

XML_Tree::get()

XML_Tree::dump
XML_Tree::&getName
XML_Tree


get namespace.

XML_Tree::&get
XML_Tree::registerName
XML_Tree
PHP Manual

XML_Tree::&getName

(No version information available, might be only in CVS)

XML_Tree::&getName — get namespace.

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefstring XML_Tree::&getName()/funcdef paramdef string $name /paramdef /funcprototype /funcsynopsis

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()

XML_Tree::&get
XML_Tree::registerName
XML_Tree


register namespace.

XML_Tree
XML_Util
XML_Tree
PHP Manual

XML_Tree::registerName

(No version information available, might be only in CVS)

XML_Tree::registerName — register namespace.

funcsynopsis funcsynopsisinfo require_once "XML/Tree.php"; /funcsynopsisinfo funcprototype funcdefvoid XML_Tree::registerName()/funcdef paramdef string $name /paramdef paramdef string $path /paramdef /funcprototype /funcsynopsis

Description

Registers a namespace.

Parameter

  • string $name - namespace

  • string $path - path

Note

This function can not be called statically.

See

XML_Tree::getName()

XML_Tree
XML_Util
XML_Tree


XML_Util

Collection of often needed methods that help you creating XML documents.

XML
Introduction
XML


XML_Util
Example
XML_Util
PHP Manual

Introduction

(No version information available, might be only in CVS)

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.

XML_Util
Example
XML_Util


Example for the usage of XML_Util

Introduction
XML_Util::apiVersion
XML_Util
PHP Manual

Example

(No version information available, might be only in CVS)

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.

Example #1 Some basic examples

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.";
}
Introduction
XML_Util::apiVersion
XML_Util


return API version

Example
XML_Util::attributesToString
XML_Util
PHP Manual

XML_Util::apiVersion()

(No version information available, might be only in CVS)

— return API version

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::apiVersion()/funcdef paramdef /funcprototype /funcsynopsis

Description

Returns API version of XML_Util.

Return value

string API version

Note

This function should be called statically.

Example
XML_Util::attributesToString
XML_Util


create XML attribute string

XML_Util::apiVersion
XML_Util::collapseEmptyTags
XML_Util
PHP Manual

XML_Util::attributesToString()

(No version information available, might be only in CVS)

— create XML attribute string

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::attributesToString()/funcdef paramdefarray $attributes /paramdef paramdefboolean $sort = TRUE /paramdef paramdefboolean $multiline = FALSE /paramdef paramdefstring $indent = ' ' /paramdef paramdefstring $linebreak = "\n" /paramdef paramdefinteger $entities = XML_UTIL_ENTITIES_XML /paramdef /funcprototype /funcsynopsis

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.

XML_Util::apiVersion
XML_Util::collapseEmptyTags
XML_Util


collapse empty XML tags in a string

XML_Util::attributesToString
XML_Util::createTag
XML_Util
PHP Manual

XML_Util::collapseEmptyTags()

(No version information available, might be only in CVS)

— collapse empty XML tags in a string

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::collapseEmptyTags()/funcdef paramdefstring $string /paramdef paramdefinteger $mode = XML_UTIL_COLLAPSE_ALL /paramdef /funcprototype /funcsynopsis

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.

XML_Util::attributesToString
XML_Util::createTag
XML_Util


create a tag

XML_Util::collapseEmptyTags
XML_Util::createTagFromArray
XML_Util
PHP Manual

XML_Util::createTag()

(No version information available, might be only in CVS)

— create a tag

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::createTag()/funcdef paramdefstring $qname /paramdef paramdefarray $attributes = array() /paramdef paramdefstring $content = NULL /paramdef paramdefstring $namespaceUri = NULL /paramdef paramdefinteger $replaceEntities = XML_UTIL_REPLACE_ENTITIES /paramdef /funcprototype /funcsynopsis

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.

XML_Util::collapseEmptyTags
XML_Util::createTagFromArray
XML_Util


create a tag from an array

XML_Util::createTag
XML_Util::createStartElement
XML_Util
PHP Manual

XML_Util::createTagFromArray()

(No version information available, might be only in CVS)

— create a tag from an array

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::createTagFromArray()/funcdef paramdefarray $tag /paramdef paramdefinteger $replaceEntities = XML_UTIL_REPLACE_ENTITIES /paramdef /funcprototype /funcsynopsis

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

Example #1 Creating a tag with XML_Util::createTagFromArray()

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);
XML_Util::createTag
XML_Util::createStartElement
XML_Util


create a start element

XML_Util::createTagFromArray
XML_Util::createEndElement
XML_Util
PHP Manual

XML_Util::createStartElement()

(No version information available, might be only in CVS)

— create a start element

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::createStartElement()/funcdef paramdefstring $qname /paramdef paramdefarray $attributes = array() /paramdef paramdefstring $namespaceUri = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Util::createTagFromArray
XML_Util::createEndElement
XML_Util


create an end element

XML_Util::createStartElement
XML_Util::createCDataSection
XML_Util
PHP Manual

XML_Util::createEndElement()

(No version information available, might be only in CVS)

— create an end element

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::createEndElement()/funcdef paramdefstring $qname /paramdef /funcprototype /funcsynopsis

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.

XML_Util::createStartElement
XML_Util::createCDataSection
XML_Util


create a CData section

XML_Util::createEndElement
XML_Util::createComment
XML_Util
PHP Manual

XML_Util::createCDataSection()

(No version information available, might be only in CVS)

— create a CData section

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::createCDataSection()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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.

XML_Util::createEndElement
XML_Util::createComment
XML_Util


create an XML comment

XML_Util::createCDataSection
XML_Util::getDocTypeDeclaration
XML_Util
PHP Manual

XML_Util::createComment()

(No version information available, might be only in CVS)

— create an XML comment

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::createComment()/funcdef paramdefstring $data /paramdef /funcprototype /funcsynopsis

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.

XML_Util::createCDataSection
XML_Util::getDocTypeDeclaration
XML_Util


build a document type declaration

XML_Util::createComment
XML_Util::getXMLDeclaration
XML_Util
PHP Manual

XML_Util::getDocTypeDeclaration()

(No version information available, might be only in CVS)

— build a document type declaration

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::getDocTypeDeclaration()/funcdef paramdefstring $root /paramdef paramdefmixed $uri = NULL /paramdef paramdefmixed $internalDtd = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Util::createComment
XML_Util::getXMLDeclaration
XML_Util


build an xml declaration

XML_Util::getDocTypeDeclaration
XML_Util::isValidName
XML_Util
PHP Manual

XML_Util::getXMLDeclaration()

(No version information available, might be only in CVS)

— build an xml declaration

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::getXMLDeclaration()/funcdef paramdefstring $version = "1.0" /paramdef paramdefstring $encoding = NULL /paramdef paramdefboolean $standalone = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Util::getDocTypeDeclaration
XML_Util::isValidName
XML_Util


verify an XML name

XML_Util::getXMLDeclaration
XML_Util::replaceEntities
XML_Util
PHP Manual

XML_Util::isValidName()

(No version information available, might be only in CVS)

— verify an XML name

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefboolean XML_Util::isValidName()/funcdef paramdefstring $string /paramdef /funcprototype /funcsynopsis

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.

XML_Util::getXMLDeclaration
XML_Util::replaceEntities
XML_Util


replace XML entities

XML_Util::isValidName
XML_Util::reverseEntities
XML_Util
PHP Manual

XML_Util::replaceEntities()

(No version information available, might be only in CVS)

— replace XML entities

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::replaceEntities()/funcdef paramdefstring $string /paramdef /funcprototype /funcsynopsis

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.

XML_Util::isValidName
XML_Util::reverseEntities
XML_Util


replace XML entities

XML_Util::replaceEntities
XML_Util::splitQualifiedName
XML_Util
PHP Manual

XML_Util::reverseEntities()

(No version information available, might be only in CVS)

— replace XML entities

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefstring XML_Util::reverseEntities()/funcdef paramdefstring $string /paramdef /funcprototype /funcsynopsis

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.

XML_Util::replaceEntities
XML_Util::splitQualifiedName
XML_Util


split qualified name

XML_Util
XML_Util
PHP Manual

XML_Util::splitQualifiedName()

(No version information available, might be only in CVS)

— split qualified name

funcsynopsis funcsynopsisinfo require_once 'XML/Util.php'; /funcsynopsisinfo funcprototype funcdefarray XML_Util::splitQualifiedName()/funcdef paramdefstring $qname /paramdef paramdefstring $defaultNs = NULL /paramdef /funcprototype /funcsynopsis

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.

XML_Util
XML_Util