2007-06-17
Copyright © 1997-2007 the PHP Documentation Group
Copyright
Copyright © 1997 - 2007 by the PHP 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. A copy of the Open Publication License is distributed with this manual, 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.
In case you are interested in redistribution or republishing of this document in whole or in part, either modified or unmodified, and you have questions, please contact the copyright holders at doc-license@lists.php.net. Note that this address is mapped to a publicly archived mailing list.
The Chapter 56 section of the documentation is based on an initial contribution by Zend Technologies.
PHP, which stands for "PHP: Hypertext Preprocessor" is a widely-used Open Source general-purpose scripting language that is especially suited for Web development and can be embedded into HTML. Its syntax draws upon C, Java, and Perl, and is easy to learn. The main goal of the language is to allow web developers to write dynamically generated web pages quickly, but you can do much more with PHP.
This manual consists primarily of a function reference, but also contains a language reference, explanations of some of PHP's major features, and other supplemental information.
You can download this manual in several formats at http://www.php.net/download-docs.php. More information about how this manual is developed can be found in the 'About the manual' appendix. If you are interested in the history of PHP, visit the relevant appendix.
We highlight the currently most active people on the manual frontpage, but there are many more contributors who currently help in our work or provided a great amount of help to the project in the past. There are a lot of unnamed people who help out with their user notes on manual pages, which continually get included in the references, the work of whom we are also very thankful for. All the lists provided below are in alphabetical order.
The following contributors should be recognized for the impact they have made and/or continue to make by adding content to the manual: Bill Abt, Jouni Ahto, Alexander Aulbach, Daniel Beckham, Stig Bakken, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Hannes Magnusson, Stanislav Malyshev, Rafael Martinez, Rick McGuire, Yasuo Ohgaki, Derick Rethans, Rob Richards, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar and Andrei Zmievski.
The following contributors have done significant work editing the manual: Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe and Egon Schmid.
The currently most active maintainers are: Mehdi Achour, Friedhelm Betz, Etienne Kneuss, Nuno Lopes, Hannes Magnusson, Bobby Matthis and Philip Olson.
These people have also put a lot of effort into managing user notes: Daniel Beckham, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Maxim Maletsky, James Moore, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Maciek Sokolewicz, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles and Jeroen van Wolffelaar.
PHP (recursive acronym for "PHP: Hypertext Preprocessor") is a widely-used Open Source general-purpose scripting language that is especially suited for Web development and can be embedded into HTML.
Simple answer, but what does that mean? An example:
Notice how this is different from a script written in other languages like Perl or C -- instead of writing a program with lots of commands to output HTML, you write an HTML script with some embedded code to do something (in this case, output some text). The PHP code is enclosed in special start and end tags that allow you to jump into and out of "PHP mode".
What distinguishes PHP from something like client-side JavaScript is that the code is executed on the server. If you were to have a script similar to the above on your server, the client would receive the results of running that script, with no way of determining what the underlying code may be. You can even configure your web server to process all your HTML files with PHP, and then there's really no way that users can tell what you have up your sleeve.
The best things in using PHP are that it is extremely simple for a newcomer, but offers many advanced features for a professional programmer. Don't be afraid reading the long list of PHP's features. You can jump in, in a short time, and start writing simple scripts in a few hours.
Although PHP's development is focused on server-side scripting, you can do much more with it. Read on, and see more in the What can PHP do? section, or go right to the introductory tutorial if you are only interested in web programming.
Anything. PHP is mainly focused on server-side scripting, so you can do anything any other CGI program can do, such as collect form data, generate dynamic page content, or send and receive cookies. But PHP can do much more.
There are three main areas where PHP scripts are used.
Server-side scripting. This is the most traditional and main target field for PHP. You need three things to make this work. The PHP parser (CGI or server module), a web server and a web browser. You need to run the web server, with a connected PHP installation. You can access the PHP program output with a web browser, viewing the PHP page through the server. All these can run on your home machine if you are just experimenting with PHP programming. See the installation instructions section for more information.
Command line scripting. You can make a PHP script to run it without any server or browser. You only need the PHP parser to use it this way. This type of usage is ideal for scripts regularly executed using cron (on *nix or Linux) or Task Scheduler (on Windows). These scripts can also be used for simple text processing tasks. See the section about Command line usage of PHP for more information.
Writing desktop applications. PHP is probably not the very best language to create a desktop application with a graphical user interface, but if you know PHP very well, and would like to use some advanced PHP features in your client-side applications you can also use PHP-GTK to write such programs. You also have the ability to write cross-platform applications this way. PHP-GTK is an extension to PHP, not available in the main distribution. If you are interested in PHP-GTK, visit its own website.
PHP can be used on all major operating systems, including Linux, many Unix variants (including HP-UX, Solaris and OpenBSD), Microsoft Windows, Mac OS X, RISC OS, and probably others. PHP has also support for most of the web servers today. This includes Apache, Microsoft Internet Information Server, Personal Web Server, Netscape and iPlanet servers, Oreilly Website Pro server, Caudium, Xitami, OmniHTTPd, and many others. For the majority of the servers PHP has a module, for the others supporting the CGI standard, PHP can work as a CGI processor.
So with PHP, you have the freedom of choosing an operating system and a web server. Furthermore, you also have the choice of using procedural programming or object oriented programming, or a mixture of them. Although not every standard OOP feature is implemented in PHP 4, many code libraries and large applications (including the PEAR library) are written only using OOP code. PHP 5 fixes the OOP related weaknesses of PHP 4, and introduces a complete object model.
With PHP you are not limited to output HTML. PHP's abilities includes outputting images, PDF files and even Flash movies (using libswf and Ming) generated on the fly. You can also output easily any text, such as XHTML and any other XML file. PHP can autogenerate these files, and save them in the file system, instead of printing it out, forming a server-side cache for your dynamic content.
One of the strongest and most significant features in PHP is its support for a wide range of databases. Writing a database-enabled web page is incredibly simple. The following databases are currently supported:
We also have a database abstraction extension (named PDO) allowing you to transparently use any database supported by that extension. Additionally PHP supports ODBC, the Open Database Connection standard, so you can connect to any other database supporting this world standard.
Adabas D InterBase PostgreSQL dBase FrontBase SQLite Empress mSQL Solid FilePro (read-only) Direct MS-SQL Sybase Hyperwave MySQL Velocis IBM DB2 ODBC Unix dbm Informix Oracle (OCI7 and OCI8) Ingres Ovrimos
PHP also has support for talking to other services using protocols such as LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (on Windows) and countless others. You can also open raw network sockets and interact using any other protocol. PHP has support for the WDDX complex data exchange between virtually all Web programming languages. Talking about interconnection, PHP has support for instantiation of Java objects and using them transparently as PHP objects. You can also use our CORBA extension to access remote objects.
PHP has extremely useful text processing features, from the POSIX Extended or Perl regular expressions to parsing XML documents. For parsing and accessing XML documents, PHP 4 supports the SAX and DOM standards, and you can also use the XSLT extension to transform XML documents. PHP 5 standardizes all the XML extensions on the solid base of libxml2 and extends the feature set adding SimpleXML and XMLReader support.
At last but not least, we have many other interesting extensions, the mnoGoSearch search engine functions, the IRC Gateway functions, many compression utilities (gzip, bz2, zip), calendar conversion, translation...
As you can see this page is not enough to list all the features and benefits PHP can offer. Read on in the sections about installing PHP, and see the function reference part for explanation of the extensions mentioned here.
Here we would like to show the very basics of PHP in a short, simple tutorial. This text only deals with dynamic web page creation with PHP, though PHP is not only capable of creating web pages. See the section titled What can PHP do for more information.
PHP-enabled web pages are treated just like regular HTML pages and you can create and edit them the same way you normally create regular HTML pages.
In this tutorial we assume that your server has activated support for PHP and that all files ending in .php are handled by PHP. On most servers, this is the default extension for PHP files, but ask your server administrator to be sure. If your server supports PHP, then you do not need to do anything. Just create your .php files, put them in your web directory and the server will automatically parse them for you. There is no need to compile anything nor do you need to install any extra tools. Think of these PHP-enabled files as simple HTML files with a whole new family of magical tags that let you do all sorts of things. Most web hosts offer PHP support, but if your host does not, consider reading the PHP Links section for resources on finding PHP enabled web hosts.
Let us say you want to save precious bandwidth and develop locally. In this case, you will want to install a web server, such as Apache, and of course PHP. You will most likely want to install a database as well, such as MySQL.
You can either install these individually or choose a simpler way. Our manual has installation instructions for PHP (assuming you already have some web server set up). In case you have problems with installing PHP yourself, we would suggest you ask your questions on our installation mailing list. If you choose to go on the simpler route, then locate a pre-configured package for your operating system, which automatically installs all of these with just a few mouse clicks. It is easy to setup a web server with PHP support on any operating system, including MacOSX, Linux and Windows. On Linux, you may find rpmfind and PBone helpful for locating RPMs. You may also want to visit apt-get to find packages for Debian.
Create a file named hello.php and put it
in your web server's root directory (DOCUMENT_ROOT)
with the following content:
This program is extremely simple and you really did not need to use PHP to create a page like this. All it does is display: Hello World using the PHP echo() statement. Note that the file does not need to be executable or special in any way. The server finds out that this file needs to be interpreted by PHP because you used the ".php" extension, which the server is configured to pass on to PHP. Think of this as a normal HTML file which happens to have a set of special tags available to you that do a lot of interesting things.
If you tried this example and it did not output anything, it prompted for download, or you see the whole file as text, chances are that the server you are on does not have PHP enabled, or is not configured properly. Ask your administrator to enable it for you using the Installation chapter of the manual. If you are developing locally, also read the installation chapter to make sure everything is configured properly. Make sure that you access the file via http with the server providing you the output. If you just call up the file from your file system, then it will not be parsed by PHP. If the problems persist anyway, do not hesitate to use one of the many PHP support options.
The point of the example is to show the special PHP tag format. In this example we used <?php to indicate the start of a PHP tag. Then we put the PHP statement and left PHP mode by adding the closing tag, ?>. You may jump in and out of PHP mode in an HTML file like this anywhere you want. For more details, read the manual section on the basic PHP syntax.
A Note on Line Feeds: Line feeds have little meaning in HTML, however it is still a good idea to make your HTML look nice and clean by putting line feeds in. A linefeed that follows immediately after a closing ?> will be removed by PHP. This can be extremely useful when you are putting in many blocks of PHP or include files containing PHP that aren't supposed to output anything. At the same time it can be a bit confusing. You can put a space after the closing ?> to force a space and a line feed to be output, or you can put an explicit line feed in the last echo/print from within your PHP block.
A Note on Text Editors: There are many text editors and Integrated Development Environments (IDEs) that you can use to create, edit and manage PHP files. A partial list of these tools is maintained at PHP Editors List. If you wish to recommend an editor, please visit the above page and ask the page maintainer to add the editor to the list. Having an editor with syntax highlighting can be helpful.
A Note on Word Processors: Word processors such as StarOffice Writer, Microsoft Word and Abiword are not optimal for editing PHP files. If you wish to use one for this test script, you must ensure that you save the file as plain text or PHP will not be able to read and execute the script.
A Note on Windows Notepad: If you are writing your PHP scripts using Windows Notepad, you will need to ensure that your files are saved with the .php extension. (Notepad adds a .txt extension to files automatically unless you take one of the following steps to prevent it.) When you save the file and are prompted to provide a name for the file, place the filename in quotes (i.e. "hello.php"). Alternatively, you can click on the 'Text Documents' drop-down menu in the 'Save' dialog box and change the setting to "All Files". You can then enter your filename without quotes.
Now that you have successfully created a working PHP script, it is time to create the most famous PHP script! Make a call to the phpinfo() function and you will see a lot of useful information about your system and setup such as available predefined variables, loaded PHP modules, and configuration settings. Take some time and review this important information.
Let us do something more useful now. We are going to check
what sort of browser the visitor is using.
For that, we check the user agent string the browser
sends as part of the HTTP request. This information is stored in a variable. Variables always start
with a dollar-sign in PHP. The variable we are interested in right now
is $_SERVER['HTTP_USER_AGENT'].
Note: $_SERVER is a special reserved PHP variable that contains all web server information. It is known as a superglobal. See the related manual page on superglobals for more information. These special variables were introduced in PHP 4.1.0. Before this time, we used the older
$HTTP_*_VARSarrays instead, such as$HTTP_SERVER_VARS. Although deprecated, these older variables still exist. (See also the note on old code.)
To display this variable, you can simply do:
There are many types of variables available in PHP. In the above example we printed an Array element. Arrays can be very useful.
$_SERVER is just one variable that PHP automatically
makes available to you. A list can be seen in the
Reserved Variables section
of the manual or you can get a complete list of them by looking at
the output of the phpinfo() function used in the
example in the previous section.
You can put multiple PHP statements inside a PHP tag and create little blocks of code that do more than just a single echo. For example, if you want to check for Internet Explorer you can do this:
Example 2-4. Example using control structures and functions
A sample output of this script may be:
|
Here we introduce a couple of new concepts. We have an if statement. If you are familiar with the basic syntax used by the C language, this should look logical to you. Otherwise, you should probably pick up an introductory PHP book and read the first couple of chapters, or read the Language Reference part of the manual.
The second concept we introduced was the strpos()
function call. strpos() is a function built into
PHP which searches a string for another string. In this case we are
looking for 'MSIE' (so-called needle) inside
$_SERVER['HTTP_USER_AGENT'] (so-called haystack). If
the needle is found inside the haystack, the function returns the position
of the needle relative to the start of the haystack. Otherwise, it
returns FALSE. If it does not return FALSE, the if expression evaluates to TRUE
and the code within its {braces} is executed. Otherwise, the code is not
run. Feel free to create similar examples,
with if,
else, and other
functions such as strtoupper() and
strlen(). Each related manual page contains examples
too. If you are unsure how to use functions, you will want to read both
the manual page on how to read a
function definition and the section about
PHP functions.
We can take this a step further and show how you can jump in and out of PHP mode even in the middle of a PHP block:
Example 2-5. Mixing both HTML and PHP modes
A sample output of this script may be:
|
Instead of using a PHP echo statement to output something, we jumped out of PHP mode and just sent straight HTML. The important and powerful point to note here is that the logical flow of the script remains intact. Only one of the HTML blocks will end up getting sent to the viewer depending on the result of strpos(). In other words, it depends on whether the string MSIE was found or not.
One of the most powerful features of PHP is the way it handles HTML forms. The basic concept that is important to understand is that any form element will automatically be available to your PHP scripts. Please read the manual section on Variables from outside of PHP for more information and examples on using forms with PHP. Here is an example HTML form:
There is nothing special about this form. It is a straight HTML form with no special tags of any kind. When the user fills in this form and hits the submit button, the action.php page is called. In this file you would write something like this:
Apart from the htmlspecialchars() and
(int) parts, it should be obvious what this does.
htmlspecialchars() makes sure any characters that are
special in html are properly encoded so people can't inject HTML tags
or Javascript into your page. For the age field, since we know it is a
number, we can just convert
it to an integer which will automatically get rid of any
stray characters. You can also have PHP do this for you automatically by
using the filter extension.
The $_POST['name'] and $_POST['age']
variables are automatically set for you by PHP. Earlier we
used the $_SERVER superglobal; above we just
introduced the $_POST
superglobal which contains all POST data. Notice how the
method of our form is POST. If we used the
method GET then our form information would live in
the $_GET superglobal instead.
You may also use the $_REQUEST
superglobal, if you do not care about the source of your request data. It
contains the merged information of GET, POST and COOKIE data. Also see the
import_request_variables() function.
You can also deal with XForms input in PHP, although you will find yourself comfortable with the well supported HTML forms for quite some time. While working with XForms is not for beginners, you might be interested in them. We also have a short introduction to handling data received from XForms in our features section.
Now that PHP has grown to be a popular scripting language, there are a lot of public repositories and libraries containing code you can reuse. The PHP developers have largely tried to preserve backwards compatibility, so a script written for an older version will run (ideally) without changes in a newer version of PHP. In practice, some changes will usually be needed.
Two of the most important recent changes that affect old code are:
The deprecation of the old $HTTP_*_VARS arrays
(which need to be indicated as global when used inside a function or
method). The following
superglobal arrays
were introduced in PHP 4.1.0.
They are: $_GET, $_POST,
$_COOKIE, $_SERVER,
$_FILES, $_ENV,
$_REQUEST, and $_SESSION. The
older $HTTP_*_VARS arrays, such as
$HTTP_POST_VARS, still exist as they have since PHP 3.
As of PHP 5.0.0, the long PHP
predefined variable
arrays may be disabled with the
register_long_arrays
directive.
External variables are no longer registered in the global scope by
default. In other words, as of PHP
4.2.0 the PHP directive
register_globals is
off by default in php.ini. The preferred
method of accessing these values is via the superglobal arrays mentioned
above. Older scripts, books, and tutorials may rely on this
directive being on. If it were on, for example, one could use
$id from the URL
http://www.example.com/foo.php?id=42. Whether on
or off, $_GET['id'] is available.
With your new knowledge you should be able to understand most of the manual and also the various example scripts available in the example archives. You can also find other examples on the php.net websites in the links section: http://www.php.net/links.php.
To view various slide presentations that show more of what PHP can do, see the PHP Conference Material Sites: http://conf.php.net/ and http://talks.php.net/
Before starting the installation, first you need to know what do you want to use PHP for. There are three main fields you can use PHP, as described in the What can PHP do? section:
Websites and web applications (server-side scripting)
Command line scripting
Desktop (GUI) applications
For the first and most common form, you need three things: PHP itself, a web server and a web browser. You probably already have a web browser, and depending on your operating system setup, you may also have a web server (e.g. Apache on Linux and MacOS X; IIS on Windows). You may also rent webspace at a company. This way, you don't need to set up anything on your own, only write your PHP scripts, upload it to the server you rent, and see the results in your browser.
In case of setting up the server and PHP on your own, you have two choices for the method of connecting PHP to the server. For many servers PHP has a direct module interface (also called SAPI). These servers include Apache, Microsoft Internet Information Server, Netscape and iPlanet servers. Many other servers have support for ISAPI, the Microsoft module interface (OmniHTTPd for example). If PHP has no module support for your web server, you can always use it as a CGI or FastCGI processor. This means you set up your server to use the CGI executable of PHP to process all PHP file requests on the server.
If you are also interested to use PHP for command line scripting (e.g. write scripts autogenerating some images for you offline, or processing text files depending on some arguments you pass to them), you always need the command line executable. For more information, read the section about writing command line PHP applications. In this case, you need no server and no browser.
With PHP you can also write desktop GUI applications using the PHP-GTK extension. This is a completely different approach than writing web pages, as you do not output any HTML, but manage Windows and objects within them. For more information about PHP-GTK, please visit the site dedicated to this extension. PHP-GTK is not included in the official PHP distribution.
From now on, this section deals with setting up PHP for web servers on Unix and Windows with server module interfaces and CGI executables. You will also find information on the command line executable in the following sections.
PHP source code and binary distributions for Windows can be found at http://www.php.net/downloads.php. We recommend you to choose a mirror nearest to you for downloading the distributions.
This section will guide you through the general configuration and installation of PHP on Unix systems. Be sure to investigate any sections specific to your platform or web server before you begin the process.
As our manual outlines in the General Installation Considerations section, we are mainly dealing with web centric setups of PHP in this section, although we will cover setting up PHP for command line usage as well.
There are several ways to install PHP for the Unix platform, either with a compile and configure process, or through various pre-packaged methods. This documentation is mainly focused around the process of compiling and configuring PHP. Many Unix like systems have some sort of package installation system. This can assist in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your web server. If you are unfamiliar with building and compiling your own software, it is worth checking to see whether somebody has already built a packaged version of PHP with the features you need.
Prerequisite knowledge and software for compiling:
Basic Unix skills (being able to operate "make" and a C compiler)
An ANSI C compiler
flex: Version 2.5.4
bison: Version 1.28 (preferred), 1.35, or 1.75
A web server
Any module specific components (such as gd, pdf libs, etc.)
The initial PHP setup and configuration process is controlled by the use of the command line options of the configure script. You could get a list of all available options along with short explanations running ./configure --help. Our manual documents the different options separately. You will find the core options in the appendix, while the different extension specific options are descibed on the reference pages.
When PHP is configured, you are ready to build the module and/or executables. The command make should take care of this. If it fails and you can't figure out why, see the Problems section.
This section contains notes and hints specific to Apache installs of PHP on Unix platforms. We also have instructions and notes for Apache 2 on a separate page.
You can select arguments to add to the configure on line 10 below from the list of core configure options and from extension specific options described at the respective places in the manual. The version numbers have been omitted here, to ensure the instructions are not incorrect. You will need to replace the 'xxx' here with the correct values from your files.
Example 4-1. Installation Instructions (Apache Shared Module Version) for PHP
|
Alternatively, to install PHP as a static object:
Example 4-2. Installation Instructions (Static Module Installation for Apache) for PHP
|
Note: Replace php-5 by php-4 and php5 by php4 in PHP 4.
Depending on your Apache install and Unix variant, there are many possible ways to stop and restart the server. Below are some typical lines used in restarting the server, for different apache/unix installations. You should replace /path/to/ with the path to these applications on your systems.
Example 4-3. Example commands for restarting Apache
|
The locations of the apachectl and http(s)dctl binaries often vary. If your system has locate or whereis or which commands, these can assist you in finding your server control programs.
Different examples of compiling PHP for apache are as follows:
This will create a libphp5.so (or libphp4.so in PHP 4) shared library that is loaded into Apache using a LoadModule line in Apache's httpd.conf file. The PostgreSQL support is embedded into this library.
This will create a libphp4.so shared library for Apache, but it will also create a pgsql.so shared library that is loaded into PHP either by using the extension directive in php.ini file or by loading it explicitly in a script using the dl() function.
This will create a libmodphp5.a library, a mod_php5.c and some accompanying files and copy this into the src/modules/php5 directory in the Apache source tree. Then you compile Apache using --activate-module=src/modules/php5/libphp5.a and the Apache build system will create libphp5.a and link it statically into the httpd binary (replace php5 by php4 in PHP 4). The PostgreSQL support is included directly into this httpd binary, so the final result here is a single httpd binary that includes all of Apache and all of PHP.
Same as before, except instead of including PostgreSQL support directly into the final httpd you will get a pgsql.so shared library that you can load into PHP from either the php.ini file or directly using dl().
When choosing to build PHP in different ways, you should consider the advantages and drawbacks of each method. Building as a shared object will mean that you can compile apache separately, and don't have to recompile everything as you add to, or change, PHP. Building PHP into apache (static method) means that PHP will load and run faster. For more information, see the Apache web page on DSO support.
Note: Apache's default httpd.conf currently ships with a section that looks like this:
Unless you change that to "Group nogroup" or something like that ("Group daemon" is also very common) PHP will not be able to open files.
Note: Make sure you specify the installed version of apxs when using
--with-apxs=/path/to/apxs. You must NOT use the apxs version that is in the apache sources but the one that is actually installed on your system.
This section contains notes and hints specific to Apache 2.0 installs of PHP on Unix systems.
| Warning |
We do not recommend using a threaded MPM in production with Apache2. Use the prefork MPM instead, or use Apache1. For information on why, read the related FAQ entry on using Apache2 with a threaded MPM |
You are highly encouraged to take a look at the Apache Documentation to get a basic understanding of the Apache 2.0 Server.
PHP and Apache 2.0.x compatibility notes: The following versions of PHP are known to work with the most recent version of Apache 2.0.x:
These versions of PHP are compatible to Apache 2.0.40 and later.
- PHP 4.3.0 or later available at http://www.php.net/downloads.php.
- the latest stable development version. Get the source code http://snaps.php.net/php5-latest.tar.gz or download binaries for Windows http://snaps.php.net/win32/php5-win32-latest.zip.
- a prerelease version downloadable from http://qa.php.net/.
- you have always the option to obtain PHP through anonymous CVS.
Apache 2.0 SAPI-support started with PHP 4.2.0. PHP 4.2.3 works with Apache 2.0.39, don't use any other version of Apache with PHP 4.2.3. However, the recommended setup is to use PHP 4.3.0 or later with the most recent version of Apache2.
All mentioned versions of PHP will work still with Apache 1.3.x.
Download the most recent version of Apache 2.0 and a fitting PHP version from the above mentioned places. This quick guide covers only the basics to get started with Apache 2.0 and PHP. For more information read the Apache Documentation. The version numbers have been omitted here, to ensure the instructions are not incorrect. You will need to replace the 'NN' here with the correct values from your files.
Example 4-4. Installation Instructions (Apache 2 Shared Module Version)
|
Following the steps above you will have a running Apache 2.0 with
support for PHP as SAPI module.
Of course there are many more configuration options available for both,
Apache and PHP. For more information use
./configure --help in the corresponding source
tree. In case you wish to build a multithreaded version of Apache 2.0
you must overwrite the standard MPM-Module prefork
either with worker or perchild.
To do so append to your configure line in step 6 above either the option
--with-mpm=worker or
--with-mpm=perchild. Take care about
the consequences and understand what you are doing. For more information
read the Apache documentation about the
MPM-Modules.
Note: If you want to use content negotiation, read the Apache MultiViews FAQ.
Note: To build a multithreaded version of Apache your system must support threads. This also implies to build PHP with experimental Zend Thread Safety (ZTS). Therefore not all extensions might be available. The recommended setup is to build Apache with the standard prefork MPM-Module.
PHP 4 can be built as a Pike module for the Caudium webserver. Note that this is not supported with PHP 3. Follow the simple instructions below to install PHP 4 for Caudium.
Example 4-5. Caudium Installation Instructions
|
You can of course compile your Caudium module with support for the various extensions available in PHP 4. See the reference pages for extension specific configure options.
Note: When compiling PHP 4 with MySQL support you must make sure that the normal MySQL client code is used. Otherwise there might be conflicts if your Pike already has MySQL support. You do this by specifying a MySQL install directory the
--with-mysqloption.
To build PHP as an fhttpd module, answer "yes" to "Build as an fhttpd module?" (the --with-fhttpd=DIR option to configure) and specify the fhttpd source base directory. The default directory is /usr/local/src/fhttpd. If you are running fhttpd, building PHP as a module will give better performance, more control and remote execution capability.
Note: Support for fhttpd is no longer available as of PHP 4.3.0.
This section contains notes and hints specific to Sun Java System Web Server, Sun ONE Web Server, iPlanet and Netscape server installs of PHP on Sun Solaris.
From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to generate custom directory listings and error pages. Additional functions for Apache compatibility are also available. For support in current web servers read the note about subrequests.
You can find more information about setting up PHP for the Netscape Enterprise Server (NES) here: http://benoit.noss.free.fr/php/install-php4.html
To build PHP with Sun JSWS/Sun ONE WS/iPlanet/Netscape web servers, enter the proper install directory for the --with-nsapi=[DIR] option. The default directory is usually /opt/netscape/suitespot/. Please also read /php-xxx-version/sapi/nsapi/nsapi-readme.txt.
Install the following packages from http://www.sunfreeware.com/ or another download site:
| autoconf-2.13 |
| automake-1.4 |
| bison-1_25-sol26-sparc-local |
| flex-2_5_4a-sol26-sparc-local |
| gcc-2_95_2-sol26-sparc-local |
| gzip-1.2.4-sol26-sparc-local |
| m4-1_4-sol26-sparc-local |
| make-3_76_1-sol26-sparc-local |
| mysql-3.23.24-beta (if you want mysql support) |
| perl-5_005_03-sol26-sparc-local |
| tar-1.13 (GNU tar) |
Make sure your path includes the proper directories PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin and make it available to your system export PATH.
gunzip php-x.x.x.tar.gz (if you have a .gz dist, otherwise go to 4).
tar xvf php-x.x.x.tar
Change to your extracted PHP directory: cd ../php-x.x.x
For the following step, make sure /opt/netscape/suitespot/ is where your netscape server is installed. Otherwise, change to the correct path and run:
./configure --with-mysql=/usr/local/mysql \ --with-nsapi=/opt/netscape/suitespot/ \ --enable-libgcc |
Run make followed by make install.
After performing the base install and reading the appropriate readme file, you may need to perform some additional configuration steps.
Configuration Instructions for Sun/iPlanet/Netscape.
Firstly you may need to add some paths to the LD_LIBRARY_PATH
environment for the server to find all the shared libs. This can best done
in the start script for your web server. The start script is often located
in: /path/to/server/https-servername/start.
You may also need to edit the configuration files that are
located in: /path/to/server/https-servername/config/.
Add the following line to mime.types (you can do that by the administration server):
type=magnus-internal/x-httpd-php exts=php |
Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) and add the following, shlib will vary depending on your system, it will be something like /opt/netscape/suitespot/bin/libphp4.so. You should place the following lines after mime types init.
Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/opt/netscape/suitespot/bin/libphp4.so" Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php_ini="/path/to/php.ini"] |
Configure the default object in obj.conf (for virtual server classes [version 6.0+] in their vserver.obj.conf):
<Object name="default"> . . . .#NOTE this next line should happen after all 'ObjectType' and before all 'AddLog' lines Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...] . . </Object> |
This is only needed if you want to configure a directory that only consists of PHP scripts (same like a cgi-bin directory):
<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute [inikey=value inikey=value ...] </Object> |
Setup of authentication: PHP authentication cannot be used with any other authentication. ALL AUTHENTICATION IS PASSED TO YOUR PHP SCRIPT. To configure PHP Authentication for the entire server, add the following line to your default object:
<Object name="default"> AuthTrans fn=php4_auth_trans . . . </Object> |
To use PHP Authentication on a single directory, add the following:
<Object ppath="d:\path\to\authenticated\dir\*"> AuthTrans fn=php4_auth_trans </Object> |
Note: The stacksize that PHP uses depends on the configuration of the web server. If you get crashes with very large PHP scripts, it is recommended to raise it with the Admin Server (in the section "MAGNUS EDITOR").
Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE WS/iPlanet/Netscape is a multithreaded web server. Because of that all requests are running in the same process space (the space of the web server itself) and this space has only one environment. If you want to get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the correct way to try this in the old PHP 3.x way with getenv() or a similar way (register globals to environment, $_ENV). You would only get the environment of the running web server without any valid CGI variables!
Note: Why are there (invalid) CGI variables in the environment?
Answer: This is because you started the web server process from the admin server which runs the startup script of the web server, you wanted to start, as a CGI script (a CGI script inside of the admin server!). This is why the environment of the started web server has some CGI environment variables in it. You can test this by starting the web server not from the administration server. Use the command line as root user and start it manually - you will see there are no CGI-like environment variables.
Simply change your scripts to get CGI variables in the correct way for PHP 4.x by using the superglobal $_SERVER. If you have older scripts which use $HTTP_HOST, etc., you should turn on register_globals in php.ini and change the variable order too (important: remove "E" from it, because you do not need the environment here):
variables_order = "GPCS" register_globals = On |
You can use PHP to generate the error pages for "404 Not Found" or similar. Add the following line to the object in obj.conf for every error page you want to overwrite:
Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...] |
Another possibility is to generate self-made directory listings. Just create a PHP script which displays a directory listing and replace the corresponding default Service line for type="magnus-internal/directory" in obj.conf with the following:
Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...] |
The NSAPI module now supports the nsapi_virtual() function (alias: virtual()) to make subrequests on the web server and insert the result in the web page. This function uses some undocumented features from the NSAPI library. On Unix the module automatically looks for the needed functions and uses them if available. If not, nsapi_virtual() is disabled.
Note: But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!!
The default is to build PHP as a CGI program. This creates a command line interpreter, which can be used for CGI processing, or for non-web-related PHP scripting. If you are running a web server PHP has module support for, you should generally go for that solution for performance reasons. However, the CGI version enables users to run different PHP-enabled pages under different user-ids.
| Warning |
By using the CGI setup, your server is open to several possible attacks. Please read our CGI security section to learn how to defend yourself from those attacks. |
As of PHP 4.3.0, some important additions have happened to PHP. A new SAPI named CLI also exists and it has the same name as the CGI binary. What is installed at {PREFIX}/bin/php depends on your configure line and this is described in detail in the manual section named Using PHP from the command line. For further details please read that section of the manual.
If you have built PHP as a CGI program, you may test your build by typing make test. It is always a good idea to test your build. This way you may catch a problem with PHP on your platform early instead of having to struggle with it later.
If you have built PHP 3 as a CGI program, you may benchmark your build by typing make bench. Note that if safe mode is on by default, the benchmark may not be able to finish if it takes longer then the 30 seconds allowed. This is because the set_time_limit() can not be used in safe mode. Use the max_execution_time configuration setting to control this time for your own scripts. make bench ignores the configuration file.
Note: make bench is only available for PHP 3.
Some server supplied
environment variables are not defined in the
current CGI/1.1 specification.
Only the following variables are defined there: AUTH_TYPE,
CONTENT_LENGTH, CONTENT_TYPE,
GATEWAY_INTERFACE, PATH_INFO,
PATH_TRANSLATED, QUERY_STRING,
REMOTE_ADDR, REMOTE_HOST,
REMOTE_IDENT, REMOTE_USER,
REQUEST_METHOD, SCRIPT_NAME,
SERVER_NAME, SERVER_PORT,
SERVER_PROTOCOL, and SERVER_SOFTWARE.
Everything else should be treated as 'vendor extensions'.
This section contains notes and hints specific to installing PHP on HP-UX systems.
There are two main options for installing PHP on HP-UX systems. Either compile it, or install a pre-compiled binary.
Official pre-compiled packages are located here: http://software.hp.com/
Until this manual section is rewritten, the documentation about compiling PHP (and related extensions) on HP-UX systems has been removed. For now, consider reading the following external resource: Building Apache and PHP on HP-UX 11.11
This section contains notes and hints specific to installing PHP on OpenBSD 3.6.
Using binary packages to install PHP on OpenBSD is the recommended and simplest method. The core package has been separated from the various modules, and each can be installed and removed independently from the others. The files you need can be found on your OpenBSD CD or on the FTP site.
The main package you need to install is php4-core-4.3.8.tgz, which contains the basic engine (plus gettext and iconv). Next, take a look at the module packages, such as php4-mysql-4.3.8.tgz or php4-imap-4.3.8.tgz. You need to use the phpxs command to activate and deactivate these modules in your php.ini.
Example 4-6. OpenBSD Package Install Example
|
Read the packages(7) manual page for more information about binary packages on OpenBSD.
You can also compile up PHP from source using the ports tree. However, this is only recommended for users familiar with OpenBSD. The PHP 4 port is split into two sub-directories: core and extensions. The extensions directory generates sub-packages for all of the supported PHP modules. If you find you do not want to create some of these modules, use the no_* FLAVOR. For example, to skip building the imap module, set the FLAVOR to no_imap.
The default install of Apache runs inside a chroot(2) jail, which will restrict PHP scripts to accessing files under /var/www. You will therefore need to create a /var/www/tmp directory for PHP session files to be stored, or use an alternative session backend. In addition, database sockets need to be placed inside the jail or listen on the localhost interface. If you use network functions, some files from /etc such as /etc/resolv.conf and /etc/services will need to be moved into /var/www/etc. The OpenBSD PEAR package automatically installs into the correct chroot directories, so no special modification is needed there. More information on the OpenBSD Apache is available in the OpenBSD FAQ.
The OpenBSD 3.6 package for the gd extension requires XFree86 to be installed. If you do not wish to use some of the font features that require X11, install the php4-gd-4.3.8-no_x11.tgz package instead.
Older releases of OpenBSD used the FLAVORS system to compile up a statically linked PHP. Since it is hard to generate binary packages using this method, it is now deprecated. You can still use the old stable ports trees if you wish, but they are unsupported by the OpenBSD team. If you have any comments about this, the current maintainer for the port is Anil Madhavapeddy (avsm at openbsd dot org).
This section contains notes and hints specific to installing PHP on Solaris systems.
Solaris installs often lack C compilers and their related tools. Read this FAQ for information on why using GNU versions for some of these tools is necessary. The required software is as follows:
gcc (recommended, other C compilers may work)
make
flex
bison
m4
autoconf
automake
perl
gzip
tar
GNU sed
You can simplify the Solaris install process by using pkgadd to install most of your needed components.
This section contains notes and hints specific to installing PHP on Debian GNU/Linux.
While you can just download the PHP source and compile it yourself, using Debian's packaging system is the simplest and cleanest method of installing PHP. If you are not familiar with building software on Linux, this is the way to go.
The first decision you need to make is whether you want to install Apache 1.3.x or Apache 2.x. The corresponding PHP packages are respectively named libapache-mod-php* and libapache2-mod-php*. The steps given below will use Apache 1.3.x. Please note that, as of this writing, there is no official Debian packages of PHP 5. Then the steps given below will install PHP 4.
PHP is available in Debian as CGI or CLI flavour too, named respectively php4-cgi and php4-cli. If you need them, you'll just have to reproduce the following steps with the good package names. Another special package you'd want to install is php4-pear. It contains a minimal PEAR installation and the pear commandline utility.
If you need more recent packages of PHP than the Debian's stable ones or if some PHP modules lacks the Debian official repository, perhaps you should take a look at http://www.apt-get.org/. One of the results found should be Dotdeb. This unofficial repository is maintained by Guillaume Plessis and contains Debian packages of the most recent versions of PHP 4 and PHP 5. To use it, just add the to following two lines to your /etc/apt/sources.lists and run apt-get update :
The last thing to consider is whether your list of packages is up to date. If you have not updated it recently, you need to run apt-get update before anything else. This way, you will be using the most recent stable version of the Apache and PHP packages.
Now that everything is in place, you can use the following example to install Apache and PHP:
APT will automatically install the PHP 4 module for Apache 1.3, and all its dependencies and then activate it. If you're not asked to restart Apache during the install process, you'll have to do it manually :
In the last section, PHP was installed with only core modules. This may not be what you want and you will soon discover that you need more activated modules, like MySQL, cURL, GD, etc.
When you compile PHP from source yourself, you need to activate modules via the configure command. With APT, you just have to install additional packages. They're all named 'php4-*' (or 'php5-*' if you installed PHP 5 from a third party repository).
As you can see from the last output, there's a lot of PHP modules that you can install (excluding the php4-cgi, php4-cli or php4-pear special packages). Look at them closely and choose what you need. If you choose a module and you do not have the proper libraries, APT will automatically install all the dependencies for you.
If you choose to add the MySQL, cURL and GD support to PHP the command will look something like this:
APT will automatically add the appropriate lines to your different php.ini (/etc/php4/apache/php.ini, /etc/php4/cgi/php.ini, etc).
You'll only have to stop/start Apache as previously to activate the modules.
If you see the PHP source instead of the result the script should produce, APT has probably not included /etc/apache/conf.d/php4 in your Apache 1.3 configuration. Please ensure that the following line is present in your /etc/apache/httpd.conf file then stop/start Apache:
If you installed an additional module and if its functions are not available in your scripts, please ensure that the appropriate line is present in your php.ini, as seen before. APT may fail during the installation of the additional module, due to a confusing debconf configuration.
This section contains notes and hints specific to installing PHP on Mac OS X. There are two slightly different versions of Mac OS X, Client and Server, our manual deals with installing PHP on both systems. Note that PHP is not available for MacOS 9 and earlier versions.
There are a few pre-packaged and pre-compiled versions of PHP for Mac OS X. This can help in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your web server yourself. If you are unfamiliar with building and compiling your own software, it's worth checking whether somebody has already built a packaged version of PHP with the features you need.
The following resources offer easy to install packages and precompiled binaries for PHP on Mac OS:
PHP has come standard with Macs since OS X version 10.0.0. Enabling PHP with the default web server requires uncommenting a few lines in the Apache configuration file httpd.conf whereas the CGI and/or CLI are enabled by default (easily accessible via the Terminal program).
Enabling PHP using the instructions below is meant for quickly setting up a local development environment. It's highly recommended to always upgrade PHP to the newest version. Like most live software, newer versions are created to fix bugs and add features and PHP being is no different. See the appropriate MAC OS X installation documentation for further details. The following instructions are geared towards a beginner with details provided for getting a default setup to work. All users are encouraged to compile, or install a new packaged version.
The standard installation type is using mod_php, and enabling the bundled mod_php on Mac OS X for the Apache web server (the default web server, that is accessible via System Preferences) involves the following steps:
Locate and open the Apache configuration file. By default, the location is as follows: /etc/httpd/httpd.conf
Using Finder or Spotlight to find this file may prove difficult as by default it's private and owned by the root user.
Note: One way to open this is by using a Unix based text editor in the Terminal, for example nano, and because the file is owned by root we'll use the sudo command to open it (as root) so for example type the following into the Terminal Application (after, it will prompt for a password): sudo nano /etc/httpd/httpd.conf
Noteworthy nano commands: ^w (search), ^o (save), and ^x (exit) where ^ represents the Ctrl key.
With a text editor, uncomment the lines (by removing the #) that look similar to the following (these two lines are often not together, locate them both in the file):
# LoadModule php4_module libexec/httpd/libphp4.so # AddModule mod_php4.c |
Be sure the desired extensions will parse as PHP (examples: .php .html and .inc)
Due to the following statement already existing in httpd.conf (as of Mac Panther), once PHP is enabled the .php files will automatically parse as PHP.
<IfModule mod_php4.c>
# If php is turned on, we respect .php and .phps files.
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps
# Since most users will want index.php to work we
# also automatically enable index.php
<IfModule mod_dir.c>
DirectoryIndex index.html index.php
</IfModule>
</IfModule> |
Be sure the DirectoryIndex loads the desired default index file
This is also set in httpd.conf. Typically index.php and index.html are used. By default index.php is enabled because it's also in the PHP check shown above. Adjust accordingly.
Set the php.ini location or use the default
A typical default location on Mac OS X is /usr/local/php/php.ini and a call to phpinfo() will reveal this information. If a php.ini is not used, PHP will use all default values. See also the related FAQ on finding php.ini.
Locate or set the DocumentRoot
This is the root directory for all the web files. Files in this directory are served from the web server so the PHP files will parse as PHP before outputting them to the browser. A typical default path is /Library/WebServer/Documents but this can be set to anything in httpd.conf. Alternatively, the default DocumentRoot for individual users is /Users/yourusername/Sites
Create a phpinfo() file
The phpinfo() function will display information about PHP. Consider creating a file in the DocumentRoot with the following PHP code:
<?php phpinfo(); ?> |
Restart Apache, and load the PHP file created above
To restart, either execute sudo apachectl graceful in the shell or stop/start the "Personal Web Server" option in the OS X System Preferences. By default, loading local files in the browser will have an URL like so: http://localhost/info.php Or using the DocumentRoot in the user directory is another option and would end up looking like: http://localhost/~yourusername/info.php
The CLI (or CGI in older versions) is appropriately named php and likely exists as /usr/bin/php. Open up the terminal, read the command line section of the PHP manual, and execute php -v to check the PHP version of this PHP binary. A call to phpinfo() will also reveal this information.
Get the latest distributions of Apache and PHP.
Untar them, and run the configure program on Apache like so.
./configure --exec-prefix=/usr \ --localstatedir=/var \ --mandir=/usr/share/man \ --libexecdir=/System/Library/Apache/Modules \ --iconsdir=/System/Library/Apache/Icons \ --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ --enable-shared=max \ --enable-module=most \ --target=apache |
If you want the compiler to do some optimization, you may also want to add this line:
setenv OPTIM=-O2 |
Next, go to the PHP 4 source directory and configure it.
./configure --prefix=/usr \
--sysconfdir=/etc \
--localstatedir=/var \
--mandir=/usr/share/man \
--with-xml \
--with-apache=/src/apache_1.3.12 |
--with-apache string, put
in the path to your apache source directory, for example
/src/apache_1.3.12.
Type make and make install. This will add a directory to your Apache source directory under src/modules/php4.
Now, reconfigure Apache to build in PHP 4.
./configure --exec-prefix=/usr \ --localstatedir=/var \ --mandir=/usr/share/man \ --libexecdir=/System/Library/Apache/Modules \ --iconsdir=/System/Library/Apache/Icons \ --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ --enable-shared=max \ --enable-module=most \ --target=apache \ --activate-module=src/modules/php4/libphp4.a |
Copy and rename the php.ini-dist file to your bin directory from your PHP 4 source directory: cp php.ini-dist /usr/local/bin/php.ini or (if your don't have a local directory) cp php.ini-dist /usr/bin/php.ini.
The following instructions will help you install a PHP module for the Apache web server included in MacOS X. This version includes support for the MySQL and PostgreSQL databases. These instructions are graciously provided by Marc Liyanage.
| Warning |
Be careful when you do this, you could screw up your Apache web server! |
Do this to install:
Open a terminal window.
Type wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz, wait for the download to finish.
Type gunzip libphp4.so.gz.
Type sudo apxs -i -a -n php4 libphp4.so
Now type sudo open -a TextEdit /etc/httpd/httpd.conf. TextEdit will open with the web server configuration file. Locate these two lines towards the end of the file: (Use the Find command)
#AddType application/x-httpd-php .php #AddType application/x-httpd-php-source .phps |
Finally, type sudo apachectl graceful to restart the web server.
PHP should now be up and running. You can test it by dropping a file into your Sites folder which is called test.php. Into that file, write this line: <?php phpinfo() ?>.
Now open up 127.0.0.1/~your_username/test.php in your web browser. You should see a status table with information about the PHP module.
This section applies to Windows 98/Me and Windows NT/2000/XP/2003. PHP will not work on 16 bit platforms such as Windows 3.1 and sometimes we refer to the supported Windows platforms as Win32. Windows 95 is no longer supported as of PHP 4.3.0.
There are two main ways to install PHP for Windows: either manually or by using the installer.
If you have Microsoft Visual Studio, you can also build PHP from the original source code.
Once you have PHP installed on your Windows system, you may also want to load various extensions for added functionality.
| Warning |
There are several all-in-one installers over the Internet, but none of those are endorsed by PHP.net, as we believe that the manual installation is the best choice to have your system secure and optimised. |
The Windows PHP installer for later versions of PHP is built using MSI technology using the Wix Toolkit (http://wix.sourceforge.net/). It will install and configure PHP and all the built-in and PECL extensions, as well as configure many of the popular web servers such as IIS, Apache, and Xitami.
First, install your selected HTTP (web) server on your system, and make sure that it works. Then proceed with one of the following install types.
Run the MSI installer and follow the instructions provided by the installation wizard. You will be prompted to select the Web Server you wish to configure first, along with any configuration details needed.
You will then be prompted to select which features and extensions you wish to install and enable. By selecting "Will be installed on local hard drive" in the drop-down menu for each item you can trigger whether to install the feature or not. By selecting "Entire feature will be installed on local hard drive", you will be able to install all sub-features of the included feature ( for example by selecting this options for the feature "PDO" you will install all PDO Drivers ).
| Warning |
It is not recommended to install all extensions by default, since many other them require dependencies from outside PHP in order to function properly. Instead, use the Installation Repair Mode that can be triggered thru the 'Add/Remove Programs' control panel to enable or disable extensions and features after installation. |
The installer then sets up PHP to be used in Windows and the php.ini file, and configures certain web servers to use PHP. The installer will currently configure IIS (CGI mode only), Apache, Xitami, and Sambar Server; if you are using a different web server you'll need to configure it manually.
The installer also supports a silent mode, which is helpful for Systems Administrators to deploy PHP easily. To use silent mode:
msiexec.exe /i php-VERSION-win32-install.msi /q |
You can control the install directory by passing it as a parameter to the install. For example, to install to e:\php:
msiexec.exe /i php-VERSION-win32-install.msi /q INSTALLDIR=e:\php |
You can also specify what features to install. For example, to install the mysqli extension and the CGI executable:
msiexec.exe /i php-VERSION-win32-install.msi /q ADDLOCAL=cgi,ext_php_mysqli |
The current list of Features to install is as follows:
MainExecutable - php.exe executable ScriptExecutable - php-win.exe executable ext_php_* - the various extensions ( for example: ext_php_mysql for MySQL ) apache13 - Apache 1.3 module apache20 - Apache 2.0 module apache22 - Apache 2,2 module apacheCGI - Apache CGI executable iis4ISAPI - IIS ISAPI module iis4CGI - IIS CGI executable NSAPI - Sun/iPlanet/Netscape server module Xitami - Xitami CGI executable Sambar - Sambar Server ISAPI module CGI - php-cgi.exe executable PEAR - PEAR installer Manual - PHP Manual in CHM Format |
For more information on installing MSI installers from the command line, visit http://msdn.microsoft.com/library/en-us/msi/setup/command_line_options.asp
To upgrade, run the installer either graphically or from the command line as normal. The installer will read your current install options, remove your old installation, and reinstall PHP with the same options as before. It is recommended that you use this method of keeping PHP updated instead of manually replacing the files in the installation directory.
The Windows PHP installer is available from the downloads page at http://www.php.net/downloads.php. This installs the CGI version of PHP and for IIS, PWS, and Xitami, it configures the web server as well. The installer does not include any extra external PHP extensions (php_*.dll) as you'll only find those in the Windows Zip Package and PECL downloads.
Note: While the Windows installer is an easy way to make PHP work, it is restricted in many aspects as, for example, the automatic setup of extensions is not supported. Use of the installer isn't the preferred method for installing PHP.
First, install your selected HTTP (web) server on your system, and make sure that it works.
Run the executable installer and follow the instructions provided by the installation wizard. Two types of installation are supported - standard, which provides sensible defaults for all the settings it can, and advanced, which asks questions as it goes along.
The installation wizard gathers enough information to set up the php.ini file, and configure certain web servers to use PHP. One of the web servers the PHP installer does not configure for is Apache, so you'll need to configure it manually.
Once the installation has completed, the installer will inform you if you need to restart your system, restart the server, or just start using PHP.
| Warning |
Be aware, that this setup of PHP is not secure. If you would like to have a secure PHP setup, you'd better go on the manual way, and set every option carefully. This automatically working setup gives you an instantly working PHP installation, but it is not meant to be used on online servers. |
This install guide will help you manually install and configure PHP with a web server on Microsoft Windows. To get started you'll need to download the zip binary distribution from the downloads page at http://www.php.net/downloads.php.
Although there are many all-in-one installation kits, and we also distribute a PHP installer for Microsoft Windows, we recommend you take the time to setup PHP yourself as this will provide you with a better understanding of the system, and enables you to install PHP extensions easily when needed.
Upgrading from a previous PHP version: Previous editions of the manual suggest moving various ini and DLL files into your SYSTEM (i.e. C:\WINDOWS) folder and while this simplifies the installation procedure it makes upgrading difficult. We advise you remove all of these files (like php.ini and PHP related DLLs from the Windows SYSTEM folder) before moving on with a new PHP installation. Be sure to backup these files as you might break the entire system. The old php.ini might be useful in setting up the new PHP as well. And as you'll soon learn, the preferred method for installing PHP is to keep all PHP related files in one directory and have this directory available to your systems PATH.
MDAC requirements: If you use Microsoft Windows 98/NT4 download the latest version of the Microsoft Data Access Components (MDAC) for your platform. MDAC is available at http://msdn.microsoft.com/data/. This requirement exists because ODBC is built into the distributed Windows binaries.
The following steps should be completed on all installations before any server specific instructions are performed:
Extract the distribution file into a directory of your choice. If you are installing PHP 4, extract to C:\, as the zip file expands to a foldername like php-4.3.7-Win32. If you are installing PHP 5, extract to C:\php as the zip file doesn't expand as in PHP 4. You may choose a different location but do not have spaces in the path (like C:\Program Files\PHP) as some web servers will crash if you do.
The directory structure extracted from the zip is different for PHP versions 4 and 5 and look like as follows:
Example 6-1. PHP 4 package structure
|
Or:
Example 6-2. PHP 5 package structure
|
Notice the differences and similarities. Both PHP 4 and PHP 5 have a CGI executable, a CLI executable, and server modules, but they are located in different folders and/or have different names. While PHP 4 packages have the server modules in the sapi folder, PHP 5 distributions have no such directory and instead they're in the PHP folder root. The supporting DLLs for the PHP 5 extensions are also not in a seperate directory.
Note: In PHP 4, you should move all files located in the dll and sapi folders to the main folder (e.g. C:\php).
Here is a list of server modules shipped with PHP 4 and PHP 5:
sapi/php4activescript.dll (php5activescript.dll) - ActiveScript engine, allowing you to embed PHP in your Windows applications.
sapi/php4apache.dll (php5apache.dll) - Apache 1.3.x module.
sapi/php4apache2.dll (php5apache2.dll) - Apache 2.0.x module.
sapi/php5apache2_2.dll - Apache 2.2.x module.
sapi/php4isapi.dll (php5isapi.dll) - ISAPI Module for ISAPI compliant web servers like IIS 4.0/PWS 4.0 or newer.
sapi/php4nsapi.dll (php5nsapi.dll) - Sun/iPlanet/Netscape server module.
sapi/php4pi3web.dll (no equivalent in PHP 5) - Pi3Web server module.
Server modules provide significantly better performance and additional functionality compared to the CGI binary. The CLI version is designed to let you use PHP for command line scripting. More information about CLI is available in the chapter about using PHP from the command line.
| Warning |
The SAPI modules have been significantly improved as of the 4.1 release, however, in older systems you may encounter server errors or other server modules failing, such as ASP. |
The CGI and CLI binaries, and the web server modules all require the php4ts.dll (php5ts.dll) file to be available to them. You have to make sure that this file can be found by your PHP installation. The search order for this DLL is as follows:
The same directory from where php.exe is called, or in case you use a SAPI module, the web server's directory (e.g. C:\Program Files\Apache Group\Apache2\bin).
Any directory in your Windows PATH environment
variable.
To make php4ts.dll / php5ts.dll
available you have three options: copy the file to the Windows system
directory, copy the file to the web server's directory, or add your PHP
directory, C:\php to the
PATH. For better maintenance, we advise you to follow
the last option, add C:\php to the
PATH, because it will be simpler to upgrade PHP in the
future. Read more about how to add your PHP directory to
PATH in the corresponding FAQ entry (and
then don't forget to restart the computer - logoff isn't enough).
The next step is to set up a valid configuration file for PHP, php.ini. There are two ini files distributed in the zip file, php.ini-dist and php.ini-recommended. We advise you to use php.ini-recommended, because we optimized the default settings in this file for performance, and security. Read this well documented file carefully because it has changes from php.ini-dist that will drastically affect your setup. Some examples are display_errors being off and magic_quotes_gpc being off. In addition to reading these, study the ini settings and set every element manually yourself. If you would like to achieve the best security, then this is the way for you, although PHP works fine with these default ini files. Copy your chosen ini-file to a directory that PHP is able to find and rename it to php.ini. PHP searches for php.ini in the locations described in the Section called The configuration file in Chapter 9 section.
If you are running Apache 2, the simpler option is to use the PHPIniDir
directive (read the installation
on Apache 2 page), otherwise your best option is to set the
PHPRC environment variable. This process is explained
in the following FAQ entry.
Note: If you're using NTFS on Windows NT, 2000, XP or 2003, make sure that the user running the web server has read permissions to your php.ini (e.g. make it readable by Everyone).
The following steps are optional:
Edit your new php.ini file. If you plan to use OmniHTTPd, do not follow the next step. Set the doc_root to point to your web servers document_root. For example:
Choose the extensions you would like to load when PHP starts. See the section about Windows extensions, about how to set up one, and what is already built in. Note that on a new installation it is advisable to first get PHP working and tested without any extensions before enabling them in php.ini.
On PWS and IIS, you can set the browscap configuration setting to point to: c:\windows\system\inetsrv\browscap.ini on Windows 9x/Me, c:\winnt\system32\inetsrv\browscap.ini on NT/2000, and c:\windows\system32\inetsrv\browscap.ini on XP. For an up-to-date browscap.ini, read the following FAQ.
PHP is now setup on your system. The next step is to choose a web server, and enable it to run PHP. Choose a web server from the table of contents.
This section contains notes specific to the ActiveScript installation.
ActiveScript is a Windows only SAPI that enables you to use PHP script in any ActiveScript compliant host, like Windows Script Host, ASP/ASP.NET, Windows Script Components or Microsoft Scriptlet control.
As of PHP 5.0.1, ActiveScript has been moved to the PECL repository. The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
Note: You should read the manual installation steps first!
After installing PHP, you should download the ActiveScript DLL (php5activescript.dll) and place it in the main PHP folder (e.g. C:\php).
After having all the files needed, you must register the DLL on your system. To achieve this, open a Command Prompt window (located in the Start Menu). Then go to your PHP directory by typing something like cd C:\php. To register the DLL just type regsvr32 php5activescript.dll.
To test if ActiveScript is working, create a new file, named test.wsf (the extension is very important) and type:
<job id="test">
<script language="PHPScript">
$WScript->Echo("Hello World!");
</script>
</job> |
Note: In PHP 4, the engine was named 'ActivePHP', so if you are using PHP 4, you should replace 'PHPScript' with 'ActivePHP' in the above example.
Note: ActiveScript doesn't use the default php.ini file. Instead, it will look only in the same directory as the .exe that caused it to load. You should create php-activescript.ini and place it in that folder, if you wish to load extensions, etc.
This section contains notes and hints specific to IIS (Microsoft Internet Information Server).
| Warning |
By using the CGI setup, your server is open to several possible attacks. Please read our CGI security section to learn how to defend yourself from those attacks. |
First, read the Manual Installation Instructions. Do not skip this step as it provides crucial information for installing PHP on Windows.
CGI users must set the cgi.force_redirect PHP directive to 0 inside php.ini. Read the faq on cgi.force_redirect for important details. Also, CGI users may want to set the cgi.redirect_status_env directive. When using directives, be sure these directives aren't commented out inside php.ini.
The PHP 4 CGI is named php.exe while in PHP 5 it's php-cgi.exe. In PHP 5, php.exe is the CLI, and not the CGI.
Modify the Windows PATH environment variable to include the PHP directory. This way the PHP DLL files and PHP executables can all remain in the PHP directory without cluttering up the Windows system directory. For more details, see the FAQ on Setting the PATH.
The IIS user (usually IUSR_MACHINENAME) needs permission to read various files and directories, such as php.ini, docroot, and the session tmp directory.
Be sure the extension_dir and doc_root PHP directives are appropriately set in php.ini. These directives depend on the system that PHP is being installed on. In PHP 4, the extension_dir is extensions while with PHP 5 it's ext. So, an example PHP 5 extensions_dir value is "c:\php\ext" and an example IIS doc_root value is "c:\Inetpub\wwwroot".
PHP extension DLL files, such as php_mysql.dll and php_curl.dll, are found in the zip package of the PHP download (not the PHP installer). In PHP 5, many extensions are part of PECL and can be downloaded in the "Collection of PECL modules" package. Files such as php_zip.dll and php_ssh2.dll. Download PHP files here.
When defining the executable, the 'check that file exists' box may also be checked. For a small performance penalty, the IIS (or PWS) will check that the script file exists and sort out authentication before firing up PHP. This means that the web server will provide sensible 404 style error messages instead of CGI errors complaining that PHP did not output any data.
PHP may be installed as a CGI binary, or with the ISAPI module. In either case, you need to start the Microsoft Management Console (may appear as 'Internet Services Manager', either in your Windows NT 4.0 Option Pack branch or the Control Panel=>Administrative Tools under Windows 2000/XP). Then right click on your Web server node (this will most probably appear as 'Default Web Server'), and select 'Properties'.
If you want to use the CGI binary, do the following:
Under 'Home Directory', 'Virtual Directory', or 'Directory', do the following:
Change the Execute Permissions to 'Scripts only'
Click on the 'Configuration' button, and choose the Application Mappings tab. Click Add and set the Executable path to the appropriate CGI file. An example PHP 5 value is: C:\php\php-cgi.exe Supply .php as the extension. Leave 'Method exclusions' blank, and check the 'Script engine' checkbox. Now, click OK a few times.
Set up the appropriate security. (This is done in Internet Service Manager), and if your NT Server uses NTFS file system, add execute rights for I_USR_ to the directory that contains php.exe / php-cgi.exe.
To use the ISAPI module, do the following:
If you don't want to perform HTTP Authentication using PHP, you can (and should) skip this step. Under ISAPI Filters, add a new ISAPI filter. Use PHP as the filter name, and supply a path to the php4isapi.dll / php5isapi.dll.
Under 'Home Directory', 'Virtual Directory', or 'Directory', do the following:
Change the Execute Permissions to 'Scripts only'
Click on the 'Configuration' button, and choose the Application Mappings tab. Click Add and set the Executable path to the appropriate ISAPI DLL. An example PHP 5 value is: C:\php\php5isapi.dll Supply .php as the extension. Leave 'Method exclusions' blank, and check the 'Script engine' checkbox. Now, click OK a few times.
Stop IIS completely (NET STOP iisadmin)
Start IIS again (NET START w3svc)
With IIS 6 (2003 Server), open up the IIS Manager, go to Web Service Extensions, choose "Add a new Web service extension", enter in a name such as PHP, choose the Add button and for the value browse to either the ISAPI file (php4isapi.dll or php5isapi.dll) or CGI (php.exe or php-cgi.exe) then check "Set extension status to Allowed" and click OK.
In order to use index.php as a default content page, do the following: From within the Documents tab, choose Add. Type in index.php and click OK. Adjust the order by choosing Move Up or Move Down. This is similar to setting DirectoryIndex with Apache.
The steps above must be repeated for each extension that is to be associated with PHP scripts. .php is the most common although .php3 may be required for legacy applications.
If you experience 100% CPU usage after some time, turn off the IIS setting Cache ISAPI Application.
PWS 4 does not support ISAPI, only PHP CGI should be used.
Edit the enclosed pws-php4cgi.reg / pws-php5cgi.reg file (look into the SAPI folder for PHP 4, or in the main folder for PHP 5) to reflect the location of your php.exe / php-cgi.exe. Backslashes should be escaped, for example: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="C:\\php\\php.exe" (change to C:\\php\\php-cgi.exe if you are using PHP 5) Now merge this registery file into your system; you may do this by double-clicking it.
In the PWS Manager, right click on a given directory you want to add PHP support to, and select Properties. Check the 'Execute' checkbox, and confirm.
The recommended method for configuring these servers is to use the REG file included with the distribution (pws-php4cgi.reg in the SAPI folder for PHP 4, or pws-php5cgi.reg in the main folder for PHP 5). You may want to edit this file and make sure the extensions and PHP install directories match your configuration. Or you can follow the steps below to do it manually.
| Warning |
These steps involve working directly with the Windows registry. One error here can leave your system in an unstable state. We highly recommend that you back up your registry first. The PHP Development team will not be held responsible if you damage your registry. |
Run Regedit.
Navigate to: HKEY_LOCAL_MACHINE /System /CurrentControlSet /Services /W3Svc /Parameters /ScriptMap.
On the edit menu select: New->String Value.
Type in the extension you wish to use for your php scripts. For example .php
Double click on the new string value and enter the path to php.exe in the value data field. ex: C:\php\php.exe "%s" %s for PHP 4, or C:\php\php-cgi.exe "%s" %s for PHP 5.
Repeat these steps for each extension you wish to associate with PHP scripts.
The following steps do not affect the web server installation and only apply if you want your PHP scripts to be executed when they are run from the command line (ex. run C:\myscripts\test.php) or by double clicking on them in a directory viewer window. You may wish to skip these steps as you might prefer the PHP files to load into a text editor when you double click on them.
Navigate to: HKEY_CLASSES_ROOT
On the edit menu select: New->Key.
Name the key to the extension you setup in the previous section. ex: .php
Highlight the new key and in the right side pane, double click the "default value" and enter phpfile.
Repeat the last step for each extension you set up in the previous section.
Now create another New->Key under HKEY_CLASSES_ROOT and name it phpfile.
Highlight the new key phpfile and in the right side pane, double click the "default value" and enter PHP Script.
Right click on the phpfile key and select New->Key, name it Shell.
Right click on the Shell key and select New->Key, name it open.
Right click on the open key and select New->Key, name it command.
Highlight the new key command and in the right side pane, double click the "default value" and enter the path to php.exe. ex: c:\php\php.exe -q %1. (don't forget the %1).
Exit Regedit.
If using PWS on Windows, reboot to reload the registry.
PWS and IIS 3 users now have a fully operational system. IIS 3 users can use a nifty tool from Steven Genusa to configure their script maps.
This section contains notes and hints specific to Apache 1.3.x installs of PHP on Microsoft Windows systems. There are also instructions and notes for Apache 2 on a separate page.
Note: Please read the manual installation steps first!
There are two ways to set up PHP to work with Apache 1.3.x on Windows. One is to use the CGI binary (php.exe for PHP 4 and php-cgi.exe for PHP 5), the other is to use the Apache Module DLL. In either case you need to edit your httpd.conf to configure Apache to work with PHP, and then restart the server.
It is worth noting here that now the SAPI module has been made more stable under Windows, we recommend it's use above the CGI binary, since it is more transparent and secure.
Although there can be a few variations of configuring PHP under Apache, these are simple enough to be used by the newcomer. Please consult the Apache Documentation for further configuration directives.
After changing the configuration file, remember to restart the server, for example, NET STOP APACHE followed by NET START APACHE, if you run Apache as a Windows Service, or use your regular shortcuts.
Note: Remember that when adding path values in the Apache configuration files on Windows, all backslashes such as c:\directory\file.ext must be converted to forward slashes, as c:/directory/file.ext. A trailing slash may also be necessary for directories.
You should add the following lines to your Apache httpd.conf file:
Example 6-3. PHP as an Apache 1.3.x module This assumes PHP is installed to c:\php. Adjust the path if this is not the case. For PHP 4:
For PHP 5:
For both:
|
If you unzipped the PHP package to C:\php\ as described in the Manual Installation Steps section, you need to insert these lines to your Apache configuration file to set up the CGI binary:
| Warning |
By using the CGI setup, your server is open to several possible attacks. Please read our CGI security section to learn how to defend yourself from those attacks. |
If you would like to present PHP source files syntax highlighted, there is no such convenient option as with the module version of PHP. If you chose to configure Apache to use PHP as a CGI binary, you will need to use the highlight_file() function. To do this simply create a PHP script file and add this code: <?php highlight_file('some_php_script.php'); ?>.
This section contains notes and hints specific to Apache 2.0.x installs of PHP on Microsoft Windows systems. We also have instructions and notes for Apache 1.3.x users on a separate page.
Note: You should read the manual installation steps first!
Apache 2.2.x Support: Users of Apache 2.2.x may use the documentation below except the appropriate DLL file is named php5apache2_2.dll and it only exists as of PHP 5.2.0. See also http://snaps.php.net/
| Warning |
We do not recommend using a threaded MPM in production with Apache2. Use the prefork MPM instead, or use Apache1. For information on why, read the related FAQ entry on using Apache2 with a threaded MPM |
You are highly encouraged to take a look at the Apache Documentation to get a basic understanding of the Apache 2.0.x Server. Also consider to read the Windows specific notes for Apache 2.0.x before reading on here.
PHP and Apache 2.0.x compatibility notes: The following versions of PHP are known to work with the most recent version of Apache 2.0.x:
These versions of PHP are compatible to Apache 2.0.40 and later.
- PHP 4.3.0 or later available at http://www.php.net/downloads.php.
- the latest stable development version. Get the source code http://snaps.php.net/php5-latest.tar.gz or download binaries for Windows http://snaps.php.net/win32/php5-win32-latest.zip.
- a prerelease version downloadable from http://qa.php.net/.
- you have always the option to obtain PHP through anonymous CVS.
Apache 2.0 SAPI-support started with PHP 4.2.0. PHP 4.2.3 works with Apache 2.0.39, don't use any other version of Apache with PHP 4.2.3. However, the recommended setup is to use PHP 4.3.0 or later with the most recent version of Apache2.
All mentioned versions of PHP will work still with Apache 1.3.x.
| Warning |
Apache 2.0.x is designed to run on Windows NT 4.0, Windows 2000 or Windows XP. At this time, support for Windows 9x is incomplete. Apache 2.0.x is not expected to work on those platforms at this time. |
Download the most recent version of Apache 2.0.x and a fitting PHP version. Follow the Manual Installation Steps and come back to go on with the integration of PHP and Apache.
There are two ways to set up PHP to work with Apache 2.0.x on Windows. One is to use the CGI binary the other is to use the Apache module DLL. In either case you need to edit your httpd.conf to configure Apache to work with PHP and then restart the server.
Note: Remember that when adding path values in the Apache configuration files on Windows, all backslashes such as c:\directory\file.ext must be converted to forward slashes, as c:/directory/file.ext. A trailing slash may also be necessary for directories.
You need to insert these three lines to your Apache httpd.conf configuration file to set up the CGI binary:
| Warning |
By using the CGI setup, your server is open to several possible attacks. Please read our CGI security section to learn how to defend yourself from those attacks. |
You need to insert these two lines to your Apache httpd.conf configuration file to set up the PHP module for Apache 2.0:
Example 6-6. PHP and Apache 2.0 as Module
|
Note: Remember to substitute your actual path to PHP for the c:/php/ in the above examples. Take care to use either php4apache2.dll or php5apache2.dll in your LoadModule directive and not php4apache.dll or php5apache.dll as the latter ones are designed to run with Apache 1.3.x.
Note: If you want to use content negotiation, read related FAQ.
| Warning |
Don't mix up your installation with DLL files from different PHP versions. You have the only choice to use the DLL's and extensions that ship with your downloaded PHP version. |
This section contains notes and hints specific to Sun Java System Web Server, Sun ONE Web Server, iPlanet and Netscape server installs of PHP on Windows.
From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to generate custom directory listings and error pages. Additional functions for Apache compatibility are also available. For support in current web servers read the note about subrequests.
To install PHP as a CGI handler, do the following:
Copy php4ts.dll to your systemroot (the directory where you installed Windows)
Make a file association from the command line. Type the following two lines:
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %* |
In the Netscape Enterprise Administration Server create a dummy shellcgi directory and remove it just after (this step creates 5 important lines in obj.conf and allow the web server to handle shellcgi scripts).
In the Netscape Enterprise Administration Server create a new mime type (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).
Do it for each web server instance you want PHP to run
More details about setting up PHP as a CGI executable can be found here: http://benoit.noss.free.fr/php/install-php.html
To install PHP with NSAPI, do the following:
Copy php4ts.dll to your systemroot (the directory where you installed Windows)
Make a file association from the command line. Type the following two lines:
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %* |
In the Netscape Enterprise Administration Server create a new mime type (Category: type, Content-Type: magnus-internal/x-httpd-php, File Suffix: php).
Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) and add the following: You should place the lines after mime types init.
Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll" Init fn="php4_init" LateInit="yes" errorString="Failed to initialise PHP!" [php_ini="c:/path/to/php.ini"] |
Configure the default object in obj.conf (for virtual server classes [Sun Web Server 6.0+] in their vserver.obj.conf): In the <Object name="default"> section, place this line necessarily after all 'ObjectType' and before all 'AddLog' lines:
Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...] |
This is only needed if you want to configure a directory that only consists of PHP scripts (same like a cgi-bin directory):
<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute [inikey=value inikey=value ...] </Object> |
Restart your web service and apply changes
Do it for each web server instance you want PHP to run
Note: More details about setting up PHP as an NSAPI filter can be found here: http://benoit.noss.free.fr/php/install-php4.html
Note: The stacksize that PHP uses depends on the configuration of the web server. If you get crashes with very large PHP scripts, it is recommended to raise it with the Admin Server (in the section "MAGNUS EDITOR").
Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE WS/iPlanet/Netscape is a multithreaded web server. Because of that all requests are running in the same process space (the space of the web server itself) and this space has only one environment. If you want to get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the correct way to try this in the old PHP 3.x way with getenv() or a similar way (register globals to environment, $_ENV). You would only get the environment of the running web server without any valid CGI variables!
Note: Why are there (invalid) CGI variables in the environment?
Answer: This is because you started the web server process from the admin server which runs the startup script of the web server, you wanted to start, as a CGI script (a CGI script inside of the admin server!). This is why the environment of the started web server has some CGI environment variables in it. You can test this by starting the web server not from the administration server. Use the command line as root user and start it manually - you will see there are no CGI-like environment variables.
Simply change your scripts to get CGI variables in the correct way for PHP 4.x by using the superglobal $_SERVER. If you have older scripts which use $HTTP_HOST, etc., you should turn on register_globals in php.ini and change the variable order too (important: remove "E" from it, because you do not need the environment here):
variables_order = "GPCS" register_globals = On |
You can use PHP to generate the error pages for "404 Not Found" or similar. Add the following line to the object in obj.conf for every error page you want to overwrite:
Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...] |
Another possibility is to generate self-made directory listings. Just create a PHP script which displays a directory listing and replace the corresponding default Service line for type="magnus-internal/directory" in obj.conf with the following:
Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...] |
The NSAPI module now supports the nsapi_virtual() function (alias: virtual()) to make subrequests on the web server and insert the result in the web page. The problem is, that this function uses some undocumented features from the NSAPI library.
Under Unix this is not a problem, because the module automatically looks for the needed functions and uses them if available. If not, nsapi_virtual() is disabled.
Under Windows limitations in the DLL handling need the use of a automatic detection of the most recent ns-httpdXX.dll file. This is tested for servers till version 6.1. If a newer version of the Sun server is used, the detection fails and nsapi_virtual() is disabled.
If this is the case, try the following: Add the following parameter to php4_init in magnus.conf/obj.conf:
Init fn=php4_init ... server_lib="ns-httpdXX.dll" |
You can check the status by using the phpinfo() function.
Note: But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!!
This section contains notes and hints specific to OmniHTTPd on Windows.
Note: You should read the manual installation steps first!
| Warning |
By using the CGI setup, your server is open to several possible attacks. Please read our CGI security section to learn how to defend yourself from those attacks. |
You need to complete the following steps to make PHP work with OmniHTTPd. This is a CGI executable setup. SAPI is supported by OmniHTTPd, but some tests have shown that it is not so stable to use PHP as an ISAPI module.
Important for CGI users: Read the faq on cgi.force_redirect for important details. This directive needs to be set to 0.
Install OmniHTTPd server.
Right click on the blue OmniHTTPd icon in the system tray and select Properties
Click on Web Server Global Settings
On the 'External' tab, enter: virtual = .php | actual = c:\php\php.exe (use php-cgi.exe if installing PHP 5), and use the Add button.
On the Mime tab, enter: virtual = wwwserver/stdcgi | actual = .php, and use the Add button.
Click OK
Repeat steps 2 - 6 for each extension you want to associate with PHP.
Note: Some OmniHTTPd packages come with built in PHP support. You can choose at setup time to do a custom setup, and uncheck the PHP component. We recommend you to use the latest PHP binaries. Some OmniHTTPd servers come with PHP 4 beta distributions, so you should choose not to set up the built in support, but install your own. If the server is already on your machine, use the Replace button in Step 4 and 5 to set the new, correct information.
This section contains notes and hints specific to the Sambar Server for Windows.
Note: You should read the manual installation steps first!
This list describes how to set up the ISAPI module to work with the Sambar server on Windows.
Find the file called mappings.ini (in the config directory) in the Sambar install directory.
Open mappings.ini and add the following line under [ISAPI]:
Now restart the Sambar server for the changes to take effect.
Note: If you intend to use PHP to communicate with resources which are held on a different computer on your network, then you will need to alter the account used by the Sambar Server Service. The default account used for the Sambar Server Service is LocalSystem which will not have access to remote resources. The account can be amended by using the Services option from within the Windows Control Panel Administation Tools.
This section contains notes and hints specific to Xitami on Windows.
Note: You should read the manual installation steps first!
This list describes how to set up the PHP CGI binary to work with Xitami on Windows.
Important for CGI users: Read the faq on cgi.force_redirect for important details. This directive needs to be set to 0. If you want to use $_SERVER['PHP_SELF'] you have to enable the cgi.fix_pathinfo directive.
| Warning |
By using the CGI setup, your server is open to several possible attacks. Please read our CGI security section to learn how to defend yourself from those attacks. |
Make sure the web server is running, and point your browser to xitamis admin console (usually http://127.0.0.1/admin), and click on Configuration.
Navigate to the Filters, and put the extension which PHP should parse (i.e. .php) into the field File extensions (.xxx).
In Filter command or script put the path and name of your PHP CGI executable i.e. C:\php\php.exe for PHP 4, or C:\php\php-cgi.exe for PHP 5.
Press the 'Save' icon.
Restart the server to reflect changes.
This chapter teaches how to compile PHP from sources on windows, using Microsoft's tools. To compile PHP with cygwin, please refer to Chapter 4.
To compile and build PHP you need a Microsoft Development Environment. Microsoft Visual C++ 6.0 is recommended, though Visual C++ .NET versions will also work. Since PHP 5 the free Microsoft .NET toolchain is also supported (you need to install Windows Platform SDK, Visual C++ Toolkit and .NET Framework SDK).
To extract the downloaded files you will also need a ZIP extraction utility. Windows XP and newer already include this functionality built-in.
Before you get started, you have to download:
the win32 buildtools from the PHP site at http://www.php.net/extra/win32build.zip.
the source code for the DNS name resolver used by PHP from http://www.php.net/extra/bindlib_w32.zip. This is a replacement for the resolv.lib library included in win32build.zip.
If you plan to compile PHP as a Apache module you will also need the Apache sources.
Finally, you are going to need the source to PHP itself. You can get the latest development version using anonymous CVS, a snapshot or the most recent released source tarball.
After downloading the required packages you have to extract them in a proper place:
Create a working directory where all files end up after extracting, e.g: C:\work.
Create the directory win32build under your working directory (C:\work) and unzip win32build.zip into it.
Create the directory bindlib_w32 under your working directory (C:\work) and unzip bindlib_w32.zip into it.
Extract the downloaded PHP source code into your working directory (C:\work).
Build the libraries you are going to need (or download the binaries if available) and place the headers and libs in the C:\work\win32build\include and C:\work\win32build\lib directories, respectively.
If you don't have cygwin installed with bison and flex, you also need to make the C:\work\win32build\bin directory available in the PATH, so that thoses tools can be found by the configure script.
+--C:\work | | | +--bindlib_w32 | | | | | +--arpa | | | | | +--conf | | | | | +--... | | | +--php-5.x.x | | | | | +--build | | | | | +--... | | | | | +--win32 | | | | | +--... | | | +--win32build | | | | | +--bin | | | | | +--include | | | | | +--lib |
If you aren't using Cygwin, you must also create the directories C:\usr\local\lib and then copy bison.simple from C:\work\win32build\bin to C:\usr\local\lib.
Note: If you want to use PEAR and the comfortable command line installer, the CLI-SAPI is mandatory. For more information about PEAR and the installer read the documentation at the PEAR website.
You must build the resolv.lib library. Decide whether you want to have debug symbols available (bindlib - Win32 Debug) or not (bindlib - Win32 Release), but please remember the choice you made, because the debug build will only link with PHP when it is also built in debug mode. Build the appropriate configuration:
For GUI users, launch VC++, by double-clicking in C:\work\bindlib_w32\bindlib.dsw. Then select Build=>Rebuild All.
For command line users, make sure that you either have the C++ environment variables registered, or have run vcvars.bat, and then execute one of the following commands:
msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"
msdev bindlib.dsp /MAKE "bindlib - Win32 Release"
This chapter explains how to compile PHP >=5 using the new build system, which is CLI-based and very similar with the main PHP's Unix build system.
Note: This build system isn't available in PHP 4. Please refer to the Section called Building PHP using DSW files [PHP 4] instead.
Before starting, be sure you have read the Section called Putting it all together and you have built all needed libraries, like Libxml or ICU (needed for PHP >= 6).
First you should open a Visual Studio Command Prompt, which should be available under the Start menu. A regular Command Prompt window shouldn't work, as probably it doesn't have the necessary environment variables set. Then type something like cd C:\work\php-5.x.x to enter in the PHP source dir. Now you are ready to start configuring PHP.
The second step is running the buildconf batch file to make the configure script, by scanning the folder for config.w32 files. By default this command will also search in the following directories: pecl; ..\pecl; pecl\rpc; ..\pecl\rpc. Since PHP 5.1.0, you can change this behaviour by using the --add-modules-dir argument (e.g. cscript /nologo win32/build/buildconf.js --add-modules-dir=../php-gtk2 --add-modules-dir=../pecl).
The third step is configuring. To view the list of the available configuration options type cscript /nologo configure.js --help. After choosing the options that you will enable/disable, type something like: cscript /nologo configure.js --disable-foo --enable-fun-ext. Using --enable-foo=shared will attempt to build the 'foo' extension as a shared, dynamically loadable module.
The last step is compiling. To achieve this just issue the command nmake. The generated files (e.g. .exe and .dll) will be placed in either Release_TS or Debug_TS directories (if built with Thread safety), or in the Release or Debug directories otherwise.
Optionally you may also run PHP's test suite, by typing nmake test. If you want to run just a specific test, you may use the 'TESTS' variable (e.g. nmake /D TESTS=ext/sqlite/tests test - will only run sqlite's tests). To delete the files that were created during the compilation, you can use the nmake clean command.
A very useful configure option to build snapshots is --enable-snapshot-build, which add a new compiling mode (nmake build-snap). This tries to build every extension available (as shared, by default), but it will ignore build errors in individual extensions or SAPI.
Compiling PHP using the DSW files isn't supported as of PHP 5, as a much more flexible system was made available. Anyway, you can still use them, but keep in mind that they are not maintained very often, so you can have compiling problems. To compile PHP 4 for windows, this is the only available way though.
The first step is to configure MVC++ to prepare for compiling. Launch Microsoft Visual C++, and from the menu select Tools => Options. In the dialog, select the directories tab. Sequentially change the dropdown to Executables, Includes, and Library files. Your entries should look like this:
Executable files: C:\work\win32build\bin, Cygwin users: C:\cygwin\bin
Include files: C:\work\win32build\include
Library files: C:\work\win32build\lib
The best way to get started is to build the CGI version:
For GUI users, launch VC++, and then select File => Open Workspace and select C:\work\php-4.x.x\win32\php4ts.dsw. Then select Build=>Set Active Configuration and select the desired configuration, either php4ts - Win32 Debug_TS or php4ts - Win32 Release_TS. Finally select Build=>Rebuild All.
For command line users, make sure that you either have the C++ environment variables registered, or have run vcvars.bat, and then execute one of the following commands from the C:\work\php-4.x.x\win32 directory:
msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"
msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"
At this point, you should have a usable php.exe in either your C:\work\php-4.x.x\Debug_TS or Release_TS subdirectories.
It is possible to do minor customization to the build process by editing the main/config.win32.h file. For example you can change the default location of php.ini, the built-in extensions, and the default location for your extensions.
Next you may want to build the CLI version which is designed to use PHP from the command line. The steps are the same as for building the CGI version, except you have to select the php4ts_cli - Win32 Debug_TS or php4ts_cli - Win32 Release_TS project file. After a successful compiling run you will find the php.exe in either the directory Release_TS\cli\ or Debug_TS\cli\.
In order to build the SAPI module (php4isapi.dll) for integrating PHP with Microsoft IIS, set your active configuration to php4isapi-whatever-config and build the desired dll.
After installing PHP and a web server on Windows, you will probably want to install some extensions for added functionality. You can choose which extensions you would like to load when PHP starts by modifying your php.ini. You can also load a module dynamically in your script using dl().
The DLLs for PHP extensions are prefixed with php_.
Many extensions are built into the Windows version of PHP. This means additional DLL files, and the extension directive, are not used to load these extensions. The Windows PHP Extensions table lists extensions that require, or used to require, additional PHP DLL files. Here's a list of built in extensions:
In PHP 4 (updated PHP 4.3.11): BCMath, Caledar, COM, Ctype, FTP, MySQL, ODBC, Overload, PCRE, Session, Tokenizer, WDDX, XML and Zlib
In PHP 5 (updated PHP 5.0.4), the following changes exist. Built in: DOM, LibXML, Iconv, SimpleXML, SPL and SQLite. And the following are no longer built in: MySQL and Overload.
The default location PHP searches for extensions is C:\php4\extensions in PHP 4 and C:\php5 in PHP 5. To change this setting to reflect your setup of PHP edit your php.ini file:
You will need to change the extension_dir setting to point to the directory where your extensions lives, or where you have placed your php_*.dll files. For example:
Enable the extension(s) in php.ini you want to use by uncommenting the extension=php_*.dll lines in php.ini. This is done by deleting the leading ; from the extension you want to load.
Example 6-8. Enable Bzip2 extension for PHP-Windows
|
Some of the extensions need extra DLLs to work. Couple of them can be
found in the distribution package, in the
C:\php\dlls\ folder in PHP 4 or
in the main folder in PHP 5, but some, for example Oracle
(php_oci8.dll) require DLLs which are not bundled
with the distribution package. If you are installing PHP 4, copy the
bundled DLLs from C:\php\dlls
folder to the main C:\php
folder. Don't forget to include C:\php in the system
PATH (this process is explained in a separate FAQ entry).
Some of these DLLs are not bundled with the PHP distribution. See each extensions documentation page for details. Also, read the manual section titled Installation of PECL extensions for details on PECL. An increasingly large number of PHP extensions are found in PECL, and these extensions require a separate download.
Note: If you are running a server module version of PHP remember to restart your web server to reflect your changes to php.ini.
The following table describes some of the extensions available and required additional dlls.
Table 6-1. PHP Extensions
| Extension | Description | Notes |
|---|---|---|
| php_bz2.dll | bzip2 compression functions | None |
| php_calendar.dll | Calendar conversion functions | Built in since PHP 4.0.3 |
| php_cpdf.dll | ClibPDF functions | None |
| php_crack.dll | Crack functions | None |
| php_ctype.dll | ctype family functions | Built in since PHP 4.3.0 |
| php_curl.dll | CURL, Client URL library functions | Requires: libeay32.dll, ssleay32.dll (bundled) |
| php_cybercash.dll | Cybercash payment functions | PHP <= 4.2.0 |
| php_db.dll | DBM functions | Deprecated. Use DBA instead (php_dba.dll) |
| php_dba.dll | DBA: DataBase (dbm-style) Abstraction layer functions | None |
| php_dbase.dll | dBase functions | None |
| php_dbx.dll | dbx functions | |
| php_domxml.dll | DOM XML functions | PHP <= 4.2.0 requires: libxml2.dll (bundled) PHP >= 4.3.0 requires: iconv.dll (bundled) |
| php_dotnet.dll | .NET functions | PHP <= 4.1.1 |
| php_exif.dll | EXIF functions | php_mbstring.dll. And, php_exif.dll must be loaded after php_mbstring.dll in php.ini. |
| php_fbsql.dll | FrontBase functions | PHP <= 4.2.0 |
| php_fdf.dll | FDF: Forms Data Format functions. | Requires: fdftk.dll (bundled) |
| php_filepro.dll | filePro functions | Read-only access |
| php_ftp.dll | FTP functions | Built-in since PHP 4.0.3 |
| php_gd.dll | GD library image functions | Removed in PHP 4.3.2. Also note that truecolor functions are not available in GD1, instead, use php_gd2.dll. |
| php_gd2.dll | GD library image functions | GD2 |
| php_gettext.dll | Gettext functions | PHP <= 4.2.0 requires gnu_gettext.dll (bundled), PHP >= 4.2.3 requires libintl-1.dll, iconv.dll (bundled). |
| php_hyperwave.dll | HyperWave functions | None |
| php_iconv.dll | ICONV characterset conversion | Requires: iconv-1.3.dll (bundled), PHP >=4.2.1 iconv.dll |
| php_ifx.dll | Informix functions | Requires: Informix libraries |
| php_iisfunc.dll | IIS management functions | None |
| php_imap.dll | IMAP POP3 and NNTP functions | None |
| php_ingres.dll | Ingres II functions | Requires: Ingres II libraries |
| php_interbase.dll | InterBase functions | Requires: gds32.dll (bundled) |
| php_java.dll | Java functions | PHP <= 4.0.6 requires: jvm.dll (bundled) |
| php_ldap.dll | LDAP functions | PHP <= 4.2.0 requires libsasl.dll (bundled), PHP >= 4.3.0 requires libeay32.dll, ssleay32.dll (bundled) |
| php_mbstring.dll | Multi-Byte String functions | None |
| php_mcrypt.dll | Mcrypt Encryption functions | Requires: libmcrypt.dll |
| php_mhash.dll | Mhash functions | PHP >= 4.3.0 requires: libmhash.dll (bundled) |
| php_mime_magic.dll | Mimetype functions | Requires: magic.mime (bundled) |
| php_ming.dll | Ming functions for Flash | None |
| php_msql.dll | mSQL functions | Requires: msql.dll (bundled) |
| php_mssql.dll | MSSQL functions | Requires: ntwdblib.dll (bundled) |
| php_mysql.dll | MySQL functions | PHP >= 5.0.0, requires libmysql.dll (bundled) |
| php_mysqli.dll | MySQLi functions | PHP >= 5.0.0, requires libmysql.dll (libmysqli.dll in PHP <= 5.0.2) (bundled) |
| php_oci8.dll | Oracle 8 functions | Requires: Oracle 8.1+ client libraries |
| php_openssl.dll | OpenSSL functions | Requires: libeay32.dll (bundled) |
| php_oracle.dll | Oracle functions | Requires: Oracle 7 client libraries |
| php_overload.dll | Object overloading functions | Built in since PHP 4.3.0 |
| php_pdf.dll | PDF functions | None |
| php_pgsql.dll | PostgreSQL functions | None |
| php_printer.dll | Printer functions | None |
| php_shmop.dll | Shared Memory functions | None |
| php_snmp.dll | SNMP get and walk functions | NT only! |
| php_soap.dll | SOAP functions | PHP >= 5.0.0 |
| php_sockets.dll | Socket functions | None |
| php_sybase_ct.dll | Sybase functions | Requires: Sybase client libraries |
| php_tidy.dll | Tidy functions | PHP >= 5.0.0 |
| php_tokenizer.dll | Tokenizer functions | Built in since PHP 4.3.0 |
| php_w32api.dll | W32api functions | None |
| php_xmlrpc.dll | XML-RPC functions | PHP >= 4.2.1 requires: iconv.dll (bundled) |
| php_xslt.dll | XSLT functions | PHP <= 4.2.0 requires sablot.dll, expat.dll (bundled). PHP >= 4.2.1 requires sablot.dll, expat.dll, iconv.dll (bundled). |
| php_yaz.dll | YAZ functions | Requires: yaz.dll (bundled) |
| php_zip.dll | Zip File functions | Read only access |
| php_zlib.dll | ZLib compression functions | Built in since PHP 4.3.0 |
PECL is a repository of PHP extensions that are made available to you via the PEAR packaging system. This section of the manual is intended to demonstrate how to obtain and install PECL extensions.
These instructions assume /your/phpsrcdir/ is the path to the PHP source distribution, and that extname is the name of the PECL extension. Adjust accordingly. These instructions also assume a familiarity with the pear command. The information in the PEAR manual for the pear command also applies to the pecl command.
To be useful, a shared extension must be built, installed, and loaded. The methods described below provide you with various instructions on how to build and install the extensions, but they do not automatically load them. Extensions can be loaded by adding an extension directive. To this php.ini file, or through the use of the dl() function.
When building PHP modules, it's important to have known-good versions of the required tools (autoconf, automake, libtool, etc.) See the Anonymous CVS Instructions for details on the required tools, and required versions.
There are several options for downloading PECL extensions, such as:
The PECL web site contains information about the different extensions that are offered by the PHP Development Team. The information available here includes: ChangeLog, release notes, requirements and other similar details.
pecl download extname
PECL extensions that have releases listed on the PECL web site are available for download and installation using the pecl command. Specific revisions may also be specified.
CVS
Most PECL extensions also reside in CVS. A web-based view may be seen at http://cvs.php.net/pecl/. To download straight from CVS, the following sequence of commands may be used. Note that phpfi is the password for user cvsread:
$ cvs -d:pserver:cvsread@cvs.php.net:/repository login $ cvs -d:pserver:cvsread@cvs.php.net:/repository co pecl/extname |
Windows downloads
Windows users may find compiled PECL binaries by downloading the Collection of PECL modules from the PHP Downloads page, or by retrieving a PECL Snapshot or an extension DLL on PECL4WIN. To compile PHP under Windows, read the appropriate chapter.
As with any other PHP extension DLL, installation is as simple as copying the PECL extension DLLs into the extension_dir folder and loading them from php.ini. For example, add the following line to your php.ini:
extension=php_extname.dll |
After doing this, restart the web server.
PECL makes it easy to create shared PHP extensions. Using the pecl command, do the following:
$ pecl install extname |
This will download the source for extname, compile, and install extname.so into your extension_dir. extname.so may then be loaded via php.ini
By default, the pecl command will not install packages that are marked with the alpha or beta state. If no stable packages are available, you may install a beta package using the following command:
$ pecl install extname-beta |
You may also install a specific version using this variant:
$ pecl install extname-0.1 |
Sometimes, using the pecl installer is not an option. This could be because you're behind a firewall, or it could be because the extension you want to install is not available as a PECL compatible package, such as unreleased extensions from CVS. If you need to build such an extension, you can use the lower-level build tools to perform the build manually.
The phpize command is used to prepare the build environment for a PHP extension. In the following sample, the sources for an extension are in a directory named extname:
$ cd extname $ phpize $ ./configure $ make # make install |
A successful install will have created extname.so and put it into the PHP extensions directory. You'll need to and adjust php.ini and add an extension=extname.so line before you can use the extension.
If the system is missing the phpize command, and precompiled packages (like RPM's) are used, be sure to also install the appropriate devel version of the PHP package as they often include the phpize command along with the appropriate header files to build PHP and its extensions.
Execute phpize --help to display additional usage information.
You might find that you need to build a PECL extension statically into your PHP binary. To do this, you'll need to place the extension source under the php-src/ext/ directory and tell the PHP build system to regenerate its configure script.
$ cd /your/phpsrcdir/ext $ pecl download extname $ gzip -d < extname.tgz | tar -xvf - $ mv extname-x.x.x extname |
This will result in the following directory:
/your/phpsrcdir/ext/extname |
From here, force PHP to rebuild the configure script, and then build PHP as normal:
$ cd /your/phpsrcdir $ rm configure $ ./buildconf --force $ ./configure --help $ ./configure --with-extname --enable-someotherext --with-foobar $ make $ make install |
Note: To run the 'buildconf' script you need autoconf 2.13 and automake 1.4+ (newer versions of autoconf may work, but are not supported).
Whether --enable-extname or --with-extname is used depends on the extension. Typically an extension that does not require external libraries uses --enable. To be sure, run the following after buildconf:
$ ./configure --help | grep extname |
Some problems are more common than others. The most common ones are listed in the PHP FAQ, part of this manual.
If you are still stuck, someone on the PHP installation mailing list may be able to help you. You should check out the archive first, in case someone already answered someone else who had the same problem as you. The archives are available from the support page on http://www.php.net/support.php. To subscribe to the PHP installation mailing list, send an empty mail to php-install-subscribe@lists.php.net. The mailing list address is php-install@lists.php.net.
If you want to get help on the mailing list, please try to be precise and give the necessary details about your environment (which operating system, what PHP version, what web server, if you are running PHP as CGI or a server module, safe mode, etc...), and preferably enough code to make others able to reproduce and test your problem.
If you think you have found a bug in PHP, please report it. The PHP developers probably don't know about it, and unless you report it, chances are it won't be fixed. You can report bugs using the bug-tracking system at http://bugs.php.net/. Please do not send bug reports in mailing list or personal letters. The bug system is also suitable to submit feature requests.
Read the How to report a bug document before submitting any bug reports!
The configuration file (called php3.ini in PHP 3, and simply php.ini as of PHP 4) is read when PHP starts up. For the server module versions of PHP, this happens only once when the web server is started. For the CGI and CLI version, it happens on every invocation.
php.ini is searched in these locations (in order):
SAPI module specific location (PHPIniDir directive in Apache 2, -c command line option in CGI and CLI, php_ini parameter in NSAPI, PHP_INI_PATH environment variable in THTTPD)
The PHPRC environment variable. Before PHP 5.2.0
this was checked after the registry key mentioned below.
As of PHP 5.2.0, the following registry locations are searched in order: HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z\IniFilePath, HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y\IniFilePath and HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x\IniFilePath, where x, y and z mean the PHP major, minor and release versions.
HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath (Windows Registry location)
Current working directory (except CLI)
The web server's directory (for SAPI modules), or directory of PHP (otherwise in Windows)
Windows directory (C:\windows or C:\winnt) (for Windows), or --with-config-file-path compile time option
If php-SAPI.ini exists (where SAPI is used SAPI, so the filename is e.g. php-cli.ini or php-apache.ini), it's used instead of php.ini. SAPI name can be determined by php_sapi_name().
Note: The Apache web server changes the directory to root at startup causing PHP to attempt to read php.ini from the root filesystem if it exists.
The php.ini directives handled by extensions are documented respectively on the pages of the extensions themselves. The list of the core directives is available in the appendix. Probably not all PHP directives are documented in the manual though. For a complete list of directives available in your PHP version, please read your well commented php.ini file. Alternatively, you may find the the latest php.ini from CVS helpful too.
Example 9-1. php.ini example
|
Since PHP 5.1.0, it is possible to refer to existing .ini variables from within .ini files. Example: open_basedir = ${open_basedir} ":/new/dir".
When using PHP as an Apache module, you can also change the configuration settings using directives in Apache configuration files (e.g. httpd.conf) and .htaccess files. You will need "AllowOverride Options" or "AllowOverride All" privileges to do so.
With PHP 4 and PHP 5, there are several Apache directives that allow you to change the PHP configuration from within the Apache configuration files. For a listing of which directives are PHP_INI_ALL, PHP_INI_PERDIR, or PHP_INI_SYSTEM, have a look at the List of php.ini directives appendix.
Note: With PHP 3, there are Apache directives that correspond to each configuration setting in the php3.ini name, except the name is prefixed by "php3_".
name
valueSets the value of the specified directive. Can be used only with PHP_INI_ALL and PHP_INI_PERDIR type directives. To clear a previously set value use none as the value.
Note: Don't use php_value to set boolean values. php_flag (see below) should be used instead.
name
on|offUsed to set a boolean configuration directive. Can be used only with PHP_INI_ALL and PHP_INI_PERDIR type directives.
name
valueSets the value of the specified directive. This can not be used in .htaccess files. Any directive type set with php_admin_value can not be overridden by .htaccess or virtualhost directives. To clear a previously set value use none as the value.
name
on|offUsed to set a boolean configuration directive. This can not be used in .htaccess files. Any directive type set with php_admin_flag can not be overridden by .htaccess or virtualhost directives.
Example 9-2. Apache configuration example
|
| Caution |
PHP constants do not exist outside of PHP. For example, in httpd.conf you can not use PHP constants such as E_ALL or E_NOTICE to set the error_reporting directive as they will have no meaning and will evaluate to 0. Use the associated bitmask values instead. These constants can be used in php.ini |
When running PHP on Windows, the configuration values can be modified on a per-directory basis using the Windows registry. The configuration values are stored in the registry key HKLM\SOFTWARE\PHP\Per Directory Values, in the sub-keys corresponding to the path names. For example, configuration values for the directory c:\inetpub\wwwroot would be stored in the key HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot. The settings for the directory would be active for any script running from this directory or any subdirectory of it. The values under the key should have the name of the PHP configuration directive and the string value. PHP constants in the values are not parsed. However, only configuration values changeable in PHP_INI_USER can be set this way, PHP_INI_PERDIR values can not.
Regardless of how you run PHP, you can change certain values at runtime of your scripts through ini_set(). See the documentation on the ini_set() page for more information.
If you are interested in a complete list of configuration settings on your system with their current values, you can execute the phpinfo() function, and review the resulting page. You can also access the values of individual configuration directives at runtime using ini_get() or get_cfg_var().
When PHP parses a file, it looks for opening and closing tags, which tell PHP to start and stop interpreting the code between them. Parsing in this manner allows php to be embedded in all sorts of different documents, as everything outside of a pair of opening and closing tags is ignored by the PHP parser. Most of the time you will see php embedded in HTML documents, as in this example.
<p>This is going to be ignored.</p> <?php echo 'While this is going to be parsed.'; ?> <p>This will also be ignored.</p> |
You can also use more advanced structures:
There are four different pairs of opening and closing tags which can be used in php. Two of those, <?php ?> and <script language="php"> </script>, are always available. The other two are short tags and ASP style tags, and can be turned on and off from the php.ini configuration file. As such, while some people find short tags and ASP style tags convenient, they are less portable, and generally not recommended.
Note: Also note that if you are embedding PHP within XML or XHTML you will need to use the <?php ?> tags to remain compliant with standards.
Example 10-2. PHP Opening and Closing Tags
|
While the tags seen in examples one and two are both always available, example one is the most commonly used, and recommended, of the two.
Short tags (example three) are only available when they are
enabled via the short_open_tag
php.ini configuration file directive, or if php was configured
with the --enable-short-tags option.
Note: If you are using PHP 3 you may also enable short tags via the short_tags() function. This is only available in PHP 3!
ASP style tags (example four) are only available when they are enabled via the asp_tags php.ini configuration file directive.
Note: Support for ASP tags was added in 3.0.4.
Note: Using short tags should be avoided when developing applications or libraries that are meant for redistribution, or deployment on PHP servers which are not under your control, because short tags may not be supported on the target server. For portable, redistributable code, be sure not to use short tags.
As in C or Perl, PHP requires instructions to be terminated with a semicolon at the end of each statement. The closing tag of a block of PHP code automatically implies a semicolon; you do not need to have a semicolon terminating the last line of a PHP block. The closing tag for the block will include the immediately trailing newline if one is present.
<?php
echo 'This is a test';
?>
<?php echo 'This is a test' ?>
<?php echo 'We omitted the last closing tag'; |
Note: The closing tag of a PHP block at the end of a file is optional, and in some cases omitting it is helpful when using include() or require(), so unwanted whitespace will not occur at the end of files, and you will still be able to add headers to the response later. It is also handy if you use output buffering, and would not like to see added unwanted whitespace at the end of the parts generated by the included files.
PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:
<?php
echo 'This is a test'; // This is a one-line c++ style comment
/* This is a multi line comment
yet another line of comment */
echo 'This is yet another test';
echo 'One Final Test'; # This is a one-line shell-style comment
?> |
The "one-line" comment styles only comment to the end of the line or the current block of PHP code, whichever comes first. This means that HTML code after // ... ?> or # ... ?> WILL be printed: ?> breaks out of PHP mode and returns to HTML mode, and // or # cannot influence that. If the asp_tags configuration directive is enabled, it behaves the same with // %> and # %>. However, the </script> tag doesn't break out of PHP mode in a one-line comment.
<h1>This is an <?php # echo 'simple';?> example.</h1> <p>The header above will say 'This is an example'.</p> |
'C' style comments end at the first */ encountered. Make sure you don't nest 'C' style comments. It is easy to make this mistake if you are trying to comment out a large block of code.
PHP supports eight primitive types.
Four scalar types:
Two compound types: And finally two special types: This manual also introduces some pseudo-types for readability reasons: You may also find some references to the type "double". Consider double the same as float, the two names exist only for historic reasons.The type of a variable is usually not set by the programmer; rather, it is decided at runtime by PHP depending on the context in which that variable is used.
Note: If you want to check out the type and value of a certain expression, use var_dump().
Note: If you simply want a human-readable representation of the type for debugging, use gettype(). To check for a certain type, do not use gettype(), but use the is_type functions. Some examples:
<?php $a_bool = TRUE; // a boolean $a_str = "foo"; // a string $a_str2 = 'foo'; // a string $an_int = 12; // an integer echo gettype($a_bool); // prints out: boolean echo gettype($a_str); // prints out: string // If this is an integer, increment it by four if (is_int($an_int)) { $an_int += 4; } // If $bool is a string, print it out // (does not print out anything) if (is_string($a_bool)) { echo "String: $a_bool"; } ?>
If you would like to force a variable to be converted to a certain type, you may either cast the variable or use the settype() function on it.
Note that a variable may be evaluated with different values in certain situations, depending on what type it is at the time. For more information, see the section on Type Juggling. Also, you may be interested in viewing the type comparison tables, as they show examples of various type related comparisons.
This is the easiest type. A boolean expresses a truth value. It can be either TRUE or FALSE.
Note: The boolean type was introduced in PHP 4.
To specify a boolean literal, use either the keyword TRUE or FALSE. Both are case-insensitive.
Usually you use some kind of operator which returns a boolean value, and then pass it on to a control structure.
To explicitly convert a value to boolean, use either the (bool) or the (boolean) cast. However, in most cases you do not need to use the cast, since a value will be automatically converted if an operator, function or control structure requires a boolean argument.
See also Type Juggling.
When converting to boolean, the following values are considered FALSE:
the boolean FALSE itself
the integer 0 (zero)
the float 0.0 (zero)
an array with zero elements
an object with zero member variables (PHP 4 only)
the special type NULL (including unset variables)
SimpleXML objects created from empty tags
| Warning |
-1 is considered TRUE, like any other non-zero (whether negative or positive) number! |
<?php var_dump((bool) ""); // bool(false) var_dump((bool) 1); // bool(true) var_dump((bool) -2); // bool(true) var_dump((bool) "foo"); // bool(true) var_dump((bool) 2.3e5); // bool(true) var_dump((bool) array(12)); // bool(true) var_dump((bool) array()); // bool(false) var_dump((bool) "false"); // bool(true) ?> |
An integer is a number of the set Z = {..., -2, -1, 0, 1, 2, ...}.
See also: Arbitrary length integer / GMP, Floating point numbers, and Arbitrary precision / BCMath
Integers can be specified in decimal (10-based), hexadecimal (16-based) or octal (8-based) notation, optionally preceded by a sign (- or +).
If you use the octal notation, you must precede the number with a 0 (zero), to use hexadecimal notation precede the number with 0x.
If you specify a number beyond the bounds of the integer type, it will be interpreted as a float instead. Also, if you perform an operation that results in a number beyond the bounds of the integer type, a float will be returned instead.
<?php $large_number = 2147483647; var_dump($large_number); // output: int(2147483647) $large_number = 2147483648; var_dump($large_number); // output: float(2147483648) // it's true also for hexadecimal specified integers between 2^31 and 2^32-1: var_dump( 0xffffffff ); // output: float(4294967295) // this doesn't go for hexadecimal specified integers above 2^32-1: var_dump( 0x100000000 ); // output: int(2147483647) $million = 1000000; $large_number = 50000 * $million; var_dump($large_number); // output: float(50000000000) ?> |
| Warning |
Unfortunately, there was a bug in PHP so that this does not always work correctly when there are negative numbers involved. For example: when you do -50000 * $million, the result will be -429496728. However, when both operands are positive there is no problem. This is solved in PHP 4.1.0. |
There is no integer division operator in PHP. 1/2 yields the float 0.5. You can cast the value to an integer to always round it downwards, or you can use the round() function.
To explicitly convert a value to integer, use either the (int) or the (integer) cast. However, in most cases you do not need to use the cast, since a value will be automatically converted if an operator, function or control structure requires an integer argument. You can also convert a value to integer with the function intval().
See also type-juggling.
When converting from float to integer, the number will be rounded towards zero.
If the float is beyond the boundaries of integer (usually +/- 2.15e+9 = 2^31), the result is undefined, since the float hasn't got enough precision to give an exact integer result. No warning, not even a notice will be issued in this case!
| Warning |
Never cast an unknown fraction to integer, as this can sometimes lead to unexpected results. See for more information the warning about float-precision. |
| Caution |
Behaviour of converting to integer is undefined for other types. Currently, the behaviour is the same as if the value was first converted to boolean. However, do not rely on this behaviour, as it can change without notice. |
Floating point numbers (AKA "floats", "doubles" or "real numbers") can be specified using any of the following syntaxes:
Formally:LNUM [0-9]+
DNUM ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM}) |
| Floating point precision |
It is quite usual that simple decimal fractions like 0.1 or 0.7 cannot be converted into their internal binary counterparts without a little loss of precision. This can lead to confusing results: for example, floor((0.1+0.7)*10) will usually return 7 instead of the expected 8 as the result of the internal representation really being something like 7.9999999999.... This is related to the fact that it is impossible to exactly express some fractions in decimal notation with a finite number of digits. For instance, 1/3 in decimal form becomes 0.3333333. . .. So never trust floating number results to the last digit and never compare floating point numbers for equality. If you really need higher precision, you should use the arbitrary precision math functions or gmp functions instead. |
For information on when and how strings are converted to floats, see the section titled String conversion to numbers. For values of other types, the conversion is the same as if the value would have been converted to integer and then to float. See the Converting to integer section for more information. As of PHP 5, notice is thrown if you try to convert object to float.
A string is series of characters. In PHP, a character is the same as a byte, that is, there are exactly 256 different characters possible. This also implies that PHP has no native support of Unicode. See utf8_encode() and utf8_decode() for some Unicode support.
Note: It is no problem for a string to become very large. There is no practical bound to the size of strings imposed by PHP, so there is no reason at all to worry about long strings.
A string literal can be specified in three different ways.
The easiest way to specify a simple string is to enclose it in single quotes (the character ').
To specify a literal single quote, you will need to escape it with a backslash (\), like in many other languages. If a backslash needs to occur before a single quote or at the end of the string, you need to double it. Note that if you try to escape any other character, the backslash will also be printed! So usually there is no need to escape the backslash itself.
Note: In PHP 3, a warning will be issued at the E_NOTICE level when this happens.
Note: Unlike the two other syntaxes, variables and escape sequences for special characters will not be expanded when they occur in single quoted strings.
<?php echo 'this is a simple string'; echo 'You can also have embedded newlines in strings this way as it is okay to do'; // Outputs: Arnold once said: "I'll be back" echo 'Arnold once said: "I\'ll be back"'; // Outputs: You deleted C:\*.*? echo 'You deleted C:\\*.*?'; // Outputs: You deleted C:\*.*? echo 'You deleted C:\*.*?'; // Outputs: This will not expand: \n a newline echo 'This will not expand: \n a newline'; // Outputs: Variables do not $expand $either echo 'Variables do not $expand $either'; ?> |
If the string is enclosed in double-quotes ("), PHP understands more escape sequences for special characters:
Table 11-1. Escaped characters
| sequence | meaning |
|---|---|
| \n | linefeed (LF or 0x0A (10) in ASCII) |
| \r | carriage return (CR or 0x0D (13) in ASCII) |
| \t | horizontal tab (HT or 0x09 (9) in ASCII) |
| \\ | backslash |
| \$ | dollar sign |
| \" | double-quote |
| \[0-7]{1,3} | the sequence of characters matching the regular expression is a character in octal notation |
| \x[0-9A-Fa-f]{1,2} | the sequence of characters matching the regular expression is a character in hexadecimal notation |
Again, if you try to escape any other character, the backslash will be printed too! Before PHP 5.1.1, backslash in \{$var} hasn't been printed.
But the most important feature of double-quoted strings is the fact that variable names will be expanded. See string parsing for details.
Another way to delimit strings is by using heredoc syntax ("<<<"). One should provide an identifier (followed by new line) after <<<, then the string, and then the same identifier to close the quotation.
The closing identifier must begin in the first column of the line. Also, the identifier used must follow the same naming rules as any other label in PHP: it must contain only alphanumeric characters and underscores, and must start with a non-digit character or underscore.
| Warning | |
It is very important to note that the line with the closing identifier contains no other characters, except possibly a semicolon (;). That means especially that the identifier may not be indented, and there may not be any spaces or tabs after or before the semicolon. It's also important to realize that the first character before the closing identifier must be a newline as defined by your operating system. This is \r on Macintosh for example. Closing delimiter (possibly followed by a semicolon) must be followed by a newline too. If this rule is broken and the closing identifier is not "clean" then it's not considered to be a closing identifier and PHP will continue looking for one. If in this case a proper closing identifier is not found then a parse error will result with the line number being at the end of the script. It is not allowed to use heredoc syntax in initializing class members. Use other string syntaxes instead. |
Heredoc text behaves just like a double-quoted string, without the double-quotes. This means that you do not need to escape quotes in your here docs, but you can still use the escape codes listed above. Variables are expanded, but the same care must be taken when expressing complex variables inside a heredoc as with strings.
Example 11-4. Heredoc string quoting example
|
Note: Heredoc support was added in PHP 4.
When a string is specified in double quotes or with heredoc, variables are parsed within it.
There are two types of syntax: a simple one and a complex one. The simple syntax is the most common and convenient. It provides a way to parse a variable, an array value, or an object property.
The complex syntax was introduced in PHP 4, and can be recognised by the curly braces surrounding the expression.
If a dollar sign ($) is encountered, the parser will greedily take as many tokens as possible to form a valid variable name. Enclose the variable name in curly braces if you want to explicitly specify the end of the name.
<?php
$beer = 'Heineken';
echo "$beer's taste is great"; // works, "'" is an invalid character for varnames
echo "He drank some $beers"; // won't work, 's' is a valid character for varnames
echo "He drank some ${beer}s"; // works
echo "He drank some {$beer}s"; // works
?> |
Similarly, you can also have an array index or an object property parsed. With array indices, the closing square bracket (]) marks the end of the index. For object properties the same rules apply as to simple variables, though with object properties there doesn't exist a trick like the one with variables.
<?php
// These examples are specific to using arrays inside of strings.
// When outside of a string, always quote your array string keys
// and do not use {braces} when outside of strings either.
// Let's show all errors
error_reporting(E_ALL);
$fruits = array('strawberry' => 'red', 'banana' => 'yellow');
// Works but note that this works differently outside string-quotes
echo "A banana is $fruits[banana].";
// Works
echo "A banana is {$fruits['banana']}.";
// Works but PHP looks for a constant named banana first
// as described below.
echo "A banana is {$fruits[banana]}.";
// Won't work, use braces. This results in a parse error.
echo "A banana is $fruits['banana'].";
// Works
echo "A banana is " . $fruits['banana'] . ".";
// Works
echo "This square is $square->width meters broad.";
// Won't work. For a solution, see the complex syntax.
echo "This square is $square->width00 centimeters broad.";
?> |
For anything more complex, you should use the complex syntax.
This isn't called complex because the syntax is complex, but because you can include complex expressions this way.
In fact, you can include any value that is in the namespace in strings with this syntax. You simply write the expression the same way as you would outside the string, and then include it in { and }. Since you can't escape '{', this syntax will only be recognised when the $ is immediately following the {. (Use "{\$" to get a literal "{$"). Some examples to make it clear:
<?php
// Let's show all errors
error_reporting(E_ALL);
$great = 'fantastic';
// Won't work, outputs: This is { fantastic}
echo "This is { $great}";
// Works, outputs: This is fantastic
echo "This is {$great}";
echo "This is ${great}";
// Works
echo "This square is {$square->width}00 centimeters broad.";
// Works
echo "This works: {$arr[4][3]}";
// This is wrong for the same reason as $foo[bar] is wrong
// outside a string. In other words, it will still work but
// because PHP first looks for a constant named foo, it will
// throw an error of level E_NOTICE (undefined constant).
echo "This is wrong: {$arr[foo][3]}";
// Works. When using multi-dimensional arrays, always use
// braces around arrays when inside of strings
echo "This works: {$arr['foo'][3]}";
// Works.
echo "This works: " . $arr['foo'][3];
echo "You can even write {$obj->values[3]->name}";
echo "This is the value of the var named $name: {${$name}}";
?> |
Note: Functions and method calls work since PHP 5.
Note: Parsing variables within strings uses more memory than string concatenation. When writing a PHP script in which memory usage is a concern, consider using the concatenation operator (.) rather than variable parsing.
Characters within strings may be accessed and modified by specifying the
zero-based offset of the desired character after the string
using square array-brackets like $str[42] so think of
a string as an array of characters.
Note: They may also be accessed using braces like
$str{42}for the same purpose. However, using square array-brackets is preferred because the {braces} style is deprecated as of PHP 6.
Example 11-5. Some string examples
|
Strings may be concatenated using the '.' (dot) operator. Note that the '+' (addition) operator will not work for this. Please see String operators for more information.
There are a lot of useful functions for string modification.
See the string functions section for general functions, the regular expression functions for advanced find&replacing (in two tastes: Perl and POSIX extended).
There are also functions for URL-strings, and functions to encrypt/decrypt strings (mcrypt and mhash).
Finally, if you still didn't find what you're looking for, see also the character type functions.
You can convert a value to a string using the (string) cast, or the strval() function. String conversion is automatically done in the scope of an expression for you where a string is needed. This happens when you use the echo() or print() functions, or when you compare a variable value to a string. Reading the manual sections on Types and Type Juggling will make the following clearer. See also settype().
A boolean TRUE value is converted to the string "1", the FALSE value is represented as "" (empty string). This way you can convert back and forth between boolean and string values.
An integer or a floating point number (float) is converted to a string representing the number with its digits (including the exponent part for floating point numbers).
Note: The decimal point character is defined in the script's locale (category LC_NUMERIC). See setlocale().
Arrays are always converted to the string "Array", so you cannot dump out the contents of an array with echo() or print() to see what is inside them. To view one element, you'd do something like echo $arr['foo']. See below for tips on dumping/viewing the entire contents.
Objects are always converted to the string "Object". If you would like to print out the member variable values of an object for debugging reasons, read the paragraphs below. If you would like to find out the class name of which an object is an instance of, use get_class(). As of PHP 5, __toString() method is used if applicable.
Resources are always converted to strings with the structure "Resource id #1" where 1 is the unique number of the resource assigned by PHP during runtime. If you would like to get the type of the resource, use get_resource_type().
NULL is always converted to an empty string.
As you can see above, printing out the arrays, objects or resources does not provide you any useful information about the values themselves. Look at the functions print_r() and var_dump() for better ways to print out values for debugging.
You can also convert PHP values to strings to store them permanently. This method is called serialization, and can be done with the function serialize(). You can also serialize PHP values to XML structures, if you have WDDX support in your PHP setup.
When a string is evaluated as a numeric value, the resulting value and type are determined as follows.
The string will evaluate as a float if it contains any of the characters '.', 'e', or 'E'. Otherwise, it will evaluate as an integer.
The value is given by the initial portion of the string. If the string starts with valid numeric data, this will be the value used. Otherwise, the value will be 0 (zero). Valid numeric data is an optional sign, followed by one or more digits (optionally containing a decimal point), followed by an optional exponent. The exponent is an 'e' or 'E' followed by one or more digits.
<?php $foo = 1 + "10.5"; // $foo is float (11.5) $foo = 1 + "-1.3e3"; // $foo is float (-1299) $foo = 1 + "bob-1.3e3"; // $foo is integer (1) $foo = 1 + "bob3"; // $foo is integer (1) $foo = 1 + "10 Small Pigs"; // $foo is integer (11) $foo = 4 + "10.2 Little Piggies"; // $foo is float (14.2) $foo = "10.0 pigs " + 1; // $foo is float (11) $foo = "10.0 pigs " + 1.0; // $foo is float (11) ?> |
For more information on this conversion, see the Unix manual page for strtod(3).
If you would like to test any of the examples in this section, you can cut and paste the examples and insert the following line to see for yourself what's going on:
Do not expect to get the code of one character by converting it to integer (as you would do in C for example). Use the functions ord() and chr() to convert between charcodes and characters.
An array in PHP is actually an ordered map. A map is a type that maps values to keys. This type is optimized in several ways, so you can use it as a real array, or a list (vector), hashtable (which is an implementation of a map), dictionary, collection, stack, queue and probably more. Because you can have another PHP array as a value, you can also quite easily simulate trees.
Explanation of those data structures is beyond the scope of this manual, but you'll find at least one example for each of them. For more information we refer you to external literature about this broad topic.
An array can be created by the array() language-construct. It takes a certain number of comma-separated key => value pairs.
array( [key =>] value
, ...
)
// key may be an integer or string
// value may be any value |
A key may be either an
integer or a string. If a key is
the standard representation of an integer, it will
be interpreted as such (i.e. "8" will be
interpreted as 8, while
"08" will be interpreted as
"08").
Floats in key are truncated to integer.
There are no different indexed and
associative array types in PHP; there is only one array type,
which can both contain integer and string indices.
A value can be of any PHP type.
<?php
$arr = array("somearray" => array(6 => 5, 13 => 9, "a" => 42));
echo $arr["somearray"][6]; // 5
echo $arr["somearray"][13]; // 9
echo $arr["somearray"]["a"]; // 42
?> |
If you do not specify a key for a given value, then the maximum of the integer indices is taken, and the new key will be that maximum value + 1. If you specify a key that already has a value assigned to it, that value will be overwritten.
<?php // This array is the same as ... array(5 => 43, 32, 56, "b" => 12); // ...this array array(5 => 43, 6 => 32, 7 => 56, "b" => 12); ?> |
| Warning |
As of PHP 4.3.0, the index generation behaviour described above has changed. Now, if you append to an array in which the current maximum key is negative, then the next key created will be zero (0). Before, the new index would have been set to the largest existing key + 1, the same as positive indices are. |
Using TRUE as a key will evaluate to integer 1 as key. Using FALSE as a key will evaluate to integer 0 as key. Using NULL as a key will evaluate to the empty string. Using the empty string as key will create (or overwrite) a key with the empty string and its value; it is not the same as using empty brackets.
You cannot use arrays or objects as keys. Doing so will result in a warning: Illegal offset type.
You can also modify an existing array by explicitly setting values in it.
This is done by assigning values to the array while specifying the key in brackets. You can also omit the key, add an empty pair of brackets ("[]") to the variable name in that case.
$arr[key] = value; $arr[] = value; // key may be an integer or string // value may be any value |
$arr doesn't exist yet, it will be created.
So this is also an alternative way to specify an array.
To change a certain value, just assign a new value
to an element specified with its key. If you want to
remove a key/value pair, you need to unset() it.
<?php
$arr = array(5 => 1, 12 => 2);
$arr[] = 56; // This is the same as $arr[13] = 56;
// at this point of the script
$arr["x"] = 42; // This adds a new element to
// the array with key "x"
unset($arr[5]); // This removes the element from the array
unset($arr); // This deletes the whole array
?> |
Note: As mentioned above, if you provide the brackets with no key specified, then the maximum of the existing integer indices is taken, and the new key will be that maximum value + 1 . If no integer indices exist yet, the key will be 0 (zero). If you specify a key that already has a value assigned to it, that value will be overwritten.
Warning As of PHP 4.3.0, the index generation behaviour described above has changed. Now, if you append to an array in which the current maximum key is negative, then the next key created will be zero (0). Before, the new index would have been set to the largest existing key + 1, the same as positive indices are.
Note that the maximum integer key used for this need not currently exist in the array. It simply must have existed in the array at some time since the last time the array was re-indexed. The following example illustrates:
<?php // Create a simple array. $array = array(1, 2, 3, 4, 5); print_r($array); // Now delete every item, but leave the array itself intact: foreach ($array as $i => $value) { unset($array[$i]); } print_r($array); // Append an item (note that the new key is 5, instead of 0 as you // might expect). $array[] = 6; print_r($array); // Re-index: $array = array_values($array); $array[] = 7; print_r($array); ?>The above example will output:
Array ( [0] => 1 [1] => 2 [2] => 3 [3] => 4 [4] => 5 ) Array ( ) Array ( [5] => 6 ) Array ( [0] => 6 [1] => 7 )
There are quite a few useful functions for working with arrays. See the array functions section.
Note: The unset() function allows unsetting keys of an array. Be aware that the array will NOT be reindexed. If you only use "usual integer indices" (starting from zero, increasing by one), you can achieve the reindex effect by using array_values().
The foreach control structure exists specifically for arrays. It provides an easy way to traverse an array.
You should always use quotes around a string literal array index. For example, use $foo['bar'] and not $foo[bar]. But why is $foo[bar] wrong? You might have seen the following syntax in old scripts:
This is wrong, but it works. Then, why is it wrong? The reason is that this code has an undefined constant (bar) rather than a string ('bar' - notice the quotes), and PHP may in future define constants which, unfortunately for your code, have the same name. It works because PHP automatically converts a bare string (an unquoted string which does not correspond to any known symbol) into a string which contains the bare string. For instance, if there is no defined constant named bar, then PHP will substitute in the string 'bar' and use that.Note: This does not mean to always quote the key. You do not want to quote keys which are constants or variables, as this will prevent PHP from interpreting them.
<?php error_reporting(E_ALL); ini_set('display_errors', true); ini_set('html_errors', false); // Simple array: $array = array(1, 2); $count = count($array); for ($i = 0; $i < $count; $i++) { echo "\nChecking $i: \n"; echo "Bad: " . $array['$i'] . "\n"; echo "Good: " . $array[$i] . "\n"; echo "Bad: {$array['$i']}\n"; echo "Good: {$array[$i]}\n"; } ?>Note: The above example will output:
More examples to demonstrate this fact:
<?php
// Let's show all errors
error_reporting(E_ALL);
$arr = array('fruit' => 'apple', 'veggie' => 'carrot');
// Correct
print $arr['fruit']; // apple
print $arr['veggie']; // carrot
// Incorrect. This works but also throws a PHP error of
// level E_NOTICE because of an undefined constant named fruit
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print $arr[fruit]; // apple
// Let's define a constant to demonstrate what's going on. We
// will assign value 'veggie' to a constant named fruit.
define('fruit', 'veggie');
// Notice the difference now
print $arr['fruit']; // apple
print $arr[fruit]; // carrot
// The following is okay as it's inside a string. Constants are not
// looked for within strings so no E_NOTICE error here
print "Hello $arr[fruit]"; // Hello apple
// With one exception, braces surrounding arrays within strings
// allows constants to be looked for
print "Hello {$arr[fruit]}"; // Hello carrot
print "Hello {$arr['fruit']}"; // Hello apple
// This will not work, results in a parse error such as:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// This of course applies to using superglobals in strings as well
print "Hello $arr['fruit']";
print "Hello $_GET['foo']";
// Concatenation is another option
print "Hello " . $arr['fruit']; // Hello apple
?> |
When you turn error_reporting() up to show E_NOTICE level errors (such as setting it to E_ALL) then you will see these errors. By default, error_reporting is turned down to not show them.
As stated in the syntax section, there must be an expression between the square brackets ('[' and ']'). That means that you can write things like this:
This is an example of using a function return value as the array index. PHP also knows about constants, as you may have seen the E_* ones before.<?php $error_descriptions[E_ERROR] = "A fatal error has occured"; $error_descriptions[E_WARNING] = "PHP issued a warning"; $error_descriptions[E_NOTICE] = "This is just an informal notice"; ?> |
<?php $error_descriptions[1] = "A fatal error has occured"; $error_descriptions[2] = "PHP issued a warning"; $error_descriptions[8] = "This is just an informal notice"; ?> |
As we already explained in the above examples, $foo[bar] still works but is wrong. It works, because bar is due to its syntax expected to be a constant expression. However, in this case no constant with the name bar exists. PHP now assumes that you meant bar literally, as the string "bar", but that you forgot to write the quotes.
At some point in the future, the PHP team might want to add another constant or keyword, or you may introduce another constant into your application, and then you get in trouble. For example, you already cannot use the words empty and default this way, since they are special reserved keywords.
Note: To reiterate, inside a double-quoted string, it's valid to not surround array indexes with quotes so "$foo[bar]" is valid. See the above examples for details on why as well as the section on variable parsing in strings.
For any of the types: integer, float, string, boolean and resource, if you convert a value to an array, you get an array with one element (with index 0), which is the scalar value you started with.
If you convert an object to an array, you get the properties (member variables) of that object as the array's elements. The keys are the member variable names with a few notable exceptions: private variables have the class name prepended to the variable name; protected variables have a '*' prepended to the variable name. These prepended values have null bytes on either side. This can result in some unexpected behaviour.
<?php
class A {
private $A; // This will become '\0A\0A'
}
class B extends A {
private $A; // This will become '\0B\0A'
public $AA; // This will become 'AA'
}
var_dump((array) new B());
?> |
If you convert a NULL value to an array, you get an empty array.
The array type in PHP is very versatile, so here will be some examples to show you the full power of arrays.
<?php
// this
$a = array( 'color' => 'red',
'taste' => 'sweet',
'shape' => 'round',
'name' => 'apple',
4 // key will be 0
);
// is completely equivalent with
$a['color'] = 'red';
$a['taste'] = 'sweet';
$a['shape'] = 'round';
$a['name'] = 'apple';
$a[] = 4; // key will be 0
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';
// will result in the array array(0 => 'a' , 1 => 'b' , 2 => 'c'),
// or simply array('a', 'b', 'c')
?> |
Example 11-6. Using array()
|
Changing values of the array directly is possible since PHP 5 by passing them as reference. Prior versions need workaround:
Example 11-8. Collection
The above example will output:
|
This example creates a one-based array.
Arrays are ordered. You can also change the order using various sorting functions. See the array functions section for more information. You can count the number of items in an array using the count() function.
Because the value of an array can be anything, it can also be another array. This way you can make recursive and multi-dimensional arrays.
Example 11-12. Recursive and multi-dimensional arrays
|
You should be aware that array assignment always involves value copying. It also means that the internal array pointer used by current() and similar functions is reset. You need to use the reference operator to copy an array by reference.
To initialize an object, you use the new statement to instantiate the object to a variable.
For a full discussion, please read the section Classes and Objects.
If an object is converted to an object, it is not modified. If a value of any other type is converted to an object, a new instance of the stdClass built in class is created. If the value was NULL, the new instance will be empty. Array converts to an object with properties named by array keys and with corresponding values. For any other value, a member variable named scalar will contain the value.
A resource is a special variable, holding a reference to an external resource. Resources are created and used by special functions. See the appendix for a listing of all these functions and the corresponding resource types.
Note: The resource type was introduced in PHP 4
See also get_resource_type().
As resource types hold special handlers to opened files, database connections, image canvas areas and the like, you cannot convert any value to a resource.
Due to the reference-counting system introduced with PHP 4's Zend Engine, it is automatically detected when a resource is no longer referred to (just like Java). When this is the case, all resources that were in use for this resource are made free by the garbage collector. For this reason, it is rarely ever necessary to free the memory manually by using some free_result function.
Note: Persistent database links are special, they are not destroyed by the garbage collector. See also the section about persistent connections.
The special NULL value represents that a variable has no value. NULL is the only possible value of type NULL.
Note: The null type was introduced in PHP 4.
A variable is considered to be NULL if
it has been assigned the constant NULL.
it has not been set to any value yet.
it has been unset().
mixed indicates that a parameter may accept multiple (but not necessarily all) types.
gettype() for example will accept all PHP types, while str_replace() will accept strings and arrays.
Some functions like call_user_func() or usort() accept user defined callback functions as a parameter. Callback functions can not only be simple functions but also object methods including static class methods.
A PHP function is simply passed by its name as a string. You can pass any built-in or user defined function with the exception of array(), echo(), empty(), eval(), exit(), isset(), list(), print() and unset().
A method of an instantiated object is passed as an array containing an object as the element with index 0 and a method name as the element with index 1.
Static class methods can also be passed without instantiating an object of that class by passing the class name instead of an object as the element with index 0.
Apart from common user-defined function, create_function() can be used to create an anonymous callback function.
Example 11-13. Callback function examples
|
Note: In PHP4, you will have to use a reference to create a callback that points to the actual object, and not a copy of it. For more details, see References Explained.
void in return type means that the return value is useless. void in parameters list means that the function doesn't accept any parameters.
PHP does not require (or support) explicit type definition in
variable declaration; a variable's type is determined by the
context in which that variable is used. That is to say, if you
assign a string value to variable $var,
$var becomes a string. If you then assign an
integer value to $var, it becomes an
integer.
An example of PHP's automatic type conversion is the addition operator '+'. If any of the operands is a float, then all operands are evaluated as floats, and the result will be a float. Otherwise, the operands will be interpreted as integers, and the result will also be an integer. Note that this does NOT change the types of the operands themselves; the only change is in how the operands are evaluated.
<?php $foo = "0"; // $foo is string (ASCII 48) $foo += 2; // $foo is now an integer (2) $foo = $foo + 1.3; // $foo is now a float (3.3) $foo = 5 + "10 Little Piggies"; // $foo is integer (15) $foo = 5 + "10 Small Pigs"; // $foo is integer (15) ?> |
If the last two examples above seem odd, see String conversion to numbers.
If you wish to force a variable to be evaluated as a certain type, see the section on Type casting. If you wish to change the type of a variable, see settype().
If you would like to test any of the examples in this section, you can use the var_dump() function.
Note: The behaviour of an automatic conversion to array is currently undefined.
Also, because PHP supports indexing into strings via offsets using the same syntax as array indexing, the following example holds true for all PHP versions:
See the section titled String access by character for more information.
Type casting in PHP works much as it does in C: the name of the desired type is written in parentheses before the variable which is to be cast.
The casts allowed are:
(int), (integer) - cast to integer
(bool), (boolean) - cast to boolean
(float), (double), (real) - cast to float
(string) - cast to string
(binary) - cast to binary string (PHP 6)
(array) - cast to array
(object) - cast to object
(binary) casting and b prefix forward support was added in PHP 5.2.1
Note that tabs and spaces are allowed inside the parentheses, so the following are functionally equivalent:
<?php $foo = (int) $bar; $foo = ( int ) $bar; ?> |
Casting a literal strings and variables to binary strings:
<?php $binary = (binary)$string; $binary = b"binary string"; ?> |
Note: Instead of casting a variable to string, you can also enclose the variable in double quotes.
It may not be obvious exactly what will happen when casting between certain types. For more info, see these sections:
Variables in PHP are represented by a dollar sign followed by the name of the variable. The variable name is case-sensitive.
Variable names follow the same rules as other labels in PHP. A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
Note: For our purposes here, a letter is a-z, A-Z, and the ASCII characters from 127 through 255 (0x7f-0xff).
Tip: You may also want to take a look at the Appendix T.
For information on variable related functions, see the Variable Functions Reference.
<?php $var = 'Bob'; $Var = 'Joe'; echo "$var, $Var"; // outputs "Bob, Joe" $4site = 'not yet'; // invalid; starts with a number $_4site = 'not yet'; // valid; starts with an underscore $täyte = 'mansikka'; // valid; 'ä' is (Extended) ASCII 228. ?> |
In PHP 3, variables are always assigned by value. That is to say, when you assign an expression to a variable, the entire value of the original expression is copied into the destination variable. This means, for instance, that after assigning one variable's value to another, changing one of those variables will have no effect on the other. For more information on this kind of assignment, see the chapter on Expressions.
As of PHP 4, PHP offers another way to assign values to variables: assign by reference. This means that the new variable simply references (in other words, "becomes an alias for" or "points to") the original variable. Changes to the new variable affect the original, and vice versa.
To assign by reference, simply prepend an ampersand (&) to the beginning of the variable which is being assigned (the source variable). For instance, the following code snippet outputs 'My name is Bob' twice:
<?php $foo = 'Bob'; // Assign the value 'Bob' to $foo $bar = &$foo; // Reference $foo via $bar. $bar = "My name is $bar"; // Alter $bar... echo $bar; echo $foo; // $foo is altered too. ?> |
One important thing to note is that only named variables may be assigned by reference.
<?php
$foo = 25;
$bar = &$foo; // This is a valid assignment.
$bar = &(24 * 7); // Invalid; references an unnamed expression.
function test()
{
return 25;
}
$bar = &test(); // Invalid.
?> |
It is not necessary to initialize variables in PHP however it is a very good practice. Uninitialized variables have a default value of their type - FALSE, zero, empty string or an empty array.
Relying on the default value of an uninitialized variable is problematic in the case of including one file into another which uses the same variable name. It is also a major security risk with register_globals turned on. E_NOTICE level error is issued in case of working with uninitialized variables, however not in the case of appending elements to the uninitialized array. isset() language construct can be used to detect if a variable has been already initialized.
PHP provides a large number of predefined variables to any script which it runs. Many of these variables, however, cannot be fully documented as they are dependent upon which server is running, the version and setup of the server, and other factors. Some of these variables will not be available when PHP is run on the command line. For a listing of these variables, please see the section on Reserved Predefined Variables.
| Warning |
In PHP 4.2.0 and later, the default value for the PHP directive register_globals is
off. This is a major change in PHP. Having
register_globals off affects the set of predefined
variables available in the global scope. For example, to get
For related information on this change, read the configuration entry for register_globals, the security chapter on Using Register Globals , as well as the PHP 4.1.0 and 4.2.0 Release Announcements. Using the available PHP Reserved Predefined Variables, like the superglobal arrays, is preferred. |
From version 4.1.0 onward, PHP provides an additional set of predefined arrays
containing variables from the web server (if applicable), the
environment, and user input. These new arrays are rather special
in that they are automatically global--i.e., automatically
available in every scope. For this reason, they are often known as
"superglobals". (There is no mechanism in PHP for
user-defined superglobals.) The superglobals are listed below;
however, for a listing of their contents and further discussion on
PHP predefined variables and their natures, please see the section
Reserved Predefined Variables.
Also, you'll notice how the older predefined variables
($HTTP_*_VARS) still exist.
As of PHP 5.0.0, the long PHP
predefined variable
arrays may be disabled with the
register_long_arrays
directive.
Variable variables: Superglobals cannot be used as variable variables inside functions or class methods.
Note: Even though both the superglobal and HTTP_*_VARS can exist at the same time; they are not identical, so modifying one will not change the other.
If certain variables in variables_order are not set, their appropriate PHP predefined arrays are also left empty.
PHP Superglobals
Contains a reference to every variable which is currently
available within the global scope of the script. The keys of
this array are the names of the global variables.
$GLOBALS has existed since PHP 3.
Variables set by the web server or otherwise directly related
to the execution environment of the current script. Analogous
to the old $HTTP_SERVER_VARS array (which is
still available, but deprecated).
Variables provided to the script via URL query string. Analogous to the
old $HTTP_GET_VARS array (which is still
available, but deprecated).
Variables provided to the script via HTTP POST. Analogous to the
old $HTTP_POST_VARS array (which is still
available, but deprecated).
Variables provided to the script via HTTP cookies. Analogous to
the old $HTTP_COOKIE_VARS array (which is
still available, but deprecated).
Variables provided to the script via HTTP post file
uploads. Analogous to the old
$HTTP_POST_FILES array (which is still
available, but deprecated). See POST method
uploads for more information.
Variables provided to the script via the environment. Analogous
to the old $HTTP_ENV_VARS array (which is
still available, but deprecated).
Variables provided to the script via the GET, POST, and COOKIE input mechanisms, and which therefore cannot be trusted. The presence and order of variable inclusion in this array is defined according to the PHP variables_order configuration directive. This array has no direct analogue in versions of PHP prior to 4.1.0. See also import_request_variables().
| Caution |
Since PHP 4.3.0, FILE information from |
Note: When running on the command line , this will not include the
argvandargcentries; these are present in the$_SERVERarray.
Variables which are currently registered to a script's
session. Analogous to the old
$HTTP_SESSION_VARS array (which is still
available, but deprecated). See the Session handling functions section
for more information.
The scope of a variable is the context within which it is defined. For the most part all PHP variables only have a single scope. This single scope spans included and required files as well. For example:
Here the $a variable will be available within
the included b.inc script. However, within
user-defined functions a local function scope is introduced. Any
variable used inside a function is by default limited to the local
function scope. For example:
<?php
$a = 1; /* global scope */
function Test()
{
echo $a; /* reference to local scope variable */
}
Test();
?> |
This script will not produce any output because the echo statement
refers to a local version of the $a variable,
and it has not been assigned a value within this scope. You may
notice that this is a little bit different from the C language in
that global variables in C are automatically available to
functions unless specifically overridden by a local definition.
This can cause some problems in that people may inadvertently
change a global variable. In PHP global variables must be
declared global inside a function if they are going to be used in
that function.
First, an example use of global:
The above script will output "3". By declaring
$a and $b global within the
function, all references to either variable will refer to the
global version. There is no limit to the number of global
variables that can be manipulated by a function.
A second way to access variables from the global scope is to use
the special PHP-defined $GLOBALS array. The
previous example can be rewritten as:
The $GLOBALS array is an associative array with
the name of the global variable being the key and the contents of
that variable being the value of the array element.
Notice how $GLOBALS exists in any scope, this
is because $GLOBALS is a superglobal.
Here's an example demonstrating the power of superglobals:
Example 12-4. Example demonstrating superglobals and scope
|
Another important feature of variable scoping is the static variable. A static variable exists only in a local function scope, but it does not lose its value when program execution leaves this scope. Consider the following example:
This function is quite useless since every time it is called it
sets $a to 0 and prints
"0". The $a++ which increments the
variable serves no purpose since as soon as the function exits the
$a variable disappears. To make a useful
counting function which will not lose track of the current count,
the $a variable is declared static:
Now, every time the Test() function is called it will print the
value of $a and increment it.
Static variables also provide one way to deal with recursive
functions. A recursive function is one which calls itself. Care
must be taken when writing a recursive function because it is
possible to make it recurse indefinitely. You must make sure you
have an adequate way of terminating the recursion. The following
simple function recursively counts to 10, using the static
variable $count to know when to stop:
Note: Static variables may be declared as seen in the examples above. Trying to assign values to these variables which are the result of expressions will cause a parse error.
The Zend Engine 1, driving PHP 4, implements the static and global modifier for variables in terms of references. For example, a true global variable imported inside a function scope with the global statement actually creates a reference to the global variable. This can lead to unexpected behaviour which the following example addresses:
<?php
function test_global_ref() {
global $obj;
$obj = &new stdclass;
}
function test_global_noref() {
global $obj;
$obj = new stdclass;
}
test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?> |
Executing this example will result in the following output:
NULL
object(stdClass)(0) {
} |
A similar behaviour applies to the static statement. References are not stored statically:
<?php
function &get_instance_ref() {
static $obj;
echo 'Static object: ';
var_dump($obj);
if (!isset($obj)) {
// Assign a reference to the static variable
$obj = &new stdclass;
}
$obj->property++;
return $obj;
}
function &get_instance_noref() {
static $obj;
echo 'Static object: ';
var_dump($obj);
if (!isset($obj)) {
// Assign the object to the static variable
$obj = new stdclass;
}
$obj->property++;
return $obj;
}
$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?> |
Executing this example will result in the following output:
Static object: NULL
Static object: NULL
Static object: NULL
Static object: object(stdClass)(1) {
["property"]=>
int(1)
} |
This example demonstrates that when assigning a reference to a static variable, it's not remembered when you call the &get_instance_ref() function a second time.
Sometimes it is convenient to be able to have variable variable names. That is, a variable name which can be set and used dynamically. A normal variable is set with a statement such as:
A variable variable takes the value of a variable and treats that as the name of a variable. In the above example, hello, can be used as the name of a variable by using two dollar signs. i.e.
At this point two variables have been defined and stored in the
PHP symbol tree: $a with contents "hello" and
$hello with contents "world". Therefore, this
statement:
produces the exact same output as:
i.e. they both produce: hello world.
In order to use variable variables with arrays, you have to
resolve an ambiguity problem. That is, if you write
$$a[1] then the parser needs to know if you
meant to use $a[1] as a variable, or if you
wanted $$a as the variable and then the [1]
index from that variable. The syntax for resolving this ambiguity
is: ${$a[1]} for the first case and
${$a}[1] for the second.
| Warning |
Please note that variable variables cannot be used with PHP's Superglobal arrays within functions or class methods. |
When a form is submitted to a PHP script, the information from that form is automatically made available to the script. There are many ways to access this information, for example:
Depending on your particular setup and personal preferences, there are many ways to access data from your HTML forms. Some examples are:
Example 12-10. Accessing data from a simple POST HTML form
|
Using a GET form is similar except you'll use the appropriate
GET predefined variable instead. GET also applies to the
QUERY_STRING (the information after the '?' in a URL). So,
for example, http://www.example.com/test.php?id=3
contains GET data which is accessible with $_GET['id'].
See also $_REQUEST and
import_request_variables().
Note: Superglobal arrays, like
$_POSTand$_GET, became available in PHP 4.1.0
As shown, before PHP 4.2.0 the default value for register_globals was on. And, in PHP 3 it was always on. The PHP community is encouraging all to not rely on this directive as it's preferred to assume it's off and code accordingly.
Note: The magic_quotes_gpc configuration directive affects Get, Post and Cookie values. If turned on, value (It's "PHP!") will automagically become (It\'s \"PHP!\"). Escaping is needed for DB insertion. See also addslashes(), stripslashes() and magic_quotes_sybase.
PHP also understands arrays in the context of form variables (see the related faq). You may, for example, group related variables together, or use this feature to retrieve values from a multiple select input. For example, let's post a form to itself and upon submission display the data:
Example 12-11. More complex form variables
|
In PHP 3, the array form variable usage is limited to single-dimensional arrays. As of PHP 4, no such restriction applies.
When submitting a form, it is possible to use an image instead of the standard submit button with a tag like:
When the user clicks somewhere on the image, the accompanying form will be transmitted to the server with two additional variables, sub_x and sub_y. These contain the coordinates of the user click within the image. The experienced may note that the actual variable names sent by the browser contains a period rather than an underscore, but PHP converts the period to an underscore automatically.
PHP transparently supports HTTP cookies as defined by Netscape's Spec. Cookies are a
mechanism for storing data in the remote browser and thus
tracking or identifying return users. You can set cookies using
the setcookie() function. Cookies are part of
the HTTP header, so the SetCookie function must be called before
any output is sent to the browser. This is the same restriction
as for the header() function. Cookie data
is then available in the appropriate cookie data arrays, such
as $_COOKIE, $HTTP_COOKIE_VARS
as well as in $_REQUEST. See the
setcookie() manual page for more details and
examples.
If you wish to assign multiple values to a single cookie variable, you may assign it as an array. For example:
<?php
setcookie("MyCookie[foo]", 'Testing 1', time()+3600);
setcookie("MyCookie[bar]", 'Testing 2', time()+3600);
?> |
That will create two separate cookies although MyCookie will now be a single array in your script. If you want to set just one cookie with multiple values, consider using serialize() or explode() on the value first.
Note that a cookie will replace a previous cookie by the same name in your browser unless the path or domain is different. So, for a shopping cart application you may want to keep a counter and pass this along. i.e.
Example 12-12. A setcookie() example
|
Typically, PHP does not alter the names of variables when they are passed into a script. However, it should be noted that the dot (period, full stop) is not a valid character in a PHP variable name. For the reason, look at it:
<?php $varname.ext; /* invalid variable name */ ?> |
$varname, followed by the string concatenation
operator, followed by the barestring (i.e. unquoted string which
doesn't match any known key or reserved words) 'ext'. Obviously,
this doesn't have the intended result.
For this reason, it is important to note that PHP will automatically replace any dots in incoming variable names with underscores.
Because PHP determines the types of variables and converts them (generally) as needed, it is not always obvious what type a given variable is at any one time. PHP includes several functions which find out what type a variable is, such as: gettype(), is_array(), is_float(), is_int(), is_object(), and is_string(). See also the chapter on Types.
A constant is an identifier (name) for a simple value. As the name suggests, that value cannot change during the execution of the script (except for magic constants, which aren't actually constants). A constant is case-sensitive by default. By convention, constant identifiers are always uppercase.
The name of a constant follows the same rules as any label in PHP. A valid constant name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thusly: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*
Tip: You may also want to take a look at the Appendix T.
Example 13-1. Valid and invalid constant names
|
Note: For our purposes here, a letter is a-z, A-Z, and the ASCII characters from 127 through 255 (0x7f-0xff).
Like superglobals, the scope of a constant is global. You can access constants anywhere in your script without regard to scope. For more information on scope, read the manual section on variable scope.
You can define a constant by using the define()-function. Once a constant is defined, it can never be changed or undefined.
Only scalar data (boolean, integer, float and string) can be contained in constants. Do not define resource constants.
You can get the value of a constant by simply specifying its name. Unlike with variables, you should not prepend a constant with a $. You can also use the function constant() to read a constant's value if you wish to obtain the constant's name dynamically. Use get_defined_constants() to get a list of all defined constants.
Note: Constants and (global) variables are in a different namespace. This implies that for example TRUE and
$TRUEare generally different.
If you use an undefined constant, PHP assumes that you mean the name of the constant itself, just as if you called it as a string (CONSTANT vs "CONSTANT"). An error of level E_NOTICE will be issued when this happens. See also the manual entry on why $foo[bar] is wrong (unless you first define() bar as a constant). If you simply want to check if a constant is set, use the defined() function.
These are the differences between constants and variables:
Constants do not have a dollar sign ($) before them;
Constants may only be defined using the define() function, not by simple assignment;
Constants may be defined and accessed anywhere without regard to variable scoping rules;
Constants may not be redefined or undefined once they have been set; and
Constants may only evaluate to scalar values.
See also Class Constants.
PHP provides a large number of predefined constants to any script which it runs. Many of these constants, however, are created by various extensions, and will only be present when those extensions are available, either via dynamic loading or because they have been compiled in.
There are five magical constants that change depending on where they are used. For example, the value of __LINE__ depends on the line that it's used on in your script. These special constants are case-insensitive and are as follows:
Table 13-1. A few "magical" PHP constants
| Name | Description |
|---|---|
| __LINE__ | The current line number of the file. |
| __FILE__ | The full path and filename of the file. If used inside an include, the name of the included file is returned. Since PHP 4.0.2, __FILE__ always contains an absolute path whereas in older versions it contained relative path under some circumstances. |
| __FUNCTION__ | The function name. (Added in PHP 4.3.0) As of PHP 5 this constant returns the function name as it was declared (case-sensitive). In PHP 4 its value is always lowercased. |
| __CLASS__ | The class name. (Added in PHP 4.3.0) As of PHP 5 this constant returns the class name as it was declared (case-sensitive). In PHP 4 its value is always lowercased. |
| __METHOD__ | The class method name. (Added in PHP 5.0.0) The method name is returned as it was declared (case-sensitive). |
See also get_class(), get_object_vars(), file_exists() and function_exists().
Expressions are the most important building stones of PHP. In PHP, almost anything you write is an expression. The simplest yet most accurate way to define an expression is "anything that has a value".
The most basic forms of expressions are constants and variables. When you type "$a = 5", you're assigning '5' into $a. '5', obviously, has the value 5, or in other words '5' is an expression with the value of 5 (in this case, '5' is an integer constant).
After this assignment, you'd expect $a's value to be 5 as well, so if you wrote $b = $a, you'd expect it to behave just as if you wrote $b = 5. In other words, $a is an expression with the value of 5 as well. If everything works right, this is exactly what will happen.
Slightly more complex examples for expressions are functions. For instance, consider the following function:
Assuming you're familiar with the concept of functions (if you're not, take a look at the chapter about functions), you'd assume that typing $c = foo() is essentially just like writing $c = 5, and you're right. Functions are expressions with the value of their return value. Since foo() returns 5, the value of the expression 'foo()' is 5. Usually functions don't just return a static value but compute something.
Of course, values in PHP don't have to be integers, and very often they aren't. PHP supports four scalar value types: integer values, floating point values (float), string values and boolean values (scalar values are values that you can't 'break' into smaller pieces, unlike arrays, for instance). PHP also supports two composite (non-scalar) types: arrays and objects. Each of these value types can be assigned into variables or returned from functions.
PHP takes expressions much further, in the same way many other languages do. PHP is an expression-oriented language, in the sense that almost everything is an expression. Consider the example we've already dealt with, '$a = 5'. It's easy to see that there are two values involved here, the value of the integer constant '5', and the value of $a which is being updated to 5 as well. But the truth is that there's one additional value involved here, and that's the value of the assignment itself. The assignment itself evaluates to the assigned value, in this case 5. In practice, it means that '$a = 5', regardless of what it does, is an expression with the value 5. Thus, writing something like '$b = ($a = 5)' is like writing '$a = 5; $b = 5;' (a semicolon marks the end of a statement). Since assignments are parsed in a right to left order, you can also write '$b = $a = 5'.
Another good example of expression orientation is pre- and post-increment and decrement. Users of PHP and many other languages may be familiar with the notation of variable++ and variable--. These are increment and decrement operators. In PHP/FI 2, the statement '$a++' has no value (is not an expression), and thus you can't assign it or use it in any way. PHP enhances the increment/decrement capabilities by making these expressions as well, like in C. In PHP, like in C, there are two types of increment - pre-increment and post-increment. Both pre-increment and post-increment essentially increment the variable, and the effect on the variable is identical. The difference is with the value of the increment expression. Pre-increment, which is written '++$variable', evaluates to the incremented value (PHP increments the variable before reading its value, thus the name 'pre-increment'). Post-increment, which is written '$variable++' evaluates to the original value of $variable, before it was incremented (PHP increments the variable after reading its value, thus the name 'post-increment').
A very common type of expressions are comparison expressions. These expressions evaluate to either FALSE or TRUE. PHP supports > (bigger than), >= (bigger than or equal to), == (equal), != (not equal), < (smaller than) and <= (smaller than or equal to). The language also supports a set of strict equivalence operators: === (equal to and same type) and !== (not equal to or not same type). These expressions are most commonly used inside conditional execution, such as if statements.
The last example of expressions we'll deal with here is combined operator-assignment expressions. You already know that if you want to increment $a by 1, you can simply write '$a++' or '++$a'. But what if you want to add more than one to it, for instance 3? You could write '$a++' multiple times, but this is obviously not a very efficient or comfortable way. A much more common practice is to write '$a = $a + 3'. '$a + 3' evaluates to the value of $a plus 3, and is assigned back into $a, which results in incrementing $a by 3. In PHP, as in several other languages like C, you can write this in a shorter way, which with time would become clearer and quicker to understand as well. Adding 3 to the current value of $a can be written '$a += 3'. This means exactly "take the value of $a, add 3 to it, and assign it back into $a". In addition to being shorter and clearer, this also results in faster execution. The value of '$a += 3', like the value of a regular assignment, is the assigned value. Notice that it is NOT 3, but the combined value of $a plus 3 (this is the value that's assigned into $a). Any two-place operator can be used in this operator-assignment mode, for example '$a -= 5' (subtract 5 from the value of $a), '$b *= 7' (multiply the value of $b by 7), etc.
There is one more expression that may seem odd if you haven't seen it in other languages, the ternary conditional operator:
If the value of the first subexpression is TRUE (non-zero), then the second subexpression is evaluated, and that is the result of the conditional expression. Otherwise, the third subexpression is evaluated, and that is the value.
The following example should help you understand pre- and post-increment and expressions in general a bit better:
<?php
function double($i)
{
return $i*2;
}
$b = $a = 5; /* assign the value five into the variable $a and $b */
$c = $a++; /* post-increment, assign original value of $a
(5) to $c */
$e = $d = ++$b; /* pre-increment, assign the incremented value of
$b (6) to $d and $e */
/* at this point, both $d and $e are equal to 6 */
$f = double($d++); /* assign twice the value of $d before
the increment, 2*6 = 12 to $f */
$g = double(++$e); /* assign twice the value of $e after
the increment, 2*7 = 14 to $g */
$h = $g += 10; /* first, $g is incremented by 10 and ends with the
value of 24. the value of the assignment (24) is
then assigned into $h, and $h ends with the value
of 24 as well. */
?> |
Some expressions can be considered as statements. In this case, a statement has the form of 'expr' ';' that is, an expression followed by a semicolon. In '$b=$a=5;', $a=5 is a valid expression, but it's not a statement by itself. '$b=$a=5;' however is a valid statement.
One last thing worth mentioning is the truth value of expressions. In many events, mainly in conditional execution and loops, you're not interested in the specific value of the expression, but only care about whether it means TRUE or FALSE. The constants TRUE and FALSE (case-insensitive) are the two possible boolean values. When necessary, an expression is automatically converted to boolean. See the section about type-casting for details about how.
PHP provides a full and powerful implementation of expressions, and
documenting it entirely goes beyond the scope of this manual. The
above examples should give you a good idea about what expressions
are and how you can construct useful expressions. Throughout the
rest of this manual we'll write expr
to indicate any valid PHP expression.
An operator is something that you feed with one or more values (or expressions, in programming jargon) which yields another value (so that the construction itself becomes an expression). So you can think of functions or constructions that return a value (like print) as operators and those that return nothing (like echo) as any other thing.
There are three types of operators. Firstly there is the unary operator which operates on only one value, for example ! (the negation operator) or ++ (the increment operator). The second group are termed binary operators; this group contains most of the operators that PHP supports, and a list follows below in the section Operator Precedence.
The third group is the ternary operator: ?:. It should be used to select between two expressions depending on a third one, rather than to select two sentences or paths of execution. Surrounding ternary expressions with parentheses is a very good idea.
The precedence of an operator specifies how "tightly" it binds two expressions together. For example, in the expression 1 + 5 * 3, the answer is 16 and not 18 because the multiplication ("*") operator has a higher precedence than the addition ("+") operator. Parentheses may be used to force precedence, if necessary. For instance: (1 + 5) * 3 evaluates to 18. If operator precedence is equal, left to right associativity is used.
The following table lists the precedence of operators with the highest-precedence operators listed at the top of the table. Operators on the same line have equal precedence, in which case their associativity decides which order to evaluate them in.
Table 15-1. Operator Precedence
| Associativity | Operators | Additional Information |
|---|---|---|
| non-associative | new | new |
| left | [ | array() |
| non-associative | ++ -- | increment/decrement |
| non-associative | ~ - (int) (float) (string) (array) (object) @ | types |
| non-associative | instanceof | types |
| right | ! | logical |
| left | * / % | arithmetic |
| left | + - . | arithmetic and string |
| left | << >> | bitwise |
| non-associative | < <= > >= | comparison |
| non-associative | == != === !== | comparison |
| left | & | bitwise and references |
| left | ^ | bitwise |
| left | | | bitwise |
| left | && | logical |
| left | || | logical |
| left | ? : | ternary |
| right | = += -= *= /= .= %= &= |= ^= <<= >>= | assignment |
| left | and | logical |
| left | xor | logical |
| left | or | logical |
| left | , | many uses |
Left associativity means that the expression is evaluated from left to right, right associativity means the opposite.
Note: Although = has a lower precedence than most other operators, PHP will still allow expressions similar to the following: if (!$a = foo()), in which case the return value of foo() is put into
$a.
Remember basic arithmetic from school? These work just like those.
Table 15-2. Arithmetic Operators
| Example | Name | Result |
|---|---|---|
| -$a | Negation | Opposite of $a. |
| $a + $b | Addition | Sum of $a and $b. |
| $a - $b | Subtraction | Difference of $a and $b. |
| $a * $b | Multiplication | Product of $a and $b. |
| $a / $b | Division | Quotient of $a and $b. |
| $a % $b | Modulus | Remainder of $a divided by $b. |
The division operator ("/") returns a float value unless the two operands are integers (or strings that get converted to integers) and the numbers are evenly divisible, in which case an integer value will be returned.
Note: Remainder $a % $b is negative for negative $a.
See also the manual page on Math functions.
The basic assignment operator is "=". Your first inclination might be to think of this as "equal to". Don't. It really means that the left operand gets set to the value of the expression on the rights (that is, "gets set to").
The value of an assignment expression is the value assigned. That is, the value of "$a = 3" is 3. This allows you to do some tricky things:
In addition to the basic assignment operator, there are "combined operators" for all of the binary arithmetic, array union and string operators that allow you to use a value in an expression and then set its value to the result of that expression. For example:
<?php $a = 3; $a += 5; // sets $a to 8, as if we had said: $a = $a + 5; $b = "Hello "; $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; ?> |
Note that the assignment copies the original variable to the new one (assignment by value), so changes to one will not affect the other. This may also have relevance if you need to copy something like a large array inside a tight loop. Since PHP 4, assignment by reference has been supported, using the $var = &$othervar; syntax, but this is not possible in PHP 3. 'Assignment by reference' means that both variables end up pointing at the same data, and nothing is copied anywhere. To learn more about references, please read References explained. As of PHP 5, objects are assigned by reference unless explicitly told otherwise with the new clone keyword.
Bitwise operators allow you to turn specific bits within an integer on or off. If both the left- and right-hand parameters are strings, the bitwise operator will operate on the characters' ASCII values.
<?php
echo 12 ^ 9; // Outputs '5'
echo "12" ^ "9"; // Outputs the Backspace character (ascii 8)
// ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8
echo "hallo" ^ "hello"; // Outputs the ascii values #0 #4 #0 #0 #0
// 'a' ^ 'e' = #4
?> |
Table 15-3. Bitwise Operators
| Example | Name | Result |
|---|---|---|
| $a & $b | And | Bits that are set in both $a and $b are set. |
| $a | $b | Or | Bits that are set in either $a or $b are set. |
| $a ^ $b | Xor | Bits that are set in $a or $b but not both are set. |
| ~ $a | Not | Bits that are set in $a are not set, and vice versa. |
| $a << $b | Shift left | Shift the bits of $a $b steps to the left (each step means "multiply by two") |
| $a >> $b | Shift right | Shift the bits of $a $b steps to the right (each step means "divide by two") |
| Warning |
Don't right shift for more than 32 bits on 32 bits systems. Don't left shift in case it results to number longer than 32 bits. |
Comparison operators, as their name implies, allow you to compare two values. You may also be interested in viewing the type comparison tables, as they show examples of various type related comparisons.
Table 15-4. Comparison Operators
| Example | Name | Result |
|---|---|---|
| $a == $b | Equal | TRUE if $a is equal to $b. |
| $a === $b | Identical | TRUE if $a is equal to $b, and they are of the same type. (introduced in PHP 4) |
| $a != $b | Not equal | TRUE if $a is not equal to $b. |
| $a <> $b | Not equal | TRUE if $a is not equal to $b. |
| $a !== $b | Not identical | TRUE if $a is not equal to $b, or they are not of the same type. (introduced in PHP 4) |
| $a < $b | Less than | TRUE if $a is strictly less than $b. |
| $a > $b | Greater than | TRUE if $a is strictly greater than $b. |
| $a <= $b | Less than or equal to | TRUE if $a is less than or equal to $b. |
| $a >= $b | Greater than or equal to | TRUE if $a is greater than or equal to $b. |
If you compare an integer with a string, the string is converted to a number. If you compare two numerical strings, they are compared as integers. These rules also apply to the switch statement.
<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
switch ("a") {
case 0:
echo "0";
break;
case "a": // never reached because "a" is already matched with 0
echo "a";
break;
}
?> |
For various types, comparison is done according to the following table (in order).
Table 15-5. Comparison with Various Types
| Type of Operand 1 | Type of Operand 2 | Result |
|---|---|---|
| null or string | string | Convert NULL to "", numerical or lexical comparison |
| bool or null | anything | Convert to bool, FALSE < TRUE |
| object | object | Built-in classes can define its own comparison, different classes are uncomparable, same class - compare properties the same way as arrays (PHP 4), PHP 5 has its own explanation |
| string, resource or number | string, resource or number | Translate strings and resources to numbers, usual math |
| array | array | Array with fewer members is smaller, if key from operand 1 is not found in operand 2 then arrays are uncomparable, otherwise - compare value by value (see following example) |
| array | anything | array is always greater |
| object | anything | object is always greater |
Example 15-2. Transcription of standard array comparison
|
See also strcasecmp(), strcmp(), Array operators, and the manual section on Types.
Another conditional operator is the "?:" (or ternary) operator.
Note: Please note that the ternary operator is a statement, and that it doesn't evaluate to a variable, but to the result of a statement. This is important to know if you want to return a variable by reference. The statement return $var == 42 ? $a : $b; in a return-by-reference function will therefore not work and a warning is issued in later PHP versions.
Note: Is is recommended that you avoid "stacking" ternary expressions. PHP's behaviour when using more than one ternary operator within a single statement is non-obvious:
Example 15-4. Non-obvious Ternary Behaviour
PHP supports one error control operator: the at sign (@). When prepended to an expression in PHP, any error messages that might be generated by that expression will be ignored.
If the track_errors
feature is enabled, any error message generated by the expression
will be saved in the variable
$php_errormsg.
This variable will be overwritten on each error, so check early if you
want to use it.
<?php
/* Intentional file error */
$my_file = @file ('non_existent_file') or
die ("Failed opening file: error was '$php_errormsg'");
// this works for any expression, not just functions:
$value = @$cache[$key];
// will not issue a notice if the index $key doesn't exist.
?> |
Note: The @-operator works only on expressions. A simple rule of thumb is: if you can take the value of something, you can prepend the @ operator to it. For instance, you can prepend it to variables, function and include() calls, constants, and so forth. You cannot prepend it to function or class definitions, or conditional structures such as if and foreach, and so forth.
See also error_reporting() and the manual section for Error Handling and Logging functions.
| Warning |
Currently the "@" error-control operator prefix will even disable error reporting for critical errors that will terminate script execution. Among other things, this means that if you use "@" to suppress errors from a certain function and either it isn't available or has been mistyped, the script will die right there with no indication as to why. |
PHP supports one execution operator: backticks (``). Note that these are not single-quotes! PHP will attempt to execute the contents of the backticks as a shell command; the output will be returned (i.e., it won't simply be dumped to output; it can be assigned to a variable). Use of the backtick operator is identical to shell_exec().
Note: The backtick operator is disabled when safe mode is enabled or shell_exec() is disabled.
See also the manual section on Program Execution functions, popen() proc_open(), and Using PHP from the commandline.
PHP supports C-style pre- and post-increment and decrement operators.
Note: The increment/decrement operators do not affect boolean values. Decrementing NULL values has no effect too, but incrementing them results in 1.
Table 15-6. Increment/decrement Operators
| Example | Name | Effect |
|---|---|---|
| ++$a | Pre-increment | Increments $a by one, then returns $a. |
| $a++ | Post-increment | Returns $a, then increments $a by one. |
| --$a | Pre-decrement | Decrements $a by one, then returns $a. |
| $a-- | Post-decrement | Returns $a, then decrements $a by one. |
Here's a simple example script:
<?php echo "<h3>Postincrement</h3>"; $a = 5; echo "Should be 5: " . $a++ . "<br />\n"; echo "Should be 6: " . $a . "<br />\n"; echo "<h3>Preincrement</h3>"; $a = 5; echo "Should be 6: " . ++$a . "<br />\n"; echo "Should be 6: " . $a . "<br />\n"; echo "<h3>Postdecrement</h3>"; $a = 5; echo "Should be 5: " . $a-- . "<br />\n"; echo "Should be 4: " . $a . "<br />\n"; echo "<h3>Predecrement</h3>"; $a = 5; echo "Should be 4: " . --$a . "<br />\n"; echo "Should be 4: " . $a . "<br />\n"; ?> |
PHP follows Perl's convention when dealing with arithmetic operations on character variables and not C's. For example, in Perl 'Z'+1 turns into 'AA', while in C 'Z'+1 turns into '[' ( ord('Z') == 90, ord('[') == 91 ). Note that character variables can be incremented but not decremented and even so only plain ASCII characters (a-z and A-Z) are supported.
Incrementing or decrementing booleans has no effect.
Table 15-7. Logical Operators
| Example | Name | Result |
|---|---|---|
| $a and $b | And | TRUE if both $a and $b are TRUE. |
| $a or $b | Or | TRUE if either $a or $b is TRUE. |
| $a xor $b | Xor | TRUE if either $a or $b is TRUE, but not both. |
| ! $a | Not | TRUE if $a is not TRUE. |
| $a && $b | And | TRUE if both $a and $b are TRUE. |
| $a || $b | Or | TRUE if either $a or $b is TRUE. |
The reason for the two different variations of "and" and "or" operators is that they operate at different precedences. (See Operator Precedence.)
Example 15-6. Logical operators illustrated
The above example will output something similar to:
|
There are two string operators. The first is the concatenation operator ('.'), which returns the concatenation of its right and left arguments. The second is the concatenating assignment operator ('.='), which appends the argument on the right side to the argument on the left side. Please read Assignment Operators for more information.
<?php $a = "Hello "; $b = $a . "World!"; // now $b contains "Hello World!" $a = "Hello "; $a .= "World!"; // now $a contains "Hello World!" ?> |
See also the manual sections on the String type and String functions.
Table 15-8. Array Operators
| Example | Name | Result |
|---|---|---|
| $a + $b | Union | Union of $a and $b. |
| $a == $b | Equality | TRUE if $a and $b have the same key/value pairs. |
| $a === $b | Identity | TRUE if $a and $b have the same key/value pairs in the same order and of the same types. |
| $a != $b | Inequality | TRUE if $a is not equal to $b. |
| $a <> $b | Inequality | TRUE if $a is not equal to $b. |
| $a !== $b | Non-identity | TRUE if $a is not identical to $b. |
The + operator appends the right handed array to the left handed, whereas duplicated keys are NOT overwritten.
<?php
$a = array("a" => "apple", "b" => "banana");
$b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");
$c = $a + $b; // Union of $a and $b
echo "Union of \$a and \$b: \n";
var_dump($c);
$c = $b + $a; // Union of $b and $a
echo "Union of \$b and \$a: \n";
var_dump($c);
?> |
Union of $a and $b:
array(3) {
["a"]=>
string(5) "apple"
["b"]=>
string(6) "banana"
["c"]=>
string(6) "cherry"
}
Union of $b and $a:
array(3) {
["a"]=>
string(4) "pear"
["b"]=>
string(10) "strawberry"
["c"]=>
string(6) "cherry"
} |
Elements of arrays are equal for the comparison if they have the same key and value.
See also the manual sections on the Array type and Array functions.
instanceof is used to determine whether a PHP variable is an instantiated object of a certain class:
Although instanceof is usually used with a literal classname, it can also be used with another object or a string variable:
Example 15-11. Using instanceof with other variables
The above example will output:
|
There are a few pitfalls to be aware of. Before PHP version 5.1.0, instanceof would call __autoload() if the class name did not exist. In addition, if the class was not loaded, a fatal error would occur. This can be worked around by using a dynamic class reference, or a string variable containing the class name:
The instanceof operator was introduced in PHP 5. Before this time is_a() was used but is_a() has since been deprecated in favor of instanceof.
See also get_class() and is_a().
Any PHP script is built out of a series of statements. A statement can be an assignment, a function call, a loop, a conditional statement or even a statement that does nothing (an empty statement). Statements usually end with a semicolon. In addition, statements can be grouped into a statement-group by encapsulating a group of statements with curly braces. A statement-group is a statement by itself as well. The various statement types are described in this chapter.
The if construct is one of the most important features of many languages, PHP included. It allows for conditional execution of code fragments. PHP features an if structure that is similar to that of C:
As described in the section about expressions, expression is evaluated to its Boolean value. If expression evaluates to TRUE, PHP will execute statement, and if it evaluates to FALSE - it'll ignore it. More information about what values evaluate to FALSE can be found in the 'Converting to boolean' section.
The following example would display a is bigger
than b if $a is bigger
than $b:
Often you'd want to have more than one statement to be executed
conditionally. Of course, there's no need to wrap each statement
with an if clause. Instead, you can group
several statements into a statement group. For example, this code
would display a is bigger than b
if $a is bigger than
$b, and would then assign the value of
$a into $b:
If statements can be nested indefinitely within other if statements, which provides you with complete flexibility for conditional execution of the various parts of your program.
Often you'd want to execute a statement if a certain condition is
met, and a different statement if the condition is not met. This
is what else is for. else
extends an if statement to execute a statement
in case the expression in the if statement
evaluates to FALSE. For example, the following
code would display a is bigger than
b if $a is bigger than
$b, and a is NOT bigger
than b otherwise:
elseif, as its name suggests, is a combination of if and else. Like else, it extends an if statement to execute a different statement in case the original if expression evaluates to FALSE. However, unlike else, it will execute that alternative expression only if the elseif conditional expression evaluates to TRUE. For example, the following code would display a is bigger than b, a equal to b or a is smaller than b:
<?php
if ($a > $b) {
echo "a is bigger than b";
} elseif ($a == $b) {
echo "a is equal to b";
} else {
echo "a is smaller than b";
}
?> |
There may be several elseifs within the same if statement. The first elseif expression (if any) that evaluates to TRUE would be executed. In PHP, you can also write 'else if' (in two words) and the behavior would be identical to the one of 'elseif' (in a single word). The syntactic meaning is slightly different (if you're familiar with C, this is the same behavior) but the bottom line is that both would result in exactly the same behavior.
The elseif statement is only executed if the preceding if expression and any preceding elseif expressions evaluated to FALSE, and the current elseif expression evaluated to TRUE.
PHP offers an alternative syntax for some of its control structures; namely, if, while, for, foreach, and switch. In each case, the basic form of the alternate syntax is to change the opening brace to a colon (:) and the closing brace to endif;, endwhile;, endfor;, endforeach;, or endswitch;, respectively.
In the above example, the HTML block "A is equal to 5" is nested within an
if statement written in the alternative syntax. The
HTML block would be displayed only if $a is equal to 5.
The alternative syntax applies to else and elseif as well. The following is an if structure with elseif and else in the alternative format:
while loops are the simplest type of loop in PHP. They behave just like their C counterparts. The basic form of a while statement is:
The meaning of a while statement is simple. It tells PHP to execute the nested statement(s) repeatedly, as long as the while expression evaluates to TRUE. The value of the expression is checked each time at the beginning of the loop, so even if this value changes during the execution of the nested statement(s), execution will not stop until the end of the iteration (each time PHP runs the statements in the loop is one iteration). Sometimes, if the while expression evaluates to FALSE from the very beginning, the nested statement(s) won't even be run once.
Like with the if statement, you can group multiple statements within the same while loop by surrounding a group of statements with curly braces, or by using the alternate syntax:
The following examples are identical, and both print the numbers 1 through 10:
do-while loops are very similar to while loops, except the truth expression is checked at the end of each iteration instead of in the beginning. The main difference from regular while loops is that the first iteration of a do-while loop is guaranteed to run (the truth expression is only checked at the end of the iteration), whereas it's may not necessarily run with a regular while loop (the truth expression is checked at the beginning of each iteration, if it evaluates to FALSE right from the beginning, the loop execution would end immediately).
There is just one syntax for do-while loops:
The above loop would run one time exactly, since after the first iteration, when truth expression is checked, it evaluates to FALSE ($i is not bigger than 0) and the loop execution ends.
Advanced C users may be familiar with a different usage of the do-while loop, to allow stopping execution in the middle of code blocks, by encapsulating them with do-while (0), and using the break statement. The following code fragment demonstrates this:
<?php
do {
if ($i < 5) {
echo "i is not big enough";
break;
}
$i *= $factor;
if ($i < $minimum_limit) {
break;
}
echo "i is ok";
/* process i */
} while (0);
?> |
Don't worry if you don't understand this right away or at all. You can code scripts and even powerful scripts without using this 'feature'.
for loops are the most complex loops in PHP. They behave like their C counterparts. The syntax of a for loop is:
The first expression (expr1) is
evaluated (executed) once unconditionally at the beginning of the
loop.
In the beginning of each iteration,
expr2 is evaluated. If it evaluates to
TRUE, the loop continues and the nested
statement(s) are executed. If it evaluates to
FALSE, the execution of the loop ends.
At the end of each iteration, expr3 is
evaluated (executed).
Each of the expressions can be empty or contain multiple
expressions separated by commas. Comma separated expressions in expr2
are treated similarly to being separated by the || operator but has a
lower precedence than ||.
expr2 being empty means the loop should
be run indefinitely (PHP implicitly considers it as
TRUE, like C). This may not be as useless as
you might think, since often you'd want to end the loop using a
conditional break
statement instead of using the for truth
expression.
Consider the following examples. All of them display the numbers 1 through 10:
<?php
/* example 1 */
for ($i = 1; $i <= 10; $i++) {
echo $i;
}
/* example 2 */
for ($i = 1; ; $i++) {
if ($i > 10) {
break;
}
echo $i;
}
/* example 3 */
$i = 1;
for (; ; ) {
if ($i > 10) {
break;
}
echo $i;
$i++;
}
/* example 4 */
for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
?> |
Of course, the first example appears to be the nicest one (or perhaps the fourth), but you may find that being able to use empty expressions in for loops comes in handy in many occasions.
PHP also supports the alternate "colon syntax" for for loops.
PHP 4 introduced a foreach construct, much like Perl and some other languages. This simply gives an easy way to iterate over arrays. foreach works only on arrays, and will issue an error when you try to use it on a variable with a different data type or an uninitialized variable. There are two syntaxes; the second is a minor but useful extension of the first:
foreach (array_expression as $value)
statement
foreach (array_expression as $key => $value)
statement |
The first form loops over the array given by array_expression. On each loop, the value of the current element is assigned to $value and the internal array pointer is advanced by one (so on the next loop, you'll be looking at the next element).
The second form does the same thing, except that the current element's key will be assigned to the variable $key on each loop.
As of PHP 5, it is possible to iterate objects too.
Note: When foreach first starts executing, the internal array pointer is automatically reset to the first element of the array. This means that you do not need to call reset() before a foreach loop.
Note: Unless the array is referenced, foreach operates on a copy of the specified array and not the array itself. Therefore, the array pointer is not modified as with the each() construct, and changes to the array element returned are not reflected in the original array. However, the internal pointer of the original array is advanced with the processing of the array. Assuming the foreach loop runs to completion, the array's internal pointer will be at the end of the array.
As of PHP 5, you can easily modify array's elements by preceding $value with &. This will assign reference instead of copying the value.
This is possible only if iterated array can be referenced (i.e. is variable).
Note: foreach does not support the ability to suppress error messages using '@'.
You may have noticed that the following are functionally identical:
<?php
$arr = array("one", "two", "three");
reset($arr);
while (list(, $value) = each($arr)) {
echo "Value: $value<br />\n";
}
foreach ($arr as $value) {
echo "Value: $value<br />\n";
}
?> |
<?php
$arr = array("one", "two", "three");
reset($arr);
while (list($key, $value) = each($arr)) {
echo "Key: $key; Value: $value<br />\n";
}
foreach ($arr as $key => $value) {
echo "Key: $key; Value: $value<br />\n";
}
?> |
Some more examples to demonstrate usages:
<?php
/* foreach example 1: value only */
$a = array(1, 2, 3, 17);
foreach ($a as $v) {
echo "Current value of \$a: $v.\n";
}
/* foreach example 2: value (with key printed for illustration) */
$a = array(1, 2, 3, 17);
$i = 0; /* for illustrative purposes only */
foreach ($a as $v) {
echo "\$a[$i] => $v.\n";
$i++;
}
/* foreach example 3: key and value */
$a = array(
"one" => 1,
"two" => 2,
"three" => 3,
"seventeen" => 17
);
foreach ($a as $k => $v) {
echo "\$a[$k] => $v.\n";
}
/* foreach example 4: multi-dimensional arrays */
$a = array();
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";
foreach ($a as $v1) {
foreach ($v1 as $v2) {
echo "$v2\n";
}
}
/* foreach example 5: dynamic arrays */
foreach (array(1, 2, 3, 4, 5) as $v) {
echo "$v\n";
}
?> |
break ends execution of the current for, foreach, while, do-while or switch structure.
break accepts an optional numeric argument which tells it how many nested enclosing structures are to be broken out of.
<?php
$arr = array('one', 'two', 'three', 'four', 'stop', 'five');
while (list(, $val) = each($arr)) {
if ($val == 'stop') {
break; /* You could also write 'break 1;' here. */
}
echo "$val<br />\n";
}
/* Using the optional argument. */
$i = 0;
while (++$i) {
switch ($i) {
case 5:
echo "At 5<br />\n";
break 1; /* Exit only the switch. */
case 10:
echo "At 10; quitting<br />\n";
break 2; /* Exit the switch and the while. */
default:
break;
}
}
?> |
continue is used within looping structures to skip the rest of the current loop iteration and continue execution at the condition evaluation and then the beginning of the next iteration.
Note: Note that in PHP the switch statement is considered a looping structure for the purposes of continue.
continue accepts an optional numeric argument which tells it how many levels of enclosing loops it should skip to the end of.
<?php
while (list($key, $value) = each($arr)) {
if (!($key % 2)) { // skip odd members
continue;
}
do_something_odd($value);
}
$i = 0;
while ($i++ < 5) {
echo "Outer<br />\n";
while (1) {
echo " Middle<br />\n";
while (1) {
echo " Inner<br />\n";
continue 3;
}
echo "This never gets output.<br />\n";
}
echo "Neither does this.<br />\n";
}
?> |
Omitting the semicolon after continue can lead to confusion. Here's an example of what you shouldn't do.
<?php
for ($i = 0; $i < 5; ++$i) {
if ($i == 2)
continue
print "$i\n";
}
?> |
One can expect the result to be :
0 1 3 4 |
but this script will output :
2 |
because the return value of the print() call is int(1), and it will look like the optional numeric argument mentioned above.
The switch statement is similar to a series of IF statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. This is exactly what the switch statement is for.
Note: Note that unlike some other languages, the continue statement applies to switch and acts similar to break. If you have a switch inside a loop and wish to continue to the next iteration of the outer loop, use continue 2.
The following two examples are two different ways to write the same thing, one using a series of if and elseif statements, and the other using the switch statement:
It is important to understand how the switch statement is executed in order to avoid mistakes. The switch statement executes line by line (actually, statement by statement). In the beginning, no code is executed. Only when a case statement is found with a value that matches the value of the switch expression does PHP begin to execute the statements. PHP continues to execute the statements until the end of the switch block, or the first time it sees a break statement. If you don't write a break statement at the end of a case's statement list, PHP will go on executing the statements of the following case. For example:
<?php
switch ($i) {
case 0:
echo "i equals 0";
case 1:
echo "i equals 1";
case 2:
echo "i equals 2";
}
?> |
Here, if $i is equal to 0, PHP would execute all of the echo
statements! If $i is equal to 1, PHP would execute the last two
echo statements. You would get the expected behavior ('i equals 2'
would be displayed) only if $i is equal to 2. Thus,
it is important not to forget break statements
(even though you may want to avoid supplying them on purpose under
certain circumstances).
In a switch statement, the condition is evaluated only once and the result is compared to each case statement. In an elseif statement, the condition is evaluated again. If your condition is more complicated than a simple compare and/or is in a tight loop, a switch may be faster.
The statement list for a case can also be empty, which simply passes control into the statement list for the next case.
<?php
switch ($i) {
case 0:
case 1:
case 2:
echo "i is less than 3 but not negative";
break;
case 3:
echo "i is 3";
}
?> |
A special case is the default case. This case matches anything that wasn't matched by the other cases, and should be the last case statement. For example:
<?php
switch ($i) {
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
default:
echo "i is not equal to 0, 1 or 2";
}
?> |
The case expression may be any expression that evaluates to a simple type, that is, integer or floating-point numbers and strings. Arrays or objects cannot be used here unless they are dereferenced to a simple type.
The alternative syntax for control structures is supported with switches. For more information, see Alternative syntax for control structures.
The declare construct is used to set execution directives for a block of code. The syntax of declare is similar to the syntax of other flow control constructs:
The directive section allows the behavior of the declare block to be set. Currently only one directive is recognized: the ticks directive. (See below for more information on the ticks directive)
The statement part of the declare block will be executed -- how it is executed and what side effects occur during execution may depend on the directive set in the directive block.
The declare construct can also be used in the global scope, affecting all code following it.
<?php
// these are the same:
// you can use this:
declare(ticks=1) {
// entire script here
}
// or you can use this:
declare(ticks=1);
// entire script here
?> |
A tick is an event that occurs for every
N low-level statements executed
by the parser within the declare block.
The value for N is specified
using ticks=N
within the declare blocks's
directive section.
The event(s) that occur on each tick are specified using the register_tick_function(). See the example below for more details. Note that more than one event can occur for each tick.
Example 16-3. Profile a section of PHP code
|
Ticks are well suited for debugging, implementing simple multitasking, background I/O and many other tasks.
See also register_tick_function() and unregister_tick_function().
If called from within a function, the return() statement immediately ends execution of the current function, and returns its argument as the value of the function call. return() will also end the execution of an eval() statement or script file.
If called from the global scope, then execution of the current script file is ended. If the current script file was include()ed or require()ed, then control is passed back to the calling file. Furthermore, if the current script file was include()ed, then the value given to return() will be returned as the value of the include() call. If return() is called from within the main script file, then script execution ends. If the current script file was named by the auto_prepend_file or auto_append_file configuration options in php.ini, then that script file's execution is ended.
For more information, see Returning values.
Note: Note that since return() is a language construct and not a function, the parentheses surrounding its arguments are not required. It is common to leave them out, and you actually should do so as PHP has less work to do in this case.
Note: You should never use parentheses around your return variable when returning by reference, as this will not work. You can only return variables by reference, not the result of a statement. If you use return ($a); then you're not returning a variable, but the result of the expression ($a) (which is, of course, the value of
$a).
The require() statement includes and evaluates the specific file.
require() includes and evaluates a specific file. Detailed information on how this inclusion works is described in the documentation for include().
require() and include() are identical in every way except how they handle failure. They both produce a Warning, but require() results in a Fatal Error. In other words, don't hesitate to use require() if you want a missing file to halt processing of the page. include() does not behave this way, the script will continue regardless. Be sure to have an appropriate include_path setting as well.
Example 16-4. Basic require() examples
|
See the include() documentation for more examples.
Note: Prior to PHP 4.0.2, the following applies: require() will always attempt to read the target file, even if the line it's on never executes. The conditional statement won't affect require(). However, if the line on which the require() occurs is not executed, neither will any of the code in the target file be executed. Similarly, looping structures do not affect the behaviour of require(). Although the code contained in the target file is still subject to the loop, the require() itself happens only once.
Note: Because this is a language construct and not a function, it cannot be called using variable functions
| Warning |
Windows versions of PHP prior to PHP 4.3.0 do not support accessing remote files via this function, even if allow_url_fopen is enabled. |
See also include(), require_once(), include_once(), get_included_files(), eval(), file(), readfile(), virtual() and include_path.
The include() statement includes and evaluates the specified file.
The documentation below also applies to require(). The two constructs are identical in every way except how they handle failure. They both produce a Warning, but require() results in a Fatal Error. In other words, use require() if you want a missing file to halt processing of the page. include() does not behave this way, the script will continue regardless. Be sure to have an appropriate include_path setting as well. Be warned that parse error in included file doesn't cause processing halting in PHP versions prior to PHP 4.3.5. Since this version, it does.
Files for including are first looked in include_path relative to the current working directory and then in the directory of the current script. E.g. if your include_path is libraries, current working directory is /www/, you included include/a.php and there is include "b.php" in that file, b.php is first looked in /www/libraries/ and then in /www/include/. If filename begins with ./ or ../, it is looked only in include_path relative to the current working directory.
When a file is included, the code it contains inherits the variable scope of the line on which the include occurs. Any variables available at that line in the calling file will be available within the called file, from that point forward. However, all functions and classes defined in the included file have the global scope.
Example 16-5. Basic include() example
|
If the include occurs inside a function within the calling file, then all of the code contained in the called file will behave as though it had been defined inside that function. So, it will follow the variable scope of that function.
Example 16-6. Including within functions
|
When a file is included, parsing drops out of PHP mode and into HTML mode at the beginning of the target file, and resumes again at the end. For this reason, any code inside the target file which should be executed as PHP code must be enclosed within valid PHP start and end tags.
If "URL fopen wrappers" are enabled in PHP (which they are in the default configuration), you can specify the file to be included using a URL (via HTTP or other supported wrapper - see Appendix O for a list of protocols) instead of a local pathname. If the target server interprets the target file as PHP code, variables may be passed to the included file using a URL request string as used with HTTP GET. This is not strictly speaking the same thing as including the file and having it inherit the parent file's variable scope; the script is actually being run on the remote server and the result is then being included into the local script.
| Warning |
Windows versions of PHP prior to PHP 4.3.0 do not support accessing remote files via this function, even if allow_url_fopen is enabled. |
Example 16-7. include() through HTTP
|
| Security warning |
Remote file may be processed at the remote server (depending on the file extension and the fact if the remote server runs PHP or not) but it still has to produce a valid PHP script because it will be processed at the local server. If the file from the remote server should be processed there and outputted only, readfile() is much better function to use. Otherwise, special care should be taken to secure the remote script to produce a valid and desired code. |
See also Remote files, fopen() and file() for related information.
Handling Returns: It is possible to execute a return() statement inside an included file in order to terminate processing in that file and return to the script which called it. Also, it's possible to return values from included files. You can take the value of the include call as you would a normal function. This is not, however, possible when including remote files unless the output of the remote file has valid PHP start and end tags (as with any local file). You can declare the needed variables within those tags and they will be introduced at whichever point the file was included.
Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.
Note: In PHP 3, the return may not appear inside a block unless it's a function block, in which case the return() applies to that function and not the whole file.
$bar is the value 1 because the include was successful. Notice the difference between the above examples. The first uses return() within the included file while the other does not. If the file can't be included, FALSE is returned and E_WARNING is issued.
If there are functions defined in the included file, they can be used in the main file independent if they are before return() or after. If the file is included twice, PHP 5 issues fatal error because functions were already declared, while PHP 4 doesn't complain about functions defined after return(). It is recommended to use include_once() instead of checking if the file was already included and conditionally return inside the included file.
Another way to "include" a PHP file into a variable is to capture the output by using the Output Control Functions with include(). For example:
Example 16-10. Using output buffering to include a PHP file into a string
|
In order to automatically include files within scripts, see also the auto_prepend_file and auto_append_file configuration options in php.ini.
Note: Because this is a language construct and not a function, it cannot be called using variable functions
See also require(), require_once(), include_once(), get_included_files(), readfile(), virtual(), and include_path.
The require_once() statement includes and evaluates the specified file during the execution of the script. This is a behavior similar to the require() statement, with the only difference being that if the code from a file has already been included, it will not be included again. See the documentation for require() for more information on how this statement works.
require_once() should be used in cases where the same file might be included and evaluated more than once during a particular execution of a script, and you want to be sure that it is included exactly once to avoid problems with function redefinitions, variable value reassignments, etc.
For examples on using require_once() and include_once(), look at the PEAR code included in the latest PHP source code distributions.
Return values are the same as with include(). If the file was already included, this function returns TRUE
Note: require_once() was added in PHP 4.0.1
Note: Be aware, that the behaviour of require_once() and include_once() may not be what you expect on a non case sensitive operating system (such as Windows).
This behaviour changed in PHP 5 - the path is normalized first so that C:\PROGRA~1\A.php is realized the same as C:\Program Files\a.php and the file is required just once.
Example 16-11. require_once() is case insensitive on Windows
<?php require_once("a.php"); // this will include a.php require_once("A.php"); // this will include a.php again on Windows! (PHP 4 only) ?>
| Warning |
Windows versions of PHP prior to PHP 4.3.0 do not support accessing remote files via this function, even if allow_url_fopen is enabled. |
See also require(), include(), include_once(), get_required_files(), get_included_files(), readfile(), and virtual().
The include_once() statement includes and evaluates the specified file during the execution of the script. This is a behavior similar to the include() statement, with the only difference being that if the code from a file has already been included, it will not be included again. As the name suggests, it will be included just once.
include_once() should be used in cases where the same file might be included and evaluated more than once during a particular execution of a script, and you want to be sure that it is included exactly once to avoid problems with function redefinitions, variable value reassignments, etc.
For more examples on using require_once() and include_once(), look at the PEAR code included in the latest PHP source code distributions.
Return values are the same as with include(). If the file was already included, this function returns TRUE
Note: include_once() was added in PHP 4.0.1
Note: Be aware, that the behaviour of include_once() and require_once() may not be what you expect on a non case sensitive operating system (such as Windows).
This behaviour changed in PHP 5 - the path is normalized first so that C:\PROGRA~1\A.php is realized the same as C:\Program Files\a.php and the file is included just once.
Example 16-12. include_once() is case insensitive on Windows
<?php include_once("a.php"); // this will include a.php include_once("A.php"); // this will include a.php again on Windows! (PHP 4 only) ?>
| Warning |
Windows versions of PHP prior to PHP 4.3.0 do not support accessing remote files via this function, even if allow_url_fopen is enabled. |
See also include(), require(), require_once(), get_required_files(), get_included_files(), readfile(), and virtual().
A function may be defined using syntax such as the following:
Any valid PHP code may appear inside a function, even other functions and class definitions.
Function names follow the same rules as other labels in PHP. A valid function name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.
Tip: You may also want to take a look at the Appendix T.
In PHP 3, functions must be defined before they are referenced. No such requirement exists since PHP 4. Except when a function is conditionally defined such as shown in the two examples below.
When a function is defined in a conditional manner such as the two examples shown. Its definition must be processed prior to being called.
Example 17-2. Conditional functions
|
All functions and classes in PHP have the global scope - they can be called outside a function even if they were defined inside and vice versa.
PHP does not support function overloading, nor is it possible to undefine or redefine previously-declared functions.
Note: Function names are case-insensitive, though it is usually good form to call functions as they appear in their declaration.
PHP 3 does not support variable numbers of arguments to functions, although default arguments are supported (see Default argument values for more information). Both are supported, as of PHP 4: see Variable-length argument lists and the function references for func_num_args(), func_get_arg(), and func_get_args() for more information.
It is possible to call recursive functions in PHP. However avoid recursive function/method calls with over 100-200 recursion levels as it can smash the stack and cause a termination of the current script.
Information may be passed to functions via the argument list, which is a comma-delimited list of expressions.
PHP supports passing arguments by value (the default), passing by reference, and default argument values. Variable-length argument lists are supported only in PHP 4 and later; see Variable-length argument lists and the function references for func_num_args(), func_get_arg(), and func_get_args() for more information. A similar effect can be achieved in PHP 3 by passing an array of arguments to a function:
By default, function arguments are passed by value (so that if you change the value of the argument within the function, it does not get changed outside of the function). If you wish to allow a function to modify its arguments, you must pass them by reference.
If you want an argument to a function to always be passed by reference, you can prepend an ampersand (&) to the argument name in the function definition:
A function may define C++-style default values for scalar arguments as follows:
The output from the above snippet is:
Making a cup of cappuccino. Making a cup of . Making a cup of espresso. |
Also PHP allows you to use arrays and special type NULL as default values, for example:
Example 17-8. Using non-scalar types as default values
|
The default value must be a constant expression, not (for example) a variable, a class member or a function call.
Note that when using default arguments, any defaults should be on the right side of any non-default arguments; otherwise, things will not work as expected. Consider the following code snippet:
The output of the above example is:
Warning: Missing argument 2 in call to makeyogurt() in /usr/local/etc/httpd/htdocs/php3test/functest.html on line 41 Making a bowl of raspberry . |
Now, compare the above with this:
The output of this example is:
Making a bowl of acidophilus raspberry. |
Note: As of PHP 5, default values may be passed by reference.
PHP 4 and above has support for variable-length argument lists in user-defined functions. This is really quite easy, using the func_num_args(), func_get_arg(), and func_get_args() functions.
No special syntax is required, and argument lists may still be explicitly provided with function definitions and will behave as normal.
Values are returned by using the optional return statement. Any type may be returned, including lists and objects. This causes the function to end its execution immediately and pass control back to the line from which it was called. See return() for more information.
Example 17-11. Use of return()
|
You can't return multiple values from a function, but similar results can be obtained by returning a list.
To return a reference from a function, you have to use the reference operator & in both the function declaration and when assigning the returned value to a variable:
For more information on references, please check out References Explained.
PHP supports the concept of variable functions. This means that if a variable name has parentheses appended to it, PHP will look for a function with the same name as whatever the variable evaluates to, and will attempt to execute it. Among other things, this can be used to implement callbacks, function tables, and so forth.
Variable functions won't work with language constructs such as echo(), print(), unset(), isset(), empty(), include(), require() and the like. You need to use your own wrapper function to utilize any of these constructs as variable functions.
Example 17-14. Variable function example
|
You can also call an object's method by using the variable functions feature.
See also call_user_func(), variable variables and function_exists().
PHP comes standard with many functions and constructs. There are also functions that require specific PHP extensions compiled in otherwise you'll get fatal "undefined function" errors. For example, to use image functions such as imagecreatetruecolor(), you'll need your PHP compiled with GD support. Or, to use mysql_connect() you'll need your PHP compiled in with MySQL support. There are many core functions that are included in every version of PHP like the string and variable functions. A call to phpinfo() or get_loaded_extensions() will show you which extensions are loaded into your PHP. Also note that many extensions are enabled by default and that the PHP manual is split up by extension. See the configuration, installation, and individual extension chapters, for information on how to setup your PHP.
Reading and understanding a function's prototype is explained within the manual section titled how to read a function definition. It's important to realize what a function returns or if a function works directly on a passed in value. For example, str_replace() will return the modified string while usort() works on the actual passed in variable itself. Each manual page also has specific information for each function like information on function parameters, behavior changes, return values for both success and failure, and availability information. Knowing these important (yet often subtle) differences is crucial for writing correct PHP code.
Note: If the parameters given to a function are not what it expects, such as passing an array where a string is expected, the return value of the function is undefined. In this case it will likely return NULL but this is just a convention, and cannot be relied upon.
See also function_exists(), the function reference, get_extension_funcs(), and dl().
A class is a collection of variables and functions working with these variables. A class is defined using the following syntax:
<?php
class Cart {
var $items; // Items in our shopping cart
// Add $num articles of $artnr to the cart
function add_item($artnr, $num) {
$this->items[$artnr] += $num;
}
// Take $num articles of $artnr out of the cart
function remove_item($artnr, $num) {
if ($this->items[$artnr] > $num) {
$this->items[$artnr] -= $num;
return true;
} elseif ($this->items[$artnr] == $num) {
unset($this->items[$artnr]);
return true;
} else {
return false;
}
}
}
?> |
This defines a class named Cart that consists of an associative array of articles in the cart and two functions to add and remove items from this cart.
| Warning |
You can NOT break up a class definition into multiple files. You also can NOT break a class definition into multiple PHP blocks, unless the break is within a method declaration. The following will not work:
However, the following is allowed:
|
The following cautionary notes are valid for PHP 4.
| Caution |
The name stdClass is used internally by Zend and is reserved. You cannot have a class named stdClass in PHP. |
| Caution |
The function names __sleep and __wakeup are magical in PHP classes. You cannot have functions with these names in any of your classes unless you want the magic functionality associated with them. See below for more information. |
| Caution |
PHP reserves all function names starting with __ as magical. It is recommended that you do not use function names with __ in PHP unless you want some documented magic functionality. |
In PHP 4, only constant initializers for var variables are allowed. To initialize variables with non-constant values, you need an initialization function which is called automatically when an object is being constructed from the class. Such a function is called a constructor (see below).
<?php
class Cart {
/* None of these will work in PHP 4. */
var $todays_date = date("Y-m-d");
var $name = $firstname;
var $owner = 'Fred ' . 'Jones';
/* Arrays containing constant values will, though. */
var $items = array("VCR", "TV");
}
/* This is how it should be done. */
class Cart {
var $todays_date;
var $name;
var $owner;
var $items = array("VCR", "TV");
function Cart() {
$this->todays_date = date("Y-m-d");
$this->name = $GLOBALS['firstname'];
/* etc. . . */
}
}
?> |
Classes are types, that is, they are blueprints for actual variables. You have to create a variable of the desired type with the new operator.
<?php
$cart = new Cart;
$cart->add_item("10", 1);
$another_cart = new Cart;
$another_cart->add_item("0815", 3);
?> |
This creates the objects $cart and
$another_cart, both of the class Cart. The function
add_item() of the $cart object is being called to add 1
item of article number 10 to the $cart. 3 items of
article number 0815 are being added to $another_cart.
Both, $cart and $another_cart, have
functions add_item(), remove_item() and a variable items. These are
distinct functions and variables. You can think of the objects as
something similar to directories in a filesystem. In a filesystem you can
have two different files README.TXT, as long as they
are in different directories. Just like with directories where you'll have
to type the full pathname in order to reach each file from the toplevel
directory, you have to specify the complete name of the function you want to
call: in PHP terms, the toplevel directory would be the global namespace,
and the pathname separator would be ->. Thus, the
names $cart->items and
$another_cart->items name two different variables.
Note that the variable is named $cart->items, not
$cart->$items, that is, a variable name in PHP has
only a single dollar sign.
<?php
// correct, single $
$cart->items = array("10" => 1);
// invalid, because $cart->$items becomes $cart->""
$cart->$items = array("10" => 1);
// correct, but may or may not be what was intended:
// $cart->$myvar becomes $cart->items
$myvar = 'items';
$cart->$myvar = array("10" => 1);
?> |
Within a class definition, you do not know under which name the object
will be accessible in your program: at the time the Cart class was
written, it was unknown whether the object would be named
$cart, $another_cart, or something
else later. Thus,
you cannot write $cart->items within the Cart class
itself. Instead, in order to be able to access its own functions and
variables from within a class, one can use the pseudo-variable
$this which can be read as 'my own' or 'current
object'. Thus, '$this->items[$artnr] +=
$num' can be read as 'add $num to
the $artnr counter of my own items array' or 'add
$num to the $artnr counter of the
items array within the current object'.
Note: The
$thispseudo-variable is not usually defined if the method in which it is hosted is called statically. This is not, however, a strict rule:$thisis defined if a method is called statically from within another object. In this case, the value of$thisis that of the calling object. This is illustrated in the following example:
<?php class A { function foo() { if (isset($this)) { echo '$this is defined ('; echo get_class($this); echo ")\n"; } else { echo "\$this is not defined.\n"; } } } class B { function bar() { A::foo(); } } $a = new A(); $a->foo(); A::foo(); $b = new B(); $b->bar(); B::bar(); ?>The above example will output:
Note: There are some nice functions to handle classes and objects. You might want to take a look at the Class/Object Functions.
Often you need classes with similar variables and functions to another existing class. In fact, it is good practice to define a generic class which can be used in all your projects and adapt this class for the needs of each of your specific projects. To facilitate this, classes can be extensions of other classes. The extended or derived class has all variables and functions of the base class (this is called 'inheritance' despite the fact that nobody died) and what you add in the extended definition. It is not possible to subtract from a class, that is, to undefine any existing functions or variables. An extended class is always dependent on a single base class, that is, multiple inheritance is not supported. Classes are extended using the keyword 'extends'.
<?php
class Named_Cart extends Cart {
var $owner;
function set_owner ($name) {
$this->owner = $name;
}
}
?> |
This defines a class Named_Cart that has all variables and functions of
Cart plus an additional variable $owner and an
additional function set_owner(). You create a named cart the usual way and
can now set and get the carts owner. You can still use normal cart
functions on named carts:
<?php
$ncart = new Named_Cart; // Create a named cart
$ncart->set_owner("kris"); // Name that cart
print $ncart->owner; // print the cart owners name
$ncart->add_item("10", 1); // (inherited functionality from cart)
?> |
This is also called a "parent-child" relationship. You create a class, parent, and use extends to create a new class based on the parent class: the child class. You can even use this new child class and create another class based on this child class.
Note: Classes must be defined before they are used! If you want the class Named_Cart to extend the class Cart, you will have to define the class Cart first. If you want to create another class called Yellow_named_cart based on the class Named_Cart you have to define Named_Cart first. To make it short: the order in which the classes are defined is important.
Constructors are functions in a class that are automatically called when you create a new instance of a class with new. A function becomes a constructor, when it has the same name as the class. If a class has no constructor, the constructor of the base class will be called, if it exists.
This defines a class Auto_Cart that is a Cart plus a constructor which initializes the cart with one item of article number "10" each time a new Auto_Cart is being made with "new". Constructors can take arguments and these arguments can be optional, which makes them much more useful. To be able to still use the class without parameters, all parameters to constructors should be made optional by providing default values.
<?php
class Constructor_Cart extends Cart {
function Constructor_Cart($item = "10", $num = 1) {
$this->add_item ($item, $num);
}
}
// Shop the same old boring stuff.
$default_cart = new Constructor_Cart;
// Shop for real...
$different_cart = new Constructor_Cart("20", 17);
?> |
You also can use the @ operator to mute errors occurring in the constructor, e.g. @new.
<?php
class A
{
function A()
{
echo "I am the constructor of A.<br />\n";
}
function B()
{
echo "I am a regular function named B in class A.<br />\n";
echo "I am not a constructor in A.<br />\n";
}
}
class B extends A
{
}
// This will call B() as a constructor
$b = new B;
?> |
The function B() in class A will suddenly become a constructor in class B, although it was never intended to be. PHP 4 does not care if the function is being defined in class B, or if it has been inherited.
| Caution |
PHP 4 doesn't call constructors of the base class automatically from a constructor of a derived class. It is your responsibility to propagate the call to constructors upstream where appropriate. |
Destructors are functions that are called automatically when an object is destroyed, either with unset() or by simply going out of scope. There are no destructors in PHP. You may use register_shutdown_function() instead to simulate most effects of destructors.
| Caution |
The following is valid for PHP 4 and later only. |
Sometimes it is useful to refer to functions and variables in base classes or to refer to functions in classes that have not yet any instances. The :: operator is being used for this.
<?php
class A {
function example() {
echo "I am the original function A::example().<br />\n";
}
}
class B extends A {
function example() {
echo "I am the redefined function B::example().<br />\n";
A::example();
}
}
// there is no object of class A.
// this will print
// I am the original function A::example().<br />
A::example();
// create an object of class B.
$b = new B;
// this will print
// I am the redefined function B::example().<br />
// I am the original function A::example().<br />
$b->example();
?> |
The above example calls the function example() in class A, but there is no object of class A, so that we cannot write $a->example() or similar. Instead we call example() as a 'class function', that is, as a function of the class itself, not any object of that class.
There are class functions, but there are no class variables.
In fact, there is no object at all at the time of the call.
Thus, a class function may not use any object variables (but
it can use local and global variables), and it may not use
$this at all.
In the above example, class B redefines the function example(). The original definition in class A is shadowed and no longer available, unless you are referring specifically to the implementation of example() in class A using the ::-operator. Write A::example() to do this (in fact, you should be writing parent::example(), as shown in the next section).
In this context, there is a current object and it may have object
variables. Thus, when used from WITHIN an object function, you may use
$this and object variables.
You may find yourself writing code that refers to variables and functions in base classes. This is particularly true if your derived class is a refinement or specialisation of code in your base class.
Instead of using the literal name of the base class in your code, you should be using the special name parent, which refers to the name of your base class as given in the extends declaration of your class. By doing this, you avoid using the name of your base class in more than one place. Should your inheritance tree change during implementation, the change is easily made by simply changing the extends declaration of your class.
<?php
class A {
function example() {
echo "I am A::example() and provide basic functionality.<br />\n";
}
}
class B extends A {
function example() {
echo "I am B::example() and provide additional functionality.<br />\n";
parent::example();
}
}
$b = new B;
// This will call B::example(), which will in turn call A::example().
$b->example();
?> |
Note: In PHP 3, objects will lose their class association throughout the process of serialization and unserialization. The resulting variable is of type object, but has no class and no methods, thus it is pretty useless (it has become just like an array with a funny syntax).
| Caution |
The following information is valid for PHP >= 4 only. |
serialize() returns a string containing a byte-stream representation of any value that can be stored in PHP. unserialize() can use this string to recreate the original variable values. Using serialize to save an object will save all variables in an object. The functions in an object will not be saved, only the name of the class.
In order to be able to unserialize() an object, the
class of that object needs to be defined. That is, if you have an object
$a of class A on page1.php and serialize this, you'll
get a string that refers to class A and contains all values of variabled
contained in $a. If you want to be able to unserialize
this on page2.php, recreating $a of class A, the
definition of class A must be present in page2.php. This can be done for
example by storing the class definition of class A in an include file and
including this file in both page1.php and page2.php.
<?php
// classa.inc:
class A {
var $one = 1;
function show_one() {
echo $this->one;
}
}
// page1.php:
include("classa.inc");
$a = new A;
$s = serialize($a);
// store $s somewhere where page2.php can find it.
$fp = fopen("store", "w");
fwrite($fp, $s);
fclose($fp);
// page2.php:
// this is needed for the unserialize to work properly.
include("classa.inc");
$s = implode("", @file("store"));
$a = unserialize($s);
// now use the function show_one() of the $a object.
$a->show_one();
?> |
If you are using sessions and use session_register() to register objects, these objects are serialized automatically at the end of each PHP page, and are unserialized automatically on each of the following pages. This basically means that these objects can show up on any of your pages once they become part of your session.
It is strongly recommended that you include the class definitions of all such registered objects on all of your pages, even if you do not actually use these classes on all of your pages. If you don't and an object is being unserialized without its class definition being present, it will lose its class association and become an object of class stdClass without any functions available at all, that is, it will become quite useless.
So if in the example above $a became part of a session
by running session_register("a"), you should include the
file classa.inc on all of your pages, not only page1.php
and page2.php.
serialize() checks if your class has a function with the magic name __sleep. If so, that function is being run prior to any serialization. It can clean up the object and is supposed to return an array with the names of all variables of that object that should be serialized. If the method doesn't return anything then NULL is serialized and E_NOTICE is issued.
The intended use of __sleep is to commit pending data or perform similar cleanup tasks. Also, the function is useful if you have very large objects which need not be saved completely.
Conversely, unserialize() checks for the presence of a function with the magic name __wakeup. If present, this function can reconstruct any resources that object may have.
The intended use of __wakeup is to reestablish any database connections that may have been lost during serialization and perform other reinitialization tasks.
Creating references within the constructor can lead to confusing results. This tutorial-like section helps you to avoid problems.
<?php
class Foo {
function Foo($name) {
// create a reference inside the global array $globalref
global $globalref;
$globalref[] = &$this;
// set name to passed value
$this->setName($name);
// and put it out
$this->echoName();
}
function echoName() {
echo "<br />", $this->name;
}
function setName($name) {
$this->name = $name;
}
}
?> |
Let us check out if there is a difference between
$bar1 which has been created using
the copy = operator and
$bar2 which has been created using
the reference =& operator...
<?php
$bar1 = new Foo('set in constructor');
$bar1->echoName();
$globalref[0]->echoName();
/* output:
set in constructor
set in constructor
set in constructor */
$bar2 =& new Foo('set in constructor');
$bar2->echoName();
$globalref[1]->echoName();
/* output:
set in constructor
set in constructor
set in constructor */
?> |
Apparently there is no difference, but in fact there is a
very significant one: $bar1 and
$globalref[0] are _NOT_ referenced, they
are NOT the same variable. This is because "new" does not
return a reference by default, instead it returns a copy.
Note: There is no performance loss (since PHP 4 and up use reference counting) returning copies instead of references. On the contrary it is most often better to simply work with copies instead of references, because creating references takes some time where creating copies virtually takes no time (unless none of them is a large array or object and one of them gets changed and the other(s) one(s) subsequently, then it would be wise to use references to change them all concurrently).
<?php
// now we will change the name. what do you expect?
// you could expect that both $bar1 and $globalref[0] change their names...
$bar1->setName('set from outside');
// as mentioned before this is not the case.
$bar1->echoName();
$globalref[0]->echoName();
/* output:
set from outside
set in constructor */
// let us see what is different with $bar2 and $globalref[1]
$bar2->setName('set from outside');
// luckily they are not only equal, they are the same variable
// thus $bar2->name and $globalref[1]->name are the same too
$bar2->echoName();
$globalref[1]->echoName();
/* output:
set from outside
set from outside */
?> |
Another final example, try to understand it.
<?php
class A {
function A($i) {
$this->value = $i;
// try to figure out why we do not need a reference here
$this->b = new B($this);
}
function createRef() {
$this->c = new B($this);
}
function echoValue() {
echo "<br />","class ",get_class($this),': ',$this->value;
}
}
class B {
function B(&$a) {
$this->a = &$a;
}
function echoValue() {
echo "<br />","class ",get_class($this),': ',$this->a->value;
}
}
// try to understand why using a simple copy here would yield
// in an undesired result in the *-marked line
$a =& new A(10);
$a->createRef();
$a->echoValue();
$a->b->echoValue();
$a->c->echoValue();
$a->value = 11;
$a->echoValue();
$a->b->echoValue(); // *
$a->c->echoValue();
?> |
The above example will output:
class A: 10 class B: 10 class B: 10 class A: 11 class B: 11 class B: 11 |
In PHP 4, objects are compared in a very simple manner, namely: Two object instances are equal if they have the same attributes and values, and are instances of the same class. Similar rules are applied when comparing two objects using the identity operator (===).
If we were to execute the code in the example below:
Example 18-1. Example of object comparison in PHP 4
The above example will output:
|
Even in the cases where we have object composition, the same comparison rules apply. In the example below we create a container class that stores an associative array of Flag objects.
Example 18-2. Compound object comparisons in PHP 4
The above example will output:
|
In PHP 5 there is a new Object Model. PHP's handling of objects has been completely rewritten, allowing for better performance and more features.
Tip: You may also want to take a look at the Appendix T.
Every class definition begins with the keyword class, followed by a class
name, which can be any name that isn't a reserved
word in PHP. Followed by a pair of curly braces,
which contains the definition of the classes members and methods. A
pseudo-variable, $this is available when a method is
called from within an object context. $this is a
reference to the calling object (usually the object to which the method
belongs, but can be another object, if the method is called
statically from the context
of a secondary object). This is illustrated in the following examples:
Example 19-1.
The above example will output:
|
The default value must be a constant expression, not (for example) a variable, a class member or a function call.
Example 19-3. Class members' default value
|
Note: There are some nice functions to handle classes and objects. You might want to take a look at the Class/Object Functions.
To create an instance of a class, a new object must be created and assigned to a variable. An object will always be assigned when creating a new object unless the object has a constructor defined that throws an exception on error. Classes should be defined before instantiation (and in some cases this is a requirement).
When assigning an already created instance of a class to a new variable, the new variable will access the same instance as the object that was assigned. This behaviour is the same when passing instances to a function. A copy of an already created object can be made by cloning it.
Example 19-5. Object Assignment
The above example will output:
|
A class can inherit methods and members of another class by using the extends keyword in the declaration. It is not possible to extend multiple classes, a class can only inherit one base class.
The inherited methods and members can be overridden, unless the parent class has defined a method as final, by redeclaring them within the same name defined in the parent class. It is possible to access the overridden methods or members by referencing them with parent::
Example 19-6. Simple Class Inheritance
The above example will output:
|
Many developers writing object-oriented applications create one PHP source file per-class definition. One of the biggest annoyances is having to write a long list of needed includes at the beginning of each script (one for each class).
In PHP 5, this is no longer necessary. You may define an __autoload function which is automatically called in case you are trying to use a class which hasn't been defined yet. By calling this function the scripting engine is given a last chance to load the class before PHP fails with an error.
Note: Exceptions thrown in __autoload function cannot be caught in the catch block and results in a fatal error.
Note: Autoloading is not available if using PHP in CLI interactive mode.
PHP 5 allows developers to declare constructor methods for classes. Classes which have a constructor method call this method on each newly-created object, so it is suitable for any initialization that the object may need before it is used.
Note: Parent constructors are not called implicitly if the child class defines a constructor. In order to run a parent constructor, a call to parent::__construct() within the child constructor is required.
Example 19-8. using new unified constructors
|
For backwards compatibility, if PHP 5 cannot find a __construct() function for a given class, it will search for the old-style constructor function, by the name of the class. Effectively, it means that the only case that would have compatibility issues is if the class had a method named __construct() which was used for different semantics.
PHP 5 introduces a destructor concept similar to that of other object-oriented languages, such as C++. The destructor method will be called as soon as all references to a particular object are removed or when the object is explicitly destroyed.
Like constructors, parent destructors will not be called implicitly by the engine. In order to run a parent destructor, one would have to explicitly call parent::__destruct() in the destructor body.
Note: Destructor is called during the script shutdown so headers are always already sent.
Note: Attempting to throw an exception from a destructor causes a fatal error.
The visibility of a property or method can be defined by prefixing the declaration with the keywords: public, protected or private. Public declared items can be accessed everywhere. Protected limits access to inherited and parent classes (and to the class that defines the item). Private limits visibility only to the class that defines the item.
Class members must be defined with public, private, or protected.
Example 19-10. Member declaration
|
Note: The PHP 4 method of declaring a variable with the var keyword is still supported for compatibility reasons (as a synonym for the public keyword). In PHP 5 before 5.1.3, its usage would generate an E_STRICT warning.
Class methods must be defined with public, private, or protected. Methods without any declaration are defined as public.
Example 19-11. Method Declaration
|
The Scope Resolution Operator (also called Paamayim Nekudotayim) or in simpler terms, the double colon, is a token that allows access to static, constant, and overridden members or methods of a class.
When referencing these items from outside the class definition, use the name of the class.
Paamayim Nekudotayim would, at first, seem like a strange choice for naming a double-colon. However, while writing the Zend Engine 0.5 (which powers PHP 3), that's what the Zend team decided to call it. It actually does mean double-colon - in Hebrew!
Two special keywords self and parent
are used to access members or methods from inside the class definition.
When an extending class overrides the parents definition of a method, PHP will not call the parent's method. It's up to the extended class on whether or not the parent's method is called. This also applies to Constructors and Destructors, Overloading, and Magic method definitions.
Example 19-14. Calling a parent's method
|
Declaring class members or methods as static makes them accessible without needing an instantiation of the class. A member declared as static can not be accessed with an instantiated class object (though a static method can).
The static declaration must be after the visibility declaration. For compatibility with PHP 4, if no visibility declaration is used, then the member or method will be treated as if it was declared as public.
Because static methods are callable without an instance of
the object created, the pseudo variable $this is
not available inside the method declared as static.
In fact static method calls are resolved at compile time. When using an explicit class name the method is already identified completely and no inheritance rules apply. If the call is done by self then self is translated to the current class, that is the class the code belongs to. Here also no inheritance rules apply.
Static properties cannot be accessed through the object using the arrow operator ->.
Calling non-static methods statically generates an E_STRICT level warning.
Example 19-15. Static member example
|
It is possible to define constant values on a per-class basis remaining the
same and unchangeable. Constants differ from normal variables in that you
don't use the $ symbol to declare or use them. Like
static members, constant values
cannot be accessed from an instance of the object (using
$object::constant).
The value must be a constant expression, not (for example) a variable, a class member, result of a mathematical operation or a function call.
PHP 5 introduces abstract classes and methods. It is not allowed to create an instance of a class that has been defined as abstract. Any class that contains at least one abstract method must also be abstract. Methods defined as abstract simply declare the method's signature they cannot define the implementation.
When inheriting from an abstract class, all methods marked abstract in the parent's class declaration must be defined by the child; additionally, these methods must be defined with the same (or a less restricted) visibility. For example, if the abstract method is defined as protected, the function implementation must be defined as either protected or public, but not private.
Example 19-18. Abstract class example
The above example will output:
|
Old code that has no user-defined classes or functions named 'abstract' should run without modifications.
Object interfaces allow you to create code which specifies which methods a class must implement, without having to define how these methods are handled.
Interfaces are defined using the interface keyword, in the same way as a standard class, but without any of the methods having their contents defined.
All methods declared in an interface must be public, this is the nature of an interface.
To implement an interface, the implements operator is used. All methods in the interface must be implemented within a class; failure to do so will result in a fatal error. Classes may implement more than one interface if desired by separating each interface with a comma.
Note: A class cannot implement two interfaces that share function names, since it would cause ambiguity.
Example 19-19. Interface example
|
See also the instanceof operator.
Both method calls and member accesses can be overloaded via the __call, __get and __set methods. These methods will only be triggered when your object or inherited object doesn't contain the member or method you're trying to access. All overloading methods must not be defined as static. All overloading methods must be defined as public.
Since PHP 5.1.0 it is also possible to overload the isset() and unset() functions via the __isset and __unset methods respectively. Method __isset is called also with empty().
Class members can be overloaded to run custom code defined in your class
by defining these specially named methods. The $name
parameter used is the name of the variable that should be set or retrieved.
The __set() method's $value parameter specifies the
value that the object should set the $name.
Example 19-20. overloading with __get, __set, __isset and __unset example
The above example will output:
|
The magic method __call() allows to capture invocation of non existing
methods. That way __call() can be used to implement user defined method
handling that depends on the name of the actual method being called. This
is for instance useful for proxy implementations. The arguments that were
passed in the function will be defined as an array in the
$arguments parameter. The value returned from the
__call() method will be returned to the caller of the method.
Example 19-21. overloading with __call example
The above example will output:
|
PHP 5 provides a way for objects to be defined so it is possible to iterate through a list of items, with, for example a foreach statement. By default, all visible properties will be used for the iteration.
Example 19-22. Simple Object Iteration
The above example will output:
|
As the output shows, the foreach iterated through all
visible variables that can be
accessed. To take it a step further you can implement one
of PHP 5's internal interface named
Iterator. This allows the object to decide what and how
the object will be iterated.
Example 19-23. Object Iteration implementing Iterator
The above example will output:
|
You can also define your class so that it doesn't have to define
all the Iterator functions by simply implementing
the PHP 5 IteratorAggregate interface.
Example 19-24. Object Iteration implementing IteratorAggregate
The above example will output:
|
Note: For more examples of iterators, see the SPL Extension.
Patterns are ways to describe best practices and good designs. They show a flexible solution to common programming problems.
The Factory pattern allows for the instantiation of objects at runtime. It is called a Factory Pattern since it is responsible for "manufacturing" an object. A Parameterized Factory receives the name of the class to instantiate as argument.
Example 19-25. Parameterized Factory Method
Defining this method in a class allows drivers to be loaded on the fly. If the Example class was a database abstraction class, loading a MySQL and SQLite driver could be done as follows:
|
The Singleton pattern applies to situations in which there needs to be a single instance of a class. The most common example of this is a database connection. Implementing this pattern allows a programmer to make this single instance easily accessible by many other objects.
Example 19-26. Singleton Function
This allows a single instance of the Example class to be retrieved.
|
The function names __construct, __destruct (see Constructors and Destructors), __call, __get, __set, __isset, __unset (see Overloading), __sleep, __wakeup, __toString, __set_state, __clone and __autoload are magical in PHP classes. You cannot have functions with these names in any of your classes unless you want the magic functionality associated with them.
| Caution |
PHP reserves all function names starting with __ as magical. It is recommended that you do not use function names with __ in PHP unless you want some documented magic functionality. |
serialize() checks if your class has a function with the magic name __sleep. If so, that function is executed prior to any serialization. It can clean up the object and is supposed to return an array with the names of all variables of that object that should be serialized. If the method doesn't return anything then NULL is serialized and E_NOTICE is issued.
The intended use of __sleep is to commit pending data or perform similar cleanup tasks. Also, the function is useful if you have very large objects which do not need to be saved completely.
The __sleep method should return the value to serialize (usually $this), otherwise NULL is serialized.
Conversely, unserialize() checks for the presence of a function with the magic name __wakeup. If present, this function can reconstruct any resources that the object may have.
The intended use of __wakeup is to reestablish any database connections that may have been lost during serialization and perform other reinitialization tasks.
Example 19-27. Sleep and wakeup
|
The __toString method allows a class to decide how it will react when it is converted to a string.
It is worth noting that before PHP 5.2.0 the __toString method was only called when it was directly combined with echo() or print().
This static method is called for classes exported by var_export() since PHP 5.1.0.
The only parameter of this method is an array containing exported properties in the form array('property' => value, ...).
PHP 5 introduces the final keyword, which prevents child classes from overriding a method by prefixing the definition with final. If the class itself is being defined final then it cannot be extended.
Example 19-29. Final methods example
|
Example 19-30. Final class example
|
Creating a copy of an object with fully replicated properties is not always the wanted behavior. A good example of the need for copy constructors, is if you have an object which represents a GTK window and the object holds the resource of this GTK window, when you create a duplicate you might want to create a new window with the same properties and have the new object hold the resource of the new window. Another example is if your object holds a reference to another object which it uses and when you replicate the parent object you want to create a new instance of this other object so that the replica has its own separate copy.
An object copy is created by using the clone keyword (which calls the object's __clone() method if possible). An object's __clone() method cannot be called directly.
When an object is cloned, PHP 5 will perform a shallow copy of all of the object's properties. Any properties that are references to other variables, will remain references. If a __clone() method is defined, then the newly created object's __clone() method will be called, to allow any necessary properties that need to be changed.
Example 19-31. Cloning an object
The above example will output:
|
In PHP 5, object comparison is more complicated than in PHP 4 and more in accordance to what one will expect from an Object Oriented Language (not that PHP 5 is such a language).
When using the comparison operator (==), object variables are compared in a simple manner, namely: Two object instances are equal if they have the same attributes and values, and are instances of the same class.
On the other hand, when using the identity operator (===), object variables are identical if and only if they refer to the same instance of the same class.
An example will clarify these rules.
Example 19-32. Example of object comparison in PHP 5
The above example will output:
|
PHP 5 comes with a complete reflection API that adds the ability to reverse-engineer classes, interfaces, functions and methods as well as extensions. Additionally, the reflection API also offers ways of retrieving doc comments for functions, classes and methods.
The reflection API is an object-oriented extension to the Zend Engine, consisting of the following classes:
<?php
class Reflection { }
interface Reflector { }
class ReflectionException extends Exception { }
class ReflectionFunction extends ReflectionFunctionAbstract implements Reflector { }
class ReflectionParameter implements Reflector { }
class ReflectionMethod extends ReflectionFunctionAbstract implements Reflector { }
class ReflectionClass implements Reflector { }
class ReflectionObject extends ReflectionClass { }
class ReflectionProperty implements Reflector { }
class ReflectionExtension implements Reflector { }
?> |
Note: For details on these classes, have a look at the next chapters.
If we were to execute the code in the example below:
Example 19-33. Basic usage of the reflection API
The above example will output:
|
ReflectionException extends the standard Exception and is thrown by Reflection API. No specific methods or properties are introduced.
The ReflectionFunction class lets you reverse-engineer functions.
<?php
class ReflectionFunction extends ReflectionFunctionAbstract implements Reflector
{
final private __clone()
public void __construct(string name)
public string __toString()
public static string export(string name, bool return)
public string getName()
public bool isInternal()
public bool isUserDefined()
public string getFileName()
public int getStartLine()
public int getEndLine()
public string getDocComment()
public array getStaticVariables()
public mixed invoke(mixed args)
public mixed invokeArgs(array args)
public bool returnsReference()
public ReflectionParameter[] getParameters()
public int getNumberOfParameters()
public int getNumberOfRequiredParameters()
}
?> |
Note: getNumberOfParameters() and getNumberOfRequiredParameters() were added in PHP 5.0.3, while invokeArgs() was added in PHP 5.1.0.
To introspect a function, you will first have to create an instance of the ReflectionFunction class. You can then call any of the above methods on this instance.
Example 19-34. Using the ReflectionFunction class
|
Note: The method invoke() accepts a variable number of arguments which are passed to the function just as in call_user_func().
The ReflectionParameter class retrieves information about a function's or method's parameters.
<?php
class ReflectionParameter implements Reflector
{
final private __clone()
public void __construct(string function, string parameter)
public string __toString()
public static string export(mixed function, mixed parameter, bool return)
public string getName()
public bool isPassedByReference()
public ReflectionClass getDeclaringClass()
public ReflectionClass getClass()
public bool isArray()
public bool allowsNull()
public bool isPassedByReference()
public bool isOptional()
public bool isDefaultValueAvailable()
public mixed getDefaultValue()
}
?> |
Note: getDefaultValue(), isDefaultValueAvailable() and isOptional() were added in PHP 5.0.3, while isArray() was added in PHP 5.1.0.
To introspect function parameters, you will first have to create an instance of the ReflectionFunction or ReflectionMethod classes and then use their getParameters() method to retrieve an array of parameters.
Example 19-35. Using the ReflectionParameter class
|
The ReflectionClass class lets you reverse-engineer classes.
<?php
class ReflectionClass implements Reflector
{
final private __clone()
public void __construct(string name)
public string __toString()
public static string export(mixed class, bool return)
public string getName()
public bool isInternal()
public bool isUserDefined()
public bool isInstantiable()
public bool hasConstant(string name)
public bool hasMethod(string name)
public bool hasProperty(string name)
public string getFileName()
public int getStartLine()
public int getEndLine()
public string getDocComment()
public ReflectionMethod getConstructor()
public ReflectionMethod getMethod(string name)
public ReflectionMethod[] getMethods()
public ReflectionProperty getProperty(string name)
public ReflectionProperty[] getProperties()
public array getConstants()
public mixed getConstant(string name)
public ReflectionClass[] getInterfaces()
public bool isInterface()
public bool isAbstract()
public bool isFinal()
public int getModifiers()
public bool isInstance(stdclass object)
public stdclass newInstance(mixed args)
public stdclass newInstanceArgs(array args)
public ReflectionClass getParentClass()
public bool isSubclassOf(ReflectionClass class)
public array getStaticProperties()
public mixed getStaticPropertyValue(string name [, mixed default])
public void setStaticPropertyValue(string name, mixed value)
public array getDefaultProperties()
public bool isIterateable()
public bool implementsInterface(string name)
public ReflectionExtension getExtension()
public string getExtensionName()
}
?> |
Note: hasConstant(), hasMethod(), hasProperty(), getStaticPropertyValue() and setStaticPropertyValue() were added in PHP 5.1.0, while newInstanceArgs() was added in PHP 5.1.3.
To introspect a class, you will first have to create an instance of the ReflectionClass class. You can then call any of the above methods on this instance.
Example 19-36. Using the ReflectionClass class
|
Note: The method newInstance() accepts a variable number of arguments which are passed to the function just as in call_user_func().
Note: $class = new ReflectionClass('Foo'); $class->isInstance($arg) is equivalent to $arg instanceof Foo or is_a($arg, 'Foo').
The ReflectionMethod class lets you reverse-engineer class methods.
<?php
class ReflectionMethod extends ReflectionFunctionAbstract implements Reflector
{
public void __construct(mixed class, string name)
public string __toString()
public static string export(mixed class, string name, bool return)
public mixed invoke(stdclass object, mixed args)
public mixed invokeArgs(stdclass object, array args)
public bool isFinal()
public bool isAbstract()
public bool isPublic()
public bool isPrivate()
public bool isProtected()
public bool isStatic()
public bool isConstructor()
public bool isDestructor()
public int getModifiers()
public ReflectionClass getDeclaringClass()
// Inherited from ReflectionFunction
final private __clone()
public string getName()
public bool isInternal()
public bool isUserDefined()
public string getFileName()
public int getStartLine()
public int getEndLine()
public string getDocComment()
public array getStaticVariables()
public bool returnsReference()
public ReflectionParameter[] getParameters()
public int getNumberOfParameters()
public int getNumberOfRequiredParameters()
}
?> |
To introspect a method, you will first have to create an instance of the ReflectionMethod class. You can then call any of the above methods on this instance.
Example 19-37. Using the ReflectionMethod class
|
Note: Trying to invoke private, protected or abstract methods will result in an exception being thrown from the invoke() method.
Note: For static methods as seen above, you should pass NULL as the first argument to invoke(). For non-static methods, pass an instance of the class.
The ReflectionProperty class lets you reverse-engineer class properties.
<?php
class ReflectionProperty implements Reflector
{
final private __clone()
public void __construct(mixed class, string name)
public string __toString()
public static string export(mixed class, string name, bool return)
public string getName()
public bool isPublic()
public bool isPrivate()
public bool isProtected()
public bool isStatic()
public bool isDefault()
public int getModifiers()
public mixed getValue(stdclass object)
public void setValue(stdclass object, mixed value)
public ReflectionClass getDeclaringClass()
public string getDocComment()
}
?> |
Note: getDocComment() was added in PHP 5.1.0.
To introspect a property, you will first have to create an instance of the ReflectionProperty class. You can then call any of the above methods on this instance.
Example 19-38. Using the ReflectionProperty class
|
Note: Trying to get or set private or protected class property's values will result in an exception being thrown.
The ReflectionExtension class lets you reverse-engineer extensions. You can retrieve all loaded extensions at runtime using the get_loaded_extensions().
<?php
class ReflectionExtension implements Reflector {
final private __clone()
public void __construct(string name)
public string __toString()
public static string export(string name, bool return)
public string getName()
public string getVersion()
public ReflectionFunction[] getFunctions()
public array getConstants()
public array getINIEntries()
public ReflectionClass[] getClasses()
public array getClassNames()
}
?> |
To introspect an extension, you will first have to create an instance of the ReflectionExtension class. You can then call any of the above methods on this instance.
Example 19-39. Using the ReflectionExtension class
|
In case you want to create specialized versions of the built-in classes (say, for creating colorized HTML when being exported, having easy-access member variables instead of methods or having utility methods), you may go ahead and extend them.
Example 19-40. Extending the built-in classes
|
Note: Caution: If you're overwriting the constructor, remember to call the parent's constructor _before_ any code you insert. Failing to do so will result in the following: Fatal error: Internal error: Failed to retrieve the reflection object
PHP 5 introduces Type Hinting. Functions are now able to force parameters to be objects (by specifying the name of the class in the function prototype) or arrays (since PHP 5.1).
Example 19-41. Type Hinting examples
Failing to satisfy the type hint results in a fatal error.
Type hinting also works with functions:
|
Type Hints can only be of the object and array (since PHP 5.1) type. Traditional type hinting with int and string isn't supported.
PHP 5 has an exception model similar to that of other programming languages. An exception can be thrown, and caught ("catched") within PHP. Code may be surrounded in a try block, to facilitate the catching of potential exceptions. Each try must have at least one corresponding catch block. Multiple catch blocks can be used to catch different classes of exeptions. Normal execution (when no exception is thrown within the try block, or when a catch matching the thrown exception's class is not present) will continue after that last catch block defined in sequence. Exceptions can be thrown (or re-thrown) within a catch block.
When an exception is thrown, code following the statement will not be executed, and PHP will attempt to find the first matching catch block. If an exception is not caught, a PHP Fatal Error will be issued with an "Uncaught Exception ..." message, unless a handler has been defined with set_exception_handler().
Example 20-1. Throwing an Exception
|
A User defined Exception class can be defined by extending the built-in Exception class. The members and properties below, show what is accessible within the child class that derives from the built-in Exception class.
Example 20-2. The Built in Exception class
|
If a class extends the built-in Exception class and re-defines the constructor, it is highly recomended that it also call parent::__construct() to ensure all available data has been properly assigned. The __toString() method can be overriden to provide a custom output when the object is presented as a string.
Example 20-3. Extending the Exception class
|
References in PHP are a means to access the same variable content by different names. They are not like C pointers; instead, they are symbol table aliases. Note that in PHP, variable name and variable content are different, so the same content can have different names. The most close analogy is with Unix filenames and files - variable names are directory entries, while variable contents is the file itself. References can be thought of as hardlinking in Unix filesystem.
PHP references allow you to make two variables to refer to the same content. Meaning, when you do:
it means that$a and $b
point to the same content.
Note:
$aand$bare completely equal here, that's not$ais pointing to$bor vice versa, that's$aand$bpointing to the same place.
Note: If array with references is copied, its values are not dereferenced. This is valid also for arrays passed by value to functions.
Note: If you assign, pass or return an undefined variable by reference, it will get created.
The same syntax can be used with functions, that return references, and with new operator (in PHP 4.0.4 and later):
Since PHP 5, new return reference automatically so using =& in this context is deprecated and produces E_STRICT level message.Note: Not using the & operator causes a copy of the object to be made. If you use $this in the class it will operate on the current instance of the class. The assignment without & will copy the instance (i.e. the object) and $this will operate on the copy, which is not always what is desired. Usually you want to have a single instance to work with, due to performance and memory consumption issues.
While you can use the @ operator to mute any errors in the constructor when using it as @new, this does not work when using the &new statement. This is a limitation of the Zend Engine and will therefore result in a parser error.
| Warning | ||
If you assign a reference to a variable declared global
inside a function, the reference will be visible only inside the function.
You can avoid this by using the
|
Note: If you assign a value to a variable with references in a foreach statement, the references are modified too.
The second thing references do is to pass variables by-reference. This is done by making a local variable in a function and a variable in the calling scope reference to the same content. Example:
will make$a to be 6. This happens because in
the function foo the variable
$var refers to the same content as
$a. See also more detailed explanations about passing by reference.
The third thing reference can do is return by reference.
As said before, references aren't pointers. That means, the following construct won't do what you expect:
What happens is that $var in
foo will be bound with
$bar in caller, but then it will be
re-bound with $GLOBALS["baz"]. There's no way
to bind $bar in the calling scope to something else
using the reference mechanism, since $bar is not
available in the function foo (it is represented by
$var, but $var has only
variable contents and not name-to-value binding in the calling
symbol table).
You can use returning
references to reference variables selected by the function.
You can pass variable to function by reference, so that function could modify its arguments. The syntax is as follows:
Note that there's no reference sign on function call - only on function definition. Function definition alone is enough to correctly pass the argument by reference. In recent versions of PHP you will get a warning saying that "Call-time pass-by-reference" is deprecated when you use a & in foo(&$a);.The following things can be passed by reference:
Variable, i.e. foo($a)
New statement, i.e. foo(new foobar())
Reference, returned from a function, i.e.:
See also explanations about returning by reference.Any other expression should not be passed by reference, as the result is undefined. For example, the following examples of passing by reference are invalid:
These requirements are for PHP 4.0.4 and later.Returning by-reference is useful when you want to use a function to find which variable a reference should be bound to. Do not use return-by-reference to increase performance, the engine is smart enough to optimize this on its own. Only return references when you have a valid technical reason to do it! To return references, use this syntax:
<?php
function &find_var($param)
{
/* ...code... */
return $found_var;
}
$foo =& find_var($bar);
$foo->x = 2;
?> |
find_var function would be set, not the
copy, as it would be without using reference syntax.
Note: Unlike parameter passing, here you have to use & in both places - to indicate that you return by-reference, not a copy as usual, and to indicate that reference binding, rather than usual assignment, should be done for
$foo.
Note: If you try to return a reference from a function with the syntax: return ($found_var); this will not work as you are attempting to return the result of an expression, and not a variable, by reference. You can only return variables by reference from a function - nothing else. E_NOTICE error is issued since PHP 4.4.0 and PHP 5.1.0 if the code tries to return a dynamic expression or a result of the new operator.
When you unset the reference, you just break the binding between variable name and variable content. This does not mean that variable content will be destroyed. For example:
won't unset$b, just $a.
Again, it might be useful to think about this as analogous to Unix unlink call.
Many syntax constructs in PHP are implemented via referencing mechanisms, so everything told above about reference binding also apply to these constructs. Some constructs, like passing and returning by-reference, are mentioned above. Other constructs that use references are:
When you declare variable as global $var you are in fact creating reference to a global variable. That means, this is the same as:
That means, for example, that unsetting $var
won't unset global variable.
PHP is a powerful language and the interpreter, whether included in a web server as a module or executed as a separate CGI binary, is able to access files, execute commands and open network connections on the server. These properties make anything run on a web server insecure by default. PHP is designed specifically to be a more secure language for writing CGI programs than Perl or C, and with correct selection of compile-time and runtime configuration options, and proper coding practices, it can give you exactly the combination of freedom and security you need.
As there are many different ways of utilizing PHP, there are many configuration options controlling its behaviour. A large selection of options guarantees you can use PHP for a lot of purposes, but it also means there are combinations of these options and server configurations that result in an insecure setup.
The configuration flexibility of PHP is equally rivalled by the code flexibility. PHP can be used to build complete server applications, with all the power of a shell user, or it can be used for simple server-side includes with little risk in a tightly controlled environment. How you build that environment, and how secure it is, is largely up to the PHP developer.
This chapter starts with some general security advice, explains the different configuration option combinations and the situations they can be safely used, and describes different considerations in coding for different levels of security.
A completely secure system is a virtual impossibility, so an approach often used in the security profession is one of balancing risk and usability. If every variable submitted by a user required two forms of biometric validation (such as a retinal scan and a fingerprint), you would have an extremely high level of accountability. It would also take half an hour to fill out a fairly complex form, which would tend to encourage users to find ways of bypassing the security.
The best security is often unobtrusive enough to suit the requirements without the user being prevented from accomplishing their work, or over-burdening the code author with excessive complexity. Indeed, some security attacks are merely exploits of this kind of overly built security, which tends to erode over time.
A phrase worth remembering: A system is only as good as the weakest link in a chain. If all transactions are heavily logged based on time, location, transaction type, etc. but the user is only verified based on a single cookie, the validity of tying the users to the transaction log is severely weakened.
When testing, keep in mind that you will not be able to test all possibilities for even the simplest of pages. The input you may expect will be completely unrelated to the input given by a disgruntled employee, a cracker with months of time on their hands, or a housecat walking across the keyboard. This is why it's best to look at the code from a logical perspective, to discern where unexpected data can be introduced, and then follow how it is modified, reduced, or amplified.
The Internet is filled with people trying to make a name for themselves by breaking your code, crashing your site, posting inappropriate content, and otherwise making your day interesting. It doesn't matter if you have a small or large site, you are a target by simply being online, by having a server that can be connected to. Many cracking programs do not discern by size, they simply trawl massive IP blocks looking for victims. Try not to become one.
Using PHP as a CGI binary is an option for setups that for some reason do not wish to integrate PHP as a module into server software (like Apache), or will use PHP with different kinds of CGI wrappers to create safe chroot and setuid environments for scripts. This setup usually involves installing executable PHP binary to the web server cgi-bin directory. CERT advisory CA-96.11 recommends against placing any interpreters into cgi-bin. Even if the PHP binary can be used as a standalone interpreter, PHP is designed to prevent the attacks this setup makes possible:
Accessing system files: http://my.host/cgi-bin/php?/etc/passwd
The query information in a URL after the question mark (?) is passed as command line arguments to the interpreter by the CGI interface. Usually interpreters open and execute the file specified as the first argument on the command line.
When invoked as a CGI binary, PHP refuses to interpret the command line arguments.
Accessing any web document on server: http://my.host/cgi-bin/php/secret/doc.html
The path information part of the URL after the PHP binary name, /secret/doc.html is conventionally used to specify the name of the file to be opened and interpreted by the CGI program. Usually some web server configuration directives (Apache: Action) are used to redirect requests to documents like http://my.host/secret/script.php to the PHP interpreter. With this setup, the web server first checks the access permissions to the directory /secret, and after that creates the redirected request http://my.host/cgi-bin/php/secret/script.php. Unfortunately, if the request is originally given in this form, no access checks are made by web server for file /secret/script.php, but only for the /cgi-bin/php file. This way any user able to access /cgi-bin/php is able to access any protected document on the web server.
In PHP, compile-time configuration option --enable-force-cgi-redirect and runtime configuration directives doc_root and user_dir can be used to prevent this attack, if the server document tree has any directories with access restrictions. See below for full the explanation of the different combinations.
If your server does not have any content that is not restricted by password or ip based access control, there is no need for these configuration options. If your web server does not allow you to do redirects, or the server does not have a way to communicate to the PHP binary that the request is a safely redirected request, you can specify the option --enable-force-cgi-redirect to the configure script. You still have to make sure your PHP scripts do not rely on one or another way of calling the script, neither by directly http://my.host/cgi-bin/php/dir/script.php nor by redirection http://my.host/dir/script.php.
Redirection can be configured in Apache by using AddHandler and Action directives (see below).
This compile-time option prevents anyone from calling PHP directly with a URL like http://my.host/cgi-bin/php/secretdir/script.php. Instead, PHP will only parse in this mode if it has gone through a web server redirect rule.
Usually the redirection in the Apache configuration is done with the following directives:
Action php-script /cgi-bin/php AddHandler php-script .php |
This option has only been tested with the Apache web server, and
relies on Apache to set the non-standard CGI environment variable
REDIRECT_STATUS on redirected requests. If your
web server does not support any way of telling if the request is
direct or redirected, you cannot use this option and you must use
one of the other ways of running the CGI version documented
here.
To include active content, like scripts and executables, in the web server document directories is sometimes considered an insecure practice. If, because of some configuration mistake, the scripts are not executed but displayed as regular HTML documents, this may result in leakage of intellectual property or security information like passwords. Therefore many sysadmins will prefer setting up another directory structure for scripts that are accessible only through the PHP CGI, and therefore always interpreted and not displayed as such.
Also if the method for making sure the requests are not redirected, as described in the previous section, is not available, it is necessary to set up a script doc_root that is different from web document root.
You can set the PHP script document root by the configuration
directive doc_root in the
configuration file, or
you can set the environment variable
PHP_DOCUMENT_ROOT. If it is set, the CGI version
of PHP will always construct the file name to open with this
doc_root and the path information in the
request, so you can be sure no script is executed outside this
directory (except for user_dir
below).
Another option usable here is user_dir. When user_dir is unset,
only thing controlling the opened file name is
doc_root. Opening a URL like http://my.host/~user/doc.php does not
result in opening a file under users home directory, but a file
called ~user/doc.php under
doc_root (yes, a directory name starting with a tilde
[~]).
If user_dir is set to for example public_php, a request like http://my.host/~user/doc.php will open a file called doc.php under the directory named public_php under the home directory of the user. If the home of the user is /home/user, the file executed is /home/user/public_php/doc.php.
user_dir expansion happens regardless of
the doc_root setting, so you can control
the document root and user directory access
separately.
A very secure option is to put the PHP parser binary somewhere outside of the web tree of files. In /usr/local/bin, for example. The only real downside to this option is that you will now have to put a line similar to:
as the first line of any file containing PHP tags. You will also need to make the file executable. That is, treat it exactly as you would treat any other CGI script written in Perl or sh or any other common scripting language which uses the #! shell-escape mechanism for launching itself.
To get PHP to handle PATH_INFO and
PATH_TRANSLATED information correctly with this
setup, the PHP parser should be compiled with the --enable-discard-path
configure option.
When PHP is used as an Apache module it inherits Apache's user permissions (typically those of the "nobody" user). This has several impacts on security and authorization. For example, if you are using PHP to access a database, unless that database has built-in access control, you will have to make the database accessible to the "nobody" user. This means a malicious script could access and modify the database, even without a username and password. It's entirely possible that a web spider could stumble across a database administrator's web page, and drop all of your databases. You can protect against this with Apache authorization, or you can design your own access model using LDAP, .htaccess files, etc. and include that code as part of your PHP scripts.
Often, once security is established to the point where the PHP user (in this case, the apache user) has very little risk attached to it, it is discovered that PHP is now prevented from writing any files to user directories. Or perhaps it has been prevented from accessing or changing databases. It has equally been secured from writing good and bad files, or entering good and bad database transactions.
A frequent security mistake made at this point is to allow apache root permissions, or to escalate apache's abilities in some other way.
Escalating the Apache user's permissions to root is extremely dangerous and may compromise the entire system, so sudo'ing, chroot'ing, or otherwise running as root should not be considered by those who are not security professionals.
There are some simpler solutions. By using open_basedir you can control and restrict what directories are allowed to be used for PHP. You can also set up apache-only areas, to restrict all web based activity to non-user, or non-system, files.
PHP is subject to the security built into most server systems with respect to permissions on a file and directory basis. This allows you to control which files in the filesystem may be read. Care should be taken with any files which are world readable to ensure that they are safe for reading by all users who have access to that filesystem.
Since PHP was designed to allow user level access to the filesystem, it's entirely possible to write a PHP script that will allow you to read system files such as /etc/passwd, modify your ethernet connections, send massive printer jobs out, etc. This has some obvious implications, in that you need to ensure that the files that you read from and write to are the appropriate ones.
Consider the following script, where a user indicates that they'd like to delete a file in their home directory. This assumes a situation where a PHP web interface is regularly used for file management, so the Apache user is allowed to delete files in the user home directories.
Example 26-2. ... A filesystem attack
|
Only allow limited permissions to the PHP web user binary.
Check all variables which are submitted.
Example 26-3. More secure file name checking
|
Example 26-4. More secure file name checking
|
Depending on your operating system, there are a wide variety of files which you should be concerned about, including device entries (/dev/ or COM1), configuration files (/etc/ files and the .ini files), well known file storage areas (/home/, My Documents), etc. For this reason, it's usually easier to create a policy where you forbid everything except for what you explicitly allow.
As PHP uses the underlying C functions for filesystem related operations, it may handle null bytes in a quite unexpected way. As null bytes denote the end of a string in C, strings containing them won't be considered entirely but rather only until a null byte occurs. The following example shows a vulnerable code that demonstrates this problem:
Example 26-5. Script vulnerable to null bytes
|
Therefore, any tainted string that is used in a filesystem operation should always be validated properly. Here is a better version of the previous example:
Nowadays, databases are cardinal components of any web based application by enabling websites to provide varying dynamic content. Since very sensitive or secret information can be stored in a database, you should strongly consider protecting your databases.
To retrieve or to store any information you need to connect to the database, send a legitimate query, fetch the result, and close the connection. Nowadays, the commonly used query language in this interaction is the Structured Query Language (SQL). See how an attacker can tamper with an SQL query.
As you can surmise, PHP cannot protect your database by itself. The following sections aim to be an introduction into the very basics of how to access and manipulate databases within PHP scripts.
Keep in mind this simple rule: defense in depth. The more places you take action to increase the protection of your database, the less probability of an attacker succeeding in exposing or abusing any stored information. Good design of the database schema and the application deals with your greatest fears.
The first step is always to create the database, unless you want to use one from a third party. When a database is created, it is assigned to an owner, who executed the creation statement. Usually, only the owner (or a superuser) can do anything with the objects in that database, and in order to allow other users to use it, privileges must be granted.
Applications should never connect to the database as its owner or a superuser, because these users can execute any query at will, for example, modifying the schema (e.g. dropping tables) or deleting its entire content.
You may create different database users for every aspect of your application with very limited rights to database objects. The most required privileges should be granted only, and avoid that the same user can interact with the database in different use cases. This means that if intruders gain access to your database using your applications credentials, they can only effect as many changes as your application can.
You are encouraged not to implement all the business logic in the web application (i.e. your script), instead do it in the database schema using views, triggers or rules. If the system evolves, new ports will be intended to open to the database, and you have to re-implement the logic in each separate database client. Over and above, triggers can be used to transparently and automatically handle fields, which often provides insight when debugging problems with your application or tracing back transactions.
You may want to establish the connections over SSL to encrypt client/server communications for increased security, or you can use ssh to encrypt the network connection between clients and the database server. If either of these is used, then monitoring your traffic and gaining information about your database will be difficult for a would-be attacker.
SSL/SSH protects data travelling from the client to the server, SSL/SSH does not protect the persistent data stored in a database. SSL is an on-the-wire protocol.
Once an attacker gains access to your database directly (bypassing the webserver), the stored sensitive data may be exposed or misused, unless the information is protected by the database itself. Encrypting the data is a good way to mitigate this threat, but very few databases offer this type of data encryption.
The easiest way to work around this problem is to first create your own encryption package, and then use it from within your PHP scripts. PHP can assist you in this with several extensions, such as Mcrypt and Mhash, covering a wide variety of encryption algorithms. The script encrypts the data before inserting it into the database, and decrypts it when retrieving. See the references for further examples of how encryption works.
In case of truly hidden data, if its raw representation is not needed (i.e. not be displayed), hashing may also be taken into consideration. The well-known example for the hashing is storing the MD5 hash of a password in a database, instead of the password itself. See also crypt() and md5().
Example 27-1. Using hashed password field
|
Many web developers are unaware of how SQL queries can be tampered with, and assume that an SQL query is a trusted command. It means that SQL queries are able to circumvent access controls, thereby bypassing standard authentication and authorization checks, and sometimes SQL queries even may allow access to host operating system level commands.
Direct SQL Command Injection is a technique where an attacker creates or alters existing SQL commands to expose hidden data, or to override valuable ones, or even to execute dangerous system level commands on the database host. This is accomplished by the application taking user input and combining it with static parameters to build a SQL query. The following examples are based on true stories, unfortunately.
Owing to the lack of input validation and connecting to the database on behalf of a superuser or the one who can create users, the attacker may create a superuser in your database.
$offset
is encoded into the URL. The script expects that the incoming
$offset is a decimal number. However, what if someone tries to
break in by appending a urlencode()'d form of the
following to the URL
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
select 'crack', usesysid, 't','t','crack'
from pg_shadow where usename='postgres';
-- |
Note: It is common technique to force the SQL parser to ignore the rest of the query written by the developer with -- which is the comment sign in SQL.
A feasible way to gain passwords is to circumvent your search result pages. The only thing the attacker needs to do is to see if there are any submitted variables used in SQL statements which are not handled properly. These filters can be set commonly in a preceding form to customize WHERE, ORDER BY, LIMIT and OFFSET clauses in SELECT statements. If your database supports the UNION construct, the attacker may try to append an entire query to the original one to list passwords from an arbitrary table. Using encrypted password fields is strongly encouraged.
$query, the query beast awakened.
SQL UPDATE's are also susceptible to attack. These queries are also threatened by chopping and appending an entirely new query to it. But the attacker might fiddle with the SET clause. In this case some schema information must be possessed to manipulate the query successfully. This can be acquired by examining the form variable names, or just simply brute forcing. There are not so many naming conventions for fields storing passwords or usernames.
$uid to
change the admin's password, or simply sets $pwd to
"hehehe', admin='yes', trusted=100 " (with a trailing
space) to gain more privileges. Then, the query will be twisted:
<?php // $uid == ' or uid like'%admin%'; -- $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --"; // $pwd == "hehehe', admin='yes', trusted=100 " $query = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE ...;"; ?> |
A frightening example how operating system level commands can be accessed on some database hosts.
$prod, then the $query will be:
<?php
$query = "SELECT * FROM products
WHERE id LIKE '%a%'
exec master..xp_cmdshell 'net user test testpass /ADD'--";
$result = mssql_query($query);
?> |
Note: Some of the examples above is tied to a specific database server. This does not mean that a similar attack is impossible against other products. Your database server may be similarly vulnerable in another manner.
You may plead that the attacker must possess a piece of information about the database schema in most examples. You are right, but you never know when and how it can be taken out, and if it happens, your database may be exposed. If you are using an open source, or publicly available database handling package, which may belong to a content management system or forum, the intruders easily produce a copy of a piece of your code. It may be also a security risk if it is a poorly designed one.
These attacks are mainly based on exploiting the code not being written with security in mind. Never trust any kind of input, especially that which comes from the client side, even though it comes from a select box, a hidden input field or a cookie. The first example shows that such a blameless query can cause disasters.
Never connect to the database as a superuser or as the database owner. Use always customized users with very limited privileges.
Check if the given input has the expected data type. PHP has a wide range of input validating functions, from the simplest ones found in Variable Functions and in Character Type Functions (e.g. is_numeric(), ctype_digit() respectively) and onwards to the Perl compatible Regular Expressions support.
If the application waits for numerical input, consider verifying data with is_numeric(), or silently change its type using settype(), or use its numeric representation by sprintf().
Example 27-6. A more secure way to compose a query for paging
|
Quote each non numeric user supplied value that is passed to the database with the database-specific string escape function (e.g. mysql_escape_string(), sql_escape_string(), etc.). If a database-specific string escape mechanism is not available, the addslashes() and str_replace() functions may be useful (depending on database type). See the first example. As the example shows, adding quotes to the static part of the query is not enough, making this query easily crackable.
Do not print out any database specific information, especially about the schema, by fair means or foul. See also Error Reporting and Error Handling and Logging Functions.
You may use stored procedures and previously defined cursors to abstract data access so that users do not directly access tables or views, but this solution has another impacts.
Besides these, you benefit from logging queries either within your script or by the database itself, if it supports logging. Obviously, the logging is unable to prevent any harmful attempt, but it can be helpful to trace back which application has been circumvented. The log is not useful by itself, but through the information it contains. More detail is generally better than less.
With PHP security, there are two sides to error reporting. One is beneficial to increasing security, the other is detrimental.
A standard attack tactic involves profiling a system by feeding it improper data, and checking for the kinds, and contexts, of the errors which are returned. This allows the system cracker to probe for information about the server, to determine possible weaknesses. For example, if an attacker had gleaned information about a page based on a prior form submission, they may attempt to override variables, or modify them:
The PHP errors which are normally returned can be quite helpful to a developer who is trying to debug a script, indicating such things as the function or file that failed, the PHP file it failed in, and the line number which the failure occurred in. This is all information that can be exploited. It is not uncommon for a php developer to use show_source(), highlight_string(), or highlight_file() as a debugging measure, but in a live site, this can expose hidden variables, unchecked syntax, and other dangerous information. Especially dangerous is running code from known sources with built-in debugging handlers, or using common debugging techniques. If the attacker can determine what general technique you are using, they may try to brute-force a page, by sending various common debugging strings:
Regardless of the method of error handling, the ability to probe a system for errors leads to providing an attacker with more information.
For example, the very style of a generic PHP error indicates a system is running PHP. If the attacker was looking at an .html page, and wanted to probe for the back-end (to look for known weaknesses in the system), by feeding it the wrong data they may be able to determine that a system was built with PHP.
A function error can indicate whether a system may be running a specific database engine, or give clues as to how a web page or programmed or designed. This allows for deeper investigation into open database ports, or to look for specific bugs or weaknesses in a web page. By feeding different pieces of bad data, for example, an attacker can determine the order of authentication in a script, (from the line number errors) as well as probe for exploits that may be exploited in different locations in the script.
A filesystem or general PHP error can indicate what permissions the web server has, as well as the structure and organization of files on the web server. Developer written error code can aggravate this problem, leading to easy exploitation of formerly "hidden" information.
There are three major solutions to this issue. The first is to scrutinize all functions, and attempt to compensate for the bulk of the errors. The second is to disable error reporting entirely on the running code. The third is to use PHP's custom error handling functions to create your own error handler. Depending on your security policy, you may find all three to be applicable to your situation.
One way of catching this issue ahead of time is to make use of PHP's own error_reporting(), to help you secure your code and find variable usage that may be dangerous. By testing your code, prior to deployment, with E_ALL, you can quickly find areas where your variables may be open to poisoning or modification in other ways. Once you are ready for deployment, you should either disable error reporting completely by setting error_reporting() to 0, or turn off the error display using the php.ini option display_errors, to insulate your code from probing. If you choose to do the latter, you should also define the path to your log file using the error_log ini directive, and turn log_errors on.
Perhaps the most controversial change in PHP is when the default value for the PHP directive register_globals went from ON to OFF in PHP 4.2.0. Reliance on this directive was quite common and many people didn't even know it existed and assumed it's just how PHP works. This page will explain how one can write insecure code with this directive but keep in mind that the directive itself isn't insecure but rather it's the misuse of it.
When on, register_globals will inject your scripts with all sorts of variables, like request variables from HTML forms. This coupled with the fact that PHP doesn't require variable initialization means writing insecure code is that much easier. It was a difficult decision, but the PHP community decided to disable this directive by default. When on, people use variables yet really don't know for sure where they come from and can only assume. Internal variables that are defined in the script itself get mixed up with request data sent by users and disabling register_globals changes this. Let's demonstrate with an example misuse of register_globals:
Example 29-1. Example misuse with register_globals = on
|
When register_globals = on, our logic above may be compromised. When
off, $authorized can't be set via request so it'll
be fine, although it really is generally a good programming practice to
initialize variables first. For example, in our example above we might
have first done $authorized = false. Doing this
first means our above code would work with register_globals on or off as
users by default would be unauthorized.
Another example is that of sessions.
When register_globals = on, we could also use
$username in our example below but again you must
realize that $username could also come from other
means, such as GET (through the URL).
Example 29-2. Example use of sessions with register_globals on or off
|
It's even possible to take preventative measures to warn when forging is
being attempted. If you know ahead of time exactly where a variable
should be coming from, you can check to see if the submitted data is
coming from an inappropriate kind of submission. While it doesn't
guarantee that data has not been forged, it does require an attacker to
guess the right kind of forging. If you don't care where the request
data comes from, you can use $_REQUEST as it contains
a mix of GET, POST and COOKIE data. See also the manual section on
using variables from outside
of PHP.
Example 29-3. Detecting simple variable poisoning
|
Of course, simply turning off register_globals does not mean your code is secure. For every piece of data that is submitted, it should also be checked in other ways. Always validate your user data and initialize your variables! To check for uninitialized variables you may turn up error_reporting() to show E_NOTICE level errors.
For information about emulating register_globals being On or Off, see this FAQ.
Superglobals: availability note: Since PHP 4.1.0, superglobal arrays such as
$_GET,$_POST, and$_SERVER, etc. have been available. For more information, read the manual section on superglobals
The greatest weakness in many PHP programs is not inherent in the language itself, but merely an issue of code not being written with security in mind. For this reason, you should always take the time to consider the implications of a given piece of code, to ascertain the possible damage if an unexpected variable is submitted to it.
Example 30-1. Dangerous Variable Usage
|
You should always carefully examine your code to make sure that any variables being submitted from a web browser are being properly checked, and ask yourself the following questions:
Will this script only affect the intended files?
Can unusual or undesirable data be acted upon?
Can this script be used in unintended ways?
Can this be used in conjunction with other scripts in a negative manner?
Will any transactions be adequately logged?
By adequately asking these questions while writing the script, rather than later, you prevent an unfortunate re-write when you need to increase your security. By starting out with this mindset, you won't guarantee the security of your system, but you can help improve it.
You may also want to consider turning off register_globals, magic_quotes, or other convenience settings which may confuse you as to the validity, source, or value of a given variable. Working with PHP in error_reporting(E_ALL) mode can also help warn you about variables being used before they are checked or initialized (so you can prevent unusual data from being operated upon).
Magic Quotes is a process that automagically escapes incoming data to the PHP script. It's preferred to code with magic quotes off and to instead escape the data at runtime, as needed.
When on, all ' (single-quote), " (double quote), \ (backslash) and NULL characters are escaped with a backslash automatically. This is identical to what addslashes() does.
There are three magic quote directives:
Affects HTTP Request data (GET, POST, and COOKIE). Cannot be set at runtime, and defaults to on in PHP.
See also get_magic_quotes_gpc().
If enabled, most functions that return data from an external source, including databases and text files, will have quotes escaped with a backslash. Can be set at runtime, and defaults to off in PHP.
See also set_magic_quotes_runtime() and get_magic_quotes_runtime().
If enabled, a single-quote is escaped with a single-quote instead of a backslash. If on, it completely overrides magic_quotes_gpc. Having both directives enabled means only single quotes are escaped as ''. Double quotes, backslashes and NULL's will remain untouched and unescaped.
See also ini_get() for retrieving its value.
Useful for beginners
Magic quotes are implemented in PHP to help code written by beginners from being dangerous. Although SQL Injection is still possible with magic quotes on, the risk is reduced.
Convenience
For inserting data into a database, magic quotes essentially runs addslashes() on all Get, Post, and Cookie data, and does so automagically.
Portability
Assuming it to be on, or off, affects portability. Use get_magic_quotes_gpc() to check for this, and code accordingly.
Performance
Because not every piece of escaped data is inserted into a database, there is a performance loss for escaping all this data. Simply calling on the escaping functions (like addslashes()) at runtime is more efficient.
Although php.ini-dist enables these directives by default, php.ini-recommended disables it. This recommendation is mainly due to performance reasons.
Inconvenience
Because not all data needs escaping, it's often annoying to see escaped data where it shouldn't be. For example, emailing from a form, and seeing a bunch of \' within the email. To fix, this may require excessive use of stripslashes().
The magic_quotes_gpc directive may only be disabled at the system level, and not at runtime. In otherwords, use of ini_set() is not an option.
Example 31-1. Disabling magic quotes server side An example that sets the value of these directives to Off in php.ini. For additional details, read the manual section titled How to change configuration settings.
If access to the server configuration is unavailable, use of .htaccess is also an option. For example:
|
In the interest of writing portable code (code that works in any environment), like if setting at the server level is not possible, here's an example to disable magic_quotes_gpc at runtime. This method is inefficient so it's preferred to instead set the appropriate directives elsewhere.
Example 31-2. Disabling magic quotes at runtime
|
In general, security by obscurity is one of the weakest forms of security. But in some cases, every little bit of extra security is desirable.
A few simple techniques can help to hide PHP, possibly slowing down an attacker who is attempting to discover weaknesses in your system. By setting expose_php = off in your php.ini file, you reduce the amount of information available to them.
Another tactic is to configure web servers such as apache to parse different filetypes through PHP, either with an .htaccess directive, or in the apache configuration file itself. You can then use misleading file extensions:
PHP, like any other large system, is under constant scrutiny and improvement. Each new version will often include both major and minor changes to enhance security and repair any flaws, configuration mishaps, and other issues that will affect the overall security and stability of your system.
Like other system-level scripting languages and programs, the best approach is to update often, and maintain awareness of the latest versions and their changes.
The HTTP Authentication hooks in PHP are only available when it is
running as an Apache module and is hence not available in the CGI version.
In an Apache module PHP script, it is possible to use the
header() function to send an "Authentication Required"
message to the client browser causing it to pop up a Username/Password
input window. Once the user has filled in a username and a password,
the URL containing the PHP script will be called again with the
predefined variables
PHP_AUTH_USER, PHP_AUTH_PW,
and AUTH_TYPE set to the user name, password and
authentication type respectively. These predefined variables are found
in the $_SERVER and
$HTTP_SERVER_VARS arrays. Both "Basic" and "Digest"
(since PHP 5.1.0) authentication methods are supported. See the
header() function for more information.
PHP Version Note: Superglobals, such as $_SERVER, became available in PHP 4.1.0.
$HTTP_SERVER_VARShas been available since PHP 3.
An example script fragment which would force client authentication on a page is as follows:
Example 34-1. Basic HTTP Authentication example
|
Example 34-2. Digest HTTP Authentication example This example shows you how to implement a simple Digest HTTP authentication script. For more information read the RFC 2617.
|
Compatibility Note: Please be careful when coding the HTTP header lines. In order to guarantee maximum compatibility with all clients, the keyword "Basic" should be written with an uppercase "B", the realm string must be enclosed in double (not single) quotes, and exactly one space should precede the 401 code in the HTTP/1.0 401 header line. Authentication parameters have to be comma-separated as seen in the digest example above.
Instead of simply printing out PHP_AUTH_USER
and PHP_AUTH_PW, as done in the above example,
you may want to check the username and password for validity.
Perhaps by sending a query to a database, or by looking up the
user in a dbm file.
Watch out for buggy Internet Explorer browsers out there. They seem very picky about the order of the headers. Sending the WWW-Authenticate header before the HTTP/1.0 401 header seems to do the trick for now.
As of PHP 4.3.0, in order to prevent someone from writing a script which
reveals the password for a page that was authenticated through a
traditional external mechanism, the PHP_AUTH variables will not be
set if external authentication is enabled for that particular
page and safe mode is enabled. Regardless,
REMOTE_USER can be used
to identify the externally-authenticated user. So, you can use
$_SERVER['REMOTE_USER'].
Configuration Note: PHP uses the presence of an AuthType directive to determine whether external authentication is in effect.
Note, however, that the above does not prevent someone who controls a non-authenticated URL from stealing passwords from authenticated URLs on the same server.
Both Netscape Navigator and Internet Explorer will clear the local browser window's authentication cache for the realm upon receiving a server response of 401. This can effectively "log out" a user, forcing them to re-enter their username and password. Some people use this to "time out" logins, or provide a "log-out" button.
Example 34-3. HTTP Authentication example forcing a new name/password
|
This behavior is not required by the HTTP Basic authentication standard, so you should never depend on this. Testing with Lynx has shown that Lynx does not clear the authentication credentials with a 401 server response, so pressing back and then forward again will open the resource as long as the credential requirements haven't changed. The user can press the '_' key to clear their authentication information, however.
Also note that until PHP 4.3.3, HTTP Authentication did not work using Microsoft's IIS server with the CGI version of PHP due to a limitation of IIS. In order to get it to work in PHP 4.3.3+, you must edit your IIS configuration "Directory Security". Click on "Edit" and only check "Anonymous Access", all other fields should be left unchecked.
Another limitation is if you're using the IIS module (ISAPI) and PHP 4, you may not use the PHP_AUTH_* variables but instead, the variable HTTP_AUTHORIZATION is available. For example, consider the following code: list($user, $pw) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));
IIS Note:: For HTTP Authentication to work with IIS, the PHP directive cgi.rfc2616_headers must be set to 0 (the default value).
Note: If safe mode is enabled, the uid of the script is added to the realm part of the WWW-Authenticate header.
PHP transparently supports HTTP cookies. Cookies are a mechanism for storing data in the remote browser and thus tracking or identifying return users. You can set cookies using the setcookie() or setrawcookie() function. Cookies are part of the HTTP header, so setcookie() must be called before any output is sent to the browser. This is the same limitation that header() has. You can use the output buffering functions to delay the script output until you have decided whether or not to set any cookies or send any headers.
Any cookies sent to you from the client will automatically be included into a $_COOKIE auto-global array if variables_order contains "C". If you wish to assign multiple values to a single cookie, just add [] to the cookie name.
Depending on register_globals,
regular PHP variables can be created from cookies. However it's not
recommended to rely on them as this feature is often turned off for the
sake of security.
$HTTP_COOKIE_VARS is also set in earlier versions of PHP
when the track_vars configuration
variable is set. (This setting is always on since PHP 4.0.3.)
For more details, including notes on browser bugs, see the setcookie() and setrawcookie() function.
Session support in PHP consists of a way to preserve certain data across subsequent accesses. This enables you to build more customized applications and increase the appeal of your web site. All information is in the Session reference section.
XForms defines a variation on traditional webforms which allows them to be used on a wider variety of platforms and browsers or even non-traditional media such as PDF documents.
The first key difference in XForms is how the form is sent to the client. XForms for HTML Authors contains a detailed description of how to create XForms, for the purpose of this tutorial we'll only be looking at a simple example.
Example 37-1. A simple XForms search form
|
The above form displays a text input box (named q),
and a submit button. When the submit button is clicked, the form will be
sent to the page referred to by action.
Here's where it starts to look different from your web application's point of view. In a normal HTML form, the data would be sent as application/x-www-form-urlencoded, in the XForms world however, this information is sent as XML formatted data.
If you're choosing to work with XForms then you probably want that data as
XML, in that case, look in $HTTP_RAW_POST_DATA where
you'll find the XML document generated by the browser which you can pass
into your favorite XSLT engine or document parser.
If you're not interested in formatting and just want your data to be loaded
into the traditional $_POST variable, you can instruct
the client browser to send it as application/x-www-form-urlencoded
by changing the method attribute to
urlencoded-post.
Example 37-2. Using an XForm to populate
|
Note: As of this writing, many browsers do not support XForms. Check your browser version if the above examples fails.
This feature lets people upload both text and binary files. With PHP's authentication and file manipulation functions, you have full control over who is allowed to upload and what is to be done with the file once it has been uploaded.
PHP is capable of receiving file uploads from any RFC-1867 compliant browser (which includes Netscape Navigator 3 or later, Microsoft Internet Explorer 3 with a patch from Microsoft, or later without a patch).
Related Configurations Note: See also the file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size and max_input_time directives in php.ini
PHP also supports PUT-method file uploads as used by Netscape Composer and W3C's Amaya clients. See the PUT Method Support for more details.
Example 38-1. File Upload Form A file upload screen can be built by creating a special form which looks something like this:
The __URL__ in the above example should be replaced, and point to a PHP file. The MAX_FILE_SIZE hidden field (measured in bytes) must precede the file input field, and its value is the maximum filesize accepted by PHP. Fooling this setting on the browser side is quite easy, so never rely on files with a greater size being blocked by this feature. The PHP settings for maximum-size, however, cannot be fooled. This form element should always be used as it saves users the trouble of waiting for a big file being transferred only to find that it was too big and the transfer failed. |
Note: Be sure your file upload form has attribute enctype="multipart/form-data" otherwise the file upload will not work.
The global $_FILES
exists as of PHP 4.1.0 (Use $HTTP_POST_FILES
instead if using an earlier version).
These arrays will contain all the uploaded file information.
The contents of $_FILES from the example form is as follows. Note that this assumes the use of the file upload name userfile, as used in the example script above. This can be any name.
$_FILES['userfile']['name']The original name of the file on the client machine.
$_FILES['userfile']['type']The mime type of the file, if the browser provided this information. An example would be "image/gif". This mime type is however not checked on the PHP side and therefore don't take its value for granted.
$_FILES['userfile']['size']The size, in bytes, of the uploaded file.
$_FILES['userfile']['tmp_name']The temporary filename of the file in which the uploaded file was stored on the server.
$_FILES['userfile']['error']The error code associated with this file upload. This element was added in PHP 4.2.0
Files will, by default be stored in the server's default temporary
directory, unless another location has been given with the upload_tmp_dir directive in
php.ini. The server's default directory can
be changed by setting the environment variable
TMPDIR in the environment in which PHP runs.
Setting it using putenv() from within a PHP
script will not work. This environment variable can also be used
to make sure that other operations are working on uploaded files,
as well.
Example 38-2. Validating file uploads See also the function entries for is_uploaded_file() and move_uploaded_file() for further information. The following example will process the file upload that came from a form.
|
The PHP script which receives the uploaded file should implement
whatever logic is necessary for determining what should be done
with the uploaded file. You can, for example, use the
$_FILES['userfile']['size'] variable
to throw away any files that are either too small or too big. You
could use the
$_FILES['userfile']['type'] variable
to throw away any files that didn't match a certain type criteria, but
use this only as first of a series of checks, because this value
is completely under the control of the client and not checked on the PHP
side.
As of PHP 4.2.0, you could use $_FILES['userfile']['error']
and plan your logic according to the error codes.
Whatever the logic, you should either delete the file from the
temporary directory or move it elsewhere.
If no file is selected for upload in your form, PHP will return
$_FILES['userfile']['size'] as 0, and
$_FILES['userfile']['tmp_name'] as none.
The file will be deleted from the temporary directory at the end of the request if it has not been moved away or renamed.
Example 38-3. Uploading array of files PHP supports HTML array feature even with files.
|
Since PHP 4.2.0, PHP returns an appropriate error code along with the
file array. The error code can be found in the
error segment of the file array that is created
during the file upload by PHP. In other words, the error might be
found in $_FILES['userfile']['error'].
Value: 0; There is no error, the file uploaded with success.
Value: 1; The uploaded file exceeds the upload_max_filesize directive in php.ini.
Value: 2; The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.
Value: 3; The uploaded file was only partially uploaded.
Value: 4; No file was uploaded.
Value: 6; Missing a temporary folder. Introduced in PHP 4.3.10 and PHP 5.0.3.
Value: 7; Failed to write file to disk. Introduced in PHP 5.1.0.
Value: 8; File upload stopped by extension. Introduced in PHP 5.2.0.
Note: These became PHP constants in PHP 4.3.0.
The MAX_FILE_SIZE item cannot specify a file size greater than the file size that has been set in the upload_max_filesize ini-setting. The default is 2 Megabytes.
If a memory limit is enabled, a larger memory_limit may be needed. Make sure you set memory_limit large enough.
If max_execution_time is set too small, script execution may be exceeded by the value. Make sure you set max_execution_time large enough.
Note: max_execution_time only affects the execution time of the script itself. Any time spent on activity that happens outside the execution of the script such as system calls using system(), the sleep() function, database queries, time taken by the file upload process, etc. is not included when determining the maximum time that the script has been running.
| Warning |
max_input_time sets the maximum time, in seconds, the script is allowed to receive input; this includes file uploads. For large or multiple files, or users on slower connections, the default of 60 seconds may be exceeded. |
If post_max_size is set too small, large files cannot be uploaded. Make sure you set post_max_size large enough.
Not validating which file you operate on may mean that users can access sensitive information in other directories.
Please note that the CERN httpd seems to strip off everything starting at the first whitespace in the content-type mime header it gets from the client. As long as this is the case, CERN httpd will not support the file upload feature.
Due to the large amount of directory listing styles we cannot guarantee that files with exotic names (like containing spaces) are handled properly.
A developer may not mix normal input fields and file upload fields in the same form variable (by using an input name like foo[]).
Multiple files can be uploaded using different name for input.
It is also possible to upload multiple files simultaneously and have the information organized automatically in arrays for you. To do so, you need to use the same array submission syntax in the HTML form as you do with multiple selects and checkboxes:
Note: Support for multiple file uploads was added in PHP 3.0.10.
When the above form is submitted, the arrays
$_FILES['userfile'],
$_FILES['userfile']['name'], and
$_FILES['userfile']['size'] will be
initialized (as well as in $HTTP_POST_FILES for PHP versions prior
to 4.1.0).
When
register_globals is on, globals for uploaded
files are also initialized. Each of these will be a numerically
indexed array of the appropriate values for the submitted files.
For instance, assume that the filenames
/home/test/review.html and
/home/test/xwp.out are submitted. In this
case, $_FILES['userfile']['name'][0]
would contain the value review.html, and
$_FILES['userfile']['name'][1] would
contain the value xwp.out. Similarly,
$_FILES['userfile']['size'][0] would
contain review.html's file size, and so forth.
$_FILES['userfile']['name'][0],
$_FILES['userfile']['tmp_name'][0],
$_FILES['userfile']['size'][0], and
$_FILES['userfile']['type'][0] are
also set.
PHP provides support for the HTTP PUT method used by some clients to store files on a server. PUT requests are much simpler than a file upload using POST requests and they look something like this:
This would normally mean that the remote client would like to save the content that follows as: /path/filename.html in your web tree. It is obviously not a good idea for Apache or PHP to automatically let everybody overwrite any files in your web tree. So, to handle such a request you have to first tell your web server that you want a certain PHP script to handle the request. In Apache you do this with the Script directive. It can be placed almost anywhere in your Apache configuration file. A common place is inside a <Directory> block or perhaps inside a <Virtualhost> block. A line like this would do the trick:
This tells Apache to send all PUT requests for URIs that match the context in which you put this line to the put.php script. This assumes, of course, that you have PHP enabled for the .php extension and PHP is active. The destination resource for all PUT requests to this script has to be the script itself, not a filename the uploaded file should have.
With PHP 4 and following you would then do something like the following in your put.php. This would copy the contents of the uploaded file to the file myputfile.ext on the server. You would probably want to perform some checks and/or authenticate the user before performing this file copy.
Example 38-5. Saving HTTP PUT files with PHP 4
|
Note: All documentation below applies to PHP 3 only.
The only
trick here is that when PHP sees a PUT-method request it stores
the uploaded file in a temporary file just like those handled by
the POST-method.
When the request ends, this temporary file is deleted. So, your
PUT handling PHP script has to copy that file somewhere. The
filename of this temporary file is in the $PHP_PUT_FILENAME
variable, and you can see the suggested destination filename in
the $REQUEST_URI (may vary on non-Apache web servers). This
destination filename is the one that the remote client specified.
You do not have to listen to this client. You could, for example,
copy all uploaded files to a special uploads directory.
As long as allow_url_fopen is enabled in
php.ini, you can use HTTP and FTP
URLs with most of the functions
that take a filename as a parameter. In addition, URLs can be
used with the include(),
include_once(), require() and
require_once() statements.
See Appendix O for more information about the protocols
supported by PHP.
Note: In PHP 4.0.3 and older, in order to use URL wrappers, you were required to configure PHP using the configure option
--enable-url-fopen-wrapper.
Note: The Windows versions of PHP earlier than PHP 4.3 did not support remote file accessing for the following functions: include(), include_once(), require(), require_once(), and the imagecreatefromXXX functions in the Reference LXV, Image Functions extension.
For example, you can use this to open a file on a remote web server, parse the output for the data you want, and then use that data in a database query, or simply to output it in a style matching the rest of your website.
Example 39-1. Getting the title of a remote page
|
You can also write to files on an FTP server (provided that you have connected as a user with the correct access rights). You can only create new files using this method; if you try to overwrite a file that already exists, the fopen() call will fail.
To connect as a user other than 'anonymous', you need to specify the username (and possibly password) within the URL, such as 'ftp://user:password@ftp.example.com/path/to/file'. (You can use the same sort of syntax to access files via HTTP when they require Basic authentication.)
Note: The following applies to 3.0.7 and later.
Internally in PHP a connection status is maintained. There are 3 possible states:
0 - NORMAL
1 - ABORTED
2 - TIMEOUT
When a PHP script is running normally the NORMAL state, is active. If the remote client disconnects the ABORTED state flag is turned on. A remote client disconnect is usually caused by the user hitting his STOP button. If the PHP-imposed time limit (see set_time_limit()) is hit, the TIMEOUT state flag is turned on.
You can decide whether or not you want a client disconnect to cause your script to be aborted. Sometimes it is handy to always have your scripts run to completion even if there is no remote browser receiving the output. The default behaviour is however for your script to be aborted when the remote client disconnects. This behaviour can be set via the ignore_user_abort php.ini directive as well as through the corresponding "php_value ignore_user_abort" Apache .conf directive or with the ignore_user_abort() function. If you do not tell PHP to ignore a user abort and the user aborts, your script will terminate. The one exception is if you have registered a shutdown function using register_shutdown_function(). With a shutdown function, when the remote user hits his STOP button, the next time your script tries to output something PHP will detect that the connection has been aborted and the shutdown function is called. This shutdown function will also get called at the end of your script terminating normally, so to do something different in case of a client disconnect you can use the connection_aborted() function. This function will return TRUE if the connection was aborted.
Your script can also be terminated by the built-in script timer.
The default timeout is 30 seconds. It can be changed using
the max_execution_time php.ini directive or the corresponding
php_value max_execution_time Apache .conf directive as well as with
the set_time_limit() function. When the timer
expires the script will be aborted and as with the above client
disconnect case, if a shutdown function has been registered it will
be called. Within this shutdown function you can check to see if
a timeout caused the shutdown function to be called by calling the
connection_status() function. This function will
return 2 if a timeout caused the shutdown function to be called.
One thing to note is that both the ABORTED and the TIMEOUT states can be active at the same time. This is possible if you tell PHP to ignore user aborts. PHP will still note the fact that a user may have broken the connection, but the script will keep running. If it then hits the time limit it will be aborted and your shutdown function, if any, will be called. At this point you will find that connection_status() returns 3.
Persistent connections are links that do not close when the execution of your script ends. When a persistent connection is requested, PHP checks if there's already an identical persistent connection (that remained open from earlier) - and if it exists, it uses it. If it does not exist, it creates the link. An 'identical' connection is a connection that was opened to the same host, with the same username and the same password (where applicable).
People who aren't thoroughly familiar with the way web servers work and distribute the load may mistake persistent connects for what they're not. In particular, they do not give you an ability to open 'user sessions' on the same link, they do not give you an ability to build up a transaction efficiently, and they don't do a whole lot of other things. In fact, to be extremely clear about the subject, persistent connections don't give you any functionality that wasn't possible with their non-persistent brothers.
Why?
This has to do with the way web servers work. There are three ways in which your web server can utilize PHP to generate web pages.
The first method is to use PHP as a CGI "wrapper". When run this way, an instance of the PHP interpreter is created and destroyed for every page request (for a PHP page) to your web server. Because it is destroyed after every request, any resources that it acquires (such as a link to an SQL database server) are closed when it is destroyed. In this case, you do not gain anything from trying to use persistent connections -- they simply don't persist.
The second, and most popular, method is to run PHP as a module in a multiprocess web server, which currently only includes Apache. A multiprocess server typically has one process (the parent) which coordinates a set of processes (its children) who actually do the work of serving up web pages. When a request comes in from a client, it is handed off to one of the children that is not already serving another client. This means that when the same client makes a second request to the server, it may be served by a different child process than the first time. When opening a persistent connection, every following page requesting SQL services can reuse the same established connection to the SQL server.
The last method is to use PHP as a plug-in for a multithreaded web server. Currently PHP 4 has support for ISAPI, WSAPI, and NSAPI (on Windows), which all allow PHP to be used as a plug-in on multithreaded servers like Netscape FastTrack (iPlanet), Microsoft's Internet Information Server (IIS), and O'Reilly's WebSite Pro. The behavior is essentially the same as for the multiprocess model described before. Note that SAPI support is not available in PHP 3.
If persistent connections don't have any added functionality, what are they good for?
The answer here is extremely simple -- efficiency. Persistent connections are good if the overhead to create a link to your SQL server is high. Whether or not this overhead is really high depends on many factors. Like, what kind of database it is, whether or not it sits on the same computer on which your web server sits, how loaded the machine the SQL server sits on is and so forth. The bottom line is that if that connection overhead is high, persistent connections help you considerably. They cause the child process to simply connect only once for its entire lifespan, instead of every time it processes a page that requires connecting to the SQL server. This means that for every child that opened a persistent connection will have its own open persistent connection to the server. For example, if you had 20 different child processes that ran a script that made a persistent connection to your SQL server, you'd have 20 different connections to the SQL server, one from each child.
Note, however, that this can have some drawbacks if you are using a database with connection limits that are exceeded by persistent child connections. If your database has a limit of 16 simultaneous connections, and in the course of a busy server session, 17 child threads attempt to connect, one will not be able to. If there are bugs in your scripts which do not allow the connections to shut down (such as infinite loops), the database with only 16 connections may be rapidly swamped. Check your database documentation for information on handling abandoned or idle connections.
| Warning |
There are a couple of additional caveats to keep in mind when using persistent connections. One is that when using table locking on a persistent connection, if the script for whatever reason cannot release the lock, then subsequent scripts using the same connection will block indefinitely and may require that you either restart the httpd server or the database server. Another is that when using transactions, a transaction block will also carry over to the next script which uses that connection if script execution ends before the transaction block does. In either case, you can use register_shutdown_function() to register a simple cleanup function to unlock your tables or roll back your transactions. Better yet, avoid the problem entirely by not using persistent connections in scripts which use table locks or transactions (you can still use them elsewhere). |
An important summary. Persistent connections were designed to have one-to-one mapping to regular connections. That means that you should always be able to replace persistent connections with non-persistent connections, and it won't change the way your script behaves. It may (and probably will) change the efficiency of the script, but not its behavior!
See also fbsql_pconnect(), ibase_pconnect(), ifx_pconnect(), ingres_pconnect(), msql_pconnect(), mssql_pconnect(), mysql_pconnect(), ociplogon(), odbc_pconnect(), ora_plogon(), pfsockopen(), pg_pconnect(), and sybase_pconnect().
The PHP safe mode is an attempt to solve the shared-server security problem. It is architecturally incorrect to try to solve this problem at the PHP level, but since the alternatives at the web server and OS levels aren't very realistic, many people, especially ISP's, use safe mode for now.
| Warning |
Safe Mode was removed in PHP 6.0.0. |
Table 42-1. Security and Safe Mode Configuration Directives
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| safe_mode | "0" | PHP_INI_SYSTEM | |
| safe_mode_gid | "0" | PHP_INI_SYSTEM | Available since PHP 4.1.0. |
| safe_mode_include_dir | NULL | PHP_INI_SYSTEM | Available since PHP 4.1.0. |
| safe_mode_exec_dir | "" | PHP_INI_SYSTEM | |
| safe_mode_allowed_env_vars | "PHP_" | PHP_INI_SYSTEM | |
| safe_mode_protected_env_vars | "LD_LIBRARY_PATH" | PHP_INI_SYSTEM | |
| open_basedir | NULL | PHP_INI_SYSTEM | |
| disable_functions | "" | php.ini only | Available since PHP 4.0.1. |
| disable_classes | "" | php.ini only | Available since PHP 4.3.2. |
Here's a short explanation of the configuration directives.
safe_mode
booleanWhether to enable PHP's safe mode.
safe_mode_gid
booleanBy default, Safe Mode does a UID compare check when opening files. If you want to relax this to a GID compare, then turn on safe_mode_gid. Whether to use UID (FALSE) or GID (TRUE) checking upon file access.
safe_mode_include_dir
stringUID/GID checks are bypassed when including files from this directory and its subdirectories (directory must also be in include_path or full path must including).
As of PHP 4.2.0, this directive can take a colon (semi-colon on Windows) separated path in a fashion similar to the include_path directive, rather than just a single directory.
The restriction specified is actually a prefix, not a directory name. This means that "safe_mode_include_dir = /dir/incl" also allows access to "/dir/include" and "/dir/incls" if they exist. When you want to restrict access to only the specified directory, end with a slash. For example: "safe_mode_include_dir = /dir/incl/"
If the value of this directive is empty, no files with different UID/GID can be included in PHP 4.2.3 and as of PHP 4.3.3. In earlier versions, all files could be included.
safe_mode_exec_dir
stringIf PHP is used in safe mode, system() and the other functions executing system programs refuse to start programs that are not in this directory. You have to use / as directory separator on all environments including Windows.
safe_mode_allowed_env_vars
stringSetting certain environment variables may be a potential security breach. This directive contains a comma-delimited list of prefixes. In Safe Mode, the user may only alter environment variables whose names begin with the prefixes supplied here. By default, users will only be able to set environment variables that begin with PHP_ (e.g. PHP_FOO=BAR).
Note: If this directive is empty, PHP will let the user modify ANY environment variable!
safe_mode_protected_env_vars
stringThis directive contains a comma-delimited list of environment variables that the end user won't be able to change using putenv(). These variables will be protected even if safe_mode_allowed_env_vars is set to allow to change them.
open_basedir
stringLimit the files that can be opened by PHP to the specified directory-tree, including the file itself. This directive is NOT affected by whether Safe Mode is turned On or Off.
When a script tries to open a file with, for example, fopen() or gzopen(), the location of the file is checked. When the file is outside the specified directory-tree, PHP will refuse to open it. All symbolic links are resolved, so it's not possible to avoid this restriction with a symlink.
The special value . indicates that the working directory of the script will be used as the base-directory. This is, however, a little dangerous as the working directory of the script can easily be changed with chdir().
In httpd.conf, open_basedir can be turned off (e.g. for some virtual hosts) the same way as any other configuration directive with "php_admin_value open_basedir none".
Under Windows, separate the directories with a semicolon. On all other systems, separate the directories with a colon. As an Apache module, open_basedir paths from parent directories are now automatically inherited.
The restriction specified with open_basedir is actually a prefix, not a directory name. This means that "open_basedir = /dir/incl" also allows access to "/dir/include" and "/dir/incls" if they exist. When you want to restrict access to only the specified directory, end with a slash. For example: "open_basedir = /dir/incl/"
Note: Support for multiple directories was added in 3.0.7.
The default is to allow all files to be opened.
disable_functions
stringThis directive allows you to disable certain functions for security reasons. It takes on a comma-delimited list of function names. disable_functions is not affected by Safe Mode.
This directive must be set in php.ini For example, you cannot set this in httpd.conf.
disable_classes
stringThis directive allows you to disable certain classes for security reasons. It takes on a comma-delimited list of class names. disable_classes is not affected by Safe Mode.
This directive must be set in php.ini For example, you cannot set this in httpd.conf.
Availability note: This directive became available in PHP 4.3.2
See also: register_globals, display_errors, and log_errors.
When safe_mode is on, PHP checks to see if the owner of the current script matches the owner of the file to be operated on by a file function or its directory. For example:
-rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php -rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd |
<?php
readfile('/etc/passwd');
?> |
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2 |
However, there may be environments where a strict UID check is not appropriate and a relaxed GID check is sufficient. This is supported by means of the safe_mode_gid switch. Setting it to On performs the relaxed GID checking, setting it to Off (the default) performs UID checking.
If instead of safe_mode, you set an open_basedir directory then all file operations will be limited to files under the specified directory. For example (Apache httpd.conf example):
<Directory /docroot> php_admin_value open_basedir /docroot </Directory> |
Warning: open_basedir restriction in effect. File is in wrong directory in /docroot/script.php on line 2 |
You can also disable individual functions. Note that the disable_functions directive can not be used outside of the php.ini file which means that you cannot disable functions on a per-virtualhost or per-directory basis in your httpd.conf file. If we add this to our php.ini file:
disable_functions = readfile,system |
Warning: readfile() has been disabled for security reasons in /docroot/script.php on line 2 |
| Warning |
These PHP restrictions are not valid in executed binaries, of course. |
This is a still probably incomplete and possibly incorrect listing of the functions limited by safe mode.
Table 42-2. Safe mode limited functions
| Function | Limitations |
|---|---|
| dbmopen() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| dbase_open() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| filepro() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| filepro_rowcount() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| filepro_retrieve() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| ifx_* | sql_safe_mode restrictions, (!= safe mode) |
| ingres_* | sql_safe_mode restrictions, (!= safe mode) |
| mysql_* | sql_safe_mode restrictions, (!= safe mode) |
| pg_lo_import() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| posix_mkfifo() | Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| putenv() | Obeys the safe_mode_protected_env_vars and safe_mode_allowed_env_vars ini-directives. See also the documentation on putenv() |
| move_uploaded_file() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| chdir() | Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| dl() | This function is disabled in safe mode. |
| backtick operator | This function is disabled in safe mode. |
| shell_exec() (functional equivalent of backticks) | This function is disabled in safe mode. |
| exec() | You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable. escapeshellcmd() is executed on the argument of this function. |
| system() | You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable. escapeshellcmd() is executed on the argument of this function. |
| passthru() | You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable. escapeshellcmd() is executed on the argument of this function. |
| popen() | You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable. escapeshellcmd() is executed on the argument of this function. |
| fopen() | Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| mkdir() | Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| rmdir() | Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| rename() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| unlink() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| copy() | Checks whether the files or directories you are
about to operate on have the same UID (owner) as the script that is being
executed. Checks whether the directory in which
you are about to operate has the same UID (owner) as the script that is being
executed. (on
source and
target) |
| chgrp() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| chown() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. |
| chmod() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. In addition, you cannot set the SUID, SGID and sticky bits |
| touch() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. |
| symlink() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. (note: only the target is checked) |
| link() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. (note: only the target is checked) |
| apache_request_headers() | In safe mode, headers beginning with 'authorization' (case-insensitive) will not be returned. |
| header() | In safe mode, the uid of the script is added to the realm part of the WWW-Authenticate header if you set this header (used for HTTP Authentication). |
| PHP_AUTH variables |
In safe mode, the variables PHP_AUTH_USER,
PHP_AUTH_PW, and AUTH_TYPE
are not available in $_SERVER. Regardless, you
can still use REMOTE_USER for the USER.
(note: only affected since PHP 4.3.0)
|
| highlight_file(), show_source() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. (note: only affected since PHP 4.2.1) |
| parse_ini_file() | Checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. Checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed. (note: only affected since PHP 4.2.1) |
| set_time_limit() | Has no effect when PHP is running in safe mode. |
| max_execution_time | Has no effect when PHP is running in safe mode. |
| mail() | In safe mode, the fifth parameter is disabled. (note: only affected since PHP 4.2.3) |
| Any function that uses php4/main/fopen_wrappers.c | ?? |
As of version 4.3.0, PHP supports a new SAPI type (Server Application Programming Interface) named CLI which means Command Line Interface. As the name implies, this SAPI type main focus is on developing shell (or desktop as well) applications with PHP. There are quite a few differences between the CLI SAPI and other SAPIs which are explained in this chapter. It's worth mentioning that CLI and CGI are different SAPI's although they do share many of the same behaviors.
The CLI SAPI was released for the first time with
PHP 4.2.0, but was still experimental and had
to be explicitly enabled with --enable-cli when running
./configure. Since PHP 4.3.0 the
CLI SAPI is no longer experimental and the option
--enable-cli is on by default. You may use
--disable-cli to disable it.
As of PHP 4.3.0, the name, location and existence of the CLI/CGI binaries
will differ depending on how PHP is installed on your system. By default
when executing make, both the CGI and CLI are built and
placed as sapi/cgi/php and sapi/cli/php
respectively, in your PHP source directory. You will note that both are
named php. What happens during make install depends on
your configure line. If a module SAPI is chosen during configure, such as apxs, or the
--disable-cgi option is used, the CLI is copied to
{PREFIX}/bin/php during make install
otherwise the CGI is placed there. So, for example, if --with--apxs
is in your configure line then the CLI is copied to
{PREFIX}/bin/php during make
install. If you want to override the installation of the CGI
binary, use make install-cli after make
install. Alternatively you can specify
--disable-cgi in your configure line.
Note: Because both
--enable-cliand--enable-cgiare enabled by default, simply having--enable-cliin your configure line does not necessarily mean the CLI will be copied as {PREFIX}/bin/php during make install.
The Windows packages between PHP 4.2.0 and PHP 4.2.3 distributed the CLI as php-cli.exe, living in the same folder as the CGI php.exe. Starting with PHP 4.3.0 the Windows package distributes the CLI as php.exe in a separate folder named cli, so cli/php.exe . Starting with PHP 5, the CLI is distributed in the main folder, named php.exe. The CGI version is distributed as php-cgi.exe.
As of PHP 5, a new php-win.exe file is distributed.
This is equal to the CLI version, except that php-win doesn't output
anything and thus provides no console (no "dos box" appears on the screen).
This behavior is similar to php-gtk. You should configure with
--enable-cli-win32.
What SAPI do I have?: From a shell, typing php -v will tell you whether php is CGI or CLI. See also the function php_sapi_name() and the constant PHP_SAPI.
Note: A Unix manual page was added in PHP 4.3.2. You may view this by typing man php in your shell environment.
Remarkable differences of the CLI SAPI compared to other SAPIs:
Unlike the CGI SAPI, no headers are written to the output.
Though the CGI SAPI provides a way to suppress HTTP headers, there's no equivalent switch to enable them in the CLI SAPI.
CLI is started up in quiet mode by default, though the -q
and --no-header switches are kept for compatibility so
that you can use older CGI scripts.
It does not change the working directory to that of the script.
(-C and --no-chdir switches kept for
compatibility)
Plain text error messages (no HTML formatting).
There are certain php.ini directives which are overridden by the CLI SAPI because they do not make sense in shell environments:
Table 43-1. Overridden php.ini directives
| Directive | CLI SAPI default value | Comment |
|---|---|---|
| html_errors | FALSE | It can be quite hard to read the error message in your shell when it's cluttered with all those meaningless HTML tags, therefore this directive defaults to FALSE. |
| implicit_flush | TRUE | It is desired that any output coming from print(), echo() and friends is immediately written to the output and not cached in any buffer. You still can use output buffering if you want to defer or manipulate standard output. |
| max_execution_time | 0 (unlimited) | Due to endless possibilities of using PHP in shell environments, the maximum execution time has been set to unlimited. Whereas applications written for the web are often executed very quickly, shell application tend to have a much longer execution time. |
| register_argc_argv | TRUE |
Because this setting is TRUE you will always have access to argc (number of arguments passed to the application) and argv (array of the actual arguments) in the CLI SAPI.
As of PHP 4.3.0, the PHP variables |
Note: These directives cannot be initialized with another value from the configuration file php.ini or a custom one (if specified). This is a limitation because those default values are applied after all configuration files have been parsed. However, their value can be changed during runtime (which does not make sense for all of those directives, e.g. register_argc_argv).
To ease working in the shell environment, the following constants are defined:
Table 43-2. CLI specific Constants
| Constant | Description | ||
|---|---|---|---|
| STDIN |
An already opened stream to stdin. This saves
opening it with
| ||
| STDOUT |
An already opened stream to stdout. This saves
opening it with
| ||
| STDERR |
An already opened stream to stderr. This saves
opening it with
|
Given the above, you don't need to open e.g. a stream for stderr yourself but simply use the constant instead of the stream resource:
php -r 'fwrite(STDERR, "stderr\n");' |
The CLI SAPI does not change the current directory to the directory of the executed script!
Example showing the difference to the CGI SAPI:
<?php // Our simple test application named test.php echo getcwd(), "\n"; ?> |
When using the CGI version, the output is:
$ pwd /tmp $ php -q another_directory/test.php /tmp/another_directory |
This clearly shows that PHP changes its current directory to the one of the executed script.
Using the CLI SAPI yields:
$ pwd /tmp $ php -f another_directory/test.php /tmp |
This allows greater flexibility when writing shell tools in PHP.
Note: The CGI SAPI supports this CLI SAPI behaviour by means of the
-Cswitch when run from the command line.
The list of command line options provided by the PHP
binary can be queried anytime by running PHP with the
-h switch:
Usage: php [options] [-f] <file> [--] [args...]
php [options] -r <code> [--] [args...]
php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
php [options] -- [args...]
php [options] -a
-a Run interactively
-c <path>|<file> Look for php.ini file in this directory
-n No php.ini file will be used
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-f <file> Parse and execute <file>.
-h This help
-i PHP information
-l Syntax check only (lint)
-m Show compiled in modules
-r <code> Run PHP <code> without using script tags <?..?>
-B <begin_code> Run PHP <begin_code> before processing input lines
-R <code> Run PHP <code> for every input line
-F <file> Parse and execute <file> for every input line
-E <end_code> Run PHP <end_code> after processing all input lines
-H Hide any passed arguments from external tools.
-s Display colour syntax highlighted source.
-v Version number
-w Display source with stripped comments and whitespace.
-z <file> Load Zend extension <file>.
args... Arguments passed to script. Use -- args when first argument
starts with - or script is read from stdin
--ini Show configuration file names
--rf <name> Show information about function <name>.
--rc <name> Show information about class <name>.
--re <name> Show information about extension <name>.
--ri <name> Show configuration for extension <name>. |
The CLI SAPI has three different ways of getting the PHP code you want to execute:
Telling PHP to execute a certain file.
Both ways (whether using the -f switch or not) execute
the file my_script.php. You can choose any file to
execute - your PHP scripts do not have to end with the
.php extension but can have any name or extension
you wish.
Pass the PHP code to execute directly on the command line.
Special care has to be taken in regards of shell variable substitution and quoting usage.
Note: Read the example carefully, there are no beginning or ending tags! The
-rswitch simply does not need them. Using them will lead to a parser error.
Provide the PHP code to execute via standard input (stdin).
This gives the powerful ability to dynamically create PHP code and feed it to the binary, as shown in this (fictional) example:
Like every shell application, the PHP binary
accepts a number of arguments but your PHP script can
also receive arguments. The number of arguments which can be passed to your script
is not limited by PHP (the shell has a certain size limit
in the number of characters which can be passed; usually you won't hit this
limit). The arguments passed to your script are available in the global
array $argv. The zero index always contains the script
name (which is - in case the PHP code
is coming from either standard input or from the command line switch
-r). The second registered global variable is
$argc which contains the number of elements in the
$argv array (not the
number of arguments passed to the script).
As long as the arguments you want to pass to your script do not start with the - character, there's nothing special to watch out for. Passing an argument to your script which starts with a - will cause trouble because PHP itself thinks it has to handle it. To prevent this, use the argument list separator --. After this separator has been parsed by PHP, every argument following it is passed untouched to your script.
# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]
# This will pass the '-h' argument to your script and prevent PHP from showing it's usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
} |
However, there's another way of using PHP for shell scripting. You can write a script where the first line starts with #!/usr/bin/php. Following this you can place normal PHP code included within the PHP starting and end tags. Once you have set the execution attributes of the file appropriately (e.g. chmod +x test) your script can be executed like a normal shell or perl script:
Example 43-1. Execute PHP script as shell script
Assuming this file is named test in the current directory, we can now do the following:
|
As you see, in this case no care needs to be taken when passing parameters which start with - to your script.
Long options are available since PHP 4.3.3.
Table 43-3. Command line options
| Option | Long Option | Description | |||
|---|---|---|---|---|---|
| -a | --interactive |
Runs PHP interactively. If you compile PHP with the Readline extension (which is not available on Windows), you'll have a nice shell, including a completion feature (e.g. you can start typing a variable name, hit the TAB key and PHP completes its name) and a typing history that can be accessed using the arrow keys. The history is saved in the ~/.php_history file.
| |||
| -c | --php-ini |
This option can either specify a directory where to look for php.ini or specify a custom INI file (which does not need to be named php.ini), e.g.: If you don't specify this option, file is searched in default locations. | |||
| -n | --no-php-ini |
Ignore php.ini at all. This switch is available since PHP 4.3.0. | |||
| -d | --define |
This option allows you to set a custom value for any of the configuration directives allowed in php.ini. The syntax is:
Examples (lines are wrapped for layout reasons):
| |||
| -e | --profile-info |
Activate the extended information mode, to be used by a debugger/profiler. | |||
| -f | --file |
Parses and executed the given filename to the | |||
| -h and -? | --help and --usage | With this option, you can get information about the actual list of command line options and some one line descriptions about what they do. | |||
| -i | --info | This command line option calls phpinfo(), and prints out the results. If PHP is not working correctly, it is advisable to use php -i and see whether any error messages are printed out before or in place of the information tables. Beware that when using the CGI mode the output is in HTML and therefore quite huge. | |||
| -l | --syntax-check |
This option provides a convenient way to only perform a syntax check on the given PHP code. On success, the text No syntax errors detected in <filename> is written to standard output and the shell return code is 0. On failure, the text Errors parsing <filename> in addition to the internal parser error message is written to standard output and the shell return code is set to 255.
This option won't find fatal errors (like undefined functions). Use
| |||
| -m | --modules | ||||
| -r | --run |
This option allows execution of PHP right from within the command line. The PHP start and end tags (<?php and ?>) are not needed and will cause a parser error if present.
| |||
| -B | --process-begin |
PHP code to execute before processing stdin. Added in PHP 5. | |||
| -R | --process-code |
PHP code to execute for every input line. Added in PHP 5.
There are two special variables available in this mode:
| |||
| -F | --process-file |
PHP file to execute for every input line. Added in PHP 5. | |||
| -E | --process-end |
PHP code to execute after processing the input. Added in PHP 5. | |||
| -s | --syntax-highlight and --syntax-highlight |
Display colour syntax highlighted source. This option uses the internal mechanism to parse the file and produces a HTML highlighted version of it and writes it to standard output. Note that all it does it to generate a block of <code> [...] </code> HTML tags, no HTML headers.
| |||
| -v | --version | ||||
| -w | --strip |
Display source with stripped comments and whitespace.
| |||
| -z | --zend-extension |
Load Zend extension. If only a filename is given, PHP tries to load this extension from the current default library path on your system (usually specified /etc/ld.so.conf on Linux systems). Passing a filename with an absolute path information will not use the systems library search path. A relative filename with a directory information will tell PHP only to try to load the extension relative to the current directory. | |||
| --ini |
Shows configuration file names and scanned directories. Available as of PHP 5.2.3. | ||||
| --rf | --rfunction |
Shows information about the given function or class method (e.g. number and name of the parameters). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support.
| |||
| --rc | --rclass |
Show information about the given class (list of constants, properties and methods). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support.
| |||
| --re | --rextension |
Show information about the given extension (list of php.ini options, defined functions, constants and classes). Available as of PHP 5.1.2. This option is only available if PHP was compiled with Reflection support.
| |||
| --ri | --rextinfo |
Shows the configuration information for the given extension (the same information that is returned by phpinfo()). Available as of PHP 5.2.2. The core configuration information are available using "main" as extension name.
|
The PHP executable can be used to run PHP scripts absolutely independent from the web server. If you are on a Unix system, you should add a special first line to your PHP script, and make it executable, so the system will know, what program should run the script. On a Windows platform you can associate php.exe with the double click option of the .php files, or you can make a batch file to run the script through PHP. The first line added to the script to work on Unix won't hurt on Windows, so you can write cross platform programs this way. A simple example of writing a command line PHP program can be found below.
Example 43-8. Script intended to be run from command line (script.php)
|
In the script above, we used the special first line to indicate
that this file should be run by PHP. We work with a CLI version
here, so there will be no HTTP header printouts. There are two
variables you can use while writing command line applications with
PHP: $argc and $argv. The
first is the number of arguments plus one (the name of the script
running). The second is an array containing the arguments, starting
with the script name as number zero ($argv[0]).
In the program above we checked if there are less or more than one
arguments. Also if the argument was --help,
-help, -h or -?,
we printed out the help message, printing the script name dynamically.
If we received some other argument we echoed that out.
If you would like to run the above script on Unix, you need to make it executable, and simply call it as script.php echothis or script.php -h. On Windows, you can make a batch file for this task:
Assuming you named the above program script.php, and you have your CLI php.exe in C:\php\php.exe this batch file will run it for you with your added options: script.bat echothis or script.bat -h.
See also the Readline extension documentation for more functions you can use to enhance your command line applications in PHP.
See also Appendix K.
| Warning |
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
These functions are only available when running PHP as an Apache module.
Note: As of PHP 4.3.2,
PATH_TRANSLATEDis no longer set implicitly under the Apache 2 SAPI in contrast to the situation in Apache 1, where it's set to the same value as theSCRIPT_FILENAMEserver variable when it's not populated by Apache. This change was made to comply with the CGI specification thatPATH_TRANSLATEDshould only exist ifPATH_INFOis defined.Apache 2 users may use AcceptPathInfo = On inside httpd.conf to define
PATH_INFO.
The behaviour of the Apache PHP module is affected by settings in php.ini. Configuration settings from php.ini may be overridden by php_flag settings in the server configuration file or local .htaccess files.
Table 1. Apache configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| engine | "1" | PHP_INI_ALL | Available since PHP 4.0.5. |
| child_terminate | "0" | PHP_INI_ALL | Available since PHP 4.0.5. |
| last_modified | "0" | PHP_INI_ALL | Available since PHP 4.0.5. |
| xbithack | "0" | PHP_INI_ALL | Available since PHP 4.0.5. |
Here's a short explanation of the configuration directives.
engine
booleanTurns PHP parsing on or off. This directive is really only useful in the Apache module version of PHP. It is used by sites that would like to turn PHP parsing on and off on a per-directory or per-virtual server basis. By putting engine off in the appropriate places in the httpd.conf file, PHP can be enabled or disabled.
child_terminate
booleanSpecify whether PHP scripts may request child process termination on end of request, see also apache_child_terminate().
last_modified
booleanSend PHP scripts modification date as Last-Modified: header for this request.
xbithack
booleanParse files with executable bit set as PHP regardless of their file ending.
apache_child_terminate() will register the Apache process executing the current PHP request for termination once execution of PHP code it is completed. It may be used to terminate a process after a script with high memory consumption has been run as memory will usually only be freed internally but not given back to the operating system.
Returns TRUE if PHP is running as an Apache 1 module, the Apache version is non-multithreaded, and the child_terminate PHP directive is enabled (disabled by default). If these conditions are not met, FALSE is returned and an error of level E_WARNING is generated.
Get an Apache environment variable as specified by
variable.
This function requires Apache 2 otherwise it's undefined.
variableThe Apache environment variable
walk_to_topWhether to get the top-level variable available to all Apache layers.
(PHP 3 >= 3.0.4, PHP 4, PHP 5)
apache_lookup_uri -- Perform a partial request for the specified URI and return all info about itThis performs a partial request for a URI. It goes just far enough to obtain all the important information about the given resource.
This function is only supported when PHP is installed as an Apache module.
An object of related URI information. The properties of this object are:
| status |
| the_request |
| status_line |
| method |
| content_type |
| handler |
| uri |
| filename |
| path_info |
| args |
| boundary |
| no_cache |
| no_local_copy |
| allowed |
| send_bodyct |
| bytes_sent |
| byterange |
| clength |
| unparsed_uri |
| mtime |
| request_time |
Example 1. apache_lookup_uri() example
The above example will output something similar to:
|
apache_note() is an Apache-specific function which gets and sets values in a request's notes table.
If called with one argument, it returns the current value of note note_name. If called with two arguments, it sets the value of note note_name to note_value and returns the previous value of note note_name. If the note cannot be retrieved, FALSE is returned.
Fetches all HTTP requests from the current request.
This function is only supported when PHP is installed as an Apache module.
An associative array of all the HTTP headers in the current request, or FALSE on failure.
Example 1. apache_request_headers() example
The above example will output something similar to:
|
Note: Prior to PHP 4.3.0, apache_request_headers() was called getallheaders(). After PHP 4.3.0, getallheaders() is an alias for apache_request_headers().
Note: You can also get at the value of the common CGI variables by reading them from the environment, which works whether or not you are using PHP as an Apache module. Use phpinfo() to see a list of all of the available environment variables.
Note: As of PHP 4.3.3 you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.
apache_reset_timeout() resets the Apache write timer, which defaults to 300 seconds. With set_time_limit(0); ignore_user_abort(true) and periodic apache_reset_timeout() calls, Apache can theoretically run forever.
This function requires Apache 1.
Note: As of PHP 4.3.3 you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.
apache_setenv() sets the value of the Apache
environment variable specified by
variable.
Note: When setting an Apache environment variable, the corresponding $_SERVER variable is not changed.
variableThe environment variable that's being set.
value
The new variable value.
walk_to_topWhether to set the top-level variable available to all Apache layers.
Note: apache_setenv() can be paired up with apache_getenv() across separate pages or for setting variables to pass to Server Side Includes (.shtml) that have been included in PHP scripts.
ascii2ebcdic() is an Apache-specific function which
is available only on EBCDIC based operating systems (OS/390, BS2000).
It translates the ASCII encoded string ascii_str
to its equivalent EBCDIC representation (binary safe), and returns
the result.
ebcdic2ascii() is an Apache-specific function which
is available only on EBCDIC based operating systems (OS/390, BS2000).
It translates the EBCDIC encoded string ebcdic_str
to its equivalent ASCII representation (binary safe), and returns
the result.
Fetches all HTTP requests from the current request.
This function is an alias for apache_request_headers(). Please read the apache_request_headers() documentation for more information on how this function works.
This function is only supported when PHP is installed as an Apache module.
An associative array of all the HTTP headers in the current request, or FALSE on failure.
| Version | Description |
|---|---|
| 4.3.0 | Became an alias for apache_request_headers(). Essentially, it was renamed. This is because this function only works with Apache. |
Note: As of PHP 4.3.3 you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.
virtual() is an Apache-specific function which is similar to <!--#include virtual...--> in mod_include. It performs an Apache sub-request. It is useful for including CGI scripts or .shtml files, or anything else that you would parse through Apache. Note that for a CGI script, the script must generate valid CGI headers. At the minimum that means it must generate a Content-type header.
To run the sub-request, all buffers are terminated and flushed to the browser, pending headers are sent too.
This function is only supported when PHP is installed as an Apache module.
| Warning |
The query string can be passed to the included file but
|
Note: Environment variables set in the requested file are not visible to the calling script.
Note: As of PHP 4.3.3 you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.
The Alternative PHP Cache (APC) is a free and open opcode cache for PHP. It was conceived of to provide a free, open, and robust framework for caching and optimizing PHP intermediate code.
This PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/apc.
The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
Note: On Windows, APC needs a temp path to exist, and be writable by the web server. It checks TMP, TEMP, USERPROFILE environment variables in that order and finally tries the WINDOWS directory if none of those are set.
Note: For more in-depth, highly technical implementation details, see the developer-supplied TECHNOTES file .
The behaviour of these functions is affected by settings in php.ini.
Although the default APC settings are fine for many installations, serious users should consider tuning the following parameters.
There are two main decisions you have to make. First, how much shared memory do you want to set aside for APC, and second, whether you want APC to check if a file has been modified on every request. The two ini directives involved here are apc.shm_size and apc.stat. Read the sections on these two directives carefully below.
Once you have a running server, you should copy the apc.php script that comes with the extension to somewhere in your docroot and load it up in your browser. It provides you with a detailed look at what is happening in your cache. If you have GD enabled in PHP, it will even have pretty graphs. First thing to check is of course that it is actually caching files. Assuming it is working you should then pay close attention to the Cache full count number on the left. That tells you the number of times the cache has filled up and has had to forcefully clean up any entries not accessed within the last apc.ttl seconds. You should configure your cache to minimize this number. If you are constantly filling your cache, the resulting cache churn is going to hurt performance. You should either set more memory aside for APC, or use apc.filters to cache fewer scripts.
Table 1. APC configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| apc.enabled | "1" | PHP_INI_SYSTEM | PHP_INI_ALL in APC <= 3.0.12p2 |
| apc.shm_segments | "1" | PHP_INI_SYSTEM | |
| apc.shm_size | "30" | PHP_INI_SYSTEM | |
| apc.optimization | "0" | PHP_INI_ALL | |
| apc.num_files_hint | "1000" | PHP_INI_SYSTEM | |
| apc.user_entries_hint | "4096" | PHP_INI_SYSTEM | |
| apc.ttl | "0" | PHP_INI_SYSTEM | |
| apc.user_ttl | "0" | PHP_INI_SYSTEM | |
| apc.gc_ttl | "3600" | PHP_INI_SYSTEM | |
| apc.cache_by_default | "1" | PHP_INI_ALL | PHP_INI_SYSTEM in APC <= 3.0.12p2 |
| apc.filters | NULL | PHP_INI_SYSTEM | |
| apc.mmap_file_mask | NULL | PHP_INI_SYSTEM | |
| apc.slam_defense | "0" | PHP_INI_SYSTEM | |
| apc.file_update_protection | "2" | PHP_INI_SYSTEM | |
| apc.enable_cli | "0" | PHP_INI_SYSTEM | > APC 3.0.6 |
| apc.max_file_size | "1M" | PHP_INI_SYSTEM | > APC 3.0.6 |
| apc.stat | "1" | PHP_INI_SYSTEM | > APC 3.0.9 |
| apc.write_lock | "1" | PHP_INI_SYSTEM | >= APC 3.0.11 |
| apc.report_autofilter | "0" | PHP_INI_SYSTEM | >= APC 3.0.11 |
| apc.include_once_override | "0" | PHP_INI_SYSTEM | >= APC 3.0.12 |
| apc.rfc1867 | "0" | PHP_INI_SYSTEM | >= APC 3.0.13 |
| apc.rfc1867_prefix | "upload_" | PHP_INI_SYSTEM | >= APC 3.0.15 |
| apc.rfc1867_name | "APC_UPLOAD_PROGRESS" | PHP_INI_SYSTEM | >= APC 3.0.15 |
| apc.rfc1867_freq | "0" | PHP_INI_SYSTEM | >= APC 3.0.15 |
| apc.localcache | "0" | PHP_INI_SYSTEM | >= APC 3.0.14 |
| apc.localcache.size | "512" | PHP_INI_SYSTEM | >= APC 3.0.14 |
Here's a short explanation of the configuration directives.
apc.enabled
booleanapc.enabled can be set to 0 to disable APC. This is primarily useful when APC is statically compiled into PHP, since there is no other way to disable it (when compiled as a DSO, the extension line in php.ini can just be commented-out).
apc.shm_segments
integerThe number of shared memory segments to allocate for the compiler cache. If APC is running out of shared memory but you have already set apc.shm_size as high as your system allows, you can try raising this value.
apc.shm_size
integerThe size of each shared memory segment in MB. By default, some systems (including most BSD variants) have very low limits on the size of a shared memory segment.
apc.optimization
integerThe optimization level. Zero disables the optimizer, and higher values use more aggressive optimizations. Expect very modest speed improvements. This is experimental.
apc.num_files_hint
integerA "hint" about the number of distinct source files that will be included or requested on your web server. Set to zero or omit if you're not sure; this setting is mainly useful for sites that have many thousands of source files.
apc.user_entries_hint
integerJust like apc.num_files_hint, a "hint" about the number of distinct user cache variables to store. Set to zero or omit if not sure.
apc.ttl
integerThe number of seconds a cache entry is allowed to idle in a slot in case this cache entry slot is needed by another entry. Leaving this at zero means that your cache could potentially fill up with stale entries while newer entries won't be cached.
apc.user_ttl
integerThe number of seconds a user cache entry is allowed to idle in a slot in case this cache entry slot is needed by another entry. Leaving this at zero means that your cache could potentially fill up with stale entries while newer entries won't be cached.
apc.gc_ttl
integerThe number of seconds that a cache entry may remain on the garbage-collection list. This value provides a fail-safe in the event that a server process dies while executing a cached source file; if that source file is modified, the memory allocated for the old version will not be reclaimed until this TTL reached. Set to zero to disable this feature.
apc.cache_by_default
booleanOn by default, but can be set to off and used in conjunction with positive apc.filters so that files are only cached if matched by a positive filter.
apc.filters
stringA comma-separated list of POSIX extended regular expressions. If any pattern matches the source filename, the file will not be cached. Note that the filename used for matching is the one passed to include/require, not the absolute path. If the first character of the expression is a + then the expression will be additive in the sense that any files matched by the expression will be cached, and if the first character is a - then anything matched will not be cached. The - case is the default, so it can be left off.
apc.mmap_file_mask
stringIf compiled with MMAP support by using --enable-mmap this is the mktemp-style file_mask to pass to the mmap module for determing whether your mmap'ed memory region is going to be file-backed or shared memory backed. For straight file-backed mmap, set it to something like /tmp/apc.XXXXXX (exactly 6 Xs). To use POSIX-style shm_open/mmap put a .shm somewhere in your mask. e.g. /apc.shm.XXXXXX You can also set it to /dev/zero to use your kernel's /dev/zero interface to anonymous mmap'ed memory. Leaving it undefined will force an anonymous mmap.
apc.slam_defense
integerOn very busy servers whenever you start the server or modify files you can create a race of many processes all trying to cache the same file at the same time. This option sets the percentage of processes that will skip trying to cache an uncached file. Or think of it as the probability of a single process to skip caching. For example, setting apc.slam_defense to 75 would mean that there is a 75% chance that the process will not cache an uncached file. So, the higher the setting the greater the defense against cache slams. Setting this to 0 disables this feature.
apc.file_update_protection
integerWhen you modify a file on a live web server you really should do so in an atomic manner. That is, write to a temporary file and rename (mv) the file into its permanent position when it is ready. Many text editors, cp, tar and other such programs don't do this. This means that there is a chance that a file is accessed (and cached) while it is still being written to. This apc.file_update_protection setting puts a delay on caching brand new files. The default is 2 seconds which means that if the modification timestamp (mtime) on a file shows that it is less than 2 seconds old when it is accessed, it will not be cached. The unfortunate person who accessed this half-written file will still see weirdness, but at least it won't persist. If you are certain you always atomically update your files by using something like rsync which does this correctly, you can turn this protection off by setting it to 0. If you have a system that is flooded with io causing some update procedure to take longer than 2 seconds, you may want to increase this a bit.
apc.enable_cli
integerMostly for testing and debugging. Setting this enables APC for the CLI version of PHP. Normally you wouldn't want to create, populate and tear down the APC cache on every CLI request, but for various test scenarios it is handy to be able to enable APC for the CLI version of APC easily.
apc.max_file_size
integerPrevent files larger than this value from getting cached. Defaults to 1M.
apc.stat
integerBe careful if you change this setting. The default is for this to be On which means that APC will stat (check) the script on each request to see if it has been modified. If it has been modified it will recompile and cache the new version. If you turn this setting off, it will not check. That means that in order to have changes become active you need to restart your web server. On a production server where you rarely change the code, turning stats off can produce a significant performance boost.
For included/required files this option applies as well, but note that if you are using relative path includes (any path that doesn't start with / on Unix) APC has to check in order to uniquely identify the file. If you use absolute path includes APC can skip the stat and use that absolute path as the unique identifier for the file.
apc.write_lock
booleanOn busy servers when you first start up the server, or when many files are modified, you can end up with all your processes trying to compile and cache the same files. With write_lock enabled, only one process at a time will try to compile an uncached script while the other processes will run uncached instead of sitting around waiting on a lock.
apc.report_autofilter
booleanLogs any scripts that were automatically excluded from being cached due to early/late binding issues.
apc.include_once_override
booleanOptimize include_once() and require_once() calls and avoid the expensive system calls used.
apc.rfc1867
booleanRFC1867 File Upload Progress hook handler is only available if you compiled APC against PHP 5.2.0 or later. When enabled, any file uploads which includes a field called APC_UPLOAD_PROGRESS before the file field in an upload form will cause APC to automatically create an upload_key user cache entry where key is the value of the APC_UPLOAD_PROGRESS form entry.
Note that the file upload tracking is not threadsafe at this point, so new uploads that happen while a previous one is still going will disable the tracking for the previous.
Example 1. An apc.rfc1867 example
The above example will output something similar to:
|
apc.rfc1867_prefix
stringKey prefix to use for the user cache entry generated by rfc1867 upload progress functionality.
apc.rfc1867_name
stringSpecify the hidden form entry name that activates APC upload progress and specifies the user cache key suffix.
apc.rfc1867_freq
stringThe frequency that updates should be made to the user cache entry for upload progress. This can take the form of a percentage of the total file size or a size in bytes optionally suffixed with 'k', 'm', or 'g' for kilobytes, megabytes, or gigabytes respectively (case insensitive). A setting of 0 updates as often as possible, which may cause slower uploads.
apc.localcache
booleanThis enables a lock-free local process shadow-cache which reduces lock contention when the cache is being written to.
apc.localcache.size
integerThe size of the local process shadow-cache, should be set to a sufficently large value, approximately half of apc.num_files_hint.
(no version information, might be only in CVS)
apc_add -- Cache a variable in the data store (only if it's not stored)Note: Unlike many other mechanisms in PHP, variables stored using apc_add() will persist between requests (until the value is removed from the cache).
key
Store the variable using this name. keys are
cache-unique, so attempting to use apc_add() to
store data with a key that already exists will not overwrite the
existing data, and will instead return FALSE. (This is the only
difference between apc_add() and
apc_store().)
varThe variable to store
ttl
Time To Live; store var in the cache for
ttl seconds. After the
ttl has passed, the stored variable will be
expunged from the cache (on the next request). If no ttl
is supplied (or if the ttl is
0), the value will persist until it is removed from
the cache manually, or otherwise fails to exist in the cache (clear,
restart, etc.).
Array of cached data (and meta-data), or FALSE on failure
Note: apc_cache_info() will raise a warning if it is unable to retrieve APC cache data. This typically occurs when APC is not enabled.
cache_type
If cache_type is "user",
information about the user cache will be returned; otherwise,
information about the system cache (cached files) will be returned.
limited
If limited is TRUE, the
return value will exclude the individual list of cache entries. This
is usefull when trying to optimize calls for statistics gathering.
Example 1. A apc_cache_info() example
The above example will output something similar to:
|
cache_type
If cache_type is "user", the
user cache will be cleared; otherwise, the system cache (cached files)
will be cleared.
(no version information, might be only in CVS)
apc_compile_file -- Stores a file in the bytecode cache, bypassing all filters.
filenameFull or relative path to a PHP file that will be compiled and stored in the bytecode cache.
define() is notoriously slow. Since the main benefit of APC is to increase the performance of scripts/applications, this mechanism is provided to streamline the process of mass constant definition. However, this function does not perform as well as anticipated.
For a better-performing solution, try the hidef extension from PECL.
Note: To remove a set of stored constants (without clearing the entire cache), an empty array may be passed as the
constantsparameter, effectively clearing the stored value(s).
key
The key serves as the name of the constant set
being stored. This key is used to retrieve the
stored constants in apc_load_constants().
constantsAn associative array of constant_name => value pairs. The constant_name must follow the normal constant naming rules. value must evaluate to a scalar value.
case_sensitiveThe default behaviour for constants is to be declared case-sensitive; i.e. CONSTANT and Constant represent different values. If this parameter evaluates to FALSE the constants will be declared as case-insensitive symbols.
keyThe name of the constant set (that was stored with apc_define_constants()) to be retrieved.
case_sensitiveThe default behaviour for constants is to be declared case-sensitive; i.e. CONSTANT and Constant represent different values. If this parameter evaluates to FALSE the constants will be declared as case-insensitive symbols.
Note: Unlike many other mechanisms in PHP, variables stored using apc_store() will persist between requests (until the value is removed from the cache).
key
Store the variable using this name. keys are
cache-unique, so storing a second value with the same
key will overwrite the original value.
varThe variable to store
ttl
Time To Live; store var in the cache for
ttl seconds. After the
ttl has passed, the stored variable will be
expunged from the cache (on the next request). If no ttl
is supplied (or if the ttl is
0), the value will persist until it is removed from
the cache manually, or otherwise fails to exist in the cache (clear,
restart, etc.).
APD is the Advanced PHP Debugger. It was written to provide profiling and debugging capabilities for PHP code, as well as to provide the ability to print out a full stack backtrace. APD supports interactive debugging, but by default it writes data to trace files. It also offers event based logging so that varying levels of information (including function calls, arguments passed, timings, etc.) can be turned on or off for individual scripts.
| Caution |
APD is a Zend Extension, modifying the way the internals of PHP handle function calls, and thus may or may not be compatible with other Zend Extensions (for example Zend Optimizer). |
APD is currently available as a PECL extension from http://pecl.php.net/package/apd. Make sure you have installed the CGI version of PHP and it is available in your current path along with the phpize script.
Run the following command to download, build, and install the latest stable version of APD:
pear install apd |
This automatically installs the APD Zend module into your PHP extensions directory. It is not mandatory to keep it there; you can store the module in any directory PHP can read as long as you set the zend_extension parameter accordingly.
Windows users can download the extension dll php_apd.dll from http://snaps.php.net/win32/PECL_STABLE/.
In your INI file, add the following lines:
zend_extension = /absolute/path/to/apd.so apd.dumpdir = /absolute/path/to/trace/directory apd.statement_tracing = 0 |
Depending on your PHP build, the zend_extension directive can be one of the following:
zend_extension (non ZTS, non debug build) zend_extension_ts ( ZTS, non debug build) zend_extension_debug (non ZTS, debug build) zend_extension_debug_ts ( ZTS, debug build) |
To build APD under Windows you need a working PHP compilation environment as described on http://php.net/ -- basically, it requires you to have Microsoft Visual C++, win32build.zip, bison/flex, and some know how to get it to work. Also ensure that adp.dsp has DOS line endings; if it has unix line endings, Microsoft Visual C++ will complain about it.
The behaviour of these functions is affected by settings in php.ini.
Table 1. APD Configuration Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| apd.dumpdir | NULL | PHP_INI_ALL | |
| apd.statement_tracing | "0" | PHP_INI_ALL |
Here's a short explanation of the configuration directives.
apd.dumpdir
stringSets the directory in which APD writes profile dump files. You can specify an absolute path or a relative path.
You can specify a different directory as an argument to apd_set_pprof_trace().
apd.statement_tracing
booleanSpecfies whether or not to do per-line tracings. Turning this on (1) will impact the performance of your application.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Table 2. APD constants
| Constant | Value | Description |
|---|---|---|
| FUNCTION_TRACE (integer) | 1 | |
| ARGS_TRACE (integer) | 2 | |
| ASSIGNMENT_TRACE (integer) | 4 | |
| STATEMENT_TRACE (integer) | 8 | |
| MEMORY_TRACE (integer) | 16 | |
| TIMING_TRACE (integer) | 32 | |
| SUMMARY_TRACE (integer) | 64 | |
| ERROR_TRACE (integer) | 128 | |
| PROF_TRACE (integer) | 256 | |
| APD_VERSION (string) | example: 1.0.2-dev |
As the first line of your PHP script, call the apd_set_pprof_trace() function to start the trace:
apd_set_pprof_trace(); |
You can insert the line anywhere in your script, but if you do not start tracing at the beginning of your script you discard profile data that might otherwise lead you to a performance bottleneck.
Now run your script. The dump output will be written to apd.dumpdir/pprof_pid.ext.
Tip: If you're running the CGI version of PHP, you will need to add the '-e' flag to enable extended information for apd to work properly. For example: php -e -f script.php
To display formatted profile data, issue the pprofp command with the sort and display options of your choice. The formatted output will look something like:
bash-2.05b$ pprofp -R /tmp/pprof.22141.0 Trace for /home/dan/testapd.php Total Elapsed Time = 0.00 Total System Time = 0.00 Total User Time = 0.00 Real User System secs/ cumm %Time (excl/cumm) (excl/cumm) (excl/cumm) Calls call s/call Memory Usage Name -------------------------------------------------------------------------------------- 100.0 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0000 0.0009 0 main 56.9 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0005 0.0005 0 apd_set_pprof_trace 28.0 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 preg_replace 14.3 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 str_replace |
The -R option used in this example sorts the profile table by the amount of real time the script spent executing a given function. The "cumm call" column reveals how many times each function was called, and the "s/call" column reveals how many seconds each call to the function required, on average.
To generate a calltree file that you can import into the KCacheGrind profile analysis application, issue the pprof2calltree comand.
If you have comments, bugfixes, enhancements or want to help developing this beast, you can send an mail to apd@mail.communityconnect.com. Any help is very welcome.
This can be used to stop the running of your script, and await responses on the connected socket. To step the program, just send enter (a blank line), or enter a php command to be executed.
debug_levelAn integer which is formed by adding together the XXX_TRACE constants.
It is not recommended to use MEMORY_TRACE. It is very slow and does not appear to be accurate. ASSIGNMENT_TRACE is not implemented yet.
To turn on all functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99
Example 1. Typical session using tcplisten
|
(no version information, might be only in CVS)
apd_callstack -- Returns the current call stack as an arrayBehaves like perl's Carp::cluck. Throw a warning and a callstack.
Usually sent via the socket to restart the interpreter.
debug_levelAn integer which is formed by adding together the XXX_TRACE constants.
It is not recommended to use MEMORY_TRACE. It is very slow and does not appear to be accurate. ASSIGNMENT_TRACE is not implemented yet.
To turn on all functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99
(no version information, might be only in CVS)
apd_croak -- Throw an error, a callstack and then exitBehaves like perl's Carp::croak. Throw an error, a callstack and then exit.
(no version information, might be only in CVS)
apd_dump_function_table -- Outputs the current function table(no version information, might be only in CVS)
apd_dump_persistent_resources -- Return all persistent resources as an arrayReturn all persistent resources as an array.
(no version information, might be only in CVS)
apd_dump_regular_resources -- Return all current regular resources as an arrayReturn all current regular resources as an array.
Usually sent via the socket to request information about the running script.
(no version information, might be only in CVS)
apd_get_active_symbols -- Get an array of the current variables names in the local scopeReturns the names of all the variables defined in the active scope, (not their values).
Starts debugging to pprof_{process_id} in the dump directory.
dump_directoryThe directory in which the profile dump file is written. If not set, the apd.dumpdir setting from the php.ini file is used.
fragment
Starts debugging to apd_dump_{process_id} in the dump directory.
debug_levelAn integer which is formed by adding together the XXX_TRACE constants.
It is not recommended to use MEMORY_TRACE. It is very slow and does not appear to be accurate. ASSIGNMENT_TRACE is not implemented yet.
To turn on all functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99
dump_directoryThe directory in which the profile dump file is written. If not set, the apd.dumpdir setting from the php.ini file is used.
(no version information, might be only in CVS)
apd_set_session -- Changes or sets the current debugging levelThis can be used to increase or decrease debugging in a different area of your application.
debug_levelAn integer which is formed by adding together the XXX_TRACE constants.
It is not recommended to use MEMORY_TRACE. It is very slow and does not appear to be accurate. ASSIGNMENT_TRACE is not implemented yet.
To turn on all functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99
(no version information, might be only in CVS)
apd_set_socket_session_trace -- Starts the remote session debugging
Connects to the specified tcp_server (eg. tcplisten)
and sends debugging data to the socket.
tcp_serverIP or Unix Domain socket (like a file) of the TCP server.
socket_typeCan be AF_UNIX for file based sockets or APD_AF_INET for standard tcp/ip.
portYou can use any port, but higher numbers are better as most of the lower numbers may be used by other system services.
debug_levelAn integer which is formed by adding together the XXX_TRACE constants.
It is not recommended to use MEMORY_TRACE. It is very slow and does not appear to be accurate. ASSIGNMENT_TRACE is not implemented yet.
To turn on all functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99
Overrides built-in functions by replacing them in the symbol table.
function_nameThe function to override.
function_argsThe function arguments, as a coma separated string.
Usually you will want to pass this parameter, as well as the
function_code parameter, as a single quote
delimited string. The reason for using single quoted strings, is to
protect the variable names from parsing, otherwise, if you use double
quotes there will be a need to escape the variable names, e.g.
\$your_var.
function_codeThe new code for the function.
Renames a orig_name to new_name in the global function table. Useful for temporarily overriding built-in functions.
These functions allow you to interact with and manipulate arrays in various ways. Arrays are essential for storing, managing, and operating on sets of variables.
Simple and multi-dimensional arrays are supported, and may be either user created or created by another function. There are specific database handling functions for populating arrays from database queries, and several functions return arrays.
Please see the Arrays section of the manual for a detailed explanation of how arrays are implemented and used in PHP. See also Array operators for other ways how to manipulate the arrays.
The constants below are always available as part of the PHP core.
CASE_LOWER is used with array_change_key_case() and is used to convert array keys to lower case. This is also the default case for array_change_key_case().
CASE_UPPER is used with array_change_key_case() and is used to convert array keys to upper case.
Sorting order flags:
SORT_ASC is used with array_multisort() to sort in ascending order.
SORT_DESC is used with array_multisort() to sort in descending order.
Sorting type flags: used by various sort functions
SORT_REGULAR is used to compare items normally.
SORT_NUMERIC is used to compare items numerically.
SORT_STRING is used to compare items as strings.
SORT_LOCALE_STRING is used to compare items as strings, based on the current locale. Added in PHP 4.4.0 and 5.0.2.
Returns an array with all keys from input lowercased
or uppercased. Numbered indices are left as is.
Returns an array with its keys lower or uppercased, or false if
input is not an array.
Note: If an array has indices that will be the same once run through this function (e.g. "keY" and "kEY"), the value that is later in the array will override other indices.
Chunks an array into size large chunks.
The last chunk may contain less than size elements.
inputThe array to work on
sizeThe size of each chunk
preserve_keysWhen set to TRUE keys will be preserved. Default is FALSE which will reindex the chunk numerically
Returns a multidimensional numerically indexed array, starting with zero,
with each dimension containing size elements.
Example 1. array_chunk() example
The above example will output:
|
Creates an array by using the values from the
keys array as keys and the values from the
values array as the corresponding values.
Returns the combined array, FALSE if the number of elements for each array isn't equal or if the arrays are empty.
Throws E_WARNING if keys and
values are either empty or the number of elements
does not match.
array_count_values() returns an array using
the values of the input array as keys and
their frequency in input as values.
(PHP 4 >= 4.3.0, PHP 5)
array_diff_assoc -- Computes the difference of arrays with additional index check
Compares array1 against array2 and
returns the difference. Unlike array_diff() the array
keys are used in the comparision.
array1The array to compare from
array2An array to compare against
...More arrays to compare against
Returns an array containing all the values from
array1 that are not present in any of the other arrays.
Example 1. array_diff_assoc() example In this example you see the "a" => "green" pair is present in both arrays and thus it is not in the ouput from the function. Unlike this, the pair 0 => "red" is in the ouput because in the second argument "red" has key which is 1.
The above example will output:
|
Example 2. array_diff_assoc() example Two values from key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In other words a strict check takes place so the string representations must be the same.
The above example will output:
|
Note: This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, array_diff_assoc($array1[0], $array2[0]);.
Compares the keys from array1 against the keys
from array2 and returns the difference.
This function is like array_diff() except the
comparison is done on the keys instead of the values.
array1The array to compare from
array2An array to compare against
...More arrays to compare against
Returns an array containing all the entries from
array1 that are not present in any of the other arrays.
Example 1. array_diff_key() example The two keys from the key => value pairs are considered equal only if (string) $key1 === (string) $key2 . In other words a strict type check is executed so the string representation must be the same.
The above example will output:
|
Note: This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using array_diff_key($array1[0], $array2[0]);.
| array_diff() |
| array_udiff() |
| array_diff_assoc() |
| array_diff_uassoc() |
| array_udiff_assoc() |
| array_udiff_uassoc() |
| array_diff_ukey() |
| array_intersect() |
| array_intersect_assoc() |
| array_intersect_uassoc() |
| array_intersect_key() |
| array_intersect_ukey() |
(PHP 5)
array_diff_uassoc -- Computes the difference of arrays with additional index check which is performed by a user supplied callback function
Compares array1 against array2 and
returns the difference. Unlike array_diff() the array
keys are used in the comparision.
Unlike array_diff_assoc() an user supplied callback function is used for the indices comparision, not internal function.
array1The array to compare from
array2An array to compare against
...More arrays to compare against
key_compare_funccallback function to use. The callback function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Returns an array containing all the entries from
array1 that are not present in any of the other arrays.
Example 1. array_diff_uassoc() example The "a" => "green" pair is present in both arrays and thus it is not in the ouput from the function. Unlike this, the pair 0 => "red" is in the ouput because in the second argument "red" has key which is 1.
The above example will output:
The equality of 2 indices is checked by the user supplied callback function. |
Note: This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, array_diff_uassoc($array1[0], $array2[0], "key_compare_func");.
| array_diff() |
| array_diff_assoc() |
| array_udiff() |
| array_udiff_assoc() |
| array_udiff_uassoc() |
| array_intersect() |
| array_intersect_assoc() |
| array_uintersect() |
| array_uintersect_assoc() |
| array_uintersect_uassoc() |
(PHP 5 >= 5.1.0RC1)
array_diff_ukey -- Computes the difference of arrays using a callback function on the keys for comparison
Compares the keys from array1 against the keys
from array2 and returns the difference.
This function is like array_diff() except the
comparison is done on the keys instead of the values.
Unlike array_diff_key() an user supplied callback function is used for the indices comparision, not internal function.
array1The array to compare from
array2An array to compare against
...More arrays to compare against
key_compare_funccallback function to use. The callback function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Returns an array containing all the entries from
array1 that are not present in any of the other arrays.
Example 1. array_diff_ukey() example
The above example will output:
|
Note: This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using array_diff_ukey($array1[0], $array2[0], 'callback_func');.
| array_diff() |
| array_udiff() |
| array_diff_assoc() |
| array_diff_uassoc() |
| array_udiff_assoc() |
| array_udiff_uassoc() |
| array_diff_key() |
| array_intersect() |
| array_intersect_assoc() |
| array_intersect_uassoc() |
| array_intersect_key() |
| array_intersect_ukey() |
Compares array1 against array2 and
returns the difference.
Example 1. array_diff() example
Multiple occurrences in $array1 are all treated the same way. This will output :
|
Note: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.
Note: This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using array_diff($array1[0], $array2[0]);.
| Warning |
This was broken in PHP 4.0.4! |
(no version information, might be only in CVS)
array_fill_keys -- Fill an array with values, specifying keys
Fills an array with the
value of the value parameter, using the
values of the keys array as keys.
keysArray of values that will be used as keys
valueEither an string or an array of values
Fills an array with
num entries of the value of the
value parameter, keys starting at the
start_index parameter.
start_indexThe first index of the returned array
numNumber of elements to insert
valueValues to use filling
Iterates over each value in
the input array passing them to the
callback function. If the
callback function returns true, the current
value from input is returned into the
result array. Array keys are preserved.
inputThe array to iterate over
callbackThe callback function to use
If no callback is supplied, all entries of
input equal to FALSE (see
converting to
boolean) will be removed.
Example 1. array_filter() example
The above example will output:
|
| Caution |
If the array is changed from the callback function (e.g. element added, deleted or unset) the behavior of this function is undefined. |
array_flip() returns an array in flip
order, i.e. keys from trans become values and values
from trans become keys.
Note that the values of trans need to be valid
keys, i.e. they need to be either integer or
string. A warning will be emitted if a value has the wrong
type, and the key/value pair in question will not be
flipped.
If a value has several occurrences, the latest key will be used as its values, and all others will be lost.
array_flip() returns FALSE if it fails.
See also array_values(), array_keys(), and array_reverse().
(PHP 4 >= 4.3.0, PHP 5)
array_intersect_assoc -- Computes the intersection of arrays with additional index check
array_intersect_assoc() returns an array
containing all the values of array1
that are present in all the arguments. Note that the keys are used in
the comparison unlike in array_intersect().
Example 1. array_intersect_assoc() example
The above example will output:
|
In our example you see that only the pair "a" =>
"green" is present in both arrays and thus is returned.
The value "red" is not returned because in
$array1 its key is 0 while
the key of "red" in $array2 is
1.
The two values from the key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In other words a strict type check is executed so the string representation must be the same.
See also array_intersect(), array_uintersect_assoc(), array_intersect_uassoc(), array_uintersect_uassoc(), array_diff() and array_diff_assoc().
(PHP 5 >= 5.1.0RC1)
array_intersect_key -- Computes the intersection of arrays using keys for comparison
array_intersect_key() returns an array
containing all the values of array1
which have matching keys that are present in all the arguments.
Example 1. array_intersect_key() example
The above example will output:
|
In our example you see that only the keys 'blue'
and 'green' are present in both arrays and thus
returned. Also notice that the values for the keys
'blue' and 'green' differ between
the two arrays. A match still occurs because only the keys are checked.
The values returned are those of array1.
The two keys from the key => value pairs are considered equal only if (string) $key1 === (string) $key2 . In other words a strict type check is executed so the string representation must be the same.
See also array_diff(), array_udiff() array_diff_assoc(), array_diff_uassoc(), array_udiff_assoc(), array_udiff_uassoc(), array_diff_key(), array_diff_ukey(), array_intersect(), array_intersect_assoc(), array_intersect_uassoc() and array_intersect_ukey().
(PHP 5)
array_intersect_uassoc -- Computes the intersection of arrays with additional index check, compares indexes by a callback function
array_intersect_uassoc() returns an array
containing all the values of array1
that are present in all the arguments. Note that the keys are used in
the comparison unlike in array_intersect().
The index comparison is done by a user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Example 1. array_intersect_uassoc() example
The above example will output:
|
See also array_intersect(), array_intersect_assoc(), array_uintersect_assoc(), array_uintersect_uassoc(), array_intersect_key() and array_intersect_ukey().
(PHP 5 >= 5.1.0RC1)
array_intersect_ukey -- Computes the intersection of arrays using a callback function on the keys for comparison
array_intersect_ukey() returns an array
containing all the values of array1
which have matching keys that are present in all the arguments.
This comparison is done by a user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first key is considered to be respectively less than, equal to, or greater than the second.
Example 1. array_intersect_ukey() example
The above example will output:
|
In our example you see that only the keys 'blue'
and 'green' are present in both arrays and thus
returned. Also notice that the values for the keys
'blue' and 'green' differ between
the two arrays. A match still occurs because only the keys are checked.
The values returned are those of array1.
See also array_diff(), array_udiff() array_diff_assoc(), array_diff_uassoc(), array_udiff_assoc(), array_udiff_uassoc(), array_diff_key(), array_diff_ukey(), array_intersect(), array_intersect_assoc(), array_intersect_uassoc() and array_intersect_key().
array_intersect() returns an array
containing all the values of array1
that are present in all the arguments.
Note that keys are preserved.
Note: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.
See also array_intersect_assoc(), array_diff(), and array_diff_assoc().
array_key_exists() returns TRUE if the
given key is set in the array.
key can be any value possible
for an array index. array_key_exists() also works
on objects.
Note: The name of this function is key_exists() in PHP 4.0.6.
Example 2. array_key_exists() vs isset() isset() does not return TRUE for array keys that correspond to a NULL value, while array_key_exists() does.
|
See also isset(), array_keys(), and in_array().
array_keys() returns the keys, numeric and
string, from the input array.
If the optional search_value is specified,
then only the keys for that value are returned. Otherwise, all
the keys from the input are returned.
As of PHP 5, you can use strict parameter for
comparison including type (===).
Example 1. array_keys() example
The above example will output:
|
See also array_values() and array_key_exists().
array_map() returns an array containing all
the elements of arr1 after applying the
callback function to each one.
The number of parameters that the callback
function accepts
should match the number of arrays
passed to the array_map()
Example 2. array_map() - using more arrays
The above example will output:
|
Usually when using two or more arrays, they should be of equal length because the callback function is applied in parallel to the corresponding elements. If the arrays are of unequal length, the shortest one will be extended with empty elements.
An interesting use of this function is to construct an array of arrays, which can be easily performed by using NULL as the name of the callback function
Example 3. Creating an array of arrays
The above example will output:
|
See also array_filter(), array_reduce(), array_walk(), create_function(), and information about the callback type.
array_merge_recursive() merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one. It returns the resulting array.
If the input arrays have the same string keys, then the values for these keys are merged together into an array, and this is done recursively, so that if one of the values is an array itself, the function will merge it with a corresponding entry in another array too. If, however, the arrays have the same numeric key, the later value will not overwrite the original value, but will be appended.
Example 1. array_merge_recursive() example
The above example will output:
|
See also array_merge().
array_merge() merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one. It returns the resulting array.
If the input arrays have the same string keys, then the later value for that key will overwrite the previous one. If, however, the arrays contain numeric keys, the later value will not overwrite the original value, but will be appended.
If only one array is given and the array is numerically indexed, the keys get reindexed in a continuous way.
Example 1. array_merge() example
The above example will output:
|
Example 2. Simple array_merge() example
Don't forget that numeric keys will be renumbered!
If you want to completely preserve the arrays and just want to append them to each other, use the + operator:
The numeric key will be preserved and thus the association remains.
|
| Warning | |
The behavior of array_merge() was modified in PHP 5. Unlike PHP 4, array_merge() now only accepts parameters of type array. However, you can use typecasting to merge other types. See the example below for details.
|
See also array_merge_recursive(), array_combine() and array operators.
Returns TRUE on success or FALSE on failure.
array_multisort() can be used to sort several arrays at once, or a multi-dimensional array by one or more dimensions.
Associative (string) keys will be maintained, but numeric keys will be re-indexed.
The input arrays are treated as columns of a table to be sorted by rows - this resembles the functionality of SQL ORDER BY clause. The first array is the primary one to sort by. The rows (values) in that array that compare the same are sorted by the next input array, and so on.
The argument structure of this function is a bit unusual, but flexible. The first argument has to be an array. Subsequently, each argument can be either an array or a sorting flag from the following lists.
Sorting order flags:
SORT_ASC - Sort in ascending order
SORT_DESC - Sort in descending order
Sorting type flags:
SORT_REGULAR - Compare items normally
SORT_NUMERIC - Compare items numerically
SORT_STRING - Compare items as strings
No two sorting flags of the same type can be specified after each array. The sorting flags specified after an array argument apply only to that array - they are reset to default SORT_ASC and SORT_REGULAR before each new array argument.
Example 1. Sorting multiple arrays
In this example, after sorting, the first array will contain "10", "a", 100, 100. The second array will contain 1, 1, "2", 3. The entries in the second array corresponding to the identical entries in the first array (100 and 100) were sorted as well.
|
Example 2. Sorting multi-dimensional array
In this example, after sorting, the first array will transform to "10", 100, 100, 11, "a" (it was sorted as strings in ascending order). The second will contain 1, 3, "2", 2, 1 (sorted as numbers, in descending order).
|
Example 3. Sorting database results
For this example, each element in the Example data:
The data as an array, called
In this example, we will order by We have an array of rows, but array_multisort() requires an array of columns, so we use the below code to obtain the columns, then perform the sorting.
The dataset is now sorted, and will look like this:
|
Example 4. Case insensitive sorting Both SORT_STRING and SORT_REGULAR are case sensitive, strings starting with a capital letter will come before strings starting with a lowercase letter. To perform a case insensitive search, force the sorting order to be determined by a lowercase copy of the original array.
The above example will output:
|
array_pad() returns a copy of the
input padded to size specified by
pad_size with value
pad_value. If
pad_size is positive then the array is
padded on the right, if it's negative then on the left. If the
absolute value of pad_size is less than or
equal to the length of the input then no
padding takes place.
It is possible to add most 1048576 elements at a time.
See also array_fill() and range().
array_pop() pops and returns the last value of
the array, shortening the
array by one element.
If array is empty (or is not an array),
NULL will be returned.
See also array_push(), array_shift(), and array_unshift().
array_product() returns the product of values in an array as an integer or float.
array_push() treats
array as a stack, and pushes the passed
variables onto the end of array. The
length of array increases by the number of
variables pushed. Has the same effect as:
<?php $array[] = $var; ?> |
var.
Returns the new number of elements in the array.
Note: If you use array_push() to add one element to the array it's better to use $array[] = because in that way there is no overhead of calling a function.
Note: array_push() will raise a warning if the first argument is not an array. This differs from the $var[] behaviour where a new array is created.
See also array_pop(), array_shift(), and array_unshift().
array_rand() is rather useful when you want to
pick one or more random entries out of an array. It takes an
input array and an optional argument
num_req which specifies how many entries you
want to pick - if not specified, it defaults to 1.
If you are picking only one entry, array_rand() returns the key for a random entry. Otherwise, it returns an array of keys for the random entries. This is done so that you can pick random keys as well as values out of the array.
Note: As of PHP 4.2.0, there is no need to seed the random number generator with srand() or mt_srand() as this is now done automatically.
See also shuffle().
(PHP 4 >= 4.0.5, PHP 5)
array_reduce -- Iteratively reduce the array to a single value using a callback function
array_reduce() applies iteratively the
function function to the elements of the
array input, so as to reduce the array to
a single value. If the optional initial is
available, it will be used at the beginning of the process, or as
a final result in case the array is empty.
If the array is empty and initial is not passed,
array_reduce() returns NULL.
This will result in $b containing
15, $c containing
1200 (= 10*1*2*3*4*5), and
$d containing 1.
See also array_filter(), array_map(), array_unique(), and array_count_values().
array_reverse() takes input
array and returns a new array with the
order of the elements reversed, preserving the keys if
preserve_keys is TRUE.
Example 1. array_reverse() example
This makes both
|
Note: The second parameter was added in PHP 4.0.3.
See also array_flip().
(PHP 4 >= 4.0.5, PHP 5)
array_search -- Searches the array for a given value and returns the corresponding key if successful
Searches haystack for
needle and returns the key if it is found in
the array, FALSE otherwise.
Note: If
needleis a string, the comparison is done in a case-sensitive manner.
Note: Prior to PHP 4.2.0, array_search() returns NULL on failure instead of FALSE.
If the optional third parameter strict is set to
TRUE then the array_search()
will also check the types of the needle
in the haystack.
If needle is found in
haystack more than once, the first matching key
is returned. To return the keys for all matching values, use
array_keys() with the optional
search_value parameter instead.
| Warning |
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. |
See also array_keys(), array_values(), array_key_exists(), and in_array().
array_shift() shifts the first value of the
array off and returns it, shortening the
array by one element and moving everything
down. All numerical array keys will be modified to start counting from zero
while literal keys won't be touched. If array is empty
(or is not an array), NULL will be returned.
See also array_unshift(), array_push(), and array_pop().
array_slice() returns the sequence of elements
from the array array as specified by the
offset and length
parameters.
If offset is non-negative, the sequence will
start at that offset in the array. If
offset is negative, the sequence will
start that far from the end of the array.
If length is given and is positive, then
the sequence will have that many elements in it. If
length is given and is negative then the
sequence will stop that many elements from the end of the
array. If it is omitted, then the sequence will have everything
from offset up until the end of the
array.
Note that array_slice() will reorder and reset the
array indices by default. Since PHP 5.0.2, you can change this
behaviour by setting preserve_keys to TRUE.
Example 1. array_slice() examples
The above example will output:
|
See also array_splice() and unset().
array_splice() removes the elements designated
by offset and
length from the
input array, and replaces them with the
elements of the replacement array, if
supplied. It returns an array containing the extracted elements.
Note that numeric keys in input are not preserved.
If offset is positive then the start of
removed portion is at that offset from the beginning of the
input array. If
offset is negative then it starts that far
from the end of the input array.
If length is omitted, removes everything
from offset to the end of the array. If
length is specified and is positive, then
that many elements will be removed. If
length is specified and is negative then
the end of the removed portion will be that many elements from
the end of the array. Tip: to remove everything from
offset to the end of the array when
replacement is also specified, use
count($input) for
length.
If replacement array is specified, then
the removed elements are replaced with elements from this array.
If offset and
length are such that nothing is removed,
then the elements from the replacement
array are inserted in the place specified by the
offset. Note that keys in replacement
array are not preserved.
If replacement is just one element it is
not necessary to put array()
around it, unless the element is an array itself.
The following statements change the values of $input
the same way:
Table 1. array_splice() equivalents
| array_push($input, $x, $y) | array_splice($input, count($input), 0, array($x, $y)) |
| array_pop($input) | array_splice($input, -1) |
| array_shift($input) | array_splice($input, 0, 1) |
| array_unshift($input, $x, $y) | array_splice($input, 0, 0, array($x, $y)) |
| $input[$x] = $y // for arrays where key equals offset | array_splice($input, $x, 1, $y) |
Returns the array consisting of removed elements.
Example 1. array_splice() examples
|
See also array_slice(), unset(), and array_merge().
array_sum() returns the sum of values in an array as an integer or float.
Note: PHP versions prior to 4.2.1 modified the passed array itself and converted strings to numbers (which most of the time converted them to zero, depending on their value).
(PHP 5)
array_udiff_assoc -- Computes the difference of arrays with additional index check, compares data by a callback function
array_udiff_assoc() returns an array
containing all the values from array1
that are not present in any of the other arguments.
Note that the keys are used in the comparison unlike
array_diff() and array_udiff().
The comparison of arrays' data is performed by using an user-supplied
callback. In this aspect the behaviour is opposite to the behaviour of
array_diff_assoc() which uses internal function for
comparison.
Example 1. array_udiff_assoc() example
The above example will output:
|
In our example above you see the "1" => new cr(4) pair is present in both arrays and thus it is not in the ouput from the function.
For comparison is used the user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Note: Please note that this function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, array_udiff_assoc($array1[0], $array2[0], "some_comparison_func");.
See also array_diff(), array_diff_assoc(), array_diff_uassoc(), array_udiff(), array_udiff_uassoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() and array_uintersect_uassoc().
(PHP 5)
array_udiff_uassoc -- Computes the difference of arrays with additional index check, compares data and indexes by a callback function
array_udiff_uassoc() returns an array
containing all the values from array1
that are not present in any of the other arguments.
Note that the keys are used in the comparison unlike
array_diff() and array_udiff().
The comparison of arrays' data is performed by using an user-supplied
callback : data_compare_func. In this aspect
the behaviour is opposite to the behaviour of
array_diff_assoc() which uses internal function for
comparison. The comparison of keys (indices) is done also by the
callback function key_compare_func. This
behaviour is unlike what array_udiff_assoc() does, since
the latter compares the indices by using an internal function.
Example 1. array_udiff_uassoc() example
The above example will output:
|
In our example above you see the "1" => new cr(4) pair is present in both arrays and thus it is not in the ouput from the function. Keep in mind that you have to supply 2 callback functions.
For comparison is used the user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Note: Please note that this function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, array_udiff_uassoc($array1[0], $array2[0], "data_compare_func", "key_compare_func");.
See also array_diff(), array_diff_assoc(), array_diff_uassoc(), array_udiff(), array_udiff_assoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() and array_uintersect_uassoc().
(PHP 5)
array_udiff -- Computes the difference of arrays by using a callback function for data comparison
array_udiff() returns an array
containing all the values of array1
that are not present in any of the other arguments.
Note that keys are preserved. For the comparison of the data
data_compare_func is used.
It must return an integer less than, equal
to, or greater than zero if the first argument is considered to
be respectively less than, equal to, or greater than the
second. This is unlike array_diff() which uses an
internal function for comparing the data.
Example 1. array_udiff() example
The above example will output:
|
Note: Please note that this function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using array_udiff($array1[0], $array2[0], "data_compare_func");.
See also array_diff(), array_diff_assoc(), array_diff_uassoc(), array_udiff_assoc(), array_udiff_uassoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() and array_uintersect_uassoc().
(PHP 5)
array_uintersect_assoc -- Computes the intersection of arrays with additional index check, compares data by a callback function
array_uintersect_assoc() returns an array
containing all the values of array1
that are present in all the arguments. Note that the keys are used in
the comparison unlike in array_uintersect().
The data is compared by using a callback function.
Example 1. array_uintersect_assoc() example
The above example will output:
|
For comparison is used the user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
See also array_uintersect(), array_intersect_assoc(), array_intersect_uassoc() and array_uintersect_uassoc().
(PHP 5)
array_uintersect_uassoc -- Computes the intersection of arrays with additional index check, compares data and indexes by a callback functions
array_uintersect_uassoc() returns an array
containing all the values of array1
that are present in all the arguments. Note that the keys are used in
the comparison unlike in array_uintersect().
Both the data and the indexes are compared by using a callback functions.
Example 1. array_uintersect_uassoc() example
The above example will output:
|
For comparison is used the user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
See also array_uintersect(), array_intersect_assoc(), array_intersect_uassoc() and array_uintersect_assoc().
(PHP 5)
array_uintersect -- Computes the intersection of arrays, compares data by a callback function
array_uintersect() returns an array
containing all the values of array1
that are present in all the arguments.
The data is compared by using a callback function.
Example 1. array_uintersect() example
The above example will output:
|
For comparison is used the user supplied callback function. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
See also array_intersect(), array_uintersect_assoc(), array_intersect_uassoc() and array_uintersect_uassoc().
array_unique() takes input
array and returns a new array
without duplicate values.
Note that keys are preserved. array_unique() sorts
the values treated as string at first, then will keep the first key
encountered for every value, and ignore all following keys. It does not
mean that the key of the first related value from the unsorted
array will be kept.
Note: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.
The first element will be used.
array_unshift() prepends passed elements to
the front of the array. Note that the list
of elements is prepended as a whole, so that the prepended
elements stay in the same order. All numerical array keys will be
modified to start counting from zero while literal keys won't be touched.
Returns the new number of elements in the
array.
See also array_shift(), array_push(), and array_pop().
array_values() returns all the values from the
input array and indexes numerically the
array.
See also array_keys().
Applies the user-defined function funcname to each
element of the input array. This function will recur
into deeper arrays. Typically, funcname takes on two
parameters. The input parameter's value being the first, and
the key/index second. If the optional userdata
parameter is supplied, it will be passed as the third parameter to
the callback funcname.
Returns TRUE on success or FALSE on failure.
Note: If
funcnameneeds to be working with the actual values of the array, specify the first parameter offuncnameas a reference. Then, any changes made to those elements will be made in the original array itself.
Example 1. array_walk_recursive() example
The above example will output:
You may notice that the key 'sweet' is never displayed. Any key that holds an array will not be passed to the function. |
See also array_walk(), and information about the callback type.
Returns TRUE on success or FALSE on failure.
Applies the user-defined function funcname to each
element of the array array. Typically,
funcname takes on two parameters.
The array parameter's value being the first, and
the key/index second. If the optional userdata
parameter is supplied, it will be passed as the third parameter to
the callback funcname.
If function funcname requires more parameters than
given to it, an error of level
E_WARNING will be generated each time array_walk()
calls funcname. These warnings may be suppressed by
prepending the PHP error operator
@ to the
array_walk() call, or by using
error_reporting().
Note: If
funcnameneeds to be working with the actual values of the array, specify the first parameter offuncnameas a reference. Then, any changes made to those elements will be made in the original array itself.
Note: Passing the key and userdata to
funcnamewas added in 4.0.0
array_walk() is not affected by the internal
array pointer of array.
array_walk() will walk through the entire array
regardless of pointer position.
Users may not change the array itself from the callback function. e.g. Add/delete elements, unset elements, etc. If the array that array_walk() is applied to is changed, the behavior of this function is undefined, and unpredictable.
Example 1. array_walk() example
The above example will output:
|
See also array_walk_recursive(), create_function(), list(), foreach, each(), call_user_func_array(), and array_map(), and information about the callback type.
Returns an array of the parameters. The parameters can be given an index with the => operator. Read the section on the array type for more information on what an array is.
Note: array() is a language construct used to represent literal arrays, and not a regular function.
Syntax "index => values", separated by commas, define index and values. index may be of type string or numeric. When index is omitted, an integer index is automatically generated, starting at 0. If index is an integer, next generated index will be the biggest integer index + 1. Note that when two identical index are defined, the last overwrite the first.
Having a trailing comma after the last defined array entry, while unusual, is a valid syntax.
The following example demonstrates how to create a two-dimensional array, how to specify keys for associative arrays, and how to skip-and-continue numeric indices in normal arrays.
Note that index '3' is defined twice, and keep its final value of 13. Index 4 is defined after index 8, and next generated index (value 19) is 9, since biggest index was 8.
This example creates a 1-based array.
As in Perl, you can access a value from the array inside double quotes. However, with PHP you'll need to enclose your array between curly braces.
See also array_pad(), list(), count(), foreach, and range().
This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant.
Returns TRUE on success or FALSE on failure.
The fruits have been sorted in reverse alphabetical order, and the index associated with each element has been maintained.
You may modify the behavior of the sort using the optional
parameter sort_flags, for details
see sort().
This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant.
Returns TRUE on success or FALSE on failure.
The fruits have been sorted in alphabetical order, and the index associated with each element has been maintained.
You may modify the behavior of the sort using the optional
parameter sort_flags, for details
see sort().
compact() takes a variable number of parameters. Each parameter can be either a string containing the name of the variable, or an array of variable names. The array can contain other arrays of variable names inside it; compact() handles it recursively.
For each of these, compact() looks for a variable with that name in the current symbol table and adds it to the output array such that the variable name becomes the key and the contents of the variable become the value for that key. In short, it does the opposite of extract(). It returns the output array with all the variables added to it.
Any strings that are not set will simply be skipped.
Gotcha: Because variable variables may not be used with PHP's Superglobal arrays within functions, the Superglobal arrays may not be passed into compact().
Example 1. compact() example
The above example will output:
|
See also extract().
Returns the number of elements in var,
which is typically an array, since anything else
will have one element.
For objects, if you have SPL installed, you can hook into count() by implementing interface Countable. The interface has exactly one method, count(), which returns the return value for the count() function.
If var is not an array or an object with
implemented Countable interface,
1 will be returned.
There is one exception, if var is NULL,
0 will be returned.
Note: The optional
modeparameter is available as of PHP 4.2.0.
If the optional mode parameter is set to
COUNT_RECURSIVE (or 1), count()
will recursively count the array. This is particularly useful for
counting all the elements of a multidimensional array. The default
value for mode is 0.
count() does not detect infinite recursion.
| Caution |
count() may return 0 for a variable that isn't set, but it may also return 0 for a variable that has been initialized with an empty array. Use isset() to test if a variable is set. |
Please see the Array section of the manual for a detailed explanation of how arrays are implemented and used in PHP.
See also is_array(), isset(), and strlen().
Every array has an internal pointer to its "current" element, which is initialized to the first element inserted into the array.
The current() function simply returns the value of the array element that's currently being pointed to by the internal pointer. It does not move the pointer in any way. If the internal pointer points beyond the end of the elements list, current() returns FALSE.
| Warning |
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. |
Note: You won't be able to distinguish the end of an array from a boolean FALSE element. To properly traverse an array which may contain FALSE elements, see the each() function.
Example 1. Example use of current() and friends
|
(PHP 3, PHP 4, PHP 5)
each -- Return the current key and value pair from an array and advance the array cursor
Returns the current key and value pair from the array
array and advances the array cursor. This
pair is returned in a four-element array, with the keys
0, 1,
key, and
value. Elements 0 and
key contain the key name of the array
element, and 1 and
value contain the data.
If the internal pointer for the array points past the end of the array contents, each() returns FALSE.
<?php
$foo = array("Robert" => "Bob", "Seppo" => "Sepi");
$bar = each($foo);
print_r($bar);
?> |
$bar now contains the following key/value
pairs:
Array
(
[1] => Bob
[value] => Bob
[0] => Robert
[key] => Robert
) |
each() is typically used in conjunction with list() to traverse an array, here's an example:
After each() has executed, the array cursor will be left on the next element of the array, or past the last element if it hits the end of the array. You have to use reset() if you want to traverse the array again using each.
| Caution |
Because assigning an array to another variable resets the original
arrays pointer, our example above would cause an endless loop had we
assigned |
See also key(), list(), current(), reset(), next(), prev(), and foreach.
end() advances array's
internal pointer to the last element, and returns its value.
(PHP 3 >= 3.0.7, PHP 4, PHP 5)
extract -- Import variables into the current symbol table from an array
This function is used to import variables from an array into the
current symbol table. It takes an associative array
var_array and treats keys as variable
names and values as variable values. For each key/value pair it
will create a variable in the current symbol table, subject to
extract_type and
prefix parameters.
Note: Beginning with version 4.0.5, this function returns the number of variables extracted.
Note: EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS were introduced in version 4.2.0.
Note: EXTR_REFS was introduced in version 4.3.0.
extract() checks each key to see whether it
has a valid variable name. It also checks for collisions with
existing variables in the symbol table. The way invalid/numeric
keys and collisions are treated is determined by the
extract_type. It can be one of the
following values:
If there is a collision, overwrite the existing variable.
If there is a collision, don't overwrite the existing variable.
If there is a collision, prefix the variable name with
prefix.
Prefix all variable names with
prefix. Beginning with PHP 4.0.5, this includes
numeric variables as well.
Only prefix invalid/numeric variable names with
prefix. This flag was added in
PHP 4.0.5.
Only overwrite the variable if it already exists in the current symbol table, otherwise do nothing. This is useful for defining a list of valid variables and then extracting only those variables you have defined out of $_REQUEST, for example. This flag was added in PHP 4.2.0.
Only create prefixed variable names if the non-prefixed version of the same variable exists in the current symbol table. This flag was added in PHP 4.2.0.
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the var_array parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
extract_type. This flag was added in PHP
4.3.0.
If extract_type is not specified, it is
assumed to be EXTR_OVERWRITE.
Note that prefix is only required if
extract_type is EXTR_PREFIX_SAME,
EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID
or EXTR_PREFIX_IF_EXISTS. If
the prefixed result is not a valid variable name, it is not
imported into the symbol table. Prefixes are automatically separated from
the array key by an underscore character.
extract() returns the number of variables successfully imported into the symbol table.
| Warning |
Do not use extract() on untrusted data, like
user-input ($_GET, ...). If you do, for example, if you want to run old
code that relies on
register_globals
temporarily, make sure you use one of the non-overwriting
|
A possible use for extract() is to import into the symbol table variables contained in an associative array returned by wddx_deserialize().
Example 1. extract() example
The above example will output:
|
The $size wasn't overwritten, because we
specified EXTR_PREFIX_SAME, which resulted in
$wddx_size being created. If EXTR_SKIP was
specified, then $wddx_size wouldn't even have been created.
EXTR_OVERWRITE would have caused $size to have
value "medium", and EXTR_PREFIX_ALL would result in new variables
being named $wddx_color,
$wddx_size, and
$wddx_shape.
You must use an associative array, a numerically indexed array will not produce results unless you use EXTR_PREFIX_ALL or EXTR_PREFIX_INVALID.
See also compact().
Searches haystack for
needle and returns TRUE
if it is found in the array, FALSE otherwise.
If the third parameter strict is set to
TRUE then the in_array() function
will also check the types of
the needle in the haystack.
Note: If
needleis a string, the comparison is done in a case-sensitive manner.
Note: In PHP versions before 4.2.0
needlewas not allowed to be an array.
Example 3. in_array() with an array as needle
The above example will output:
|
See also array_search(), array_key_exists(), and isset().
key() returns the index element of the current array position.
Example 1. key() example
|
Sorts an array by key in reverse order, maintaining key to data correlations. This is useful mainly for associative arrays.
Returns TRUE on success or FALSE on failure.
You may modify the behavior of the sort using the optional
parameter sort_flags, for details
see sort().
See also asort(), arsort(), ksort(), sort(), natsort(), and rsort().
Sorts an array by key, maintaining key to data correlations. This is useful mainly for associative arrays.
Returns TRUE on success or FALSE on failure.
You may modify the behavior of the sort using the optional
parameter sort_flags, for details
see sort().
See also asort(), arsort(), krsort(), uksort(), sort(), natsort(), and rsort().
Note: The second parameter was added in PHP 4.
Like array(), this is not really a function, but a language construct. list() is used to assign a list of variables in one operation.
Note: list() only works on numerical arrays and assumes the numerical indices start at 0.
Example 1. list() examples
|
Example 2. An example use of list()
|
| Warning |
list() assigns the values starting with the right-most parameter. If you are using plain variables, you don't have to worry about this. But if you are using arrays with indices you usually expect the order of the indices in the array the same you wrote in the list() from left to right; which it isn't. It's assigned in the reverse order. |
Example 3. Using list() with array indices
Gives the following output (note the order of the elements compared in which order they were written in the list() syntax):
|
This function implements a sort algorithm that orders alphanumeric strings in the way a human being would while maintaining key/value associations. This is described as a "natural ordering".
Returns TRUE on success or FALSE on failure.
natcasesort() is a case insensitive version of natsort().
Example 1. natcasesort() example
The above example will output:
For more information see: Martin Pool's Natural Order String Comparison page. |
See also sort(), natsort(), strnatcmp(), and strnatcasecmp().
This function implements a sort algorithm that orders alphanumeric strings in the way a human being would while maintaining key/value associations. This is described as a "natural ordering". An example of the difference between this algorithm and the regular computer string sorting algorithms (used in sort()) can be seen below:
Returns TRUE on success or FALSE on failure.
Example 1. natsort() example
The above example will output:
For more information see: Martin Pool's Natural Order String Comparison page. |
See also natcasesort(), strnatcmp(), and strnatcasecmp().
Returns the array value in the next place that's pointed to by the internal array pointer, or FALSE if there are no more elements.
next() behaves like current(), with one difference. It advances the internal array pointer one place forward before returning the element value. That means it returns the next array value and advances the internal array pointer by one. If advancing the internal array pointer results in going beyond the end of the element list, next() returns FALSE.
| Warning |
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. |
Note: You won't be able to distinguish the end of an array from a boolean FALSE element. To properly traverse an array which may contain FALSE elements, see the each() function.
Example 1. Example use of next() and friends
|
Returns the array value in the previous place that's pointed to by the internal array pointer, or FALSE if there are no more elements.
| Warning |
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. |
Note: You won't be able to distinguish the beginning of an array from a boolean FALSE element. To properly traverse an array which may contain FALSE elements, see the each() function.
prev() behaves just like next(), except it rewinds the internal array pointer one place instead of advancing it.
Example 1. Example use of prev() and friends
|
range() returns an array of elements from
low to high,
inclusive. If low > high, the sequence will be from high to low.
New parameter: The optional
stepparameter was added in 5.0.0.
If a step value is given, it will be used as the
increment between elements in the sequence. step
should be given as a positive number. If not specified,
step will default to 1.
Example 1. range() examples
|
Note: Prior to PHP 4.1.0, range() only generated incrementing integer arrays. Support for character sequences and decrementing arrays was added in 4.1.0. Character sequence values are limited to a length of one. If a length greater than one is entered, only the first character is used.
| Caution |
In PHP versions 4.1.0 through 4.3.2, range() sees numeric strings as strings and not integers. Instead, they will be used for character sequences. For example, "4242" is treated as "4". |
See also shuffle(), array_fill(), and foreach.
reset() rewinds array's
internal pointer to the first element and returns the value of the first
array element, or FALSE if the array is empty.
Example 1. reset() example
|
This function sorts an array in reverse order (highest to lowest).
Note: This function assigns new keys for the elements in
array. It will remove any existing keys you may have assigned, rather than just reordering the keys.
Returns TRUE on success or FALSE on failure.
The fruits have been sorted in reverse alphabetical order.
You may modify the behavior of the sort using the optional
parameter sort_flags, for details
see sort().
See also arsort(), asort(), ksort(), krsort(), sort(), and usort().
This function shuffles (randomizes the order of the elements in) an array.
Note: This function assigns new keys for the elements in
array. It will remove any existing keys you may have assigned, rather than just reordering the keys.
Note: As of PHP 4.2.0, there is no need to seed the random number generator with srand() or mt_srand() as this is now done automatically.
See also arsort(), asort(), ksort(), rsort(), sort(), and usort().
This function sorts an array. Elements will be arranged from lowest to highest when this function has completed.
Note: This function assigns new keys for the elements in
array. It will remove any existing keys you may have assigned, rather than just reordering the keys.
Returns TRUE on success or FALSE on failure.
The fruits have been sorted in alphabetical order.
The optional second parameter sort_flags
may be used to modify the sorting behavior using these values:
Sorting type flags:
SORT_REGULAR - compare items normally (don't change types)
SORT_NUMERIC - compare items numerically
SORT_STRING - compare items as strings
SORT_LOCALE_STRING - compare items as strings, based on the current locale. Added in PHP 4.4.0 and 5.0.2. Before PHP 6, it uses the system locale, which can be changed using setlocale(). Since PHP 6, you must use the i18n_loc_set_default() function.
Note: The second parameter was added in PHP 4.
| Warning |
Be careful when sorting arrays with mixed types values because sort() can produce unpredictable results. |
See also arsort(), asort(), ksort(), krsort(), natsort(), natcasesort(), rsort(), usort(), array_multisort(), and uksort().
(PHP 3 >= 3.0.4, PHP 4, PHP 5)
uasort -- Sort an array with a user-defined comparison function and maintain index associationThis function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant. The comparison function is user-defined.
Returns TRUE on success or FALSE on failure.
See also usort(), uksort(), sort(), asort(), arsort(), ksort(), and rsort().
(PHP 3 >= 3.0.4, PHP 4, PHP 5)
uksort -- Sort an array by keys using a user-defined comparison functionuksort() will sort the keys of an array using a user-supplied comparison function. If the array you wish to sort needs to be sorted by some non-trivial criteria, you should use this function.
Function cmp_function should accept two
parameters which will be filled by pairs of array keys.
The comparison function must return an integer less than, equal
to, or greater than zero if the first argument is considered to
be respectively less than, equal to, or greater than the
second.
Returns TRUE on success or FALSE on failure.
Example 1. uksort() example
The above example will output:
|
See also usort(), uasort(), sort(), asort(), arsort(), ksort(), natsort(), and rsort().
(PHP 3 >= 3.0.3, PHP 4, PHP 5)
usort -- Sort an array by values using a user-defined comparison functionThis function will sort an array by its values using a user-supplied comparison function. If the array you wish to sort needs to be sorted by some non-trivial criteria, you should use this function.
The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Note: If two members compare as equal, their order in the sorted array is undefined. Up to PHP 4.0.6 the user defined functions would keep the original order for those elements, but with the new sort algorithm introduced with 4.1.0 this is no longer the case as there is no solution to do so in an efficient way.
Note: This function assigns new keys for the elements in
array. It will remove any existing keys you may have assigned, rather than just reordering the keys.
Returns TRUE on success or FALSE on failure.
Note: Obviously in this trivial case the sort() function would be more appropriate.
Example 2. usort() example using multi-dimensional array
When sorting a multi-dimensional array, The above example will output:
|
Example 3. usort() example using a member function of an object
The above example will output:
|
See also uasort(), uksort(), sort(), asort(), arsort(),ksort(), natsort(), and rsort().
The aspell() functions allows you to check the spelling on a word and offer suggestions.
Note: This extension has been removed from PHP and is no longer available as of PHP 4.3.0. If you want to use spell-checking capabilities in PHP, use pspell instead. It uses pspell library and works with newer versions of aspell.
aspell works only with very old (up to .27.* or so) versions of aspell library. Neither this module, nor those versions of aspell library are supported any longer. You need the aspell library, available from: http://aspell.sourceforge.net/.
In PHP 4, these functions are only available if PHP was
configured with --with-aspell=[DIR].
(PHP 3 >= 3.0.7, PHP 4 <= 4.2.3)
aspell_check_raw -- Check a word without changing its case or trying to trim it [deprecated]aspell_check_raw() checks the spelling of a word, without changing its case or trying to trim it in any way.
dictionary_linkThe dictionnary link identifier returned by aspell_new().
wordThe tested word.
aspell_check() checks the spelling of a word.
dictionary_linkThe dictionnary link identifier returned by aspell_new().
wordThe tested word.
aspell_new() opens up a new dictionary for use with the other aspell functions.
aspell_suggest() suggest spellings for the given
word.
dictionary_linkThe dictionnary link identifier returned by aspell_new().
wordThe tested word.
For arbitrary precision mathematics PHP offers the Binary Calculator which supports numbers of any size and precision, represented as strings.
Since PHP 4.0.4, libbcmath is bundled with PHP. You don't need any external libraries for this extension.
These functions are only available if PHP was
configured with --enable-bcmath.
In PHP 3, these functions are only available if PHP was not
configured with --disable-bcmath.
The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.
The behaviour of these functions is affected by settings in php.ini.
For further details and definitions of the PHP_INI_* constants, see the Appendix I.
Here's a short explanation of the configuration directives.
Sums left_operand and
right_operand.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
Compares the left_operand to the
right_operand and returns the result as an
integer.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
scale
The optional scale parameter is used to set the
number of digits after the decimal place which will be used in the
comparison.
Returns 0 if the two operands are equal, 1 if the
left_operand is larger than the
right_operand, -1 otherwise.
Divides the left_operand by the
right_operand.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
Get the modulus of the left_operand using
modulus.
Multiply the left_operand by the
right_operand.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
Raise left_operand to the power
right_operand.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
Use the fast-exponentiation method to raise
left_operand to the power
right_operand with respect to the modulus
modulus.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
modulusThe modulus, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
Note: Because this method uses the modulus operation, non-natural numbers may give unexpected results. A natural number is any positive non-zero integer.
The following two statements are functionally identical. The bcpowmod() version however, executes in less time and can accept larger parameters.
Sets the default scale parameter for all subsequent bc math functions that do not explicitly specify a scale parameter.
operandThe operand, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
Subtracts the right_operand from the
left_operand.
left_operandThe left operand, as a string.
right_operandThe right operand, as a string.
scaleThis optional parameter is used to set the number of digits after the decimal place in the result. You can also set the global default scale for all functions by using bcscale().
| Warning |
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. |
Bcompiler was written for several reasons:
| To encode entire script in a proprietary PHP application |
| To encode some classes and/or functions in a proprietary PHP application |
| To enable the production of php-gtk applications that could be used on client desktops, without the need for a php.exe. |
| To do the feasibility study for a PHP to C converter |
The second of these goals is achieved using the bcompiler_write_header(), bcompiler_write_class(), bcompiler_write_footer(), bcompiler_read(), and bcompiler_load() functions. The bytecode files can be written as either uncompressed or plain. The bcompiler_load() reads a bzip compressed bytecode file, which tends to be 1/3 of the size of the original file.
To create EXE type files, bcompiler has to be used with a modified sapi file or a version of PHP which has been compiled as a shared library. In this scenario, bcompiler reads the compressed bytecode from the end of the exe file.
bcompiler can improve performance by about 30% when used with uncompressed bytecodes only. But keep in mind that uncompressed bytecode can be up to 5 times larger than the original source code. Using bytecode compression can save your space, but decompression requires much more time than parsing a source. bcompiler also does not do any bytecode optimization, this could be added in the future...
In terms of code protection, it is safe to say that it would be impossible to recreate the exact source code that it was built from, and without the accompanying source code comments. It would effectively be useless to use the bcompiler bytecodes to recreate and modify a class. However it is possible to retrieve data from a bcompiled bytecode file - so don't put your private passwords or anything in it.
short installation note:
You need at least PHP 4.3.0 for the compression to work
To install on PHP 4.3.0 and later at the Unix command prompt type pear install bcompiler
To install on Windows, until the binary package distribution mechanism is finished please search the archives of the pear-general mailing list for pre-built packages. (or send an email to it if you could not find a reference)
To install on older versions you need to make some slight changes to the build.
untar the bcompiler.tgz archive into php4/ext.(Get it directly from PECL http://pecl.php.net/get/bcompiler)
If the new directory is now called something like bcompiler-0.x, then you should rename it to bcompiler (except you only want to build it as self-contained php-module).
If you are using versions before PHP 4.3.0, the you will need to copy the Makefile.in.old to Makefile.in and config.m4.old to config.m4.
run phpize in ext/bcompiler
run ./buildconf in php4
run configure with
--enable-bcompiler (and your other options)
make; make install
that's it.
If you have comments, bugfixes, enhancements or want to help developing this beast, you can drop me a mail at alan_k@php.net. Any help is very welcome.
Reads data from a bcompiler exe file and creates classes from the bytecodes.
Example 1. bcompiler_load() example
|
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads data from a bzcompressed file and creates classes from the bytecodes.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Note: Please use include or require statements to parse bytecodes, it's more portable and convenient way than using this function.
Please note that this function won't execute script body code contained in the bytecode file.
Reads the bytecodes of a class and calls back to a user function.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Note: This function has been removed from bcompiler and is no longer available as of bcompiler 0.5.
Reads data from a open file handle and creates classes from the bytecodes.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Note: Please use include or require statements to parse bytecodes, it's more portable and convenient way than using this function.
Please note that this function won't execute script body code contained in the bytecode file.
Reads the bytecodes from PHP for an existing class, and writes them to the open file handle.
filehandleA file handle as returned by fopen().
classNameThe class name, as a string.
extends
Example 1. bcompiler_write_class() example
|
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Note: This function does not perform dependency checking, so make sure you write the classes in an order that will not result in an undefined class error occurring when you load it.
Reads the bytecodes from PHP for an existing constant, and writes them to the open file handle.
filehandleA file handle as returned by fopen().
constantNameThe name of the defined constant, as a string.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
An EXE (or self executable) file consists of 3 parts:
| The stub (executable code, e.g. a compiled C program) that loads PHP interpreter, bcompiler extension, stored Bytecodes and initiates a call for the specified function (e.g. main) or class method (e.g. main::main) |
| The Bytecodes (uncompressed only for the moment) |
| The bcompiler EXE footer |
To obtain a suitable stub you can compile php_embed-based stub phpe.c located in the examples/embed directory on bcompiler's CVS.
Example 1. bcompiler_write_footer() example
|
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
This function complies specified source file into bytecodes, and writes them to the open file handle.
filehandleA file handle as returned by fopen().
filenameThe source file path, as a string.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Writes the single character \x00 to indicate End of compiled data.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads the bytecodes from PHP for an existing function, and writes them to the open file handle. Order is not important, (eg. if function b uses function a, and you compile it like the example below, it will work perfectly OK).
filehandleA file handle as returned by fopen().
functionNameThe function name, as a string.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Searches for all functions declared in the given file, and writes their correspondent bytecodes to the open file handle.
filehandleA file handle as returned by fopen().
fileNameThe file to be compiled. You must always include or require the file you intend to compile.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Writes the header part of a bcompiler file.
filehandleA file handle as returned by fopen().
write_verCan be used to write bytecode in a previously used format, so that you can use it with older versions of bcompiler.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
The bzip2 functions are used to transparently read and write bzip2 (.bz2) compressed files.
This module uses the functions of the bzip2 library by Julian Seward. This module requires bzip2/libbzip2 version >= 1.0.x.
Bzip2 support in PHP is not enabled by default. You will
need to use the --with-bz2[=DIR]
configuration option when compiling PHP to enable bzip2 support.
This extension defines one resource type: a file pointer identifying the bz2-file to work on.
This example opens a temporary file and writes a test string to it, then prints out the contents of the file.
Example 1. Small bzip2 Example
|
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
bzcompress() compresses the given string and returns it as bzip2 encoded data.
sourceThe string to compress.
blocksize
Specifies the blocksize used during compression and should be a number
from 1 to 9 with 9 giving the best compression, but using more
resources to do so. blocksize defaults to 4.
workfactorControls how the compression phase behaves when presented with worst case, highly repetitive, input data. The value can be between 0 and 250 with 0 being a special case and 30 being the default value.
Regardless of the workfactor, the generated
output is the same.
bzdecompress() decompresses the given string containing bzip2 encoded data.
sourceThe string to decompress.
smallIf TRUE, an alternative decompression algorithm will be used which uses less memory (the maximum memory requirement drops to around 2300K) but works at roughly half the speed.
See the bzip2 documentation for more information about this feature.
Returns the error number of any bzip2 error returned by the given file pointer.
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
Returns the error number and error string of any bzip2 error returned by the given file pointer.
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
Returns an associative array, with the error code in the errno entry, and the error message in the errstr entry.
Gets the error string of any bzip2 error returned by the given file pointer.
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
Forces a write of all buffered bzip2 data for the file pointer
bz.
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
bzopen() opens a bzip2 (.bz2) file for reading or writing.
filenameThe name of the file to open.
modeSimilar to the fopen() function ('r' for read, 'w' for write, etc.).
If the open fails, bzopen() returns FALSE, otherwise it returns a pointer to the newly opened file.
bzread() reads from the given bzip2 file pointer.
Reading stops when length (uncompressed) bytes have
been read or EOF is reached, whichever comes first.
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
lengthIf not specified, bzread() will read 1024 (uncompressed) bytes at a time.
bzwrite() writes a string into the given bzip2 file stream.
bzThe file pointer. It must be valid and must point to a file successfully opened by bzopen().
dataThe written data.
length
If supplied, writing will stop after length
(uncompressed) bytes have been written or the end of
data is reached, whichever comes first.
The calendar extension presents a series of functions to simplify converting between different calendar formats. The intermediary or standard it is based on is the Julian Day Count. The Julian Day Count is a count of days starting from January 1st, 4713 B.C. To convert between calendar systems, you must first convert to Julian Day Count, then to the calendar system of your choice. Julian Day Count is very different from the Julian Calendar! For more information on Julian Day Count, visit http://www.hermetic.ch/cal_stud/jdn.htm. For more information on calendar systems visit http://www.fourmilab.ch/documents/calendar/. Excerpts from this page are included in these instructions, and are in quotes.
To get these functions to work, you have to compile PHP with
--enable-calendar.
The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The following constants are available since PHP 4.3.0 :
The following constants are available since PHP 5.0.0 :
(PHP 4 >= 4.1.0, PHP 5)
cal_days_in_month -- Return the number of days in a month for a given year and calendar
This function will return the number of days in the
month of year for
the specified calendar.
calendarCalendar to use for calculation
monthMonth in the selected calendar
yearYear in the selected calendar
cal_from_jd() converts the Julian day given in
jd into a date of the specified
calendar. Supported
calendar values are
CAL_GREGORIAN,
CAL_JULIAN,
CAL_JEWISH and
CAL_FRENCH.
Returns an array containing calendar information like month, day, year, day of week, abbreviated and full names of weekday and month and the date in string form "month/day/year".
Example 1. cal_from_jd() example
The above example will output:
|
cal_info() returns information on the
specified calendar.
Calendar information is returned as an array containing the
elements calname, calsymbol,
month, abbrevmonth and
maxdaysinmonth. The names of the different calendars
which can be used as calendar are as follows:
0 or CAL_GREGORIAN - Gregorian Calendar
1 or CAL_JULIAN - Julian Calendar
2 or CAL_JEWISH - Jewish Calendar
3 or CAL_FRENCH - French Revolutionary Calendar
If no calendar is specified information on all
supported calendars is returned as an array.
calendarCalendar to return information for. If no calendar is specified information about all calendars is returned.
Example 1. cal_info() example
The above example will output:
|
cal_to_jd() calculates the Julian day count
for a date in the specified calendar.
Supported calendars are
CAL_GREGORIAN,
CAL_JULIAN,
CAL_JEWISH and
CAL_FRENCH.
calendarCalendar to convert from, one of CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH or CAL_FRENCH.
month
The month as a number, the valid range depends
on the calendar
day
The day as a number, the valid range depends
on the calendar
year
The year as a number, the valid range depends
on the calendar
(PHP 3 >= 3.0.9, PHP 4, PHP 5)
easter_date -- Get Unix timestamp for midnight on Easter of a given yearReturns the Unix timestamp corresponding to midnight on Easter of the given year.
| Warning |
This function will generate a warning if the year is outside of the range for Unix timestamps (i.e. before 1970 or after 2037). |
The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate.
(The code is based on a C program by Simon Kershaw, <webmaster at ely.anglican dot org>)
(PHP 3 >= 3.0.9, PHP 4, PHP 5)
easter_days -- Get number of days after March 21 on which Easter falls for a given yearReturns the number of days after March 21 on which Easter falls for a given year. If no year is specified, the current year is assumed.
This function can be used instead of easter_date() to calculate Easter for years which fall outside the range of Unix timestamps (i.e. before 1970 or after 2037).
The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate.
(The code is based on a C program by Simon Kershaw, <webmaster at ely.anglican dot org>)
| Version | Description |
|---|---|
| Since 4.3.0 |
The year parameter is optional and defaults
to the current year according to the local time if omitted.
|
| Since 4.3.0 |
The method parameter was introduced
and allows to calculate easter dates based
on the Gregorian calendar during the years 1582 - 1752 when set to
CAL_EASTER_ROMAN. See the calendar constants for more valid
constants.
|
(PHP 3, PHP 4, PHP 5)
FrenchToJD -- Converts a date from the French Republican Calendar to a Julian Day CountConverts a date from the French Republican Calendar to a Julian Day Count.
These routines only convert dates in years 1 through 14 (Gregorian dates 22 September 1792 through 22 September 1806). This more than covers the period when the calendar was in use.
monthThe month as a number from 1 (for Vendémiaire) to 13 (for the period of 5-6 days at the end of each year)
dayThe day as a number from 1 to 30
yearThe year as a number between 1 and 14
Valid Range for Gregorian Calendar 4714 B.C. to 9999 A.D.
Although this function can handle dates all the way back to 4714 B.C., such use may not be meaningful. The Gregorian calendar was not instituted until October 15, 1582 (or October 5, 1582 in the Julian calendar). Some countries did not accept it until much later. For example, Britain converted in 1752, The USSR in 1918 and Greece in 1923. Most European countries used the Julian calendar prior to the Gregorian.
monthThe month as a number from 1 (for January) to 12 (for December)
dayThe day as a number from 1 to 31
yearThe year as a number between -4714 and 9999
Returns the day of the week. Can return a string or an integer depending on the mode.
Returns a string containing a month name.
mode tells this function which calendar to
convert the Julian Day Count to, and what type of month names are
to be returned.
Table 1. Calendar modes
| Mode | Meaning | Values |
|---|---|---|
| 0 | Gregorian - abbreviated | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec |
| 1 | Gregorian | January, February, March, April, May, June, July, August, September, October, November, December |
| 2 | Julian - abbreviated | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec |
| 3 | Julian | January, February, March, April, May, June, July, August, September, October, November, December |
| 4 | Jewish | Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul |
| 5 | French Republican | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra |
Converts a Julian Day Count to the French Republican Calendar.
Converts Julian Day Count to a string containing the Gregorian date in the format of "month/day/year".
Converts a Julian Day Count to the Jewish Calendar.
juliandayA julian day number as integer
hebrew
If the hebrew parameter is set to TRUE, the
fl parameter is used for Hebrew, string based,
output format.
flThe available formats are: CAL_JEWISH_ADD_ALAFIM_GERESH, CAL_JEWISH_ADD_ALAFIM, CAL_JEWISH_ADD_GERESHAYIM.
Converts Julian Day Count to a string containing the Julian Calendar Date in the format of "month/day/year".
This function will return a Unix timestamp corresponding to the
Julian Day given in jday or FALSE if
jday is not inside the Unix epoch
(Gregorian years between 1970 and 2037 or 2440588 <=
jday <= 2465342 ). The time returned is
localtime (and not GMT).
Although this function can handle dates all the way back to the year 1 (3761 B.C.), such use may not be meaningful. The Jewish calendar has been in use for several thousand years, but in the early days there was no formula to determine the start of a month. A new month was started when the new moon was first observed.
monthThe month as a number from 1 to 13
dayThe day as a number from 1 to 30
yearThe year as a number between 1 and 9999
Valid Range for Julian Calendar 4713 B.C. to 9999 A.D.
Although this function can handle dates all the way back to 4713 B.C., such use may not be meaningful. The calendar was created in 46 B.C., but the details did not stabilize until at least 8 A.D., and perhaps as late at the 4th century. Also, the beginning of a year varied from one culture to another - not all accepted January as the first month.
| Caution |
Remember, the current calendar system being used worldwide is the Gregorian calendar. gregoriantojd() can be used to convert such dates to their Julian Day count. |
monthThe month as a number from 1 (for January) to 12 (for December)
dayThe day as a number from 1 to 31
yearThe year as a number between -4713 and 9999
These functions interface the CCVS API, allowing you to work directly with CCVS from your PHP scripts. CCVS is RedHat's solution to the "middle-man" in credit card processing. It lets you directly address the credit card clearing houses via your *nix box and a modem. Using the CCVS module for PHP, you can process credit cards directly through CCVS via your PHP Scripts. The following references will outline the process.
Note: CCVS has been discontinued by Red Hat and there are no plans to issue further keys or support contracts. Those looking for a replacement can consider MCVE by Main Street Softworks as a potential replacement. It is similar in design and has documented PHP support!
This extension has been removed from PHP and is no longer available as of PHP 4.3.0. If you want to use credit card processing features you can use MCVE instead.
To enable CCVS Support in PHP, first verify your CCVS installation
directory. You will then need to configure PHP with the --with-ccvs option. If you use this
option without specifying the path to your CCVS installation, PHP
will attempt to look in the default CCVS Install location
(/usr/local/ccvs). If CCVS is in a non-standard location,
run configure with: --with-ccvs=[DIR], where
DIR is the path to your CCVS installation. Please note that CCVS support
requires that DIR/lib and DIR/include exist, and include
cv_api.h under the include directory and
libccvs.a under the lib directory.
Additionally, a ccvsd process will need to be running for the configurations you intend to use in your PHP scripts. You will also need to make sure the PHP Processes are running under the same user as your CCVS was installed as (e.g. if you installed CCVS as user 'ccvs', your PHP processes must run as 'ccvs' as well.)
RedHat has discontinued support for CCVS; however, a slightly outdated manual is still available at http://www.redhat.com/docs/manuals/ccvs/.
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
(4.0.2 - 4.2.3 only)
ccvs_command -- Performs a command which is peculiar to a single protocol, and thus is not available in the general CCVS API| Warning |
This function is currently not documented; only the argument list is available. |
(4.0.2 - 4.2.3 only)
ccvs_count -- Find out how many transactions of a given type are stored in the system| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
These functions allow you to obtain information about classes and instance objects. You can obtain the name of the class to which an object belongs, as well as its member properties and methods. Using these functions, you can find out not only the class membership of an object, but also its parentage (i.e. what class is the object class extending).
In this example, we first define a base class and an extension
of the class. The base class describes a general vegetable,
whether it is edible or not and what is its color. The subclass
Spinach adds a method to cook it and another to
find out if it is cooked.
Example 1. classes.inc
|
We then instantiate 2 objects from these classes and print out information about them, including their class parentage. We also define some utility functions, mainly to have a nice printout of the variables.
Example 2. test_script.php
One important thing to note in the example above is that
the object
|
(PHP 4 >= 4.0.5, PHP 5)
call_user_method_array -- Call a user method given with an array of parameters [deprecated]| Warning |
The call_user_method_array() function is deprecated as of PHP 4.1.0, use the call_user_func_array() variety with the array(&$obj, "method_name") syntax instead. |
(PHP 3 >= 3.0.3, PHP 4, PHP 5)
call_user_method -- Call a user method on an specific object [deprecated]| Warning |
The call_user_method() function is deprecated as of PHP 4.1.0, use the call_user_func() variety with the array(&$obj, "method_name") syntax instead. |
This function checks if the given class have been defined.
Example 2.
|
Returns an array of method names defined for the class specified by
class_name. In case of an error, it returns NULL.
Example 1. get_class_methods() example
The above example will output:
|
Get the default properties of the given class.
Returns an associative array of default public properties of the class. The resulting array elements are in the form of varname => value.
Example 1. get_class_vars() example
The above example will output:
|
Returns the name of the class of which object is an
instance. Returns FALSE if object is not an
object.
Example 1. Using get_class()
The above example will output:
|
Returns an array of the names of the declared classes in the current script.
Note: In PHP 4.0.1, three extra classes are returned at the beginning of the array: stdClass (defined in Zend/zend.c), OverloadedTestClass (defined in ext/standard/basic_functions.c) and Directory (defined in ext/standard/dir.c).
Also note that depending on what extensions you have compiled or loaded into PHP, additional classes could be present. This means that you will not be able to define your own classes using these names. There is a list of predefined classes in the Predefined Classes section of the appendices.
Returns an associative array of defined object properties for the
specified object. If a property have not been
assigned a value, it will be returned with a NULL value.
Example 1. Use of get_object_vars()
The above example will output:
|
Retrieves the parent class name for object or class.
Returns the name of the parent class of the class of which
object is an instance or the name.
If called without parameter outside object, this function returns FALSE.
| Version | Description |
|---|---|
| Before 5.1.0 | If called without parameter outside object, this function would have returned NULL with a warning. |
| Since 5.0.0 |
The object parameter is optional if called
from the object's method.
|
| Since 4.0.5 |
If object is a string, returns the name of the
parent class of the class with that name.
|
Example 1. Using get_parent_class()
The above example will output:
|
Checks if the given interface has been defined.
Returns TRUE if the interface given by
interface_name has been defined, FALSE otherwise.
(PHP 4 >= 4.2.0, PHP 5)
is_a -- Checks if the object is of this class or has this class as one of its parents
Checks if the given object is of this class or has
this class as one of its parents.
Note: The is_a() function is deprecated as of PHP 5 in favor of the instanceof type operator.
Returns TRUE if the object is of this class or has this class as one of its parents, FALSE otherwise.
Checks if the given object has the class
class_name as one of its parents.
This function returns TRUE if the object object,
belongs to a class which is a subclass of
class_name, FALSE otherwise.
Example 1. is_subclass_of() example
The above example will output:
|
Checks if the class method exists in the given
object.
Returns TRUE if the method given by method_name
has been defined for the given object, FALSE
otherwise.
This function checks if the given property exists in
the specified class (and if it is accessible from the current scope).
Note: As opposed with isset(), property_exists() returns TRUE even if the property has the value NULL.
classThe class name or an object of the class to test for
propertyThe name of the property
Returns TRUE if the property exists, FALSE if it doesn't exist or NULL in case of an error.
Example 1. A property_exists() example
|
These functions allow the dynamic manipulation of PHP classes, at runtime.
Note: This extension has been replaced by runkit, which is not limited to class manipulation but has function manipulation, as well.
This PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/classkit.
The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Note: This function cannot be used to manipulate the currently running (or chained) method.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Example 1. classkit_import() example
The above example will output:
|
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
classnameThe class to which this method will be added
methodnameThe name of the method to add
argsComma-delimited list of arguments for the newly-created method
code
The code to be evaluated when methodname
is called
flagsThe type of method to create, can be CLASSKIT_ACC_PUBLIC, CLASSKIT_ACC_PROTECTED or CLASSKIT_ACC_PRIVATE
Note: This parameter is only used as of PHP 5, because, prior to this, all methods were public.
Example 1. classkit_method_add() example
The above example will output:
|
| classkit_method_copy() |
| classkit_method_redefine() |
| classkit_method_remove() |
| classkit_method_rename() |
| create_function() |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dClassDestination class for copied method
dMethodDestination method name
sClassSource class of the method to copy
sMethod
Name of the method to copy from the source class. If this parameter is
omitted, the value of dMethod is assumed.
Example 1. classkit_method_copy() example
The above example will output:
|
| classkit_method_add() |
| classkit_method_redefine() |
| classkit_method_remove() |
| classkit_method_rename() |
Note: This function cannot be used to manipulate the currently running (or chained) method.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
classnameThe class in which to redefine the method
methodnameThe name of the method to redefine
argsComma-delimited list of arguments for the redefined method
code
The new code to be evaluated when methodname
is called
flagsThe redefined method can be CLASSKIT_ACC_PUBLIC, CLASSKIT_ACC_PROTECTED or CLASSKIT_ACC_PRIVATE
Note: This parameter is only used as of PHP 5, because, prior to this, all methods were public.
Example 1. classkit_method_redefine() example
The above example will output:
|
| classkit_method_add() |
| classkit_method_copy() |
| classkit_method_remove() |
| classkit_method_rename() |
Note: This function cannot be used to manipulate the currently running (or chained) method.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
classnameThe class in which to remove the method
methodnameThe name of the method to remove
| classkit_method_add() |
| classkit_method_copy() |
| classkit_method_redefine() |
| classkit_method_rename() |
Note: This function cannot be used to manipulate the currently running (or chained) method.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
classnameThe class in which to rename the method
methodnameThe name of the method to rename
newnameThe new name to give to the renamed method
ClibPDF lets you create PDF documents with PHP. ClibPDF functionality and API are similar to PDFlib. This documentation should be read alongside the ClibPDF manual since it explains the library in much greater detail.
Many functions in the native ClibPDF and the PHP module, as well as in PDFlib, have the same name. All functions except for cpdf_open() take the handle for the document as their first parameter.
Currently this handle is not used internally since ClibPDF does not support the creation of several PDF documents at the same time. Actually, you should not even try it, the results are unpredictable. I can't oversee what the consequences in a multi threaded environment are. According to the author of ClibPDF this will change in one of the next releases (current version when this was written is 1.10). If you need this functionality use the pdflib module.
A nice feature of ClibPDF (and PDFlib) is the ability to create the pdf document completely in memory without using temporary files. It also provides the ability to pass coordinates in a predefined unit length. (This feature can also be simulated by pdf_translate() when using the PDFlib functions.)
Another nice feature of ClibPDF is the fact that any page can be modified at any time even if a new page has been already opened. The function cpdf_set_current_page() allows to leave the current page and presume modifying an other page.
Most of the functions are fairly easy to use. The most difficult part is probably creating a very simple PDF document at all. The following example should help you to get started. It creates a document with one page. The page contains the text "Times-Roman" in an outlined 30pt font. The text is underlined.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.1.0.
Note: If you're interested in alternative free PDF generators that do not utilize external PDF libraries, see this related FAQ.
In order to use the ClibPDF functions you need to install the ClibPDF package. It is available for download from FastIO, but requires that you purchase a license for commercial use. PHP requires that you use cpdflib >= 2. The development of ClibPDF library has been discontinued thus FastIO website would be most probably inaccessible.
To get these functions to work, you have to compile PHP with
--with-cpdflib[=DIR]. DIR is the cpdflib
install directory, defaults to /usr. In addition you
can specify the jpeg library and the tiff library for ClibPDF to use. To do
so add to your configure line the options
--with-jpeg-dir[=DIR]
--with-tiff-dir[=DIR].
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Example 1. Simple ClibPDF Example
|
The pdflib distribution contains a more complex example which creates a series of pages with an analog clock. Here is that example converted into PHP using the ClibPDF extension:
Example 2. pdfclock example from pdflib 2.0 distribution
|
Adds a note at the specified point.
pdf_documentThe document handle, returned by cpdf_open().
llxLower left X
llyLower left Y
urxUpper right X
uryUpper right Y
titleThe title of the annotation
textThe contents of the annotation
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Adds a bookmark with text text that points to the
current page.
pdf_documentThe document handle, returned by cpdf_open().
lastoutline
sublevel
open
pagenr
textThe bookmark text
Draws an arc.
pdf_documentThe document handle, returned by cpdf_open().
xThe x-coordinate of the center
yThe y-coordinate of the center
radiusThe arc radius
startThe starting angle, in degrees
endThe ending angle, in degrees
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Starts a text section.
The created text section must be ended with cpdf_end_text().
Draws a circle.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the center
y_coorThe y-coordinate of the center
radiusThe circle radius
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Closes the PDF document.
This should be the last function called, even after cpdf_finalize(), cpdf_output_buffer() or cpdf_save_to_file().
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_closepath_fill_stroke -- Close, fill and stroke current pathCloses, fills the interior of the current path with the current fill color and draws current path.
| cpdf_closepath() |
| cpdf_stroke() |
| cpdf_fill() |
| cpdf_setgray_fill() |
| cpdf_setgray() |
| cpdf_setrgbcolor_fill() |
| cpdf_setrgbcolor() |
Closes the current path and draws a line along it.
cpdf_closepath_stroke() is a combination of cpdf_closepath() and cpdf_stroke().
Outputs the string in text in the next line.
Draws a Bezier curve from the current point to the point
(x3, y3) using
(x1, y1) and
(x2, y2) as control points.
pdf_documentThe document handle, returned by cpdf_open().
x1x-coordinate for the first control point
y1y-coordinate for the first control point
x2x-coordinate for the second control point
y2y-coordinate for the second control point
x3x-coordinate for the target
y3y-coordinate for the target
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Ends a text section which was started with cpdf_begin_text().
Fills the interior of the current path with the current fill color and draws current path.
| cpdf_closepath() |
| cpdf_stroke() |
| cpdf_fill() |
| cpdf_setgray_fill() |
| cpdf_setgray() |
| cpdf_setrgbcolor_fill() |
| cpdf_setrgbcolor() |
Fills the interior of the current path with the current fill color.
| cpdf_closepath() |
| cpdf_stroke() |
| cpdf_setgray_fill() |
| cpdf_setgray() |
| cpdf_setrgbcolor_fill() |
| cpdf_setrgbcolor() |
Ends the page which number is page_number.
This function is only used for saving memory. A finalized page takes less memory but cannot be modified anymore.
Ends the PDF document.
You still have to call cpdf_close().
Sets several document limits. This function has to be called before cpdf_open() to take effect. It sets the limits for any document open afterwards.
maxPagesThe maximum number of pages
maxFontsThe maximum number of fonts
maxImagesThe maximum number of images
maxAnnotsThe maximum number of annotations
maxObjectsThe maximum number of objects
Opens a JPEG image.
pdf_documentThe document handle, returned by cpdf_open().
file_nameThe path to the image file. The format of the image has to be JPEG
x_coorThe x-coordinate of the image
y_coorThe y-coordinate of the image
angleThe image rotation angle, in degrees
widthThe image width
heightThe image height
x_scale
y_scale
gsaveShould be non-zero to allow this function to operate correctly
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
The cpdf_lineto() function draws a line from the current point to the specified point.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the destination point
y_coorThe y-coordinate of the destination point
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Sets the current point to the given coordinates.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate
y_coorThe y-coordinate
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Opens a new PDF document.
compressionIf different from 0, document compression is turned on
filenameSets the file in which the document is written. - is a synonym for stdout.
If omitted, the document is created in memory and can either be written into a file with cpdf_save_to_file() or written to standard output with cpdf_output_buffer().
Note: Using stdout will not work if PHP is compiled as an apache module. You can solve this problem by skipping this parameter filename and using cpdf_output_buffer() later to output the PDF document.
doc_limitsAn array defining the document limitation. See cpdf_global_set_document_limits() for more information
Returns a document handle, needed as the first parameter for all other functions of the library.
(PHP 3 >= 3.0.9, PHP 4, PHP 5 <= 5.0.4)
cpdf_output_buffer -- Outputs the pdf document in memory bufferOutputs the pdf document to stdout.
The document has to be created in memory which is the case if cpdf_open() has been called without the file name parameter.
Starts a new page.
pdf_documentThe document handle, returned by cpdf_open().
page_numberThe page number
orientation0 for portrait and 1 for landscape
heightThe page height
widthThe page width
unitThe unit for the coordinate system. The value should be the number of postscript points per unit. Since one inch is equal to 72 points, a value of 72 would set the unit to one inch. The default is also 72.
Places an image created with the PHP image functions on the page. The image can be scaled at the same time.
Note: This function is only available if PHP was compiled with the GD Graphics Library 1.3. See the GD extension installation instructions for further information.
pdf_documentThe document handle, returned by cpdf_open().
imageAn image created with the PHP image functions
x_coorThe x-coordinate of the image
y_coorThe y-coordinate of the image
angleThe image rotation angle, in degrees
widthThe image width
heightThe image height
gsaveShould be non-zero to allow this function to operate correctly
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Draws a rectangle.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the lower left corner
y_coorThe y-coordinate of the lower left corner
widthThe rectangle width
heightThe rectangle height
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Example 1. Drawing a rectangle
|
Restores the environment saved with cpdf_save(). It works like the postscript command grestore. Very useful if you want to translate or rotate an object without effecting other objects.
The cpdf_rlineto() function draws a line from the current point to the given relative point.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the destination point
y_coorThe y-coordinate of the destination point
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Set the current point relative to the given coordinates.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the destination point
y_coorThe y-coordinate of the destination point
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
| Warning |
This function is currently not documented; only the argument list is available. |
Sets the rotation in degrees to angle.
Outputs the PDF document into a file if it has been created in memory.
This function is not needed if the PDF document has been open by specifying a filename as a parameter of cpdf_open().
pdf_documentThe document handle, returned by cpdf_open().
filenameThe path to the saved PDF document
Saves the current environment. It works like the postscript command gsave. Very useful if you want to translate or rotate an object without effecting other objects.
Sets the scaling factor in both directions.
pdf_documentThe document handle, returned by cpdf_open().
x_scaleThe X scale percent to set. Default to 0.0
y_scaleThe Y scale percent to set. Default to 0.0
| Warning |
This function is currently not documented; only the argument list is available. |
Sets the spacing between characters.
pdf_documentThe document handle, returned by cpdf_open().
spaceDistance between individual characters in a string.
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_set_creator -- Sets the creator field in the pdf documentSets the creator of a PDF document.
pdf_documentThe document handle, returned by cpdf_open().
creatorThe creator of the document
Sets the page on which all operations are performed. One can switch between pages until a page is finished with cpdf_finalize_page().
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)
cpdf_set_font_directories -- Sets directories to search when using external fonts
| Warning |
This function is currently not documented; only the argument list is available. |
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)
cpdf_set_font_map_file -- Sets fontname to filename translation map when using external fonts
| Warning |
This function is currently not documented; only the argument list is available. |
Sets the current font face, font size and encoding.
pdf_documentThe document handle, returned by cpdf_open().
font_nameThe font name. Currently only the standard postscript fonts are supported.
See the ClibPDF Manual for more information, especially on how to support Asian fonts.
sizeThe font size
encodingCan take the following values: MacRomanEncoding, MacExpertEncoding, WinAnsiEncoding, and NULL (the font's built-in encoding).
Sets the horizontal scaling to scale percent.
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_set_keywords -- Sets the keywords field of the pdf documentSets the keywords of the PDF document.
pdf_documentThe document handle, returned by cpdf_open().
keywordsThe keywords to set on the document
Sets the distance between text lines. This will be
used if text is output by cpdf_continue_text().
pdf_documentThe document handle, returned by cpdf_open().
distanceThe distance between text lines, as a float
Sets the transition between following pages.
pdf_documentThe document handle, returned by cpdf_open().
transition
The value of transition
can be
| 0 for none, |
| 1 for two lines sweeping across the screen reveal the page, |
| 2 for multiple lines sweeping across the screen reveal the page, |
| 3 for a box reveals the page, |
| 4 for a single line sweeping across the screen reveals the page, |
| 5 for the old page dissolves to reveal the page, |
| 6 for the dissolve effect moves from one screen edge to another, |
| 7 for the old page is simply replaced by the new page (default) |
duration
The value of duration is the number of seconds
between page flipping.
direction
orientation
inout
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_set_subject -- Sets the subject field of the pdf document
Sets the subject of the PDF document.
pdf_documentThe document handle, returned by cpdf_open().
subjectThe subject of the document
Sets a matrix which describes a transformation
applied on the current text font.
pdf_documentThe document handle, returned by cpdf_open().
matrixAn array of six elements describing the transformation
Sets the position of text for the next cpdf_show() call.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the text position
y_coorThe y-coordinate of the text position
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Determines how the text is rendered.
pdf_documentThe document handle, returned by cpdf_open().
rendermode
The possible values for rendermode are 0=fill
text, 1=stroke text, 2=fill and stroke text, 3=invisible, 4=fill
text and add it to clipping path, 5=stroke text and add it to
clipping path, 6=fill and stroke text and add it to clipping
path, 7=add it to clipping path.
Sets the text rising to value units.
pdf_documentThe document handle, returned by cpdf_open().
valueThe text rising, as a float
(PHP 3 >= 3.0.9, PHP 4, PHP 5 <= 5.0.4)
cpdf_set_viewer_preferences -- How to show the document in the viewer
| Warning |
This function is currently not documented; only the argument list is available. |
Sets the spacing between words.
Sets the dash pattern to the given one. If both parameters are 0, a solid line is set.
pdf_documentThe document handle, returned by cpdf_open().
whiteWhite units, as a float
blackBlack units, as a float
pdf_documentThe document handle, returned by cpdf_open().
valueThe flatness as a float, between 0 and 100
Sets the current gray value to fill a path.
pdf_documentThe document handle, returned by cpdf_open().
valueThe gray value, as a float
Sets the current drawing color to the given gray value.
pdf_documentThe document handle, returned by cpdf_open().
gray_valueThe gray value, as a float
Sets the current drawing and filling color to the given gray value.
pdf_documentThe document handle, returned by cpdf_open().
gray_valueThe gray value, as a float
pdf_documentThe document handle, returned by cpdf_open().
value0 = butt end, 1 = round, 2 = projecting square
pdf_documentThe document handle, returned by cpdf_open().
value0 = miter, 1 = round, 2 = bevel
pdf_documentThe document handle, returned by cpdf_open().
widthThe line width, as a float
pdf_documentThe document handle, returned by cpdf_open().
valueThe miter limit. Must be greater or equal than 1
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_setrgbcolor_fill -- Sets filling color to rgb color valueSets the current rgb color value to fill a path.
pdf_documentThe document handle, returned by cpdf_open().
red_valueThe red value, as a float between 0.0 (black) and 1.0 (red)
green_valueThe green value, as a float between 0.0 (black) and 1.0 (green)
blue_valueThe blue value, as a float between 0.0 (black) and 1.0 (blue)
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_setrgbcolor_stroke -- Sets drawing color to rgb color valueSets the current drawing color to the given rgb color value.
pdf_documentThe document handle, returned by cpdf_open().
red_valueThe red value, as a float between 0.0 (black) and 1.0 (red)
green_valueThe green value, as a float between 0.0 (black) and 1.0 (green)
blue_valueThe blue value, as a float between 0.0 (black) and 1.0 (blue)
(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)
cpdf_setrgbcolor -- Sets drawing and filling color to rgb color valueSets the current drawing and filling color to the given rgb color value.
pdf_documentThe document handle, returned by cpdf_open().
red_valueThe red value, as a float between 0.0 (black) and 1.0 (red)
green_valueThe green value, as a float between 0.0 (black) and 1.0 (green)
blue_valueThe blue value, as a float between 0.0 (black) and 1.0 (blue)
Outputs the string text at the given position.
Note: The function cpdf_show_xy() is identical to cpdf_text() without the optional parameters.
pdf_documentThe document handle, returned by cpdf_open().
textThe text
x_coorThe x-coordinate of the text position
y_coorThe y-coordinate of the text position
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
Returns the width of the string in text.
This function requires a font to be set before.
Outputs the string text at the given position.
pdf_documentThe document handle, returned by cpdf_open().
textThe text
x_coorThe x-coordinate of the text position
y_coorThe y-coordinate of the text position
modeThe optional parameter mode
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.
orientationRotation of the text in degrees
alignmodeDetermines how the text is aligned. See the ClibPDF documentation for possible values.
Sets the origin of coordinate system to the specified point.
pdf_documentThe document handle, returned by cpdf_open().
x_coorThe x-coordinate of the point
y_coorThe y-coordinate of the point
COM is an acronym for Component Object Model; it is an object orientated layer (and associated services) on top of DCE RPC (an open standard) and defines a common calling convention that enables code written in any language to call and interoperate with code written in any other language (provided those languages are COM aware). Not only can the code be written in any language, but it need not even be part of the same executable; the code can be loaded from a DLL, be found in another process running on the same machine, or, with DCOM (Distributed COM), be found in another process on a remote machine, all without your code even needing to know where a component resides.
There is a subset of COM known as OLE Automation which comprises a set of COM interfaces that allow loose binding to COM objects, so that they can be introspected and called at run-time without compile-time knowledge of how the object works. The PHP COM extension utilizes the OLE Automation interfaces to allow you to create and call compatible objects from your scripts. Technically speaking, this should really be called the "OLE Automation Extension for PHP", since not all COM objects are OLE compatible.
Now, why would or should you use COM? COM is one of the main ways to glue applications and components together on the Windows platform; using COM you can launch Microsoft Word, fill in a document template and save the result as a Word document and send it to a visitor of your web site. You can also use COM to perform administrative tasks for your network and to configure your IIS; these are just the most common uses; you can do much more with COM.
Starting with PHP 5, this extension (and this documentation) was rewritten from scratch and much of the old confusing and bogus cruft has be removed. Additionally, we support the instantiation and creation of .Net assemblies using the COM interoperability layer provided by Microsoft.
Please read this article for an overview of the changes in this extension in PHP 5.
COM functions are only available for the Windows version of PHP.
.Net support requires PHP 5 and the .Net runtime.
There is no installation needed to use these functions; they are part of the PHP core.
The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.
You are responsible for installing support for the various COM objects that you intend to use (such as MS Word); we don't and can't bundle all of those with PHP.
Starting with PHP 5, you may use PHP's own foreach statement to iterate over the contents of a standard COM/OLE IEnumVariant. In laymans terms, this means that you can use foreach in places where you would have used For Each in VB/ASP code.
Many COM objects expose their properties as arrays, or using array-style access. In PHP 4, you may use PHP array syntax to read/write such a property, but only a single dimension is allowed. If you want to read a multi-dimensional property, you could instead make the property access into a function call, with each parameter representing each dimension of the array access, but there is no way to write to such a property.
PHP 5 introduces the following new features to make your life easier:
Access multi-dimensional arrays, or COM properties that require multiple parameters using PHP array syntax. You can also write or set properties using this technique.
Iterate SafeArrays ("true" arrays) using the the Section called foreach in Chapter 16 control structure. This works because SafeArrays include information about their size. If an array-style property implements IEnumVariant then you can also use foreach for that property too; take a look at the Section called For Each for more information on this topic.
This extension will throw instances of the class com_exception whenever there is a potentially fatal error reported by COM. All COM exceptions have a well-defined code property that corresponds to the HRESULT return value from the various COM operations. You may use this code to make programmatic decisions on how to handle the exception.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Com configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| com.allow_dcom | "0" | PHP_INI_SYSTEM | Available since PHP 4.0.5. |
| com.autoregister_typelib | "0" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 4. Available since PHP 4.1.0. |
| com.autoregister_verbose | "0" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 4. Available since PHP 4.1.0. |
| com.autoregister_casesensitive | "1" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP 4. Available since PHP 4.1.0. |
| com.code_page | "" | PHP_INI_ALL | Available since PHP 5.0.0. |
| com.typelib_file | "" | PHP_INI_SYSTEM | Available since PHP 4.0.5. |
Here's a short explanation of the configuration directives.
com.allow_dcomWhen this is turned on, PHP will be allowed to operate as a D-COM (Distributed COM) client and will allow the PHP script to instantiate COM objects on a remote server.
com.autoregister_typelib
When this is turned on, PHP will attempt to register constants from
the typelibrary of objects that it instantiates, if those objects
implement the interfaces required to obtain that information.
The case sensitivity of the constants it registers is controlled by the
com.autoregister_casesensitive
configuration directive.
com.autoregister_verboseWhen this is turned on, any problems with loading a typelibrary during object instantiation will be reported using the PHP error mechanism. The default is off, which does not emit any indication if there was an error finding or loading the type library.
com.autoregister_casesensitiveWhen this is turned on (the default), constants found in auto-loaded type libraries will be registered case sensitively. See com_load_typelib() for more details.
com.code_pageIt controls the default character set code-page to use when passing strings to and from COM objects. If set to an empty string, PHP will assume that you want CP_ACP, which is the default system ANSI code page.
If the text in your scripts is encoded using a different encoding/character set by default, setting this directive will save you from having to pass the code page as a parameter to the COM class constructor. Please note that by using this directive (as with any PHP configuration directive), your PHP script becomes less portable; you should use the COM constructor parameter whenever possible.
Note: This configuration directive was introduced with PHP 5.
com.typelib_fileWhen set, this should hold the path to a file that contains a list of typelibraries that should be loaded on startup. Each line of the file will be treated as the type library name and loaded as though you had called com_load_typelib(). The constants will be registered persistently, so that the library only needs to be loaded once. If a type library name ends with the string #cis or #case_insensitive, then the constants from that library will be registered case insensitively.
This extension defines a reference to a COM component returned by deprecated com_load() (this function does not exist in PHP 5; use the COM class instead).
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
For further information on COM read the COM specification or perhaps take a look at Don Box's Yet Another COM Library (YACL). You might find some additional useful information in our FAQ for Chapter 66. If you're thinking of using MS Office applications on the server side, you should read the information here: Considerations for Server-Side Automation of Office.
The COM class allows you to instantiate an OLE compatible COM object and call its methods and access its properties.
COM class constructor. The parameters have the following meanings:
Can be a ProgID, Class ID or Moniker that names the component to load.
A ProgID is typically the application or DLL name, followed by a period, followed by the object name. e.g: Word.Application.
A Class ID is the UUID that uniquely identifies a given class.
A Moniker is a special form of naming, similar in concept to a URL scheme, that identifies a resource and specifies how it should be loaded. As an example, you could load up Word and get an object representing a word document by specifying the full path to the word document as the module name, or you can use LDAP: as a moniker to use the ADSI interface to LDAP.
The name of the DCOM server on which the component should be loaded and run. If NULL, the object is run using the default for the application. The default is typically to run it on the local machine, although the administrator might have configured the application to launch on a different machine.
If you specify a non-NULL value for server, PHP will refuse to load
the object unless the
com.allow_dcom
configuration option
is set to TRUE.
If server_name is an array, it should contain the
following elements (case sensitive!). Note that they are all optional
(although you need to specify both Username and Password together); if
you omit the Server setting, the default server will be used (as
mentioned above), and the instantiation of the object will not be
affected by the
com.allow_dcom
directive.
Table 1. DCOM server name
server_name key | type | description |
|---|---|---|
| Server | string | The name of the server. |
| Username | string | The username to connect as. |
| Password | string | The password for Username. |
| Flags | integer | One or more of the following constants, logically OR'd together:
CLSCTX_INPROC_SERVER,
CLSCTX_INPROC_HANDLER,
CLSCTX_LOCAL_SERVER,
CLSCTX_REMOTE_SERVER,
CLSCTX_SERVER and
CLSCTX_ALL. The default value if not
specified here is CLSCTX_SERVER if you also
omit Server, or
CLSCTX_REMOTE_SERVER if you do specify a
server. You should consult the Microsoft documentation for
CoCreateInstance for more information on the meaning of these
constants; you will typically never have to use them.
|
Specifies the codepage that is used to convert strings to unicode-strings and vice versa. The conversion is applied whenever a PHP string is passed as a parameter or returned from a method of this COM object. The code page is sticky in PHP 5, which means that it will propagate to objects and variants returned from the object.
Possible values are CP_ACP (use system default ANSI code page - the default if this parameter is omitted), CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP (use codepage/locale set for the current executing thread), CP_UTF7 and CP_UTF8. You may also use the number for a given codepage; consult the Microsoft documentation for more details on codepages and their numeric values.
The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM.
Starting with PHP 5, PHP will automatically detect methods that accept parameters by reference, and will automatically convert regular PHP variables to a form that can be passed by reference. This means that you can call the method very naturally; you needn't go to any extra effort in your code.
In PHP 4, to pass parameters by reference you need to create an instance of the VARIANT class to wrap the byref parameters.
In PHP versions prior to 5, a number of not very pleasant hacks meant that the following method names were not passed through to COM and were handled directly by PHP. PHP 5 eliminates these things; read the details below to determine how to fix your scripts. These magic method names are case insensitive.
void COM::AddRef ( void )Artificially adds a reference count to the COM object.
| Warning |
You should never need to use this method. It exists as a logical complement to the Release() method below. |
Artificially removes a reference count from the COM object.
| Warning |
You should never need to use this method. Its existence in PHP is a bug designed to work around a bug that keeps COM objects running longer than they should. |
These pseudo methods are only available if com_isenum() returns TRUE, in which case, they hide any methods with the same names that might otherwise be provided by the COM object. These methods have all been eliminated in PHP 5, and you should use the Section called For Each in Reference XV, COM and .Net (Windows) instead.
variant COM::All ( void )Returns a variant representing a SafeArray that has 10 elements; each element will be an empty/null variant. This function was supposed to return an array containing all the elements from the iterator, but was never completed. Do not use.
variant COM::Next ( void )Returns a variant representing the next element available from the iterator, or FALSE when there are no more elements.
variant COM::Prev ( void )Returns a variant representing the previous element available from the iterator, or FALSE when there are no more elements.
void COM::Reset ( void )Rewinds the iterator back to the start.
Example 1. COM example (1)
|
Example 2. COM example (2)
|
The DOTNET class allows you to instantiate a class from a .Net assembly and call its methods and access its properties.
DOTNET class constructor. assembly_name specifies
which assembly should be loaded, and class_name
specifices which class in that assembly to instantiate. You may
optionally specify a codepage to use for unicode
string transformations; see the COM class
for more details on code pages.
The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM and from there to DOTNET. In other words, the .Net object is mapped through the COM interoperability layer provided by the .Net runtime.
Once you have created a DOTNET object, PHP treats it identically to any other COM object; all the same rules apply.
Note: You need to install the .Net runtime on your web server to take advantage of this feature.
The VARIANT is COM's equivalent of the PHP zval; it is a structure that can contain a value with a range of different possible types. The VARIANT class provided by the COM extension allows you to have more control over the way that PHP passes values to and from COM.
VARIANT class constructor. Parameters:
initial value. if omitted, or set to NULL an VT_EMPTY object is created.
specifies the content type of the VARIANT object. Possible values are one of the VT_XXX the Section called Predefined Constants in Reference XV, COM and .Net (Windows).
In PHP versions prior to PHP 5, you could force PHP to pass a variant
object by reference by OR'ing VT_BYREF
with the type. In PHP 5, this hack is not
supported; instead, PHP 5 can detect parameters passed by reference
automatically; they do not even need to be passed as VARIANT objects.
Consult the MSDN library for additional information on the VARIANT type.
specifies the codepage that is used to convert strings to unicode. See the parameter of the same name in the COM class for more information.
PHP versions prior to PHP 5 define a number of (undocumented) virtual properties for instances of the VARIANT class; these properties have all been removed in PHP 5 in favour of its more natural syntax; these differences are best highlighted by example:
The reason for the change is that, internally, the COM extension sees VARIANT, COM and DOTNET classes as the same thing, and the design philosophy for these classes is that all property and member accesses are passed through to COM with no interference. The new syntax is more natural and less effort, and most of the removed virtual properties didn't make any sense in a PHP context in any case.
Note: PHP 5 takes a much simpler approach to handling VARIANTs; when returning a value or fetching a variant property, the variant is converted to a PHP value only when there is a direct mapping between the types that would not result in a loss of information. In all other cases, the result is returned as an instance of the VARIANT class. You can force PHP to convert or evaluate the variant as a PHP native type by using a casting operator explicitly, or implicitly casting to a string by print()ing it. You may use the wide range of variant functions to perform arithmetic operations on variants without forcing a conversion or risking a loss of data.
See also variant_get_type().
Increases the components reference counter.
| Warning |
You should never need to use this function. |
Generates a Globally Unique Identifier (GUID) and returns it as a string. A GUID is generated in the same way as DCE UUID's, except that the Microsoft convention is to enclose a GUID in curly braces.
See also uuid_create() in the PECL uuid extension.
Instructs COM to sink events generated by
comobject into the PHP object
sinkobject. PHP will attempt to use the default
dispinterface type specified by the typelibrary associated with
comobject, but you may override this choice by
setting sinkinterface to the name of the
dispinterface that you want to use.
sinkobject should be an instance of a class with
methods named after those of the desired dispinterface; you may use
com_print_typeinfo() to help generate a template class
for this purpose.
Be careful how you use this feature; if you are doing something similar to the example below, then it doesn't really make sense to run it in a web server context.
Example 1. COM event sink example
|
See also com_print_typeinfo(), com_message_pump().
com_get_active_object() is similar to creating a new instance of a COM object, except that it will only return an object to your script if the object is already running. OLE applications use something known as the Running Object Table to allow well-known applications to be launched only once; this function exposes the COM library function GetActiveObject() to get a handle on a running instance.
progid must be either the ProgID or CLSID for the
object that you want to access (for example
Word.Application). code_page
acts in precisely the same way that it does for the COM class.
If the requested object is running, it will be returned to your script just like any other COM object. Otherwise a com_exception will be raised. There are a variety of reasons why this function might fail, the most common being that the object is not already running. In that situation, the exception error code will be MK_E_UNAVAILABLE; you can use the getCode method of the exception object to check the exception code.
| Warning |
Using com_get_active_object() in a web server context is not always a smart idea. Most COM/OLE applications are not designed to handle more than one client concurrently, even (or especially!) Microsoft Office. You should read Considerations for Server-Side Automation of Office for more information on the general issues involved. |
Returns the value of the property of the
COM component referenced by com_object.
Returns FALSE on error.
Note: This function does not exist in PHP 5; instead, you should use the regular and more natural OO syntax to access properties or call methods.
com_invoke() invokes the method
named function_name of the COM
component referenced by com_object.
com_invoke() returns FALSE on error,
returns the function_name's return
value on success. All the extra parameters
function_parameters are passed to
the method function_name.
Note: This function does not exist in PHP 5; instead, you should use the regular and more natural OO syntax to access properties or call methods.
(PHP 4 >= 4.1.0)
com_isenum -- Indicates if a COM object has an IEnumVariant interface for iteration [deprecated]Checks to see if a COM object can be enumerated using the Next() method hack. Returns TRUE if it can, FALSE if it cannot. See COM class for more details on these methods.
Note: This function does not exist in PHP 5; use the more natural foreach statement to iterate over the contents of COM objects. See the Section called For Each in Reference XV, COM and .Net (Windows) for more details.
Loads a type-library and registers its constants in the engine, as though
they were defined using define(). The
case_insensitive behaves in the same way as the
parameter with the same name in the define() function.
typelib_name can be one of the following:
The filename of a .tlb file or the executable module that contains the type library.
The type library GUID, followed by its version number, for example {00000200-0000-0010-8000-00AA006D2EA4},2,0.
The type library name, e.g. Microsoft OLE DB ActiveX Data Objects 1.0 Library.
Note that it is much more efficient to use the
com.typelib_file
configuration setting to pre-load and register the constants,
although not so flexible.
If you have turned on
com.autoregister_typelib
,
then PHP will attempt to automatically register the constants associated
with a COM object when you instantiate it. This depends on the
interfaces provided by the COM object itself, and may not always be
possible.
Equivalent to using the new operator to create an instance of the COM class. You should do that instead of calling this function.
Note: This function does not exist in PHP 5; use the COM class instead.
(PHP 4 >= 4.2.3, PHP 5)
com_message_pump -- Process COM messages, sleeping for up to timeoutms milliseconds
This function will sleep for up to timeoutms
milliseconds, or until a message arrives in the queue. If a message or
messages arrives before the timeout, they will be dispatched, and the
function will return TRUE. If the timeout occurs and no messages were
processed, the return value will be FALSE. If you do not specify a
value for timeoutms, then 0 will be assumed. A 0
value means that no waiting will be performed; if there are messages
pending they will be dispatched as before; if there are no messages
pending, the function will return FALSE immediately without sleeping.
The purpose of this function is to route COM calls between apartments and handle various synchronization issues. This allows your script to wait efficiently for events to be triggered, while still handling other events or running other code in the background. You should use it in a loop, as demonstrated by the example in the com_event_sink() function, until you are finished using event bound COM objects.
(PHP 4 >= 4.2.3, PHP 5)
com_print_typeinfo -- Print out a PHP class definition for a dispatchable interfaceThe purpose of this function is to help generate a skeleton class for use as an event sink. You may also use it to generate a dump of any COM object, provided that it supports enough of the introspection interfaces, and that you know the name of the interface you want to display.
comobject should be either an instance of a COM
object, or be the name of a typelibrary (which will be resolved according
to the rules set out in com_load_typelib()).
dispinterface is the name of an IDispatch
descendant interface that you want to display. If
wantsink is TRUE, the corresponding sink
interface will be displayed instead.
See also com_event_sink(), com_load_typelib().
This function is an alias of: com_get().
Note: This function does not exist in PHP 5; instead, you should use the regular and more natural OO syntax to access properties or call methods.
This function is an alias of: com_set().
Note: This function does not exist in PHP 5; instead, you should use the regular and more natural OO syntax to access properties or call methods.
This function is an alias of: com_set().
Note: This function does not exist in PHP 5; instead, you should use the regular and more natural OO syntax to access properties or call methods.
Decreases the components reference counter.
| Warning |
You should never need to use this function. |
Note: This function has gone away in PHP 5.
Sets the value of the property of the COM
component referenced by com_object.
Returns the newly set value if succeeded, FALSE on error.
Note: This function does not exist in PHP 5; instead, you should use the regular and more natural OO syntax to access properties or call methods.
Returns the absolute value of val.
See also abs().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Adds left to right using
the following rules (taken from the MSDN library), which correspond to
those of Visual Basic:
Table 1. Variant Addition Rules
| If | Then |
|---|---|
| Both expressions are of the string type | Concatenation |
| One expression is a string type and the other a character | Addition |
| One expression is numeric and the other is a string | Addition |
| Both expressions are numeric | Addition |
| Either expression is NULL | NULL is returned |
| Both expressions are empty | Integer subtype is returned |
See also variant_sub().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Performs a bitwise AND operation, according to the following truth table; note that this is slightly different from a regular AND operation.
Table 1. Variant AND Rules
If left is | If right is | then the result is |
|---|---|---|
| TRUE | TRUE | TRUE |
| TRUE | FALSE | FALSE |
| TRUE | NULL | NULL |
| FALSE | TRUE | FALSE |
| FALSE | FALSE | FALSE |
| FALSE | NULL | FALSE |
| NULL | TRUE | NULL |
| NULL | FALSE | FALSE |
| NULL | NULL | NULL |
See also variant_or().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
This function makes a copy of variant and then
performs a variant cast operation to force the copy to have the type
given by type. type should
be one of the VT_XXX constants.
This function wraps VariantChangeType() in the COM library; consult MSDN for more information.
See also variant_set_type().
Concatenates left with
right and returns the result.
See also the Section called String Operators in Chapter 15 for the string
concatenation operator; this function is notionally equivalent to
$left . $right.
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Compares left with right
and returns one of the following values:
Table 1. Variant Comparision Results
| value | meaning |
|---|---|
| VARCMP_LT | left is less than
right
|
| VARCMP_EQ | left is equal to
right
|
| VARCMP_GT | left is greater than
right
|
| VARCMP_NULL | Either left,
right or both are NULL
|
This function will only compare scalar values, not arrays or variant records.
lcid is a valid Locale Identifier to use when
comparing strings (this affects string collation).
flags can be one or more of the following values
OR'd together, and affects string comparisons:
Table 2. Variant Comparision Flags
| value | meaning |
|---|---|
| NORM_IGNORECASE | Compare case insensitively |
| NORM_IGNORENONSPACE | Ignore nonspacing characters |
| NORM_IGNORESYMBOLS | Ignore symbols |
| NORM_IGNOREWIDTH | Ignore string width |
| NORM_IGNOREKANATYPE | Ignore Kana type |
| NORM_IGNOREKASHIDA | Ignore Arabic kashida characters |
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Converts timestamp from a unix timestamp value
into a variant of type VT_DATE. This allows easier
interopability between the unix-ish parts of PHP and COM.
See also variant_date_to_timestamp() for the inverse of this operation, mktime(), time().
Converts variant from a VT_DATE
(or similar) value into a Unix timestamp. This allows easier
interopability between the Unix-ish parts of PHP and COM.
See also variant_date_from_timestamp() for the inverse of this operation, date(), strftime().
Divides left by right and
returns the result, subject to the following rules:
Table 1. Variant Division Rules
| If | Then |
|---|---|
| Both expressions are of the string, date, character, boolean type | Double is returned |
| One expression is a string type and the other a character | Division and a double is returned |
| One expression is numeric and the other is a string | Division and a double is returned. |
| Both expressions are numeric | Division and a double is returned |
| Either expression is NULL | NULL is returned |
right is empty and
left is anything but empty | A com_exception with code DISP_E_DIVBYZERO is thrown |
left is empty and
right is anything but empty. | 0 as type double is returned |
| Both expressions are empty | A com_exception with code DISP_E_OVERFLOW is thrown |
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
If each bit in left is equal to the corresponding
bit in right then TRUE is returned, otherwise
FALSE is returned.
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
If variant is negative, then the first negative
integer greater than or equal to the variant is returned, otherwise
returns the integer portion of the value of
variant.
See also variant_int(), variant_round(), floor(), ceil(), round().
| Warning |
This documentation is based on the MSDN documentation; it appears that this function is either the same as variant_int(), or that there is an error in the MSDN documentation. |
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
This function returns an integer value that indicates the type of
variant, which can be an instance of
COM,
DOTNET or
VARIANT classes. The return value
can be compared to one of the VT_XXX constants.
The return value for COM and DOTNET objects will usually be VT_DISPATCH; the only reason this function works for those classes is because COM and DOTNET are descendants of VARIANT.
In PHP versions prior to 5, you could obtain this information from
instances of the VARIANT class ONLY, by reading a fake
type property. See the VARIANT class for more information on
this.
Converts left and right to
integer values, and then performs integer division according the
following rules:
Table 1. Variant Integer Division Rules
| If | Then |
|---|---|
| Both expressions are of the string, date, character, boolean type | Division and integer is returned |
| One expression is a string type and the other a character | Division |
| One expression is numeric and the other is a string | Division |
| Both expressions are numeric | Division |
| Either expression is NULL | NULL is returned |
| Both expressions are empty | A com_exception with code DISP_E_DIVBYZERO is thrown |
See also variant_div().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Performs a bitwise implication operation, according to the following truth table:
Table 1. Variant Implication Table
If left is | If right is | then the result is |
|---|---|---|
| TRUE | TRUE | TRUE |
| TRUE | FALSE | TRUE |
| TRUE | NULL | TRUE |
| FALSE | TRUE | TRUE |
| FALSE | FALSE | TRUE |
| FALSE | NULL | TRUE |
| NULL | TRUE | TRUE |
| NULL | FALSE | NULL |
| NULL | NULL | NULL |
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
If variant is negative, then the first negative
integer greater than or equal to the variant is returned, otherwise
returns the integer portion of the value of
variant.
See also variant_fix(), variant_round(), floor(), ceil(), round().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Divides left by right and
returns the remainder.
See also variant_div(), variant_idiv().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Multiplies left by right and
returns the result, subject to the following rules:
Table 1. Variant Multiplication Rules
| If | Then |
|---|---|
| Both expressions are of the string, date, character, boolean type | Multiplication |
| One expression is a string type and the other a character | Multiplication |
| One expression is numeric and the other is a string | Multiplication |
| Both expressions are numeric | Multiplication |
| Either expression is NULL | NULL is returned |
| Both expressions are empty | Empty string is returned |
Boolean values are converted to -1 for FALSE and 0 for TRUE.
See also variant_div(), variant_idiv().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Performs logical negation of variant and returns
the result.
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Performs bitwise not negation on variant and
returns the result. If variant is NULL, the
result will also be NULL.
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Performs a bitwise OR operation, according to the following truth table; note that this is slightly different from a regular OR operation.
Table 1. Variant OR Rules
If left is | If right is | then the result is |
|---|---|---|
| TRUE | TRUE | TRUE |
| TRUE | FALSE | TRUE |
| TRUE | NULL | TRUE |
| FALSE | TRUE | TRUE |
| FALSE | FALSE | FALSE |
| FALSE | NULL | NULL |
| NULL | TRUE | TRUE |
| NULL | FALSE | NULL |
| NULL | NULL | NULL |
See also variant_and(), variant_xor().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Returns the result of left to the power of
right.
See also pow().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Returns the value of variant rounded to
decimals decimal places.
See also round().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
This function is similar to variant_cast() except that the variant is modified "in-place"; no new variant is created. The parameters for this function have identical meaning to those of variant_cast().
See also variant_cast().
Converts value to a variant and assigns it to the
variant object; no new variant object is created,
and the old value of variant is freed/released.
(PHP 5)
variant_sub -- subtracts the value of the right variant from the left variant value and returns the result
Subtracts right from left using
the following rules:
Table 1. Variant Subtraction Rules
| If | Then |
|---|---|
| Both expressions are of the string type | Subtraction |
| One expression is a string type and the other a character | Subtraction |
| One expression is numeric and the other is a string | Subtraction. |
| Both expressions are numeric | Subtraction |
| Either expression is NULL | NULL is returned |
| Both expressions are empty | Empty string is returned |
See also variant_add().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
Performs a logical exclusion, according to the following truth table:
Table 1. Variant XOR Rules
If left is | If right is | then the result is |
|---|---|---|
| TRUE | TRUE | FALSE |
| TRUE | FALSE | TRUE |
| FALSE | TRUE | TRUE |
| FALSE | FALSE | FALSE |
| NULL | NULL | NULL |
See also variant_and(), variant_or().
Note: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.
These functions allow you to use the CrackLib library to test the 'strength' of a password. The 'strength' of a password is tested by that checks length, use of upper and lower case and checked against the specified CrackLib dictionary. CrackLib will also give helpful diagnostic messages that will help 'strengthen' the password.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.0.0.
More information regarding CrackLib along with the library can be found at http://sourceforge.net/projects/cracklib.
This PECL extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/crack.
In PHP 4 this PECL extensions
source can be found in the ext/ directory within the
PHP source or at the PECL link above.
In order to use these functions you must compile PHP with Crack support
by using the --with-crack[=DIR]
configuration option.
Windows users will enable php_crack.dll inside of php.ini in order to use these functions. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
The behaviour of these functions is affected by settings in php.ini.
Table 1. Crack configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| crack.default_dictionary | NULL | PHP_INI_PERDIR | Available since PHP 4.0.5. |
The CrackLib extension defines a dictionary resource identifier returned by crack_opendict().
This example shows how to open a CrackLib dictionary, test a given password, retrieve any diagnostic messages, and close the dictionary.
Example 1. CrackLib example
|
Note: If crack_check() returns TRUE, crack_getlastmessage() will return 'strong password'.
Performs an obscure check with the given password on the specified dictionary.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dictionaryThe crack lib dictionary. If not specified, the last opened dictionary is used.
passwordThe tested password.
crack_closedict() closes the specified
dictionary identifier.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
crack_getlastmessage() returns the message from the last obscure check.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
The message from the last obscure check or FALSE if there was no obscure checks made so far.
The returned message is one of:
it's WAY too short
it is too short
it does not contain enough DIFFERENT characters
it is all whitespace
it is too simplistic/systematic
it looks like a National Insurance number.
it is based on a dictionary word
it is based on a (reversed) dictionary word
strong password
crack_opendict() opens the specified CrackLib
dictionary for use with
crack_check().
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Note: Only one dictionary may be open at a time.
The functions provided by this extension check whether a character or string falls into a certain character class according to the current locale (see also setlocale()).
When called with an integer argument these functions behave exactly like their C counterparts from ctype.h. It means that if you pass an integer smaller than 256 it will use the ASCII value of it to see if it fits in the specified range (digits are in 0x30-0x39). If the number is between -128 and -1 inclusive then 256 will be added and the check will be done on that.
When called with a string argument they will check every character in the string and will only return TRUE if every character in the string matches the requested criteria. When called with an empty string the result will always be TRUE in PHP < 5.1 and FALSE since 5.1.
Passing anything else but a string or integer will return FALSE immediately.
It should be noted that ctype functions are always preferred over regular expressions, and even to some equivalent str_* and is_* functions. This is because of the fact that ctype uses a native C library and thus processes significantly faster.
Beginning with PHP 4.2.0 these functions are enabled by default.
For older versions you have to configure and compile PHP with
--enable-ctype. You can disable
ctype support with --disable-ctype.
The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.
Note: Builtin support for ctype is available with PHP 4.3.0.
Checks if all of the characters in the provided string,
text, are alphanumeric. In the standard
C locale letters are just [A-Za-z]
and the function is equivalent to
preg_match('/^[a-z0-9]+$/iD', $text).
Returns TRUE if every character in text is either
a letter or a digit, FALSE otherwise.
Example 1. A ctype_alnum() example (using the default locale)
The above example will output:
|
Checks if all of the characters in the provided string,
text, are alphabetic.
In the standard C locale letters are just
[A-Za-z] and ctype_alpha() is
equivalent to (ctype_upper($text) || ctype_lower($text))
if $text is just a single character, but other languages have letters that
are considered neither upper nor lower case.
Returns TRUE if every character in text is
a letter from the current locale, FALSE otherwise.
Example 1. A ctype_alpha() example (using the default locale)
The above example will output:
|
Checks if all of the characters in the provided string,
text, are control characters.
Control characters are e.g. line feed, tab, escape.
Returns TRUE if every character in text is
a control character from the current locale, FALSE otherwise.
Example 1. A ctype_cntrl() example
The above example will output:
|
Checks if all of the characters in the provided string,
text, are numerical.
Example 1. A ctype_digit() example
The above example will output:
|
Checks if all of the characters in the provided string,
text, creates visible output.
Returns TRUE if every character in text is
printable and actually creates visible output (no white space), FALSE
otherwise.
Example 1. A ctype_graph() example
The above example will output:
|
Checks if all of the characters in the provided string,
text, are lowercase letters.
Example 1. A ctype_lower() example (using the default locale)
The above example will output:
|
Checks if all of the characters in the provided string,
text, are printable.
Returns TRUE if every character in text
will actually create output (including blanks). Returns FALSE if
text contains control characters or characters
that do not have any output or control function at all.
Example 1. A ctype_print() example
The above example will output:
|
(PHP 4 >= 4.0.4, PHP 5)
ctype_punct -- Check for any printable character which is not whitespace or an alphanumeric character
Checks if all of the characters in the provided string,
text, are punctuation character.
Returns TRUE if every character in text
is printable, but neither letter, digit or blank, FALSE otherwise.
Example 1. A ctype_punct() example
The above example will output:
|
Checks if all of the characters in the provided string,
text, creates whitespace.
Returns TRUE if every character in text
creates some sort of white space, FALSE otherwise. Besides the
blank character this also includes tab, vertical tab, line feed,
carriage return and form feed characters.
Example 1. A ctype_space() example
The above example will output:
|
Checks if all of the characters in the provided string,
text, are uppercase characters.
Example 1. A ctype_upper() example (using the default locale)
The above example will output:
|
Checks if all of the characters in the provided string,
text, are hexadecimal 'digits'.
Returns TRUE if every character in text is
a hexadecimal 'digit', that is a decimal digit or a character from
[A-Fa-f] , FALSE otherwise.
Example 1. A ctype_xdigit() example
The above example will output:
|
PHP supports libcurl, a library created by Daniel Stenberg, that allows you to connect and communicate to many different types of servers with many different types of protocols. libcurl currently supports the http, https, ftp, gopher, telnet, dict, file, and ldap protocols. libcurl also supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading (this can also be done with PHP's ftp extension), HTTP form based upload, proxies, cookies, and user+password authentication.
These functions have been added in PHP 4.0.2.
In order to use PHP's cURL functions you need to install the libcurl package. PHP requires that you use libcurl 7.0.2-beta or higher. In PHP 4.2.3, you will need libcurl version 7.9.0 or higher. From PHP 4.3.0, you will need a libcurl version that's 7.9.8 or higher. PHP 5.0.0 requires a libcurl version 7.10.5 or greater.
To use PHP's cURL support you must also compile PHP --with-curl[=DIR] where DIR is the
location of the directory containing the lib and include
directories. In the "include" directory there should be a folder
named "curl" which should contain the easy.h and
curl.h files. There should be a file named
libcurl.a located in the "lib" directory. Beginning
with PHP 4.3.0 you can configure PHP to use cURL for URL streams
--with-curlwrappers.
Note to Win32 Users: In order to enable this module on a Windows environment, libeay32.dll and ssleay32.dll must be present in your PATH.
You don't need libcurl.dll from the cURL site.
Once you've compiled PHP with cURL support, you can begin using the cURL functions. The basic idea behind the cURL functions is that you initialize a cURL session using the curl_init(), then you can set all your options for the transfer via the curl_setopt(), then you can execute the session with the curl_exec() and then you finish off your session using the curl_close(). Here is an example that uses the cURL functions to fetch the example.com homepage into a file:
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Available since PHP 5.2.0
Available since PHP 5.2.0
Available since PHP 5.2.0
Available since PHP 5.2.0
Available since PHP 5.2.0
Available since PHP 5.1.0
This constant is not available when opendbase_dir or safe_mode are enabled.
Available since PHP 5.2.1
Available since PHP 6.0.0
Available since PHP 5.1.0
Available since PHP 5.1.0
Available since PHP 5.1.0
Closes a cURL session and frees all resources. The cURL handle,
ch, is also deleted.
Example 1. Initializing a new cURL session and fetching a web page
|
Copies a cURL handle keeping the same preferences.
Example 1. Copying a cURL handle
|
(PHP 4 >= 4.0.3, PHP 5)
curl_error -- Return a string containing the last error for the current sessionReturns a clear text error message for the last cURL operation.
Execute the given cURL session.
This function should be called after initializing a cURL session and all the options for the session are set.
Returns TRUE on success or FALSE on failure. However, if the CURLOPT_RETURNTRANSFER option is set, it will return the result on success, FALSE on failure.
Example 1. Fetching a web page
|
chA cURL handle returned by curl_init().
optThis may be one of the following constants:
CURLINFO_EFFECTIVE_URL - Last effective URL
CURLINFO_HTTP_CODE - Last received HTTP code
CURLINFO_FILETIME - Remote time of the retrieved document, if -1 is returned the time of the document is unknown
CURLINFO_TOTAL_TIME - Total transaction time in seconds for last transfer
CURLINFO_NAMELOOKUP_TIME - Time in seconds until name resolving was complete
CURLINFO_CONNECT_TIME - Time in seconds it took to establish the connection
CURLINFO_PRETRANSFER_TIME - Time in seconds from start until just before file transfer begins
CURLINFO_STARTTRANSFER_TIME - Time in seconds until the first byte is about to be transferred
CURLINFO_REDIRECT_TIME - Time in seconds of all redirection steps before final transaction was started
CURLINFO_SIZE_UPLOAD - Total number of bytes uploaded
CURLINFO_SIZE_DOWNLOAD - Total number of bytes downloaded
CURLINFO_SPEED_DOWNLOAD - Average download speed
CURLINFO_SPEED_UPLOAD - Average upload speed
CURLINFO_HEADER_SIZE - Total size of all headers received
CURLINFO_HEADER_OUT - The request string sent. Available since PHP 6.0.0
CURLINFO_REQUEST_SIZE - Total size of issued requests, currently only for HTTP requests
CURLINFO_SSL_VERIFYRESULT - Result of SSL certification verification requested by setting CURLOPT_SSL_VERIFYPEER
CURLINFO_CONTENT_LENGTH_DOWNLOAD - content-length of download, read from Content-Length: field
CURLINFO_CONTENT_LENGTH_UPLOAD - Specified size of upload
CURLINFO_CONTENT_TYPE - Content-type of downloaded object, NULL indicates server did not send valid Content-Type: header
If opt is given, returns its value as a string.
Otherwise, returns an associative array with the following elements
(which correspond to opt):
"url"
"content_type"
"http_code"
"header_size"
"request_size"
"filetime"
"ssl_verify_result"
"redirect_count"
"total_time"
"namelookup_time"
"connect_time"
"pretransfer_time"
"size_upload"
"size_download"
"speed_download"
"speed_upload"
"download_content_length"
"upload_content_length"
"starttransfer_time"
"redirect_time"
Initializes a new session and return a cURL handle for use with the curl_setopt(), curl_exec(), and curl_close() functions.
urlIf provided, the CURLOPT_URL option will be set to its value. You can manually set this using the curl_setopt() function.
Example 1. Initializing a new cURL session and fetching a web page
|
Adds the ch handle to the multi handle
mh
mhA cURL multi handle returned by curl_multi_init().
chA cURL handle returned by curl_init().
Example 1. curl_multi_add_handle() example This example will create two cURL handles, add them to a multi handle, and then run them in parallel.
|
Example 1. curl_multi_close() example This example will create two cURL handles, add them to a multi handle, and then run them in parallel.
|
Processes each of the handles in the stack. This method can be called whether or not a handle needs to read or write data.
mhA cURL multi handle returned by curl_multi_init().
still_runningA reference to a flag to tell whether the operations are still running.
A cURL code defined in the cURL Predefined Constants.
Note: This only returns errors regarding the whole multi stack. There might still have occurred problems on individual transfers even when this function returns CURLM_OK.
Example 1. curl_multi_exec() example This example will create two cURL handles, add them to a multi handle, and then run them in parallel.
|
(PHP 5)
curl_multi_getcontent -- Return the content of a cURL handle if CURLOPT_RETURNTRANSFER is setIf CURLOPT_RETURNTRANSFER is an option that is set for a specific handle, then this function will return the content of that cURL handle in the form of a string.
Ask the multi handle if there are any messages/informationals from the individual transfers. Messages may include informationals such as an error code from the transfer or just the fact that a transfer is completed.
Repeated calls to this function will return a new result each time, until a FALSE is returned
as a signal that there is no more to get at this point. The integer pointed to with
msgs_in_queue will contain the number of remaining messages after this
function was called.
| Warning |
The data the returned resource points to will not survive calling curl_multi_remove_handle(). |
mhA cURL multi handle returned by curl_multi_init().
msgs_in_queueNumber of messages that are still in the queue
Allows the processing of multiple cURL handles in parallel.
Example 1. curl_multi_init() example This example will create two cURL handles, add them to a multi handle, and then run them in parallel.
|
Removes a given ch handle from the given mh
handle. When the ch handle has been removed, it is again perfectly
legal to run curl_exec() on this handle. Removing a handle while being
used, will effectively halt all transfers in progress.
mhA cURL multi handle returned by curl_multi_init().
chA cURL handle returned by curl_init().
(PHP 5)
curl_multi_select -- Get all the sockets associated with the cURL extension, which can then be "selected"Get all the sockets associated with the cURL extension, which can then be "selected".
mhA cURL multi handle returned by curl_multi_init().
timeoutTime, in seconds, to wait for a response.
On success, returns the number of descriptors contained in, the descriptor sets. On failure, this function will return FALSE.
Sets multiple options for a cURL session. This function is useful for setting a large amount of cURL options without repetitively calling curl_setopt().
chA cURL handle returned by curl_init().
optionsAn array specifying which options to set and their values. The keys should be valid curl_setopt() constants or their integer equivalents.
Returns TRUE if all options were successfully set. If an option could
not be successfully set, FALSE is immediately returned, ignoring any
future options in the options array.
Example 1. Initializing a new cURL session and fetching a web page
|
Prior to PHP 5.1.4 this function can be simulated with:
Sets an option on the given cURL session handle.
chA cURL handle returned by curl_init().
optionThe CURLOPT_XXX option to set.
value
The value to be set on option.
value should be a bool for the
following values of the option parameter:
| Option | Set value to | Notes |
|---|---|---|
| CURLOPT_AUTOREFERER | TRUE to automatically set the Referer: field in requests where it follows a Location: redirect. | Available since PHP 5.1.0. |
| CURLOPT_BINARYTRANSFER | TRUE to return the raw output when CURLOPT_RETURNTRANSFER is used. | |
| CURLOPT_COOKIESESSION | TRUE to mark this as a new cookie "session". It will force libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session. By default, libcurl always stores and loads all cookies, independent if they are session cookies are not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only. | Available since PHP 5.1.0. |
| CURLOPT_CRLF | TRUE to convert Unix newlines to CRLF newlines on transfers. | |
| CURLOPT_DNS_USE_GLOBAL_CACHE | TRUE to use a global DNS cache. This option is not thread-safe and is enabled by default. | |
| CURLOPT_FAILONERROR | TRUE to fail silently if the HTTP code returned is greater than or equal to 400. The default behavior is to return the page normally, ignoring the code. | |
| CURLOPT_FILETIME |
TRUE to attempt to retrieve the modification
date of the remote document. This value can be retrieved using
the CURLINFO_FILETIME option with
curl_getinfo().
| |
| CURLOPT_FOLLOWLOCATION | TRUE to follow any "Location: " header that the server sends as part of the HTTP header (note this is recursive, PHP will follow as many "Location: " headers that it is sent, unless CURLOPT_MAXREDIRS is set). | |
| CURLOPT_FORBID_REUSE | TRUE to force the connection to explicitly close when it has finished processing, and not be pooled for reuse. | |
| CURLOPT_FRESH_CONNECT | TRUE to force the use of a new connection instead of a cached one. | |
| CURLOPT_FTP_USE_EPRT | TRUE to use EPRT (and LPRT) when doing active FTP downloads. Use FALSE to disable EPRT and LPRT and use PORT only. | Added in PHP 5.0.0. |
| CURLOPT_FTP_USE_EPSV | TRUE to first try an EPSV command for FTP transfers before reverting back to PASV. Set to FALSE to disable EPSV. | |
| CURLOPT_FTPAPPEND | TRUE to append to the remote file instead of overwriting it. | |
| CURLOPT_FTPASCII | An alias of CURLOPT_TRANSFERTEXT. Use that instead. | |
| CURLOPT_FTPLISTONLY | TRUE to only list the names of an FTP directory. | |
| CURLOPT_HEADER | TRUE to include the header in the output. | |
| CURLOPT_HTTPGET | TRUE to reset the HTTP request method to GET. Since GET is the default, this is only necessary if the request method has been changed. | |
| CURLOPT_HTTPPROXYTUNNEL | TRUE to tunnel through a given HTTP proxy. | |
| CURLOPT_MUTE | TRUE to be completely silent with regards to the cURL functions. | |
| CURLOPT_NETRC | TRUE to scan the ~/.netrc file to find a username and password for the remote site that a connection is being established with. | |
| CURLOPT_NOBODY | TRUE to exclude the body from the output. | |
| CURLOPT_NOPROGRESS |
TRUE to disable the progress meter for cURL transfers.
| |
| CURLOPT_NOSIGNAL | TRUE to ignore any cURL function that causes a signal to be sent to the PHP process. This is turned on by default in multi-threaded SAPIs so timeout options can still be used. | Added in cURL 7.10 and PHP 5.0.0. |
| CURLOPT_POST | TRUE to do a regular HTTP POST. This POST is the normal application/x-www-form-urlencoded kind, most commonly used by HTML forms. | |
| CURLOPT_PUT | TRUE to HTTP PUT a file. The file to PUT must be set with CURLOPT_INFILE and CURLOPT_INFILESIZE. | |
| CURLOPT_RETURNTRANSFER | TRUE to return the transfer as a string of the return value of curl_exec() instead of outputting it out directly. | |
| CURLOPT_SSL_VERIFYPEER | FALSE to stop cURL from verifying the peer's certificate. Alternate certificates to verify against can be specified with the CURLOPT_CAINFO option or a certificate directory can be specified with the CURLOPT_CAPATH option. CURLOPT_SSL_VERIFYHOST may also need to be TRUE or FALSE if CURLOPT_SSL_VERIFYPEER is disabled (it defaults to 2). | TRUE by default as of cURL 7.10. Default bundle installed as of cURL 7.10. |
| CURLOPT_TRANSFERTEXT | TRUE to use ASCII mode for FTP transfers. For LDAP, it retrieves data in plain text instead of HTML. On Windows systems, it will not set STDOUT to binary mode. | |
| CURLOPT_UNRESTRICTED_AUTH | TRUE to keep sending the username and password when following locations (using CURLOPT_FOLLOWLOCATION), even when the hostname has changed. | Added in PHP 5.0.0. |
| CURLOPT_UPLOAD | TRUE to prepare for an upload. | |
| CURLOPT_VERBOSE | TRUE to output verbose information. Writes output to STDERR, or the file specified using CURLOPT_STDERR. |
value should be an integer for the
following values of the option parameter:
| Option | Set value to | Notes |
|---|---|---|
| CURLOPT_BUFFERSIZE | The size of the buffer to use for each read. There is no guarantee this request will be fulfilled, however. | Added in cURL 7.10 and PHP 5.0.0. |
| CURLOPT_CLOSEPOLICY |
Either
CURLCLOSEPOLICY_LEAST_RECENTLY_USED or
CURLCLOSEPOLICY_OLDEST.
There are three other CURLCLOSEPOLICY_
constants, but cURL does not support them yet.
| |
| CURLOPT_CONNECTTIMEOUT | The number of seconds to wait whilst trying to connect. Use 0 to wait indefinitely. | |
| CURLOPT_DNS_CACHE_TIMEOUT | The number of seconds to keep DNS entries in memory. This option is set to 120 (2 minutes) by default. | |
| CURLOPT_FTPSSLAUTH | The FTP authentication method (when is activated): CURLFTPAUTH_SSL (try SSL first), CURLFTPAUTH_TLS (try TLS first), or CURLFTPAUTH_DEFAULT (let cURL decide). | Added in cURL 7.12.2 and PHP 5.1.0. |
| CURLOPT_HTTP_VERSION |
CURL_HTTP_VERSION_NONE (default, lets CURL
decide which version to use),
CURL_HTTP_VERSION_1_0 (forces HTTP/1.0),
or CURL_HTTP_VERSION_1_1 (forces HTTP/1.1).
| |
| CURLOPT_HTTPAUTH |
The HTTP authentication method(s) to use. The options are:
The bitwise | (or) operator can be used to combine more than one method. If this is done, cURL will poll the server to see what methods it supports and pick the best one.
| Added in PHP 5.0.0. |
| CURLOPT_INFILESIZE | The expected size, in bytes, of the file when uploading a file to a remote site. | |
| CURLOPT_LOW_SPEED_LIMIT | The transfer speed, in bytes per second, that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for PHP to consider the transfer too slow and abort. | |
| CURLOPT_LOW_SPEED_TIME | The number of seconds the transfer should be below CURLOPT_LOW_SPEED_LIMIT for PHP to consider the transfer too slow and abort. | |
| CURLOPT_MAXCONNECTS | The maximum amount of persistent connections that are allowed. When the limit is reached, CURLOPT_CLOSEPOLICY is used to determine which connection to close. | |
| CURLOPT_MAXREDIRS | The maximum amount of HTTP redirections to follow. Use this option alongside CURLOPT_FOLLOWLOCATION. | |
| CURLOPT_PORT | An alternative port number to connect to. | |
| CURLOPT_PROXYAUTH |
The HTTP authentication method(s) to use for the proxy connection.
Use the same bitmasks as described in
CURLOPT_HTTPAUTH. For proxy authentication,
only CURLAUTH_BASIC and
CURLAUTH_NTLM are currently supported.
| Added in cURL 7.10.7 and PHP 5.1.0. |
| CURLOPT_PROXYPORT | The port number of the proxy to connect to. This port number can also be set in CURLOPT_PROXY. | Added in PHP 5.0.0. |
| CURLOPT_PROXYTYPE |
Either CURLPROXY_HTTP (default) or
CURLPROXY_SOCKS5.
| Added in cURL 7.10 and PHP 5.0.0. |
| CURLOPT_RESUME_FROM | The offset, in bytes, to resume a transfer from. | |
| CURLOPT_SSL_VERIFYHOST | 1 to check the existence of a common name in the SSL peer certificate. 2 to check the existence of a common name and also verify that it matches the hostname provided. | |
| CURLOPT_SSLVERSION | The SSL version (2 or 3) to use. By default PHP will try to determine this itself, although in some cases this must be set manually. | |
| CURLOPT_TIMECONDITION |
How CURLOPT_TIMEVALUE is treated.
Use CURL_TIMECOND_IFMODSINCE to return the
page only if it has been modified since the time specified in
CURLOPT_TIMEVALUE. If it hasn't been modified,
a "304 Not Modified" header will be returned
assuming CURLOPT_HEADER is TRUE.
Use CURL_TIMECOND_ISUNMODSINCE for the reverse
effect. CURL_TIMECOND_IFMODSINCE is the
default.
| Added in PHP 5.1.0. |
| CURLOPT_TIMEOUT | The maximum number of seconds to allow cURL functions to execute. | |
| CURLOPT_TIMEVALUE |
The time in seconds since January 1st, 1970. The time will be used
by CURLOPT_TIMECONDITION. By default,
CURL_TIMECOND_IFMODSINCE is used.
|
value should be a string for the
following values of the option parameter:
| Option | Set value to | Notes |
|---|---|---|
| CURLOPT_CAINFO | The name of a file holding one or more certificates to verify the peer with. This only makes sense when used in combination with CURLOPT_SSL_VERIFYPEER. | |
| CURLOPT_CAPATH | A directory that holds multiple CA certificates. Use this option alongside CURLOPT_SSL_VERIFYPEER. | |
| CURLOPT_COOKIE | The contents of the "Set-Cookie: " header to be used in the HTTP request. | |
| CURLOPT_COOKIEFILE | The name of the file containing the cookie data. The cookie file can be in Netscape format, or just plain HTTP-style headers dumped into a file. | |
| CURLOPT_COOKIEJAR | The name of a file to save all internal cookies to when the connection closes. | |
| CURLOPT_CUSTOMREQUEST |
A custom request method to use instead of
"GET" or "HEAD" when doing
a HTTP request. This is useful for doing
"DELETE" or other, more obscure HTTP requests.
Valid values are things like "GET",
"POST", "CONNECT" and so on;
i.e. Do not enter a whole HTTP request line here. For instance,
entering "GET /index.html HTTP/1.0\r\n\r\n"
would be incorrect.
| |
| CURLOPT_EGBSOCKET | Like CURLOPT_RANDOM_FILE, except a filename to an Entropy Gathering Daemon socket. | |
| CURLOPT_ENCODING | The contents of the "Accept-Encoding: " header. This enables decoding of the response. Supported encodings are "identity", "deflate", and "gzip". If an empty string, "", is set, a header containing all supported encoding types is sent. | Added in cURL 7.10. |
| CURLOPT_FTPPORT | The value which will be used to get the IP address to use for the FTP "POST" instruction. The "POST" instruction tells the remote server to connect to our specified IP address. The string may be a plain IP address, a hostname, a network interface name (under Unix), or just a plain '-' to use the systems default IP address. | |
| CURLOPT_INTERFACE | The name of the outgoing network interface to use. This can be an interface name, an IP address or a host name. | |
| CURLOPT_KRB4LEVEL | The KRB4 (Kerberos 4) security level. Any of the following values (in order from least to most powerful) are valid: "clear", "safe", "confidential", "private".. If the string does not match one of these, "private" is used. Setting this option to NULL will disable KRB4 security. Currently KRB4 security only works with FTP transactions. | |
| CURLOPT_POSTFIELDS | The full data to post in a HTTP "POST" operation. | |
| CURLOPT_PROXY | The HTTP proxy to tunnel requests through. | |
| CURLOPT_PROXYUSERPWD | A username and password formatted as "[username]:[password]" to use for the connection to the proxy. | |
| CURLOPT_RANDOM_FILE | A filename to be used to seed the random number generator for SSL. | |
| CURLOPT_RANGE | Range(s) of data to retrieve in the format "X-Y" where X or Y are optional. HTTP transfers also support several intervals, separated with commas in the format "X-Y,N-M". | |
| CURLOPT_REFERER | The contents of the "Referer: " header to be used in a HTTP request. | |
| CURLOPT_SSL_CIPHER_LIST | A list of ciphers to use for SSL. For example, RC4-SHA and TLSv1 are valid cipher lists. | |
| CURLOPT_SSLCERT | The name of a file containing a PEM formatted certificate. | |
| CURLOPT_SSLCERTPASSWD | The password required to use the CURLOPT_SSLCERT certificate. | |
| CURLOPT_SSLCERTTYPE | The format of the certificate. Supported formats are "PEM" (default), "DER", and "ENG". | Added in cURL 7.9.3 and PHP 5.0.0. |
| CURLOPT_SSLENGINE | The identifier for the crypto engine of the private SSL key specified in CURLOPT_SSLKEY. | |
| CURLOPT_SSLENGINE_DEFAULT | The identifier for the crypto engine used for asymmetric crypto operations. | |
| CURLOPT_SSLKEY | The name of a file containing a private SSL key. | |
| CURLOPT_SSLKEYPASSWD |
The secret password needed to use the private SSL key specified in
CURLOPT_SSLKEY.
| |
| CURLOPT_SSLKEYTYPE | The key type of the private SSL key specified in CURLOPT_SSLKEY. Supported key types are "PEM" (default), "DER", and "ENG". | |
| CURLOPT_URL | The URL to fetch. This can also be set when initializing a session with curl_init(). | |
| CURLOPT_USERAGENT | The contents of the "User-Agent: " header to be used in a HTTP request. | |
| CURLOPT_USERPWD | A username and password formatted as "[username]:[password]" to use for the connection. |
value should be an array for the
following values of the option parameter:
| Option | Set value to | Notes |
|---|---|---|
| CURLOPT_HTTP200ALIASES | An array of HTTP 200 responses that will be treated as valid responses and not as errors. | Added in cURL 7.10.3 and PHP 5.0.0. |
| CURLOPT_HTTPHEADER | An array of HTTP header fields to set. | |
| CURLOPT_POSTQUOTE | An array of FTP commands to execute on the server after the FTP request has been performed. | |
| CURLOPT_QUOTE | An array of FTP commands to execute on the server prior to the FTP request. |
value should be a stream resource (using
fopen(), for example) for the following values of the
option parameter:
| Option | Set value to | Notes |
|---|---|---|
| CURLOPT_FILE | The file that the transfer should be written to. The default is STDOUT (the browser window). | |
| CURLOPT_INFILE | The file that the transfer should be read from when uploading. | |
| CURLOPT_STDERR | An alternative location to output errors to instead of STDERR. | |
| CURLOPT_WRITEHEADER | The file that the header part of the transfer is written to. |
value should be a string that is the name of a valid
callback function for the following values of the
option parameter:
| Option | Set value to | Notes |
|---|---|---|
| CURLOPT_HEADERFUNCTION | The name of a callback function where the callback function takes two parameters. The first is the cURL resource, the second is a string with the header data to be written. The header data must be written when using this callback function. Return the number of bytes written. | |
| CURLOPT_PASSWDFUNCTION | The name of a callback function where the callback function takes three parameters. The first is the cURL resource, the second is a string containing a password prompt, and the third is the maximum password length. Return the string containing the password. | |
| CURLOPT_READFUNCTION | The name of a callback function where the callback function takes two parameters. The first is the cURL resource, and the second is a string with the data to be read. The data must be read by using this callback function. Return the number of bytes read. Return 0 to signal EOF. | |
| CURLOPT_WRITEFUNCTION | The name of a callback function where the callback function takes two parameters. The first is the cURL resource, and the second is a string with the data to be written. The data must be written by using this callback function. Must return the exact number of bytes written or this will fail. |
Example 1. Initializing a new cURL session and fetching a web page
|
Returns an associative array with the following elements:
| version_number | cURL 24 bit version number |
| version | cURL version number, as a string |
| ssl_version_number | OpenSSL 24 bit version number |
| ssl_version | OpenSSL version number, as a string |
| libz_version | zlib version number, as a string |
| host | Information about the host where cURL was built |
| age | |
| features | A bitmask of the CURL_VERSION_XXX constants |
| protocols | An array of protocols names supported by cURL |
These functions are only available if the interpreter has been
compiled with the --with-cybercash=[DIR].
This extension has been moved from PHP as of PHP 4.3.0 and now CyberCash lives in PECL.
If you have questions as to the latest status of CyberCash then the following CyberCash Faq will be helpful. In short, CyberCash was bought out by VeriSign and although the CyberCash service continues to exist, VeriSign encourages users to switch. See the above faq and PECL link for details.
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
The function returns an associative array with the elements "errcode" and, if "errcode" is FALSE, "outbuff" (string), "outLth" (long) and "macbuff" (string).
wmkThe merchant key.
skThe session key.
inbuffURL encoded string of value pairs, i.e. order-id=12345&amount=USD+12.34&card_number=......
This extension allows you to process credit cards transactions using Credit Mutuel CyberMUT system.
CyberMUT is a popular Web Payment Service in France, provided by the Credit Mutuel bank. If you are foreign in France, these functions will not be useful for you.
The use of these functions is almost identical to the original functions, except for the parameters of return for CreerFormulaireCM and CreerReponseCM, which are returned directly by functions PHP, whereas they had passed in reference in the original functions.
Note: This extension is not available on Windows platforms.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 4.3.0
You will require the appropriate SDK for your platform, which may be sent to you after your CyberMUT's subscription (contact them via Web, or go to the nearest Credit Mutuel).
Note: These functions only provide a link to CyberMUT SDK. Be sure to read the CyberMUT Developers Guide for full details of the required parameters.
cybermut_creerformulairecm() is used to generate the HTML form of request for payment.
(4.0.5 - 4.2.3 only, PECL)
cybermut_creerreponsecm -- Generate the delivery's acknowledgement of the payment's confirmationThe parameter is "OK" if the message of confirmation of the payment were correctly authenticated by cybermut_testmac(). Any other chain is regarded as an error message.
(4.0.5 - 4.2.3 only, PECL)
cybermut_testmac -- Make sure that there was no data diddling contained in the received message of confirmation
cybermut_testmac() is used to make sure that there was
no data diddling contained in the received message of confirmation.
Pay attention to parameters code_return and
text_free, which cannot be evaluated as is,
because of the dash.
| Warning |
This function is currently not documented; only the argument list is available. |
Note: This extension is not available on Windows platforms.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.0.0.
To enable Cyrus IMAP support and to use these functions you have to compile
PHP with the --with-cyrus option.
This extension defines a Cyrus IMAP connection identifier returned by cyrus_connect().
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
These functions allow you to get the date and time from the server where your PHP scripts are running. You can use these functions to format the date and time in many different ways.
Note: Please keep in mind that these functions are dependent on the locale settings of your server. Make sure to take daylight saving time (use e.g. $date = strtotime('+7 days', $date) and not $date += 7*24*60*60) and leap years into consideration when working with these functions.
Note: The timezones referenced in this section can be found in the Appendix J.
There is no installation needed to use these functions; they are part of the PHP core.
Note: The latest version of the timezone database can be installed via PECL's timezonedb. For Windows users, a pre-compiled DLL can be downloaded from the PECL4Win site: php_timezonedb.dll.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Date/Time Configuration Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| date.default_latitude | "31.7667" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.default_longitude | "35.2333" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.sunrise_zenith | "90.83" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.sunset_zenith | "90.83" | PHP_INI_ALL | Available since PHP 5.0.0. |
| date.timezone | "" | PHP_INI_ALL | Available since PHP 5.1.0. |
Here's a short explanation of the configuration directives.
date.default_latitude
floatThe default latitude.
date.default_longitude
floatThe default longitude.
date.sunrise_zenith
floatThe default sunrise zenith.
date.sunset_zenith
floatThe default sunset zenith.
date.timezone
string
The default timezone used by all date/time functions if the
TZ environment variable isn't set. The precedence
order is described in the date_default_timezone_get()
page. See Appendix J for a list of supported timezones.
Note: The first four configuration options are currently only used by date_sunrise() and date_sunset().
The following constants are defined since PHP 5.1.1 and they offer standard date representations, which can be used along with the date format functions (like date()).
Atom (example: 2005-08-15T15:52:01+00:00)
HTTP Cookies (example: Monday, 15-Aug-05 15:52:01 UTC)
ISO-8601 (example: 2005-08-15T15:52:01+0000)
RFC 822 (example: Mon, 15 Aug 05 15:52:01 +0000)
RFC 850 (example: Monday, 15-Aug-05 15:52:01 UTC)
RFC 1036 (example: Mon, 15 Aug 05 15:52:01 +0000)
RFC 1123 (example: Mon, 15 Aug 2005 15:52:01 +0000)
RFC 2822 (Mon, 15 Aug 2005 15:52:01 +0000)
Same as DATE_ATOM (since PHP 5.1.3)
RSS (Mon, 15 Aug 2005 15:52:01 +0000)
World Wide Web Consortium (example: 2005-08-15T15:52:01+00:00)
Following constants exists since PHP 5.1.2 and specify a format returned by functions date_sunrise() and date_sunset().
Checks the validity of the date formed by the arguments. A date is considered valid if each parameter is properly defined.
monthThe month is between 1 and 12 inclusive.
day
The day is within the allowed number of days for the given
month. Leap years
are taken into consideration.
yearThe year is between 1 and 32767 inclusive.
timeString in a format accepted by strtotime(), defaults to "now".
timezoneTime zone of the time.
objectDateTime object.
yearYear of the date.
monthMonth of the date.
dayDay of the date.
(PHP 5 >= 5.1.0RC1)
date_default_timezone_get -- Gets the default timezone used by all date/time functions in a scriptThis functions returns the default timezone, using the following "guess" order:
The timezone set using the date_default_timezone_set() function (if any)
The TZ environment variable (if non empty)
The date.timezone ini option (if set)
"magical" guess (if the operating system supports it)
If none of the above options succeeds, return UTC
(PHP 5 >= 5.1.0RC1)
date_default_timezone_set -- Sets the default timezone used by all date/time functions in a scriptdate_default_timezone_set() sets the default timezone used by all date/time functions.
Note: Since PHP 5.1.0 (when the date/time functions were rewritten), every call to a date/time function will generate a E_NOTICE if the timezone isn't valid, and/or a E_STRICT message if using the system settings or the
TZenvironment variable.
Instead of using this function to set the default timezone in your script, you can also use the INI setting date.timezone to set the default timezone.
timezone_identifierThe timezone identifier, like UTC or Europe/Lisbon. The list of valid identifiers is available in the Appendix J.
This function returns FALSE if the
timezone_identifier isn't valid, or TRUE
otherwise.
objectDateTime object.
yearYear of the date.
monthMonth of the date.
dayDay of the date.
(no version information, might be only in CVS)
date_parse -- Returns associative array with detailed info about given date
Example 1. A date_parse() example
The above example will output:
|
(no version information, might be only in CVS)
date_sun_info -- Returns an array with information about sunset/sunrise and twilight begin/end
Example 1. A date_sun_info() example
The above example will output:
|
date_sunrise() returns the sunrise time for a given
day (specified as a timestamp) and location.
timestamp
The timestamp of the day from which the sunrise
time is taken.
format
latitudeDefaults to North, pass in a negative value for South. See also: date.default_latitude
longitudeDefaults to East, pass in a negative value for West. See also: date.default_longitude
zenithDefault: date.sunrise_zenith
gmtoffsetSpecified in hours.
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
Example 1. date_sunrise() example
The above example will output something similar to:
|
date_sunset() returns the sunset time for a given
day (specified as a timestamp) and location.
timestamp
The timestamp of the day from which the sunset
time is taken.
format
latitudeDefaults to North, pass in a negative value for South. See also: date.default_latitude
longitudeDefaults to East, pass in a negative value for West. See also: date.default_longitude
zenithDefault: date.sunrise_zenith
gmtoffsetSpecified in hours.
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
Example 1. date_sunset() example
The above example will output something similar to:
|
objectDateTime object.
hourHour of the time.
minuteMinute of the time.
secondSecond of the time.
Returns a string formatted according to the given format string using the
given integer timestamp or the current time
if no timestamp is given. In other words, timestamp
is optional and defaults to the value of time().
formatThe format of the outputted date string. See the formatting options below.
Table 1. The following characters are recognized in the
format parameter string
format character | Description | Example returned values |
|---|---|---|
| Day | --- | --- |
| d | Day of the month, 2 digits with leading zeros | 01 to 31 |
| D | A textual representation of a day, three letters | Mon through Sun |
| j | Day of the month without leading zeros | 1 to 31 |
| l (lowercase 'L') | A full textual representation of the day of the week | Sunday through Saturday |
| N | ISO-8601 numeric representation of the day of the week (added in PHP 5.1.0) | 1 (for Monday) through 7 (for Sunday) |
| S | English ordinal suffix for the day of the month, 2 characters | st, nd, rd or th. Works well with j |
| w | Numeric representation of the day of the week | 0 (for Sunday) through 6 (for Saturday) |
| z | The day of the year (starting from 0) | 0 through 365 |
| Week | --- | --- |
| W | ISO-8601 week number of year, weeks starting on Monday (added in PHP 4.1.0) | Example: 42 (the 42nd week in the year) |
| Month | --- | --- |
| F | A full textual representation of a month, such as January or March | January through December |
| m | Numeric representation of a month, with leading zeros | 01 through 12 |
| M | A short textual representation of a month, three letters | Jan through Dec |
| n | Numeric representation of a month, without leading zeros | 1 through 12 |
| t | Number of days in the given month | 28 through 31 |
| Year | --- | --- |
| L | Whether it's a leap year | 1 if it is a leap year, 0 otherwise. |
| o | ISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. (added in PHP 5.1.0) | Examples: 1999 or 2003 |
| Y | A full numeric representation of a year, 4 digits | Examples: 1999 or 2003 |
| y | A two digit representation of a year | Examples: 99 or 03 |
| Time | --- | --- |
| a | Lowercase Ante meridiem and Post meridiem | am or pm |
| A | Uppercase Ante meridiem and Post meridiem | AM or PM |
| B | Swatch Internet time | 000 through 999 |
| g | 12-hour format of an hour without leading zeros | 1 through 12 |
| G | 24-hour format of an hour without leading zeros | 0 through 23 |
| h | 12-hour format of an hour with leading zeros | 01 through 12 |
| H | 24-hour format of an hour with leading zeros | 00 through 23 |
| i | Minutes with leading zeros | 00 to 59 |
| s | Seconds, with leading zeros | 00 through 59 |
| u | Milliseconds (added in PHP 5.2.2) | Example: 54321 |
| Timezone | --- | --- |
| e | Timezone identifier (added in PHP 5.1.0) | Examples: UTC, GMT, Atlantic/Azores |
| I (capital i) | Whether or not the date is in daylight saving time | 1 if Daylight Saving Time, 0 otherwise. |
| O | Difference to Greenwich time (GMT) in hours | Example: +0200 |
| P | Difference to Greenwich time (GMT) with colon between hours and minutes (added in PHP 5.1.3) | Example: +02:00 |
| T | Timezone abbreviation | Examples: EST, MDT ... |
| Z | Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. | -43200 through 50400 |
| Full Date/Time | --- | --- |
| c | ISO 8601 date (added in PHP 5) | 2004-02-12T15:19:21+00:00 |
| r | RFC 2822 formatted date | Example: Thu, 21 Dec 2000 16:01:07 +0200 |
| U | Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) | See also time() |
Unrecognized characters in the format string will be printed as-is. The Z format will always return 0 when using gmdate().
timestamp
The optional timestamp parameter is an
integer Unix timestamp that defaults to the current
local time if a timestamp is not given. In other
words, it defaults to the value of time().
Returns a formatted date string. If a non-numeric value is used for
timestamp, FALSE is returned and an
E_WARNING level error is emitted.
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
| Version | Description |
|---|---|
| 5.1.0 | The valid range of a timestamp is typically from Fri, 13 Dec 1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are the dates that correspond to the minimum and maximum values for a 32-bit signed integer). However, before PHP 5.1.0 this range was limited from 01-01-1970 to 19-01-2038 on some systems (e.g. Windows). |
| 5.1.0 | Now issues the E_STRICT and E_NOTICE time zone errors. |
| 5.1.1 |
There are useful constants
of standard date/time formats that can be used to specify the
format parameter.
|
Example 1. date() examples
|
You can prevent a recognized character in the format string from being expanded by escaping it with a preceding backslash. If the character with a backslash is already a special sequence, you may need to also escape the backslash.
It is possible to use date() and mktime() together to find dates in the future or the past.
Example 3. date() and mktime() example
|
Note: This can be more reliable than simply adding or subtracting the number of seconds in a day or month to a timestamp because of daylight saving time.
Some examples of date() formatting. Note that you should escape any other characters, as any which currently have a special meaning will produce undesirable results, and other characters may be assigned meaning in future PHP versions. When escaping, be sure to use single quotes to prevent characters like \n from becoming newlines.
Example 4. date() Formatting
|
To format dates in other languages, you should use the setlocale() and strftime() functions instead of date().
Note: To generate a timestamp from a string representation of the date, you may be able to use strtotime(). Additionally, some databases have functions to convert their date formats into timestamps (such as MySQL's UNIX_TIMESTAMP function).
Tip: Timestamp of the start of the request is available in
$_SERVER['REQUEST_TIME']since PHP 5.1.
Returns an associative array containing the date
information of the timestamp, or the current
local time if no timestamp is given.
Returns an associative array of information related to
the typestamp. Elements from the returned
associative array are as follows:
Table 1. Key elements of the returned associative array
| Key | Description | Example returned values |
|---|---|---|
| "seconds" | Numeric representation of seconds | 0 to 59 |
| "minutes" | Numeric representation of minutes | 0 to 59 |
| "hours" | Numeric representation of hours | 0 to 23 |
| "mday" | Numeric representation of the day of the month | 1 to 31 |
| "wday" | Numeric representation of the day of the week | 0 (for Sunday) through 6 (for Saturday) |
| "mon" | Numeric representation of a month | 1 through 12 |
| "year" | A full numeric representation of a year, 4 digits | Examples: 1999 or 2003 |
| "yday" | Numeric representation of the day of the year | 0 through 365 |
| "weekday" | A full textual representation of the day of the week | Sunday through Saturday |
| "month" | A full textual representation of a month, such as January or March | January through December |
| 0 | Seconds since the Unix Epoch, similar to the values returned by time() and used by date(). | System Dependent, typically -2147483648 through 2147483647. |
This is an interface to gettimeofday(2). It returns an associative array containing the data returned from the system call.
By default an array is returned. If return_float
is set, then a float is returned.
Array keys:
"sec" - seconds since the Unix Epoch
"usec" - microseconds
"minuteswest" - minutes west of Greenwich
"dsttime" - type of dst correction
Identical to the date() function except that the time returned is Greenwich Mean Time (GMT).
Returns a formatted date string. If a non-numeric value is used for
timestamp, FALSE is returned and an
E_WARNING level error is emitted.
| Version | Description |
|---|---|
| 5.1.0 | The valid range of a timestamp is typically from Fri, 13 Dec 1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are the dates that correspond to the minimum and maximum values for a 32-bit signed integer). However, before PHP 5.1.0 this range was limited from 01-01-1970 to 19-01-2038 on some systems (e.g. Windows). |
| 5.1.1 |
There are useful constants
of standard date/time formats that can be used to specify the
format parameter.
|
Identical to mktime() except the passed parameters represents a GMT date. gmmktime() internally uses mktime() so only times valid in derived local time can be used.
Like mktime(), arguments may be left out in order from right to left, with any omitted arguments being set to the current corresponding GMT value.
hourThe hour
minuteThe minute
secondThe second
monthThe month
dayThe day
yearThe year
is_dst
Parameters always represent a GMT date so is_dst
doesn't influence the result.
(PHP 3 >= 3.0.12, PHP 4, PHP 5)
gmstrftime -- Format a GMT/UTC time/date according to locale settingsBehaves the same as strftime() except that the time returned is Greenwich Mean Time (GMT). For example, when run in Eastern Standard Time (GMT -0500), the first line below prints "Dec 31 1998 20:00:00", while the second prints "Jan 01 1999 01:00:00".
Returns a number formatted according to the given format string using the
given integer timestamp or the current local time
if no timestamp is given. In other words, timestamp
is optional and defaults to the value of time().
Unlike the function date(), idate()
accepts just one char in the format parameter.
format
Table 1. The following characters are recognized in the
format parameter string
format character | Description |
|---|---|
| B | Swatch Beat/Internet Time |
| d | Day of the month |
| h | Hour (12 hour format) |
| H | Hour (24 hour format) |
| i | Minutes |
| I | returns 1 if DST is activated, 0 otherwise |
| L | returns 1 for leap year, 0 otherwise |
| m | Month number |
| s | Seconds |
| t | Days in current month |
| U | Seconds since the Unix Epoch - January 1 1970 00:00:00 GMT - this is the same as time() |
| w | Day of the week (0 on Sunday) |
| W | ISO-8601 week number of year, weeks starting on Monday |
| y | Year (1 or 2 digits - check note below) |
| Y | Year (4 digits) |
| z | Day of the year |
| Z | Timezone offset in seconds |
timestamp
The optional timestamp parameter is an
integer Unix timestamp that defaults to the current
local time if a timestamp is not given. In other
words, it defaults to the value of time().
Returns an integer.
As idate() always returns an integer and as they can't start with a "0", idate() may return fewer digits than you would expect. See the example below.
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
The localtime() function returns an array identical to that of the structure returned by the C function call.
timestamp
The optional timestamp parameter is an
integer Unix timestamp that defaults to the current
local time if a timestamp is not given. In other
words, it defaults to the value of time().
is_associativeIf set to FALSE or not supplied than the array is returned as a regular, numerically indexed array. If the argument is set to TRUE then localtime() is an associative array containing all the different elements of the structure returned by the C function call to localtime. The names of the different keys of the associative array are as follows:
"tm_sec" - seconds
"tm_min" - minutes
"tm_hour" - hour
"tm_mday" - day of the month
Months are from 0 (Jan) to 11 (Dec) and days of the week are from 0 (Sun) to 6 (Sat).
"tm_mon" - month of the year, starting with 0 for January
"tm_year" - Years since 1900
"tm_wday" - Day of the week
"tm_yday" - Day of the year
"tm_isdst" - Is daylight savings time in effect
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
Example 1. localtime() example
The above example will output something similar to:
|
microtime() returns the current Unix timestamp with microseconds. This function is only available on operating systems that support the gettimeofday() system call.
get_as_floatWhen called without the optional argument, this function returns the string "msec sec" where sec is the current time measured in the number of seconds since the Unix Epoch (0:00:00 January 1, 1970 GMT), and msec is the microseconds part. Both portions of the string are returned in units of seconds.
If the optional get_as_float is set to
TRUE then a float (in seconds) is returned.
Example 1. Timing script execution with microtime()
|
Returns the Unix timestamp corresponding to the arguments given. This timestamp is a long integer containing the number of seconds between the Unix Epoch (January 1 1970 00:00:00 GMT) and the time specified.
Arguments may be left out in order from right to left; any arguments thus omitted will be set to the current value according to the local date and time.
hourThe number of the hour.
minuteThe number of the minute.
secondThe number of seconds past the minute.
monthThe number of the month.
dayThe number of the day.
year
The number of the year, may be a two or four digit value,
with values between 0-69 mapping to 2000-2069 and 70-100 to
1970-2000. On systems where time_t is a 32bit signed integer, as
most common today, the valid range for year
is somewhere between 1901 and 2038, although this limitation is
overcome as of PHP 5.1.0.
is_dst
This parameter can be set to 1 if the time is during daylight savings time (DST),
0 if it is not, or -1 (the default) if it is unknown whether the time is within
daylight savings time or not. If it's unknown, PHP tries to figure it out itself.
This can cause unexpected (but not incorrect) results.
Some times are invalid if DST is enabled on the system PHP is running on or
is_dst is set to 1. If DST is enabled in e.g. 2:00, all times
between 2:00 and 3:00 are invalid and mktime() returns an undefined
(usually negative) value.
Some systems (e.g. Solaris 8) enable DST at midnight so time 0:30 of the day when DST
is enabled is evaluated as 23:30 of the previous day.
Note: As of PHP 5.1.0, this parameter became deprecated. As a result, the new timezone handling features should be used instead.
mktime() returns the Unix timestamp of the arguments given. If the arguments are invalid, the function returns FALSE (before PHP 5.1 it returned -1).
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
Example 1. mktime() example mktime() is useful for doing date arithmetic and validation, as it will automatically calculate the correct value for out-of-range input. For example, each of the following lines produces the string "Jan-01-1998".
|
Example 2. Last day of next month The last day of any given month can be expressed as the "0" day of the next month, not the -1 day. Both of the following examples will produce the string "The last day in Feb 2000 is: 29".
|
| Caution |
Before PHP 5.1.0, negative timestamps were not supported under any known version of Windows and some other systems as well. Therefore the range of valid years was limited to 1970 through 2038. |
Returns a string formatted according to the given format string
using the given timestamp or the current
local time if no timestamp is given. Month and weekday names and
other language dependent strings respect the current locale set
with setlocale().
Not all conversion specifiers may be supported by your C library, in which case they will not be supported by PHP's strftime(). Additionally, not all platforms support negative timestamps, therefore your date range may be limited to no earlier than the Unix epoch. This means that e.g. %e, %T, %R and %D (there might be more) and dates prior to Jan 1, 1970 will not work on Windows, some Linux distributions, and a few other operating systems. For Windows systems a complete overview of supported conversion specifiers can be found at this MSDN website.
formatThe following conversion specifiers are recognized in the format string:
%a - abbreviated weekday name according to the current locale
%A - full weekday name according to the current locale
%b - abbreviated month name according to the current locale
%B - full month name according to the current locale
%c - preferred date and time representation for the current locale
%C - century number (the year divided by 100 and truncated to an integer, range 00 to 99)
%d - day of the month as a decimal number (range 01 to 31)
%D - same as %m/%d/%y
%e - day of the month as a decimal number, a single digit is preceded by a space (range ' 1' to '31')
%g - like %G, but without the century.
%G - The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.
%h - same as %b
%H - hour as a decimal number using a 24-hour clock (range 00 to 23)
%I - hour as a decimal number using a 12-hour clock (range 01 to 12)
%j - day of the year as a decimal number (range 001 to 366)
%m - month as a decimal number (range 01 to 12)
%M - minute as a decimal number
%n - newline character
%p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale
%r - time in a.m. and p.m. notation
%R - time in 24 hour notation
%S - second as a decimal number
%t - tab character
%T - current time, equal to %H:%M:%S
%u - weekday as a decimal number [1,7], with 1 representing Monday
| Warning |
Sun Solaris seems to start with Sunday as 1 although ISO 9889:1999 (the current C standard) clearly specifies that it should be Monday. |
%U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week
%V - The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. (Use %G or %g for the year component that corresponds to the week number for the specified timestamp.)
%W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week
%w - day of the week as a decimal, Sunday being 0
%x - preferred date representation for the current locale without the time
%X - preferred time representation for the current locale without the date
%y - year as a decimal number without a century (range 00 to 99)
%Y - year as a decimal number including the century
%Z or %z - time zone or name or abbreviation
%% - a literal `%' character
timestamp
The optional timestamp parameter is an
integer Unix timestamp that defaults to the current
local time if a timestamp is not given. In other
words, it defaults to the value of time().
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
This example works if you have the respective locales installed in your system.
Example 2. ISO 8601:1988 week number example
|
Note: %G and %V, which are based on ISO 8601:1988 week numbers can give unexpected (albeit correct) results if the numbering system is not thoroughly understood. See %V examples in this manual page.
strptime() returns an array with the
date parsed, or FALSE on error.
Month and weekday names and other language dependent strings respect the current locale set with setlocale() (LC_TIME).
Note: This function is not implemented on Windows platforms.
date (string)The string to parse (e.g. returned from strftime())
format (string)
The format used in date (e.g. the same as
used in strftime()).
For more information about the format options, read the strftime() page.
Returns an array, or FALSE on failure.
Table 1. The following parameters are returned in the array
| parameters | Description |
|---|---|
| tm_sec | Seconds after the minute (0-61) |
| tm_min | Minutes after the hour (0-59) |
| tm_hour | Hour since midnight (0-23) |
| tm_mday | Day of the month (1-31) |
| tm_mon | Months since January (0-11) |
| tm_year | Years since 1900 |
| tm_wday | Days since Sunday (0-6) |
| tm_yday | Days since January 1 (0-365) |
| unparsed | the date part which was not
recognized using the specified format |
Example 1. strptime() example
The above example will output something similar to:
|
(PHP 3 >= 3.0.12, PHP 4, PHP 5)
strtotime -- Parse about any English textual datetime description into a Unix timestamp
The function expects to be given a string containing a US English date
format and will try to parse that format into a Unix timestamp (the
number of seconds since January 1 1970 00:00:00 GMT), relative
to the timestamp given in now, or the current time
if none is supplied.
This function will use the TZ environment variable (if
available) to calculate the timestamp. Since PHP 5.1.0 there are easier
ways to define the timezone that is used across all date/time functions.
That process is explained in the
date_default_timezone_get() function page.
Note: If the number of the year is specified in a two digit format, the values between 00-69 are mapped to 2000-2069 and 70-99 to 1970-1999.
timeThe string to parse, according to the GNU Date Input Formats syntax. Before PHP 5.0.0, microseconds weren't allowed in the time, since PHP 5.0.0 they are allowed but ignored.
nowThe timestamp used to calculate the returned value.
Returns a timestamp on success, FALSE otherwise. Previous to PHP 5.1.0, this function would return -1 on failure.
Every call to a date/time function will generate a E_NOTICE
if the time zone is not valid, and/or a E_STRICT message
if using the system settings or the TZ environment
variable. See also date_default_timezone_set()
Example 1. A strtotime() example
|
| Warning |
In PHP 5 up to 5.0.2, "now" and other relative times are wrongly computed from today's midnight. It differs from other versions where it is correctly computed from current time. |
| Warning |
In PHP versions prior to 4.4.0, "next" is incorrectly computed as +2. A typical solution to this is to use "+1". |
Note: The valid range of a timestamp is typically from Fri, 13 Dec 1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are the dates that correspond to the minimum and maximum values for a 32-bit signed integer.) Additionally, not all platforms support negative timestamps, therefore your date range may be limited to no earlier than the Unix epoch. This means that e.g. dates prior to Jan 1, 1970 will not work on Windows, some Linux distributions, and a few other operating systems. PHP 5.1.0 and newer versions overcome this limitation though.
Returns the current time measured in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT).
Example 1. time() example
The above example will output something similar to:
|
Tip: Timestamp of the start of the request is available in
$_SERVER['REQUEST_TIME']since PHP 5.1.
(PHP 5 >= 5.1.0RC1)
timezone_abbreviations_list -- Returns associative array containing dst, offset and the timezone name
Example 1. A timezone_abbreviations_list() example
The above example will output something similar to:
|
(PHP 5 >= 5.1.0RC1)
timezone_identifiers_list -- Returns numerically index array with all timezone identifiers
Example 1. A timezone_identifiers_list() example
The above example will output something similar to:
|
(no version information, might be only in CVS)
timezone_name_from_abbr -- Returns the timezone name from abbrevation
abbrTime zone abbreviation.
gmtOffset
Offset from GMT in seconds. Defaults to -1 which means that first found
time zone corresponding to abbr is returned.
Otherwise exact offset is searched and only if not found then the first
time zone with any offset is returned.
isdst
Daylight saving time indicator. If abbr doesn't
exist then the time zone is searched solely by
offset and isdst.
This function returns the offset to GMT for the date/time specified in the
datetime parameter. The GMT offset is calculated
with the timezone information contained in the DateTime object being used.
objectDateTimeZone object.
datetimeDateTime that contains the date/time to compute the offset from.
Example 1. timezone_offset_get() examples
|
timezoneTime zone identifier as full name (e.g. Europe/Prague) or abbreviation (e.g. CET).
(no version information, might be only in CVS)
timezone_transitions_get -- Returns all transitions for the timezoneReturns numerically indexed array containing associative array with all transitions on success or FALSE on failure.
| Warning |
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. |
db++, made by the German company Concept asa, is a relational database system with high performance and low memory and disk usage in mind. While providing SQL as an additional language interface, it is not really a SQL database in the first place but provides its own AQL query language which is much more influenced by the relational algebra than SQL is.
Concept asa always had an interest in supporting open source languages, db++ has had Perl and Tcl call interfaces for years now and uses Tcl as its internal stored procedure language.
This extension relies on external client libraries so you have to have a db++ client installed on the system you want to use this extension on.
Concept asa provides db++ Demo versions and documentation for Linux, some other Unix versions. There is also a Windows version of db++, but this extension doesn't support it (yet).
In order to build this extension yourself you need the db++ client libraries
and header files to be installed on your system (these are included in the
db++ installation archives by default). You have to run
configure with option --with-dbplus to
build this extension.
configure looks for the client libraries and header files
under the default paths /usr/dbplus,
/usr/local/dbplus and /opt/dblus.
If you have installed db++ in a different place you have add the installation
path to the configure option like this:
--with-dbplus=/your/installation/path.
Most db++ functions operate on or return
dbplus_relation resources. A
dbplus_relation is a handle to a stored
relation or a relation generated as the result of a query.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Table 1. DB++ Error Codes
| PHP Constant | db++ constant | meaning |
|---|---|---|
| DBPLUS_ERR_NOERR (integer) | ERR_NOERR | Null error condition |
| DBPLUS_ERR_DUPLICATE (integer) | ERR_DUPLICATE | Tried to insert a duplicate tuple |
| DBPLUS_ERR_EOSCAN (integer) | ERR_EOSCAN | End of scan from rget() |
| DBPLUS_ERR_EMPTY (integer) | ERR_EMPTY | Relation is empty (server) |
| DBPLUS_ERR_CLOSE (integer) | ERR_CLOSE | The server can't close |
| DBPLUS_ERR_WLOCKED (integer) | ERR_WLOCKED | The record is write locked |
| DBPLUS_ERR_LOCKED (integer) | ERR_LOCKED | Relation was already locked |
| DBPLUS_ERR_NOLOCK (integer) | ERR_NOLOCK | Relation cannot be locked |
| DBPLUS_ERR_READ (integer) | ERR_READ | Read error on relation |
| DBPLUS_ERR_WRITE (integer) | ERR_WRITE | Write error on relation |
| DBPLUS_ERR_CREATE (integer) | ERR_CREATE | Create() system call failed |
| DBPLUS_ERR_LSEEK (integer) | ERR_LSEEK | Lseek() system call failed |
| DBPLUS_ERR_LENGTH (integer) | ERR_LENGTH | Tuple exceeds maximum length |
| DBPLUS_ERR_OPEN (integer) | ERR_OPEN | Open() system call failed |
| DBPLUS_ERR_WOPEN (integer) | ERR_WOPEN | Relation already opened for writing |
| DBPLUS_ERR_MAGIC (integer) | ERR_MAGIC | File is not a relation |
| DBPLUS_ERR_VERSION (integer) | ERR_VERSION | File is a very old relation |
| DBPLUS_ERR_PGSIZE (integer) | ERR_PGSIZE | Relation uses a different page size |
| DBPLUS_ERR_CRC (integer) | ERR_CRC | Invalid crc in the superpage |
| DBPLUS_ERR_PIPE (integer) | ERR_PIPE | Piped relation requires lseek() |
| DBPLUS_ERR_NIDX (integer) | ERR_NIDX | Too many secondary indices |
| DBPLUS_ERR_MALLOC (integer) | ERR_MALLOC | Malloc() call failed |
| DBPLUS_ERR_NUSERS (integer) | ERR_NUSERS | Error use of max users |
| DBPLUS_ERR_PREEXIT (integer) | ERR_PREEXIT | Caused by invalid usage |
| DBPLUS_ERR_ONTRAP (integer) | ERR_ONTRAP | Caused by a signal |
| DBPLUS_ERR_PREPROC (integer) | ERR_PREPROC | Error in the preprocessor |
| DBPLUS_ERR_DBPARSE (integer) | ERR_DBPARSE | Error in the parser |
| DBPLUS_ERR_DBRUNERR (integer) | ERR_DBRUNERR | Run error in db |
| DBPLUS_ERR_DBPREEXIT (integer) | ERR_DBPREEXIT | Exit condition caused by prexit() * procedure |
| DBPLUS_ERR_WAIT (integer) | ERR_WAIT | Wait a little (Simple only) |
| DBPLUS_ERR_CORRUPT_TUPLE (integer) | ERR_CORRUPT_TUPLE | A client sent a corrupt tuple |
| DBPLUS_ERR_WARNING0 (integer) | ERR_WARNING0 | The Simple routines encountered a non fatal error which was corrected |
| DBPLUS_ERR_PANIC (integer) | ERR_PANIC | The server should not really die but after a disaster send ERR_PANIC to all its clients |
| DBPLUS_ERR_FIFO (integer) | ERR_FIFO | Can't create a fifo |
| DBPLUS_ERR_PERM (integer) | ERR_PERM | Permission denied |
| DBPLUS_ERR_TCL (integer) | ERR_TCL | TCL_error |
| DBPLUS_ERR_RESTRICTED (integer) | ERR_RESTRICTED | Only two users |
| DBPLUS_ERR_USER (integer) | ERR_USER | An error in the use of the library by an application programmer |
| DBPLUS_ERR_UNKNOWN (integer) | ERR_UNKNOWN |
relation
tuple
An array of attribute/value pairs to be inserted into the given
relation.
After successful execution this array will contain the complete data of the newly created tuple, including all implicitly set domain fields like sequences.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Executes an AQL query on the given
server and dbpath.
queryThe AQL query to be executed. Further information on the AQL A... Query Language is provided in the original db++ manual.
server
dbpath
Returns a relation handle on success. The result data may be fetched from this relation by calling dbplus_next() and dbplus_current(). Other relation access functions will not work on a result relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Changes the virtual current directory where relation files will be looked for by dbplus_open().
newdirThe new directory for relation files. You can omit this parameter to query the current working directory.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Closes a relation previously opened by dbplus_open().
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads the data for the current tuple for the given
relation.
relationA relation opened by dbplus_open().
tupleThe data will be passed back in this parameter, as an associative array.
The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Returns a clear error string for the given error code.
errnoThe error code. If not provided, the result code of the last db++ operation is assumed.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Places a constraint on the given relation.
Further calls to functions like dbplus_curr() or dbplus_next() will only return tuples matching the given constraints.
relationA relation opened by dbplus_open().
constraints
Constraints are triplets of strings containing of a domain name,
a comparison operator and a comparison value. The
constraints parameter array may consist of
a collection of string arrays, each of which contains a domain, an
operator and a value, or of a single string array containing a
multiple of three elements.
The comparison operator may be one of the following strings: '==', '>', '>=', '<', '<=', '!=', '~' for a regular expression match and 'BAND' or 'BOR' for bitwise operations.
tuple
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads the data for the first tuple for the given
relation, makes it the current tuple and pass it
back as an associative array in tuple.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Writes all changes applied to relation since the
last flush to disk.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Releases a write lock on the given tuple previously
obtained by dbplus_getlock().
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Frees all tuple locks held on the given relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Requests a write lock on the specified tuple.
Returns zero on success or a non-zero error code, especially DBPLUS_ERR_WLOCKED on failure.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Obtains a number guaranteed to be unique for the given
relation and will pass it back in the variable
given as uniqueid.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads the data for the last tuple for the given
relation, makes it the current tuple and pass it
back as an associative array in tuple.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Requests a write lock on the given relation.
Other clients may still query the relation, but can't alter it while it is locked.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads the data for the next tuple for the given
relation, makes it the current tuple and will pass
it back as an associative array in tuple.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
nameCan be either a file name or a relative or absolute path name. This will be mapped in any case to an absolute relation file path on a specific host machine and server.
On success a relation file resource (cursor) is returned which must be used in any subsequent commands referencing the relation. Failure leads to a zero return value, the actual error code may be asked for by calling dbplus_errno().
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Reads the data for the previous tuple for the given
relation, makes it the current tuple and will pass
it back as an associative array in tuple.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Changes access permissions as specified by mask,
user and group. The
values for these are operating system specific.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Creates a new relation. Any existing relation sharing the same
name will be overwritten if the relation is
currently not in use and overwrite is set to TRUE.
name
domlistA combination of domains. May be passed as a single domain name string or as an array of domain names.
This parameter should contain the domain specification for the new relation within an array of domain description strings. A domain description string consists of a domain name unique to this relation, a slash and a type specification character. See the db++ documentation, especially the dbcreate(1) manpage, for a description of available type specifiers and their meanings.
Note: This function will also accept a string with space delimited domain description strings, but it is recommended to use an array
overwrite
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
(4.1.0 - 4.2.3 only, PECL)
dbplus_rcrtexact -- Creates an exact but empty copy of a relation including indices
dbplus_rcrtexact() will create an exact but
empty copy of the given relation under a
new name.
name
relationThe copied relation, opened by dbplus_open().
overwrite
An existing relation by the same name will only
be overwritten if this parameter is set to TRUE and no other process
is currently using the relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
(4.1.0 - 4.2.3 only, PECL)
dbplus_rcrtlike -- Creates an empty copy of a relation with default indices
dbplus_rcrtexact() will create an empty copy
of the given relation under a new
name, but with default indices.
name
relationThe copied relation, opened by dbplus_open().
overwrite
An existing relation by the same name will only
be overwritten if this parameter is set to TRUE and no other process
is currently using the relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_resolve() will try to resolve the given
relation_name and find out internal server
id, real hostname and the database path on this host.
Returns an array containing these values under the keys sid, host and host_path or FALSE on error.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_rkeys() will replace the current
primary key for relation with the
combination of domains specified by domlist.
relationA relation opened by dbplus_open().
domlistA combination of domains. May be passed as a single domain name string or as an array of domain names.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_ropen() will open the relation
file locally for quick access without any
client/server overhead. Access is read only and only
dbplus_current() and
dbplus_next() may be applied to the returned
relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_rquery() performs a local (raw) AQL query using an AQL interpreter embedded into the db++ client library. dbplus_rquery() is faster than dbplus_aql() but will work on local data only.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_rrename() will change the name of
relation to name.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_rsecindex() will create a new secondary
index for relation with consists of the
domains specified by domlist and is of
type type
relationA relation opened by dbplus_open().
domlistA combination of domains. May be passed as a single domain name string or as an array of domain names.
type
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_unlink() will close and remove the
relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_rzap() will remove all tuples from
relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
A db++ server will prepare a TCL interpreter for each client connection. This interpreter will enable the server to execute TCL code provided by the client as a sort of stored procedures to improve the performance of database operations by avoiding client/server data transfers and context switches.
dbplus_tcl() needs to pass the client
connection id the TCL script code should
be executed by. dbplus_resolve() will provide
this connection id. The function will return whatever the TCL
code returns or a TCL error message if the TCL code fails.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_tremove() removes
tuple from relation
if it perfectly matches a tuple within the
relation. current, if given, will contain
the data of the new current tuple after calling
dbplus_tremove().
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Release a write lock previously obtained by dbplus_lockrel().
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Calling dbplus_unselect() will remove a
constraint previously set by dbplus_find() on
relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
dbplus_update() replaces the old
tuple with the data from the new one, only if the
old completely matches a tuple within
relation.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Request an exclusive lock on relation preventing
even read access from other clients.
| Warning |
This function is EXPERIMENTAL. The behaviour of this function, the name of this function, and anything else documented about this function may change without notice in a future release of PHP. Use this function at your own risk. |
Releases an exclusive lock previously obtained by dbplus_xlockrel().
These functions build the foundation for accessing Berkeley DB style databases.
This is a general abstraction layer for several file-based databases. As such, functionality is limited to a common subset of features supported by modern databases such as Sleepycat Software's DB2. (This is not to be confused with IBM's DB2 software, which is supported through the ODBC functions.)
The behaviour of various aspects depends on the implementation of the underlying database. Functions such as dba_optimize() and dba_sync() will do what they promise for one database and will do nothing for others. You have to download and install supported dba-Handlers.
Table 1. List of DBA handlers
| Handler | Notes |
|---|---|
| dbm | Dbm is the oldest (original) type of Berkeley DB style databases. You should avoid it, if possible. We do not support the compatibility functions built into DB2 and gdbm, because they are only compatible on the source code level, but cannot handle the original dbm format. |
| ndbm | Ndbm is a newer type and more flexible than dbm. It still has most of the arbitrary limits of dbm (therefore it is deprecated). |
| gdbm | Gdbm is the GNU database manager. |
| db2 | DB2 is Sleepycat Software's DB2. It is described as "a programmatic toolkit that provides high-performance built-in database support for both standalone and client/server applications. |
| db3 | DB3 is Sleepycat Software's DB3. |
| db4 | DB4 is Sleepycat Software's DB4. This is available since PHP 4.3.2. |
| cdb | Cdb is "a fast, reliable, lightweight package for creating and reading constant databases." It is from the author of qmail and can be found at http://cr.yp.to/cdb.html. Since it is constant, we support only reading operations. And since PHP 4.3.0 we support writing (not updating) through the internal cdb library. |
| cdb_make | Since PHP 4.3.0 we support creation (not updating) of cdb files when the bundled cdb library is used. |
| flatfile | This is available since PHP 4.3.0 for compatibility with the deprecated dbm extension only and should be avoided. However you may use this where files were created in this format. That happens when configure could not find any external library. |
| inifile | This is available since PHP 4.3.3 to be able to modify php.ini files from within PHP scripts. When working with ini files you can pass arrays of the form array(0=>group,1=>value_name) or strings of the form "[group]value_name" where group is optional. As the functions dba_firstkey() and dba_nextkey() return string representations of the key there is a new function dba_key_split() available since PHP 5 which allows to convert the string keys into array keys without loosing FALSE. |
| qdbm | This is available since PHP 5.0.0. The qdbm library can be loaded from http://qdbm.sourceforge.net. |
When invoking the dba_open() or dba_popen() functions, one of the handler names must be supplied as an argument. The actually available list of handlers is displayed by invoking phpinfo() or dba_handlers().
By using the --enable-dba=shared
configuration option you can build a dynamic loadable module to enable PHP
for basic support of dbm-style databases. You also have to add support
for at least one of the following handlers by specifying the
--with-XXXX configure switch to your PHP
configure line.
| Warning |
After configuring and compiling PHP you must execute the following test from commandline: php run-tests.php ext/dba. This shows whether your combination of handlers works. Most problematic are dbm and ndbm which conflict with many installations. The reason for this is that on several systems these libraries are part of more than one other library. The configuration test only prevents you from configuring malfunctioning single handlers but not combinations. |
Table 2. Supported DBA handlers
| Handler | Configure Switch |
|---|---|
| dbm |
To enable support for dbm add
--with-dbm[=DIR].
|
| ndbm |
To enable support for ndbm add
--with-ndbm[=DIR].
|
| gdbm |
To enable support for gdbm add
--with-gdbm[=DIR].
|
| db2 |
To enable support for db2 add
--with-db2[=DIR].
|
| db3 |
To enable support for db3 add
--with-db3[=DIR].
|
| db4 |
To enable support for db4 add
--with-db4[=DIR].
|
| cdb |
To enable support for cdb add
--with-cdb[=DIR].
|
| flatfile |
To enable support for flatfile add
--with-flatfile.
|
| inifile |
To enable support for inifile add
--with-inifile.
|
| qdbm |
To enable support for qdbm add
--with-qdbm[=DIR].
|
Note: Up to PHP 4.3.0 you are able to add both db2 and db3 handler but only one of them can be used internally. That means that you cannot have both file formats. Starting with PHP 5.0.0 there is a configuration check avoid such misconfigurations.
The functions dba_open() and dba_popen() return a handle to the specified database file to access which is used by all other dba-function calls.
DBA is binary safe and does not have any arbitrary limits. However, it inherits all limits set by the underlying database implementation.
All file-based databases must provide a way of setting the file mode of a new created database, if that is possible at all. The file mode is commonly passed as the fourth argument to dba_open() or dba_popen().
You can access all entries of a database in a linear way by using the dba_firstkey() and dba_nextkey() functions. You may not change the database while traversing it.
dba_close() closes the established database and frees all resources of the specified database handle.
dba_delete() deletes the specified entry from the database.
keyThe key of the entry which is deleted.
handleThe database handler, returned by dba_open() or dba_popen().
dba_exists() checks whether the specified
key exists in the database.
keyThe key the check is performed for.
handleThe database handler, returned by dba_open() or dba_popen().
dba_fetch() fetches the data specified by
key from the database specified with
handle.
keyThe key the data is specified by.
Note: When working with inifiles this function accepts arrays as keys where index 0 is the group and index 1 is the value name. See: dba_key_split().
skipThe number of key-value pairs to ignore when using cdb databases. This value is ignored for all other databases which do not support multiple keys with the same name.
handleThe database handler, returned by dba_open() or dba_popen().
dba_firstkey() returns the first key of the database and resets the internal key pointer. This permits a linear search through the whole database.
dba_handlers() list all the handlers supported by this extension.
Returns an array of database handlers. If full_info
is set to TRUE, the array will be associative with the handlers names as
keys, and their version information as value. Otherwise, the result will be
an indexed array of handlers names.
Note: When the internal cdb library is used you will see cdb and cdb_make.
Example 1. dba_handlers() Example
The above example will output something similar to:
|
dba_insert() inserts the entry described with
key and value into the
database.
keyThe key of the entry to be inserted. If this key already exist in the database, this function will fail. Use dba_replace() if you need to replace an existent key.
valueThe value to be inserted.
handleThe database handler, returned by dba_open() or dba_popen().
dba_key_split() splits a key (string representation) into an array representation.
Returns an array of the form array(0 => group, 1 =>
value_name). This function will return FALSE if
key is NULL or FALSE.
dba_nextkey() returns the next key of the database and advances the internal key pointer.
dba_open() establishes a database instance for
path with mode using
handler.
pathCommonly a regular path in your filesystem.
modeIt is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access.
Additionally you can set the database lock method with the next char. Use l to lock the database with a .lck file or d to lock the databasefile itself. It is important that all of your applications do this consistently.
If you want to test the access and do not want to wait for the lock you can add t as third character. When you are absolutely sure that you do not require database locking you can do so by using - instead of l or d. When none of d, l or - is used, dba will lock on the database file as it would with d.
Note: There can only be one writer for one database file. When you use dba on a web server and more than one request requires write operations they can only be done one after another. Also read during write is not allowed. The dba extension uses locks to prevent this. See the following table:
Table 1. DBA locking
already open mode= "rl"mode= "rlt"mode= "wl"mode= "wlt"mode= "rd"mode= "rdt"mode= "wd"mode= "wdt"not open ok ok ok ok ok ok ok ok mode= "rl"ok ok wait false illegal illegal illegal illegal mode= "wl"wait false wait false illegal illegal illegal illegal mode= "rd"illegal illegal illegal illegal ok ok wait false mode= "wd"illegal illegal illegal illegal wait false wait false
ok: the second call will be successfull. wait: the second call waits until dba_close() is called for the first. false: the second call returns false. illegal: you must not mix "l" and "d" modifiers for modeparameter.
handler
The name of the handler which
shall be used for accessing path. It is passed
all optional parameters given to dba_open() and
can act on behalf of them.
| Version | Description |
|---|---|
| 4.3.0 | It's possible to open database files over network connection. However in cases a socket connection will be used (as with http or ftp) the connection will be locked instead of the resource itself. This is important to know since in such cases locking is simply ignored on the resource and other solutions have to be found. |
| 4.3.0 |
Locking and the mode modifiers "l", "d", "-"
and "t" were added.
In previous PHP versions, you must use semaphores to guard against
simultaneous database access for any database handler with the exception
of GDBM. See System V semaphore support.
|
| before 4.3.5 | open mode 'c' is broken for several internal handlers and truncates the database instead of appending data to an existent database. Also dbm and ndbm fail on mode 'c' in typical configurations (this cannot be fixed). |
dba_popen() establishes a persistent database instance
for path with mode using
handler.
pathCommonly a regular path in your filesystem.
modeIt is r for read access, w for read/write access to an already existing database, c for read/write access and database creation if it doesn't currently exist, and n for create, truncate and read/write access.
handler
The name of the handler which
shall be used for accessing path. It is passed
all optional parameters given to dba_popen() and
can act on behalf of them.
dba_replace() replaces or inserts the entry described
with key and value into the
database specified by handle.
keyThe key of the entry to be replaced.
valueThe value to be replaced.
handleThe database handler, returned by dba_open() or dba_popen().
These functions allow you to access records stored in dBase-format (dbf) databases.
dBase files are simple sequential files of fixed length records. Records are appended to the end of the file and delete records are kept until you call dbase_pack().
The types of dBase fields available are:
Table 1. Available types of fields
| Field | dBase Type | Format | Additional information |
|---|---|---|---|
| M | Memo | n/a | This type is not supported by PHP, such field will be ignored |
| D | Date | YYYYMMDD | The field length is limited to 8 |
| N | Number | A number | You must declare a length and a precision (the number of digits after the decimal point) |
| C | String | A string | You must declare a length. When retrieving data, the string will be right-padded with spaces to fit the declared length. |
| L | Boolean | T or Y for TRUE, F or N for FALSE | Stored and returned as an integer (1 or 0) |
| F | Float | A float number | Support for this type of field was added in PHP 5.2.0 |
| Warning |
There is no support for indexes or memo fields. There is no support for locking, too. Two concurrent web server processes modifying the same dBase file will very likely ruin your database. We recommend that you do not use dBase files as your production database. Choose any real SQL server instead; MySQL or Postgres are common choices with PHP. dBase support is here to allow you to import and export data to and from your web database, because the file format is commonly understood by Windows spreadsheets and organizers. |
In order to enable the bundled dbase library and to use these functions,
you must compile PHP with the --enable-dbase
option.
Many examples in this reference require a dBase database. We will use /tmp/test.dbf that will be created in the example of dbase_create().
Adds the given data to the database.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
recordAn indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.
Note: If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
dbase_create() creates a dBase database with the given definition.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
Note: This function is affected by open_basedir.
filenameThe name of the database. It can be a relative or absolute path to the file where dBase will store your data.
fieldsAn array of arrays, each array describing the format of one field of the database. Each field consists of a name, a character indicating the field type, and optionally, a length, and a precision.
Note: The fieldnames are limited in length and must not exceed 10 chars.
Returns a database link identifier if the database is successfully created, or FALSE if an error occurred.
Example 1. Creating a dBase database file
|
Marks the given record to be deleted from the database.
Note: To actually remove the record from the database, you must also call dbase_pack().
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
record_numberAn integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).
Returns information on the column structure of the given database link identifier.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
An indexed array with an entry for each column in the database. The array index starts at 0.
Each array element contains an associative array of column information, as described here:
The name of the column
The human-readable name for the dbase type of the column (i.e. date, boolean, etc.)
The number of bytes this column can hold
The number of digits of decimal precision for the column
A suggested printf() format specifier for the column
The byte offset of the column from the start of the row
If the database header information cannot be read, FALSE is returned.
Example 1. Showing header information for a dBase database file
|
(PHP 3 >= 3.0.4, PHP 4, PHP 5)
dbase_get_record_with_names -- Gets a record from a database as an associative arrayGets a record from a dBase database as an associative array.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
record_numberThe index of the record.
An associative array with the record. This will also include a key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).
Each field is converted to the appropriate PHP type, except:
Dates are left as strings.
Integers that would have caused an overflow (> 32 bits) are returned as strings.
On error, dbase_get_record_with_names() will return FALSE.
Example 1. Listing all the registered members in the database
|
Gets a record from a database as an indexed array.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
record_numberThe index of the record.
An indexed array with the record. This array will also include an associative key named deleted which is set to 1 if the record has been marked for deletion (see dbase_delete_record()).
Each field is converted to the appropriate PHP type, except:
Dates are left as strings.
Integers that would have caused an overflow (> 32 bits) are returned as strings.
On error, dbase_get_record() will return FALSE.
Gets the number of fields (columns) in the specified database.
Note: Field numbers are between 0 and dbase_numfields($db)-1, while record numbers are between 1 and dbase_numrecords($db).
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
Gets the number of records (rows) in the specified database.
Note: Record numbers are between 1 and dbase_numrecords($db), while field numbers are between 0 and dbase_numfields($db)-1.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
dbase_open() opens a dBase database with the given access mode.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
Note: This function is affected by open_basedir.
filenameThe name of the database. It can be a relative or absolute path to the file where dBase will store your data.
modeAn integer which correspond to those for the open() system call (Typically 0 means read-only, 1 means write-only, and 2 means read and write).
Note: You can't open a dBase file in write-only mode as the function will fail to read the headers information and thus you can't use 1 as
mode.
Returns a database link identifier if the database is successfully opened, or FALSE if an error occurred.
Packs the specified database by permanently deleting all records marked for deletion using dbase_delete_record().
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
Replaces the given record in the database with the given data.
dbase_identifierThe database link identifier, returned by dbase_open() or dbase_create().
recordAn indexed array of data. The number of items must be equal to the number of fields in the database, otherwise dbase_add_record() will fail.
Note: If you're using dbase_get_record() return value for this parameter, remember to reset the key named deleted.
record_numberAn integer which spans from 1 to the number of records in the database (as returned by dbase_numrecords()).
Example 1. Updating a record in the database
|
These functions allow you to store records stored in a dbm-style database. This type of database (supported by the Berkeley DB, GDBM, and some system libraries, as well as a built-in flatfile library) stores key/value pairs (as opposed to the full-blown records supported by relational databases).
Note: DBM support is deprecated and you are encouraged to use the Database (dbm-style) abstraction layer functions instead.
Note: This extension has been removed from PHP and is no longer available as of PHP 5.0.0.
To use this functions you have to compile PHP with support for an underlying database. See the list of supported Databases.
In order to use these functions, you must compile PHP with dbm support
by using the --with-db option. In
addition you must ensure support
for an underlying database or you can use some system libraries.
The function dbmopen() returns an database identifier which is used by the other dbm-functions.
Deletes the value for key in the database.
Returns TRUE on success or FALSE on failure. Returns FALSE if the key didn't exist in the database.
Returns TRUE if there is a value associated with the
key.
Gets the value associated with the given key.
Returns the first key in the database. Note that no particular order is guaranteed since the database may be built using a hash-table, which doesn't guarantee any ordering.
Adds the value to the database with the specified key.
dbm_identifierThe DBM link identifier, returned by dbmopen().
keyThe added key
valueThe added key value
Returns -1 if the database was opened read-only, 0 if the insert was successful, and 1 if the specified key already exists. (To replace the value, use dbmreplace().)
Returns the next key after key.
By calling dbmfirstkey() followed by successive calls to dbmnextkey() it is possible to visit every key/value pair in the dbm database. For example:
Opens the specified DBM database in the given mode.
filenameThe full-path filename of the DBM file to be opened
flagsThe file open mode which is one of r, n, c or w, for read-only, new (implies read-write, and most likely will truncate an already-existing database of the same name), create (implies read-write, and will not truncate an already-existing database of the same name) and read-write respectively.
Returns an identifier to be passed to the other DBM functions on success, or FALSE on failure.
Note: If NDBM support is used, NDBM will actually create filename.dir and filename.pag files. GDBM only uses one file, as does the internal flat-file support, and Berkeley DB creates a filename.db file.
Note that PHP does its own file locking in addition to any file locking that may be done by the DBM library itself. PHP does not delete the .lck files it creates. It uses these files simply as fixed inodes on which to do the file locking. For more information on DBM files, see your Unix man pages, or obtain GNU's GDBM.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
Replaces the value for the specified key in the database.
This will also add the key to the database if it didn't already exist.
dbm_identifierThe DBM link identifier, returned by dbmopen().
keyThe replaced key
valueThe new value
The dbx module is a database abstraction layer (db 'X', where 'X' is a supported database). The dbx functions allow you to access all supported databases using a single calling convention. The dbx-functions themselves do not interface directly to the databases, but interface to the modules that are used to support these databases.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.1.0.
To be able to use a database with the dbx-module, the module must be either linked or loaded into PHP, and the database module must be supported by the dbx-module. Currently, the following databases are supported, but others will follow:
FrontBase (available from PHP 4.1.0).
Sybase-CT (available from PHP 4.2.0).
Oracle (oci8) (available from PHP 4.3.0).
SQLite (PHP 5).
Documentation for adding additional database support to dbx can be found at http://www.guidance.nl/php/dbx/doc/.
In order to have these functions available, you must compile PHP with
dbx support by using the --enable-dbx
option and all options for the databases that will be used, e.g. for
MySQL you must also specify
--with-mysql=[DIR].
To get other supported databases to work with the dbx-module refer to their
specific documentation.
The behaviour of these functions is affected by settings in php.ini.
Table 1. DBX Configuration Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| dbx.colnames_case | "unchanged" | PHP_INI_SYSTEM | Available since PHP 4.3.0. |
Here's a short explanation of the configuration directives.
dbx.colnames_case
stringColumns names can be returned "unchanged" or converted to "uppercase" or "lowercase". This directive can be overridden with a flag to dbx_query().
There are two resource types used in the dbx module. The first one is the link-object for a database connection, the second a result-object which holds the result of a query.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
dbx_compare() is a helper function for dbx_sort() to ease the make and use of the custom sorting function.
row_aFirst row
row_bSecond row
column_keyThe compared column
flags
The flags can be set to specify comparison
direction:
DBX_CMP_ASC - ascending order
DBX_CMP_DESC - descending order
DBX_CMP_NATIVE - no type conversion
DBX_CMP_TEXT - compare items as strings
DBX_CMP_NUMBER - compare items numerically
flags parameter is
DBX_CMP_ASC | DBX_CMP_NATIVE.
Returns 0 if the row_a[$column_key]
is equal to row_b[$column_key], and 1
or -1 if the former is greater or is smaller than the
latter one, respectively, or vice versa if the flag
is set to DBX_CMP_DESC.
Example 1. dbx_compare() example
|
Opens a connection to a database.
module
The module parameter can be either a string or a
constant, though the latter form is preferred. The possible values are
given below, but keep in mind that they only work if the module is
actually loaded.
DBX_MYSQL or "mysql"
DBX_ODBC or "odbc"
DBX_PGSQL or "pgsql"
DBX_MSSQL or "mssql"
DBX_FBSQL or "fbsql" (available from PHP 4.1.0)
DBX_SYBASECT or "sybase_ct" (available from PHP 4.2.0)
DBX_OCI8 or "oci8" (available from PHP 4.3.0)
DBX_SQLITE or "sqlite" (PHP 5)
hostThe SQL server host
databaseThe database name
usernameThe username
passwordThe password
persistent
The persistent parameter can be set to
DBX_PERSISTENT, if so, a persistent connection
will be created.
The host, database,
username and password
parameters are expected, but not always used depending on the connect
functions for the abstracted module.
Returns an object on success, FALSE on error. If a connection has been made but the database could not be selected, the connection is closed and FALSE is returned.
The returned object has three properties:
It is the name of the currently selected database.
It is a valid handle for the connected database, and as such it can be used in module-specific functions (if required).
It is used internally by dbx only, and is actually the module number mentioned above.
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)
dbx_error -- Report the error message of the latest function call in the module
Returns a string containing the error message from the last function call
of the abstracted module (e.g. mysql module). If there are multiple
connections in the same module, just the last error is given. If there are
connections on different modules, the latest error is returned for the
module specified by the link_identifier parameter.
Note: Always refer to the module-specific documentation as well.
The error message for Microsoft SQL Server is actually the result of the mssql_get_last_message() function.
The error message for Oracle (oci8) is not implemented yet.
(PHP 4 >= 4.3.0, PHP 5 <= 5.0.4)
dbx_escape_string -- Escape a string so it can safely be used in an sql-statementEscape the given string so that it can safely be used in an sql-statement.
Returns the text, escaped where necessary (such as quotes, backslashes etc). On error, NULL is returned.
Example 1. dbx_escape_string() example
|
(PHP 5 <= 5.0.4)
dbx_fetch_row -- Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag setdbx_fetch_row() fetches rows from a result identifier that had the DBX_RESULT_UNBUFFERED flag set.
When the DBX_RESULT_UNBUFFERED is not set in the query, dbx_fetch_row() will fail as all rows have already been fetched into the results data property.
As a side effect, the rows property of the query-result object is incremented for each successful call to dbx_fetch_row().
Returns an object on success that contains the same information as any row would have in the dbx_query() result data property, including columns accessible by index or fieldname when the flags for dbx_query() were set that way.
Upon failure, returns 0 (e.g. when no more rows are available).
Example 1. How to handle the returned value
|
Sends a query and fetch all results.
link_identifierThe DBX link object returned by dbx_connect()
sql_statementSQL statement.
flagsThe compared column
flags
The flags parameter is used to control the amount of
information that is returned. It may be any combination of the following
constants with the bitwise OR operator (|). The DBX_COLNAMES_* flags
override the dbx.colnames_case setting from php.ini.
It is always set, that is, the returned object has a data property which is a 2 dimensional array indexed numerically. For example, in the expression data[2][3] 2 stands for the row (or record) number and 3 stands for the column (or field) number. The first row and column are indexed at 0.
If DBX_RESULT_ASSOC is also specified, the returning object contains the information related to DBX_RESULT_INFO too, even if it was not specified.
It provides info about columns, such as field names and field types.
It effects that the field values can be accessed with the respective column names used as keys to the returned object's data property.
Associated results are actually references to the numerically indexed data, so modifying data[0][0] causes that data[0]['field_name_for_first_column'] is modified as well.
This flag will not create the data property, and the rows property will initially be 0. Use this flag for large datasets, and use dbx_fetch_row() to retrieve the results row by row.
The dbx_fetch_row() function will return rows that are conformant to the flags set with this query. Incidentally, it will also update the rows each time it is called.
The case of the returned column names will not be changed.
The case of the returned column names will be changed to uppercase.
The case of the returned column names will be changed to lowercase.
flags parameter. This means
that only the following combinations are effective:
DBX_RESULT_INDEX
DBX_RESULT_INDEX | DBX_RESULT_INFO
DBX_RESULT_INDEX |
DBX_RESULT_INFO |
DBX_RESULT_ASSOC - this is the default, if
flags is not specified.
dbx_query() returns an object or 1
on success, and 0 on failure. The result object is
returned only if the query given in sql_statement
produces a result set (i.e. a SELECT query, even if the result set is
empty).
The returned object has four or five
properties depending on flags:
It is a valid handle for the connected database, and as such it can be used in module specific functions (if required).
These contain the number of columns (or fields) and rows (or records) respectively.
It is returned only if either DBX_RESULT_INFO or
DBX_RESULT_ASSOC is specified in the
flags parameter. It is a 2 dimensional array,
that has two named rows (name and
type) to retrieve column information.
This property contains the actual resulting data, possibly associated
with column names as well depending on flags.
If DBX_RESULT_ASSOC is set, it is possible to use
$result->data[2]["field_name"].
Example 2. outputs the content of data property into HTML table
|
Example 3. How to handle UNBUFFERED queries
|
Example 4. How to handle the returned value
|
Note: Always refer to the module-specific documentation as well.
Column names for queries on an Oracle database are returned in lowercase.
(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)
dbx_sort -- Sort a result from a dbx_query by a custom sort functionSort a result from a dbx_query() call with a custom sort function.
resultA result set returned by dbx_query().
user_compare_functionThe user-defined comparison function. It must accept two arguments and return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
Example 1. dbx_sort() example
|
PHP supports the direct io functions as described in the Posix Standard (Section 6) for performing I/O functions at a lower level than the C-Language stream I/O functions (fopen(), fread(),..). The use of the DIO functions should be considered only when direct control of a device is needed. In all other cases, the standard filesystem functions are more than adequate.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.1.0.
This extension is only available on Windows Platforms as of PHP 5.0.0
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
One resource type is defined by this extension: a file descriptor returned by dio_open().
The dio_fcntl() function performs the
operation specified by cmd on the file
descriptor fd. Some commands require
additional arguments args to be supplied.
Note: This function is not implemented on Windows platforms.
fdThe file descriptor returned by dio_open().
cmdCan be one of the following operations:
F_SETLK - Lock is set or cleared. If the lock is held by someone else dio_fcntl() returns -1.
F_SETLKW - like F_SETLK, but in case the lock is held by someone else, dio_fcntl() waits until the lock is released.
F_GETLK - dio_fcntl() returns an associative array (as described above) if someone else prevents lock. If there is no obstruction key "type" will set to F_UNLCK.
F_DUPFD - finds the lowest numbered available
file descriptor greater than or equal to args
and returns them.
F_SETFL - Sets the file descriptors flags to
the value specified by args, which can be
O_APPEND, O_NONBLOCK or
O_ASYNC. To use O_ASYNC
you will need to use the PCNTL
extension.
args
args is an associative array, when
cmd is F_SETLK or
F_SETLLW, with the following keys:
"start" - offset where lock begins
"length" - size of locked area. zero means to end of file
"wenth" - Where l_start is relative to: can be SEEK_SET, SEEK_END and SEEK_CUR
"type" - type of lock: can be F_RDLCK (read lock), F_WRLCK (write lock) or F_UNLCK (unlock)
Example 1. Setting and clearing a lock
|
(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)
dio_open -- Opens a new filename with specified permissions of flags and creation permissions of modedio_open() opens a file and returns a new file descriptor for it.
filenameThe opened file.
flags
The flags parameter can also include any
combination of the following flags:
O_CREAT - creates the file, if it doesn't already exist.
O_EXCL - if both, O_CREAT and O_EXCL are set, dio_open() fails, if the file already exists.
O_TRUNC - if the file exists, and its opened for write access, the file will be truncated to zero length.
O_APPEND - write operations write data at the end of the file.
O_NONBLOCK - sets non blocking mode.
mode
If flags is O_CREAT,
mode will set the mode of the file
(creation permissions).
O_RDONLY - opens the file for read access.
O_WRONLY - opens the file for write access.
O_RDWR - opens the file for both reading and writing.
The function dio_read() reads and returns
len bytes from file with descriptor
fd.
fdThe file descriptor returned by dio_open().
lenThe number of bytes to read. If not specified, dio_read() reads 1K sized block.
The function dio_seek() is used to change the file position of the given file descriptor.
fdThe file descriptor returned by dio_open().
posThe new position.
whence
Specifies how the position pos should be
interpreted:
SEEK_SET (default) - specifies that
pos is specified from the beginning of the
file.
SEEK_CUR - Specifies that
pos is a count of characters from the current
file position. This count may be positive or negative.
SEEK_END - Specifies that
pos is a count of characters from the end of
the file. A negative count specifies a position within the current
extent of the file; a positive count specifies a position past the
current end. If you set the position past the current end, and
actually write data, you will extend the file with zeros up to that
position.
Example 1. Positioning in a file
|
dio_stat() returns information about the given file descriptor.
Returns an associative array with the following keys:
"device" - device
"inode" - inode
"mode" - mode
"nlink" - number of hard links
"uid" - user id
"gid" - group id
"device_type" - device type (if inode device)
"size" - total size in bytes
"blocksize" - blocksize
"blocks" - number of blocks allocated
"atime" - time of last access
"mtime" - time of last modification
"ctime" - time of last change
(PHP 4 >= 4.3.0, PHP 5 <= 5.0.4)
dio_tcsetattr -- Sets terminal attributes and baud rate for a serial port
dio_tcsetattr() sets the terminal attributes and baud
rate of the open fd.
Note: This function is not implemented on Windows platforms.
fdThe file descriptor returned by dio_open().
optionsThe currently available options are:
'baud' - baud rate of the port - can be 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 or 50, default value is 9600.
'bits' - data bits - can be 8,7,6 or 5. Default value is 8.
'stop' - stop bits - can be 1 or 2. Default value is 1.
'parity' - can be 0,1 or 2. Default value is 0.
Example 1. Setting the baud rate on a serial port
|
dio_truncate() truncates a file to at most
offset bytes in size.
If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.
Note: This function is not implemented on Windows platforms.
dio_write() writes up to len
bytes from data to file fd.
fdThe file descriptor returned by dio_open().
dataThe written data.
lenThe length of data to write in bytes. If not specified, the function writes all the data to the specified file.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Note: The PATH_SEPARATOR was introduced with PHP 4.3.0-RC2.
Note: When safe mode is enabled, PHP checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed.
Changes the root directory of the current process to
directory.
This function is only available if your system supports it and you're using the CLI, CGI or Embed SAPI. Also, this function requires root privileges.
A pseudo-object oriented mechanism for reading a directory. The
given directory is opened. Two properties
are available once the directory has been opened. The handle
property can be used with other directory functions such as
readdir(), rewinddir() and
closedir(). The path property is set to path
the directory that was opened. Three methods are available:
read, rewind and close.
Example 1. dir() example Please note the fashion in which dir()'s return value is checked in the example below. We are explicitly testing whether the return value is identical to (equal to and of the same type as--see Comparison Operators for more information) FALSE since otherwise, any directory entry whose name evaluates to FALSE will stop the loop.
The above example will output something similar to:
|
Note: The order in which directory entries are returned by the read method is system-dependent.
Note: This defines the internal class Directory, meaning that you will not be able to define your own classes with that name. For a full list of predefined classes in PHP, please see Predefined Classes.
Closes the directory stream indicated by
dir_handle. The stream must have previously
been opened by opendir().
Returns the current working directory on success, or FALSE on failure.
On some Unix variants, getcwd() will return FALSE if any one of the parent directories does not have the readable or search mode set, even if the current directory does. See chmod() for more information on modes and permissions.
Opens up a directory handle to be used in subsequent closedir(), readdir(), and rewinddir() calls.
pathThe directory path that is to be opened
context
For a description of the context parameter,
refer to the streams section of
the manual.
Returns a directory handle resource on success, or FALSE on failure.
If path is not a valid directory or the
directory can not be opened due to permission restrictions or
filesystem errors, opendir() returns FALSE and
generates a PHP error of level
E_WARNING. You can suppress the error output of
opendir() by prepending
'@' to the
front of the function name.
Example 1. opendir() example
The above example will output something similar to:
|
Returns the filename of the next file from the directory. The filenames are returned in the order in which they are stored by the filesystem.
Returns the filename on success, or FALSE on failure.
| Warning |
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. |
Example 1. List all files in a directory Please note the fashion in which readdir()'s return value is checked in the examples below. We are explicitly testing whether the return value is identical to (equal to and of the same type as--see Comparison Operators for more information) FALSE since otherwise, any directory entry whose name evaluates to FALSE will stop the loop (e.g. a directory named "0").
|
Resets the directory stream indicated by
dir_handle to the beginning of the
directory.
Returns an array of files and directories from the
directory.
directoryThe directory that will be scanned.
sorting_order
By default, the sorted order is alphabetical in ascending order. If
the optional sorting_order is used (set to 1),
then the sort order is alphabetical in descending order.
context
For a description of the context parameter,
refer to the streams section of
the manual.
Returns an array of filenames on success, or FALSE on
failure. If directory is not a directory, then
boolean FALSE is returned, and an error of level
E_WARNING is generated.
Example 1. A simple scandir() example
The above example will output something similar to:
|
Example 2. PHP 4 alternatives to scandir()
The above example will output something similar to:
|
Tip: You can use a URL as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename and Appendix O for a list of supported URL protocols.
The DOM extension allows you to operate on XML documents through the DOM API with PHP 5.
For PHP 4, use DOM XML.
The API of the module follows the DOM Level 3 standard as closely as possible. Consequently, the API is fully object-oriented. It is a good idea to have the DOM standard available when using this module.
This module defines a number of classes, which are explained in the following tables. Classes with an equivalent in the DOM standard are named DOMxxx.
Extends DOMNode. The DOMAttr interface represents an attribute in an DOMElement object.
Extends DOMNode.
DOMCharacterData->appendData() - Append a string to the end of the character data of the node
DOMCharacterData->deleteData() - Remove a range of characters from the node
DOMCharacterData->insertData() - Insert a string at the specified 16-bit unit offset
DOMCharacterData->replaceData() - Replace a substring within the DOMCharacterData node
DOMCharacterData->substringData() - Extracts a range of data from the node
Extends DOMNode.
DOMDocument->createAttribute() - Create new attribute
DOMDocument->createAttributeNS() - Create new attribute node with an associated namespace
DOMDocument->createCDATASection() - Create new cdata node
DOMDocument->createComment() - Create new comment node
DOMDocument->createDocumentFragment() - Create new document fragment
DOMDocument->createElement() - Create new element node
DOMDocument->createElementNS() - Create new element node with an associated namespace
DOMDocument->createEntityReference() - Create new entity reference node
DOMDocument->createProcessingInstruction() - Creates new PI node
DOMDocument->createTextNode() - Create new text node
DOMDocument->getElementById() - Searches for an element with a certain id
DOMDocument->getElementsByTagName() - Searches for all elements with given tag name
DOMDocument->getElementsByTagNameNS() - Searches for all elements with given tag name in specified namespace
DOMDocument->importNode() - Import node into current document
DOMDocument->load() - Load XML from a file
DOMDocument->loadHTML() - Load HTML from a string
DOMDocument->loadHTMLFile() - Load HTML from a file
DOMDocument->loadXML() - Load XML from a string
DOMDocument->normalizeDocument() - Normalizes the document
DOMDocument->relaxNGValidate() - Performs relaxNG validation on the document
DOMDocument->relaxNGValidateSource() - Performs relaxNG validation on the document
DOMDocument->registerNodeClass() - Register extended class used to create base node type (not DOM standard)
DOMDocument->save() - Dumps the internal XML tree back into a file
DOMDocument->saveHTML() - Dumps the internal document into a string using HTML formatting
DOMDocument->saveHTMLFile() - Dumps the internal document back into a file using HTML formatting
DOMDocument->saveXML() - Dumps the internal XML tree back into a string
DOMDocument->schemaValidate() - Validates a document based on a schema
DOMDocument->schemaValidateSource() - Validates a document based on a schema
DOMDocument->validate() - Validates the document based on its DTD
DOMDocument->xinclude() - Substitutes XIncludes in a DOMDocument Object
Table 3.
| Name | Type | Read-only | Description |
|---|---|---|---|
| actualEncoding | string | yes | |
| config | DOMConfiguration | yes | |
| doctype | DOMDocumentType | yes | The Document Type Declaration associated with this document. |
| documentElement | DOMElement | yes | This is a convenience attribute that allows direct access to the child node that is the document element of the document. |
| documentURI | string | no | The location of the document or NULL if undefined. |
| encoding | string | no | |
| formatOutput | bool | no | |
| implementation | DOMImplementation | yes | The DOMImplementation object that handles this document. |
| preserveWhiteSpace | bool | no | Do not remove redundant white space. Default to TRUE. |
| recover | bool | no | |
| resolveExternals | bool | no | Set it to TRUE to load external entities from a doctype declaration. This is useful for including character entities in your XML document. |
| standalone | bool | no | |
| strictErrorChecking | bool | no | Throws DOMException on errors. Default to TRUE. |
| substituteEntities | bool | no | |
| validateOnParse | bool | no | Loads and validates against the DTD. Default to FALSE. |
| version | string | no | |
| xmlEncoding | string | yes | An attribute specifying, as part of the XML declaration, the encoding of this document. This is NULL when unspecified or when it is not known, such as when the Document was created in memory. |
| xmlStandalone | bool | no | An attribute specifying, as part of the XML declaration, whether this document is standalone. This is FALSE when unspecified. |
| xmlVersion | string | no | An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is "1.0". |
Extends DOMNode
Each DOMDocument has a doctype attribute whose value is either NULL or a DOMDocumentType object.
Table 4.
| Name | Type | Read-only | Description |
|---|---|---|---|
| publicId | string | yes | The public identifier of the external subset. |
| systemId | string | yes | The system identifier of the external subset. This may be an absolute URI or not. |
| name | string | yes | The name of DTD; i.e., the name immediately following the DOCTYPE keyword. |
| entities | DOMNamedNodeMap | yes | A DOMNamedNodeMap containing the general entities, both external and internal, declared in the DTD. |
| notations | DOMNamedNodeMap | yes | A DOMNamedNodeMap containing the notations declared in the DTD. |
| internalSubset | string | yes | The internal subset as a string, or null if there is none. This is does not contain the delimiting square brackets. |
Extends DOMNode.
DOMElement->getAttribute() - Returns value of attribute
DOMElement->getAttributeNode() - Returns attribute node
DOMElement->getAttributeNodeNS() - Returns attribute node
DOMElement->getAttributeNS() - Returns value of attribute
DOMElement->getElementsByTagName() - Gets elements by tagname
DOMElement->getElementsByTagNameNS() - Get elements by namespaceURI and localName
DOMElement->hasAttribute() - Checks to see if attribute exists
DOMElement->hasAttributeNS() - Checks to see if attribute exists
DOMElement->removeAttribute() - Removes attribute
DOMElement->removeAttributeNode() - Removes attribute
DOMElement->removeAttributeNS() - Removes attribute
DOMElement->setAttribute() - Adds new attribute
DOMElement->setAttributeNode() - Adds new attribute node to element
DOMElement->setAttributeNodeNS() - Adds new attribute node to element
DOMElement->setAttributeNS() - Adds new attribute
DOMElement->setIdAttribute() - Declares the ID attribute
DOMElement->setIdAttributeNode() - Declares the ID attribute
DOMElement->setIdAttributeNS() - Declares the ID attribute
Extends DOMNode
This interface represents a known entity, either parsed or unparsed, in an XML document.
Table 6.
| Name | Type | Read-only | Description |
|---|---|---|---|
| publicId | string | yes | The public identifier associated with the entity if specified, and NULL otherwise. |
| systemId | string | yes | The system identifier associated with the entity if specified, and NULL otherwise. This may be an absolute URI or not. |
| notationName | string | yes | For unparsed entities, the name of the notation for the entity. For parsed entities, this is NULL. |
| actualEncoding | string | no | An attribute specifying the encoding used for this entity at the time of parsing, when it is an external parsed entity. This is NULL if it an entity from the internal subset or if it is not known. |
| encoding | string | yes | An attribute specifying, as part of the text declaration, the encoding of this entity, when it is an external parsed entity. This is NULL otherwise. |
| version | string | yes | An attribute specifying, as part of the text declaration, the version number of this entity, when it is an external parsed entity. This is NULL otherwise. |
DOM operations raise exceptions under particular circumstances, i.e., when an operation is impossible to perform for logical reasons.
See also Chapter 20.
The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.
DOMImplementation->createDocument() - Creates a DOM Document object of the specified type with its document element
DOMImplementation->createDocumentType() - Creates an empty DOMDocumentType object
DOMImplementation->hasFeature() - Test if the DOM implementation implements a specific feature
DOMNamedNodeMap->getNamedItem() - Retrieves a node specified by name
DOMNamedNodeMap->getNamedItemNS() - Retrieves a node specified by local name and namespace URI
DOMNamedNodeMap->item() - Retrieves a node specified by index
DOMNode->appendChild() - Adds new child at the end of the children
DOMNode->cloneNode() - Clones a node
DOMNode->hasAttributes() - Checks if node has attributes
DOMNode->hasChildNodes() - Checks if node has children
DOMNode->insertBefore() - Adds a new child before a reference node
DOMNode->isDefaultNamespace() - Checks if the specified namespaceURI is the default namespace
DOMNode->isSameNode() - Indicates if two nodes are the same node
DOMNode->isSupported() - Checks if feature is supported for specified version
DOMNode->lookupNamespaceURI() - Returns namespace URI of the node based on the prefix
DOMNode->lookupPrefix() - Returns name space prefix of the node based on namespaceURI
DOMNode->normalize() - Normalizes the node
DOMNode->removeChild() - Removes child from list of children
DOMNode->replaceChild() - Replaces a child
Table 8.
| Name | Type | Read-only | Description |
|---|---|---|---|
| nodeName | string | yes | Returns the most accurate name for the current node type |
| nodeValue | string | no | The value of this node, depending on its type. |
| nodeType | int | yes | Gets the type of the node. One of the predefined XML_xxx_NODE constants |
| parentNode | DOMNode | yes | The parent of this node. |
| childNodes | DOMNodeList | yes | A DOMNodeList that contains all children of this node. If there are no children, this is an empty DOMNodeList. |
| firstChild | DOMNode | yes | The first child of this node. If there is no such node, this returns NULL. |
| lastChild | DOMNode | yes | The last child of this node. If there is no such node, this returns NULL. |
| previousSibling | DOMNode | yes | The node immediately preceding this node. If there is no such node, this returns NULL. |
| nextSibling | DOMNode | yes | The node immediately following this node. If there is no such node, this returns NULL. |
| attributes | DOMNamedNodeMap | yes | A DOMNamedNodeMap containing the attributes of this node (if it is a DOMElement) or NULL otherwise. |
| ownerDocument | DOMDocument | yes | The DOMDocument object associated with this node. |
| namespaceURI | string | yes | The namespace URI of this node, or NULL if it is unspecified. |
| prefix | string | no | The namespace prefix of this node, or NULL if it is unspecified. |
| localName | string | yes | Returns the local part of the qualified name of this node. |
| baseURI | string | yes | The absolute base URI of this node or NULL if the implementation wasn't able to obtain an absolute URI. |
| textContent | string | no | This attribute returns the text content of this node and its descendants. |
Extends DOMNode.
DOMProcessingInstruction->__construct() - construct a new DOMProcessingInstruction object
Extends DOMCharacterData.
DOMText->isWhitespaceInElementContent() - Indicates whether this text node contains whitespace
DOMText->splitText() - Breaks the node into two nodes at the specified offset
DOMXPath->registerNamespace() - Registers the namespace with the DOMXpath object
DOMXPath->evaluate() - Evaluates the given XPath expression and returns a typed result if possible
DOMXPath->query() - Evaluates the given XPath expression
Many examples in this reference require an XML file. We will use book.xml that contains the following:
Example 1. book.xml
|
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Table 14. XML constants
| Constant | Value | Description |
|---|---|---|
| XML_ELEMENT_NODE (integer) | 1 | Node is a DOMElement |
| XML_ATTRIBUTE_NODE (integer) | 2 | Node is a DOMAttr |
| XML_TEXT_NODE (integer) | 3 | Node is a DOMText |
| XML_CDATA_SECTION_NODE (integer) | 4 | Node is a DOMCharacterData |
| XML_ENTITY_REF_NODE (integer) | 5 | Node is a DOMEntityReference |
| XML_ENTITY_NODE (integer) | 6 | Node is a DOMEntity |
| XML_PI_NODE (integer) | 7 | Node is a DOMProcessingInstruction |
| XML_COMMENT_NODE (integer) | 8 | Node is a DOMComment |
| XML_DOCUMENT_NODE (integer) | 9 | Node is a DOMDocument |
| XML_DOCUMENT_TYPE_NODE (integer) | 10 | Node is a DOMDocumentType |
| XML_DOCUMENT_FRAG_NODE (integer) | 11 | Node is a DOMDocumentFragment |
| XML_NOTATION_NODE (integer) | 12 | Node is a DOMNotation |
| XML_HTML_DOCUMENT_NODE (integer) | 13 | |
| XML_DTD_NODE (integer) | 14 | |
| XML_ELEMENT_DECL_NODE (integer) | 15 | |
| XML_ATTRIBUTE_DECL_NODE (integer) | 16 | |
| XML_ENTITY_DECL_NODE (integer) | 17 | |
| XML_NAMESPACE_DECL_NODE (integer) | 18 | |
| XML_ATTRIBUTE_CDATA (integer) | 1 | |
| XML_ATTRIBUTE_ID (integer) | 2 | |
| XML_ATTRIBUTE_IDREF (integer) | 3 | |
| XML_ATTRIBUTE_IDREFS (integer) | 4 | |
| XML_ATTRIBUTE_ENTITY (integer) | 5 | |
| XML_ATTRIBUTE_NMTOKEN (integer) | 7 | |
| XML_ATTRIBUTE_NMTOKENS (integer) | 8 | |
| XML_ATTRIBUTE_ENUMERATION (integer) | 9 | |
| XML_ATTRIBUTE_NOTATION (integer) | 10 |
Table 15. DOMException constants
| Constant | Value | Description |
|---|---|---|
| DOM_INDEX_SIZE_ERR (integer) | 1 | If index or size is negative, or greater than the allowed value. |
| DOMSTRING_SIZE_ERR (integer) | 2 | If the specified range of text does not fit into a DOMString. |
| DOM_HIERARCHY_REQUEST_ERR (integer) | 3 | If any node is inserted somewhere it doesn't belong |
| DOM_WRONG_DOCUMENT_ERR (integer) | 4 | If a node is used in a different document than the one that created it. |
| DOM_INVALID_CHARACTER_ERR (integer) | 5 | If an invalid or illegal character is specified, such as in a name. |
| DOM_NO_DATA_ALLOWED_ERR (integer) | 6 | If data is specified for a node which does not support data. |
| DOM_NO_MODIFICATION_ALLOWED_ERR (integer) | 7 | If an attempt is made to modify an object where modifications are not allowed. |
| DOM_NOT_FOUND_ERR (integer) | 8 | If an attempt is made to reference a node in a context where it does not exist. |
| DOM_NOT_SUPPORTED_ERR (integer) | 9 | If the implementation does not support the requested type of object or operation. |
| DOM_INUSE_ATTRIBUTE_ERR (integer) | 10 | If an attempt is made to add an attribute that is already in use elsewhere. |
| DOM_INVALID_STATE_ERR (integer) | 11 | If an attempt is made to use an object that is not, or is no longer, usable. |
| DOM_SYNTAX_ERR (integer) | 12 | If an invalid or illegal string is specified. |
| DOM_INVALID_MODIFICATION_ERR (integer) | 13 | If an attempt is made to modify the type of the underlying object. |
| DOM_NAMESPACE_ERR (integer) | 14 | If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces. |
| DOM_INVALID_ACCESS_ERR (integer) | 15 | If a parameter or an operation is not supported by the underlying object. |
| DOM_VALIDATION_ERR (integer) | 16 | If a call to a method such as insertBefore or removeChild would make the Node invalid with respect to "partial validity", this exception would be raised and the operation would not be done. |
(no version information, might be only in CVS)
DOMAttr->__construct() -- Creates a new DOMAttr objectCreates a new DOMAttr object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createAttribute().
Example 1. Creating a new DOMAttr
|
(no version information, might be only in CVS)
DOMAttr->isId() -- Checks if attribute is a defined IDThis function checks if the attribute is a defined ID.
According to the DOM standard this requires a DTD which defines the attribute ID to be of type ID. You need to validate your document with DOMDocument->validate() or DOMDocument::validateOnParse before using this function.
Example 1. DOMAttr->isId() Example
|
(no version information, might be only in CVS)
DOMCharacterData->appendData() -- Append the string to the end of the character data of the node
Append the string data to the end of the character data of the node.
| DOMCharacterData->deleteData() |
| DOMCharacterData->insertData() |
| DOMCharacterData->replaceData() |
| DOMCharacterData->substringData() |
(no version information, might be only in CVS)
DOMCharacterData->deleteData() -- Remove a range of characters from the node
Deletes count characters starting from position
offset.
offsetThe offset from which to start removing.
count
The number of characters to delete. If the sum of
offset and count exceeds
the length, then all characters to the end of the data are deleted.
Raised if offset is negative or greater than the
number of 16-bit units in data, or if count is
negative.
| DOMCharacterData->appendData() |
| DOMCharacterData->insertData() |
| DOMCharacterData->replaceData() |
| DOMCharacterData->substringData() |
(no version information, might be only in CVS)
DOMCharacterData->insertData() -- Insert a string at the specified 16-bit unit offset
Inserts string data at position offset.
Raised if offset is negative or greater than the
number of 16-bit units in data.
| DOMCharacterData->appendData() |
| DOMCharacterData->deleteData() |
| DOMCharacterData->replaceData() |
| DOMCharacterData->substringData() |
(no version information, might be only in CVS)
DOMCharacterData->replaceData() -- Replace a substring within the DOMCharacterData node
Replace count characters starting from position
offset with data.
offsetThe offset from which to start replacing.
count
The number of characters to replace. If the sum of
offset and count exceeds
the length, then all characters to the end of the data are replaced.
dataThe string with which the range must be replaced.
Raised if offset is negative or greater than the
number of 16-bit units in data, or if count is
negative.
| DOMCharacterData->appendData() |
| DOMCharacterData->deleteData() |
| DOMCharacterData->insertData() |
| DOMCharacterData->substringData() |
(no version information, might be only in CVS)
DOMCharacterData->substringData() -- Extracts a range of data from the nodeReturns the specified substring.
The specified substring. If the sum of offset
and count exceeds the length, then all 16-bit units
to the end of the data are returned.
Raised if offset is negative or greater than the
number of 16-bit units in data, or if count is
negative.
| DOMCharacterData->appendData() |
| DOMCharacterData->deleteData() |
| DOMCharacterData->insertData() |
| DOMCharacterData->replaceData() |
(no version information, might be only in CVS)
DOMComment->__construct() -- Creates a new DOMComment objectCreates a new DOMComment object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createComment().
Example 1. Creating a new DOMComment
|
(no version information, might be only in CVS)
DOMDocument->__construct() -- Creates a new DOMDocument objectCreates a new DOMDocument object.
versionThe version number of the document as part of the XML declaration.
encodingThe encoding of the document as part of the XML declaration.
(no version information, might be only in CVS)
DOMDocument->createAttribute() -- Create new attributeThis function creates a new instance of class DOMAttr. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
| DOMNode->appendChild() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createAttributeNS() -- Create new attribute node with an associated namespaceThis function creates a new instance of class DOMAttr. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
namespaceURIThe URI of the namespace.
qualifiedNameThe tag name and prefix of the attribute, as prefix:tagname.
Raised if qualifiedName contains an invalid character.
Raised if qualifiedName is a malformed qualified
name, or if qualifiedName has a prefix and
namespaceURI is NULL.
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createCDATASection() -- Create new cdata nodeThis function creates a new instance of class DOMCDATASection. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createComment() -- Create new comment nodeThis function creates a new instance of class DOMComment. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createDocumentFragment() -- Create new document fragmentThis function creates a new instance of class DOMDocumentFragment. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createElement() -- Create new element nodeThis function creates a new instance of class DOMElement. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
nameThe tag name of the element.
valueThe value of the element. By default, an empty element will be created. You can also set the value later with DOMElement->nodeValue.
Example 1. Creating a new element and inserting it as root
The above example will output:
|
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createElementNS() -- Create new element node with an associated namespaceThis function creates a new element node with an associated namespace. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
namespaceURIThe URI of the namespace.
qualifiedNameThe qualified name of the element, as prefix:tagname.
valueThe value of the element. By default, an empty element will be created. You can also set the value later with DOMElement->nodeValue.
Raised if qualifiedName contains an invalid character.
Raised if qualifiedName is a maformed qualified
name.
Example 1. Creating a new element and inserting it as root
The above example will output:
|
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createEntityReference() -- Create new entity reference nodeThis function creates a new instance of class DOMEntityReference. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
nameThe content of the entity reference, e.g. the entity reference minus the leading & and the trailing ; characters.
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createProcessingInstruction() |
| DOMDocument->createTextNode() |
(no version information, might be only in CVS)
DOMDocument->createProcessingInstruction() -- Creates new PI nodeThis function creates a new instance of class DOMProcessingInstruction. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
targetThe target of the processing instruction.
dataThe content of the processing instruction.
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createTextNode() |
This function creates a new instance of class DOMText. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().
| DOMNode->appendChild() |
| DOMDocument->createAttribute() |
| DOMDocument->createAttributeNS() |
| DOMDocument->createCDATASection() |
| DOMDocument->createComment() |
| DOMDocument->createDocumentFragment() |
| DOMDocument->createElement() |
| DOMDocument->createElementNS() |
| DOMDocument->createEntityReference() |
| DOMDocument->createProcessingInstruction() |
(no version information, might be only in CVS)
DOMDocument->getElementById() -- Searches for an element with a certain idThis function is similar to DOMDocument->getElementsByTagName() but searches for an element with a given id.
For this function to work, you will need either to set some ID attributes with DOMElement->setIdAttribute() or a DTD which defines an attribute to be of type ID. In the later case, you will need to validate your document with DOMDocument->validate() or DOMDocument->validateOnParse before using this function.
Example 1. DOMDocument->getElementById() Example
The above example will output:
|
(no version information, might be only in CVS)
DOMDocument->getElementsByTagName() -- Searches for all elements with given tag nameThis function returns a new instance of class DOMNodeList containing the elements with a given tag name.
(no version information, might be only in CVS)
DOMDocument->getElementsByTagNameNS() -- Searches for all elements with given tag name in specified namespaceReturns a DOMNodeList of all elements with a given local name and a namespace URI.
namespaceURIThe namespace URI of the elements to match on. The special value * matches all namespaces.
localNameThe local name of the elements to match on. The special value * matches all local names.
Example 1. Get all the XInclude elements
The above example will output:
|
(no version information, might be only in CVS)
DOMDocument->importNode() -- Import node into current documentThis function returns a copy of the node to import and associates it with the current document.
importedNodeThe node to import.
deep
If set to TRUE, this method will recursively import the subtree under
the importedNode.
Loads an XML document from a file.
Returns TRUE on success or FALSE on failure. If called statically, returns a DOMDocument.
The function parses the HTML contained in the string source.
Unlike loading XML, HTML does not have to be well-formed to load. This
function may also be called statically to load and create a
DOMDocument object. The static invocation may be
used when no DOMDocument properties need to be
set prior to loading.
The function parses the HTML document in the file named
filename. Unlike loading XML, HTML does not have
to be well-formed to load.
This function may also be called statically to load and create a DOMDocument object. The static invocation may be used when no DOMDocument properties need to be set prior to loading.
Loads an XML document from a string.
This method may also be called statically to load and create a DOMDocument object. The static invocation may be used when no DOMDocument properties need to be set prior to loading.
Returns TRUE on success or FALSE on failure. If called statically, returns a DOMDocument.
(no version information, might be only in CVS)
DOMDocument->normalizeDocument() -- Normalizes the documentThis method acts as if you saved and then loaded the document, putting the document in a "normal" form.
(no version information, might be only in CVS)
DOMDocument->registerNodeClass() -- Register extended class used to create base node typeThis method allows you to register your own extended DOM class to be used afterward by the PHP DOM extension.
This method is not part of the DOM standard.
baseclassThe DOM class that you want to extend. You can find a list of these classes in the chapter introduction.
Of course, you won't be able to register a class extending DOMDocument but you can always start your document by instanciating your own extending class.
extendedclass
Your extended class name. If NULL is provided, any previously
registered class extending baseclass will
be removed.
Example 1. Adding a new method to DOMElement to ease our code
The above example will output:
|
(no version information, might be only in CVS)
DOMDocument->relaxNGValidate() -- Performs relaxNG validation on the documentPerforms relaxNG validation on the document based on the given RNG schema.
| DOMDocument->relaxNGValidateSource() |
| DOMDocument->schemaValidate() |
| DOMDocument->schemaValidateSource() |
| DOMDocument->validate() |
(no version information, might be only in CVS)
DOMDocument->relaxNGValidateSource() -- Performs relaxNG validation on the documentPerforms relaxNG validation on the document based on the given RNG source.
| DOMDocument->relaxNGValidate() |
| DOMDocument->schemaValidate() |
| DOMDocument->schemaValidateSource() |
| DOMDocument->validate() |
(no version information, might be only in CVS)
DOMDocument->save() -- Dumps the internal XML tree back into a fileCreates an XML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.
filenameThe path to the saved XML document.
optionsAdditional Options. Currently only LIBXML_NOEMPTYTAG is supported.
Example 1. Saving a DOM tree into a file
|
(no version information, might be only in CVS)
DOMDocument->saveHTML() -- Dumps the internal document into a string using HTML formattingCreates an HTML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.
Example 1. Saving a HTML tree into a string
|
(no version information, might be only in CVS)
DOMDocument->saveHTMLFile() -- Dumps the internal document into a file using HTML formattingCreates an HTML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.
Example 1. Saving a HTML tree into a file
|
(no version information, might be only in CVS)
DOMDocument->saveXML() -- Dumps the internal XML tree back into a stringCreates an XML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.
nodeUse this parameter to output only a specific node without XML declaration rather than the entire document.
optionsAdditional Options. Currently only LIBXML_NOEMPTYTAG is supported.
Example 1. Saving a DOM tree into a string
The above example will output:
|
(no version information, might be only in CVS)
DOMDocument->schemaValidate() -- Validates a document based on a schemaValidates a document based on the given schema file.
| DOMDocument->schemaValidateSource() |
| DOMDocument->relaxNGValidate() |
| DOMDocument->relaxNGValidateSource() |
| DOMDocument->validate() |
(no version information, might be only in CVS)
DOMDocument->schemaValidateSource() -- Validates a document based on a schemaValidates a document based on a schema defined in the given string.
| DOMDocument->schemaValidate() |
| DOMDocument->relaxNGValidate() |
| DOMDocument->relaxNGValidateSource() |
| DOMDocument->validate() |
(no version information, might be only in CVS)
DOMDocument->validate() -- Validates the document based on its DTDValidates the document based on its DTD.
You can also use the validateOnParse property of DOMDocument to make a DTD validation.
Returns TRUE on success or FALSE on failure. If the document have no DTD attached, this method will return FALSE.
| DOMDocument->schemaValidate() |
| DOMDocument->schemaValidateSource() |
| DOMDocument->relaxNGValidate() |
| DOMDocument->relaxNGValidateSource() |
(no version information, might be only in CVS)
DOMDocument->xinclude() -- Substitutes XIncludes in a DOMDocument ObjectThis method substitutes XIncludes in a DOMDocument object.
Note: Due to libxml2 automatically resolving entities, this method will produce unexpected results if the included XML file have an attached DTD.
Example 1. DOMDocument->xinclude() example
The above example will output something similar to:
|
(no version information, might be only in CVS)
DOMDocumentFragment->appendXML() -- Append raw XML dataAppends raw XML data to a DOMDocumentFragment.
This method is not part of the DOM standard. It was created as a simplier approach for appending an XML DocumentFragment in a DOMDocument.
If you want to stick to the standards, you will have to create a temporary DOMDocument with a dummy root and then loop through the child nodes of the root of your XML data to append them.
Example 1. Appending XML data to your document
The above example will output:
|
(no version information, might be only in CVS)
DOMElement->__construct() -- Creates a new DOMElement objectCreates a new DOMElement object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createElement() or DOMDocument->createElementNS().
nameThe tag name of the element. When also passing in namespaceURI, the element name may take a prefix to be associated with the URI.
valueThe value of the element.
namespaceURIA namespace URI to create the element within a specific namespace.
Example 1. Creating a new DOMElement
|
(no version information, might be only in CVS)
DOMElement->getAttribute() -- Returns value of attribute
Gets the value of the attribute with name name
for the current node.
The value of the attribute, or an empty string if no attribute with the
given name is found.
(no version information, might be only in CVS)
DOMElement->getAttributeNode() -- Returns attribute node
Returns the attribute node with name name for the
current element.
(no version information, might be only in CVS)
DOMElement->getAttributeNodeNS() -- Returns attribute node
Returns the attribute node in namespace namespaceURI
with local name localName for the current node.
| DOMElement->hasAttributeNS() |
| DOMElement->setAttributeNodeNS() |
| DOMElement->removeAttributeNode() |
(no version information, might be only in CVS)
DOMElement->getAttributeNS() -- Returns value of attribute
Gets the value of the attribute in namespace namespaceURI
with local name localName for the current node.
The value of the attribute, or an empty string if no attribute with the
given localName and namespaceURI
is found.
(no version information, might be only in CVS)
DOMElement->getElementsByTagName() -- Gets elements by tagname
This function returns a new instance of the class
DOMNodeList of all descendant elements with a
given tag name, in the order in which they are
encountered in a preorder traversal of this element tree.
This function returns a new instance of the class DOMNodeList of all matched elements.
(no version information, might be only in CVS)
DOMElement->getElementsByTagNameNS() -- Get elements by namespaceURI and localName
This function fetch all the descendant elements with a given
localName and namespaceURI.
namespaceURIThe namespace URI.
localNameThe local name. Use * to return all elements within the element tree.
This function returns a new instance of the class DOMNodeList of all matched elements in the order in which they are encountered in a preorder traversal of this element tree.
(no version information, might be only in CVS)
DOMElement->hasAttribute() -- Checks to see if attribute exists
Indicates whether attribute named name
exists as a member of the element.
| DOMElement->hasAttributeNS() |
| DOMElement->getAttribute() |
| DOMElement->setAttribute() |
| DOMElement->removeAttribute() |
(no version information, might be only in CVS)
DOMElement->hasAttributeNS() -- Checks to see if attribute exists
Indicates whether attribute in namespace namespaceURI
named localName exists as a member of the element.
| DOMElement->hasAttribute() |
| DOMElement->getAttributeNS() |
| DOMElement->setAttributeNS() |
| DOMElement->removeAttributeNS() |
Removes attribute named name from the element.
(no version information, might be only in CVS)
DOMElement->removeAttributeNode() -- Removes attribute
Removes attribute oldnode from the element.
Raised if the node is readonly.
Raised if oldnode is not an attribute of the element.
Removes attribute is namespace namespaceURI
named localName from the element.
Sets an attribute with name name to the given
value. If the attribute does not exist, it will be created.
(no version information, might be only in CVS)
DOMElement->setAttributeNode() -- Adds new attribute node to element
Adds new attribute node attr to element.
(no version information, might be only in CVS)
DOMElement->setAttributeNodeNS() -- Adds new attribute node to element
Adds new attribute node attr to element.
| DOMElement->hasAttributeNS() |
| DOMElement->getAttributeNodeNS() |
| DOMElement->removeAttributeNode() |
Sets an attribute with namespace namespaceURI and
name name to the given value. If the attribute
does not exist, it will be created.
namespaceURIThe namespace URI.
qualifiedNameThe qualified name of the attribute, as prefix:tagname.
valueThe value of the attribute.
Raised if the node is readonly.
Raised if qualifiedName is a malformed qualified
name, or if qualifiedName has a prefix and
namespaceURI is NULL.
(no version information, might be only in CVS)
DOMElement->setIdAttribute() -- Declares the attribute specified by name to be of type ID
Declares the attribute name to be of type ID.
nameThe name of the attribute.
isId
Set it to TRUE if you want name to be of type
ID, FALSE otherwise.
Raised if the node is readonly.
Raised if name is not an attribute of this element.
| DOMDocument->getElementById() |
| DOMElement->setIdAttributeNode() |
| DOMElement->setIdAttributeNS() |
(no version information, might be only in CVS)
DOMElement->setIdAttributeNode() -- Declares the attribute specified by node to be of type ID
Declares the attribute specified by attr to be of
type ID.
attrThe attribute node.
isId
Set it to TRUE if you want name to be of type
ID, FALSE otherwise.
Raised if the node is readonly.
Raised if name is not an attribute of this element.
(no version information, might be only in CVS)
DOMElement->setIdAttributeNS() -- Declares the attribute specified by local name and namespace URI to be of type ID
Declares the attribute specified by localName and
namespaceURI to be of type ID.
namespaceURIThe namespace URI of the attribute.
localNameThe local name of the attribute, as prefix:tagname.
isId
Set it to TRUE if you want name to be of type
ID, FALSE otherwise.
Raised if the node is readonly.
Raised if name is not an attribute of this element.
(no version information, might be only in CVS)
DOMEntityReference->__construct() -- Creates a new DOMEntityReference objectCreates a new DOMEntityReference object.
Example 1. Creating a new DOMEntityReference
|
(no version information, might be only in CVS)
DOMImplementation->__construct() -- Creates a new DOMImplementation objectCreates a new DOMImplementation object.
(no version information, might be only in CVS)
DOMImplementation->createDocument() -- Creates a DOMDocument object of the specified type with its document elementCreates a DOMDocument object of the specified type with its document element.
namespaceURIThe namespace URI of the document element to create.
qualifiedNameThe qualified name of the document element to create.
doctypeThe type of document to create or NULL.
A new DOMDocument object. If
namespaceURI, qualifiedName,
and doctype are null, the returned
DOMDocument is empty with no document element
Raised if doctype has already been used with a
different document or was created from a different implementation.
Raised if there is an error with the namespace, as determined by
namespaceURI and qualifiedName.
(no version information, might be only in CVS)
DOMImplementation->createDocumentType() -- Creates an empty DOMDocumentType objectCreates an empty DOMDocumentType object. Entity declarations and notations are not made available. Entity reference expansions and default attribute additions do not occur.
qualifiedNameThe qualified name of the document type to create.
publicIdThe external subset public identifier.
systemIdThe external subset system identifier.
Example 1. Creating a document with an attached DTD
The above example will output:
|
Raised if there is an error with the namespace, as determined by
qualifiedName.
(no version information, might be only in CVS)
DOMImplementation->hasFeature() -- Test if the DOM implementation implements a specific feature
Test if the DOM implementation implements a specific
feature.
You can find a list of all features in the Conformance section of the DOM specification.
featureThe feature to test.
version
The version number of the feature to test. In
level 2, this can be either 2.0 or
1.0.
Example 1. Testing your DOM Implementation
|
(no version information, might be only in CVS)
DOMNamedNodeMap->getNamedItem() -- Retrieves a node specified by nameRetrieves a node specified by its nodeName.
(no version information, might be only in CVS)
DOMNamedNodeMap->getNamedItemNS() -- Retrieves a node specified by local name and namespace URI
Retrieves a node specified by localName and
namespaceURI.
namespaceURIThe namespace URI of the node to retrieve.
localNameThe local name of the node to retrieve.
A node (of any type) with the specified local name and namespace URI, or NULL if no node is found.
(no version information, might be only in CVS)
DOMNamedNodeMap->item() -- Retrieves a node specified by index
Retrieves a node specified by index within the
DOMNamedNodeMap object.
The node at the indexth position in the map, or NULL
if that is not a valid index (greater than or equal to the number of nodes
in this map).
(no version information, might be only in CVS)
DOMNode->appendChild() -- Adds new child at the end of the childrenThis functions appends a child to an existing list of children or creates a new list of children. The child can be created with e.g. DOMDocument->createElement(), DOMDocument->createTextNode() etc. or simply by using any other node.
Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
Raised if this node is of a type that does not allow children of the
type of the newnode node, or if the node to
append is one of this node's ancestors or this node itself.
Raised if newnode was created from a different
document than the one that created this node.
deepIndicates whether to copy all descendant nodes. This parameter is defaulted to FALSE.
(no version information, might be only in CVS)
DOMNode->hasAttributes() -- Checks if node has attributesThis method checks if the node has attributes. The tested node have to be an XML_ELEMENT_NODE.
(no version information, might be only in CVS)
DOMNode->hasChildNodes() -- Checks if node has childrenThis function checks if the node has children.
(no version information, might be only in CVS)
DOMNode->insertBefore() -- Adds a new child before a reference nodeThis function inserts a new node right before the reference node. If you plan to do further modifications on the appended child you must use the returned node.
newnodeThe new node.
refnode
The reference node. If not supplied, newnode is
appended to the children.
Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
Raised if this node is of a type that does not allow children of the
type of the newnode node, or if the node to
append is one of this node's ancestors or this node itself.
Raised if newnode was created from a different
document than the one that created this node.
Raised if refnode is not a child of this node.
(no version information, might be only in CVS)
DOMNode->isDefaultNamespace() -- Checks if the specified namespaceURI is the default namespace or not
Tells whether namespaceURI is the default namespace.
(no version information, might be only in CVS)
DOMNode->isSameNode() -- Indicates if two nodes are the same nodeThis function indicates if two nodes are the same node. The comparison is not based on content
(no version information, might be only in CVS)
DOMNode->isSupported() -- Checks if feature is supported for specified version
Checks if the asked feature is supported for the
specified version.
featureThe feature to test. See the example of DOMImplementation->hasFeature() for a list of features.
version
The version number of the feature to test.
(no version information, might be only in CVS)
DOMNode->lookupNamespaceURI() -- Gets the namespace URI of the node based on the prefix
Gets the namespace URI of the node based on the
prefix.
(no version information, might be only in CVS)
DOMNode->lookupPrefix() -- Gets the namespace prefix of the node based on the namespace URIGets the namespace prefix of the node based on the namespace URI.
(no version information, might be only in CVS)
DOMNode->removeChild() -- Removes child from list of childrenThis functions removes a child from a list of children.
Raised if this node is readonly.
Raised if oldnode is not a child of this node.
The following example will delete the chapter element of our XML document.
Example 1. Removing a child
The above example will output:
|
This function replaces the child oldnode
with the passed new node. If the new node is already a child it
will not be added a second time. If the replacement succeeds the
old node is returned.
newnodeThe new node. It must be a member of the target document, i.e. created by one of the DOMDocument->createXXX() methods or imported in the document by DOMDocument->importNode().
oldnodeThe old node.
Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
Raised if this node is of a type that does not allow children of the
type of the newnode node, or if the node to
put in is one of this node's ancestors or this node itself.
Raised if newnode was created from a different
document than the one that created this node.
Raised if oldnode is not a child of this node.
(no version information, might be only in CVS)
DOMNodelist->item() -- Retrieves a node specified by index
Retrieves a node specified by index within the
DOMNodeList object.
Tip: If you need to know the number of nodes in the collection, use the length property of the DOMNodeList object.
The node at the indexth position in the
DOMNodeList, or NULL if that is not a valid
index.
Example 1. Traversing all the entries of the table
Alternatively, you can use foreach, which is a much more convenient way:
The above example will output:
|
(no version information, might be only in CVS)
DOMProcessingInstruction->__construct() -- Creates a new DOMProcessingInstruction objectCreates a new DOMProcessingInstruction object. This object is read only. It may be appended to a document, but additional nodes may not be appended to this node until the node is associated with a document. To create a writeable node, use DOMDocument->createProcessingInstruction().
nameThe tag name of the processing instruction.
valueThe value of the processing instruction.
Example 1. Creating a new DOMProcessingInstruction
The above example will output:
|
(no version information, might be only in CVS)
DOMText->__construct() -- Creates a new DOMText object(no version information, might be only in CVS)
DOMText->isWhitespaceInElementContent() -- Indicates whether this text node contains whitespaceIndicates whether this text node contains whitespace. The text node is determined to contain whitespace in element content during the load of the document.
(no version information, might be only in CVS)
DOMText->splitText() -- Breaks this node into two nodes at the specified offset
Breaks this node into two nodes at the specified offset,
keeping both in the tree as siblings.
After being split, this node will contain all the content up to the
offset. If the original node had a parent node,
the new node is inserted as the next sibling of the original node.
When the offset is equal to the length of this node,
the new node has no data.
The new node of the same type, which contains all the content at and after the
offset.
(no version information, might be only in CVS)
DOMXPath->__construct() -- Creates a new DOMXPath object(no version information, might be only in CVS)
DOMXPath->evaluate() -- Evaluates the given XPath expression and returns a typed result if possible.
Executes the given XPath expression and returns
a typed result if possible.
expressionThe XPath expression to execute.
contextnode
The optional contextnode can be specified for
doing relative XPath queries. By default, the queries are relative to
the root element.
Returns a typed result if possible or a DOMNodeList
containing all nodes matching the given XPath expression.
Example 1. Getting the count of all the english books
The above example will output:
|
(no version information, might be only in CVS)
DOMXPath->query() -- Evaluates the given XPath expression
Executes the given XPath expression.
expressionThe XPath expression to execute.
contextnode
The optional contextnode can be specified for
doing relative XPath queries. By default, the queries are relative to
the root element.
Returns a DOMNodeList containing all nodes matching
the given XPath expression. Any expression which do
not return nodes will return an empty DOMNodeList.
Example 1. Getting all the english books
The above example will output:
We can also use the
|
(no version information, might be only in CVS)
DOMXPath->registerNamespace() -- Registers the namespace with the DOMXPath object
Registers the namespaceURI and
prefix with the DOMXPath object.
This function takes the node node of class
SimpleXML and makes it into a
DOMElement node. This new object can then be used
as a native DOMElement node.
Example 1. Import SimpleXML into DOM with dom_import_simplexml()
|
The DOM XML extension has been overhauled in PHP 4.3.0 to better comply with the DOM standard. The extension still contains many old functions, but they should no longer be used. In particular, functions that are not object-oriented should be avoided.
The extension allows you to operate on an XML document with the DOM API. It also provides a function domxml_xmltree() to turn the complete XML document into a tree of PHP objects. Currently, this tree should be considered read-only - you can modify it, but this would not make any sense since DomDocument_dump_mem() cannot be applied to it. Therefore, if you want to read an XML file and write a modified version, use DomDocument_create_element(), DomDocument_create_text_node(), set_attribute(), etc. and finally the DomDocument_dump_mem() function.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.0.0.
This extension makes use of the GNOME XML library. Download and install this library. You will need at least libxml-2.4.14. To use DOM XSLT features you can use the libxslt library and EXSLT enhancements from http://www.exslt.org/. Download and install these libraries if you plan to use (enhanced) XSLT features. You will need at least libxslt-1.0.18.
This PECL extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/domxml.
In PHP 4 this PECL extensions
source can be found in the ext/ directory within the
PHP source or at the PECL link above.
This extension is only available if PHP was configured with
--with-dom[=DIR]. Add
--with-dom-xslt[=DIR] to include DOM
XSLT support. DIR is the libxslt install directory. Add
--with-dom-exslt[=DIR] to include DOM
EXSLT support, where DIR is the libexslt install directory.
Windows users will enable php_domxml.dll inside of php.ini in order to use these functions. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/ Also, there is one additional DLL that must be made available to your system's PATH in order for this extension to work. In PHP 4 this is in the dlls/ directory. It's name: For PHP <= 4.2.0, it's libxml2.dll. For PHP >= 4.3.0, it's iconv.dll. And as of PHP 5.0.0, iconv is compiled into your Windows PHP binaries by default so no extra DLL is needed.
There are quite a few functions that do not fit into the DOM standard and should no longer be used. These functions are listed in the following table. The function DomNode_append_child() has changed its behaviour. It now adds a child and not a sibling. If this breaks your application, use the non-DOM function DomNode_append_sibling().
Table 1. Deprecated functions and their replacements
| Old function | New function |
|---|---|
| xmldoc | domxml_open_mem() |
| xmldocfile | domxml_open_file() |
| domxml_new_xmldoc | domxml_new_doc() |
| domxml_dump_mem | DomDocument_dump_mem() |
| domxml_dump_mem_file | DomDocument_dump_file() |
| DomDocument_dump_mem_file | DomDocument_dump_file() |
| DomDocument_add_root | DomDocument_create_element() followed by DomNode_append_child() |
| DomDocument_dtd | DomDocument_doctype() |
| DomDocument_root | DomDocument_document_element() |
| DomDocument_children | DomNode_child_nodes() |
| DomDocument_imported_node | No replacement. |
| DomNode_add_child | Create a new node with e.g. DomDocument_create_element() and add it with DomNode_append_child(). |
| DomNode_children | DomNode_child_nodes() |
| DomNode_parent | DomNode_parent_node() |
| DomNode_new_child | Create a new node with e.g. DomDocument_create_element() and add it with DomNode_append_child(). |
| DomNode_set_content | Create a new node with e.g. DomDocument_create_text_node() and add it with DomNode_append_child(). |
| DomNode_get_content | Content is just a text node and can be accessed with DomNode_child_nodes(). |
| DomNode_set_content | Content is just a text node and can be added with DomNode_append_child(). |
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Table 2. XML constants
| Constant | Value | Description |
|---|---|---|
| XML_ELEMENT_NODE (integer) | 1 | Node is an element |
| XML_ATTRIBUTE_NODE (integer) | 2 | Node is an attribute |
| XML_TEXT_NODE (integer) | 3 | Node is a piece of text |
| XML_CDATA_SECTION_NODE (integer) | 4 | |
| XML_ENTITY_REF_NODE (integer) | 5 | |
| XML_ENTITY_NODE (integer) | 6 | Node is an entity like |
| XML_PI_NODE (integer) | 7 | Node is a processing instruction |
| XML_COMMENT_NODE (integer) | 8 | Node is a comment |
| XML_DOCUMENT_NODE (integer) | 9 | Node is a document |
| XML_DOCUMENT_TYPE_NODE (integer) | 10 | |
| XML_DOCUMENT_FRAG_NODE (integer) | 11 | |
| XML_NOTATION_NODE (integer) | 12 | |
| XML_GLOBAL_NAMESPACE (integer) | 1 | |
| XML_LOCAL_NAMESPACE (integer) | 2 | |
| XML_HTML_DOCUMENT_NODE (integer) | ||
| XML_DTD_NODE (integer) | ||
| XML_ELEMENT_DECL_NODE (integer) | ||
| XML_ATTRIBUTE_DECL_NODE (integer) | ||
| XML_ENTITY_DECL_NODE (integer) | ||
| XML_NAMESPACE_DECL_NODE (integer) | ||
| XML_ATTRIBUTE_CDATA (integer) | ||
| XML_ATTRIBUTE_ID (integer) | ||
| XML_ATTRIBUTE_IDREF (integer) | ||
| XML_ATTRIBUTE_IDREFS (integer) | ||
| XML_ATTRIBUTE_ENTITY (integer) | ||
| XML_ATTRIBUTE_NMTOKEN (integer) | ||
| XML_ATTRIBUTE_NMTOKENS (integer) | ||
| XML_ATTRIBUTE_ENUMERATION (integer) | ||
| XML_ATTRIBUTE_NOTATION (integer) | ||
| XPATH_UNDEFINED (integer) | ||
| XPATH_NODESET (integer) | ||
| XPATH_BOOLEAN (integer) | ||
| XPATH_NUMBER (integer) | ||
| XPATH_STRING (integer) | ||
| XPATH_POINT (integer) | ||
| XPATH_RANGE (integer) | ||
| XPATH_LOCATIONSET (integer) | ||
| XPATH_USERS (integer) | ||
| XPATH_NUMBER (integer) |
The API of the module follows the DOM Level 2 standard as closely as possible. Consequently, the API is fully object-oriented. It is a good idea to have the DOM standard available when using this module. Though the API is object-oriented, there are many functions which can be called in a non-object-oriented way by passing the object to operate on as the first argument. These functions are mainly to retain compatibility to older versions of the extension, and should not be used when creating new scripts.
This API differs from the official DOM API in two ways. First, all class attributes are implemented as functions with the same name. Secondly, the function names follow the PHP naming convention. This means that a DOM function lastChild() will be written as last_child().
This module defines a number of classes, which are listed - including their method - in the following tables. Classes with an equivalent in the DOM standard are named DOMxxx.
Table 3. List of classes
| Class name | Parent classes |
|---|---|
| DomAttribute | DomNode |
| DomCData | DomNode |
| DomComment | DomCData : DomNode |
| DomDocument | DomNode |
| DomDocumentType | DomNode |
| DomElement | DomNode |
| DomEntity | DomNode |
| DomEntityReference | DomNode |
| DomProcessingInstruction | DomNode |
| DomText | DomCData : DomNode |
| Parser | Currently still called DomParser |
| XPathContext |
Table 4. DomDocument class (DomDocument : DomNode)
| Method name | Function name | Remark |
|---|---|---|
| doctype | DomDocument_doctype() | |
| document_element | DomDocument_document_element() | |
| create_element | DomDocument_create_element() | |
| create_text_node | DomDocument_create_text_node() | |
| create_comment | DomDocument_create_comment() | |
| create_cdata_section | DomDocument_create_cdata_section() | |
| create_processing_instruction | DomDocument_create_processing_instruction() | |
| create_attribute | DomDocument_create_attribute() | |
| create_entity_reference | DomDocument_create_entity_reference() | |
| get_elements_by_tagname | DomDocument_get_elements_by_tagname() | |
| get_element_by_id | DomDocument_get_element_by_id() | |
| dump_mem | DomDocument_dump_mem() | not DOM standard |
| dump_file | DomDocument_dump_file() | not DOM standard |
| html_dump_mem | DomDocument_html_dump_mem() | not DOM standard |
| xpath_init | xpath_init | not DOM standard |
| xpath_new_context | xpath_new_context | not DOM standard |
| xptr_new_context | xptr_new_context | not DOM standard |
Table 5. DomElement class (DomElement : DomNode)
| Method name | Function name | Remark |
|---|---|---|
| tagname | DomElement_tagname() | |
| get_attribute | DomElement_get_attribute() | |
| set_attribute | DomElement_set_attribute() | |
| remove_attribute | DomElement_remove_attribute() | |
| get_attribute_node | DomElement_get_attribute_node() | |
| set_attribute_node | DomElement_set_attribute_node() | |
| get_elements_by_tagname | DomElement_get_elements_by_tagname() | |
| has_attribute | DomElement_has_attribute() |
Table 6. DomNode class
| Method name | Remark |
|---|---|
| DomNode_node_name() | |
| DomNode_node_value() | |
| DomNode_node_type() | |
| DomNode_last_child() | |
| DomNode_first_child() | |
| DomNode_child_nodes() | |
| DomNode_previous_sibling() | |
| DomNode_next_sibling() | |
| DomNode_parent_node() | |
| DomNode_owner_document() | |
| DomNode_insert_before() | |
| DomNode_append_child() | |
| DomNode_append_sibling() | Not in DOM standard. This function emulates the former behaviour of DomNode_append_child(). |
| DomNode_remove_child() | |
| DomNode_has_child_nodes() | |
| DomNode_has_attributes() | |
| DomNode_clone_node() | |
| DomNode_attributes() | |
| DomNode_unlink_node() | Not in DOM standard |
| DomNode_replace_node() | Not in DOM standard |
| DomNode_set_content() | Not in DOM standard, deprecated |
| DomNode_get_content() | Not in DOM standard, deprecated |
| DomNode_dump_node() | Not in DOM standard |
| DomNode_is_blank_node() | Not in DOM standard |
Table 7. DomAttribute class (DomAttribute : DomNode)
| Method name | Remark | |
|---|---|---|
| name | DomAttribute_name() | |
| value | DomAttribute_value() | |
| specified | DomAttribute_specified() |
Table 8. DomProcessingInstruction class (DomProcessingInstruction : DomNode)
| Method name | Function name | Remark |
|---|---|---|
| target | DomProcessingInstruction_target() | |
| data | DomProcessingInstruction_data() |
Table 10. XPathContext class
| Method name | Function name | Remark |
|---|---|---|
| eval | XPathContext_eval() | |
| eval_expression | XPathContext_eval_expression() | |
| register_ns | XPathContext_register_ns() |
Table 11. DomDocumentType class (DomDocumentType : DomNode)
| Method name | Function name | Remark |
|---|---|---|
| name | DomDocumentType_name() | |
| entities | DomDocumentType_entities() | |
| notations | DomDocumentType_notations() | |
| public_id | DomDocumentType_public_id() | |
| system_id | DomDocumentType_system_id() | |
| internal_subset | DomDocumentType_internal_subset() |
The classes DomDtd is derived from DomNode. DomComment is derived from DomCData.
Many examples in this reference require an XML string. Instead of repeating this string in every example, it will be put into a file which will be included by each example. This include file is shown in the following example section. Alternatively, you could create an XML document and read it with DomDocument_open_file().
Example 1. Include file example.inc with XML string
|
(no version information, might be only in CVS)
DomAttribute->set_value -- Sets the value of an attributeThis function sets the value of an attribute.
(no version information, might be only in CVS)
DomAttribute->specified -- Checks if attribute is specifiedChecks if the attribute was explicitly given a value in the original document.
Note: This method is not implemented yet.
This function returns the value of the attribute.
Example 1. Getting all the attributes of a node
The above example will output:
|
(no version information, might be only in CVS)
DomDocument->add_root -- Adds a root node [deprecated]Adds a root element node to a dom document and returns the new node. The element name is given in the passed parameter.
This function returns a new instance of class DomAttribute. The name of the attribute is the value of the first parameter. The value of the attribute is the value of the second parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domnode_append_child(), domdocument_create_element(), domdocument_create_text(), domdocument_create_cdata_section(), domdocument_create_processing_instruction(), domdocument_create_entity_reference(), and domnode_insert_before().
(no version information, might be only in CVS)
DomDocument->create_cdata_section -- Create new cdata nodeThis function returns a new instance of class DomCData. The content of the cdata is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domnode_append_child(), domdocument_create_element(), domdocument_create_text(), domdocument_create_attribute(), domdocument_create_processing_instruction(), domdocument_create_entity_reference(), and domnode_insert_before().
(no version information, might be only in CVS)
DomDocument->create_comment -- Create new comment nodeThis function returns a new instance of class DomComment. The content of the comment is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domnode_append_child(), domdocument_create_element(), domdocument_create_text(), domdocument_create_attribute(), domdocument_create_processing_instruction(), domdocument_create_entity_reference(), and domnode_insert_before().
(no version information, might be only in CVS)
DomDocument->create_element_ns -- Create new element node with an associated namespace
This function returns a new instance of class
DomElement. The tag name of the element is the
value of the passed parameter name. The URI of the
namespace is the value of the passed parameter uri.
If there is already a namespace declaration with the same uri in the root-node
of the document, the prefix of this is taken, otherwise it will take the one provided
in the optional parameter prefix or generate a random one.
This node will not show up in the document unless it
is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domdocument_create_element_ns(), domnode_add_namespace(), domnode_set_namespace(), domnode_append_child(), domdocument_create_text(), domdocument_create_comment(), domdocument_create_attribute(), domdocument_create_processing_instruction(), domdocument_create_entity_reference(), and domnode_insert_before().
(no version information, might be only in CVS)
DomDocument->create_element -- Create new element nodeThis function returns a new instance of class DomElement. The tag name of the element is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domdocument_create_element_ns(), domnode_append_child(), domdocument_create_text(), domdocument_create_comment(), domdocument_create_attribute(), domdocument_create_processing_instruction(), domdocument_create_entity_reference(), and domnode_insert_before().
(no version information, might be only in CVS)
DomDocument->create_entity_reference -- Create an entity referenceThis function returns a new instance of class DomEntityReference. The content of the entity reference is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domnode_append_child(), domdocument_create_element(), domdocument_create_text(), domdocument_create_cdata_section(), domdocument_create_processing_instruction(), domdocument_create_attribute(), and domnode_insert_before().
(no version information, might be only in CVS)
DomDocument->create_processing_instruction -- Creates new PI nodeThis function returns a new instance of class DomCData. The content of the pi is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domnode_append_child(), domdocument_create_element(), domdocument_create_text(), domdocument_create_cdata_section(), domdocument_create_attribute(), domdocument_create_entity_reference(), and domnode_insert_before().
This function returns a new instance of class DomText. The content of the text is the value of the passed parameter. This node will not show up in the document unless it is inserted with e.g. domnode_append_child().
The return value is FALSE if an error occurred.
See also domnode_append_child(), domdocument_create_element(), domdocument_create_comment(), domdocument_create_text(), domdocument_create_attribute(), domdocument_create_processing_instruction(), domdocument_create_entity_reference(), and domnode_insert_before().
This function returns an object of class DomDocumentType. In versions of PHP before 4.3 this has been the class Dtd, but the DOM Standard does not know such a class.
See also the methods of class DomDocumentType.
(no version information, might be only in CVS)
DomDocument->document_element -- Returns root element nodeThis function returns the root element node of a document.
The following example returns just the element with name CHAPTER and prints it. The other node -- the comment -- is not returned.
Example 1. Retrieving root element
The above example will output:
|
(no version information, might be only in CVS)
DomDocument->dump_file -- Dumps the internal XML tree back into a file
Creates an XML document from the dom representation. This function
usually is called after building a new dom document from scratch
as in the example below. The
format specifies whether the output should be
neatly formatted, or not. The first parameter specifies the name of the
filename and the second parameter, whether it should be compressed or not.
Example 1. Creating a simple HTML document header
|
See also domdocument_dump_mem(), and domdocument_html_dump_mem().
(no version information, might be only in CVS)
DomDocument->dump_mem -- Dumps the internal XML tree back into a string
Creates an XML document from the dom representation. This function
usually is called after building a new dom document from scratch
as in the example below. The
format specifies whether the output should be
neatly formatted, or not.
Example 1. Creating a simple HTML document header
|
Note: The first parameter was added in PHP 4.3.0.
See also domdocument_dump_file(), and domdocument_html_dump_mem().
(no version information, might be only in CVS)
DomDocument->get_element_by_id -- Searches for an element with a certain idThis function is similar to domdocument_get_elements_by_tagname() but searches for an element with a given id. According to the DOM standard this requires a DTD which defines the attribute ID to be of type ID, though the current implementation simply does an xpath search for "//*[@ID = '%s']". This does not comply to the DOM standard which requires to return null if it is not known which attribute is of type id. This behaviour is likely to be fixed, so do not rely on the current behaviour.
(no version information, might be only in CVS)
DomDocument->get_elements_by_tagname -- Returns array with nodes with given tagname in document or empty array, if not found
See also domdocument_add_root()
(no version information, might be only in CVS)
DomDocument->html_dump_mem -- Dumps the internal XML tree back into a string as HTMLCreates an HTML document from the dom representation. This function usually is called after building a new dom document from scratch as in the example below.
Example 1. Creating a simple HTML document header
The above example will output:
|
See also domdocument_dump_file(), and domdocument_html_dump_mem().
(no version information, might be only in CVS)
DomDocument->xinclude -- Substitutes XIncludes in a DomDocument ObjectThis function substitutes XIncludes in a DomDocument object.
Example 1. Substituting Xincludes
The above example will output:
If include.xml doesn't exist, you'll see:
|
(no version information, might be only in CVS)
DomDocumentType->entities() -- Returns list of entities
| Warning |
This function is currently not documented; only the argument list is available. |
(no version information, might be only in CVS)
DomDocumentType->internal_subset() -- Returns internal subset
| Warning |
This function is currently not documented; only the argument list is available. |
(no version information, might be only in CVS)
DomDocumentType->name() -- Returns name of document typeThis function returns the name of the document type.
(no version information, might be only in CVS)
DomDocumentType->notations() -- Returns list of notations
| Warning |
This function is currently not documented; only the argument list is available. |
(no version information, might be only in CVS)
DomDocumentType->public_id() -- Returns public id of document typeThis function returns the public id of the document type.
(no version information, might be only in CVS)
DomDocumentType->system_id() -- Returns the system id of document typeReturns the system id of the document type.
(no version information, might be only in CVS)
DomElement->get_attribute_node() -- Returns the node of the given attributeReturns the node of the given attribute in the current element.
Returns the node of the attribute as a DomAttribute
or FALSE if no attribute with the given name is
found.
Example 1. Getting an attribute node
|
(no version information, might be only in CVS)
DomElement->get_attribute() -- Returns the value of the given attributeReturns the value of the given attribute in the current element.
Since PHP 4.3, if no attribute with given name is
found, an empty string is returned.
Returns the name of the attribute as a string or an empty string if no
attribute with the given name is found.
(no version information, might be only in CVS)
DomElement->get_elements_by_tagname() -- Gets elements by tagname
Gets all the sub elements with the specific name
within the current element.
(no version information, might be only in CVS)
DomElement->has_attribute() -- Checks to see if an attribute exists in the current node
This functions checks to see if an attribute named
name exists in the current node.
Example 1. Testing the existence of an attribute
|
Removes an attribute from the current DomElement node.
(no version information, might be only in CVS)
DomElement->set_attribute_node() -- Adds new attribute
| Warning |
This function is currently not documented; only the argument list is available. |
(no version information, might be only in CVS)
DomElement->set_attribute() -- Sets the value of an attribute
Sets an attribute with name name to the given
value.
nameThe name of the attribute. If this attribute doesn't exist, it will be created.
valueThe value of the attribute.
Returns the old DomAttribute node, or the new one if you are creating the attribute for the first time.
(no version information, might be only in CVS)
DomElement->tagname() -- Returns the name of the current elementReturns the name of the current node. Calling this function is the same as accessing the tagname property, or calling DomNode->node_name on the current node.
(no version information, might be only in CVS)
DomNode->add_namespace -- Adds a namespace declaration to a nodeThis method adds a namespace declaration to a node.
Note: This method is not part of the DOM specification.
You can set the namespace URI and prefix of a DOMElement or a DOMAttr at creation time by using DOMDocument->createElementNS() or DOMDocument->createAttributeNS().
Note: Remember the an attribute does not inherit its namespace from the element it is attached to.
(no version information, might be only in CVS)
DomNode->append_child -- Adds a new child at the end of the childrenThis functions appends a child to an existing list of children or creates a new list of children.
newnodeThe node being appended. It can be created with e.g. DomDocument->create_element, DomDocument->create_text_node etc. or simply by using any other node.
Note: You can not append a DOMAttribute using this method. Use DomElement->set_attribute() instead.
| Version | Description |
|---|---|
| 4.3.0 | You are not allowed anymore to insert a node from another document. |
| 4.3.0 | Prior to PHP 4.3.0, the new child is duplicated before being appended. Therefore the new child is a completely new copy which can be modified without changing the node which was passed to this function. If the node passed has children itself, they will be duplicated as well, which makes it quite easy to duplicate large parts of an XML document. The return value is the appended child. If you plan to do further modifications on the appended child you must use the returned node. |
| 4.3.0 and 4.3.1 |
The new child newnode is first unlinked from
its existing context, if it's already a child of DomNode. Therefore
the newnode is moved and not copies anymore.
This is the behaviour according to the W3C specifications. If you
need the old behaviour, use DomNode->clone_node before appending.
|
| 4.3.2 |
The new child newnode is first unlinked from
its existing context, if it's already in the tree. Same rules apply.
|
The following example adds a new element node to a fresh document and sets the attribute align to left.
The above example could also be written as the following:
A more complex example is the one below. It first searches for a certain element, duplicates it including its children and adds it as a sibling. Finally a new attribute is added to one of the children of the new sibling and the whole document is dumped.
Example 3. Adding a child
|
The above example could also be done with DomNode->insert_before instead of DomNode->append_child.
This functions appends a sibling to an existing node. The child can be created with e.g. domdocument_create_element(), domdocument_create_text() etc. or simply by using any other node.
Before a new sibling is added it is first duplicated. Therefore the new child is a completely new copy which can be modified without changing the node which was passed to this function. If the node passed has children itself, they will be duplicated as well, which makes it quite easy to duplicate large parts of an XML document. The return value is the added sibling. If you plan to do further modifications on the added sibling you must use the returned node.
This function has been added to provide the behaviour of domnode_append_child() as it works till PHP 4.2.
See also domnode_append_before().
This function only returns an array of attributes if the node is of type XML_ELEMENT_NODE.
(PHP >= 4.3 only) If no attributes are found, NULL is returned.
Returns all children of the node.
See also domnode_next_sibling(), and domnode_previous_sibling().
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
See also domdocument_dump_mem().
Returns the first child of the node.
(PHP >= 4.3 only) If no first child is found, NULL is returned.
See also domnode_last_child(), and domnode_next_sibling(), domnode_previous_sibling().
This function returns the content of the actual node.
Example 1. Getting a content
|
(no version information, might be only in CVS)
DomNode->has_attributes -- Checks if node has attributesThis function checks if the node has attributes.
See also domnode_has_child_nodes().
(no version information, might be only in CVS)
DomNode->has_child_nodes -- Checks if node has childrenThis function checks if the node has children.
See also domnode_child_nodes().
This function inserts the new node newnode right
before the node refnode. The return value is the
inserted node. If you plan to do further modifications on the appended
child you must use the returned node.
(PHP >= 4.3 only) If newnode already is part of a
document, it will be first unlinked from its existing context. If
refnode is NULL, then newnode
will be inserted at the end of the list of children.
domnode_insert_before() is very similar to domnode_append_child() as the following example shows which does the same as the example at domnode_append_child().
Example 1. Adding a child
|
See also domnode_append_child().
| Warning |
This function is currently not documented; only the argument list is available. |
Returns the last child of the node.
(PHP >= 4.3 only) If no last child is found, NULL is returned.
See also domnode_first_child(), and domnode_next_sibling(), domnode_previous_sibling().
(no version information, might be only in CVS)
DomNode->next_sibling -- Returns the next sibling of nodeThis function returns the next sibling of the current node. If there is no next sibling it returns FALSE (< 4.3) or null (>= 4.3). You can use this function to iterate over all children of a node as shown in the example.
Example 1. Iterate over children
|
See also domnode_previous_sibling().
Returns name of the node. The name has different meanings for the different types of nodes as illustrated in the following table.
Table 1. Meaning of value
| Type | Meaning |
|---|---|
| DomAttribute | value of attribute |
| DomAttribute | |
| DomCDataSection | #cdata-section |
| DomComment | #comment |
| DomDocument | #document |
| DomDocumentType | document type name |
| DomElement | tag name |
| DomEntity | name of entity |
| DomEntityReference | name of entity reference |
| DomNotation | notation name |
| DomProcessingInstruction | target |
| DomText | #text |
Returns the type of the node. All possible types are listed in the table in the introduction.
Example 1.
The above example will output:
|
Returns value of the node. The value has different meanings for the different types of nodes as illustrated in the following table.
Table 1. Meaning of value
| Type | Meaning |
|---|---|
| DomAttribute | value of attribute |
| DomAttribute | |
| DomCDataSection | content |
| DomComment | content of comment |
| DomDocument | null |
| DomDocumentType | null |
| DomElement | null |
| DomEntity | null |
| DomEntityReference | null |
| DomNotation | null |
| DomProcessingInstruction | entire content without target |
| DomText | content of text |
(no version information, might be only in CVS)
DomNode->owner_document -- Returns the document this node belongs toThis function returns the document the current node belongs to.
The following example will create two identical lists of children.
See also domnode_insert_before().
(no version information, might be only in CVS)
DomNode->parent_node -- Returns the parent of the nodeThis function returns the parent node.
(PHP >= 4.3 only) If no parent is found, NULL is returned.
The following example will show two identical lists of children.
(no version information, might be only in CVS)
DomNode->previous_sibling -- Returns the previous sibling of nodeThis function returns the previous sibling of the current node. If there is no previous sibling it returns FALSE (< 4.3) or NULL (>= 4.3). You can use this function to iterate over all children of a node as shown in the example.
See also domnode_next_sibling().
(no version information, might be only in CVS)
DomNode->remove_child -- Removes child from list of childrenThis functions removes a child from a list of children. If child cannot be removed or is not a child the function will return FALSE. If the child could be removed the functions returns the old child.
Example 1. Removing a child
|
See also domnode_append_child().
(PHP 4.2) This function replaces the child oldnode
with the passed new node. If the new node is already a child it
will not be added a second time. If the old node cannot be found
the function returns FALSE. If the replacement succeeds the old node
is returned.
(PHP 4.3) This function replaces the child oldnode
with the passed newnode, even if the new node already
is a child of the DomNode. If newnode was already
inserted in the document it is first unlinked from its existing context.
If the old node cannot be found the function returns FALSE. If the replacement
succeeds the old node is returned. (This behaviour is according to the W3C specs).
See also domnode_append_child()
(PHP 4.2) This function replaces an existing node with the passed
new node. Before the replacement
newnode is copied if it has a parent to
make sure a node which is
already in the document will not be inserted a second time. This
behaviour enforces doing all modifications on the node before the
replacement or to refetch the inserted node afterwards with functions like
domnode_first_child(),
domnode_child_nodes() etc..
(PHP 4.3) This function replaces an existing node with the passed new node. It is not
copied anymore. If newnode was already inserted in the document
it is first unlinked from its existing context. If the replacement succeeds the old
node is returned.
See also domnode_append_child()
| Warning |
This function is currently not documented; only the argument list is available. |
Sets the namespace of a node to uri.
If there is already a namespace declaration with the same uri in one of the parent nodes
of the node, the prefix of this is taken, otherwise it will take the one provided
in the optional parameter prefix or generate a random one.
See also domdocument_create_element_ns(), and domnode_add_namespace()
| Warning |
This function is currently not documented; only the argument list is available. |
(no version information, might be only in CVS)
DomProcessingInstruction->data -- Returns the data of ProcessingInstruction nodeThis method gets the data of the ProcessingInstruction node.
(no version information, might be only in CVS)
DomProcessingInstruction->target -- Returns the target of a ProcessingInstruction nodeThis method gets the target of the ProcessingInstruction node.
(no version information, might be only in CVS)
DomXsltStylesheet->process() -- Applies the XSLT-Transformation on a DomDocument ObjectApplies an XSLT Transformation on the given DomDocument object.
xml_docThe XML document being transformed, as a DomDocument object.
xslt_paramsAn associative array that takes pairs of parameter names and values.
is_xpath_param
If set to FALSE the values of the xslt_params
will be quoted. This is the default behavior. It allows you to pass
the values as PHP strings.
Note: If your strings contains both single and double quotes, you must take care of quoting all the values by yourself and set this parameter to TRUE.
profile_filenameSet this to the path of a filename, if you want profiling information.
(no version information, might be only in CVS)
DomXsltStylesheet->result_dump_file() -- Dumps the result from a XSLT-Transformation into a fileSince DomXsltStylesheet->process() always returns a well-formed XML DomDocument, no matter what output method was declared in <xsl:output> and similar attributes/elements, it's of not much use, if you want to output HTML 4 or text data.
This function on the contrary honors <xsl:output method="html|text"> and other output control directives. See the example for instruction on how to use it.
(no version information, might be only in CVS)
DomXsltStylesheet->result_dump_mem() -- Dumps the result from a XSLT-Transformation back into a stringSince DomXsltStylesheet->process() always returns a well-formed XML DomDocument, no matter what output method was declared in <xsl:output> and similar attributes/elements, it's of not much use, if you want to output HTML 4 or text data.
This function on the contrary honors <xsl:output method="html|text"> and other output control directives. See the example for instruction on how to use it.
Creates a new Dom document from scratch and returns it.
The function parses the XML document in the given file.
filenameThe path to the XML file. The file is accessed in read-only mode.
modeThis optional parameter can be used to change the behavior of this function.
You can use one of the following constants for it: DOMXML_LOAD_PARSING (default), DOMXML_LOAD_VALIDATING or DOMXML_LOAD_RECOVERING. You can add to it also DOMXML_LOAD_DONT_KEEP_BLANKS, DOMXML_LOAD_SUBSTITUTE_ENTITIES and DOMXML_LOAD_COMPLETE_ATTRS by bitwise or.
error
If used, it will contain the error messages.
error must be passed in by reference.
The function parses the XML document in the given string.
strThe contents of the XML file.
modeThis optional parameter can be used to change the behavior of this function.
You can use one of the following constants for it: DOMXML_LOAD_PARSING (default), DOMXML_LOAD_VALIDATING or DOMXML_LOAD_RECOVERING. You can add to it also DOMXML_LOAD_DONT_KEEP_BLANKS, DOMXML_LOAD_SUBSTITUTE_ENTITIES and DOMXML_LOAD_COMPLETE_ATTRS by bitwise or.
error
If used, it will contain the error messages.
error must be passed in by reference.
The function parses the XML document in str and
returns a tree PHP objects as the parsed document.
This function is isolated from the other functions, which means you cannot access the tree with any of the other functions. Modifying it, for example by adding nodes, makes no sense since there is currently no way to dump it as an XML file.
However this function may be valuable if you want to read a file and investigate the content.
(PHP 4 >= 4.2.0, PECL)
domxml_xslt_stylesheet_doc -- Creates a DomXsltStylesheet Object from a DomDocument ObjectCreates a DomXsltStylesheet object from the given XSL document.
(PHP 4 >= 4.2.0, PECL)
domxml_xslt_stylesheet_file -- Creates a DomXsltStylesheet Object from an XSL document in a fileCreates a DomXsltStylesheet object from the given XSL file.
Call XSLTProcessor::importStylesheet with DOMDocument::load($xsl_file) as parameter.
(PHP 4 >= 4.2.0, PECL)
domxml_xslt_stylesheet -- Creates a DomXsltStylesheet object from an XSL document in a stringCreates a DomXsltStylesheet object from the given XSL buffer.
Call XSLTProcessor::importStylesheet with DOMDocument::loadXML($xsl_buf) as parameter.
(PHP 4 >= 4.0.4, PECL)
xpath_eval_expression -- Evaluates the XPath Location Path in the given string
Example 1. xpath_eval_expression() Example
The above example will output:
|
See also xpath_eval().
The optional contextnode can be specified for doing relative XPath queries.
See also xpath_new_context().
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
Enchant is the PHP binding for the Enchant library. Enchant steps in to provide uniformity and conformity on top of all spelling libraries, and implement certain features that may be lacking in any individual provider library. Everything should "just work" for any and every definition of "just working."
Enchat supports the following backends:
Aspell/Pspell (intends to replace Ispell)
Ispell (old as sin, could be interpreted as a defacto standard)
MySpell/Hunspell (an OOo projects, also used by Mozilla)
Uspell (primarily Yiddish, Hebrew, and Eastern European languages - hosted in AbiWord's CVS under the module "uspell")
Hspell (Hebrew)
AppleSpell (Mac OSX)
This version uses the functions of the Enchant library by Dom Lachowicz. You need Enchant 1.2.4 or later.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/enchant.
There are two types of resources in this extension. The first one is the broker (backends manager) and the second is for the dictionary.
Example 1. Enchant Usage Example
|
Enumerates the Enchant providers and tells you some rudimentary information about them. The same info is provided through phpinfo().
Example 1. List the backends provided by the given broker
The above example will output something similar to:
|
Tells if a dictionary exists or not, using a non-empty tags
Free a broker resource with all its dictionaries.
Returns the last error which occurred in this broker.
(no version information, might be only in CVS)
enchant_broker_list_dicts -- Returns a list of available dictionariesReturns a list of available dictionaries with their details.
Example 1. List all available dictionaries for one broker
The above example will output something similar to:
|
create a new dictionary using tag, the non-empty language tag you wish to request a dictionary for ("en_US", "de_DE", ...)
Example 1. A enchant_broker_request_dict() example Check if a dictionary exists using enchant_broker_dict_exists() and request it.
|
(PECL)
enchant_broker_request_pwl_dict -- creates a dictionary using a PWL file. A PWL file is personal word file one word per line.creates a dictionary using a PWL file. A PWL file is personal word file one word per line.
Declares a preference of dictionaries to use for the language described/referred to by 'tag'. The ordering is a comma delimited list of provider names. As a special exception, the "*" tag can be used as a language tag to declare a default ordering for any language that does not explicitly declare an ordering.
brokerBroker resource
tagLanguage tag. The special "*" tag can be used as a language tag to declare a default ordering for any language that does not explicitly declare an ordering.
orderingComma delimited list of provider names
Add a word to personal word list of the given dictionary.
Add a word to the given dictionary. It will be added only for the active spell-checking session.
If the word is correctly spelled return TRUE, otherwise return FALSE
Example 1. A enchant_dict_describe() example Check if a dictionary exists using enchant_broker_dict_exists() and show the detail of it.
The above example will output something similar to:
|
Returns the last error of the current spelling-session
Tells whether or not a word already exists in the current session.
If the word is correctly spelled return TRUE, otherwise return FALSE, if suggestions variable is provided, fill it with spelling alternatives.
dictDictionary resource
wordThe word to check
suggestionsIf the word is not correctly spelled, this variable will contain an array of suggestions.
Example 1. A enchant_dict_quick_check() example
The above example will output something similar to:
|
Add a correction for 'mis' using 'cor'. Notes that you replaced @mis with @cor, so it's possibly more likely that future occurrences of @mis will be replaced with @cor. So it might bump @cor up in the suggestion list.
(PECL)
enchant_dict_suggest -- Will return a list of values if any of those pre-conditions are not met.
Example 1. A enchant_dict_suggest() example
|
These are functions dealing with error handling and logging. They allow you to define your own error handling rules, as well as modify the way the errors can be logged. This allows you to change and enhance error reporting to suit your needs.
With the logging functions, you can send messages directly to other machines, to an email (or email to pager gateway!), to system logs, etc., so you can selectively log and monitor the most important parts of your applications and websites.
The error reporting functions allow you to customize what level and kind of error feedback is given, ranging from simple notices to customized functions returned during errors.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Errors and Logging Configuration Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| error_reporting | NULL | PHP_INI_ALL | |
| display_errors | "1" | PHP_INI_ALL | |
| display_startup_errors | "0" | PHP_INI_ALL | Available since PHP 4.0.3. |
| log_errors | "0" | PHP_INI_ALL | |
| log_errors_max_len | "1024" | PHP_INI_ALL | Available since PHP 4.3.0. |
| ignore_repeated_errors | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
| ignore_repeated_source | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
| report_memleaks | "1" | PHP_INI_ALL | Available since PHP 4.3.0. |
| track_errors | "0" | PHP_INI_ALL | |
| html_errors | "1" | PHP_INI_ALL | PHP_INI_SYSTEM in PHP <= 4.2.3. Available since PHP 4.0.2. |
| docref_root | "" | PHP_INI_ALL | Available since PHP 4.3.0. |
| docref_ext | "" | PHP_INI_ALL | Available since PHP 4.3.2. |
| error_prepend_string | NULL | PHP_INI_ALL | |
| error_append_string | NULL | PHP_INI_ALL | |
| error_log | NULL | PHP_INI_ALL | |
| warn_plus_overloading | NULL | PHP_INI?? |
Here's a short explanation of the configuration directives.
error_reporting
integerSet the error reporting level. The parameter is either an integer representing a bit field, or named constants. The error_reporting levels and constants are described in Predefined Constants, and in php.ini. To set at runtime, use the error_reporting() function. See also the display_errors directive.
In PHP 4 and PHP 5 the default value is E_ALL & ~E_NOTICE. This setting does not show E_NOTICE level errors. You may want to show them during development.
Note: Enabling E_NOTICE during development has some benefits. For debugging purposes: NOTICE messages will warn you about possible bugs in your code. For example, use of unassigned values is warned. It is extremely useful to find typos and to save time for debugging. NOTICE messages will warn you about bad style. For example, $arr[item] is better to be written as $arr['item'] since PHP tries to treat "item" as constant. If it is not a constant, PHP assumes it is a string index for the array.
Note: In PHP 5 a new error level E_STRICT is available. As E_STRICT is not included within E_ALL you have to explicitly enable this kind of error level. Enabling E_STRICT during development has some benefits. STRICT messages will help you to use the latest and greatest suggested method of coding, for example warn you about using deprecated functions.
PHP Constants outside of PHP: Using PHP Constants outside of PHP, like in httpd.conf, will have no useful meaning so in such cases the integer values are required. And since error levels will be added over time, the maximum value (for E_ALL) will likely change. So in place of E_ALL consider using a larger value to cover all bit fields from now and well into the future, a numeric value like 2147483647.
In PHP 3, the default setting is (E_ERROR | E_WARNING | E_PARSE), meaning the same thing. Note, however, that since constants are not supported in PHP 3's php3.ini, the error_reporting setting there must be numeric; hence, it is 7.
display_errors
booleanThis determines whether errors should be printed to the screen as part of the output or if they should be hidden from the user.
Note: This is a feature to support your development and should never be used on production systems (e.g. systems connected to the internet).
Note: Although display_errors may be set at runtime (with ini_set()), it won't have any affect if the script has fatal errors. This is because the desired runtime action does not get executed.
display_startup_errors
booleanEven when display_errors is on, errors that occur during PHP's startup sequence are not displayed. It's strongly recommended to keep display_startup_errors off, except for debugging.
log_errors
booleanTells whether script error messages should be logged to the server's error log or error_log. This option is thus server-specific.
Note: You're strongly advised to use error logging in place of error displaying on production web sites.
log_errors_max_len
integerSet the maximum length of log_errors in bytes. In error_log information about the source is added. The default is 1024 and 0 allows to not apply any maximum length at all. This length is applied to logged errors, displayed errors and also to $php_errormsg.
When an integer is used, the value is measured in bytes. You may also use shorthand notation as described in this FAQ.
ignore_repeated_errors
booleanDo not log repeated messages. Repeated errors must occur in the same file on the same line until ignore_repeated_source is set true.
ignore_repeated_source
booleanIgnore source of message when ignoring repeated messages. When this setting is On you will not log errors with repeated messages from different files or sourcelines.
report_memleaks
booleanIf this parameter is set to Off, then memory leaks will not be shown (on stdout or in the log). This has only effect in a debug compile, and if error_reporting includes E_WARNING in the allowed list
track_errors
booleanIf enabled, the last error message will always be present in the variable $php_errormsg.
html_errors
booleanTurn off HTML tags in error messages. The new format for HTML errors produces clickable messages that direct the user to a page describing the error or function in causing the error. These references are affected by docref_root and docref_ext.
docref_root
stringThe new error format contains a reference to a page describing the error or function causing the error. In case of manual pages you can download the manual in your language and set this ini directive to the URL of your local copy. If your local copy of the manual can be reached by '/manual/' you can simply use docref_root=/manual/. Additional you have to set docref_ext to match the fileextensions of your copy docref_ext=.html. It is possible to use external references. For example you can use docref_root=http://manual/en/ or docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"
Most of the time you want the docref_root value to end with a slash '/'. But see the second example above which does not have nor need it.
Note: This is a feature to support your development since it makes it easy to lookup a function description. However it should never be used on production systems (e.g. systems connected to the internet).
docref_ext
stringSee docref_root.
Note: The value of docref_ext must begin with a dot '.'.
error_prepend_string
stringString to output before an error message.
error_append_string
stringString to output after an error message.
error_log
stringName of the file where script errors should be logged. The file should be writable by the web server's user. If the special value syslog is used, the errors are sent to the system logger instead. On Unix, this means syslog(3) and on Windows NT it means the event log. The system logger is not supported on Windows 95. See also: syslog(). If this directive is not set, errors are sent to the SAPI error logger. For example, it is an error log in Apache or stderr in CLI.
warn_plus_overloading
booleanIf enabled, this option makes PHP output a warning when the plus (+) operator is used on strings. This is to make it easier to find scripts that need to be rewritten to using the string concatenator instead (.). This option doesn't exist as of PHP 4.
The constants below are always available as part of the PHP core.
Note: You may use these constant names in php.ini but not outside of PHP, like in httpd.conf, where you'd use the bitmask values instead.
Table 2. Errors and Logging
| Value | Constant | Description | Note |
|---|---|---|---|
| 1 | E_ERROR (integer) | Fatal run-time errors. These indicate errors that can not be recovered from, such as a memory allocation problem. Execution of the script is halted. | |
| 2 | E_WARNING (integer) | Run-time warnings (non-fatal errors). Execution of the script is not halted. | |
| 4 | E_PARSE (integer) | Compile-time parse errors. Parse errors should only be generated by the parser. | |
| 8 | E_NOTICE (integer) | Run-time notices. Indicate that the script encountered something that could indicate an error, but could also happen in the normal course of running a script. | |
| 16 | E_CORE_ERROR (integer) | Fatal errors that occur during PHP's initial startup. This is like an E_ERROR, except it is generated by the core of PHP. | since PHP 4 |
| 32 | E_CORE_WARNING (integer) | Warnings (non-fatal errors) that occur during PHP's initial startup. This is like an E_WARNING, except it is generated by the core of PHP. | since PHP 4 |
| 64 | E_COMPILE_ERROR (integer) | Fatal compile-time errors. This is like an E_ERROR, except it is generated by the Zend Scripting Engine. | since PHP 4 |
| 128 | E_COMPILE_WARNING (integer) | Compile-time warnings (non-fatal errors). This is like an E_WARNING, except it is generated by the Zend Scripting Engine. | since PHP 4 |
| 256 | E_USER_ERROR (integer) | User-generated error message. This is like an E_ERROR, except it is generated in PHP code by using the PHP function trigger_error(). | since PHP 4 |
| 512 | E_USER_WARNING (integer) | User-generated warning message. This is like an E_WARNING, except it is generated in PHP code by using the PHP function trigger_error(). | since PHP 4 |
| 1024 | E_USER_NOTICE (integer) | User-generated notice message. This is like an E_NOTICE, except it is generated in PHP code by using the PHP function trigger_error(). | since PHP 4 |
| 2048 | E_STRICT (integer) | Run-time notices. Enable to have PHP suggest changes to your code which will ensure the best interoperability and forward compatibility of your code. | since PHP 5 |
| 4096 | E_RECOVERABLE_ERROR (integer) | Catchable fatal error. It indicates that a probably dangerous error occured, but did not leave the Engine in an unstable state. If the error is not caught by a user defined handle (see also set_error_handler()), the application aborts as it was an E_ERROR. | since PHP 5.2.0 |
| 8191 | E_ALL (integer) | All errors and warnings, as supported, except of level E_STRICT in PHP < 6. | 6143 in PHP 5.2.x and 2047 previously |
The above values (either numerical or symbolic) are used to build up a bitmask that specifies which errors to report. You can use the bitwise operators to combine these values or mask out certain types of errors. Note that only '|', '~', '!', '^' and '&' will be understood within php.ini, however, and that no bitwise operators will be understood within php3.ini.
Below we can see an example of using the error handling capabilities in PHP. We define an error handling function which logs the information into a file (using an XML format), and e-mails the developer in case a critical error in the logic happens.
Example 1. Using error handling in a script
|
Returns an associative array. The possible returned elements are as follows:
Table 1. Possible returned elements from debug_backtrace()
| Name | Type | Description |
|---|---|---|
| function | string | The current function name. See also __FUNCTION__. |
| line | integer | The current line number. See also __LINE__. |
| file | string | The current file name. See also __FILE__. |
| class | string | The current class name. See also __CLASS__ |
| object | object | The current object. |
| type | string | The current call type. If a method call, "->" is returned. If a static method call, "::" is returned. If a function call, nothing is returned. |
| args | array | If inside a function, this lists the functions arguments. If inside an included file, this lists the included file name(s). |
Example 1. debug_backtrace() example
Results similar to the following when executing /tmp/b.php:
|
debug_print_backtrace() prints a PHP backtrace. It prints the function calls, included/required files and eval()ed stuff.
Example 1. debug_print_backtrace() example
The above example will output something similar to:
|
Returns an associative array describing the last error with keys "type", "message", "file" and "line". Returns NULL if there hasn't been an error yet.
Sends an error message to the web server's error log, a TCP port or to a file.
messageThe error message that should be logged.
message_typeSays where the error should go. The possible message types are as follows:
Table 1. error_log() log types
| 0 |
message is sent to PHP's system logger, using
the Operating System's system logging mechanism or a file, depending
on what the error_log
configuration directive is set to. This is the default option.
|
| 1 |
message is sent by email to the address in
the destination parameter. This is the only
message type where the fourth parameter,
extra_headers is used.
|
| 2 |
message is sent through the PHP debugging
connection. This option is only available if remote debugging has
been enabled. In this case, the
destination parameter specifies the host name
or IP address and optionally, port number, of the socket receiving
the debug information. This option is only available in PHP 3.
|
| 3 |
message is appended to the file
destination. A newline is not automatically
added to the end of the message string.
|
destination
The destination. Its meaning depends on the
message_type parameter as described above.
extra_headers
The extra headers. It's used when the message_type
parameter is set to 1.
This message type uses the same internal function as
mail() does.
Example 1. error_log() examples
|
The error_reporting() function sets the error_reporting directive at runtime. PHP has many levels of errors, using this function sets that level for the duration (runtime) of your script.
levelThe new error_reporting level. It takes on either a bitmask, or named constants. Using named constants is strongly encouraged to ensure compatibility for future versions. As error levels are added, the range of integers increases, so older integer-based error levels will not always behave as expected.
The available error level constants are listed below. The actual meanings of these error levels are described in the predefined constants.
Table 1. error_reporting() level constants and bit values
| value | constant |
|---|---|
| 1 | E_ERROR |
| 2 | E_WARNING |
| 4 | E_PARSE |
| 8 | E_NOTICE |
| 16 | E_CORE_ERROR |
| 32 | E_CORE_WARNING |
| 64 | E_COMPILE_ERROR |
| 128 | E_COMPILE_WARNING |
| 256 | E_USER_ERROR |
| 512 | E_USER_WARNING |
| 1024 | E_USER_NOTICE |
| 6143 | E_ALL |
| 2048 | E_STRICT |
| 4096 | E_RECOVERABLE_ERROR |
Example 1. error_reporting() examples
|
| Warning |
Most of E_STRICT errors are evaluated at the compile time thus such errors are not reported in the file where error_reporting is enhanced to include E_STRICT errors (and vice versa). |
Used after changing the error handler function using set_error_handler(), to revert to the previous error handler (which could be the built-in or a user defined function).
Example 1. restore_error_handler() example Decide if unserialize() caused an error, then restore the original error handler.
The above example will output:
|
Used after changing the exception handler function using set_exception_handler(), to revert to the previous exception handler (which could be the built-in or a user defined function).
Sets a user function (error_handler) to handle
errors in a script.
This function can be used for defining your own way of handling errors during runtime, for example in applications in which you need to do cleanup of data/files when a critical error happens, or when you need to trigger an error under certain conditions (using trigger_error()).
It is important to remember that the standard PHP error handler is completely bypassed. error_reporting() settings will have no effect and your error handler will be called regardless - however you are still able to read the current value of error_reporting and act appropriately. Of particular note is that this value will be 0 if the statement that caused the error was prepended by the @ error-control operator.
Also note that it is your responsibility to die() if necessary. If the error-handler function returns, script execution will continue with the next statement after the one that caused an error.
The following error types cannot be handled with a user defined function: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, and most of E_STRICT raised in the file where set_error_handler() is called.
If errors occur before the script is executed (e.g. on file uploads) the custom error handler cannot be called since it is not registered at that time.
error_handlerThe user function needs to accept two parameters: the error code, and a string describing the error. Then there are three optional parameters that may be supplied: the filename in which the error occurred, the line number in which the error occurred, and the context in which the error occurred (an array that points to the active symbol table at the point the error occurred). The function can be shown as:
handler ( int errno, string errstr [, string errfile [, int errline [, array errcontext]]] )
errno
The first parameter, errno, contains the
level of the error raised, as an integer.
errstr
The second parameter, errstr, contains the
error message, as a string.
errfile
The third parameter is optional, errfile,
which contains the filename that the error was raised in, as a string.
errline
The fourth parameter is optional, errline,
which contains the line number the error was raised at, as an integer.
errcontext
The fifth parameter is optional, errcontext,
which is an array that points to the active symbol table at the point
the error occurred. In other words, errcontext
will contain an array of every variable that existed in the scope the
error was triggered in.
User error handler must not modify error context.
error_types
Can be used to mask the triggering of the
error_handler function just like the error_reporting ini setting
controls which errors are shown. Without this mask set the
error_handler will be called for every error
regardless to the setting of the error_reporting setting.
Returns a string containing the previously defined error handler (if any), or NULL on error. If the previous handler was a class method, this function will return an indexed array with the class and the method name.
| Version | Description |
|---|---|
| 5.2.0 | The error handler must return FALSE to populate $php_errormsg. |
| 5.0.0 |
The error_types parameter was introduced.
|
| 4.3.0 |
Instead of a function name, an array containing an object reference
and a method name can also be supplied as the
error_handler.
|
| 4.0.2 |
Three optional parameters for the error_handler
user function was introduced. These are the filename, the line number,
and the context.
|
Example 1. Error handling with set_error_handler() and trigger_error() The example below shows the handling of internal exceptions by triggering errors and handling them with a user defined function:
The above example will output something similar to:
|
| error_reporting() |
| restore_error_handler() |
| trigger_error() |
| error level constants |
| information about the callback type |
Sets the default exception handler if an exception is not caught within a
try/catch block. Execution will stop after the
exception_handler is called.
exception_handlerName of the function to be called when an uncaught exception occurs. This function must be defined before calling set_exception_handler(). This handler function needs to accept one parameter, which will be the exception object that was thrown.
Returns the name of the previously defined exception handler, or NULL on error. If no previous handler was defined, NULL is also returned.
restore_exception_handler(), restore_error_handler(), error_reporting(), information about the callback type, and PHP 5 Exceptions.
Used to trigger a user error condition, it can be used by in conjunction with the built-in error handler, or with a user defined function that has been set as the new error handler (set_error_handler()).
This function is useful when you need to generate a particular response to an exception at runtime.
error_msgThe designated error message for this error. It's limited to 1024 characters in length. Any additional characters beyond 1024 will be truncated.
error_typeThe designated error type for this error. It only works with the E_USER family of constants, and will default to E_USER_NOTICE.
Example 1. trigger_error() example See set_error_handler() for a more extensive example.
|
With the exif extension you are able to work with image meta data. For example, you may use exif functions to read meta data of pictures taken from digital cameras by working with information stored in the headers of the JPEG and TIFF images.
Your PHP must be compiled in with --enable-exif. PHP does not require any additional library for the exif module. Windows users must also have the mbstring extension enabled.
To enable exif-support configure PHP with
--enable-exif
Windows users must enable both the php_mbstring.dll and php_exif.dll DLL's in php.ini. The php_mbstring.dll DLL must be loaded before the php_exif.dll DLL so adjust your php.ini accordingly.
The behaviour of these functions is affected by settings in php.ini.
Exif supports automatically conversion for Unicode and JIS character encodings of user comments when module mbstring is available. This is done by first decoding the comment using the specified characterset. The result is then encoded with another characterset which should match your HTTP output.
Table 1. Exif configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| exif.encode_unicode | "ISO-8859-15" | PHP_INI_ALL | Available since PHP 4.3.0. |
| exif.decode_unicode_motorola | "UCS-2BE" | PHP_INI_ALL | Available since PHP 4.3.0. |
| exif.decode_unicode_intel | "UCS-2LE" | PHP_INI_ALL | Available since PHP 4.3.0. |
| exif.encode_jis | "" | PHP_INI_ALL | Available since PHP 4.3.0. |
| exif.decode_jis_motorola | "JIS" | PHP_INI_ALL | Available since PHP 4.3.0. |
| exif.decode_jis_intel | "JIS" | PHP_INI_ALL | Available since PHP 4.3.0. |
Here's a short explanation of the configuration directives.
exif.encode_unicode
stringexif.encode_unicode defines the characterset UNICODE user comments are handled. This defaults to ISO-8859-15 which should work for most non Asian countries. The setting can be empty or must be an encoding supported by mbstring. If it is empty the current internal encoding of mbstring is used.
exif.decode_unicode_motorola
stringexif.decode_unicode_motorola defines the image internal characterset for Unicode encoded user comments if image is in motorola byte order (big-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is UCS-2BE.
exif.decode_unicode_intel
stringexif.decode_unicode_intel defines the image internal characterset for Unicode encoded user comments if image is in intel byte order (little-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is UCS-2LE.
exif.encode_jis
stringexif.encode_jis defines the characterset JIS user comments are handled. This defaults to an empty value which forces the functions to use the current internal encoding of mbstring.
exif.decode_jis_motorola
stringexif.decode_jis_motorola defines the image internal characterset for JIS encoded user comments if image is in motorola byte order (big-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is JIS.
exif.decode_jis_intel
stringexif.decode_jis_intel defines the image internal characterset for JIS encoded user comments if image is in intel byte order (little-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is JIS.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The exif_imagetype() lists several related built-in constants.
exif_imagetype() reads the first bytes of an image and checks its signature.
exif_imagetype() can be used to avoid calls to other
exif functions with unsupported file types
or in conjunction with $_SERVER['HTTP_ACCEPT'] to check
whether or not the viewer is able to see a specific image in the browser.
When a correct signature is found, the appropriate constant value will be returned otherwise the return value is FALSE. The return value is the same value that getimagesize() returns in index 2 but exif_imagetype() is much faster.
The following constants are defined, and represent possible exif_imagetype() return values:
Table 1. Imagetype Constants
| Value | Constant |
|---|---|
| 1 | IMAGETYPE_GIF |
| 2 | IMAGETYPE_JPEG |
| 3 | IMAGETYPE_PNG |
| 4 | IMAGETYPE_SWF |
| 5 | IMAGETYPE_PSD |
| 6 | IMAGETYPE_BMP |
| 7 | IMAGETYPE_TIFF_II (intel byte order) |
| 8 | IMAGETYPE_TIFF_MM (motorola byte order) |
| 9 | IMAGETYPE_JPC |
| 10 | IMAGETYPE_JP2 |
| 11 | IMAGETYPE_JPX |
| 12 | IMAGETYPE_JB2 |
| 13 | IMAGETYPE_SWC |
| 14 | IMAGETYPE_IFF |
| 15 | IMAGETYPE_WBMP |
| 16 | IMAGETYPE_XBM |
exif_read_data() reads the EXIF headers from a JPEG or TIFF image file. This way you can read meta data generated by digital cameras.
Exif headers tend to be present in JPEG/TIFF images generated by digital cameras, but unfortunately each digital camera maker has a different idea of how to actually tag their images, so you can't always rely on a specific Exif header being present.
Height and Width are computed the same way getimagesize() does so their values must not be part of any header returned. Also, html is a height/width text string to be used inside normal HTML.
When an Exif header contains a Copyright note, this itself can contain two values. As the solution is inconsistent in the Exif 2.10 standard, the COMPUTED section will return both entries Copyright.Photographer and Copyright.Editor while the IFD0 sections contains the byte array with the NULL character that splits both entries. Or just the first entry if the datatype was wrong (normal behaviour of Exif). The COMPUTED will also contain the entry Copyright which is either the original copyright string, or a comma separated list of the photo and editor copyright.
The tag UserComment has the same problem as the Copyright tag. It can store two values. First the encoding used, and second the value itself. If so the IFD section only contains the encoding or a byte array. The COMPUTED section will store both in the entries UserCommentEncoding and UserComment. The entry UserComment is available in both cases so it should be used in preference to the value in IFD0 section.
exif_read_data() also validates EXIF data tags according to the EXIF specification (http://exif.org/Exif2-2.PDF, page 20).
Note: Windows ME/XP can both wipe the Exif headers when connecting to a camera. More information available at http://www.canon.co.jp/Imaging/NOTICE/011214-e.html.
filenameThe name of the image file being read. This cannot be an URL.
sectionsIs a comma separated list of sections that need to be present in file to produce a result array. If none of the requested sections could be found the return value is FALSE.
| FILE | FileName, FileSize, FileDateTime, SectionsFound |
| COMPUTED | html, Width, Height, IsColor, and more if available. Height and Width are computed the same way getimagesize() does so their values must not be part of any header returned. Also, html is a height/width text string to be used inside normal HTML. |
| ANY_TAG | Any information that has a Tag e.g. IFD0, EXIF, ... |
| IFD0 | All tagged data of IFD0. In normal imagefiles this contains image size and so forth. |
| THUMBNAIL | A file is supposed to contain a thumbnail if it has a second IFD. All tagged information about the embedded thumbnail is stored in this section. |
| COMMENT | Comment headers of JPEG images. |
| EXIF | The EXIF section is a sub section of IFD0. It contains more detailed information about an image. Most of these entries are digital camera related. |
arrays
Specifies whether or not each section becomes an array. The
sections COMPUTED,
THUMBNAIL, and COMMENT
always become arrays as they may contain values whose names conflict
with other sections.
thumbnailWhen set to TRUE the thumbnail itself is read. Otherwise, only the tagged data is read.
It returns an associative array where the array indexes are the header names and the array values are the values associated with those headers. If no data can be returned, exif_read_data() will return FALSE.
| Version | Description |
|---|---|
| 4.3.0 | Can read all embedded IFD data including arrays (returned as such). Also the size of an embedded thumbnail is returned in a THUMBNAIL subarray, and can return thumbnails in TIFF format. Also, there is no longer a maximum length for returned values (not until the memory limit has been reached) |
| 4.3.0 | If PHP has mbstring support, the user comment can automatically change encoding. Also, if the user comment uses Unicode or JIS encoding this encoding will automatically be changed according to the exif ini settings in php.ini |
| 4.3.0 | If the image contains any IFD0 data then COMPUTED contains the entry ByteOrderMotorola which is 0 for little-endian (intel) and 1 for big-endian (motorola) byte order. Also, COMPUTED and UserComment no longer only contain the first copyright entry if the datatype was wrong. |
Example 1. exif_read_data() example
The first call fails because the image has no header information. The above example will output something similar to:
|
| Warning |
This function is currently not documented; only the argument list is available. |
exif_thumbnail() reads the embedded thumbnail of a TIFF or JPEG image.
If you want to deliver thumbnails through this function, you should send the mimetype information using the header() function.
It is possible that exif_thumbnail() cannot create an
image but can determine its size. In this case, the return value is
FALSE but width and height
are set.
filenameThe name of the image file being read. This image contains an embedded thumbnail.
widthThe return width of the returned thumbnail.
heightThe returned height of the returned thumbnail.
imagetypeThe returned image type of the returned thumbnail. This is either TIFF or JPEG.
Example 1. exif_thumbnail() example
|
This extension allows to interact with processes through PTY. You may consider using the expect:// wrapper with the filesystem functions which provide a simpler and more intuitive interface.
This module uses the functions of the expect library. You need libexpect version >= 5.43.0.
This PECL extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/expect.
In PHP 4 this PECL extensions
source can be found in the ext/ directory within the
PHP source or at the PECL link above.
In order to use these functions you must compile PHP with expect support
by using the --with-expect[=DIR]
configure option.
Windows users will enable php_expect.dll inside of php.ini in order to use these functions. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
The behaviour of these functions is affected by settings in php.ini.
In order to configure expect extension, there are configuration options in the configuration file php.ini.
Table 1. Expect Configure Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| expect.timeout | "10" | PHP_INI_ALL | |
| expect.loguser | "1" | PHP_INI_ALL | |
| expect.logfile | "" | PHP_INI_ALL |
Here's a short explanation of the configuration directives.
expect.timeout
integerThe timeout period for waiting for the data, when using the expect_expectl() function.
A value of "-1" disables a timeout from occurring.
Note: A value of "0" causes the expect_expectl() function to return immediately.
expect.loguser
booleanWhether expect should send any output from the spawned process to stdout. Since interactive programs typically echo their input, this usually suffices to show both sides of the conversation.
expect.logfile
stringName of the file, where the output from the spawned process will be written. If this file doesn't exist, it will be created.
Note: If this configuration is not empty, the output is written regardless of the value of expect.loguser.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Indicates that the pattern is a glob-style string pattern.
Indicates that the pattern is an exact string.
Indicates that the pattern is a regexp-style string pattern.
Value, returned by expect_expectl(), when EOF is reached.
Value, returned by expect_expectl() upon timeout of seconds, specified in value of expect.timeout
Value, returned by expect_expectl() if no pattern have been matched.
This example connects to the remote host via SSH, and prints the remote uptime.
Example 1. Expect Usage Example
|
(no version information, might be only in CVS)
expect_expectl -- Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seenWaits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen.
If match is provided, then it is filled with the result of search.
The matched string can be found in match[0].
The match substrings (according to the parentheses) in the original pattern can be found
in match[1], match[2], and so
on, up to match[9] (the limitation of libexpect).
expectAn Expect stream, previously opened with expect_popen().
casesAn array of expect cases. Each expect case is an indexed array, as described in the following table:
Table 1. Expect Case Array
| Index Key | Value Type | Description | Is Mandatory | Default Value |
|---|---|---|---|---|
| 0 | string | pattern, that will be matched against the output from the stream | yes | |
| 1 | mixed | value, that will be returned by this function, if the pattern matches | yes | |
| 2 | integer | pattern type, one of: EXP_GLOB, EXP_EXACT or EXP_REGEXP | no | EXP_GLOB |
Returns value associated with the pattern that was matched.
On failure this function returns: EXP_EOF, EXP_TIMEOUT or EXP_FULLBUFFER
Example 1. expect_expectl() example
|
(no version information, might be only in CVS)
expect_popen -- Execute command via Bourne shell, and open the PTY stream to the processExecute command via Bourne shell, and open the PTY stream to the process.
Returns an open PTY stream to the process'es stdio, stdout and stderr.
On failure this function returns FALSE.
FAM monitors files and directories, notifying interested applications of changes. More information about FAM is available at http://oss.sgi.com/projects/fam/.
A PHP script may specify a list of files for FAM to monitor using the functions provided by this extension.
The FAM process is started when the first connection from any application to it is opened. It exits after all connections to it have been closed.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.1.0.
Note: This extension is not available on Windows platforms.
This extension uses the functions of the FAM library, developed by SGI. Therefore you have to download and install the FAM library.
To use PHP's FAM support you must compile PHP --with-fam[=DIR] where DIR is the
location of the directory containing the lib and include
directories.
There are two resource types used in the FAM module. The first one is the connection to the FAM service returned by fam_open(), the second a monitoring resource returned by the fam_monitor_XXX functions.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Table 1. FAM event constants
| Constant | Description |
|---|---|
| FAMChanged (integer) | Some value which can be obtained with fstat(1) changed for a file or directory. |
| FAMDeleted (integer) | A file or directory was deleted or renamed. |
| FAMStartExecuting (integer) | An executable file started executing. |
| FAMStopExecuting (integer) | An executable file that was running finished. |
| FAMCreated (integer) | A file was created in a directory. |
| FAMMoved (integer) | This event never occurs. |
| FAMAcknowledge (integer) | An event in response to fam_cancel_monitor(). |
| FAMExists (integer) | An event upon request to monitor a file or directory. When a directory is monitored, an event for that directory and every file contained in that directory is issued. |
| FAMEndExist (integer) | Event after the last FAMEExists event. |
Terminates monitoring on a resource.
In addition an FAMAcknowledge event occurs.
famA resource representing a connection to the FAM service returned by fam_open()
fam_monitorA resource returned by one of the fam_monitor_XXX functions
Requests monitoring for a collection of files within a directory.
A FAM event will be generated whenever the status of the files change. The possible event codes are described in detail in the constants part of this section.
famA resource representing a connection to the FAM service returned by fam_open()
dirnameDirectory path to the monitored files
depth
The maximum search depth starting from this
directory
mask
A shell pattern mask restricting the file names
to look for
| fam_monitor_file() |
| fam_monitor_directory() |
| fam_cancel_monitor() |
| fam_suspend_monitor() |
| fam_resume_monitor() |
Requests monitoring for a directory and all contained files.
A FAM event will be generated whenever the status of the directory (i.e. the result of function stat() on that directory) or its content (i.e. the results of readdir()) changes.
The possible event codes are described in detail in the constants part of this section.
famA resource representing a connection to the FAM service returned by fam_open()
dirnamePath to the monitored directory
| fam_monitor_file() |
| fam_monitor_collection() |
| fam_cancel_monitor() |
| fam_suspend_monitor() |
| fam_resume_monitor() |
Requests monitoring for a single file. A FAM event will be generated whenever the file status changes (i.e. the result of function stat() on that file).
The possible event codes are described in detail in the constants part of this section.
famA resource representing a connection to the FAM service returned by fam_open()
filenamePath to the monitored file
| fam_monitor_directory() |
| fam_monitor_collection() |
| fam_cancel_monitor() |
| fam_suspend_monitor() |
| fam_resume_monitor() |
Returns the next pending FAM event.
The function will block until an event is available which can be checked for using fam_pending().
Returns an array that contains a FAM event code in the 'code' element, the path of the file this event applies to in the 'filename' element and optionally a hostname in the 'hostname' element.
The possible event codes are described in detail in the constants part of this section.
Returns a resource representing a connection to the FAM service on success or FALSE on errors.
Returns non-zero if events are available to be fetched using fam_next_event(), zero otherwise.
Resumes monitoring of a resource previously suspended using fam_suspend_monitor().
famA resource representing a connection to the FAM service returned by fam_open()
fam_monitorA resource returned by one of the fam_monitor_XXX functions
fam_suspend_monitor() temporarily suspend monitoring of a resource.
Monitoring can later be continued using fam_resume_monitor() without the need of requesting a complete new monitor.
famA resource representing a connection to the FAM service returned by fam_open()
fam_monitorA resource returned by one of the fam_monitor_XXX functions
Forms Data Format (FDF) is a format for handling forms within PDF documents. You should read the documentation at http://partners.adobe.com/asn/acrobat/forms.jsp for more information on what FDF is and how it is used in general.
The general idea of FDF is similar to HTML forms. The difference is basically the format how data is transmitted to the server when the submit button is pressed (this is actually the Form Data Format) and the format of the form itself (which is the Portable Document Format, PDF). Processing the FDF data is one of the features provided by the fdf functions. But there is more. One may as well take an existing PDF form and populated the input fields with data without modifying the form itself. In such a case one would create a FDF document (fdf_create()) set the values of each input field (fdf_set_value()) and associate it with a PDF form (fdf_set_file()). Finally it has to be sent to the browser with MimeType application/vnd.fdf. The Acrobat reader plugin of your browser recognizes the MimeType, reads the associated PDF form and fills in the data from the FDF document.
If you look at an FDF-document with a text editor you will find a catalogue object with the name FDF. Such an object may contain a number of entries like Fields, F, Status etc.. The most commonly used entries are Fields which points to a list of input fields, and F which contains the filename of the PDF-document this data belongs to. Those entries are referred to in the FDF documentation as /F-Key or /Status-Key. Modifying this entries is done by functions like fdf_set_file() and fdf_set_status(). Fields are modified with fdf_set_value(), fdf_set_opt() etc..
You need the FDF toolkit SDK available from http://partners.adobe.com/asn/acrobat/forms.jsp. As of PHP 4.3.0 you need at least SDK version 5.0. The FDF toolkit library is available in binary form only, platforms supported by Adobe are Win32, Linux, Solaris and AIX.
You must compile PHP with
--with-fdftk[=DIR].
Note: If you run into problems configuring PHP with fdftk support, check whether the header file fdftk.h and the library libfdftk.so are at the right place. The configure script supports both the directory structure of the FDF SDK distribution and the usual DIR/include / DIR/lib layout, so you can point it either directly to the unpacked distribution directory or put the header file and the appropriate library for your platform into e.g. /usr/local/include and /usr/local/lib and configure with
--with-fdftk=/usr/local.
Note to Win32 Users: In order for this extension to work, there are DLL files that must be available to the Windows system PATH. See the FAQ titled "How do I add my PHP directory to the PATH on Windows" for information on how to do this. Although copying DLL files from the PHP folder into the Windows system directory also works (because the system directory is by default in the systems PATH), it is not recommended. This extension requires the following files to be in the PATH: fdftk.dll
Most fdf functions require a fdf resource
as their first parameter. A fdf resource
is a handle to an opened fdf file. fdf
resources may be obtained using fdf_create(),
fdf_open() and fdf_open_string().
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The following examples shows just the evaluation of form data.
Example 1. Evaluating a FDF document
|
Adds a script to the FDF, which Acrobat then adds to the doc-level scripts of a document, once the FDF is imported into it.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
script_nameThe script name.
script_codeThe script code. It is strongly suggested to use \r for linebreaks within the script code.
Example 1. Adding JavaScript code to a FDF
will create a FDF like this:
|
| Warning |
This function is currently not documented; only the argument list is available. |
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
Creates a new FDF document.
This function is needed if one would like to populate input fields in a PDF document with data.
Example 1. Populating a PDF document
|
| Warning |
This function is currently not documented; only the argument list is available. |
Gets the error code set by the last FDF function call.
A textual description of the error may be obtained using with fdf_error().
Gets a textual description for the FDF error code given in
error_code.
error_codeAn error code obtained with fdf_errno(). If not provided, this function uses the internal error code set by the last operation.
Gets the appearance of a field (i.e. the value of
the /AP key) and stores it in a file.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
field
faceThe possible values are FDFNormalAP, FDFRolloverAP and FDFDownAP.
filenameThe appearance will be stored in this parameter.
Extracts a file uploaded by means of the "file selection" field
fieldname and stores it under
savepath.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldname
savepathMay be the name of a plain file or an existing directory in which the file is to be created under its original name. Any existing file under the same name will be overwritten.
Note: There seems to be no other way to find out the original filename but to store the file using a directory as
savepathand check for the basename it was stored under.
The returned array contains the following fields:
path - path were the file got stored
size - size of the stored file in bytes
type - mimetype if given in the FDF
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
Returns the encoding as a string. An empty string is returned if the default PDFDocEncoding/Unicode scheme is used.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
Gets the value for the requested field.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string.
whichElements of an array field can be retrieved by passing this optional parameter, starting at zero. For non-array fields, this parameter will be ignored.
Return the FDF version for the given document, or the toolkit API version number if no parameter is given.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
Returns the version as a string. For the current FDF toolkit 5.0 the API version number is 5.0 and the document version number is either 1.2, 1.3 or 1.4.
This is a convenience function to set appropriate HTTP headers for FDF output. It sets the Content-type: to application/vnd.fdf.
Gets the name of the field after the given field. This name can be used with several functions.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string. If not given, the first field will be assumed.
Reads form data from a string.
You can use fdf_open_string() together with
$HTTP_FDF_DATA to process FDF form input from a remote
client.
fdf_dataThe data as returned from a PDF form or created using fdf_create() and fdf_save_string().
Opens a file with form data.
You can also use fdf_open_string() to process the results of a PDF form POST request.
filenamePath to the FDF file. This file must contain the data as returned from a PDF form or created using fdf_create() and fdf_save().
| Warning |
This function is currently not documented; only the argument list is available. |
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
Example 1. Retrieving FDF as a string
The above example will output:
|
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
filenameIf provided, the resulting FDF will be written in this parameter. Otherwise, this function will write the FDF to the default PHP output stream.
Sets the appearance of a field (i.e. the value of the /AP key).
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
field_name
faceThe possible values FDFNormalAP, FDFRolloverAP and FDFDownAP.
filename
page_number
Sets the character encoding for the FDF document.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
encodingThe encoding name. The following values are supported: "Shift-JIS", "UHC", "GBK" and "BigFive".
An empty string resets the encoding to the default PDFDocEncoding/Unicode scheme.
Selects a different PDF document to display the form results in then the form it originated from.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
urlShould be given as an absolute URL.
target_frameUse this parameter to specify the frame in which the document will be displayed. You can also set the default value for this parameter using fdf_set_target_frame().
Example 1. Passing FDF data to a second form
|
Sets certain flags of the given field.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string.
whichFlags
newFlags
Sets a javascript action for the given field.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string.
trigger
script
(PHP 4 >= 4.3.0, PHP 5)
fdf_set_on_import_javascript -- Adds javascript code to be executed when Acrobat opens the FDF| Warning |
This function is currently not documented; only the argument list is available. |
Sets options of the given field.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string.
element
str1
str2
Sets the value of the /STATUS key. When a client receives a FDF with a status set it will present the value in an alert box.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
status
Sets a submit form action for the given field.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string.
trigger
script
flags
Sets the target frame to display a result PDF defined with fdf_save_file() in.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
frame_nameThe frame name, as a string.
Sets the value for the given field.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
fieldnameName of the FDF field, as a string.
valueThis parameter will be stored as a string unless it is an array. In this case all array elements will be stored as a value array.
isNameNote: In older versions of the FDF toolkit last parameter determined if the field value was to be converted to a PDF Name (= 1) or set to a PDF String (= 0).
The value is no longer used in the current toolkit version 5.0. For compatibility reasons it is still supported as an optional parameter beginning with PHP 4.3, but ignored internally.
Sets the FDF version for the given document.
Some features supported by this extension are only available in newer FDF versions.
fdf_documentThe FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
versionThe version number. For the current FDF toolkit 5.0, this may be either 1.2, 1.3 or 1.4.
The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/fileinfo
There is one resource used in Fileinfo extension: a magic database descriptor returned by finfo_open().
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
No special handling.
Follow symlinks.
Return a mime string, instead of a textual description.
Decompress compressed files.
Look at the contents of blocks or character special devices.
Return all matches, not just the first.
If possible preserve the original access time.
Don't translate unprintable characters to a \ooo octal representation.
This function is used to get information about binary data in a string.
finfoFileinfo resource returned by finfo_open().
stringContent of a file to be checked.
optionsOne or disjunction of more Fileinfo constants.
context
__destruct();
}This function closes the resource opened by finfo_open().
This function is used to get information about a file.
finfoFileinfo resource returned by finfo_open().
file_nameName of a file to be checked.
optionsOne or disjunction of more Fileinfo constants.
contextFor a description of contexts, refer to Reference CLX, Stream Functions.
Returns a textual description of the contents of the
filename argument, or FALSE if an error occurred.
Example 1. A finfo_file() example
The above example will output something similar to:
|
(PECL)
finfo_open(no version information, might be only in CVS)
finfo->__construct() -- Create a new fileinfo resourceProcedural style
resource finfo_open ( [int options [, string arg]] )Object oriented style (constructor):
class finfo {This function opens a magic database and returns its resource.
optionsOne or disjunction of more Fileinfo constants.
magic_fileName of a magic database file, usually something like /path/to/magic.mime. If not specified, the MAGIC environment variable is used. If this variable is not set either, /usr/share/misc/magic is used by default. A .mime and/or .mgc suffix is added if needed.
Example 1. Object oriented style
|
Example 2. Procedural style
|
The above example will output:
text/plain |
This function sets various Fileinfo options. Options can be set also directly in finfo_open() or other Fileinfo functions.
finfoFileinfo resource returned by finfo_open().
optionsOne or disjunction of more Fileinfo constants.
These functions allow read-only access to data stored in filePro databases.
filePro is a registered trademark of fP Technologies, Inc. You can find more information about filePro at http://www.fptech.com/.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.2.0.
filePro support in PHP is not enabled by default. To
enable the bundled read-only filePro support you need
to use the--enable-filepro configuration
option when compiling PHP.
Returns the number of fields (columns) in the opened filePro database.
Returns the name of the field corresponding to
field_number.
Returns the edit type of the field corresponding to field_number.
Returns the width of the field corresponding to field_number.
Returns the data from the specified location in the database.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
row_numberThe row number. Must be between zero and the total number of rows minus one (0..filepro_rowcount() - 1)
field_numberThe field number. Accepts values between zero and the total number of fields minus one (0..filepro_fieldcount() - 1)
Returns the number of rows in the opened filePro database.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
This reads and verifies the map file, storing the field count and info.
No locking is done, so you should avoid modifying your filePro database while it may be opened in PHP.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
No external libraries are needed to build this extension, but if you want PHP to support LFS (large files) on Linux, then you need to have a recent glibc and you need compile PHP with the following compiler flags: -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Filesystem and Streams Configuration Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| allow_url_fopen | "1" | PHP_INI_SYSTEM | PHP_INI_ALL in PHP <= 4.3.4. Available since PHP 4.0.4. |
| allow_url_include | "0" | PHP_INI_SYSTEM | Available since PHP 5.2.0. |
| user_agent | NULL | PHP_INI_ALL | Available since PHP 4.3.0. |
| default_socket_timeout | "60" | PHP_INI_ALL | Available since PHP 4.3.0. |
| from | "" | PHP_INI_ALL | |
| auto_detect_line_endings | "0" | PHP_INI_ALL | Available since PHP 4.3.0. |
Here's a short explanation of the configuration directives.
allow_url_fopen
booleanThis option enables the URL-aware fopen wrappers that enable accessing URL object like files. Default wrappers are provided for the access of remote files using the ftp or http protocol, some extensions like zlib may register additional wrappers.
Note: This setting can only be set in php.ini due to security reasons.
Note: This option was introduced immediately after the release of version 4.0.3. For versions up to and including 4.0.3 you can only disable this feature at compile time by using the configuration switch
--disable-url-fopen-wrapper.
| Warning |
On Windows versions prior to PHP 4.3.0, the following functions do not support remote file accessing: include(), include_once(), require(), require_once() and the imagecreatefromXXX functions in the Reference LXV, Image Functions extension. |
allow_url_include
booleanThis option allows the use of URL-aware fopen wrappers with the following functions: include(), include_once(), require(), require_once().
Note: This setting requires allow_url_fopen to be on.
user_agent
stringDefine the user agent for PHP to send.
default_socket_timeout
integerDefault timeout (in seconds) for socket based streams.
Note: This configuration option was introduced in PHP 4.3.0
from
stringDefine the anonymous ftp password (your email address).
auto_detect_line_endings
booleanWhen turned on, PHP will examine the data read by fgets() and file() to see if it is using Unix, MS-Dos or Macintosh line-ending conventions.
This enables PHP to interoperate with Macintosh systems, but defaults to Off, as there is a very small performance penalty when detecting the EOL conventions for the first line, and also because people using carriage-returns as item separators under Unix systems would experience non-backwards-compatible behaviour.
Note: This configuration option was introduced in PHP 4.3.0
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Since PHP 5.2.0.
Since PHP 5.0.0. Search for filename in
include_path.
Since PHP 5.0.0. Strips EOL characters.
Since PHP 5.0.0. Skips empty lines.
For related functions, see also the Directory and Program Execution sections.
For a list and explanation of the various URL wrappers that can be used as remote files, see also Appendix O.
Given a string containing a path to a file, this function will
return the base name of the file.
If the filename ends in suffix this will
also be cut off.
On Windows, both slash (/) and backslash (\) are used as directory separator character. In other environments, it is the forward slash (/).
Note: The
suffixparameter was added in PHP 4.1.0.
See also dirname().
Attempts to change the group of the file filename
to group.
Only the superuser may change the group of a file arbitrarily; other users may change the group of a file to any group of which that user is a member.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
Attempts to change the mode of the file specified by
filename to that given in
mode.
Note that mode is not automatically
assumed to be an octal value, so strings (such as "g+w") will
not work properly. To ensure the expected operation,
you need to prefix mode with a zero (0):
<?php
chmod("/somedir/somefile", 755); // decimal; probably incorrect
chmod("/somedir/somefile", "u+rwx,go+rx"); // string; incorrect
chmod("/somedir/somefile", 0755); // octal; correct value of mode
?> |
The mode parameter consists of three octal
number components specifying access restrictions for the owner,
the user group in which the owner is in, and to everybody else in
this order. One component can be computed by adding up the needed
permissions for that target user base. Number 1 means that you
grant execute rights, number 2 means that you make the file
writeable, number 4 means that you make the file readable. Add
up these numbers to specify needed rights. You can also read more
about modes on Unix systems with 'man 1 chmod' and 'man 2 chmod'.
<?php
// Read and write for owner, nothing for everybody else
chmod("/somedir/somefile", 0600);
// Read and write for owner, read for everybody else
chmod("/somedir/somefile", 0644);
// Everything for owner, read and execute for others
chmod("/somedir/somefile", 0755);
// Everything for owner, read and execute for owner's group
chmod("/somedir/somefile", 0750);
?> |
Returns TRUE on success or FALSE on failure.
Note: The current user is the user under which PHP runs. It is probably not the same user you use for normal shell or FTP access. The mode can be changed only by user who owns the file on most systems.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. In addition, you cannot set the SUID, SGID and sticky bits.
Attempts to change the owner of the file filename
to user user. Only the superuser may change the
owner of a file.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
When you use stat(), lstat(), or any of the other functions listed in the affected functions list (below), PHP caches the information those functions return in order to provide faster performance. However, in certain cases, you may want to clear the cached information. For instance, if the same file is being checked multiple times within a single script, and that file is in danger of being removed or changed during that script's operation, you may elect to clear the status cache. In these cases, you can use the clearstatcache() function to clear the information that PHP caches about a file.
You should also note that PHP doesn't cache information about non-existent files. So, if you call file_exists() on a file that doesn't exist, it will return FALSE until you create the file. If you create the file, it will return TRUE even if you then delete the file.
Note: This function caches information about specific filenames, so you only need to call clearstatcache() if you are performing multiple operations on the same filename and require the information about that particular file to not be cached.
Affected functions include stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype(), and fileperms().
Makes a copy of the file source to
dest.
If you wish to move a file, use the rename() function.
sourcePath to the source file.
dest
The destination path. If dest is a URL, the
copy operation may fail if the wrapper does not support overwriting of
existing files.
| Warning |
If the destination file already exists, it will be overwritten. |
| Version | Description |
|---|---|
| 4.3.0 |
Both source and dest
may now be URLs if the "fopen wrappers" have been enabled.
See fopen() for more details.
|
Note: Windows compatibility: If you copy a file with no size, copy() will return FALSE, but the file will be correctly copied.
This is a dummy manual entry to satisfy those people who are looking for unlink() or unset() in the wrong place.
Given a string containing a path to a file, this function will return the name of the directory.
On Windows, both slash (/) and backslash (\) are used as directory separator character. In other environments, it is the forward slash (/).
Note: In PHP 4.0.3, dirname() was fixed to be POSIX-compliant. Essentially, this means that if there are no slashes in
path, a dot ('.') is returned, indicating the current directory. Otherwise, the returned string ispathwith any trailing /component removed. Note that this means that you will often get a slash or a dot back from dirname() in situations where the older functionality would have given you the empty string.
dirname() has changed its behaviour in PHP 4.3.0. Check the following examples:
<?php
//before PHP 4.3.0
dirname('c:/'); // returned '.'
//after PHP 4.3.0
dirname('c:/'); // returns 'c:'
?> |
dirname() has been binary safe since PHP 5.0.0
See also basename(), pathinfo(), and realpath().
Given a string containing a directory, this function will return the number of bytes available on the corresponding filesystem or disk partition.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Given a string containing a directory, this function will return the total number of bytes on the corresponding filesystem or disk partition.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
handleThe file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen().
handleThe file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
Returns TRUE if the file pointer is at EOF or an error occurs (including socket timeout); otherwise returns FALSE.
| Warning |
If a connection opened by fsockopen() wasn't closed by the server, feof() will wait until a timeout has been reached to return TRUE. The default timeout value is 60 seconds. You may use stream_set_timeout() to change this value. |
| Warning | |
If passed file pointer is not valid you may get an infinite loop, because EOF fails to return TRUE. |
This function forces a write of all buffered output to the resource
pointed to by the file handle.
handleThe file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
Returns a string containing a single character read from the
file pointed to by handle.
Returns FALSE on EOF.
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
| Warning |
This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Please read the section on Booleans for more information. Use the === operator for testing the return value of this function. |
Note: This function is binary-safe.
See also fread(), fopen(), popen(), fsockopen(), and fgets().
Similar to fgets() except that fgetcsv() parses the line it reads for fields in CSV format and returns an array containing the fields read.
handleA valid file pointer to a file successfully opened by fopen(), popen(), or fsockopen().
lengthMust be greater than the longest line (in characters) to be found in the CSV file (allowing for trailing line-end characters). It became optional in PHP 5. Omitting this parameter (or setting it to 0 in PHP 5.0.4 and later) the maximum line length is not limited, which is slightly slower.
delimiterSet the field delimiter (one character only). Defaults as a comma.
enclosureSet the field enclosure character (one character only). Defaults as a double quotation mark.
Returns an indexed array containing the fields read.
Note: A blank line in a CSV file will be returned as an array comprising a single null field, and will not be treated as an error.
Note: If you are having problems with PHP not recognizing the line endings when reading files either on or created by a Macintosh computer, you might want to enable the auto_detect_line_endings run-time configuration option.
fgetcsv() returns FALSE on error, including end of file.
Example 1. Read and print the entire contents of a CSV file
|
Note: Locale setting is taken into account by this function. If
LANGis e.g. en_US.UTF-8, files in one-byte encoding are read wrong by this function.
handleThe file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
length
Reading ends when length - 1 bytes have been
read, on a newline (which is included in the return value), or on EOF
(whichever comes first). If no length is specified, it will keep
reading from the stream until it reaches the end of the line.
Note: Until PHP 4.3.0, omitting it would assume 1024 as the line length. If the majority of the lines in the file are all larger than 8KB, it is more resource efficient for your script to specify the maximum line length.
Returns a string of up to length - 1 bytes read from
the file pointed to by handle.
If an error occurs, returns FALSE.
Note: If you are having problems with PHP not recognizing the line endings when reading files either on or created by a Macintosh computer, you might want to enable the auto_detect_line_endings run-time configuration option.
Note: People used to the 'C' semantics of fgets() should note the difference in how EOF is returned.
Identical to fgets(), except that fgetss attempts to strip any HTML and PHP tags from the text it reads.
You can use the optional third parameter to specify tags which should not be stripped.
Note:
allowable_tagswas added in PHP 3.0.13, PHP 4.0.0.
Parameter length is optional since PHP 5.
Note: If you are having problems with PHP not recognizing the line endings when reading files either on or created by a Macintosh computer, you might want to enable the auto_detect_line_endings run-time configuration option.
See also fgets(), fopen(), fsockopen(), popen(), and strip_tags().
filenamePath to the file or directory.
On windows, use //computername/share/filename or \\computername\share\filename to check files on network shares.
Returns TRUE if the file or directory specified by
filename exists; FALSE otherwise.
| Warning |
This function returns FALSE for files inaccessible due to safe mode restrictions. However these files still can be included if they are located in safe_mode_include_dir. |
Note: The check is done using the real UID/GID instead of the effective one.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Identical to file(), except that
file_get_contents() returns the file in a string,
starting at the specified offset up to
maxlen bytes.
On failure, file_get_contents() will return FALSE.
file_get_contents() is the preferred way to read the contents of a file into a string. It will use memory mapping techniques if supported by your OS to enhance performance.
Note: If you're opening a URI with special characters, such as spaces, you need to encode the URI with urlencode().
Note:
contextparameter can be skipped by NULL.
Note: This function is binary-safe.
Tip: You can use a URL as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename and Appendix O for a list of supported URL protocols.
Note: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
| Warning |
When using SSL, Microsoft IIS will violate the protocol by closing the connection without sending a close_notify indicator. PHP will report this as "SSL: Fatal Protocol Error" when you reach the end of the data. To workaround this, you should lower your error_reporting level not to include warnings. PHP 4.3.7 and higher can detect buggy IIS server software when you open the stream using the https:// wrapper and will suppress the warning for you. If you are using fsockopen() to create an ssl:// socket, you are responsible for detecting and suppressing the warning yourself. |
| file() |
| fgets() |
| fread() |
| readfile() |
| file_put_contents() |
| stream_get_contents() |
| stream_context_create() |
Identical to calling fopen(), fwrite(), and fclose() successively.
You can also specify the data parameter as an array
(not multi-dimension arrays). This is equivalent to
file_put_contents($filename, implode('', $array)).
filenameThe file name where to write the data
dataThe data to write. Can be either a string, an array or a stream resource (explained above).
If data is a stream resource, the
remaining buffer of that stream will be copied to the specified file.
This is similar with using stream_copy_to_stream().
flags
flags can take
FILE_USE_INCLUDE_PATH,
FILE_APPEND and/or LOCK_EX
(acquire an exclusive lock), however the
FILE_USE_INCLUDE_PATH option should be used with
caution. As of PHP 6, it can also take one of
FILE_TEXT or FILE_BINARY to
specify how newlines should be handled when outputting the file. See
fopen()'s "t" and "b"
modes for more information.
contextA context resource
The function returns the amount of bytes that were written to the file, or FALSE on failure.
Note: This function is binary-safe.
Note: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
Tip: You can use a URL as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename and Appendix O for a list of supported URL protocols.
Reads an entire file into an array.
Note: You can use file_get_contents() to return the contents of a file as a string.
filenamePath to the file.
Tip: You can use a URL as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename and Appendix O for a list of supported URL protocols.
flags
The optional parameter flags can be one, or
more, of the following constants:
Search for the file in the include_path.
Do not add newline at the end of each array element
Skip empty lines
context
Note: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
Returns the file in an array. Each element of the array corresponds to a line in the file, with the newline still attached. Upon failure, file() returns FALSE.
Note: Each line in the resulting array will include the line ending, unless FILE_IGNORE_NEW_LINES is used, so you still need to use rtrim() if you do not want the line ending present.
Note: If you are having problems with PHP not recognizing the line endings when reading files either on or created by a Macintosh computer, you might want to enable the auto_detect_line_endings run-time configuration option.
| Version | Description |
|---|---|
| 5.0.0 |
The context parameter was added
|
| 5.0.0 |
Prior to PHP 5.0.0 the flags parameter only
covered include_path and was
enabled with 1
|
| 4.3.0 | file() became binary safe |
Example 1. file() example
|
| Warning |
When using SSL, Microsoft IIS will violate the protocol by closing the connection without sending a close_notify indicator. PHP will report this as "SSL: Fatal Protocol Error" when you reach the end of the data. To workaround this, you should lower your error_reporting level not to include warnings. PHP 4.3.7 and higher can detect buggy IIS server software when you open the stream using the https:// wrapper and will suppress the warning for you. If you are using fsockopen() to create an ssl:// socket, you are responsible for detecting and suppressing the warning yourself. |
Returns the time the file was last accessed, or FALSE in case of an error. The time is returned as a Unix timestamp.
Note: The atime of a file is supposed to change whenever the data blocks of a file are being read. This can be costly performance-wise when an application regularly accesses a very large number of files or directories. Some Unix filesystems can be mounted with atime updates disabled to increase the performance of such applications; USENET news spools are a common example. On such filesystems this function will be useless.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
See also filemtime(), fileinode(), and date().
Returns the time the file was last changed, or FALSE in case of an error. The time is returned as a Unix timestamp.
Note: Note: In most Unix filesystems, a file is considered changed when its inode data is changed; that is, when the permissions, owner, group, or other metadata from the inode is updated. See also filemtime() (which is what you want to use when you want to create "Last Modified" footers on web pages) and fileatime().
Note: Note also that in some Unix texts the ctime of a file is referred to as being the creation time of the file. This is wrong. There is no creation time for Unix files in most Unix filesystems.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Gets the file group. The group ID is returned in numerical format, use posix_getgrgid() to resolve it to a group name.
Returns the group ID of the file, or FALSE in case of an error. The group ID is returned in numerical format, use posix_getgrgid() to resolve it to a group name. Upon failure, FALSE is returned.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
This function returns the time when the data blocks of a file were being written to, that is, the time when the content of the file was changed.
Returns the time the file was last modified, or FALSE in case of an error. The time is returned as a Unix timestamp, which is suitable for the date() function.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Returns the user ID of the owner of the file, or FALSE in case of an error. The user ID is returned in numerical format, use posix_getpwuid() to resolve it to a username.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Example 2. Display full permissions
The above example will output:
|
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Returns the size of the file in bytes, or FALSE (and generates an error of level E_WARNING) in case of an error.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, filesize() may return unexpected results for files which are larger than 2GB. For files between 2GB and 4GB in size this can usually be overcome by using sprintf("%u", filesize($file)).
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Returns the type of the file. Possible values are fifo, char, dir, block, link, file, and unknown.
Returns FALSE if an error occurs. filetype() will also produce an E_NOTICE message if the stat call fails or if the file type is unknown.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
See also is_dir(), is_file(), is_link(), file_exists(), stat(), and mime_content_type().
PHP supports a portable way of locking complete files in an advisory way (which means all accessing programs have to use the same way of locking or it will not work).
Note: flock() is mandatory under Windows.
flock() operates on handle
which must be an open file
pointer. operation is one of the following
values:
To acquire a shared lock (reader), set
operation to LOCK_SH (set to 1 prior to
PHP 4.0.1).
To acquire an exclusive lock (writer), set
operation to LOCK_EX (set to 2 prior to
PHP 4.0.1).
To release a lock (shared or exclusive), set
operation to LOCK_UN (set to 3 prior to
PHP 4.0.1).
If you don't want flock() to block while
locking, add LOCK_NB (4 prior to PHP 4.0.1) to
operation.
flock() allows you to perform a simple reader/writer model which can be used on virtually every platform (including most Unix derivatives and even Windows). The optional third argument is set to TRUE if the lock would block (EWOULDBLOCK errno condition). The lock is released also by fclose() (which is also called automatically when script finished).
Returns TRUE on success or FALSE on failure.
Note: Because flock() requires a file pointer, you may have to use a special lock file to protect access to a file that you intend to truncate by opening it in write mode (with a "w" or "w+" argument to fopen()).
| Warning |
flock() will not work on NFS and many other networked file systems. Check your operating system documentation for more details. On some operating systems flock() is implemented at the process level. When using a multithreaded server API like ISAPI you may not be able to rely on flock() to protect files against other PHP scripts running in parallel threads of the same server instance! flock() is not supported on antiquated filesystems like FAT and its derivates and will therefore always return FALSE under this environments (this is especially true for Windows 98 users). |
fnmatch() checks if the passed string would
match the given shell wildcard pattern.
This is especially useful for filenames, but may also be used on regular strings. The average user may be used to shell patterns or at least in their simplest form to '?' and '*' wildcards so using fnmatch() instead of ereg() or preg_match() for frontend search expression input may be way more convenient for non-programming users.
| Warning |
For now this function is not available on Windows or other non-POSIX compliant systems. |
See also glob(), ereg(), preg_match() and the Unix manpage on fnmatch(3) for flag names (as long as they are not documented here ).
fopen() binds a named resource, specified by
filename, to a stream.
filename
If filename is of the form "scheme://...", it
is assumed to be a URL and PHP will search for a protocol handler
(also known as a wrapper) for that scheme. If no wrappers for that
protocol are registered, PHP will emit a notice to help you track
potential problems in your script and then continue as though
filename specifies a regular file.
If PHP has decided that filename specifies
a local file, then it will try to open a stream on that file.
The file must be accessible to PHP, so you need to ensure that
the file access permissions allow this access.
If you have enabled safe mode,
or open_basedir further
restrictions may apply.
If PHP has decided that filename specifies
a registered protocol, and that protocol is registered as a
network URL, PHP will check to make sure that
allow_url_fopen is
enabled. If it is switched off, PHP will emit a warning and
the fopen call will fail.
Note: The list of supported protocols can be found in Appendix O. Some protocols (also referred to as wrappers) support context and/or php.ini options. Refer to the specific page for the protocol in use for a list of options which can be set. (e.g. php.ini value user_agent used by the http wrapper).
On the Windows platform, be careful to escape any backslashes used in the path to the file, or use forward slashes.
mode
The mode parameter specifies the type of access
you require to the stream. It may be any of the following:
Table 1.
A list of possible modes for fopen()
using mode
mode | Description |
|---|---|
| 'r' | Open for reading only; place the file pointer at the beginning of the file. |
| 'r+' | Open for reading and writing; place the file pointer at the beginning of the file. |
| 'w' | Open for writing only; place the file pointer at the beginning of the file and truncate the file to zero length. If the file does not exist, attempt to create it. |
| 'w+' | Open for reading and writing; place the file pointer at the beginning of the file and truncate the file to zero length. If the file does not exist, attempt to create it. |
| 'a' | Open for writing only; place the file pointer at the end of the file. If the file does not exist, attempt to create it. |
| 'a+' | Open for reading and writing; place the file pointer at the end of the file. If the file does not exist, attempt to create it. |
| 'x' | Create and open for writing only; place the file pointer at the beginning of the file. If the file already exists, the fopen() call will fail by returning FALSE and generating an error of level E_WARNING. If the file does not exist, attempt to create it. This is equivalent to specifying O_EXCL|O_CREAT flags for the underlying open(2) system call. |
| 'x+' | Create and open for reading and writing; place the file pointer at the beginning of the file. If the file already exists, the fopen() call will fail by returning FALSE and generating an error of level E_WARNING. If the file does not exist, attempt to create it. This is equivalent to specifying O_EXCL|O_CREAT flags for the underlying open(2) system call. |
Note: Different operating system families have different line-ending conventions. When you write a text file and want to insert a line break, you need to use the correct line-ending character(s) for your operating system. Unix based systems use \n as the line ending character, Windows based systems use \r\n as the line ending characters and Macintosh based systems use \r as the line ending character.
If you use the wrong line ending characters when writing your files, you might find that other applications that open those files will "look funny".
Windows offers a text-mode translation flag ('t') which will transparently translate \n to \r\n when working with the file. In contrast, you can also use 'b' to force binary mode, which will not translate your data. To use these flags, specify either 'b' or 't' as the last character of the
modeparameter.The default translation mode depends on the SAPI and version of PHP that you are using, so you are encouraged to always specify the appropriate flag for portability reasons. You should use the 't' mode if you are working with plain-text files and you use \n to delimit your line endings in your script, but expect your files to be readable with applications such as notepad. You should use the 'b' in all other cases.
If you do not specify the 'b' flag when working with binary files, you may experience strange problems with your data, including broken image files and strange problems with \r\n characters.
Note: For portability, it is strongly recommended that you always use the 'b' flag when opening files with fopen().
Note: Again, for portability, it is also strongly recommended that you re-write code that uses or relies upon the 't' mode so that it uses the correct line endings and 'b' mode instead.
use_include_path
The optional third use_include_path parameter
can be set to '1' or TRUE if you want to search for the file in the
include_path, too.
contextNote: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
If the open fails, the function an error of level E_WARNING is generated. You may use @ to suppress this warning.
| Version | Description |
|---|---|
| 4.3.2 | As of PHP 4.3.2, the default mode is set to binary for all platforms that distinguish between binary and text mode. If you are having problems with your scripts after upgrading, try using the 't' flag as a workaround until you have made your script more portable as mentioned below |
| 4.3.2 | The 'x' and 'x+' option was added |
| Warning |
When using SSL, Microsoft IIS will violate the protocol by closing the connection without sending a close_notify indicator. PHP will report this as "SSL: Fatal Protocol Error" when you reach the end of the data. To workaround this, you should lower your error_reporting level not to include warnings. PHP 4.3.7 and higher can detect buggy IIS server software when you open the stream using the https:// wrapper and will suppress the warning for you. If you are using fsockopen() to create an ssl:// socket, you are responsible for detecting and suppressing the warning yourself. |
Note: When safe mode is enabled, PHP checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed.
If you are experiencing problems with reading and writing to files and you're using the server module version of PHP, remember to make sure that the files and directories you're using are accessible to the server process.
| Appendix O |
| fclose() |
| fgets() |
| fread() |
| fwrite() |
| fsockopen() |
| file() |
| file_exists() |
| is_readable() |
| stream_set_timeout() |
| popen() |
| stream_context_create() |
Reads to EOF on the given file pointer from the current position and writes the results to the output buffer.
If an error occurs, fpassthru() returns
FALSE. Otherwise, fpassthru() returns
the number of characters read from handle
and passed through to the output.
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
You may need to call rewind() to reset the file pointer to the beginning of the file if you have already written data to the file.
If you just want to dump the contents of a file to the output buffer, without first modifying it or seeking to a particular offset, you may want to use the readfile(), which saves you the fopen() call.
Note: When using fpassthru() on a binary file on Windows systems, you should make sure to open the file in binary mode by appending a b to the mode used in the call to fopen().
You are encouraged to use the b flag when dealing with binary files, even if your system does not require it, so that your scripts will be more portable.
Example 1. Using fpassthru() with binary files
|
See also readfile(), fopen(), popen(), and fsockopen()
fputcsv() formats a line (passed as a
fields array) as CSV and write it to the
specified file handle. Returns the length of the
written string, or FALSE on failure.
The optional delimiter parameter sets the field
delimiter (one character only). Defaults as a comma: ,.
The optional enclosure parameter sets the field
enclosure (one character only) and defaults to a double quotation mark:
".
Note: If you are having problems with PHP not recognizing the line endings when reading files either on or created by a Macintosh computer, you might want to enable the auto_detect_line_endings run-time configuration option.
See also fgetcsv().
fread() reads up to
length bytes from the file pointer
referenced by handle. Reading stops when up to
length bytes have been read, EOF
(end of file) is reached, (for network streams) when a packet becomes
available, or (after opening userspace stream) when 8192 bytes have been read
whichever comes first.
Returns the read string or FALSE in case of error.
<?php // get contents of a file into a string $filename = "/usr/local/something.txt"; $handle = fopen($filename, "r"); $contents = fread($handle, filesize($filename)); fclose($handle); ?> |
| Warning |
On systems which differentiate between binary and text files (i.e. Windows) the file must be opened with 'b' included in fopen() mode parameter. |
<?php $filename = "c:\\files\\somepic.gif"; $handle = fopen($filename, "rb"); $contents = fread($handle, filesize($filename)); fclose($handle); ?> |
| Warning |
When reading from anything that is not a regular local file, such as streams returned when reading remote files or from popen() and fsockopen(), reading will stop after a packet is available. This means that you should collect the data together in chunks as shown in the examples below. |
<?php
// For PHP 5 and up
$handle = fopen("http://www.example.com/", "rb");
$contents = stream_get_contents($handle);
fclose($handle);
?> |
<?php
$handle = fopen("http://www.example.com/", "rb");
$contents = '';
while (!feof($handle)) {
$contents .= fread($handle, 8192);
}
fclose($handle);
?> |
Note: If you just want to get the contents of a file into a string, use file_get_contents() as it has much better performance than the code above.
See also fwrite(), fopen(), fsockopen(), popen(), fgets(), fgetss(), fscanf(), file(), and fpassthru().
The function fscanf() is similar to
sscanf(), but it takes its input from a file
associated with handle and interprets the
input according to the specified format, which is
described in the documentation for sprintf(). If only
two parameters were passed to this function, the values parsed will be
returned as an array. Otherwise, if optional parameters are passed, the
function will return the number of assigned values. The optional
parameters must be passed by reference.
Any whitespace in the format string matches any whitespace in the input stream. This means that even a tab \t in the format string can match a single space character in the input stream.
Note: Prior to PHP 4.3.0, the maximum number of characters read from the file was 512 (or up to the first \n, whichever came first). As of PHP 4.3.0 arbitrarily long lines will be read and scanned.
See also fread(), fgets(), fgetss(), sscanf(), printf(), and sprintf().
Sets the file position indicator for the file referenced by
handle. The new position, measured in bytes
from the beginning of the file, is obtained by adding
offset to the position specified by
whence, whose values are defined as
follows:
SEEK_SET - Set position equal to offset bytes. |
SEEK_CUR - Set position to current location plus offset. |
SEEK_END - Set position to end-of-file plus offset.
(To move to a position before the end-of-file, you need to pass a negative
value in offset.) |
If whence is not specified, it is assumed to be
SEEK_SET.
Upon success, returns 0; otherwise, returns -1. Note that seeking past EOF is not considered an error.
May not be used on file pointers returned by fopen() if they use the "http://" or "ftp://" formats. fseek() gives also undefined results for append-only streams (opened with "a" flag).
Note: The
whenceargument was added after PHP 4.0.0.
Note: If you have opened the file in append ("a" or "a+") mode, any data you write to the file will always be appended, regardless of the file position.
Gathers the statistics of the file opened by the file
pointer handle. This function is similar to the
stat() function except that it operates
on an open file pointer instead of a filename.
Returns an array with the statistics of the file; the format of the array is described in detail on the stat() manual page.
Example 1. fstat() example
The above example will output something similar to:
|
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Returns the position of the file pointer referenced by
handle; i.e., its offset into the file stream.
If an error occurs, returns FALSE.
Takes the filepointer, handle, and truncates the file to
length, size. Returns TRUE on success or FALSE on failure.
Note: The file pointer is changed only in append mode. In write mode, additional fseek() call is needed.
fwrite() writes the contents of
string to the file stream pointed to by
handle. If the length
argument is given, writing will stop after
length bytes have been written or the end
of string is reached, whichever comes
first.
fwrite() returns the number of bytes written, or FALSE on error.
Note that if the length argument is given,
then the magic_quotes_runtime
configuration option will be ignored and no slashes will be
stripped from string.
Note: On systems which differentiate between binary and text files (i.e. Windows) the file must be opened with 'b' included in fopen() mode parameter.
Note: If
handlewas fopen()ed in append mode, fwrite()s are atomic (unless the size ofstringexceeds the filesystem's block size, on some platforms, and as long as the file is on a local filesystem). That is, there is no need to flock() a resource before calling fwrite(); all of the data will be written without interruption.
Example 1. A simple fwrite() example
|
See also fread(), fopen(), fsockopen(), popen(), and file_put_contents().
The glob() function searches for all the pathnames
matching pattern according to the rules used by
the libc glob() function, which is similar to the rules used by common
shells.
patternThe pattern. No tilde expansion or parameter substitution is done.
flagsValid flags:
GLOB_MARK - Adds a slash to each item returned
GLOB_NOSORT - Return files as they appear in the directory (no sorting)
GLOB_NOCHECK - Return the search pattern if no files matching it were found
GLOB_NOESCAPE - Backslashes do not quote metacharacters
GLOB_BRACE - Expands {a,b,c} to match 'a', 'b', or 'c'
GLOB_ONLYDIR - Return only directory entries which match the pattern
GLOB_ERR - Stop on read errors (like unreadable directories), by default errors are ignored.
Returns an array containing the matched files/directories, an empty array if no file matched or FALSE on error.
Example 1. Convenient way how glob() can replace opendir() and friends.
The above example will output something similar to:
|
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: This function isn't available on some systems (e.g. old Sun OS).
Note: The GLOB_BRACE flag is not available on some non GNU systems, like Solaris.
filename
Path to the file. If filename is a relative
filename, it will be checked relative to the current working
directory.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Returns TRUE if the file or directory specified by
filename exists and is readable, FALSE otherwise.
Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). Safe mode limitations are not taken into account.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Note: The check is done using the real UID/GID instead of the effective one.
(PHP 3 >= 3.0.17, PHP 4 >= 4.0.3, PHP 5)
is_uploaded_file -- Tells whether the file was uploaded via HTTP POST
Returns TRUE if the file named by filename was
uploaded via HTTP POST. This is useful to help ensure that a
malicious user hasn't tried to trick the script into working on
files upon which it should not be working--for instance,
/etc/passwd.
This sort of check is especially important if there is any chance that anything done with uploaded files could reveal their contents to the user, or even to other users on the same system.
For proper working, the function is_uploaded_file() needs an argument like $_FILES['userfile']['tmp_name'], - the name of the uploaded file on the clients machine $_FILES['userfile']['name'] does not work.
Example 1. is_uploaded_file() example
|
is_uploaded_file() is available only in versions of PHP 3 after PHP 3.0.16, and in versions of PHP 4 after 4.0.2. If you are stuck using an earlier version, you can use the following function to help protect yourself:
Note: The following example will not work in versions of PHP 4 after 4.0.2. It depends on internal functionality of PHP which changed after that version.
Example 2. is_uploaded_file() example for PHP 4 < 4.0.3
|
See also move_uploaded_file(), and the section Handling file uploads for a simple usage example.
Returns TRUE if the filename exists and is
writable. The filename argument may be a directory name allowing you
to check if a directory is writeable.
Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). Safe mode limitations are not taken into account.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
See also is_readable(), file_exists(), and fwrite().
Attempts to change the group of the symlink filename
to group.
Only the superuser may change the group of a symlink arbitrarily; other users may change the group of a symlink to any group of which that user is a member.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
Attempts to change the owner of the symlink filename
to user user.
Only the superuser may change the owner of a symlink.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed.
Note: This function will not work on remote files as the file to be examined must be accessible via the servers filesystem.
Note: This function is not implemented on Windows platforms.
Gets information about a link.
This function is used to verify if a link (pointed to by
path) really exists (using the same method as the
S_ISLNK macro defined in stat.h).
linkinfo() returns the st_dev field of the Unix C stat structure returned by the lstat system call. Returns 0 or FALSE in case of error.
Gathers the statistics of the file or symbolic link named by
filename.
See the manual page for stat() for information on
the structure of the array that lstat() returns.
This function is identical to the stat() function
except that if the filename parameter is a symbolic
link, the status of the symbolic link is returned, not the status of the
file pointed to by the symbolic link.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
Attempts to create the directory specified by pathname.
pathnameThe directory path.
modeThe mode is 0777 by default, which means the widest possible access. For more information on modes, read the details on the chmod() page.
Note:
modeis ignored on Windows.
Note that you probably want to specify the mode as an octal number, which means it should have a leading zero. The mode is also modified by the current umask, which you can change using umask().
recursive
contextNote: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
| Version | Description |
|---|---|
| 5.0.0 |
The recursive parameter was added
|
| 5.0.0 | As of PHP 5.0.0 mkdir() can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support mkdir() |
| 4.2.0 |
The mode parameter became optional.
|
Note: When safe mode is enabled, PHP checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed.
This function checks to ensure that the file designated by
filename is a valid upload file (meaning
that it was uploaded via PHP's HTTP POST upload mechanism). If
the file is valid, it will be moved to the filename given by
destination.
If filename is not a valid upload file,
then no action will occur, and
move_uploaded_file() will return
FALSE.
If filename is a valid upload file, but
cannot be moved for some reason, no action will occur, and
move_uploaded_file() will return
FALSE. Additionally, a warning will be issued.
This sort of check is especially important if there is any chance that anything done with uploaded files could reveal their contents to the user, or even to other users on the same system.
Note: move_uploaded_file() is both safe mode and open_basedir aware. However, restrictions are placed only on the
destinationpath as to allow the moving of uploaded files in whichfilenamemay conflict with such restrictions. move_uploaded_file() ensures the safety of this operation by allowing only those files uploaded through PHP to be moved.
| Warning |
If the destination file already exists, it will be overwritten. |
See also is_uploaded_file(), and the section Handling file uploads for a simple usage example.
parse_ini_file() loads in the
ini file specified in filename,
and returns the settings in it in an associative array.
By setting the last process_sections
parameter to TRUE, you get a multidimensional array, with
the section names and settings included. The default
for process_sections is FALSE
Note: This function has nothing to do with the php.ini file. It is already processed, the time you run your script. This function can be used to read in your own application's configuration files.
Note: If a value in the ini file contains any non-alphanumeric characters it needs to be enclosed in double-quotes (").
Note: Since PHP 4.2.1 this function is also affected by safe mode and open_basedir.
Note: As of PHP 5.0.0 this function also handles new lines in values.
Note: There are reserved words which must not be used as keys for ini files. These include: null, yes, no, true, and false. Values null, no and false results in "", yes and true results in "1". Characters {}|&~![()" must not be used anywhere in the key and have a special meaning in the value.
The structure of the ini file is similar to that of the php.ini's.
Constants may also be parsed in the ini file so if you define a constant as an ini value before running parse_ini_file(), it will be integrated into the results. Only ini values are evaluated. For example:
Example 2. parse_ini_file() example
Would produce:
|
Keys and section names consisting from numbers are evaluated as PHP integers thus numbers starting by 0 are evaluated as octals and numbers starting by 0x are evaluated as hexadecimals.
pathinfo() returns an associative array
containing information about path. The
following array elements are returned:
dirname, basename
and extension if any.
You can specify which elements are returned with optional parameter
options. It composes from
PATHINFO_DIRNAME,
PATHINFO_BASENAME,
PATHINFO_EXTENSION and
PATHINFO_FILENAME (available since PHP 5.2.0). It
defaults to return all elements. This function returns string if not all
elements are requested.
Note: For information on retrieving the current path info, read the section on predefined reserved variables.
See also dirname(), basename(), parse_url() and realpath().
handleThe file pointer must be valid, and must have been returned by a successful call to popen().
Opens a pipe to a process executed by forking the command given by command.
Returns a file pointer identical to that returned by fopen(), except that it is unidirectional (may only be used for reading or writing) and must be closed with pclose(). This pointer may be used with fgets(), fgetss(), and fwrite().
If an error occurs, returns FALSE.
Note: If you're looking for bi-directional support (two-way), use proc_open().
If the command to be executed could not be found, a valid resource is returned. This may seem odd, but makes sense; it allows you to access any error message returned by the shell:
<?php
error_reporting(E_ALL);
/* Add redirection so we can get stderr. */
$handle = popen('/path/to/spooge 2>&1', 'r');
echo "'$handle'; " . gettype($handle) . "\n";
$read = fread($handle, 2096);
echo $read;
pclose($handle);
?> |
Note: When safe mode is enabled, you can only execute executables within the safe_mode_exec_dir. For practical reasons it is currently not allowed to have .. components in the path to the executable.
| Warning |
With safe mode enabled, the command string is escaped with escapeshellcmd(). Thus, echo y | echo x becomes echo y \| echo x. |
See also pclose(), fopen(), and proc_open().
Reads a file and writes it to the output buffer.
Returns the number of bytes read from the file. If an error occurs, FALSE is returned and unless the function was called as @readfile(), an error message is printed.
Tip: You can use a URL as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename and Appendix O for a list of supported URL protocols.
You can use the optional second parameter and set it to TRUE, if you want to search for the file in the include_path, too.
Note: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
See also fpassthru(), file(), fopen(), include(), require(), virtual(), file_get_contents(), and Appendix O.
realpath() expands all symbolic links and
resolves references to '/./', '/../' and extra '/' characters in
the input path and return the canonicalized
absolute pathname. The resulting path will have no symbolic link,
'/./' or '/../' components.
realpath() returns FALSE on failure, e.g. if
the file does not exist. On BSD systems realpath()
doesn't fail if only the last path component
doesn't exist, while other systems will return FALSE.
See also basename(), dirname(), and pathinfo().
Attempts to rename oldname to
newname.
oldname
Note: The old name. The wrapper used in
oldnamemust match the wrapper used innewname.
newnameThe new name.
contextNote: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
| Version | Description |
|---|---|
| 5.0.0 | rename() can now also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support rename(). |
| 4.3.3 | rename() is now able to rename files across partitions on *nix based systems. |
Sets the file position indicator for handle
to the beginning of the file stream.
Note: If you have opened the file in append ("a" or "a+") mode, any data you write to the file will always be appended, regardless of the file position.
handleThe file pointer must be valid, and must point to a file successfully opened by fopen().
Attempts to remove the directory named by dirname.
The directory must be empty, and the relevant permissions must permit this.
dirnamePath to the directory.
contextNote: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
| Version | Description |
|---|---|
| 5.0.0 | As of PHP 5.0.0 rmdir() can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support rmdir(). |
Note: When safe mode is enabled, PHP checks whether the directory in which you are about to operate has the same UID (owner) as the script that is being executed.
Gathers the statistics of the file named by
filename. If filename is a
symbolic link, statistics are from the file itself, not the symlink.
lstat() is identical to stat() except it would instead be based off the symlinks status.
Table 1. stat() and fstat() result format
| Numeric | Associative (since PHP 4.0.6) | Description |
|---|---|---|
| 0 | dev | device number |
| 1 | ino | inode number |
| 2 | mode | inode protection mode |
| 3 | nlink | number of links |
| 4 | uid | userid of owner |
| 5 | gid | groupid of owner |
| 6 | rdev | device type, if inode device * |
| 7 | size | size in bytes |
| 8 | atime | time of last access (Unix timestamp) |
| 9 | mtime | time of last modification (Unix timestamp) |
| 10 | ctime | time of last inode change (Unix timestamp) |
| 11 | blksize | blocksize of filesystem IO * |
| 12 | blocks | number of blocks allocated |
In case of error, stat() returns FALSE.
Note: The results of this function are cached. See clearstatcache() for more details.
Tip: As of PHP 5.0.0 this function can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support stat() family of functionality.
symlink() creates a symbolic link to the existing
target with the specified name
link.
Creates a file with a unique filename, with access permission set to 0600, in the specified directory. If the directory does not exist, tempnam() may generate a file in the system's temporary directory, and return the name of that.
Prior to PHP 4.0.6, the behaviour of the
tempnam() function was system dependent. On
Windows the TMP environment variable will override the
dir parameter, on Linux the TMPDIR
environment variable has precedence, while SVR4 will always use
your dir parameter if the directory it
points to exists. Consult your system documentation on the
tempnam(3) function if in doubt.
Note: If PHP cannot create a file in the specified
dirparameter, it falls back on the system default.
Returns the new temporary filename, or FALSE on failure.
Note: This function's behavior changed in 4.0.3. The temporary file is also created to avoid a race condition where the file might appear in the filesystem between the time the string was generated and before the script gets around to creating the file. Note, that you need to remove the file in case you need it no more, it is not done automatically.
See also tmpfile(), sys_get_temp_dir() and unlink().
Creates a temporary file with a unique name in read-write (w+) mode and returns a file handle .
The file is automatically removed when closed (using fclose()), or when the script ends.
For details, consult your system documentation on the tmpfile(3) function, as well as the stdio.h header file.
Returns a file handle, similar to the one returned by fopen(), for the new file, or FALSE on failure.
Attempts to set the access and modification times of the file named in the
filename parameter to the value given in
time. If time
is not supplied, the current system time is used. If the third parameter,
is present, the access time of the given
filename is set to the value of atime.
Note that the access time is always modified, regardless of the number
of parameters.
If the file does not exist, it will be created. Returns TRUE on success or FALSE on failure.
| Warning |
It is not currently possible to change the modification time of a directory with this function under Windows. |
umask() sets PHP's umask to
mask & 0777 and returns the old
umask. When PHP is being used as a server module, the umask
is restored when each request is finished.
umask() without arguments simply returns the current umask.
Note: Avoid using this function in multithreaded webservers. It is better to change the file permissions with chmod() after creating the file. Using umask() can lead to unexpected behavior of concurrently running scripts and the webserver itself because they all use the same umask.
Deletes filename. Similar to the Unix C unlink()
function.
filenamePath to the file.
contextNote: Context support was added with PHP 5.0.0. For a description of contexts, refer to Reference CLX, Stream Functions.
| Version | Description |
|---|---|
| 5.0.0 | As of PHP 5.0.0 unlink() can also be used with some URL wrappers. Refer to Appendix O for a listing of which wrappers support unlink(). |
This extension serves for validating and filtering data coming usually from some insecure source such as user input.
The following filters currently exist, be sure to read the Filter Constants section for information that describes the behavior of each constant:
Table 1. Existing filters
| ID | Name | Options | Flags | Description |
|---|---|---|---|---|
| FILTER_VALIDATE_INT | "int" |
min_range,
max_range
| FILTER_FLAG_ALLOW_OCTAL, FILTER_FLAG_ALLOW_HEX | Validates value as integer, optionally from the specified range. |
| FILTER_VALIDATE_BOOLEAN | "boolean" | Returns TRUE for "1", "true", "on" and "yes", FALSE for "0", "false", "off", "no", and "", NULL otherwise. | ||
| FILTER_VALIDATE_FLOAT | "float" |
decimal
| FILTER_FLAG_ALLOW_THOUSAND | Validates value as float. |
| FILTER_VALIDATE_REGEXP | "validate_regexp" |
regexp
|
Validates value against regexp, a
Perl-compatible regular expression.
| |
| FILTER_VALIDATE_URL | "validate_url" | FILTER_FLAG_SCHEME_REQUIRED, FILTER_FLAG_HOST_REQUIRED, FILTER_FLAG_PATH_REQUIRED, FILTER_FLAG_QUERY_REQUIRED | Validates value as URL, optionally with required components. | |
| FILTER_VALIDATE_EMAIL | "validate_email" | Validates value as e-mail. | ||
| FILTER_VALIDATE_IP | "validate_ip" | FILTER_FLAG_IPV4, FILTER_FLAG_IPV6, FILTER_FLAG_NO_PRIV_RANGE, FILTER_FLAG_NO_RES_RANGE | Validates value as IP address, optionally only IPv4 or IPv6 or not from private or reserved ranges. | |
| FILTER_SANITIZE_STRING | "string" | FILTER_FLAG_NO_ENCODE_QUOTES, FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH, FILTER_FLAG_ENCODE_AMP | Strip tags, optionally strip or encode special characters. | |
| FILTER_SANITIZE_STRIPPED | "stripped" | Alias of "string" filter. | ||
| FILTER_SANITIZE_ENCODED | "encoded" | FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH | URL-encode string, optionally strip or encode special characters. | |
| FILTER_SANITIZE_SPECIAL_CHARS | "special_chars" | FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_ENCODE_HIGH | HTML-escape '"<>& and characters with ASCII value less than 32, optionally strip or encode other special characters. | |
| FILTER_UNSAFE_RAW | "unsafe_raw" | FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH, FILTER_FLAG_ENCODE_AMP | Do nothing, optionally strip or encode special characters. | |
| FILTER_SANITIZE_EMAIL | "email" | Remove all characters except letters, digits and !#$%&'*+-/=?^_`{|}~@.[]. | ||
| FILTER_SANITIZE_URL | "url" | Remove all characters except letters, digits and $-_.+!*'(),{}|\\^~[]`<>#%";/?:@&=. | ||
| FILTER_SANITIZE_NUMBER_INT | "number_int" | Remove all characters except digits and +-. | ||
| FILTER_SANITIZE_NUMBER_FLOAT | "number_float" | FILTER_FLAG_ALLOW_FRACTION, FILTER_FLAG_ALLOW_THOUSAND, FILTER_FLAG_ALLOW_SCIENTIFIC | Remove all characters except digits, +- and optionally .,eE. | |
| FILTER_SANITIZE_MAGIC_QUOTES | "magic_quotes" | Apply addslashes(). | ||
| FILTER_CALLBACK | "callback" | callback function or method | Call user-defined function to filter data. |
The behaviour of these functions is affected by settings in php.ini.
Table 2. Filter Configuration Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| filter.default | unsafe_raw | PHP_INI_PERDIR | |
| filter.default_flags | PHP_INI_PERDIR |
Here's a short explanation of the configuration directives.
filter.default
stringFilter all $_GET, $_POST, $_COOKIE and $_REQUEST data by this filter. Original data can be accessed through filter_input().
Accepts the name of the filter you like to use by default. See the existing filter list for the list of the filter names.
filter.default_flags
integerDefault flags
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
POST variables.
GET variables.
COOKIE variables.
ENV variables.
SERVER variables.
SESSION variables. (not implemented yet)
REQUEST variables. (not implemented yet)
No flags.
Flag used to require scalar as input
Require an array as input.
Always returns an array.
Use NULL instead of FALSE on failure.
ID of "int" filter.
ID of "boolean" filter.
ID of "float" filter.
ID of "validate_regexp" filter.
ID of "validate_url" filter.
ID of "validate_email" filter.
ID of "validate_ip" filter.
ID of default ("string") filter.
ID of "unsafe_raw" filter.
ID of "string" filter.
ID of "stripped" filter.
ID of "encoded" filter.
ID of "special_chars" filter.
ID of "email" filter.
ID of "url" filter.
ID of "number_int" filter.
ID of "number_float" filter.
ID of "magic_quotes" filter.
ID of "callback" filter.
Allow octal notation (0[0-7]+) in "int" filter.
Allow hex notation (0x[0-9a-fA-F]+) in "int" filter.
Strip characters with ASCII value less than 32.
Strip characters with ASCII value greater than 127.
Encode characters with ASCII value less than 32.
Encode characters with ASCII value greater than 127.
Encode &.
Don't encode ' and ".
(No use for now.)
Allow fractional part in "number_float" filter.
Allow thousand separator (,) in "number_float" filter.
Allow scientific notation (e, E) in "number_float" filter.
Require scheme in "validate_url" filter.
Require host in "validate_url" filter.
Require path in "validate_url" filter.
Require query in "validate_url" filter.
Allow only IPv4 address in "validate_ip" filter.
Allow only IPv6 address in "validate_ip" filter.
Deny reserved addresses in "validate_ip" filter.
Deny private addresses in "validate_ip" filter.
(no version information, might be only in CVS)
filter_has_var -- Checks if variable of specified type exists
typeOne of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER, INPUT_ENV.
variable_nameName of a variable to check.
(no version information, might be only in CVS)
filter_id -- Returns the filter ID belonging to a named filter(no version information, might be only in CVS)
filter_input_array -- Gets multiple variables from outside PHP and optionally filters themThis function is useful for retrieving many values without repetitively calling filter_input().
typeOne of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER, INPUT_ENV, INPUT_SESSION, or INPUT_REQUEST.
definitionAn array defining the arguments. A valid key is a string containing a variable name and a valid value is either a filter type, or an array optionally specifying the filter, flags and options. If the value is an array, valid keys are filter which specifies the filter type, flags which specifies any flags that apply to the filter, and options which specifies any options that apply to the filter. See the example below for a better understanding.
This parameter can be also an integer holding a filter constant. Then all values in the input array are filtered by this filter.
An array containing the values of the requested variables on success, or FALSE on failure. An array value will be FALSE if the filter fails, or NULL if the variable is not set. Or if the flag FILTER_NULL_ON_FAILURE is used, it returns FALSE if the variable is not set and NULL if the filter fails.
Example 1. A filter_input_array() example
The above example will output:
|
(no version information, might be only in CVS)
filter_input -- Gets variable from outside PHP and optionally filters it
typeOne of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER, INPUT_ENV, INPUT_SESSION (not implemented yet) and INPUT_REQUEST (not implemented yet).
variable_nameName of a variable to get.
filterFilter to apply. Defaults to FILTER_DEFAULT.
optionsAssociative array of options or bitwise disjunction of flags. If filter accepts options, flags can be provided in "flags" field of array.
Value of the requested variable on success, FALSE if the filter fails,
or NULL if the variable_name variable is not set.
If the flag FILTER_NULL_ON_FAILURE is used, it
returns FALSE if the variable is not set and NULL if the filter fails.
Example 1. A filter_input() example
The above example will output something similar to:
|
(no version information, might be only in CVS)
filter_list -- Returns a list of all supported filtersReturns an array of names of all supported filters, empty array if there are no such filters. Indexes of this array are not filter IDs, they can be obtained with filter_id() from a name instead.
Example 1. A filter_list() example
The above example will output something similar to:
|
(no version information, might be only in CVS)
filter_var_array -- Gets multiple variables and optionally filters themThis function is useful for retrieving many values without repetitively calling filter_var().
dataAn array with string keys containing the data to filter.
definitionAn array defining the arguments. A valid key is a string containing a variable name and a valid value is either a filter type, or an array optionally specifying the filter, flags and options. If the value is an array, valid keys are filter which specifies the filter type, flags which specifies any flags that apply to the filter, and options which specifies any options that apply to the filter. See the example below for a better understanding.
This parameter can be also an integer holding a filter constant. Then all values in the input array are filtered by this filter.
An array containing the values of the requested variables on success, or FALSE on failure. An array value will be FALSE if the filter fails, or NULL if the variable is not set.
Example 1. A filter_var_array() example
The above example will output:
|
(no version information, might be only in CVS)
filter_var -- Filters a variable with a specified filter
variableValue to filter, arrays are filtered recursively.
filterID of a filter to use. Defaults to FILTER_SANITIZE_STRING.
optionsAssociative array of options or bitwise disjunction of flags. If filter accepts options, flags can be provided in "flags" field of array. For the "callback" filter, callback type should be passed.
Firebird/InterBase is a relational database offering many ANSI SQL-92 features that runs on Linux, Windows, and a variety of Unix platforms. Firebird/InterBase offers excellent concurrency, high performance, and powerful language support for stored procedures and triggers. It has been used in production systems, under a variety of names since 1981.
InterBase is the name of the closed-source variant of this RDBMS that was developed by Borland/Inprise. More information about InterBase is available at http://www.borland.com/interbase/.
Firebird is a commercially independent project of C and C++ programmers, technical advisors and supporters developing and enhancing a multi-platform relational database management system based on the source code released by Inprise Corp (now known as Borland Software Corp) under the InterBase Public License v.1.0 on 25 July, 2000. More information about Firebird is available at http://www.firebirdsql.org/.
Note: This extension supports InterBase versions 5 and up and all versions of Firebird. Support for InterBase version 5.x will be dropped in PHP 5.
This database uses a single quote (') character for escaping, a behavior similar to the Sybase database, add to your php.ini the following directive:
To enable InterBase support configure PHP
--with-interbase[=DIR], where DIR is the
InterBase base install directory, which defaults to
/usr/interbase.
Note to Win32 Users: In order for this extension to work, there are DLL files that must be available to the Windows system PATH. See the FAQ titled "How do I add my PHP directory to the PATH on Windows" for information on how to do this. Although copying DLL files from the PHP folder into the Windows system directory also works (because the system directory is by default in the systems PATH), it is not recommended. This extension requires the following files to be in the PATH: gds32.dll
In case you installed the InterBase database server on the same machine PHP is running on, you will have this DLL already. Therefore you don't need to worry because gds32.dll will already be in the PATH.
The behaviour of these functions is affected by settings in php.ini.
Table 1. InterBase configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| ibase.allow_persistent | "1" | PHP_INI_SYSTEM | |
| ibase.max_persistent | "-1" | PHP_INI_SYSTEM | |
| ibase.max_links | "-1" | PHP_INI_SYSTEM | |
| ibase.default_db | NULL | PHP_INI_SYSTEM | Available since PHP 5.0.0. |
| ibase.default_user | NULL | PHP_INI_ALL | |
| ibase.default_password | NULL | PHP_INI_ALL | |
| ibase.default_charset | NULL | PHP_INI_ALL | Available since PHP 5.0.0. |
| ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | PHP_INI_ALL | |
| ibase.dateformat | "%Y-%m-%d" | PHP_INI_ALL | |
| ibase.timeformat | "%H:%M:%S" | PHP_INI_ALL |
Here's a short explanation of the configuration directives.
ibase.allow_persistent
booleanWhether to allow persistent connections to Firebird/InterBase.
ibase.max_persistent
integerThe maximum number of persistent Firebird/InterBase connections per process. New connections created with ibase_pconnect() will be non-persistent if this number would be exceeded.
ibase.max_links
integerThe maximum number of Firebird/InterBase connections per process, including persistent connections.
ibase.default_db
stringThe default database to connect to when ibase_[p]connect() is called without specifying a database name. If this value is set and SQL safe mode is enabled, no other connections than to this database will be allowed.
ibase.default_user
stringThe user name to use when connecting to a database if no user name is specified.
ibase.default_password
stringThe password to use when connecting to a database if no password is specified.
ibase.default_charset
stringThe character set to use when connecting to a database if no character set is specified.
ibase.timestampformat
string
ibase.dateformat
string
ibase.timeformat
stringThese directives are used to set the date and time formats that are used when returning dates and times from a result set, or when binding arguments to date and time parameters.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The following constants can be passed to ibase_trans() to specify transaction behaviour.
Table 2. Firebird/InterBase transaction flags
| Constant | Description |
|---|---|
| IBASE_DEFAULT | The default transaction settings are to be used. This default is determined by the client library, which defines it as IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT in most cases. |
| IBASE_READ | Starts a read-only transaction. |
| IBASE_WRITE | Starts a read-write transaction. |
| IBASE_CONSISTENCY | Starts a transaction with the isolation level set to 'consistency', which means the transaction cannot read from tables that are being modified by other concurrent transactions. |
| IBASE_CONCURRENCY | Starts a transaction with the isolation level set to 'concurrency' (or 'snapshot'), which means the transaction has access to all tables, but cannot see changes that were committed by other transactions after the transaction was started. |
| IBASE_COMMITTED | Starts a transaction with the isolation level set to 'read committed'. This flag should be combined with either IBASE_REC_VERSION or IBASE_REC_NO_VERSION. This isolation level allows access to changes that were committed after the transaction was started. If IBASE_REC_NO_VERSION was specified, only the latest version of a row can be read. If IBASE_REC_VERSION was specified, a row can even be read when a modification to it is pending in a concurrent transaction. |
| IBASE_WAIT | Indicated that a transaction should wait and retry when a conflict occurs. |
| IBASE_NOWAIT | Indicated that a transaction should fail immediately when a conflict occurs. |
The following constants can be passed to ibase_fetch_row(), ibase_fetch_assoc() or ibase_fetch_object() to specify fetch behaviour.
Table 3. Firebird/InterBase fetch flags
| Constant | Description |
|---|---|
| IBASE_FETCH_BLOBS | Also available as IBASE_TEXTfor backward compatibility. Causes BLOB contents to be fetched inline, instead of being fetched as BLOB identifiers. |
| IBASE_FETCH_ARRAYS | Causes arrays to be fetched inline. Otherwise, array identifiers are returned. Array identifiers can only be used as arguments to INSERT operations, as no functions to handle array identifiers are currently available. |
| IBASE_UNIXTIME | Causes date and time fields not to be returned as strings, but as UNIX timestamps (the number of seconds since the epoch, which is 1-Jan-1970 0:00 UTC). Might be problematic if used with dates before 1970 on some systems. |
The following constants are used to pass requests and options to the service API functions (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() and ibase_maintain_db()). Please refer to the Firebird/InterBase manuals for the meaning of these options.
Options to ibase_backup()
Options to ibase_restore()
Options to ibase_maintain_db()
Options to ibase_db_info()
Options to ibase_server_info()
PHP 4 uses server,
dba_user_name and
dba_user_password instead of
service_handle parameter.
| Warning |
This function is currently not documented; only the argument list is available. |
This function returns the number of rows that were affected by the previous query (INSERT, UPDATE or DELETE) that was executed from within the specified transaction context.
link_identifier
A transaction context. If link_identifier is a
connection resource, its default transaction is used.
| Warning |
This function is currently not documented; only the argument list is available. |
ibase_blob_add() adds data into a blob created with ibase_blob_create().
This function will discard a BLOB if it has not yet been closed by ibase_blob_close().
This function closes a BLOB that has either been opened for reading by ibase_open_blob() or has been opened for writing by ibase_create_blob().
If the BLOB was being read, this function returns TRUE on success, if the BLOB was being written to, this function returns a string containing the BLOB id that has been assigned to it by the database. On failure, this function returns FALSE.
ibase_blob_create() creates a new BLOB for filling with data.
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
This function opens a BLOB for reading and sends its contents directly to standard output (the browser, in most cases).
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
blob_id
This function returns at most len bytes from a BLOB
that has been opened for reading by ibase_blob_open().
Note: It is not possible to read from a BLOB that has been opened for writing by ibase_blob_create().
This function creates a BLOB, reads an entire file into it, closes it and returns the assigned BLOB id.
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
file_handleThe file handle is a handle returned by fopen().
Example 1. ibase_blob_import() example
|
Returns the BLOB length and other useful information.
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
blob_idA BLOB id.
Returns an array containing information about a BLOB. The information returned consists of the length of the BLOB, the number of segments it contains, the size of the largest segment, and whether it is a stream BLOB or a segmented BLOB.
Opens an existing BLOB for reading.
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
blob_idA BLOB id.
Closes the link to an InterBase database that's associated with a connection id returned from ibase_connect(). Default transaction on link is committed, other transactions are rolled back.
connection_idAn InterBase link identifier returned from ibase_connect(). If omitted, the last opened link is assumed.
Commits a transaction without closing it.
link_or_trans_identifierIf called without an argument, this function commits the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be committed. If the argument is a transaction identifier, the corresponding transaction will be committed. The transaction context will be retained, so statements executed from within this transaction will not be invalidated.
link_or_trans_identifierIf called without an argument, this function commits the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be committed. If the argument is a transaction identifier, the corresponding transaction will be committed.
Establishes a connection to an InterBase server.
In case a second call is made to ibase_connect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned. The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling ibase_close().
database
The database argument has to be a valid path to
database file on the server it resides on. If the server is not local,
it must be prefixed with either 'hostname:' (TCP/IP), '//hostname/'
(NetBEUI) or 'hostname@' (IPX/SPX), depending on the connection
protocol used.
usernameThe user name. Can be set with the ibase.default_user php.ini directive.
password
The password for username. Can be set with the
ibase.default_password php.ini directive.
charset
charset is the default character set for a
database.
buffers
buffers is the number of database buffers to
allocate for the server-side cache. If 0 or omitted, server chooses
its own default.
dialect
dialect selects the default SQL dialect for any
statement executed within a connection, and it defaults to the highest
one supported by client libraries. Functional only with InterBase 6
and up.
roleFunctional only with InterBase 5 and up.
sync
If you get some error like "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (this occurs when you try use some character with accents) when using this and after ibase_query() you must set the character set (i.e. ISO8859_1 or your current character set).
Example 1. ibase_connect() example
|
| Warning |
This function is currently not documented; only the argument list is available. |
(PHP 4 >= 4.2.0, PHP 5)
ibase_delete_user -- Delete a user from a security database (only for IB6 or later)
PHP 4 uses server,
dba_user_name and
dba_user_password instead of
service_handle parameter.
| Warning |
This function is currently not documented; only the argument list is available. |
This functions drops a database that was opened by either ibase_connect() or ibase_pconnect(). The database is closed and deleted from the server.
Returns the error code that resulted from the most recent InterBase function call.
Returns the error message that resulted from the most recent InterBase function call.
Execute a query prepared by ibase_prepare().
This is a lot more effective than using ibase_query() if you are repeating a same kind of query several times with only some parameters changing.
If the query raises an error, returns FALSE. If it is successful and there is a (possibly empty) result set (such as with a SELECT query), returns a result identifier. If the query was successful and there were no results, returns TRUE.
Note: In PHP 5.0.0 and up, this function returns the number of rows affected by the query (if > 0 and applicable to the statement type). A query that succeeded, but did not affect any rows (e.g. an UPDATE of a non-existent record) will return TRUE.
Fetch a result row from a query as an associative array.
ibase_fetch_assoc() fetches one row of data from the
result. If two or more columns of the result
have the same field names, the last column will take precedence. To
access the other column(s) of the same name, you either need to access
the result with numeric indices by using
ibase_fetch_row() or use alias names in your query.
resultThe result handle.
fetch_flag
fetch_flag is a combination of the constants
IBASE_TEXT and IBASE_UNIXTIME
ORed together. Passing IBASE_TEXT will cause this
function to return BLOB contents instead of BLOB ids. Passing
IBASE_UNIXTIME will cause this function to return
date/time values as Unix timestamps instead of as formatted strings.
Returns an associative array that corresponds to the fetched row. Subsequent calls will return the next row in the result set, or FALSE if there are no more rows.
Fetches a row as a pseudo-object from a given result identifier.
Subsequent calls to ibase_fetch_object() return the next row in the result set.
result_idAn InterBase result identifier obtained either by ibase_query() or ibase_execute().
fetch_flag
fetch_flag is a combination of the constants
IBASE_TEXT and IBASE_UNIXTIME
ORed together. Passing IBASE_TEXT will cause this
function to return BLOB contents instead of BLOB ids. Passing
IBASE_UNIXTIME will cause this function to return
date/time values as Unix timestamps instead of as formatted strings.
ibase_fetch_row() fetches one row of data from the given result set.
Subsequent calls to ibase_fetch_row() return the next row in the result set, or FALSE if there are no more rows.
result_identifierAn InterBase result identifier.
fetch_flag
fetch_flag is a combination of the constants
IBASE_TEXT and IBASE_UNIXTIME
ORed together. Passing IBASE_TEXT will cause this
function to return BLOB contents instead of BLOB ids. Passing
IBASE_UNIXTIME will cause this function to return
date/time values as Unix timestamps instead of as formatted strings.
Returns an array that corresponds to the fetched row, or FALSE if there are no more rows. Each result column is stored in an array offset, starting at offset 0.
Returns an array with information about a field after a select query has been run.
Example 1. ibase_field_info() example
|
This function causes the registered event handler specified by
event to be cancelled. The callback function will
no longer be called for the events it was registered to handle.
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
(PHP 4 >= 4.2.0, PHP 5)
ibase_modify_user -- Modify a user to a security database (only for IB6 or later)| Warning |
This function is currently not documented; only the argument list is available. |
PHP 4 uses server,
dba_user_name and
dba_user_password instead of
service_handle parameter.
This function assigns a name to a result set. This name can be used later in
UPDATE|DELETE ... WHERE CURRENT OF name statements.
Example 1. ibase_name_result() example
|
Example 1. ibase_num_fields() example
|
This function returns the number of parameters in the prepared query specified
by query. This is the number of binding arguments that
must be present when calling ibase_execute().
Returns an array with information about a parameter after a query has been prepared.
(PHP 3 >= 3.0.6, PHP 4, PHP 5)
ibase_pconnect -- Open a persistent connection to an InterBase databaseOpens a persistent connection to an InterBase database.
ibase_pconnect() acts very much like ibase_connect() with two major differences.
First, when connecting, the function will first try to find a (persistent) link that's already opened with the same parameters. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the InterBase server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (ibase_close() will not close links established by ibase_pconnect()). This type of link is therefore called 'persistent'.
database
The database argument has to be a valid path to
database file on the server it resides on. If the server is not local,
it must be prefixed with either 'hostname:' (TCP/IP), '//hostname/'
(NetBEUI) or 'hostname@' (IPX/SPX), depending on the connection
protocol used.
usernameThe user name. Can be set with the ibase.default_user php.ini directive.
password
The password for username. Can be set with the
ibase.default_password php.ini directive.
charset
charset is the default character set for a
database.
buffers
buffers is the number of database buffers to
allocate for the server-side cache. If 0 or omitted, server chooses
its own default.
dialect
dialect selects the default SQL dialect for any
statement executed within a connection, and it defaults to the highest
one supported by client libraries. Functional only with InterBase 6
and up.
roleFunctional only with InterBase 5 and up.
sync
(PHP 3 >= 3.0.6, PHP 4, PHP 5)
ibase_prepare -- Prepare a query for later binding of parameter placeholders and executionPrepare a query for later binding of parameter placeholders and execution (via ibase_execute()).
Performs a query on an InterBase database.
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
queryAn InterBase query.
bind_args
If the query raises an error, returns FALSE. If it is successful and there is a (possibly empty) result set (such as with a SELECT query), returns a result identifier. If the query was successful and there were no results, returns TRUE.
Note: In PHP 5.0.0 and up, this function will return the number of rows affected by the query for INSERT, UPDATE and DELETE statements. In order to retain backward compatibility, it will return TRUE for these statements if the query succeeded without affecting any rows.
If you get some error like "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (this occurs when you try use some character with accents) when using this and after ibase_query() you must set the character set (i.e. ISO8859_1 or your current character set).
| Warning |
This function is currently not documented; only the argument list is available. |
Rolls back a transaction without closing it.
link_or_trans_identifierIf called without an argument, this function rolls back the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be rolled back. If the argument is a transaction identifier, the corresponding transaction will be rolled back. The transaction context will be retained, so statements executed from within this transaction will not be invalidated.
link_or_trans_identifierIf called without an argument, this function rolls back the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be rolled back. If the argument is a transaction identifier, the corresponding transaction will be rolled back.
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
This function registers a PHP user function as event handler for the specified events.
event_handlerThe callback is called with the event name and the link resource as arguments whenever one of the specified events is posted by the database.
The callback must return FALSE if the event handler should be canceled. Any other return value is ignored. This function accepts up to 15 event arguments.
event_name1An event name.
event_name2
...
The return value is an event resource. This resource can be used to free the event handler using ibase_free_event_handler().
Example 1. ibase_set_event_handler() example
|
(PHP 3 >= 3.0.6, PHP 4)
ibase_timefmt -- Sets the format of timestamp, date and time type columns returned from queriesSets the format of timestamp, date or time type columns returned from queries.
You can set defaults for these formats with the PHP configuration directives ibase.timestampformat, ibase.dateformat and ibase.timeformat.
Note: This function has been removed from PHP 5, use ini_set() instead.
formatInternally, the columns are formatted by c-function strftime(), so refer to its documentation regarding to the format of the string.
columntype
columntype is one of the constants
IBASE_TIMESTAMP, IBASE_DATE
and IBASE_TIME. If omitted, defaults to
IBASE_TIMESTAMP for backwards compatibility.
Begins a transaction.
Note: The behaviour of this function has been changed in PHP 5.0.0. The first call to ibase_trans() will not return the default transaction of a connection. All transactions started by ibase_trans() will be rolled back at the end of the script if they were not committed or rolled back by either ibase_commit() or ibase_rollback().
Note: In PHP 5.0.0. and up, this function will accept multiple
trans_argsandlink_identifierarguments. This allows transactions over multiple database connections, which are committed using a 2-phase commit algorithm. This means you can rely on the updates to either succeed in every database, or fail in every database. It does NOT mean you can use tables from different databases in the same query!If you use transactions over multiple databases, you will have to specify both the
link_idandtransaction_idin calls to ibase_query() and ibase_prepare().
trans_args
trans_args can be a combination of
IBASE_READ,
IBASE_WRITE,
IBASE_COMMITTED,
IBASE_CONSISTENCY,
IBASE_CONCURRENCY,
IBASE_REC_VERSION,
IBASE_REC_NO_VERSION,
IBASE_WAIT and
IBASE_NOWAIT.
link_identifierAn InterBase link identifier. If omitted, the last opened link is assumed.
This function suspends execution of the script until one of the specified events is posted by the database. The name of the event that was posted is returned. This function accepts up to 15 event arguments.
| Warning |
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. |
(no version information, might be only in CVS)
PDO_FIREBIRD DSN -- Connecting to Firebird and Interbase databasesThe PDO_FIREBIRD Data Source Name (DSN) is composed of the following elements:
The DSN prefix is firebird:.
The hostname on which the database server resides.
The port number for the server on which the database is running.
The name of the database.
The name of the user that will connect to the database.
The password for the user.
FriBiDi is a free implementation of the Unicode Bidirectional Algorithm.
This PECL extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/fribidi.
In order to use these functions you must compile PHP with Fribidi support
by using the --with-fribidi[=DIR]
configure option.
Windows users will enable php_fribidi.dll inside of php.ini in order to use these functions. The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Unicode
Arabic
Hebrew
Hebrew/Yiddish
Arabic
Persian
Used for test purposes, will treat CAPS as non-English letters
Right to left
Left to right
Autodetect the base direction
Converts a logical string to a vissual one.
These functions allow you to access FrontBase database servers. More information about FrontBase can be found at http://www.frontbase.com/.
Documentation for FrontBase can be found at http://www.frontbase.com/cgi-bin/WebObjects/FrontBase.woa/wa/productsPage?currentPage=Documentation.
Frontbase support has been added to PHP 4.0.6.
You must install the FrontBase database server or at least the fbsql client libraries to use this functions. You can get FrontBase from http://www.frontbase.com/.
In order to have these functions available, you must compile PHP with
fbsql support by using the
--with-fbsql[=DIR] option. If you use
this option without specifying the path to fbsql, PHP will search for the
fbsql client libraries in the default installation location for the
platform. Users who installed FrontBase in a non standard directory should
always specify the path to fbsql:
--with-fbsql=/path/to/fbsql. This will
force PHP to use the client libraries installed by FrontBase, avoiding any
conflicts.
The behaviour of these functions is affected by settings in php.ini.
Table 1. FrontBase configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| fbsql.allow_persistent | "1" | PHP_INI_SYSTEM | Available since PHP 4.2.0. |
| fbsql.generate_warnings | "0" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.autocommit | "1" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.max_persistent | "-1" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.max_links | "128" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.max_connections | "128" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.max_results | "128" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.batchSize | "1000" | PHP_INI_SYSTEM | |
| fbsql.default_host | NULL | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.default_user | "_SYSTEM" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.default_password | "" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.default_database | "" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
| fbsql.default_database_password | "" | PHP_INI_SYSTEM | Available since PHP 4.0.6. |
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
(PHP 4 >= 4.0.6, PHP 5)
fbsql_affected_rows -- Get number of affected rows in previous FrontBase operation
fbsql_affected_rows() returns the number
of rows affected by the last INSERT, UPDATE or DELETE query
associated with link_identifier.
Note: If you are using transactions, you need to call fbsql_affected_rows() after your INSERT, UPDATE, or DELETE query, not after the commit.
If the last query was a DELETE query with no WHERE clause, all of the records will have been deleted from the table but this function will return zero.
Note: When using UPDATE, FrontBase will not update columns where the new value is the same as the old value. This creates the possibility that fbsql_affected_rows() may not actually equal the number of rows matched, only the number of rows that were literally affected by the query.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns the current autocommit status.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
OnOffIf this optional parameter is given the auto commit status will be changed.
With OnOff set to TRUE each statement will be
committed automatically, if no errors was found.
With OnOff set to FALSE the user must commit or rollback the transaction using either fbsql_commit() or fbsql_rollback().
Returns the size of the given BLOB.
blob_handleA BLOB handle, returned by fbsql_create_blob().
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
(no version information, might be only in CVS)
fbsql_change_user -- Change logged in user of the active connectionfbsql_change_user() changes the logged in user of the specified connection. If the new user and password authorization fails, the current connected user stays active.
userThe new user name.
passwordThe new user password.
databaseIf specified, this will be the default or current database after the user has been changed.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns the size of the given CLOB.
clob_handleA CLOB handle, returned by fbsql_create_clob().
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Closes the connection to the FrontBase server that's associated with the specified link identifier.
Using fbsql_close() isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Ends the current transaction by writing all inserts, updates and deletes to the disk and unlocking all row and table locks held by the transaction. This command is only needed if autocommit is set to false.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
fbsql_connect() establishes a connection to a FrontBase server.
If a second call is made to fbsql_connect() with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned.
The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling fbsql_close().
hostnameThe server host name. Defaults to 'NULL'.
usernameThe user name for the connection. Defaults to _SYSTEM.
passwordThe user name for the connection. Defaults to the empty string.
Creates a BLOB from the given data.
blob_dataThe BLOB data.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns a resource handle to the newly created BLOB, which can be used with insert and update commands to store the BLOB in the database.
Example 1. fbsql_create_blob() example
|
Creates a CLOB from the given data.
clob_dataThe CLOB data.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns a resource handle to the newly created CLOB, which can be used with insert and update commands to store the CLOB in the database.
Example 1. fbsql_create_clob() example
|
Attempts to create a new database on the specied server.
database_nameThe database name, as a string.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
database_options
Moves the internal row pointer of the FrontBase result associated with the specified result identifier to point to the specified row number.
The next call to fbsql_fetch_row() would return that row.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
row_numberThe row number. Starts at 0.
Example 1. fbsql_data_seek() example
|
(PHP 4 >= 4.0.6, PHP 5)
fbsql_database_password -- Sets or retrieves the password for a FrontBase databaseSets and retrieves the database password used by the connection. If a database is protected by a database password, the user must call this function before calling fbsql_select_db().
If no link is open, the function will try to establish a link as if fbsql_connect() was called, and use it.
This function does not change the database password in the database nor can it be used to retrieve the database password for a database.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
database_passwordThe database password, as a string. If given, the function sets the database password for the specified link identifier.
Example 1. fbsql_create_clob() example
|
Get or set the database name used with the connection.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
database
The database name. If given, the default database of the connexion
will be changed to database.
Selects a database and executes a query on it.
databaseThe database to be selected.
queryThe SQL query to be executed.
Note: The query string shall always end with a semicolon.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns a positive FrontBase result identifier to the query result, or FALSE on error.
Gets the current status of the specified database.
database_nameThe database name.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns an integer value with the current status. This can be one of the following constants:
FALSE - The exec handler for the host was invalid. This error will
occur when the link_identifier connects directly
to a database by using a port number. FBExec can be available on the
server but no connection has been made for it.
FBSQL_UNKNOWN - The Status is unknown.
FBSQL_STOPPED - The database is not running. Use fbsql_start_db() to start the database.
FBSQL_STARTING - The database is starting.
FBSQL_RUNNING - The database is running and can be used to perform SQL operations.
FBSQL_STOPPING - The database is stopping.
FBSQL_NOEXEC - FBExec is not running on the server and it is not possible to get the status of the database.
fbsql_drop_db() attempts to drop (remove) an entire database from the server associated with the specified link identifier.
database_nameThe database name, as a string.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns the numerical value of the error message from previous FrontBase operation.
Errors coming back from the fbsql database backend don't issue warnings. Instead, use fbsql_errno() to retrieve the error code. Note that this function only returns the error code from the most recently executed fbsql function (not including fbsql_error() and fbsql_errno()), so if you want to use it, make sure you check the value before calling another fbsql function.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns the error number from the last fbsql function, or 0 (zero) if no error occurred.
Example 1. fbsql_errno() Example
|
Returns the error message from previous FrontBase operation.
Errors coming back from the fbsql database backend don't issue warnings. Instead, use fbsql_error() to retrieve the error text. Note that this function only returns the error code from the most recently executed fbsql function (not including fbsql_error() and fbsql_errno()), so if you want to use it, make sure you check the value before calling another fbsql function.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns the error text from the last fbsql function, or '' (the empty string) if no error occurred.
Example 1. fbsql_error() Example
|
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_array -- Fetch a result row as an associative array, a numeric array, or bothfbsql_fetch_array() is a combination of fbsql_fetch_row() and fbsql_fetch_assoc().
An important thing to note is that using fbsql_fetch_array() is NOT significantly slower than using fbsql_fetch_row(), while it provides a significant added value.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
result_typeA constant and can take the following values: FBSQL_ASSOC, FBSQL_NUM, or FBSQL_BOTH.
When using FBSQL_BOTH, in addition to storing the data in the numeric indices of the result array, it also stores the data in associative indices, using the field names as keys.
Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must the numeric index of the column or make an alias for the column.
Example 1. fbsql_fetch_array() example
|
Calling fbsql_fetch_assoc() is equivalent to calling fbsql_fetch_array() with FBSQL_ASSOC as second parameter. It only returns an associative array.
This is the way fbsql_fetch_array() originally worked. If you need the numeric indices as well as the associative, use fbsql_fetch_array().
An important thing to note is that using fbsql_fetch_assoc() is NOT significantly slower than using fbsql_fetch_row(), while it provides a significant added value.
Returns an associative array that corresponds to the fetched row, or FALSE if there are no more rows.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must use fbsql_fetch_array() and have it return the numeric indices as well.
(PHP 4 >= 4.0.6, PHP 5)
fbsql_fetch_field -- Get column information from a result and return as an objectUsed in order to obtain information about fields in a certain query result.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
field_offsetThe numerical offset of the field. The field index starts at 0. If not specified, the next field that wasn't yet retrieved by fbsql_fetch_field() is retrieved.
Returns an object containing field information, or FALSE on errors.
The properties of the object are:
name - column name
table - name of the table the column belongs to
max_length - maximum length of the column
not_null - 1 if the column cannot be NULL
type - the type of the column
Example 1. fbsql_fetch_field() example
|
Stores the lengths of each result column in the last row returned by fbsql_fetch_row(), fbsql_fetch_array() and fbsql_fetch_object() in an array.
Returns an array, starting at offset 0, that corresponds to the lengths of each field in the last row fetched by fbsql_fetch_row(), or FALSE on error.
fbsql_fetch_object() is similar to fbsql_fetch_array(), with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property names).
Speed-wise, the function is identical to fbsql_fetch_array(), and almost as quick as fbsql_fetch_row() (the difference is insignificant).
Returns an object with properties that correspond to the fetched row, or FALSE if there are no more rows.
fbsql_fetch_row() fetches one row of data from the result associated with the specified result identifier.
Subsequent call to fbsql_fetch_row() would return the next row in the result set, or FALSE if there are no more rows.
Returns an array that corresponds to the fetched row where each result column is stored in an offset, starting at offset 0, or FALSE if there are no more rows.
| fbsql_fetch_array() |
| fbsql_fetch_assoc() |
| fbsql_fetch_object() |
| fbsql_data_seek() |
| fbsql_fetch_lengths() |
| fbsql_result() |
(PHP 4 >= 4.0.6, PHP 5)
fbsql_field_flags -- Get the flags associated with the specified field in a resultGets the flags associated with the specified field in a result.
resultA result pointer returned by fbsql_list_fields().
field_offsetThe numerical offset of the field. The field index starts at 0.
Returns the field flags of the specified field as a single word per flag separated by a single space, so that you can split the returned value using explode().
Returns the length of the specified field.
resultA result pointer returned by fbsql_list_fields().
field_offsetThe numerical offset of the field. The field index starts at 0.
Returns the name of the specified field index.
resultA result pointer returned by fbsql_list_fields().
field_indexThe numerical offset of the field. The field index starts at 0.
Example 1. fbsql_field_name() example
The above example will output:
|
Seeks to the specified field offset. If the next call to fbsql_fetch_field() doesn't include a field offset, the field offset specified in fbsql_field_seek() will be returned.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
field_offsetThe numerical offset of the field. The field index starts at 0.
Returns the name of the table that the specified field is in.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
field_offsetThe numerical offset of the field. The field index starts at 0.
fbsql_field_type() is similar to the fbsql_field_name() function, but the field type is returned instead.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
field_offsetThe numerical offset of the field. The field index starts at 0.
Returns the field type, as a string.
This can be one of int, real, string, blob, and others as detailed in the FrontBase documentation.
Example 1. fbsql_field_type() example
|
Frees all memory associated with the given result
identifier.
fbsql_free_result() only needs to be called if you are concerned about how much memory is being used for queries that return large result sets. All associated result memory is automatically freed at the end of the script's execution.
| Warning |
This function is currently not documented; only the argument list is available. |
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Gets or sets the host name used with a connection.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
host_nameIf provided, this will be the new connection host name.
Gets the id generated from the previous INSERT operation which created a DEFAULT UNIQUE value.
Note: The value of the FrontBase SQL function fbsql_insert_id() always contains the most recently generated DEFAULT UNIQUE value, and is not reset between queries.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns the ID generated from the previous INSERT query, or 0 if the previous query does not generate an DEFAULT UNIQUE value.
If you need to save the value for later, be sure to call this function immediately after the query that generates the value.
Return a result pointer containing the databases available from the current fbsql daemon. Use the fbsql_tablename() to traverse this result pointer.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Note: The above code would just as easily work with fbsql_fetch_row() or other similar functions.
Retrieves information about the given table.
database_nameThe database name.
table_nameThe table name.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns a result pointer which can be used with the fbsql_field_xxx functions, or FALSE on error.
A string describing the error will be placed in $phperrmsg, and unless the function was called as @fbsql() then this error string will also be printed out.
Example 1. fbsql_list_fields() example
The above example will output something similar to:
|
Returns a result pointer describing the database.
databaseThe database name.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Returns a result pointer which can be used with the fbsql_tablename() function to read the actual table names, or FALSE on error.
When sending more than one SQL statement to the server or executing a stored procedure with multiple results will cause the server to return multiple result sets. This function will test for additional results available form the server. If an additional result set exists it will free the existing result set and prepare to fetch the words from the new result set.
Example 1. fbsql_next_result() example
|
Returns the number of fields in the given result
set.
Gets the number of rows in the given result set.
This function is only valid for SELECT statements. To retrieve the number of rows returned from a INSERT, UPDATE or DELETE query, use fbsql_affected_rows().
Get or set the user password used with a connection.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
passwordIf provided, this will be the new connection password.
Establishes a persistent connection to a FrontBase server.
To set the server port number, use fbsql_select_db().
fbsql_pconnect() acts very much like fbsql_connect() with two major differences:
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use.
This type of links is therefore called 'persistent'.
hostnameThe server host name. Defaults to localhost.
usernameThe user name for the connection. Defaults to _SYSTEM.
passwordThe password for the connection. Defaults to the empty string.
Returns a positive FrontBase persistent link identifier on success, or FALSE on error.
Sends a query to the currently active database on
the server.
If the query succeeds, you can call fbsql_num_rows() to find out how many rows were returned for a SELECT statement or fbsql_affected_rows() to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.
queryThe SQL query to be executed.
Note: The query string shall always end with a semicolon.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
batch_size
fbsql_query() returns TRUE (non-zero) or FALSE to indicate whether or not the query succeeded. A return value of TRUE means that the query was legal and could be executed by the server. It does not indicate anything about the number of rows affected or returned. It is perfectly possible for a query to succeed but affect no rows or return no rows.
For SELECT statements, fbsql_query() returns a new result identifier that you can pass to fbsql_result().
fbsql_query() will also fail and return FALSE if you don't have permission to access the table(s) referenced by the query.
The following query is syntactically invalid, so fbsql_query() fails and returns FALSE:
The following query is semantically invalid if my_col is not a column in the table my_tbl, so fbsql_query() fails and returns FALSE:
| fbsql_affected_rows() |
| fbsql_db_query() |
| fbsql_free_result() |
| fbsql_result() |
| fbsql_select_db() |
| fbsql_connect() |
Reads BLOB data from the database.
If a select statement contains BLOB and/or CLOB columns FrontBase will return the data directly when data is fetched. This default behavior can be changed with fbsql_set_lob_mode() so the fetch functions will return handles to BLOB and CLOB data. If a handle is fetched a user must call fbsql_read_blob() to get the actual BLOB data from the database.
blob_handleA BLOB handle, returned by fbsql_create_blob().
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Example 1. fbsql_read_blob() example
|
Reads CLOB data from the database.
If a select statement contains BLOB and/or CLOB columns FrontBase will return the data directly when data is fetched. This default behavior can be changed with fbsql_set_lob_mode() so the fetch functions will return handles to BLOB and CLOB data. If a handle is fetched a user must call fbsql_read_clob() to get the actual CLOB data from the database.
clob_handleA CLOB handle, returned by fbsql_create_clob().
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Example 1. fbsql_read_clob() example
|
Returns the contents of one cell from a FrontBase
result set.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than fbsql_result().
Calls to fbsql_result() should not be mixed with calls to other functions that deal with the result set.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
row
fieldCan be the field's offset, or the field's name, or the field's table dot field's name (tabledname.fieldname).
If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name.
Note: Specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.
Recommended high-performance alternatives:
| fbsql_fetch_row() |
| fbsql_fetch_array() |
| fbsql_fetch_assoc() |
| fbsql_fetch_object() |
Ends the current transaction by rolling back all statements issued since last commit.
This command is only needed if autocommit is set to false.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
Gets the number of rows affected by the last statement.
Sets the current active database on the given link identifier.
The client contacts FBExec to obtain the port number to use for the connection to the database. If the database name is a number the system will use that as a port number and it will not ask FBExec for the port number. The FrontBase server can be stared as FRontBase -FBExec=No -port=<port number> <database name>.
Every subsequent call to fbsql_query() will be made on the active database.
database_nameThe name of the database to be selected.
If the database is protected with a database password, the you must call fbsql_database_password() before selecting the database.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
| Warning |
This function is currently not documented; only the argument list is available. |
Sets the mode for retrieving LOB data from the database.
When BLOB and CLOB data is retrieved in FrontBase it can be retrieved direct or indirect. Direct retrieved LOB data will always be fetched no matter the setting of the lob mode. If the LOB data is less than 512 bytes it will always be retrieved directly.
resultA result identifier returned by fbsql_query() or fbsql_db_query().
lob_modeCan be one of:
FBSQL_LOB_DIRECT - LOB data is retrieved directly. When data is fetched from the database with fbsql_fetch_row(), and other fetch functions, all CLOB and BLOB columns will be returned as ordinary columns. This is the default value on a new FrontBase result.
FBSQL_LOB_HANDLE - LOB data is retrieved as handles to the data. When data is fetched from the database with fbsql_fetch_row(), and other fetch functions, LOB data will be returned as a handle to the data if the data is stored indirect or the data if it is stored direct. If a handle is returned it will be a 27 byte string formatted as @'000000000000000000000000'.
Changes the password for the given user.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
userThe user name.
passwordThe new password to be set.
old_passwordThe old password to be replaced.
Sets the transaction locking and
isolation.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
lockingThe type of locking to be set. It can be one of the following constants: FBSQL_LOCK_DEFERRED, FBSQL_LOCK_OPTIMISTIC, or FBSQL_LOCK_PESSIMISTIC.
isolationThe type of isolation to be set. It can be one of the following constants: FBSQL_ISO_READ_UNCOMMITTED, FBSQL_ISO_READ_COMMITTED, FBSQL_ISO_REPEATABLE_READ, FBSQL_ISO_SERIALIZABLE, or FBSQL_ISO_VERSIONED.
Start a database on local or remote server.
database_nameThe database name.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
database_options
Stops a database on local or remote server.
database_nameThe database name.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
fbsql_table_name() gets the name of the current table in
the given result set.
The fbsql_num_rows() function may be used to determine the number of tables in the result pointer.
resultA result pointer returned by fbsql_list_tables().
indexInteger index for the current table.
Get or set the username used for the connection.
link_identifierA FrontBase link identifier returned by fbsql_connect() or fbsql_pconnect().
If optional and not specified, the function will try to find an open link to the FrontBase server and if no such link is found it will try to create one as if fbsql_connect() was called with no arguments
usernameIf provided, this is the new username to set.
The functions in this extension implement client access to file servers speaking the File Transfer Protocol (FTP) as defined in http://www.faqs.org/rfcs/rfc959. This extension is meant for detailed access to an FTP server providing a wide range of control to the executing script. If you only wish to read from or write to a file on an FTP server, consider using the ftp:// wrapper with the filesystem functions which provide a simpler and more intuitive interface.
In order to use FTP functions with your PHP configuration, you should
add the --enable-ftp option when
installing PHP 4 or greater or --with-ftp
when using PHP 3.
The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.
This extension uses one resource type, which is the link identifier of the FTP connection, returned by ftp_connect() or ftp_ssl_connect().
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The following constants were introduced in PHP 4.3.0.
See ftp_set_option() for information.
Automatically determine resume position and start position for GET and PUT requests (only works if FTP_AUTOSEEK is enabled)
Asynchronous transfer has failed
Asynchronous transfer has finished
Asynchronous transfer is still active
Example 1. FTP example
|
Sends an ALLO command to the remote FTP server to allocate space for a file to be uploaded.
Note: Many FTP servers do not support this command. These servers may return a failure code (FALSE) indicating the command is not supported or a success code (TRUE) to indicate that pre-allocation is not necessary and the client should continue as though the operation were successful. Because of this, it may be best to reserve this function for servers which explicitly require preallocation.
ftp_streamThe link identifier of the FTP connection.
fileziseThe number of bytes to allocate.
return
A textual representation of the servers response will be returned by
reference in result if a variable is provided.
Example 1. ftp_alloc() example
|
Example 1. ftp_cdup() example
|
Changes the current directory to the specified one.
Returns TRUE on success or FALSE on failure. If changing directory fails, PHP will also throw a warning.
Example 1. ftp_chdir() example
|
Sets the permissions on the specified remote file to
mode.
ftp_streamThe link identifier of the FTP connection.
modeThe new permissions, given as an octal value.
filenameThe remote file.
Example 1. ftp_chmod() example
|
ftp_close() closes the given link identifier and releases the resource.
Note: After calling this function, you can no longer use the FTP connection and must create a new one with ftp_connect().
Example 1. ftp_close() example
|
ftp_connect() opens an FTP connection to the
specified host.
hostThe FTP server address. This parameter shouldn't have any trailing slashes and shouldn't be prefixed with ftp://.
portThis parameter specifies an alternate port to connect to. If it is omitted or set to zero, then the default FTP port, 21, will be used.
timeoutThis parameter specifies the timeout for all subsequent network operations. If omitted, the default value is 90 seconds. The timeout can be changed and queried at any time with ftp_set_option() and ftp_get_option().
ftp_delete() deletes the file specified by
path from the FTP server.
Example 1. ftp_delete() example
|
Sends a SITE EXEC command request to the FTP
server.
Returns TRUE if the command was successful (server sent response code: 200); otherwise returns FALSE.
Example 1. ftp_exec() example
|
(PHP 3 >= 3.0.13, PHP 4, PHP 5)
ftp_fget -- Downloads a file from the FTP server and saves to an open file
ftp_fget() retrieves remote_file
from the FTP server, and writes it to the given file pointer.
ftp_streamThe link identifier of the FTP connection.
handleAn open file pointer in which we store the data.
remote_fileThe remote file path.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
resumeposThe position in the remote file to start downloading from.
Example 1. ftp_fget() example
|
ftp_fput() uploads the data from a file pointer to a remote file on the FTP server.
ftp_streamThe link identifier of the FTP connection.
remote_fileThe remote file path.
handleAn open file pointer on the local file. Reading stops at end of file.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
startpos
Example 1. ftp_fput() example
|
(PHP 4 >= 4.2.0, PHP 5)
ftp_get_option -- Retrieves various runtime behaviours of the current FTP stream
This function returns the value for the requested
option from the specified FTP connection.
Returns the value on success or FALSE if the given
option is not supported. In the latter case, a
warning message is also thrown.
ftp_get() retrieves a remote file from the FTP server, and saves it into a local file.
ftp_streamThe link identifier of the FTP connection.
local_fileThe local file path (will be overwritten if the file already exists).
remote_fileThe remote file path.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
resumeposThe position in the remote file to start downloading from.
Example 1. ftp_get() example
|
Logs in to the given FTP stream.
ftp_streamThe link identifier of the FTP connection.
usernameThe username (USER).
passwordThe password (PASS).
Returns TRUE on success or FALSE on failure. If login fails, PHP will also throw a warning.
Example 1. ftp_login() example
|
ftp_mdtm() gets the last modified time for a remote file.
Note: Not all servers support this feature!
Note: ftp_mdtm() does not work with directories.
ftp_streamThe link identifier of the FTP connection.
remote_fileThe file from which to extract the last modification time.
Example 1. ftp_mdtm() example
|
Creates the specified directory on the FTP server.
ftp_streamThe link identifier of the FTP connection.
directoryThe name of the directory that will be created.
Example 1. ftp_mkdir() example
|
Continues retrieving/sending a file non-blocking.
Example 1. ftp_nb_continue() example
|
(PHP 4 >= 4.3.0, PHP 5)
ftp_nb_fget -- Retrieves a file from the FTP server and writes it to an open file (non-blocking)ftp_nb_fget() retrieves a remote file from the FTP server.
The difference between this function and ftp_fget() is that this function retrieves the file asynchronously, so your program can perform other operations while the file is being downloaded.
ftp_streamThe link identifier of the FTP connection.
handleAn open file pointer in which we store the data.
remote_fileThe remote file path.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
resumepos
Example 1. ftp_nb_fget() example
|
(PHP 4 >= 4.3.0, PHP 5)
ftp_nb_fput -- Stores a file from an open file to the FTP server (non-blocking)ftp_nb_fput() uploads the data from a file pointer to a remote file on the FTP server.
The difference between this function and the ftp_fput() is that this function uploads the file asynchronously, so your program can perform other operations while the file is being uploaded.
ftp_streamThe link identifier of the FTP connection.
remote_fileThe remote file path.
handleAn open file pointer on the local file. Reading stops at end of file.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
startpos
Example 1. ftp_nb_fput() example
|
(PHP 4 >= 4.3.0, PHP 5)
ftp_nb_get -- Retrieves a file from the FTP server and writes it to a local file (non-blocking)ftp_nb_get() retrieves a remote file from the FTP server, and saves it into a local file.
The difference between this function and ftp_get() is that this function retrieves the file asynchronously, so your program can perform other operations while the file is being downloaded.
ftp_streamThe link identifier of the FTP connection.
local_fileThe local file path (will be overwritten if the file already exists).
remote_fileThe remote file path.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
resumepos
Example 1. ftp_nb_get() example
|
Example 2. Resuming a download with ftp_nb_get()
|
Example 3. Resuming a download at position 100 to a new file with ftp_nb_get()
|
In the example above, newfile is 100 bytes smaller than README on the FTP server because we started reading at offset 100. If we didn't disable FTP_AUTOSEEK, the first 100 bytes of newfile would be '\0'.
ftp_nb_put() stores a local file on the FTP server.
The difference between this function and the ftp_put() is that this function uploads the file asynchronously, so your program can perform other operations while the file is being uploaded.
ftp_streamThe link identifier of the FTP connection.
remote_fileThe remote file path.
local_fileThe local file path.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
startpos
Example 1. ftp_nb_put() example
|
Example 2. Resuming an upload with ftp_nb_put()
|
ftp_streamThe link identifier of the FTP connection.
directoryThe directory to be listed. This parameter can also include arguments, eg. ftp_nlist($conn_id, "-la /your/dir"); Note that this parameter isn't escaped so there may be some issues with filenames containing spaces and other characters.
Returns an array of filenames from the specified directory on success or FALSE on error.
Example 1. ftp_nlist() example
The above example will output something similar to:
|
ftp_pasv() turns on or off passive mode. In passive mode, data connections are initiated by the client, rather than by the server. It may be needed if the client is behind firewall.
ftp_streamThe link identifier of the FTP connection.
pasvIf TRUE, the passive mode is turned on, else it's turned off.
Example 1. ftp_pasv() example
|
ftp_put() stores a local file on the FTP server.
ftp_streamThe link identifier of the FTP connection.
remote_fileThe remote file path.
local_fileThe local file path.
modeThe transfer mode. Must be either FTP_ASCII or FTP_BINARY.
startpos
Example 1. ftp_put() example
|
Example 1. ftp_pwd() example
|
Sends an arbitrary command to the FTP server.
Returns the server's response as an array of strings. No parsing is performed on the response string, nor does ftp_raw() determine if the command succeeded.
(PHP 3 >= 3.0.13, PHP 4, PHP 5)
ftp_rawlist -- Returns a detailed list of files in the given directoryftp_rawlist() executes the FTP LIST command, and returns the result as an array.
ftp_streamThe link identifier of the FTP connection.
directoryThe directory path.
recursiveIf set to TRUE, the issued command will be LIST -R.
Returns an array where each element corresponds to one line of text.
The output is not parsed in any way. The system type identifier returned by ftp_systype() can be used to determine how the results should be interpreted.
Example 1. ftp_rawlist() example
The above example will output something similar to:
|
ftp_rename() renames a file or a directory on the FTP server.
ftp_streamThe link identifier of the FTP connection.
oldnameThe old file/directory name.
newnameThe new name.
Example 1. ftp_rename() example
|
Removes the specified directory on the FTP server.
ftp_streamThe link identifier of the FTP connection.
directoryThe directory to delete. This must be either an absolute or relative path to an empty directory.
Example 1. ftp_rmdir() example
|
This function controls various runtime options for the specified FTP stream.
ftp_streamThe link identifier of the FTP connection.
optionCurrently, the following options are supported:
Table 1. Supported runtime FTP options
| FTP_TIMEOUT_SEC |
Changes the timeout in seconds used for all network related
functions. value must be an integer that
is greater than 0. The default timeout is 90 seconds.
|
| FTP_AUTOSEEK |
When enabled, GET or PUT requests with a
resumepos or startpos
parameter will first seek to the requested position within the file.
This is enabled by default.
|
value
This parameter depends on which option is chosen
to be altered.
Returns TRUE if the option could be set; FALSE if not. A warning
message will be thrown if the option is not
supported or the passed value doesn't match the
expected value for the given option.
ftp_site() sends the given SITE command to the FTP server.
SITE commands are not standardized, and vary from server to server. They are useful for handling such things as file permissions and group membership.
ftp_streamThe link identifier of the FTP connection.
commandThe SITE command. Note that this parameter isn't escaped so there may be some issues with filenames containing spaces and other characters.
Example 1. Sending a SITE command to an ftp server
|
ftp_size() returns the size of the given file in bytes.
Note: Not all servers support this feature.
Example 1. ftp_size() example
|
ftp_ssl_connect() opens a SSL-FTP connection to the
specified host.
Why this function may not exist: ftp_ssl_connect() is only available if OpenSSL support is enabled into your version of PHP. If it's undefined and you've compiled FTP support then this is why. For Windows you must compile your own PHP binaries to support this function.
hostThe FTP server address. This parameter shouldn't have any trailing slashes and shouldn't be prefixed with ftp://.
portThis parameter specifies an alternate port to connect to. If it is omitted or set to zero, then the default FTP port, 21, will be used.
timeoutThis parameter specifies the timeout for all subsequent network operations. If omitted, the default value is 90 seconds. The timeout can be changed and queried at any time with ftp_set_option() and ftp_get_option().
(PHP 3 >= 3.0.13, PHP 4, PHP 5)
ftp_systype -- Returns the system type identifier of the remote FTP serverReturns the system type identifier of the remote FTP server.
Example 1. ftp_systype() example
The above example will output something similar to:
|
These functions all handle various operations involved in working with functions.
(PHP 4 >= 4.0.4, PHP 5)
call_user_func_array -- Call a user function given with an array of parameters
Call a user defined function with the parameters in
param_arr.
functionThe function to be called.
param_arrThe parameters to be passed to the function, as an indexed array.
Example 1. call_user_func_array() example
|
Call a user defined function given by the function
parameter.
functionThe function to be called. Class methods may also be invoked statically using this function by passing array($classname, $methodname) to this parameter.
parameterZero or more parameters to be passed to the function.
Creates an anonymous function from the parameters passed, and returns a unique name for it.
Usually these parameters will be passed as single quote delimited strings. The reason for using single quoted strings, is to protect the variable names from parsing, otherwise, if you use double quotes there will be a need to escape the variable names, e.g. \$avar.
argsThe function arguments.
codeThe function code.
Example 1. Creating an anonymous function with create_function() You can use this function, to (for example) create a function from information gathered at run time:
|
Or, perhaps to have general handler function that can apply a set of operations to a list of parameters:
Example 2. Making a general processing function with create_function()
The above example will output:
|
But perhaps the most common use for of lambda-style (anonymous) functions is to create callback functions, for example when using array_walk() or usort()
Example 3. Using anonymous functions as callback functions
The above example will output:
an array of strings ordered from shorter to longer
The above example will output:
sort it from longer to shorter
The above example will output:
|
Gets the specified argument from a user-defined function's argument list.
This function may be used in conjunction with func_get_args() and func_num_args() to allow user-defined functions to accept variable-length argument lists.
Generates a warning if called from outside of a user-defined function, or
if arg_num is greater than the number of arguments
actually passed.
Note: Because this function depends on the current scope to determine parameter details, it cannot be used as a function parameter. If you must pass this value, assign the results to a variable, and pass the variable.
Note: This function returns a copy of the passed arguments only, and does not account for default (non-passed) arguments.
Gets an array of the function's argument list.
This function may be used in conjunction with func_get_arg() and func_num_args() to allow user-defined functions to accept variable-length argument lists.
Returns an array in which each element is a copy of the corresponding member of the current user-defined function's argument list.
Example 1. func_get_args() example
|
Note: Because this function depends on the current scope to determine parameter details, it cannot be used as a function parameter. If you must pass this value, assign the results to a variable, and pass the variable.
Note: This function returns a copy of the passed arguments only, and does not account for default (non-passed) arguments.
Gets the number of arguments passed to the function.
This function may be used in conjunction with func_get_arg() and func_get_args() to allow user-defined functions to accept variable-length argument lists.
Note: Because this function depends on the current scope to determine parameter details, it cannot be used as a function parameter. If you must pass this value, assign the results to a variable, and pass the variable.
Checks the list of defined functions, both built-in (internal) and
user-defined, for function_name.
Returns TRUE if function_name exists and is a
function, FALSE otherwise.
Note: This function will return FALSE for constructs, such as include_once() and echo().
Note: A function name may exist even if the function itself is unusable due to configuration or compiling options (with the image functions being an example).
Returns an multidimensional array containing a list of all defined
functions, both built-in (internal) and user-defined. The internal
functions will be accessible via $arr["internal"], and
the user defined ones using $arr["user"] (see example
below).
Example 1. get_defined_functions() example
The above example will output something similar to:
|
(PHP 3 >= 3.0.4, PHP 4, PHP 5)
register_shutdown_function -- Register a function for execution on shutdown
Registers the function named by function to be
executed when script processing is complete.
Multiple calls to register_shutdown_function() can be made, and each will be called in the same order as they were registered. If you call exit() within one registered shutdown function, processing will stop completely and no other registered shutdown functions will be called.
In PHP 4.0.6 and earlier under Apache, the registered shutdown functions are called after the request has been completed (including sending any output buffers), so it is not possible to send output to the browser using echo() or print(), or retrieve the contents of any output buffers using ob_get_contents(). Since PHP 4.1, the shutdown functions are called as the part of the request so that it's possible to send the output from them. There is currently no way to process the data with output buffering functions in the shutdown function. Shutdown function is called after closing all opened output buffers thus, for example, its output will not be compressed if zlib.output_compression is enabled.
As of PHP 4, it is possible to pass parameters to the shutdown function by passing additional parameters to register_shutdown_function().
Note: Typically undefined functions cause fatal errors in PHP, but when the
functioncalled with register_shutdown_function() is undefined, an error of level E_WARNING is generated instead. Also, for reasons internal to PHP, this error will refer to Unknown at line #0.
Note: Working directory of the script can change inside the shutdown function under some web servers, e.g. Apache.
Note: Shutdown function is called during the script shutdown so headers are always already sent.
Registers the given function to be executed when a
tick is called.
functionThe function name as a string, or an array consisting of an object and a method.
arg
...
| Warning |
register_tick_function() should not be used with threaded web server modules. Ticks are not working in ZTS mode and may crash your web server. |
(PHP 4 >= 4.0.3, PHP 5)
unregister_tick_function -- De-register a function for execution on each tick
De-registers the function named by function_name so it is
no longer executed when a tick is
called.
The GeoIP extension allows you to find the location of an IP address. City, State, Country, Longitude, Latitude, and other information as all, such as ISP and connection type can be obtained with the help of GeoIP.
This extension requires the GeoIP C library version 1.4.0 or higher to be installed. You can grab the latest version from http://www.maxmind.com/app/c and compile it yourself.
By default, you will only have access to the Free GeoIP Country or GeoLite City databases. While this module can work with other types of database, you must buy a commercial license from Maxmind.
This PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/geoip.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The following constants are for net speed:
(no version information, might be only in CVS)
geoip_country_code_by_name -- Get the two letter country codeThe geoip_country_code_by_name() function will return the two letter country code corresponding to a hostname or an IP address.
Returns the two letter ISO country code on success, or FALSE if the address cannot be found in the database.
(no version information, might be only in CVS)
geoip_country_code3_by_name -- Get the three letter country codeThe geoip_country_code3_by_name() function will return the three letter country code corresponding to a hostname or an IP address.
Returns the three letter country code on success, or FALSE if the address cannot be found in the database.
(no version information, might be only in CVS)
geoip_country_name_by_name -- Get the full country nameThe geoip_country_name_by_name() function will return the full country name corresponding to a hostname or an IP address.
Returns the country name on success, or FALSE if the address cannot be found in the database.
Example 1. A geoip_country_name_by_name() example This will print where the host example.com is located.
The above example will output:
|
The geoip_database_info() function returns the corresponding GeoIP Database version as it is defined inside the binary file.
If this function is called without arguments, it returns the version of the GeoIP Free Country Edition.
databaseThe database type as an integer. You can use the various constants defined with this extension (ie: GEOIP_*_EDITION).
Example 1. A geoip_region_by_name() example This will output the current database version string.
The above example will output:
|
The geoip_id_by_name() function will return the country and region corresponding to a hostname or an IP address.
The return value is numeric and can be compared to the following constants:
GEOIP_UNKNOWN_SPEED
GEOIP_DIALUP_SPEED
GEOIP_CABLEDSL_SPEED
GEOIP_CORPORATE_SPEED
Example 1. A geoip_id_by_name() example This will output the net speed of the host example.com.
The above example will output:
|
The geoip_org_by_name() function will return the name of the organization that an IP is assigned to.
This function is currently only available to users who have bought a commercial GeoIP Organization, ISP or AS Edition. A warning will be issued if the proper database cannot be located.
Returns the organization name on success, or FALSE if the address cannot be found in the database.
Example 1. A geoip_org_by_name() example This will print to whom the host example.com IP is allocated.
The above example will output:
|
(no version information, might be only in CVS)
geoip_record_by_name -- Returns the detailed City information found in the GeoIP DatabaseThe geoip_record_by_name() function will return the record information corresponding to a hostname or an IP address.
This function is available for both GeoLite City Edition and commercial GeoIP City Edition. A warning will be issued if the proper database cannot be located.
The names of the different keys of the returning associative array are as follows:
"country_code" -- Two letter country code (see geoip_country_code_by_name())
"region" -- The region code (ex: CA for California)
"city" -- The city.
"postal_code" -- The Postal Code, FSA or Zip Code.
"latitude" -- The Latitude as signed double.
"longitude" -- The Longitude as signed double.
"dma_code"
"area_code" -- The PSTN area code (ex: 212)
Returns the associative array on success, or FALSE if the address cannot be found in the database.
Example 1. A geoip_record_by_name() example This will print the array containing the record of host example.com.
The above example will output:
|
(no version information, might be only in CVS)
geoip_region_by_name -- Get the country code and regionThe geoip_region_by_name() function will return the country and region corresponding to a hostname or an IP address.
This function is currently only available to users who have bought a commercial GeoIP Region Edition. A warning will be issued if the proper database cannot be located.
The names of the different keys of the returning associative array are as follows:
"country_code" -- Two letter country code (see geoip_country_code_by_name())
"region" -- The region code (ex: CA for California)
Returns the associative array on success, or FALSE if the address cannot be found in the database.
Example 1. A geoip_region_by_name() example This will print the array containing the country code and region of the host example.com.
The above example will output:
|
The gettext functions implement an NLS (Native Language Support) API which can be used to internationalize your PHP applications. Please see the gettext documentation for your system for a thorough explanation of these functions or view the docs at http://www.gnu.org/software/gettext/manual/gettext.html.
To use these functions you must download and install the GNU gettext package from http://www.gnu.org/software/gettext/gettext.html
To include GNU gettext support in your PHP build you must add the option
--with-gettext[=DIR] where DIR is the
gettext install directory, defaults to /usr/local.
(PHP 4 >= 4.2.0, PHP 5)
bind_textdomain_codeset -- Specify the character encoding in which the messages from the DOMAIN message catalog will be returned
With bind_textdomain_codeset(), you can set in which
encoding will be messages from domain returned by
gettext() and similar functions.
The bindtextdomain() function sets the path for a domain.
This function allows you to override the current domain for a single message lookup.
This function allows you to override the current domain for a single plural message lookup.
The dgettext() function allows you to override
the current domain for a single message lookup.
The dngettext() function allows you to override
the current domain for a single plural message lookup.
Returns a translated string if one is found in the translation table, or the submitted message if not found.
Example 1. gettext()-check
|
The plural version of gettext(). Some languages have more than one form for plural messages dependent on the count.
This function sets the domain to search within when calls are made to gettext(), usually the named after an application.
These functions allow you to work with arbitrary-length integers using the GNU MP library.
These functions have been added in PHP 4.0.4.
Note: Most GMP functions accept GMP number arguments, defined as resource below. However, most of these functions will also accept numeric and string arguments, given that it is possible to convert the latter to a number. Also, if there is a faster function that can operate on integer arguments, it would be used instead of the slower function when the supplied arguments are integers. This is done transparently, so the bottom line is that you can use integers in every function that expects GMP number. See also the gmp_init() function.
| Warning |
If you want to explicitly specify a large integer, specify it as a string. If you don't do that, PHP will interpret the integer-literal first, possibly resulting in loss of precision, even before GMP comes into play. |
Note: This extension is available on Windows platforms since PHP 5.1.0.
You can download the GMP library from http://www.swox.com/gmp/. This site also has the GMP manual available.
You will need GMP version 2 or better to use these functions. Some functions may require more recent version of the GMP library.
In order to have these functions available, you must compile PHP with
GMP support by using the --with-gmp option.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
More mathematical functions can be found in the sections BCMath Arbitrary Precision Mathematics Functions and Mathematical Functions.
Add two GMP numbers. The result will be a GMP number representing the sum of the arguments.
Clears (sets to 0) bit index in
a. The index starts at 0.
Note: Unlike most of the other GMP functions, gmp_clrbit() must be called with a GMP resource that already exists (using gmp_init() for example). One will not be automatically created.
See also gmp_setbit() and gmp_testbit().
Returns a positive value if a > b, zero if a = b and a negative value if a < b.
Divides a by b and
returns the integer result. The result rounding is defined by the
round, which can have the following
values:
GMP_ROUND_ZERO: The result is truncated
towards 0.
GMP_ROUND_PLUSINF: The result is
rounded towards +infinity.
GMP_ROUND_MINUSINF: The result is
rounded towards -infinity.
This function can also be called as gmp_div().
Example 1. gmp_div_q() example
The printout of the above program will be:
|
See also gmp_div_r(), gmp_div_qr()
The function divides n by
d and returns array, with the first
element being [n/d] (the integer result of the
division) and the second being (n - [n/d] * d)
(the remainder of the division).
See the gmp_div_q() function for description
of the round argument.
See also gmp_div_q(), gmp_div_r().
Calculates remainder of the integer division of
n by d. The
remainder has the sign of the n argument,
if not zero.
See the gmp_div_q() function for description
of the round argument.
See also gmp_div_q(), gmp_div_qr()
Divides n by d,
using fast "exact division" algorithm. This function produces
correct results only when it is known in advance that
d divides n.
Calculates factorial (a!) of a.
Example 1. gmp_fact() example
The printout of the above program will be:
|
Calculate greatest common divisor of a and
b. The result is always positive even if
either of, or both, input operands are negative.
Calculates g, s, and t, such that a*s + b*t = g = gcd(a,b), where gcd is the greatest common divisor. Returns an array with respective elements g, s and t.
This function can be used to solve linear Diophantine equations in two variables. These are equations that allow only integer solutions and have the form: a*x + b*y = c. For more information, go to the "Diophantine Equation" page at MathWorld
Example 1. Solving a linear Diophantine equation
|
Returns the hamming distance between a and
b. Both operands should be non-negative.
See also gmp_popcount(), gmp_xor()
Creates a GMP number from an integer or string. String
representation can be decimal, hexadecimal or octal.
Optional parameter base is available since
PHP 4.1.0. Its default value is 0.
The base may vary from 2 to 36. If base is 0 (default value), the actual base is determined from the leading characters: if the first two characters are 0x or 0X, hexadecimal is assumed, otherwise if the first character is "0", octal is assumed, otherwise decimal is assumed.
Note: It is not necessary to call this function if you want to use integer or string in place of GMP number in GMP functions, like gmp_add(). Function arguments are automatically converted to GMP numbers, if such conversion is possible and needed, using the same rules as gmp_init().
This function allows to convert GMP number to integer.
| Warning |
This function returns a useful result only if the number actually fits the PHP integer (i.e., signed long type). If you want just to print the GMP number, use gmp_strval(). |
Example 1. gmp_intval() example
The printout of the above program will be:
|
Computes the inverse of a modulo
b. Returns FALSE if an inverse does not
exist.
Computes
Jacobi symbol of a and
p. p should be odd
and must be positive.
Compute the
Legendre symbol of a and
p. p should be odd
and must be positive.
Calculates n modulo
d. The result is always non-negative, the
sign of d is ignored.
Return next prime number greater than a.
This function uses a probabilistic algorithm to identify primes and chances to get a composite number are extremely small.
Calculates logical inclusive OR of two GMP numbers.
Returns TRUE if a is a perfect square,
FALSE otherwise.
Example 1. gmp_perfect_square() example
The printout of the above program will be:
|
See also: gmp_sqrt(), gmp_sqrtrem().
Raise base into power
exp. The case of 0^0 yields
1. exp cannot be negative.
Calculate (base raised into power
exp) modulo mod. If
exp is negative, result is undefined.
If this function returns 0, a is
definitely not prime. If it returns 1, then
a is "probably" prime. If it returns 2,
then a is surely prime. Reasonable values
of reps vary from 5 to 10 (default being
10); a higher value lowers the probability for a non-prime to
pass as a "probable" prime.
The function uses Miller-Rabin's probabilistic test.
Generate a random number. The number will be between
zero and the number of bits per limb multiplied by
limiter. If limiter
is negative, negative numbers are generated.
A limb is an internal GMP mechanism. The number of bits in a limb is not static, and can vary from system to system. Generally, the number of bits in a limb is either 16 or 32, but this is not guaranteed.
Example 1. gmp_random() example
The printout of the above program might be:
|
Scans a, starting with bit
start, towards more significant bits,
until the first clear bit is found. Returns the index of the
found bit. The index starts from 0.
Example 1. gmp_scan0() example
The printout of the above program will be:
|
Scans a, starting with bit
start, towards more significant bits,
until the first set bit is found. Returns the index of the found
bit. If no set bit is found, -1 is returned.
Example 1. gmp_scan1() example
The printout of the above program will be:
|
Sets bit index in
a. set_clear
defines if the bit is set to 0 or 1. By default the bit is set to
1. Index starts at 0.
Note: Unlike most of the other GMP functions, gmp_setbit() must be called with a GMP resource that already exists (using gmp_init() for example). One will not be automatically created.
See also gmp_clrbit() and gmp_testbit().
Returns 1 if a is positive,
-1 if a is negative,
and 0 if a is zero.
Calculates square root of a and returns the
integer portion of the result.
Returns array where first element is the integer square root of
a (see also
gmp_sqrt()), and the second is the remainder
(i.e., the difference between a and the
first element squared).
Example 1. gmp_sqrtrem() example
The printout of the above program will be:
|
Convert GMP number to string representation in base
base. The default base is 10. Allowed
values for the base are from 2 to 36.
This module allows you to interact with gnupg.
The gnupg extension requires PHP 4.3. To use this extension in an OO style, PHP 5 is required.
This extension requires the gpgme library
The gnupg-extension is not bundled with PHP. It is a PECL extension and can be located here: http://pecl.php.net/package/gnupg.
This extension makes use of the keyring of the current user. This keyring is normally located in ~./.gnupg/. To specify a custom location, store the path to the keyring in the environment variable GNUPGHOME. See putenv for more information how to do this.
Some functions require the specification of a key. This specification can be anything that refers to an unique key (userid, key-id, fingerprint, ...). This documentation uses the fingerprint in all examples.
This extension also comes with an Iterator for your keyring.
<?php
// create a new iterator for listing all public keys that matches 'example'
$iterator = new gnupg_keylistiterator("example");
foreach($iterator as $fingerprint => $userid){
echo $fingerprint." -> ".$userid."\n";
}
?> |
This example will clearsign a given text.
Example 1. gnupg clearsign example (procedural)
|
Example 2. gnupg clearsign example (OO)
|
(no version information, might be only in CVS)
gnupg_cleardecryptkeys -- Removes all keys which were set for decryption before(no version information, might be only in CVS)
gnupg_clearencryptkeys -- Removes all keys which were set for encryption before(no version information, might be only in CVS)
gnupg_clearsignkeys -- Removes all keys which were set for signing beforeDecrypts the given text with the keys, which were set with gnupg_adddecryptkey before.
On success, this function returns the decrypted text. On failure, this function returns FALSE.
Example 2. OO gnupg_encrypt() example
|
(no version information, might be only in CVS)
gnupg_decryptverify -- Decrypts and verifies a given text
Decrypts and verifies a given text and returns information about the
signature.
The parameter plaintext gets filled with the decrypted
text.
On success, this function returns information about the signature and
fills the plaintext parameter with the decrypted text.
On failure, this function returns FALSE.
Encrypts the given plaintext with the keys, which
were set with gnupg_addencryptkey before and
returns the encrypted text.
On success, this function returns the encrypted text. On failure, this function returns FALSE.
Encrypts and signs the given plaintext with the
keys, which were set with
gnupg_addsignkey and gnupg_addencryptkey before and
returns the encrypted and signed text.
On success, this function returns the encrypted and signed text. On failure, this function returns FALSE.
Exports the key fingerprint.
On success, this function returns the keydata. On failure, this function returns FALSE.
(no version information, might be only in CVS)
gnupg_geterror -- Returns the errortext, if a function fails(no version information, might be only in CVS)
gnupg_getprotocol -- Returns the currently active protocol for all operationsReturns the currently active protocol, which can be one of GNUPG_PROTOCOL_OpenPGP or GNUPG_PROTOCOL_CMS.
Imports the key keydata and returns an array with
information about the importprocess.
On success, this function returns and info-array about the importprocess. On failure, this function returns FALSE.
(no version information, might be only in CVS)
gnupg_keyinfo -- Returns an array with information about all keys that matches the given patternReturns an array with information about all keys that matches the given pattern or FALSE, if an error has occurred.
Pass a non-zero integer-value to this function to enable armored-output (default). Pass 0 to disable armored output.
(no version information, might be only in CVS)
gnupg_seterrormode -- Sets the mode for error_reporting
errormode takes a constant indicating what type of
error_reporting should be used. The possible values are
GNUPG_ERROR_WARNING,
GNUPG_ERROR_EXCEPTION and
GNUPG_ERROR_SILENT.
By default GNUPG_ERROR_SILENT is used.
signmode takes a constant indicating what type of
signature should be produced. The possible values are
GNUPG_SIG_MODE_NORMAL,
GNUPG_SIG_MODE_DETACH and
GNUPG_SIG_MODE_CLEAR.
By default GNUPG_SIG_MODE_CLEAR is used.
Signs the given plaintext with the keys, which were
set with gnupg_addsignkey before and
returns the signed text or the signature, depending on what was set with
gnupg_setsignmode.
On success, this function returns the signed text or the signature. On failure, this function returns FALSE.
Verifies the given signed_text and returns information about the
signature.
To verify a clearsigned text, set signature to FALSE.
If the optional parameter plaintext is passed, it is
filled with the plaintext.
On success, this function returns informations about the signature. On failure, this function returns FALSE.
The gopher protocol, as defined by RFC 1436, is generally considered the ancestor of the modern HTTP protocol. However, gopher was also intended to provide references to non-gopher resources including telnet, wais, nntp, and even http. This extension adds gopher support to PHP's URL Wrappers, and provides a helper function gopher_parsedir() to make sense of gopher formatted directory listings.
Prerequisite: PHP 4.3.0 or higher.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/net_gopher
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Table 1. Net_Gopher constants
| Constant | Value | Description |
|---|---|---|
| GOPHER_DOCUMENT | 0 | Standard text/plain document. |
| GOPHER_DIRECTORY | 1 | A resource containing a gopher formatted directory listing. |
| GOPHER_BINHEX | 4 | A BinHex encoded binary file. |
| GOPHER_DOSBINARY | 5 | A DOS formatted binary archive. |
| GOPHER_UUENCODED | 6 | A UUEncoded file. |
| GOPHER_BINARY | 9 | A generic binary file. |
| GOPHER_INFO | 255 | An Informational entry |
| GOPHER_HTTP | 254 | A reference to an HTTP resource. |
| GOPHER_UNKNOWN | -1 | An unrecognized entry. |
gopher_parsedir() parses a gopher formatted directory entry into an associative array.
While gopher returns text/plain documents for actual document requests. A request to a directory (such as /) will return specially encoded series of lines with each line being one directory entry or information line.
Returns an associative array whose components are:
type - One of the
GOPHER_XXX constants.
title - The name of the resource.
path - The path of the resource.
host - The domain name of the host that has
this document (or directory).
port - The port at which to connect on
host.
Upon failure, the additional data entry of the
returned array will hold the parsed line.
Example 1. Hypothetical output from gopher://gopher.example.com/
|
In the example above, the root directory at gopher.example.com knows about one DOCUMENT identified by 0 located at gopher://gopher.example.com:70/allabout.txt. It also knows about two other directory (which have their own listing files) at gopher://gopher.exmaple.com:70/stories and at gopher://gopher.ejemplo.co.es:70/. In addition there is a binary file, a link to an HTTP url, and several informative lines.
By passing each line of the directory listing into gopher_parsedir(), an associative array is formed containing a parsed out version of the data.
Example 2. Using gopher_parsedir()
The above example will output:
|
The PECL/haru extension provides bindings for Haru Free PDF Library - free, cross platform, opensource software library for generating PDF files.
You can find the library here: http://libharu.sourceforge.net.
| Warning |
This extension is EXPERIMENTAL. The behaviour of this extension -- including the names of its functions and anything else documented about this extension -- may change without notice in a future release of PHP. Use this extension at your own risk. |
You need to install libharu first to be able to use PECL/haru. PECL/haru is tested with libharu 2.0.8, older versions might or might not work for you. PECL/haru also requires PHP 5.1.3 or newer.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/haru.
The latest PECL/haru Win32 DLL can be downloaded here: php_haru.dll.
Example 1. Basic PECL/haru example
|
Open the result document in your favourite PDF viewer and you should see a light-blue rectangle and white "Hello World!" on it.
| HaruException |
| HaruDoc |
| HaruPage |
| HaruFont |
| HaruImage |
| HaruEncoder |
| HaruOutline |
| HaruAnnotation |
| HaruDestination |
These Base14 fonts are built-in into PDF and all viewers can display them. Using these fonts may decrease the size of the result file and make the processing faster, avoiding loading external fonts. However the fonts support only latin1 character set and you have to load external fonts if you need to use an other character set.
The Base14 fonts:
Courier
Courier-Bold
Courier-Oblique
Courier-BoldOblique
Helvetica
Helvetica-Bold
Helvetica-Oblique
Helvetica-BoldOblique
Times-Roman
Times-Bold
Times-Italic
Times-BoldItalic
Symbol
ZapfDingbats
Table 1. Single-byte character set encodings
| Name | Description |
|---|---|
| StandardEncoding | The default encoding of PDF. |
| MacRomanEncoding | The standard encoding of Mac OS. |
| WinAnsiEncoding | The standard encoding of Windows. |
| FontSpecific | The font built-in encoding. |
| ISO8859-2 | Latin2 (East European) |
| ISO8859-3 | Latin3 (South European) |
| ISO8859-4 | Latin4 (North European) |
| ISO8859-5 | Cyrillic |
| ISO8859-6 | Arabic |
| ISO8859-7 | Greek |
| ISO8859-8 | Hebrew |
| ISO8859-9 | Latin5 (Turkish) |
| ISO8859-10 | Latin6 (Nordic) |
| ISO8859-11 | Thai |
| ISO8859-13 | Latin7 (Baltic Rim) |
| ISO8859-14 | Latin8 (Celtic) |
| ISO8859-15 | Latin9 |
| ISO8859-16 | Latin10 |
| CP1250 | MS Windows Codepage 1250. |
| CP1251 | MS Windows Codepage 1251. |
| CP1252 | MS Windows Codepage 1252. |
| CP1253 | MS Windows Codepage 1253. |
| CP1254 | MS Windows Codepage 1254. |
| CP1255 | MS Windows Codepage 1255. |
| CP1256 | MS Windows Codepage 1256. |
| CP1257 | MS Windows Codepage 1257. |
| CP1258 | MS Windows Codepage 1258. |
| KOI8-R | Cyrillic character set. |
Table 2. Multi-byte character set encodings
| Name | Description |
|---|---|
| GB-EUC-H | EUC-CN encoding. |
| GB-EUC-V | Vertical writing version of GB-EUC-H. |
| GBK-EUC-H | Microsoft Code Page 936 (lfCharSet 0x86) GBK encoding. |
| GBK-EUC-V | Vertical writing version of GBK-EUC-H. |
| ETen-B5-H | Microsoft Code Page 950 (lfCharSet 0x88) Big Five character set with ETen extensions. |
| ETen-B5-V | Vertical writing version of ETen-B5-H. |
| 90ms-RKSJ-H | Microsoft Code Page 932, JIS X 0208 character. |
| 90ms-RKSJ-V | Vertical writing version of 90ms-RKSJ-V. |
| 90msp-RKSJ-H | Microsoft Code Page 932, JIS X 0208 character (proportional). |
| EUC-H | JIS X 0208 character set, EUC-JP encoding. |
| EUC-V | Vertical writing version of EUC-H. |
| KSC-EUC-H | KS X 1001:1992 character set, EUC-KR encoding. |
| KSC-EUC-V | Vertical writing version of KSC-EUC-V. |
| KSCms-UHC-H | Microsoft Code Page 949 (lfCharSet 0x81), KS X 1001:1992 character set plus 8822 additional hangul, Unified Hangul Code (UHC) encoding (proportional). |
| KSCms-UHC-HW-H | Microsoft Code Page 949 (lfCharSet 0x81), KS X 1001:1992 character set plus 8822 additional hangul, Unified Hangul Code (UHC) encoding (fixed width). |
| KSCms-UHC-HW-V | Vertical writing version of KSCms-UHC-HW-H. |
Table 1.
| Type | Name | Description |
|---|---|---|
| int | HaruDoc::CS_DEVICE_GRAY | |
| int | HaruDoc::CS_DEVICE_RGB | |
| int | HaruDoc::CS_DEVICE_CMYK | |
| int | HaruDoc::CS_CAL_GRAY | |
| int | HaruDoc::CS_CAL_RGB | |
| int | HaruDoc::CS_LAB | |
| int | HaruDoc::CS_ICC_BASED | |
| int | HaruDoc::CS_SEPARATION | |
| int | HaruDoc::CS_DEVICE_N | |
| int | HaruDoc::CS_INDEXED | |
| int | HaruDoc::CS_PATTERN | |
| int | HaruDoc::ENABLE_READ | |
| int | HaruDoc::ENABLE_PRINT | |
| int | HaruDoc::ENABLE_EDIT_ALL | |
| int | HaruDoc::ENABLE_COPY | |
| int | HaruDoc::ENABLE_EDIT | |
| int | HaruDoc::ENCRYPT_R2 | |
| int | HaruDoc::ENCRYPT_R3 | |
| int | HaruDoc::INFO_AUTHOR | |
| int | HaruDoc::INFO_CREATOR | |
| int | HaruDoc::INFO_TITLE | |
| int | HaruDoc::INFO_SUBJECT | |
| int | HaruDoc::INFO_KEYWORDS | |
| int | HaruDoc::INFO_CREATION_DATE | |
| int | HaruDoc::INFO_MOD_DATE | |
| int | HaruDoc::COMP_NONE | |
| int | HaruDoc::COMP_TEXT | |
| int | HaruDoc::COMP_IMAGE | |
| int | HaruDoc::COMP_METADATA | |
| int | HaruDoc::COMP_ALL | |
| int | HaruDoc::PAGE_LAYOUT_SINGLE | |
| int | HaruDoc::PAGE_LAYOUT_ONE_COLUMN | |
| int | HaruDoc::PAGE_LAYOUT_TWO_COLUMN_LEFT | |
| int | HaruDoc::PAGE_LAYOUT_TWO_COLUMN_RIGHT | |
| int | HaruDoc::PAGE_MODE_USE_NONE | |
| int | HaruDoc::PAGE_MODE_USE_OUTLINE | |
| int | HaruDoc::PAGE_MODE_USE_THUMBS | |
| int | HaruDoc::PAGE_MODE_FULL_SCREEN |
| HaruDoc::__construct() |
| HaruDoc::addPageLabel() |
| HaruDoc::addPage() |
| HaruDoc::createOutline() |
| HaruDoc::getCurrentEncoder() |
| HaruDoc::getCurrentPage() |
| HaruDoc::getEncoder() |
| HaruDoc::getFont() |
| HaruDoc::getInfoAttr() |
| HaruDoc::getPageLayout() |
| HaruDoc::getPageMode() |
| HaruDoc::getStreamSize() |
| HaruDoc::insertPage() |
| HaruDoc::loadJPEG() |
| HaruDoc::loadPNG() |
| HaruDoc::loadRAW() |
| HaruDoc::loadTTC() |
| HaruDoc::loadTTC() |
| HaruDoc::loadType1() |
| HaruDoc::output() |
| HaruDoc::readFromStream() |
| HaruDoc::resetError() |
| HaruDoc::resetStream() |
| HaruDoc::save() |
| HaruDoc::setCompressionMode() |
| HaruDoc::setCurrentEncoder() |
| HaruDoc::setEncryptionMode() |
| HaruDoc::setInfoAttr() |
| HaruDoc::setInfoDateAttr() |
| HaruDoc::setOpenAction() |
| HaruDoc::setPageLayout() |
| HaruDoc::setPageMode() |
| HaruDoc::setPagesConfiguration() |
| HaruDoc::setPassword() |
| HaruDoc::setPermission() |
| HaruDoc::useCNSEncodings() |
| HaruDoc::useCNSFonts() |
| HaruDoc::useCNTEncodings() |
| HaruDoc::useCNTFonts() |
| HaruDoc::useJPEncodings() |
| HaruDoc::useJPFonts() |
| HaruDoc::useKREncodings() |
| HaruDoc::useKRFonts() |
Table 1.
| Type | Name | Description |
|---|---|---|
| int | HaruPage::GMODE_PAGE_DESCRIPTION | |
| int | HaruPage::GMODE_TEXT_OBJECT | |
| int | HaruPage::GMODE_PATH_OBJECT | |
| int | HaruPage::GMODE_CLIPPING_PATH | |
| int | HaruPage::GMODE_SHADING | |
| int | HaruPage::GMODE_INLINE_IMAGE | |
| int | HaruPage::GMODE_EXTERNAL_OBJECT | |
| int | HaruPage::BUTT_END | |
| int | HaruPage::ROUND_END | |
| int | HaruPage::PROJECTING_SCUARE_END | |
| int | HaruPage::MITER_JOIN | |
| int | HaruPage::ROUND_JOIN | |
| int | HaruPage::BEVEL_JOIN | |
| int | HaruPage::FILL | |
| int | HaruPage::STROKE | |
| int | HaruPage::FILL_THEN_STROKE | |
| int | HaruPage::INVISIBLE | |
| int | HaruPage::FILL_CLIPPING | |
| int | HaruPage::STROKE_CLIPPING | |
| int | HaruPage::FILL_STROKE_CLIPPING | |
| int | HaruPage::CLIPPING | |
| int | HaruPage::TALIGN_LEFT | |
| int | HaruPage::TALIGN_RIGHT | |
| int | HaruPage::TALIGN_CENTER | |
| int | HaruPage::TALIGN_JUSTIFY | |
| int | HaruPage::SIZE_LETTER | |
| int | HaruPage::SIZE_LEGAL | |
| int | HaruPage::SIZE_A3 | |
| int | HaruPage::SIZE_A4 | |
| int | HaruPage::SIZE_A5 | |
| int | HaruPage::SIZE_B4 | |
| int | HaruPage::SIZE_B5 | |
| int | HaruPage::SIZE_EXECUTIVE | |
| int | HaruPage::SIZE_US4x6 | |
| int | HaruPage::SIZE_US4x8 | |
| int | HaruPage::SIZE_US5x7 | |
| int | HaruPage::SIZE_COMM10 | |
| int | HaruPage::PORTRAIT | |
| int | HaruPage::LANDSCAPE | |
| int | HaruPage::TS_WIPE_LIGHT | |
| int | HaruPage::TS_WIPE_UP | |
| int | HaruPage::TS_WIPE_LEFT | |
| int | HaruPage::TS_WIPE_DOWN | |
| int | HaruPage::TS_BARN_DOORS_HORIZONTAL_OUT | |
| int | HaruPage::TS_BARN_DOORS_HORIZONTAL_IN | |
| int | HaruPage::TS_BARN_DOORS_VERTICAL_OUT | |
| int | HaruPage::TS_BARN_DOORS_VERTICAL_IN | |
| int | HaruPage::TS_BOX_OUT | |
| int | HaruPage::TS_BOX_IN | |
| int | HaruPage::TS_BLINDS_HORIZONTAL | |
| int | HaruPage::TS_BLINDS_VERTICAL | |
| int | HaruPage::TS_DISSOLVE | |
| int | HaruPage::TS_GLITTER_RIGHT | |
| int | HaruPage::TS_GLITTER_DOWN | |
| int | HaruPage::TS_GLITTER_TOP_LEFT_TO_BOTTOM_RIGHT | |
| int | HaruPage::TS_REPLACE | |
| int | HaruPage::NUM_STYLE_DECIMAL | |
| int | HaruPage::NUM_STYLE_UPPER_ROMAN | |
| int | HaruPage::NUM_STYLE_LOWER_ROMAN | |
| int | HaruPage::NUM_STYLE_UPPER_LETTERS | |
| int | HaruPage::NUM_STYLE_LOWER_LETTERS |
| HaruPage::arc() |
| HaruPage::beginText() |
| HaruPage::circle() |
| HaruPage::closePath() |
| HaruPage::concat() |
| HaruPage::createDestination() |
| HaruPage::createLinkAnnotation() |
| HaruPage::createTextAnnotation() |
| HaruPage::createUrlAnnotation() |
| HaruPage::curveTo() |
| HaruPage::curveTo2() |
| HaruPage::curveTo3() |
| HaruPage::drawImage() |
| HaruPage::ellipse() |
| HaruPage::endPath() |
| HaruPage::endText() |
| HaruPage::eofillStroke() |
| HaruPage::eofill() |
| HaruPage::fillStroke() |
| HaruPage::fill() |
| HaruPage::getCharSpace() |
| HaruPage::getCMYKFill() |
| HaruPage::getCMYKStroke() |
| HaruPage::getCurrentFontSize() |
| HaruPage::getCurrentFont() |
| HaruPage::getCurrentPos() |
| HaruPage::getCurrentTextPos() |
| HaruPage::getDash() |
| HaruPage::getFillingColorSpace() |
| HaruPage::getFlatness() |
| HaruPage::getGMode() |
| HaruPage::getGrayFill() |
| HaruPage::getGrayStroke() |
| HaruPage::getHeight() |
| HaruPage::getHorizontalScaling() |
| HaruPage::getLineCap() |
| HaruPage::getLineJoin() |
| HaruPage::getLineWidth() |
| HaruPage::getMiterLimit() |
| HaruPage::getRGBFill() |
| HaruPage::getRGBStroke() |
| HaruPage::getStrokingColorSpace() |
| HaruPage::getTextLeading() |
| HaruPage::getTextMatrix() |
| HaruPage::getTextRenderingMode() |
| HaruPage::getTextRise() |
| HaruPage::getTextWidth() |
| HaruPage::getTransMatrix() |
| HaruPage::getWidth() |
| HaruPage::getWordSpace() |
| HaruPage::lineTo() |
| HaruPage::measureText() |
| HaruPage::moveTextPos() |
| HaruPage::moveToNextLine() |
| HaruPage::moveTo() |
| HaruPage::rectangle() |
| HaruPage::setCharSpace() |
| HaruPage::setCMYKFill() |
| HaruPage::setCMYKStroke() |
| HaruPage::setDash() |
| HaruPage::setFlatness() |
| HaruPage::setFontAndSize() |
| HaruPage::setGrayFill() |
| HaruPage::setGrayStroke() |
| HaruPage::setHeight() |
| HaruPage::setHorizontalScaling() |
| HaruPage::setLineCap() |
| HaruPage::setLineJoin() |
| HaruPage::setLineWidth() |
| HaruPage::setMiterLimit() |
| HaruPage::setRGBFill() |
| HaruPage::setRGBStroke() |
| HaruPage::setRotate() |
| HaruPage::setSize() |
| HaruPage::setSlideShow() |
| HaruPage::setTextLeading() |
| HaruPage::setTextMatrix() |
| HaruPage::setTextTenderingMode() |
| HaruPage::setWidth() |
| HaruPage::setWordSpace() |
| HaruPage::showTextNextLine() |
| HaruPage::showText() |
| HaruPage::stroke() |
| HaruPage::textOut() |
| HaruPage::textRect() |
Table 1.
| Type | Name | Description |
|---|---|---|
| int | HaruEncoder::TYPE_SINGLE_BYTE | |
| int | HaruEncoder::TYPE_DOUBLE_BYTE | |
| int | HaruEncoder::TYPE_UNINITIALIZED | |
| int | HaruEncoder::UNKNOWN | |
| int | HaruEncoder::WMODE_HORIZONTAL | |
| int | HaruEncoder::WMODE_VERTICAL | |
| int | HaruEncoder::BYTE_TYPE_SINGLE | |
| int | HaruEncoder::BYTE_TYPE_LEAD | |
| int | HaruEncoder::BYTE_TYPE_TRAIL | |
| int | HaruEncoder::BYTE_TYPE_UNKNOWN |
Table 1.
| Type | Name | Description |
|---|---|---|
| int | HaruAnnotation::NO_HIGHLIGHT | |
| int | HaruAnnotation::INVERT_BOX | |
| int | HaruAnnotation::INVERT_BORDER | |
| int | HaruAnnotation::DOWN_APPEARANCE | |
| int | HaruAnnotation::ICON_COMMENT | |
| int | HaruAnnotation::ICON_KEY | |
| int | HaruAnnotation::ICON_NOTE | |
| int | HaruAnnotation::ICON_HELP | |
| int | HaruAnnotation::ICON_NEW_PARAGRAPH | |
| int | HaruAnnotation::ICON_PARAGRAPH | |
| int | HaruAnnotation::ICON_INSERT |
(no version information, might be only in CVS)
HaruAnnotation::setBorderStyle -- Set the border style of the annotationDefines the style of the border of the annotation. This function may be used with link annotations only.
(no version information, might be only in CVS)
HaruAnnotation::setHighlightMode -- Set the highlighting mode of the annotationDefines the appearance of the annotation when clicked. This function may be used with link annotations only.
modeThe highlighting mode of the annotation. Can take only these values:
| HaruAnnotation::NO_HIGHLIGHT - no highlighting. |
| HaruAnnotation::INVERT_BOX - invert the contents of the annotation. |
| HaruAnnotation::INVERT_BORDER - invert the border of the annotation. |
| HaruAnnotation::DOWN_APPEARANCE - dent the annotation. |
(no version information, might be only in CVS)
HaruAnnotation::setIcon -- Set the icon style of the annotationDefines the style of the annotation icon. This function may be used with text annotations only.
iconThe style of the icon. Can take only these values:
| HaruAnnotation::ICON_COMMENT |
| HaruAnnotation::ICON_KEY |
| HaruAnnotation::ICON_NOTE |
| HaruAnnotation::ICON_HELP |
| HaruAnnotation::ICON_NEW_PARAGRAPH |
| HaruAnnotation::ICON_PARAGRAPH |
| HaruAnnotation::ICON_INSERT |
(no version information, might be only in CVS)
HaruAnnotation::setOpened -- Set the initial state of the annotationDefines whether the annotation is initially displayed open. This function may be used with text annotations only.
(no version information, might be only in CVS)
HaruDestination::setFit -- Set the appearance of the page to fit the windowDefines the appearance of the page to fit the window.
(no version information, might be only in CVS)
HaruDestination::setFitB -- Set the appearance of the page to fit the bounding box of the page within the windowDefines the appearance of the page to fit the bounding box of the page within the window.
(no version information, might be only in CVS)
HaruDestination::setFitBH -- Set the appearance of the page to fit the width of the bounding box
Defines the appearance of the page to magnifying to fit the width of the
bounding box and setting the top position of the page to the value of
top.
(no version information, might be only in CVS)
HaruDestination::setFitBV -- Set the appearance of the page to fit the height of the boudning box
Defines the appearance of the page to magnifying to fit the height of the
bounding box and setting the left position of the page to the value of
left.
(no version information, might be only in CVS)
HaruDestination::setFitH -- Set the appearance of the page to fit the window width
Defines the appearance of the page to fit the window width and sets the top
position of the page to the value of top.
(no version information, might be only in CVS)
HaruDestination::setFitR -- Set the appearance of the page to fit the specified rectangleDefines the appearance of the page to fit the rectangle by the parameters.
leftThe left coordinates of the page.
bottomThe bottom coordinates of the page.
rightThe right coordinates of the page.
topThe top coordinates of the page.
(no version information, might be only in CVS)
HaruDestination::setFitV -- Set the appearance of the page to fit the window heightDefines the appearance of the page to fit the window height.
(no version information, might be only in CVS)
HaruDestination::setXYZ -- Set the appearance of the page
Defines the appearance of the page using three parameters:
left, top and
zoom.
leftThe left position of the page.
topThe top position of the page.
zoomThe magnification factor. The value must be between 0.08 (8%) and 32 (3200%).
Adds new page to the document and returns new HaruPage instance.
(no version information, might be only in CVS)
HaruDoc::addPageLabel -- Set the numbering style for the specified range of pagesSet the numbering style for the specified range of pages.
first_pageThe first page included into the labeling range.
styleThe numbering style. The following values are allowed:
| HaruPage::NUM_STYLE_DECIMAL - page label is displayed using decimal numerals. |
| HaruPage::NUM_STYLE_UPPER_ROMAN - page label is displayed using uppercase Roman numerals. |
| HaruPage::NUM_STYLE_LOWER_ROMAN - page label is displayed using lowercase Roman numerals. |
| HaruPage::NUM_STYLE_UPPER_LETTER - page label is displayed using uppercase letters (from A to Z). |
| HaruPage::NUM_STYLE_LOWER_LETTERS - page label is displayed using lowercase letters (from a to z). |
first_numThe first page number in this range.
prefixThe prefix for the page label. Optional, empty by default.
(no version information, might be only in CVS)
HaruDoc::__construct -- Construct new HaruDoc instance(no version information, might be only in CVS)
HaruDoc::createOutline -- Create a HaruOutline instanceCreates and returns new HaruOutline instance.
titleThe caption of new outline object.
parent_outlineA valid HaruOutline instance or NULL.
encoderA valid HaruEncoder instance or NULL.
(no version information, might be only in CVS)
HaruDoc::getCurrentEncoder -- Get HaruEncoder currently used in the documentReturns HaruEncoder currently used in the document or FALSE if encoder is not set.
(no version information, might be only in CVS)
HaruDoc::getCurrentPage -- Return current page of the documentGet current page of the document. Returns HaruPage instance on success or FALSE if there is no current page at the moment.
(no version information, might be only in CVS)
HaruDoc::getEncoder -- Get HaruEncoder instance for the specified encodingReturns HaruEncoder instance for the specified encoding.
Creates and returns HaruFont instance with the
specified fontname and
encoding.
fontnameThe name of the font. See Builtin Fonts for the list of builtin fonts. You can also use the name of a font loaded via HaruDoc::loadTTF(), HaruDoc::loadTTC() and HaruDoc::loadType1().
encodingThe encoding to use. See Builtin Encodings for the list of supported encodings.
(no version information, might be only in CVS)
HaruDoc::getInfoAttr -- Get current value of the specified document attributeReturns the string value of the specified document attribute.
typeThe type of the attribute. The following values are available:
| HaruDoc::INFO_AUTHOR |
| HaruDoc::INFO_CREATOR |
| HaruDoc::INFO_TITLE |
| HaruDoc::INFO_SUBJECT |
| HaruDoc::INFO_KEYWORDS |
| HaruDoc::INFO_CREATION_DATE |
| HaruDoc::INFO_MOD_DATE |
Returns the page layout currently set in the document or FALSE if page layout was not set. See HaruDoc::setPageLayout() for the list of possible values.
Returns the page mode currently set in the document. See HaruDoc::setPageMode() for the list of possible values.
(no version information, might be only in CVS)
HaruDoc::getStreamSize -- Get the size of the temporary streamReturns the size of the data in the temporary stream of the document. The size is zero if the document was not saved to the temporary stream.
(no version information, might be only in CVS)
HaruDoc::insertPage -- Insert new page just before the specified pageCreates new page and inserts just before the specified page. Returns new HaruPage instance.
(no version information, might be only in CVS)
HaruDoc::loadJPEG -- Load JPEG image and return new HaruImage instanceLoads the specified JPEG image and returns new HaruImage instance.
(no version information, might be only in CVS)
HaruDoc::loadPNG -- Load PNG image and return HaruImage instance
Loads PNG image and returns HaruImage instance.
You can set deferred parameter to TRUE for
deferred data loading, in this case only size and color are loaded
immediately. Default value of deferred is FALSE.
Libharu might be built without libpng support, in this case each call to this function would result in exception.
filenameThe name of a PNG image file.
deferredDo not load data immediately. Defaults to FALSE.
(no version information, might be only in CVS)
HaruDoc::loadRaw -- Load RAW image and return HaruImage instanceLoads RAW image and returns new HaruImage instance.
filenameThe name of a RAW image file.
widthThe width of the image.
heightThe height of the image.
color_spaceThe color space of the image. Can be one of the following values:
| HaruDoc::CS_DEVICE_GRAY |
| HaruDoc::CS_DEVICE_RGB |
| HaruDoc::CS_DEVICE_CMYK |
(no version information, might be only in CVS)
HaruDoc::loadTTC -- Load the font with the specified index from TTC fileLoads the TrueType font with the specified index from a TrueType collection file.
fontfileThe TrueType collection file.
indexThe index of the font in the collection file.
embedWhen set to TRUE, the glyph data of the font is embedded into the PDF file, otherwise only the matrix data is included. Defaults to FALSE.
Loads the given TTF file and (optionally) embed its data into the document.
fontfileThe TTF file to load.
embedWhen set to TRUE, the glyph data of the font is embedded into the PDF file, otherwise only the matrix data is included. Defaults to FALSE.
Loads Type1 font from the given file and registers it in the PDF document.
afmfilePath to an AFM file.
pfmfilePath to a PFA/PFB file, optional. If it's not set only the glyph data of the font is embedded into the PDF document.
(no version information, might be only in CVS)
HaruDoc::output -- Write the document data to the output buffer(no version information, might be only in CVS)
HaruDoc::readFromStream -- Read data from the temporary stream
Returns data from the temporary stream. The bytes
parameter specifies how much bytes to read, though the stream may contain
less bytes than requested.
(no version information, might be only in CVS)
HaruDoc::resetError -- Reset error state of the document handleOnce an error code is set, most of the operations, including I/O processing functions cannot be performed. In case if you want to continue after the cause of the error has been fixed, you have to invoke this function in order to reset the document error state.
(no version information, might be only in CVS)
HaruDoc::save -- Save the document into the specified file(no version information, might be only in CVS)
HaruDoc::saveToStream -- Save the document into a temporary stream(no version information, might be only in CVS)
HaruDoc::setCompressionMode -- Set compression mode for the documentDefines compression mode for the document. In case when libharu was compiled without Zlib support this function will always throw HaruException.
modeThe compression mode to use. The value is a combination of the following flags:
| HaruDoc::COMP_NONE - all contents is not compressed. |
| HaruDoc::COMP_TEXT - compress the text data. |
| HaruDoc::COMP_IMAGE - compress the image data. |
| HaruDoc::COMP_METADATA - compress other data (fonts, cmaps). |
| HaruDoc::COMP_ALL - compress all data. |
(no version information, might be only in CVS)
HaruDoc::setCurrentEncoder -- Set the current encoder for the documentDefines the encoder currently used in the document.
encodingThe name of the encoding to use. See Builtin Encodings for the list of allowed values.
(no version information, might be only in CVS)
HaruDoc::setEncryptionMode -- Set encryption mode for the documentDefines encryption mode for the document. The encryption mode cannot be set before setting the password.
modeThe encryption mode to use. Can be one of the following:
| HaruDoc::ENCRYPT_R2 - use "revision2" algorithm. |
| HaruDoc::ENCRYPT_R3 - use "revision3" algorithm. Using this value bumps the version of PDF to 1.4. |
key_lenThe encryption key length in bytes. This parameter is optional and used only when mode is HaruDoc::ENCRYPT_R3. The default value is 5 (40bit).
(no version information, might be only in CVS)
HaruDoc::setInfoAttr -- Set the info attribute of the documentDefines an info attribute. Uses the current encoding of the document.
typeThe type of the attribute. Can be one of the following:
| HaruDoc::INFO_AUTHOR |
| HaruDoc::INFO_CREATOR |
| HaruDoc::INFO_TITLE |
| HaruDoc::INFO_SUBJECT |
| HaruDoc::INFO_KEYWORDS |
infoThe value of the attribute.
(no version information, might be only in CVS)
HaruDoc::setInfoDateAttr -- Set the datetime info attributes of the documentSets the datetime info attributes of the document.
typeThe type of the attribute. Can be one of the following:
| HaruDoc::INFO_CREATION_DATE |
| HaruDoc::INFO_MOD_DATE |
year
monthBetween 1 and 12.
dayBetween 1 and 31, 30, 29 or 28 (different for each month).
hourBetween 0 and 23.
minBetween 0 and 59.
secBetween 0 and 59.
indThe timezone relation to UTC, can be "", " ", "+", "-" and "Z".
off_hour
If ind is not " " or "", values between 0 and
23 are valid. Otherwise, this parameter is ignored.
off_min
If ind is not " " or "", values between 0 and
59 are valid. Otherwise, this parameter is ignored.
(no version information, might be only in CVS)
HaruDoc::setOpenAction -- Define which page is shown when the document is openedDefines wich page should be shown when the document is opened.
(no version information, might be only in CVS)
HaruDoc::setPageLayout -- Set how pages should be displayed
layoutThe following values are accepted:
| HaruDoc::PAGE_LAYOUT_SINGLE - only one page is displayed. |
| HaruDoc::PAGE_LAYOUT_ONE_COLUMN - display the pages in one column. |
| HaruDoc::PAGE_LAYOUT_TWO_COLUMN_LEFT - display pages in two columns, first page left. |
| HaruDoc::PAGE_LAYOUT_TWO_COLUMN_RIGHT - display pages in two columns, first page right. |
(no version information, might be only in CVS)
HaruDoc::setPageMode -- Set how the document should be displayed
modeThe following values are accepted:
| HaruDoc::PAGE_MODE_USE_NONE - display the document with neither outline nor thumbnail. |
| HaruDoc::PAGE_MODE_USE_OUTLINE - display the document with outline pane. |
| HaruDoc::PAGE_MODE_USE_THUMBS - display the document with thumbnail pane. |
| HaruDoc::PAGE_MODE_FULL_SCREEN - display the document with full screen mode. |
(no version information, might be only in CVS)
HaruDoc::setPagesConfiguration -- Set the number of pages per set of pages
By default the document has one pages object as a root for all pages.
All page objects are create as branches of this object. One pages object
can contain only 8191, therefore the maximum number of pages per document
is 8191. But you can change that fact by setting
page_per_pages parameter, so that the root pages
object contains 8191 more pages (not page) objects, which in turn contain
8191 pages each. So the maximum number of pages in the document becomes
8191*page_per_pages.
(no version information, might be only in CVS)
HaruDoc::setPassword -- Set owner and user passwords for the documentDefines owner and user passwords for the document. Setting the passwords makes the document contents encrypted.
owner_passwordThe password of the owner, which can change permissions of the document. Empty password is not accepted. Owner's password cannot be the same as the user's password.
user_passwordThe password of the user. Can be empty.
(no version information, might be only in CVS)
HaruDoc::setPermission -- Set permissions for the document
permissionThe values is a combination of these flags:
| HaruDoc::ENABLE_READ - user can read the document. |
| HaruDoc::ENABLE_PRINT - user can print the document. |
| HaruDoc::ENABLE_EDIT_ALL - user can edit the contents of the document other than annotations and form fields. |
| HaruDoc::ENABLE_COPY - user can copy the text and the graphics of the document. |
| HaruDoc::ENABLE_EDIT - user can add or modify the annotations and form fields of the document. |
(no version information, might be only in CVS)
HaruDoc::useCNSEncodings -- Enable Chinese simplified encodings(no version information, might be only in CVS)
HaruDoc::useCNSFonts -- Enable builtin Chinese simplified fonts(no version information, might be only in CVS)
HaruDoc::useCNTEncodings -- Enable Chinese traditional encodings(no version information, might be only in CVS)
HaruDoc::useCNTFonts -- Enable builtin Chinese traditional fonts(no version information, might be only in CVS)
HaruEncoder::getByteType -- Get the type of the byte in the textReturns the type of the byte in the text on the specified position. The result is one of the following values:
| HaruEncoder::BYTE_TYPE_SINGLE - single byte character. |
| HaruEncoder::BYTE_TYPE_LEAD - lead byte of a double-byte character. |
| HaruEncoder::BYTE_TYPE_TRAIL - trailing byte of a double-byte character. |
| HaruEncoder::BYTE_TYPE_UNKNOWN - invalid encoder or cannot detect the byte type. |
Returns the type of the encoder. The result is one of the followin values:
| HaruEncoder::TYPE_SINGLE_BYTE - the encoder is for single byte characters. |
| HaruEncoder::TYPE_DOUBLE_BYTE - the encoder is for multibyte characters. |
| HaruEncoder::TYPE_UNINITIALIZED - the encoder is not initialized. |
| HaruEncoder::UNKNOWN - the encoder is invalid. |
(no version information, might be only in CVS)
HaruEncoder::getUnicode -- Convert the specified character to unicodeConverts the specified character to unicode.
(no version information, might be only in CVS)
HaruEncoder::getWritingMode -- Get the writing mode of the encoderReturns the writing mode of the encoder. The result value is on of the following:
| HaruEncoder::WMODE_HORIZONTAL - horizontal writing mode. |
| HaruEncoder::WMODE_VERTICAL - vertical writing mode. |
(no version information, might be only in CVS)
HaruFont::getAscent -- Get the vertical ascent of the font(no version information, might be only in CVS)
HaruFont::getCapHeight -- Get the distance from the baseline of uppercase lettersReturns the distance from the baseline of uppercase letters.
(no version information, might be only in CVS)
HaruFont::getDescent -- Get the vertical descent of the font(no version information, might be only in CVS)
HaruFont::getEncodingName -- Get the name of the encoding(no version information, might be only in CVS)
HaruFont::getTextWidth -- Get the total width of the text, number of characters, number of words and number of spacesReturns the total width of the text, number of characters, number of words and number of spaces in the given text.
(no version information, might be only in CVS)
HaruFont::getUnicodeWidth -- Get the width of the character in the fontReturns the width of the character in the font.
(no version information, might be only in CVS)
HaruFont::getXHeight -- Get the distance from the baseline of lowercase lettersReturns the distance from the baseline of lowercase letters.
(no version information, might be only in CVS)
HaruFont::measureText -- Calculate the number of characters which can be included within the specified widthReturns the number of characters which can be included within the specified width.
textThe text to fit the width.
widthThe width of the area to put the text to.
font_sizeThe size of the font.
char_spaceThe character spacing.
word_spaceThe word spacing.
word_wrapWhen this parameter is set to TRUE the function "emulates" word wrapping and doesn't include the part of the current word if reached the end of the area. Defaults to FALSE.
(no version information, might be only in CVS)
HaruImage::getBitsPerComponent -- Get the number of bits used to describe each color component of the imageReturns the number of bits used to describe each color component of the image.
(no version information, might be only in CVS)
HaruImage::getColorSpace -- Get the name of the color spaceReturns the name of the color space of the image. The name is one of the following values:
| "DeviceGray" |
| "DeviceRGB" |
| "DeviceCMYK" |
| "Indexed" |
Returns an array with two elements: width and height, which contain appropriate dimensions of the image.
(no version information, might be only in CVS)
HaruImage::setColorMask -- Set the color mask of the imageDefines the transparent color of the image using the RGB range values. The color within the range is displayed as a transparent color. The color space of the image must be RGB.
rminThe lower limit of red. Must be between 0 and 255.
rmaxThe upper limit of red. Must be between 0 and 255.
gminThe lower limit of green. Must be between 0 and 255.
gmaxThe upper limit of green. Must be between 0 and 255.
bminThe lower limit of blue. Must be between 0 and 255.
bmaxThe upper limit of blue. Must be between 0 and 255.
Sets the image used as image-mask. It must be 1bit gray-scale color image.
(no version information, might be only in CVS)
HaruOutline::setDestination -- Set the destination for the outlineSets a destination object which becomes a target to jump to when the outline is clicked.
(no version information, might be only in CVS)
HaruOutline::setOpened -- Set the initial state of the outlineDefines whether this node is opened or not when the outline is displayed for the first time.
Appends an arc to the current path.
xHorizontal coordinate of the center.
yVertical coordinate of the center.
rayThe ray of the arc.
ang1The angle of the beginning.
ang2
The angle of the end. Must be greater than ang1.
(no version information, might be only in CVS)
HaruPage::beginText -- Begin a text object and set the current text position to (0,0)Begins new text object and sets the current text position to (0,0).
(no version information, might be only in CVS)
HaruPage::circle -- Append a circle to the current pathAppends a circle to the current path.
xHorizontal coordinate of the center point.
yVertical coordinate of the center point.
rayThe ray of the circle.
(no version information, might be only in CVS)
HaruPage::closePath -- Append a straight line from the current point to the start point of the pathAppends a straight line from the current point to the start point of the path.
(no version information, might be only in CVS)
HaruPage::concat -- Concatenate current transformation matrix of the page and the specified matrixConcatenates current transformation matrix of the page and the specified matrix.
(no version information, might be only in CVS)
HaruPage::createDestination -- Create new HaruDestination instanceCreates and returns new HaruDestination instance.
(no version information, might be only in CVS)
HaruPage::createLinkAnnotation -- Create new HaruAnnotation instanceCreates and returns new HaruAnnotation instance.
rectangleAn array with 4 coordinates of the clickable area.
destinationValid HaruDestination instance.
(no version information, might be only in CVS)
HaruPage::createTextAnnotation -- Create new HaruAnnotation instanceCreates and returns new HaruAnnotation instance.
rectangleAn array with 4 coordinates of the annotation area.
textThe text to be displayed.
encoderOptional HaruEncoder instance.
(no version information, might be only in CVS)
HaruPage::createURLAnnotation -- Create and return new HaruAnnotation instanceCreates and returns new HaruAnnotation instance.
(no version information, might be only in CVS)
HaruPage::curveTo2 -- Append a Bezier curve to the current pathAppends a Bezier curve to the current path. The current point and the point (x2, y2) are used as the control points for the Bezier curve and current point is moved to the point (x3, y3).
(no version information, might be only in CVS)
HaruPage::curveTo3 -- Append a Bezier curve to the current pathAppends a Bezier curve to the current path. The point (x1, y1) and the point (x3, y3) are used as the control points for a Bezier curve and current point is moved to the point (x3, y3).
(no version information, might be only in CVS)
HaruPage::curveTo -- Append a Bezier curve to the current pathAppend a Bezier curve to the current path. The point (x1, y1) and the point (x2, y2) are used as the control points for a Bezier curve and current point is moved to the point (x3, y3).
Show image at the page.
imageValid HaruImage instance.
xThe left border of the area where the image is displayed.
yThe lower border of the area where the image is displayed.
widthThe width of the image area.
heightThe height of the image area.
(no version information, might be only in CVS)
HaruPage::ellipse -- Append an ellipse to the current pathAppends an ellipse to the current path.
xHorizontal coordinate of the center.
yVertical coordinate of the center.
xrayThe ray of the ellipse in the x direction.
yrayThe ray of the ellipse in the y direction.
(no version information, might be only in CVS)
HaruPage::endPath -- End current path object without filling and painting operationsEnds current path object without performing filling and painting operations.
(no version information, might be only in CVS)
HaruPage::eofill -- Fill current path using even-odd rule(no version information, might be only in CVS)
HaruPage::eoFillStroke -- Fill current path using even-odd rule, then paint the pathFills current path using even-odd rule, then paints the path.
close_pathOptional parameter. When set to TRUE, the function closes the current path. Default to FALSE.
(no version information, might be only in CVS)
HaruPage::fill -- Fill current path using nonzero winding number rule(no version information, might be only in CVS)
HaruPage::fillStroke -- Fill current path using nonzero winding number rule, then paint the pathFills current path using nonzero winding number rule, then paints the path.
close_pathOptional parameter. When set to TRUE, the function closes the current path. Default to FALSE.
(no version information, might be only in CVS)
HaruPage::getCharSpace -- Get the current value of character spacing(no version information, might be only in CVS)
HaruPage::getCMYKFill -- Get the current filling colorReturns the current filling color as an array with 4 elements ("c", "m", "y" and "k").
(no version information, might be only in CVS)
HaruPage::getCMYKStroke -- Get the current stroking colorReturns the current stroking color as an array with 4 elements ("c", "m", "y" and "k").
(no version information, might be only in CVS)
HaruPage::getCurrentFont -- Get the currently used fontReturns the currently used font as an instance of HaruFont.
(no version information, might be only in CVS)
HaruPage::getCurrentFontSize -- Get the current font size(no version information, might be only in CVS)
HaruPage::getCurrentPos -- Get the current position for path paintingReturns the current position for path painting as an array of with two elements - "x" and "y".
(no version information, might be only in CVS)
HaruPage::getCurrentTextPos -- Get the current position for text printingReturns the current position for text printing as an array with 2 elements - "x" and "y".
Returns the current dash pattern as an array of two elements - "pattern" and "phase" or FALSE if dash pattern was not set. See HaruPage::setDash() for more information on dash patterns.
(no version information, might be only in CVS)
HaruPage::getFillingColorSpace -- Get the current filling color spaceReturns the current filling color space. The result value is one of the following:
| HaruDoc::CS_DEVICE_GRAY |
| HaruDoc::CS_DEVICE_RGB |
| HaruDoc::CS_DEVICE_CMYK |
| HaruDoc::CS_CAL_GRAY |
| HaruDoc::CS_CAL_RGB |
| HaruDoc::CS_LAB |
| HaruDoc::CS_ICC_BASED |
| HaruDoc::CS_SEPARATION |
| HaruDoc::CS_DEVICE_N |
| HaruDoc::CS_INDEXED |
| HaruDoc::CS_PATTERN |
Returns the current graphics mode. The result value is one of the following:
| HaruPage::GMODE_PAGE_DESCRIPTION |
| HaruPage::GMODE_TEXT_OBJECT |
| HaruPage::GMODE_PATH_OBJECT |
| HaruPage::GMODE_CLIPPING_PATH |
| HaruPage::GMODE_SHADING |
| HaruPage::GMODE_INLINE_IMAGE |
| HaruPage::GMODE_EXTERNAL_OBJECT |
(no version information, might be only in CVS)
HaruPage::getGrayFill -- Get the current filling color(no version information, might be only in CVS)
HaruPage::getGrayStroke -- Get the current stroking color(no version information, might be only in CVS)
HaruPage::getHorizontalScaling -- Get the current value of horizontal scalingReturns the current value of horizontal scaling.
(no version information, might be only in CVS)
HaruPage::getLineCap -- Get the current line cap styleReturns the current line cap style. The result value is one of the following:
| HaruPage::BUTT_END - the line is squared off at the endpoint of the path. |
| HaruPage::ROUND_END - the end of the line becomes a semicircle with center in the end point of the path. |
| HaruPage::PROJECTING_SCUARE_END - the line continues to the point that exceeds half of the stroke width the end point. |
(no version information, might be only in CVS)
HaruPage::getLineJoin -- Get the current line join styleReturns the current line join style. The result value is one of the following:
| HaruPage::MITER_JOIN |
| HaruPage::ROUND_JOIN |
| HaruPage::BEVEL_JOIN |
(no version information, might be only in CVS)
HaruPage::getMiterLimit -- Get the value of miter limitReturns the current filling color as an array with 3 elements: "r", "g" and "b".
(no version information, might be only in CVS)
HaruPage::getRGBStroke -- Get the current stroking color(no version information, might be only in CVS)
HaruPage::getStrokingColorSpace -- Get the current stroking color spaceReturns the current stroking color space. The list of return values is the same as for HaruPage::getFillingColorSpace().
(no version information, might be only in CVS)
HaruPage::getTextLeading -- Get the current value of line spacing(no version information, might be only in CVS)
HaruPage::getTextMatrix -- Get the current text transformation matrix of the pageReturns the current text transformation matrix of the page as an array of 6 elements: "a", "b", "c", "d", "x" and "y".
(no version information, might be only in CVS)
HaruPage::getTextRenderingMode -- Get the current text rendering modeReturns the current text rendering mode. The result value is one of the following:
| HaruPage::FILL |
| HaruPage::STROKE |
| HaruPage::FILL_THEN_STROKE |
| HaruPage::INVISIBLE |
| HaruPage::FILL_CLIPPING |
| HaruPage::STROKE_CLIPPING |
| HaruPage::FILL_STROKE_CLIPPING |
| HaruPage::CLIPPING |
(no version information, might be only in CVS)
HaruPage::getTextRise -- Get the current value of text rising(no version information, might be only in CVS)
HaruPage::getTextWidth -- Get the width of the text using current fontsize, character spacing and word spacingReturns the width of the text using current fontsize, character spacing and word spacing.
(no version information, might be only in CVS)
HaruPage::getTransMatrix -- Get the current transformation matrix of the pageReturns the current transformation matrix of the page as an array of 6 elements: "a", "b", "c", "d", "x" and "y".
(no version information, might be only in CVS)
HaruPage::getWordSpace -- Get the current value of word spacing(no version information, might be only in CVS)
HaruPage::lineTo -- Draw a line from the current point to the specified pointDraws a line from the current point to the specified point.
(no version information, might be only in CVS)
HaruPage::measureText -- Calculate the number of characters which can be included within the specified widthReturns the number of characters which can be included within the specified width.
textThe text to measure.
widthThe width of the area to put the text to.
wordwrapWhen this parameter is set to TRUE the function "emulates" word wrapping and doesn't include the part of the current word if reached the end of the area. Defaults to FALSE.
(no version information, might be only in CVS)
HaruPage::moveTextPos -- Move text position to the specified offset
Moves text position to the specified offset. If the start position of the current
line is (x1, y1), the start of the next line is (x1 + x,
y1 + y). If optional parameter set_leading
is TRUE, the function sets the text leading to -y. The default
value of set_leading is FALSE.
(no version information, might be only in CVS)
HaruPage::moveTo -- Set starting point for new drawing path(no version information, might be only in CVS)
HaruPage::moveToNextLine -- Move text position to the start of the next lineMoves text position to the start of the next line.
(no version information, might be only in CVS)
HaruPage::rectangle -- Append a rectangle to the current pathAppends a rectangle to the current drawing path.
xThe left border of the rectangle.
yThe lower border of the rectangle.
widthThe width of the rectangle.
heightThe height of the rectangle.
(no version information, might be only in CVS)
HaruPage::setCharSpace -- Set character spacing for the page(no version information, might be only in CVS)
HaruPage::setCMYKFill -- Set filling color for the pageDefines filling color for the page.
(no version information, might be only in CVS)
HaruPage::setCMYKStroke -- Set stroking color for the pageDefines stroking color for the page.
(no version information, might be only in CVS)
HaruPage::setDash -- Set the dash pattern for the pageDefines the dash pattern for the page.
patternAn array (8 elements max) which contains a pattern of dashes and gaps used for lines on the page.
phaseThe phase on which the pattern begins.
(no version information, might be only in CVS)
HaruPage::setFontAndSize -- Set font and fontsize for the pageDefines current font and its size for the page.
(no version information, might be only in CVS)
HaruPage::setGrayFill -- Set filling color for the page(no version information, might be only in CVS)
HaruPage::setGrayStroke -- Sets stroking color for the page(no version information, might be only in CVS)
HaruPage::setHorizontalScaling -- Set horizontal scaling for the pageDefines horizontal scaling for text showing on the page. The initial value is 100.
(no version information, might be only in CVS)
HaruPage::setLineCap -- Set the shape to be used at the ends of lines
capMust be one of the following values:
| HaruPage::BUTT_END - the line is squared off at the endpoint of the path. |
| HaruPage::ROUND_END - the end of the line becomes a semicircle with center in the end point of the path. |
| HaruPage::PROJECTING_SCUARE_END - the line continues to the point that exceeds half of the stroke width the end point. |
(no version information, might be only in CVS)
HaruPage::setLineJoin -- Set line join style for the page
joinMust be one of the following values:
| HaruPage::MITER_JOIN |
| HaruPage::ROUND_JOIN |
| HaruPage::BEVEL_JOIN |
(no version information, might be only in CVS)
HaruPage::setMiterLimit -- Set the current value of the miter limit of the pageDefines the current value of the miter limit of the page.
(no version information, might be only in CVS)
HaruPage::setRGBFill -- Set filling color for the pageDefines filling color for the page. All values must be between 0 and 1.
(no version information, might be only in CVS)
HaruPage::setRGBStroke -- Set stroking color for the pageDefines stroking color for the page. All values must be between 0 and 1.
(no version information, might be only in CVS)
HaruPage::setSize -- Set size and direction of the pageChanges size and direction of the page to a predefined format.
sizeMust be one of the following values:
| HaruPage::SIZE_LETTER |
| HaruPage::SIZE_LEGAL |
| HaruPage::SIZE_A3 |
| HaruPage::SIZE_A4 |
| HaruPage::SIZE_A5 |
| HaruPage::SIZE_B4 |
| HaruPage::SIZE_B5 |
| HaruPage::SIZE_EXECUTIVE |
| HaruPage::SIZE_US4x6 |
| HaruPage::SIZE_US4x8 |
| HaruPage::SIZE_US5x7 |
| HaruPage::SIZE_COMM10 |
directionMust be one of the following values:
| HaruPage::PORTRAIT |
| HaruPage::LANDSCAPE |
(no version information, might be only in CVS)
HaruPage::setSlideShow -- Set transition style for the pageDefines transition style for the page.
typeMust be one of the following values:
| HaruPage::TS_WIPE_RIGHT |
| HaruPage::TS_WIPE_LEFT |
| HaruPage::TS_WIPE_UP |
| HaruPage::TS_WIPE_DOWN |
| HaruPage::TS_BARN_DOORS_HORIZONTAL_OUT |
| HaruPage::TS_BARN_DOORS_HORIZONTAL_IN |
| HaruPage::TS_BARN_DOORS_VERTICAL_OUT |
| HaruPage::TS_BARN_DOORS_VERTICAL_IN |
| HaruPage::TS_BOX_OUT |
| HaruPage::TS_BOX_IN |
| HaruPage::TS_BLINDS_HORIZONTAL |
| HaruPage::TS_BLINDS_VERTICAL |
| HaruPage::TS_DISSOLVE |
| HaruPage::TS_GLITTER_RIGHT |
| HaruPage::TS_GLITTER_DOWN |
| HaruPage::TS_GLITTER_TOP_LEFT_TO_BOTTOM_RIGHT |
| HaruPage::TS_REPLACE |
disp_timeThe display duration of the page in seconds.
trans_timeThe duration of the transition effect in seconds.
(no version information, might be only in CVS)
HaruPage::setTextLeading -- Set text leading (line spacing) for the page(no version information, might be only in CVS)
HaruPage::setTextMatrix -- Set the current text transformation matrix of the pageDefines the text transformation matrix of the page.
(no version information, might be only in CVS)
HaruPage::setTextRenderingMode -- Set text rendering mode for the pageDefines text rendering mode for the page.
modeMust be one of the following values:
| HaruPage::FILL |
| HaruPage::STROKE |
| HaruPage::FILL_THEN_STROKE |
| HaruPage::INVISIBLE |
| HaruPage::FILL_CLIPPING |
| HaruPage::STROKE_CLIPPING |
| HaruPage::FILL_STROKE_CLIPPING |
| HaruPage::CLIPPING |
(no version information, might be only in CVS)
HaruPage::setTextRise -- Set the current value of text rising(no version information, might be only in CVS)
HaruPage::setWordSpace -- Set word spacing for the page(no version information, might be only in CVS)
HaruPage::showText -- Print text at the current position of the pagePrints out the text at the current position of the page.
(no version information, might be only in CVS)
HaruPage::showTextNextLine -- Move the current position to the start of the next line and print the textMoves the current position to the start of the next line and print out the text.
(no version information, might be only in CVS)
HaruPage::textOut -- Print the text on the specified positionPrints the text on the specified position.
(no version information, might be only in CVS)
HaruPage::textRect -- Print the text inside the specified regionPrints the text inside the specified region.
leftLeft border of the text area.
topTop border of the text area.
rightRight border of the text area.
bottomLower border of the text area.
textThe text to print.
alignText alignment. Must be one of the following values:
| HaruPage::TALING_LEFT |
| HaruPage::TALING_RIGHT |
| HaruPage::TALING_CENTER |
| HaruPage::TALING_JUSTIFY |
Message Digest (hash) engine. Allows direct or incremental processing of arbitrary length messages using a variety of hashing algorithms.
The Hash extension requires no external libraries and is enabled by default as of PHP 5.1.2. It may be explicitly disabled by using the --disable-hash switch to configure. Earlier versions of PHP may incorporate the Hash extension by installing the PECL module.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Optional flag for hash_init(). Indicates that the HMAC digest-keying algorithm should be applied to the current hashing context.
(no version information, might be only in CVS)
hash_algos -- Return a list of registered hashing algorithmsReturns a numerically indexed array containing the list of supported hashing algorithms.
Example 1. hash_algos() example As of PHP 5.1.2, hash_algos() will return the following list of algorithm names.
The above example will output:
|
(no version information, might be only in CVS)
hash_file -- Generate a hash value using the contents of a given file
algoName of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
filenameURL describing location of file to be hashed; Supports fopen wrappers.
raw_outputWhen set to TRUE, outputs raw binary data. Default value (FALSE) outputs lowercase hexits.
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
(no version information, might be only in CVS)
hash_final -- Finalize an incremental hash and return resulting digest
contextHashing context returned by hash_init().
raw_outputWhen set to TRUE, outputs raw binary data. Default value (FALSE) outputs lowercase hexits.
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
(no version information, might be only in CVS)
hash_hmac_file -- Generate a keyed hash value using the HMAC method and the contents of a given file
algoName of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
filenameURL describing location of file to be hashed; Supports fopen wrappers.
keyShared secret key used for generating the HMAC variant of the message digest.
raw_outputWhen set to TRUE, outputs raw binary data. Default value (FALSE) outputs lowercase hexits.
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
(no version information, might be only in CVS)
hash_hmac -- Generate a keyed hash value using the HMAC method
algoName of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
dataMessage to be hashed.
keyShared secret key used for generating the HMAC variant of the message digest.
raw_outputWhen set to TRUE, outputs raw binary data. Default value (FALSE) outputs lowercase hexits.
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
(no version information, might be only in CVS)
hash_init -- Initialize an incremental hashing context
algoName of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
options
Optional settings for hash generation, currently supports only one option:
HASH_HMAC. When specified, the key
must be specified.
key
When HASH_HMAC is specified for options,
a shared secret key to be used with the HMAC hashing method must be supplied in this
parameter.
Returns a Hashing Context resource for use with hash_update(), hash_update_stream(), hash_update_file(), and hash_final().
(no version information, might be only in CVS)
hash_update_file -- Pump data into an active hashing context from a file
contextHashing context returned by hash_init().
filenameURL describing location of file to be hashed; Supports fopen wrappers.
contextStream context as returned by stream_context_create().
(no version information, might be only in CVS)
hash_update_stream -- Pump data into an active hashing context from an open stream
contextHashing context returned by hash_init().
handleOpen file handle as returned by any stream creation function.
length
Maximum number of characters to copy from handle
into the hashing context.
(no version information, might be only in CVS)
hash_update -- Pump data into an active hashing context
contextHashing context returned by hash_init().
dataMessage to be included in the hash digest.
algoName of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
dataMessage to be hashed.
raw_outputWhen set to TRUE, outputs raw binary data. Default value (FALSE) outputs lowercase hexits.
Returns a string containing the calculated message digest as lowercase hexits
unless raw_output is set to true in which case the raw
binary representation of the message digest is returned.
This HTTP extension aims to provide a convenient and powerful set of functionality for one of PHPs major applications.
It eases handling of HTTP URLs, dates, redirects, headers and messages, provides means for negotiation of clients preferred language and charset, as well as a convenient way to send any arbitrary data with caching and resuming capabilities.
It provides powerful request functionality, if built with CURL support. Parallel requests are available for PHP 5 and greater.
Additionally to the API reference in this manual you can find information about how to install and configure as well as which global constants are predefined in the following sections:
| Installation |
| Configuration |
| Global Constants |
| Resource Types |
The classes below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The HttpResponse class requires at least PHP v5.1. Any other class is available as of PHP v5.0.
Note: Be aware though, that some methods are not available with PHP v5.0.
| HttpMessage |
| HttpQueryString |
| HttpDeflateStream |
| HttpInflateStream |
| HttpRequest |
| HttpRequestPool |
| HttpResponse |
Built-in HTTP related functions previously listed on this page can be found in the networking category.
The following functions do not need the HTTP module to be present: header(), headers_list(), headers_sent(), setcookie() and setrawcookie().
| http_build_cookie() |
| http_date() |
| http_get_request_body_stream() |
| http_get_request_body() |
| http_get_request_headers() |
| http_match_etag() |
| http_match_modified() |
| http_match_request_header() |
| http_support() |
| http_get() |
| http_head() |
| http_post_data() |
| http_post_fields() |
| http_put_data() |
| http_put_file() |
| http_put_stream() |
| http_request_body_encode() |
| http_request_method_exists() |
| http_request_method_name() |
| http_request_method_register() |
| http_request_method_unregister() |
| http_request() |
This PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/pecl_http.
Note: The official name of this extension is pecl_http.
The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
In order to be able to load this extension on Windows, you additionally need to load the following PHP extensions: hash, iconv and SPL.
The extension must be built with libcurl support to enable request functionality (--with-http-curl-requests). A library version equal or greater to v7.12.3 is required.
To enable support for sending and receiving compressed responses, the extension must be built with zlib support (--with-http-zlib-compression). A library version equal or greater than v1.2.2 is required.
Content type quessing can be enabled by building this extension with libmagic support (--with-http-magic-mime).
The behaviour of these functions is affected by settings in php.ini.
Table 1. HTTP Configuration Options
| Name | Default | Changeable | Description |
|---|---|---|---|
| http.etag.mode | "MD5" | PHP_INI_ALL | The hashing algorithm used to generate the ETag. MD5, SHA1, and CRC32 are always available. If the hash xtension is enabled, any hashing algorithms this extension provides are available, too. |
| http.log.cache | "" | PHP_INI_ALL | The path (or stream wrapper url) to a log file in which to write successful cache hits. |
| http.log.redirect | "" | PHP_INI_ALL | The path (or stream wrapper url) to a log file in which to write redirects. |
| http.log.not_found | "" | PHP_INI_ALL | The path (or stream wrapper url) to a log file in which to write "file not found" errors. |
| http.log.allowed_methods | "" | PHP_INI_ALL | The path (or stream wrapper url) to a log file in which to write "allowed methods" violations. |
| http.log.composite | "" | PHP_INI_ALL | The path (or stream wrapper url) to a log file in which to write all events. |
| http.request.methods.allowed | "" | PHP_INI_ALL | Allowed request methods. If a client issues a request with a request method other than listed here, PHP exits with a status of "405 Method not allowed". See the INI setting http.force_exit for what "exits" means. |
| http.request.methods.custom | "" | PHP_INI_PERDIR|PHP_INI_SYSTEM | Custom request methods. If you want to use any non-standard request methods, you can register them with this INI setting or http_request_method_register(). |
| http.request.datashare.cookie | "0" | PHP_INI_SYSTEM | Whether the global HttpRequestDataShare should by default share cookie information. |
| http.request.datashare.dns | "1" | PHP_INI_SYSTEM | Whether the global HttpRequestDataShare should by default share name lookup information. |
| http.request.datashare.ssl | "0" | PHP_INI_SYSTEM | Whether the global HttpRequestDataShare should by default share SSL session information. This is not yet implemented in libcurl. |
| http.request.datashare.connect | "0" | PHP_INI_SYSTEM | Whether the global HttpRequestDataShare should by default share connect information. This is not yet implemented in libcurl. |
| http.persistent.handles.limit | "-1" | PHP_INI_SYSTEM | The maximum amount of persistent handles to keep alive. |
| http.persistent.handles.ident | "GLOBAL" | PHP_INI_ALL | The ident of persistent handles. |
| http.send.inflate.start_auto | "0" | PHP_INI_PERDIR|PHP_INI_SYSTEM | Whether to automatically start the inflate output handler. |
| http.send.inflate.start_flags | "0" | PHP_INI_ALL | Initialization settings for the inflate output handler. |
| http.send.deflate.start_auto | "0" | PHP_INI_PERDIR|PHP_INI_SYSTEM | Whether to automatically start the deflate output handler. |
| http.send.deflate.start_flags | "0" | PHP_INI_ALL | Initialization settings for the deflate output handler. See deflate constants. |
| http.send.not_found_404 | "1" | PHP_INI_ALL | Whether to automatically exit with a status of "404 Not found", if http_send_file() was not able to find the specified file. See the INI setting http.force_exit for what "exits" means. |
| http.only_exceptions | "0" | PHP_INI_ALL | Whether all notices/warnings/errors should be thrown as exceptions. |
| http.force_exit | "1" | PHP_INI_ALL | Each occasion where "exits with a status of..." is mentioned, usually causes the halt of the scripting engine. Disable this option if you alternatively want to start a discarding (dev/null) output handler and continue script execution. |
This extension defines a stream resource returned by http_get_request_body_stream() and (thereafter) HttpResponse::getStream().
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Constants usable with http_support()
querying for this constant will always return TRUE
whether support to issue HTTP requests is given, ie. libcurl support was compiled in
whether support to guess the Content-Type of HTTP messages is given, ie. libmagic support was compiled in
whether support for zlib encodings is given, ie. libz support was compiled in
whether support to issue HTTP requests over SSL is givem, ie. linked libcurl was built with SSL support
Constants usable with http_parse_params()
allow commans additionally to semicolons as separator
continue parsing after an error occurred
raise PHP warnings on parse errors
all three values above, bitwise or'ed
Constants usable with http_parse_cookie() and its return value
Constants usable with http_deflate() and HttpDeflateStream
Constants usable with HttpDeflateStream and HttpInflateStream
Constants used for error reporting and Exceptions
runtime error
an invalid parameter was passed
header() or similar operation failed
HTTP header parse error
unknown/invalid request method
with operation incompatible message type
encoding/decoding error
request failure
request pool failure
socket exception
response failure
invalid URL
querystring operation failure
Constants usable with HttpMessage
Constants usable with HttpQueryString
Constants used for the httpauthtype request option
Constants used for the HTTP protocol version request option
Constants used for the SSL protocol type and version request option
Constants used for the proxytype request option
Constants used for the ipresolve request option
Predefined HTTP request method constants
Constants usable with http_redirect()
guess applicable redirect method
permanent redirect (301 Moved permanently)
standard redirect (302 Found)
Note: RFC 1945 and RFC 2068 specify that the client is not allowed to change the method on the redirected request. However, most existing user agent implementations treat 302 as if it were a 303 response, performing a GET on the Location field-value regardless of the original request method. The status codes 303 and 307 have been added for servers that wish to make unambiguously clear which kind of reaction is expected of the client.
redirect applicable to POST requests (303 See other)
proxy redirect (305 Use proxy)
temporary redirect (307 Temporary Redirect)
Constants usable with http_build_url()
replace every part of the first URL when there's one of the second URL
join relative paths
join query strings
strip any user authentication information
strip any password authentication information
strip any authentication information
strip explicit port numbers
strip complete path
strip query string
strip any fragments (#identifier)
strip anything but scheme and host
(no version information, might be only in CVS)
Request Options -- options usable with the HttpRequest class and request functionsOptions related to time outs
Options related to urls
the request url
use another port as specified in the url
whether and how many redirects to follow; defaults to 0
whether to continue sending credentials on redirects to a different host
the refererring url to send
Options related to cookies
whether custom cookies should be urlencode()d prior sending
list of cookies as associative array like array("cookie" => "value")
path to a file where cookies are/will be stored
don't load session cookies from cookiestore if TRUE
Options related to headers
the user agent to send; defaults to PECL::HTTP/x.y.z (PHP/x.y.z); omitted if explicitly set to an empty string
timestamp for If-(Un)Modified-Since header
quoted etag for If-(None-)Match header
list of custom headers as associative array like array("header" => "value")
Options related to authentication
Options related to proxies
Options related to the transfer
whether to request and accept a gzip/deflate content encoded response
start the download at the specified byte offset if server support is given (indicated by a 206 response code)
array of arrays, each containing two integers, specifying the ranges to download if server support is given (indicated by a 206 response code); only recognized if the resume option is empty
Options imposing limits
maximum file size that should be downloaded; has no effect, if the size of the requested entity is unknown (eg. dynamic pages with chunked transfer encoding etc.)
the lowest transfer speed a successful request may have
the time in which low_speed_limit must be transferred for a successful request
maximum send speed in bytes per second
maximum receive speed in bytes per second
Callback options
progress callback
Network options
SSL options
Note: SSL options are set through an array with the single "ssl" request option name.
path to certificate
type of certificate
password for certificate
path to key
type of key
pasword for key
ssl engine to use
ssl version to use
whether to verify the peer
whether to verify the host
list of allowed ciphers
Table 1. Instance Properties
| Modifiers | Type | Name | Description |
|---|---|---|---|
| protected | int | type | message type |
| protected | string | body | message body |
| protected | float | httpVersion | HTTP protocol version |
| protected | array | headers | message headers |
| protected | string | requestMethod | request method name |
| protected | requestUrl | string | request URL |
| protected | int | responseCode | response code |
| protected | string | responseStatus | response status message |
| protected | HttpMessage | parentMessage | reference to parent message |
Note: None of these default properties can be accessed by reference, array key/index notation nor be used in increment or decrement operations.
| HttpMessage::construct() |
| HttpMessage::factory() |
| HttpMessage::fromEnv() |
| HttpMessage::fromString() |
| HttpMessage::toString() |
| HttpMessage::toMessageTypeObject() |
| HttpMessage::guessContentType() |
| HttpMessage::detach() |
| HttpMessage::prepend() |
| HttpMessage::reverse() |
| HttpMessage::send() |
| HttpMessage::getParentMessage() |
| HttpMessage::getType() |
| HttpMessage::setType() |
| HttpMessage::getHttpVersion() |
| HttpMessage::setHttpVersion() |
| HttpMessage::getHeaders() |
| HttpMessage::getHeader() |
| HttpMessage::addHeaders() |
| HttpMessage::setHeaders() |
| HttpMessage::getBody() |
| HttpMessage::setBody() |
| HttpMessage::getRequestMethod() |
| HttpMessage::setRequestMethod() |
| HttpMessage::getRequestUrl() |
| HttpMessage::setRequestUrl() |
| HttpMessage::getResponseCode() |
| HttpMessage::setResponseCode() |
| HttpMessage::getResponseStatus() |
| HttpMessage::setResponseStatus() |
Instantiate a new HttpMessage object.
The constructed object will actually represent the last message of the passed string. If there were prior messages, those can be accessed by HttpMessage::getParentMessage().
(no version information, might be only in CVS)
HttpMessage::factory -- Create HttpMessage from stringCreate an HttpMessage object from a string.
raw_messagea single or several consecutive HTTP messages
class_namea class extending HttpMessage
(no version information, might be only in CVS)
HttpMessage::fromEnv -- Create HttpMessage from environmentCreate an HttpMessage object from script environment.
message_typeThe message type. See HttpMessage type constants.
class_namea class extending HttpMessage
(no version information, might be only in CVS)
HttpMessage::fromString -- Create HttpMessage from stringCreate an HttpMessage object from a string.
This function alias is deprecated and only exists for backwards compatibility reasons. It is recommended to not use this function as one day it may be removed from PHP.
raw_messagea single or several consecutive HTTP messages
class_namea class extending HttpMessage
Get the string representation of the Message.
include_parentspecifies whether the returned string should also contain any parent messages
(no version information, might be only in CVS)
HttpMessage::toMessageTypeObject -- Create HTTP object regarding message typeCreates an object regarding to the type of the message.
Attempts to guess the content type of the message body through libmagic.
Returns a clone of an HttpMessage object detached from any parent messages.
Prepends message(s) to the HTTP message.
messageHttpMessage object to prepend
topwhether to prepend to the top most or right this message
Throws HttpInvalidParamException if the message is located within the same message chain.
Reorders the message chain in reverse order.
Send the Message according to its type as Response or Request.
This provides limited functionality compared to HttpRequest and HttpResponse.
Get Message Type. Either HTTP_MSG_NONE, HTTP_MSG_REQUEST or HTTP_MSG_RESPONSE.
Set Message Type. Either HTTP_MSG_NONE, HTTP_MSG_REQUEST or HTTP_MSG_RESPONSE.
Get the HTTP Protocol Version of the Message.
Set the HTTP Protocol version of the Message.
Add headers. If append is true, headers with the same name will be separated, else overwritten.
headersassociative array containing the additional HTTP headers to add to the messages existing headers
appendif true, and a header with the same name of one to add exists already, this respective header will be converted to an array containing both header values, otherwise it will be overwritten with the new header value
headersassociative array containing the new HTTP headers, which will replace all previous HTTP headers of the message
Set the body of the HttpMessage.
Note: Don't forget to update any headers accordingly.
Get the Request Method of the Message.
Returns the request method name on success, or FALSE if the message is not of type HttpMessage::TYPE_REQUEST.
Set the Request Method of the HTTP Message.
Returns TRUE on success, or FALSE if the message is not of type HttpMessage::TYPE_REQUEST or an invalid request method was supplied.
Returns the request URL as string on success, or FALSE if the message is not of type HttpMessage::TYPE_REQUEST.
Set the Request URL of the HTTP Message.
Returns TRUE on success, or FALSE if the message is not of type HttpMessage::TYPE_REQUEST or supplied URL was empty.
Returns the HTTP response code if the message is of type HttpMessage::TYPE_RESPONSE, else FALSE.
Set the response code of an HTTP Response Message.
Returns TRUE on success, or FALSE if the message is not of type HttpMessage::TYPE_RESPONSE or the response code is out of range (100-510).
Get the Response Status of the message (i.e. the string following the response code).
Returns the HTTP response status string if the message is of type HttpMessage::TYPE_RESPONSE, else FALSE.
Set the Response Status of the HTTP message (i.e. the string following the response code).
Returns TRUE on success or FALSE if the message is not of type HttpMessage::TYPE_RESPONSE.
(no version information, might be only in CVS)
HttpQueryString::__construct -- HttpQueryString constructorCreates a new HttpQueryString object instance.
Operates on and modifies $_GET and $_SERVER['QUERY_STRING'] if global is TRUE.
globalwhether to operate on $_GET and $_SERVER['QUERY_STRING']
addadditional/initial query string parameters
(no version information, might be only in CVS)
HttpQueryString::singleton -- HttpQueryString singletonGet a single instance (differentiates between the global setting).
Get (part of) the query string.
The type parameter is either one of the HttpQueryString::TYPE_* constants or a type abbreviation like "b" for bool, "i" for int, "f" for float, "s" for string, "a" for array and "o" for a stdClass object.
keykey of the query string param to retrieve
typewhich variable type to enforce
defvaldefault value if key does not exist
deletewhether to remove the key/value pair from the query string
Returns the value of the query string param or the whole query string if no key was specified on success or defval if key does not exist.
Copies the query string object and sets provided params at the clone.
Set query string entry/entries. NULL values will unset the variable.
Get the query string represented as associative array.
(no version information, might be only in CVS)
HttpQueryString::xlate -- Change query strings charsetConverts the query string from the source encoding ie to the target encoding oe.
| Warning |
Don't use any character set that can contain NUL bytes like UTF-16. |
Note: This method requires ext/iconv to be enabled and loaded.
Table 1.
| Type | Name | Description |
|---|---|---|
| int | TYPE_GZIP | gzip encoding |
| int | TYPE_ZLIB | zlib AKA deflate encoding |
| int | TYPE_RAW | raw deflate encoding |
| int | LEVEL_DEF | default compression level |
| int | LEVEL_MIN | minimum compression level |
| int | LEVEL_MAX | maximum compression level |
| int | STRATEGY_DEF | default strategy |
| int | STRATEGY_FILT | filtered strategy |
| int | STRATEGY_HUFF | Huffman strategy |
| int | STRATEGY_RLE | RLE strategy |
| int | STRATEGY_FIXED | fixed strategy |
| int | FLUSH_NONE | no forced flush |
| int | FLUSH_SYNC | synching flush |
| int | FLUSH_FULL | full flush |
(no version information, might be only in CVS)
HttpDeflateStream::factory -- HttpDeflateStream class factoryCreates a new HttpDeflateStream object instance.
See the deflate stream constants table for possible flags.
(no version information, might be only in CVS)
HttpDeflateStream::__construct -- HttpDeflateStream class constructorCreates a new HttpDeflateStream object instance.
See the deflate stream constants table for possible flags.
Passes more data through the deflate stream.
Finalizes the deflate stream. The deflate stream can be reused after finalizing.
(no version information, might be only in CVS)
HttpInflateStream::factory -- HttpInflateStream class factoryCreates a new HttpInflateStream object instance.
See the inflate constants table for possible flags.
(no version information, might be only in CVS)
HttpInflateStream::__construct -- HttpInflateStream class constructorCreates a new HttpInflateStream object instance.
See the inflate constants table for possible flags.
Passes more data through the inflate stream.
Flushes the inflate stream.
Note: Flushing usually has no effect on inflate streams.
Finalizes the inflate stream. The inflate stream can be reused after finalizing.
Table 1. Instance Properties
| Modifiers | Type | Name | Description |
|---|---|---|---|
| protected | array | options | request options to configure the request; see request options |
| protected | array | postFields | form data: array("fieldname" => "fieldvalue") |
| protected | array | postFiles | files to upload: array(array("name" => "image", "file" => "/home/u/images/u.png", "type" => "image/png")) |
| protected | array | responseInfo | information (statistical) about the request/response; see Request/response information |
| protected | HttpMessage | responseMessage | the response message |
| protected | integer | responseCode | the numerical response code |
| protected | string | responseStatus | the literal response status text |
| protected | integer | method | the request method to use |
| protected | string | url | the request url |
| protected | string | contentType | the content type to use for raw post requests |
| protected | string | rawPostData | raw post data |
| protected | string | queryData | query parameters |
| protected | string | putFile | the file to upload with a PUT request |
| protected | string | putData | raw data to upload with a PUT request |
| protected | HttpMessage | history | the whole request/response history if history logging is enabled |
| public | boolean | recordHistory | whether to enable history logging |
Table 2.
| Type | Name | Description |
|---|---|---|
| integer | METH_GET | GET request method |
| integer | METH_HEAD | HEAD request method |
| integer | METH_POST | POST request method |
| integer | METH_PUT | PUT request method |
| integer | METH_DELETE | DELETE request method |
| integer | METH_OPTIONS | OPTIONS request method |
| integer | METH_TRACE | TRACE request method |
| integer | METH_CONNECT | CONNECT request method |
| integer | METH_PROPFIND | PROPFIND request method |
| integer | METH_PROPPATCH | PROPPATCH request method |
| integer | METH_MKCOL | MKCOL request method |
| integer | METH_COPY | COPY request method |
| integer | METH_MOVE | MOVE request method |
| integer | METH_LOCK | LOCK request method |
| integer | METH_UNLOCK | UNLOCK request method |
| integer | METH_VERSION_CONTROL | VERSION-CONTROL request method |
| integer | METH_REPORT | REPORT request method |
| integer | METH_CHECKOUT | CHECKOUT request method |
| integer | METH_CHECKIN | CHECKIN request method |
| integer | METH_UNCHECKOUT | UNCHECKOUT request method |
| integer | METH_MKWORKSPACE | MKWORKSPACE request method |
| integer | METH_UPDATE | UPDATE request method |
| integer | METH_LABEL | LABEL request method |
| integer | METH_MERGE | MERGE request method |
| integer | METH_BASELINE_CONTROL | BASELINE-CONTROL request method |
| integer | METH_MKACTIVITY | MKACTIVITY request method |
| integer | METH_ACL | ACL request method |
| integer | VERSION_1_0 | HTTP protocol version 1.0 |
| integer | VERSION_1_1 | HTTP protocol version 1.1 |
| integer | VERSION_ANY | any HTTP protocol version |
| integer | AUTH_BASIC | basic authentication |
| integer | AUTH_DIGEST | digest authentication |
| integer | AUTH_NTLM | NTLM authentication |
| integer | AUTH_GSSNEG | GSS negotiate authentication |
| integer | AUTH_ANY | any authentication |
| integer | PROXY_SOCKS4 | SOCKS v4 proxy |
| integer | PROXY_SOCKS5 | SOCKS v5 proxy |
| integer | PROXY_HTTP | HTTP proxy |
| integer | SSL_VERSION_TLSv1 | use TLS v1 |
| integer | SSL_VERSION_SSLv2 | use SSL v2 |
| integer | SSL_VERSION_SSLv3 | use SSL v3 |
| integer | SSL_VERSION_ANY | use any SSL/TLS method |
| integer | IPRESOLVE_V4 | resolve via IPv4 only |
| integer | IPRESOLVE_V6 | resolve via IPv6 only |
| integer | IPRESOLVE_ANY | use any resolving methods |
| HttpRequest::construct() |
| HttpRequest::getOptions() |
| HttpRequest::setOptions() |
| HttpRequest::getSslOptions() |
| HttpRequest::addSslOptions() |
| HttpRequest::setSslOptions() |
| HttpRequest::getUrl() |
| HttpRequest::setUrl() |
| HttpRequest::getMethod() |
| HttpRequest::setMethod() |
| HttpRequest::enableCookies() |
| HttpRequest::resetCookies() |
| HttpRequest::getCookies() |
| HttpRequest::addCookies() |
| HttpRequest::setCookies() |
| HttpRequest::getHeaders() |
| HttpRequest::addHeaders() |
| HttpRequest::setHeaders() |
| HttpRequest::getContentType() |
| HttpRequest::setContentType() |
| HttpRequest::getQueryData() |
| HttpRequest::addQueryData() |
| HttpRequest::setQueryData() |
| HttpRequest::getPostFields() |
| HttpRequest::addPostFields() |
| HttpRequest::setPostFields() |
| HttpRequest::getPostFiles() |
| HttpRequest::addPostFile() |
| HttpRequest::setPostFiles() |
| HttpRequest::getRawPostData() |
| HttpRequest::addRawPostData() |
| HttpRequest::setRawPostData() |
| HttpRequest::getPutData() |
| HttpRequest::addPutData() |
| HttpRequest::setPutData() |
| HttpRequest::getPutFile() |
| HttpRequest::setPutFile() |
| HttpRequest::send() |
| HttpRequest::getRequestMessage() |
| HttpRequest::getRawRequestMessage() |
| HttpRequest::getResponseMessage() |
| HttpRequest::getRawResponseMessage() |
| HttpRequest::getResponseCode() |
| HttpRequest::getResponseStatus() |
| HttpRequest::getResponseHeader() |
| HttpRequest::getResponseCookies() |
| HttpRequest::getResponseBody() |
| HttpRequest::getResponseData() |
| HttpRequest::getResponseInfo() |
| HttpRequest::clearHistory() |
| HttpRequest::getHistory() |
Add custom cookies.
Note: The request option encodecookies controls whether the cookie values should be urlencode()d.
Note: Affects any request method.
Add request header name/value pairs.
Adds POST data entries, leaving previously set unchanged, unless a post entry with the same name already exists.
Affects only POST and custom requests.
Add a file to the POST request, leaving previously set files unchanged.
Affects only POST and custom requests. Cannot be used with raw post data.
namethe form element name
filethe path to the file
content_typethe content type of the file
Returns TRUE on success, or FALSE if the content type seems not to contain a primary and a secondary content type part.
Add PUT data, leaving previously set PUT data unchanged.
Affects only PUT requests.
Add parameters to the query parameter list, leaving previously set unchanged.
Affects any request type.
Add raw post data, leaving previously set raw post data unchanged.
Affects only POST and custom requests.
Clears all history messages.
Note: History is only logged if
recordHistorywas enabled.
Instantiate a new HttpRequest object.
urlthe target request url
request_methodthe request method to use
optionsan associative array with request options
Enable automatic sending of received cookies.
Note: Note that cuutomly set cookies will be sent anyway.
Get all sent requests and received responses as an HttpMessage object.
If you want to record history, set the instance variable
HttpRequest::recordHistory to TRUE.
The returned object references the last received response, use HttpMessage::getParentMessage()() to access the data of previously sent requests and received responses.
Get the current query data in form of an urlencoded query string.
(no version information, might be only in CVS)
HttpRequest::getRawRequestMessage -- Get raw request message(no version information, might be only in CVS)
HttpRequest::getRawResponseMessage -- Get raw response messageReturns the complete web server response, including the headers in a form of a string.
Get sent HTTP message.
If redirects were allowed and several responses were received, the data references the last received response. Use HttpMessage::getParentMessage() to access the data of previously sent requests within this request cycle.
Note: Note that the internal request message is immutable, that means that the request message received through HttpRequest::getRequestMessage() will always look the same for the same request, regardless of any changes you may have made to the returned object.
Get the response body after the request has been sent.
If redirects were allowed and several responses were received, the data references the last received response.
Get the response code after the request has been sent.
If redirects were allowed and several responses were received, the data references the last received response.
(no version information, might be only in CVS)
HttpRequest::getResponseCookies -- Get response cookie(s)Get response cookie(s) after the request has been sent.
If redirects were allowed and several responses were received, the data references the last received response.
* Get all response data after the request has been sent.
If redirects were allowed and several responses were received, the data references the last received response.
Returns an associative array with the key "headers" containing an associative array holding all response headers, as well as the key "body" containing a string with the response body.
(no version information, might be only in CVS)
HttpRequest::getResponseHeader -- Get response header(s)Get response header(s) after the request has been sent.
If redirects were allowed and several responses were received, the data references the last received response.
Returns either a string with the value of the header matching name if requested, FALSE on failure, or an associative array containing all response headers.
Get response info after the request has been sent.
See http_get() for a full list of returned info.
If redirects were allowed and several responses were received, the data references the last received response.
namethe info to read; if empty or omitted, an associative array containing all available info will be returned
Returns either a scalar containing the value of the info matching name if requested, FALSE on failure, or an associative array containing all available info.
(no version information, might be only in CVS)
HttpRequest::getResponseMessage -- Get response messageGet the full response as HttpMessage object after the request has been sent.
If redirects were allowed and several responses were received, the data references the last received response. Use HttpMessage::getParentMessage() to access the data of previously received responses within this request cycle.
Get the response status (i.e. the string after the response code) after the message has been sent.
Reset all automatically received/sent cookies.
Note: Note that customly set cookies are not affected.
session_onlywhether only session cookies should be reset (needs libcurl >= v7.15.4, else libcurl >= v7.14.1)
Send the HTTP request.
Note: While an exception may be thrown, the transfer could have succeeded at least partially, so you might want to check the return values of various HttpRequest::getResponse*() methods.
Throws HttpRuntimeException, HttpRequestException, HttpMalformedHeaderException, HttpEncodingException.
Example 1. GET example
|
Example 2. POST example
|
Set the content type the post request should have.
Returns TRUE on success, or FALSE if the content type does not seem to contain a primary and a secondary part.
cookiesan associative array as parameter containing cookie name/value pairs; if empty or omitted, all previously set cookies will be unset
Set request header name/value pairs.
headersan associative array as parameter containing header name/value pairs; if empty or omitted, all previously set headers will be unset
Set the request options to use.
See the full list of request options.
optionsan associative array, which values will overwrite the currently set request options; if empty or omitted, the options of the HttpRequest object will be reset
Set the POST data entries, overwriting previously set POST data.
Affects only POST and custom requests.
post_dataan associative array containing the post fields; if empty, the post data will be unset
Set files to post, overwriting previously set post files.
Affects only POST and requests. Cannot be used with raw post data.
Set PUT data to send, overwriting previously set PUT data.
Affects only PUT requests.
Only either PUT data or PUT file can be used for each request. PUT data has higher precedence and will be used even if a PUT file is set.
Set file to put. Affects only PUT requests.
Set the URL query parameters to use, overwriting previously set query parameters.
Affects any request types.
query_dataa string or associative array parameter containing the pre-encoded query string or to be encoded query fields; if empty, the query data will be unset
Set raw post data to send, overwriting previously set raw post data. Don't forget to specify a content type. Affects only POST and custom requests.
Only either post fields or raw post data can be used for each request. Raw post data has higher precedence and will be used even if post fields are set.
optionsan associative array containing any SSL specific options; if empty or omitted, the SSL options will be reset
Attach an HttpRequest object to this HttpRequestPool.
| Warning |
Set all options prior attaching! |
Throws HttpInvalidParamException, HttpRequestException, HttpRequestPoolException, HttpEncodingException.
(no version information, might be only in CVS)
HttpRequestPool::__construct -- HttpRequestPool constructorInstantiate a new HttpRequestPool object. An HttpRequestPool is able to send several HttpRequests in parallel.
Accepts virtually infinite optional parameters each referencing an HttpRequest object.
Throws HttpRequestPoolException (HttpRequestException, HttpInvalidParamException).
Example 1. A HttpRequestPool example
|
(no version information, might be only in CVS)
HttpRequestPool::__destruct -- HttpRequestPool destructorDetach an HttpRequest object from this HttpRequestPool.
(no version information, might be only in CVS)
HttpRequestPool::getAttachedRequests -- Get attached requests(no version information, might be only in CVS)
HttpRequestPool::getFinishedRequests -- Get finished requestsGet attached HttpRequest objects that already have finished their work.
Returns an array containing all attached HttpRequest objects that already have finished their work.
Throws HttpRequestPoolException (HttpSocketException, HttpRequestException, HttpMalformedHeaderException).
(no version information, might be only in CVS)
HttpRequestPool::socketPerform -- Perform socket actionsReturns TRUE until each request has finished its transaction.
Example 1. A HttpRequestPool::socketPerform() example
|
(no version information, might be only in CVS)
HttpRequestPool::socketSelect -- Perform socket selectTable 1. Static Properties
| Modifiers | Type | Name | Description |
|---|---|---|---|
| protected | boolean | cache | whether caching the response should be attempted |
| protected | boolean | gzip | whether the sent entity should be gzip'ed on the fly |
| protected | string | eTag | the generated or custom ETag |
| protected | integer | lastModified | the generated or custom timestamp of last modification |
| protected | string | cacheControl | Cache-Control setting |
| protected | string | contentType | the Content-Type of the sent entity |
| protected | string | contentDisposition | the Content-Disposition of the sent entity |
| protected | integer | bufferSize | the chunk buffer size used for throttling |
| protected | double | throttleDelay | the seconds to delay when throttling |
Table 2.
| Type | Name | Description |
|---|---|---|
| integer | REDIRECT | guess applicable redirect method |
| integer | REDIRECT_PERM | permanent redirect (301 Moved permanently) |
| integer | REDIRECT_FOUND | standard redirect (302 Found) |
| integer | REDIRECT_POST | redirect applicable to POST requests (303 See other) |
| integer | REDIRECT_PROXY | proxy redirect (305 Use proxy) |
| integer | REDIRECT_TEMP | temporary redirect (307 Temporary Redirect) |
| HttpResponse::getBufferSize() |
| HttpResponse::setBufferSize() |
| HttpResponse::getCacheControl() |
| HttpResponse::setCacheControl() |
| HttpResponse::getCache() |
| HttpResponse::setCache() |
| HttpResponse::getContentDisposition() |
| HttpResponse::setContentDisposition() |
| HttpResponse::getContentType() |
| HttpResponse::setContentType() |
| HttpResponse::getData() |
| HttpResponse::setData() |
| HttpResponse::getETag() |
| HttpResponse::setETag() |
| HttpResponse::getFile() |
| HttpResponse::setFile() |
| HttpResponse::getGzip() |
| HttpResponse::setGzip() |
| HttpResponse::getHeader() |
| HttpResponse::setHeader() |
| HttpResponse::getLastModified() |
| HttpResponse::setLastModified() |
| HttpResponse::getStream() |
| HttpResponse::setStream() |
| HttpResponse::getThrottleDelay() |
| HttpResponse::setThrottleDelay() |
| HttpResponse::redirect() |
| HttpResponse::capture() |
| HttpResponse::send() |
| HttpResponse::guessContentType() |
| HttpResponse::redirect() |
| HttpResponse::status() |
| HttpResponse::getRequestHeaders() |
| HttpResponse::getRequestBody() |
| HttpResponse::getRequestBodyStream() |
| HttpResponse::setBufferSize() |
| HttpResponse::getThrottleDelay() |
| HttpResponse::setThrottleDelay() |
Get current Cache-Control header setting.
(no version information, might be only in CVS)
HttpResponse::getContentDisposition -- Get content dispositionGet current Content-Disposition setting.
| HttpResponse::setContentDisposition() |
| HttpResponse::getContentType() |
| HttpResponse::setContentType() |
Get current Content-Type header setting.
| HttpResponse::getContentDisposition() |
| HttpResponse::setContentDisposition() |
| HttpResponse::setContentType() |
| HttpResponse::guessContentType() |
| HttpResponse::setData() |
| HttpResponse::getFile() |
| HttpResponse::setFile() |
| HttpResponse::getStream() |
| HttpResponse::setStream() |
Get calculated or previously set custom ETag.
| HttpResponse::getData() |
| HttpResponse::setData() |
| HttpResponse::setFile() |
| HttpResponse::getStream() |
| HttpResponse::setStream() |
Get header(s) about to be sent.
Note: This may not work as expected with the following SAPI(s): Apache2 w/PHP < 5.1.3.
namespecifies the name of the header to read; if empty or omitted, an associative array with all headers will be returned
Returns either a string containing the value of the header matching name, FALSE on failure, or an associative array with all headers.
Get calculated or previously set custom Last-Modified date.
Get the previously set resource to be sent.
| HttpResponse::getData() |
| HttpResponse::setData() |
| HttpResponse::getFile() |
| HttpResponse::setFile() |
| HttpResponse::setStream() |
This function is an alias of: http_get_request_body().
(no version information, might be only in CVS)
HttpResponse::getRequestBodyStream -- Get request body streamThis function is an alias of: http_get_request_body_stream().
(no version information, might be only in CVS)
HttpResponse::getRequestHeaders -- Get request headersThis function is an alias of: http_get_request_headers().
Attempts to guess the content type of supplied payload through libmagic.
If the attempt is successful, the guessed Content-Type will automatically be set as response Content-Type.
This function is an alias of: http_redirect().
Finally send the entity.
A successful caching attempt will exit PHP, and write a log entry if the INI setting http.log.cache is set. See the INI setting http.force_exit for what "exits" means.
Sets the send buffer size of the throttling mechanism.
Note: Provides a basic throttling mechanism, which will yield the current process respectively thread until the entity has been completely sent.
Note: This may not work as expected with the following SAPI(s): FastCGI.
| HttpResponse::getBufferSize() |
| HttpResponse::getThrottleDelay() |
| HttpResponse::setThrottleDelay() |
Define a custom Cache-Control header, usually being private or public;
controlthe primary cache control setting
max_agethe max-age in seconds, suggesting how long the cache entry is valid on the client side
must_revalidatewhether the cached entity should be revalidated by the client for every request
Returns TRUE on success, or FALSE if control does not match one of public, private or no-cache.
Whether it should be attempted to cache the entity.
This will result in necessary caching headers and checks of clients If-Modified-Since and If-None-Match headers. If one of those headers matches a 304 Not Modified status code will be issued.
Note: If you're using sessions, be sure that you set session.cache_limiter to something more appropriate than "no-cache"!
(no version information, might be only in CVS)
HttpResponse::setContentDisposition -- Set content dispositionSet the Content-Disposition. The Content-Disposition header is very useful if the data actually sent came from a file or something similar, that should be "saved" by the client/user (i.e. by browsers "Save as..." popup window).
filenamethe file name the "Save as..." dialog should display
inlineif set to true and the user agent knows how to handle the content type, it will probably not cause the popup window to be shown
| HttpResponse::getContentDisposition() |
| HttpResponse::getContentType() |
| HttpResponse::setContentType() |
Set the Content-Type of the sent entity.
Returns TRUE on success, or FALSE if the content type does not seem to contain a primary and secondary content type part.
| HttpResponse::getContentDisposition() |
| HttpResponse::setContentDisposition() |
| HttpResponse::getContentType() |
| HttpResponse::guessContentType() |
Set the data to be sent.
Note: Previously calculated or defined ETag and Last-Modified will be recalculated and redefined.
| HttpResponse::getData() |
| HttpResponse::getFile() |
| HttpResponse::setFile() |
| HttpResponse::getStream() |
| HttpResponse::setStream() |
Set a custom ETag. Use this only if you know what you're doing.
Set the file to be sent.
Note: Previously calculated or defined ETag and Last-Modified will be recalculated and redefined.
| HttpResponse::getData() |
| HttpResponse::setData() |
| HttpResponse::getFile() |
| HttpResponse::getStream() |
| HttpResponse::setStream() |
Enable on-thy-fly gzip'ing of the sent entity.
Send an HTTP header.
namethe name of the header
valuethe value of the header; if not set, no header with this name will be sent
replacewhether an existing header should be replaced
Set a custom Last-Modified date.
Set the resource to be sent.
Note: Previously calculated or defined ETag and Last-Modified will be recalculated and redefined.
| HttpResponse::getData() |
| HttpResponse::setData() |
| HttpResponse::getFile() |
| HttpResponse::setFile() |
| HttpResponse::getStream() |
Sets the throttle delay.
Note: Provides a basic throttling mechanism, which will yield the current process respectively thread until the entity has been completely sent.
Note: This may not work as expected with the following SAPI(s): FastCGI.
This function is an alias of: http_send_status().
Attempts to cache the sent entity by its ETag, either supplied or generated by the hash algorithm specified by the INI setting http.etag.mode.
If the clients If-None-Match header matches the supplied/calculated ETag, the body is considered cached on the clients side and a 304 Not Modified status code is issued.
A log entry is written to the cache log if the INI setting http.log.cache is set and the cache attempt was successful.
Note: This function may be used in conjunction with http_send_data(), http_send_file() and http_send_stream().
If this function is used outside the http_send_*() API, it facilitates the ob_etaghandler().
Returns FALSE or exits on success with 304 Not Modified if the entity is cached. See the INI setting http.force_exit for what "exits" means.
| http_cache_last_modified() |
| ob_etaghandler() |
| http_match_etag() |
| the HttpResponse class if you are using PHP-5.1 and above |
Attempts to cache the sent entity by its last modification date.
If the supplied argument is greater than 0, it is handled as timestamp and will be sent as date of last modification. If it is 0 or omitted, the current time will be sent as Last-Modified date. If it's negative, it is handled as expiration time in seconds, which means that if the requested last modification date is not between the calculated timespan, the Last-Modified header is updated and the actual body will be sent.
A log entry will be written to the cache log if the INI setting http.log.cache is set and the cache attempt was successful.
Note: This function may be used in conjunction with http_send_data(), http_send_file() and http_send_stream().
Returns FALSE or exits on success with 304 Not Modified if the entity is cached. See the INI setting http.force_exit for what "exits" means.
Decodes a string which is HTTP-chunked encoded.
Compress data with gzip, zlib AKA deflate or raw deflate encoding.
See the deflate constants table for possible values for the flags parameter.
Decompress data compressed with either gzip, deflate AKA zlib or raw deflate encoding.
(no version information, might be only in CVS)
http_get_request_body_stream -- Get request body as streamCreate a stream to read the raw request body (e.g. POST or PUT data).
This function can only be used once if the request method was another than POST.
| http_get_request_body() |
| http_get_request_headers() |
| the HttpResponse class if you are using PHP-5.1 and above |
Get the raw request body (e.g. POST or PUT data).
This function can not be used after http_get_request_body_stream() if the request method was another than POST.
| http_get_request_body_stream() |
| http_get_request_headers() |
| the HttpResponse class if you are using PHP-5.1 and above |
| http_get_request_body() |
| http_get_request_body_stream() |
| the HttpResponse class if you are using PHP-5.1 and above |
Compose a valid HTTP date regarding RFC 1123 looking like: Wed, 22 Dec 2004 11:34:47 GMT.
Check for features that require external libraries.
See the feature support constants table
for possible values for the feature argument.
Returns integer, whether requested feature is supported,
or a bitmask with all supported features if feature was omitted.
Matches the given ETag against the clients If-Match resp. If-None-Match HTTP headers.
etagthe ETag to match
for_rangeif set to TRUE, the header usually used to validate HTTP ranges will be checked
| http_match_last_modified() |
| http_match_request_header() |
| http_cache_etag() |
| http_cache_last_modified() |
| ob_etaghandler() |
Matches the given Unix timestamp against the clients If-Modified-Since resp. If-Unmodified-Since HTTP headers.
timestampUnix timestamp; current time, if omitted
for_rangeif set to TRUE, the header usually used to validate HTTP ranges will be checked
Match an incoming HTTP header.
headerthe header name (case-insensitive)
valuethe header value that should be compared
match_casewhether the value should be compared case sensitively
Build a cookie string from an array/object like returned by http_parse_cookie().
This function negotiates the clients preferred charset based on its Accept-Charset HTTP header. The qualifier is recognized and charsets without qualifier are rated highest.
supportedarray containing the supported charsets as values
resultwill be filled with an array containing the negotiation results
Returns the negotiated charset or the default charset (i.e. first array entry) if none match.
Example 1. Using http_negotiate_charset()
|
(no version information, might be only in CVS)
http_negotiate_content_type -- Negotiate clients preferred content typeThis function negotiates the clients preferred content type based on its Accept HTTP header. The qualifier is recognized and content types without qualifier are rated highest.
supportedarray containing the supported content types as values
resultwill be filled with an array containing the negotiation results
Returns the negotiated content type or the default content type (i.e. first array entry) if none match.
This function negotiates the clients preferred language based on its Accept-Language HTTP header. The qualifier is recognized and languages without qualifier are rated highest. The qualifier will be decreased by 10% for partial matches (i.e. matching primary language).
supportedarray containing the supported languages as values
resultwill be filled with an array containing the negotiation results
Returns the negotiated language or the default language (i.e. first array entry) if none match.
For use with ob_start().
Note: This output handler can only be used once.
The deflate output buffer handler can only be used once.
It conflicts with ob_gzhandler() and zlib.output_compression as well and should not be used after mbstring extension's mb_output_handler() and session extension's URL-Rewriter (AKA session.use_trans_sid).
For use with ob_start().
Output buffer handler generating an ETag with the hash algorithm specified with the INI setting http.etag.mode.
This output handler is used by http_cache_etag().
For use with ob_start().
Same restrictions as with ob_deflatehandler() apply.
Parses HTTP cookies like sent in a response into a struct.
cookiestring containing the value of a Set-Cookie response header
flagsparse flags (HTTP_COOKIE_PARSE_RAW)
allowed_extrasarray containing recognized extra keys; by default all unknown keys will be treated as cookie names
Example 1. Using http_parse_cookie()
The above example will output:
|
Parses HTTP headers into an associative array.
Example 1. Using http_parse_headers()
The above example will output:
|
Parses the HTTP message into a simple
recursive object.
Example 1. Using http_parse_message()
The above example will output something similar to:
|
Parse parameter list.
See the params parsing constants table for possible
values of the flags argument.
(no version information, might be only in CVS)
http_persistent_handles_count -- Stat persistent handlesList statistics about persistent handles usage.
Returns persistent handles statistics as stdClass object on success or FALSE on failure.
Example 1. A http_persistent_handles_count() example
The above example will output:
|
(no version information, might be only in CVS)
http_persistent_handles_ident -- Get/set ident of persistent handlesQuery or define the ident of persistent handles.
Example 1. A http_persistent_handles_ident() example
The above example will output:
|
(no version information, might be only in CVS)
http_persistent_handles_clean -- Clean up persistent handlesClean up (close) persistent handles, optionally identified with ident.
Performs an HTTP GET request on the supplied url.
See the full list of request options.
Example 1. A http_get() example
The above example will output:
|
Performs an HTTP HEAD request on the supplied url.
See the full list of request options.
Performs an HTTP POST request on the supplied url.
See the full list of request options.
Performs an HTTP POST request on the supplied url.
See the full list of request options.
Performs an HTTP PUT request on the supplied url.
See the full list of request options.
Performs an HTTP PUT request on the supplied url.
See the full list of request options.
Performs an HTTP PUT request on the supplied url.
See the full list of request options.
Check if a request method is registered (or available by default).
Get the literal string representation of a standard or registered request method.
Unregister a previously registered custom request method.
Performs a custom HTTP request on the supplied url.
See the full list of request options.
Generate x-www-form-urlencoded resp. form-data encoded request body.
Redirect to the given url.
The supplied url will be expanded with http_build_url(), the params array will
be treated with http_build_str() and the session identification will be appended
if session is true. The HTTP response code will be set according to status.
You can use one of the redirect constants for convenience.
Please see RFC 2616
for which redirect response code to use in which situation. By default PHP will decide which response status fits best.
To be RFC compliant, "Redirecting to <a>URL</a>." will be displayed, if the client doesn't redirect immediately, and the request method was another one than HEAD.
A log entry will be written to the redirect log, if the INI setting http.log.redirect is set and the redirect attempt was successful.
urlthe URL to redirect to
paramsassociative array of query parameters
sessionwhether to append session information
statuscustom response status code
Returns FALSE or exits on success with the specified redirection status code. See the INI setting http.force_exit for what "exits" means.
Example 1. A http_redirect() example
The above example will output:
|
Send the Content-Disposition. The Content-Disposition header is very useful if the data actually sent came from a file or something similar, that should be "saved" by the client/user (i.e. by browsers "Save as..." popup window).
Note: This function is supposed to be used in conjunction with http_send_data(), http_send_file() and http_send_stream().
filenamethe file name the "Save as..." dialog should display
inlineif set to TRUE and the user agent knows how to handle the content type, it will probably not cause the popup window to be shown
| http_send_data() |
| http_send_file() |
| http_send_stream() |
| the HttpResponse class if you are using PHP-5.1 and above |
Send the Content-Type of the sent entity.
Note: This function is supposed to be used in conjunction with http_send_data(), http_send_file() and http_send_stream().
Raises an E_WARNING when the content_type
doesn't seem to contain a primary and a secondary part.
| http_send_data() |
| http_send_file() |
| http_send_stream() |
| the HttpResponse class if you are using PHP-5.1 and above |
Sends raw data with support for (multiple) range requests.
| http_send_file() |
| http_send_stream() |
| http_throttle() |
| http_send_content_type() |
| http_send_content_disposition() |
| the HttpResponse class if you are using PHP-5.1 and above |
Sends a file with support for (multiple) range requests.
This functions behaviour and further action is dependent on the following INI settings: http.send.not_found_404 and http.log.not_found.
If the INI setting http.send.not_found_404
is enabled and the INI setting http.log.not_found
points to a writable file, a log message is written when the file was not found.
Example 1. A http_send_file() example
The above example will output:
|
| http_send_data() |
| http_send_stream() |
| http_throttle() |
| http_send_content_type() |
| http_send_content_disposition() |
| the HttpResponse class if you are using PHP-5.1 and above |
Send a Last-Modified header with a valid HTTP date.
Note: This function is supposed to be used in conjunction with http_send_data(), http_send_file() and http_send_stream().
timestampa Unix timestamp, converted to a valid HTTP date; if omitted, the current time will be sent
Sends an already opened stream with support for (multiple) range requests.
| http_send_data() |
| http_send_file() |
| http_throttle() |
| http_send_content_type() |
| http_send_content_disposition() |
| the HttpResponse class if you are using PHP-5.1 and above |
Sets the throttle delay and send buffer size.
Note: This function is supposed to be used in conjunction with http_send_data(), http_send_file() and http_send_stream().
Note: Provides a basic throttling mechanism, which will yield the current process respectively thread until the entity has been completely sent.
Note: This may not work as expected with the following SAPI(s): FastCGI.
| http_send_data() |
| http_send_file() |
| http_send_stream() |
| the HttpResponse class if you are using PHP-5.1 and above |
Opponent to parse_str().
queryassociative array of query string parameters
prefixtop level prefix
arg_separatorargument separator to use (by default the INI setting arg_separator.output will be used, or "&" if neither is set
Build an URL.
The parts of the second URL will be merged into the first according to the flags argument.
url(part(s) of) an URL in form of a string or associative array like parse_url() returns
partssame as the first argument
flagsa bitmask of binary or'ed HTTP_URL constants; HTTP_URL_REPLACE is the default
new_urlif set, it will be filled with the parts of the composed url like parse_url() would return
Example 1. A http_build_url() example
The above example will output:
|
Hyperwave has been developed at IICM in Graz. It started with the name Hyper-G and changed to Hyperwave when it was commercialised (in 1996).
Hyperwave is not free software. The current version, 5.5 is available at http://www.hyperwave.com/. A time limited version can be ordered for free (30 days).
See also the Hyperwave API module.
Hyperwave is an information system similar to a database (HIS, Hyperwave Information Server). Its focus is the storage and management of documents. A document can be any possible piece of data that may as well be stored in file. Each document is accompanied by its object record. The object record contains meta data for the document. The meta data is a list of attributes which can be extended by the user. Certain attributes are always set by the Hyperwave server, other may be modified by the user. An attribute is a name/value pair of the form name=value. The complete object record contains as many of those pairs as the user likes. The name of an attribute does not have to be unique, e.g. a title may appear several times within an object record. This makes sense if you want to specify a title in several languages. In such a case there is a convention, that each title value is preceded by the two letter language abbreviation followed by a colon, e.g. 'en:Title in English' or 'ge:Titel in deutsch'. Other attributes like a description or keywords are potential candidates. You may also replace the language abbreviation by any other string as long as it separated by colon from the rest of the attribute value.
Each object record has native a string representation with each name/value pair separated by a newline. The Hyperwave extension also knows a second representation which is an associated array with the attribute name being the key. Multilingual attribute values itself form another associated array with the key being the language abbreviation. Actually any multiple attribute forms an associated array with the string left to the colon in the attribute value being the key. (This is not fully implemented. Only the attributes Title, Description and Keyword are treated properly yet.)
Besides the documents, all hyper links contained in a document are stored as object records as well. Hyper links which are in a document will be removed from it and stored as individual objects, when the document is inserted into the database. The object record of the link contains information about where it starts and where it ends. In order to gain the original document you will have to retrieve the plain document without the links and the list of links and reinsert them. The functions hw_pipedocument() and hw_gettext() do this for you. The advantage of separating links from the document is obvious. Once a document to which a link is pointing to changes its name, the link can easily be modified accordingly. The document containing the link is not affected at all. You may even add a link to a document without modifying the document itself.
Saying that hw_pipedocument() and hw_gettext() do the link insertion automatically is not as simple as it sounds. Inserting links implies a certain hierarchy of the documents. On a web server this is given by the file system, but Hyperwave has its own hierarchy and names do not reflect the position of an object in that hierarchy. Therefore creation of links first of all requires a mapping from the Hyperwave hierarchy and namespace into a web hierarchy respective web namespace. The fundamental difference between Hyperwave and the web is the clear distinction between names and hierarchy in Hyperwave. The name does not contain any information about the objects position in the hierarchy. In the web the name also contains the information on where the object is located in the hierarchy. This leads to two possibles ways of mapping. Either the Hyperwave hierarchy and name of the Hyperwave object is reflected in the URL or the name only. To make things simple the second approach is used. Hyperwave object with name my_object is mapped to http://host/my_object disregarding where it resides in the Hyperwave hierarchy. An object with name parent/my_object could be the child of my_object in the Hyperwave hierarchy, though in a web namespace it appears to be just the opposite and the user might get confused. This can only be prevented by selecting reasonable object names.
Having made this decision a second problem arises. How do you
involve PHP? The URL http://host/my_object will
not call any PHP script unless you tell your web server to rewrite it to
e.g. http://host/php_script/my_object and the script
php_script evaluates the $PATH_INFO
variable and retrieves the object with name my_object
from the Hyperwave server. Their is just one little
drawback which can be fixed easily. Rewriting any URL would not allow
any access to other document on the web server. A PHP script for
searching in the Hyperwave server would be impossible. Therefore
you will need at least a second rewriting rule to exclude certain
URLs like all e.g. starting with http://host/Hyperwave
This is basically sharing of a namespace by the web and Hyperwave server.
Based on the above mechanism links are insert into documents.
It gets more complicated if PHP is not run as a server module or CGI script but as a standalone application e.g. to dump the content of the Hyperwave server on a CD-ROM. In such a case it makes sense to retain the Hyperwave hierarchy and map in onto the file system. This conflicts with the object names if they reflect its own hierarchy (e.g. by choosing names including '/'). Therefore '/' has to be replaced by another character, e.g. '_'.
The network protocol to communicate with the Hyperwave server is called HG-CSP (Hyper-G Client/Server Protocol). It is based on messages to initiate certain actions, e.g. get object record. In early versions of the Hyperwave Server two native clients (Harmony, Amadeus) were provided for communication with the server. Those two disappeared when Hyperwave was commercialised. As a replacement a so called wavemaster was provided. The wavemaster is like a protocol converter from HTTP to HG-CSP. The idea is to do all the administration of the database and visualisation of documents by a web interface. The wavemaster implements a set of placeholders for certain actions to customise the interface. This set of placeholders is called the PLACE Language. PLACE lacks a lot of features of a real programming language and any extension to it only enlarges the list of placeholders. This has led to the use of JavaScript which IMO does not make life easier.
Adding Hyperwave support to PHP should fill in the gap of a missing programming language for interface customisation. It implements all the messages as defined by the HG-CSP but also provides more powerful commands to e.g. retrieve complete documents.
Hyperwave has its own terminology to name certain pieces of information. This has widely been taken over and extended. Almost all functions operate on one of the following data types.
object ID: A unique integer value for each object in the Hyperwave server. It is also one of the attributes of the object record (ObjectID). Object ids are often used as an input parameter to specify an object.
object record: A string with attribute-value pairs of the form attribute=value. The pairs are separated by a carriage return from each other. An object record can easily be converted into an object array with hw_object2array(). Several functions return object records. The names of those functions end with obj.
object array: An associative array with all attributes of an object. The keys are the attribute names. If an attribute occurs more than once in an object record it will result in another indexed or associative array. Attributes which are language depended (like the title, keyword, description) will form an associative array with the keys set to the language abbreviations. All other multiple attributes will form an indexed array. PHP functions never return object arrays.
hw_document: This is a complete new data type which holds the actual document, e.g. HTML, PDF etc. It is somewhat optimized for HTML documents but may be used for any format.
Several functions which return an array of object records do also return an associative array with statistical information about them. The array is the last element of the object record array. The statistical array contains the following entries:
Number of object records with attribute PresentationHints set to Hidden.
Number of object records with attribute PresentationHints set to CollectionHead.
Number of object records with attribute PresentationHints set to FullCollectionHead.
Index in array of object records with attribute PresentationHints set to CollectionHead.
Index in array of object records with attribute PresentationHints set to FullCollectionHead.
Total: Number of object records.
This PECL extension is not bundled with PHP.
In order to use these functions you must compile PHP with Hyperwave support
by using the --with-hyperwave[=DIR]
configure option.
Windows users will enable php_hyperwave.dll inside of php.ini in order to use these functions. The DLL for this PECL extension may be downloaded from either the PHP Downloads page or from http://pecl4win.php.net/
The Hyperwave extension is best used when PHP is compiled as an Apache module. In such a case the underlying Hyperwave server can be hidden from users almost completely if Apache uses its rewriting engine. The following instructions will explain this.
Since PHP with Hyperwave support built into Apache is intended
to replace the native Hyperwave solution based on Wavemaster, we
will assume that the Apache server will only serve as a Hyperwave
web interface for these examples. This is not necessary but it simplifies
the configuration. The concept is quite simple. First of all you
need a PHP script which evaluates the $_ENV['PATH_INFO']
variable and treats its value as the name of a Hyperwave
object. Let's call this script 'Hyperwave'. The URL
http://your.hostname/Hyperwave/name_of_object
would than return the Hyperwave object with the name
'name_of_object'. Depending on the type of the object
the script has to react accordingly. If it is a collection, it will probably
return a list of children. If it is a document it will return the
mime type and the content. A slight improvement can be achieved
if the Apache rewriting engine is used. From the users point of
view it would be more straight forward if the URL
http://your.hostname/name_of_object would
return the object. The rewriting rule is quite easy:
to return the object itself
to allow searching
to identify yourself
to set your profile
one for each additional function like to show the object attributes, to show information about users, to show the status of the server, etc.
As an alternative to the Rewrite Engine, you can also consider using the Apache ErrorDocument directive, but be aware, that ErrorDocument redirected pages cannot receive POST data.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Hyperwave configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| hyperwave.allow_persistent | "0" | PHP_INI_SYSTEM | Available since PHP 4.3.2. |
| hyperwave.default_port | "418" | PHP_INI_ALL |
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
There are still some things to do:
The hw_InsertDocument has to be split into hw_insertobject() and hw_putdocument().
The names of several functions are not fixed, yet.
Most functions require the current connection as its first parameter. This leads to a lot of typing, which is quite often not necessary if there is just one open connection. A default connection will improve this.
Conversion form object record into object array needs to handle any multiple attribute.
(PHP 3 >= 3.0.4, PHP 4, PECL)
hw_Array2Objrec -- Convert attributes from object array to object record
Converts an object_array into an object record.
Multiple attributes like 'Title' in different languages are treated
properly.
See also hw_objrec2array().
| Warning |
This function is currently not documented; only the argument list is available. |
Returns an array of object ids. Each id
belongs to a child of the collection with ID
objectID.
The array contains all children both documents and collections.
Returns an array of object records. Each object record
belongs to a child of the collection with ID
objectID.
The array contains all children both documents and collections.
Returns FALSE if connection is not a valid connection index, otherwise TRUE. Closes down the connection to a Hyperwave server with the given connection index.
Opens a connection to a Hyperwave server and returns a connection
index on success, or FALSE if the connection
could not be made. Each of the arguments should be a quoted string,
except for the port number. The username and
password arguments are
optional and can be left out. In such a case no identification with
the server will be done. It is similar to identify as user anonymous.
This function returns a connection
index that is needed by other Hyperwave functions. You can have
multiple connections open at once. Keep in mind, that the password
is not encrypted.
See also hw_pconnect().
(PHP 3 >= 3.0.3, PHP 4, PECL)
hw_connection_info -- Prints information about the connection to Hyperwave server
| Warning |
This function is currently not documented; only the argument list is available. |
Copies the objects with object ids as specified in the second
parameter to the collection
with the id destination id.
The value return is the number of copied objects.
See also hw_mv().
Deletes the object with the given object id in the second parameter. It will delete all instances of the object.
Returns TRUE if no error occurs otherwise FALSE.
See also hw_mv().
Returns an th object id of the document to
which anchorID belongs.
Returns an th object record of the document to
which anchorID belongs.
Returns the object record of the document.
For backward compatibility, hw_documentattributes() is also accepted. This is deprecated, however.
See also hw_document_bodytag(), and hw_document_size().
Returns the BODY tag of the document. If the document is an HTML document the BODY tag should be printed before the document.
See also hw_document_attributes(), and hw_document_size().
For backward compatibility, hw_documentbodytag() is also accepted. This is deprecated, however.
Returns the content of the document. If the document is an HTML document the content is everything after the BODY tag. Information from the HEAD and BODY tag is in the stored in the object record.
See also hw_document_attributes(), hw_document_size(), and hw_document_setcontent().
Sets or replaces the content of the document. If the document is an HTML document the content is everything after the BODY tag. Information from the HEAD and BODY tag is in the stored in the object record. If you provide this information in the content of the document too, the Hyperwave server will change the object record accordingly when the document is inserted. Probably not a very good idea. If this functions fails the document will retain its old content.
See also hw_document_attributes(), hw_document_size(), and hw_document_content().
Returns the size in bytes of the document.
See also hw_document_bodytag(), and hw_document_attributes().
For backward compatibility, hw_documentsize() is also accepted. This is deprecated, however.
| Warning |
This function is currently not documented; only the argument list is available. |
Uploads the text document to the server. The object record of the document may not be modified while the document is edited. This function will only works for pure text documents. It will not open a special data connection and therefore blocks the control connection during the transfer.
See also hw_pipedocument(), hw_free_document(), hw_document_bodytag(), hw_document_size(), hw_output_document(), and hw_gettext().
Returns the last error number. If the return value is 0 no error has occurred. The error relates to the last command.
Returns a string containing the last error message or 'No Error'. If FALSE is returned, this function failed. The message relates to the last command.
Frees the memory occupied by the Hyperwave document.
Returns an array of object ids with anchors of the document
with object ID objectID.
Returns an array of object records with anchors of the document
with object ID objectID.
Returns the object record for the object with ID
objectID.
It will also lock the object, so other users cannot access
it until it is unlocked.
See also hw_unlock(), and hw_getobject().
Returns an array of object ids. Each object ID
belongs to a child collection of the collection with ID
objectID. The function will not
return child documents.
See also hw_children(), and hw_getchilddoccoll().
Returns an array of object records. Each object records
belongs to a child collection of the collection with ID
objectID. The function will not return
child documents.
See also hw_childrenobj(), and hw_getchilddoccollobj().
Returns array of object ids for child documents of a collection.
See also hw_children(), and hw_getchildcoll().
(PHP 3 >= 3.0.3, PHP 4, PECL)
hw_GetChildDocCollObj -- Object records of child documents of collectionReturns an array of object records for child documents of a collection.
See also hw_childrenobj(), and hw_getchildcollobj().
Returns the object record for the object with ID
objectID if the second parameter is an integer.
If the second parameter is an array of integer the function will
return an array of object records. In such a case the last
parameter is also evaluated which is a query string.
The query string has the following syntax:
<expr> ::= "(" <expr> ")" |
"!" <expr> | /* NOT */
<expr> "||" <expr> | /* OR */
<expr> "&&" <expr> | /* AND */
<attribute> <operator> <value>
<attribute> ::= /* any attribute name (Title, Author, DocumentType ...) */
<operator> ::= "=" | /* equal */
"<" | /* less than (string compare) */
">" | /* greater than (string compare) */
"~" /* regular expression matching */
The query allows to further select certain objects from the list of given objects. Unlike the other query functions, this query may use not indexed attributes. How many object records are returned depends on the query and if access to the object is allowed.
See also hw_getandlock(), and hw_getobjectbyquery().
Searches for objects on the whole server and returns an array of
object ids. The maximum number of matches is limited to
max_hits. If max_hits
is set to -1 the maximum number of matches is unlimited.
The query will only work with indexed attributes.
See also hw_getobjectbyqueryobj().
Searches for objects in collection with ID
objectID and returns an array of
object ids. The maximum number of matches is limited to
max_hits.
If max_hits
is set to -1 the maximum number of matches is unlimited.
The query will only work with indexed attributes.
See also hw_getobjectbyquerycollobj().
Searches for objects in collection with ID
objectID and returns an array of
object records. The maximum number of matches is limited to
max_hits.
If max_hits
is set to -1 the maximum number of matches is unlimited.
The query will only work with indexed attributes.
See also hw_getobjectbyquerycoll().
Searches for objects on the whole server and returns an array of
object records. The maximum number of matches is limited to
max_hits. If max_hits
is set to -1 the maximum number of matches is unlimited.
The query will only work with indexed attributes.
See also hw_getobjectbyquery().
Returns an indexed array of object ids. Each object id belongs to
a parent of the object with ID objectID.
Returns an indexed array of object records plus an associated array with statistical
information about the object records. The associated array is the
last entry of the returned array. Each object record belongs to
a parent of the object with ID objectID.
| Warning |
This function is currently not documented; only the argument list is available. |
Returns a remote document. Remote documents in Hyperwave notation are documents retrieved from an external source. Common remote documents are for example external web pages or queries in a database. In order to be able to access external sources through remote documents Hyperwave introduces the HGI (Hyperwave Gateway Interface) which is similar to the CGI. Currently, only ftp, http-servers and some databases can be accessed by the HGI. Calling hw_getremote() returns the document from the external source. If you want to use this function you should be very familiar with HGIs. You should also consider to use PHP instead of Hyperwave to access external sources. Adding database support by a Hyperwave gateway should be more difficult than doing it in PHP.
See also hw_getremotechildren().
Returns the children of a remote document. Children of a remote document are remote documents itself. This makes sense if a database query has to be narrowed and is explained in Hyperwave Programmers' Guide. If the number of children is 1 the function will return the document itself formatted by the Hyperwave Gateway Interface (HGI). If the number of children is greater than 1 it will return an array of object record with each maybe the input value for another call to hw_getremotechildren(). Those object records are virtual and do not exist in the Hyperwave server, therefore they do not have a valid object ID. How exactly such an object record looks like is up to the HGI. If you want to use this function you should be very familiar with HGIs. You should also consider to use PHP instead of Hyperwave to access external sources. Adding database support by a Hyperwave gateway should be more difficult than doing it in PHP.
See also hw_getremote().
Returns the object records of all anchors pointing to the object with ID
objectID. The object can either be a document
or an anchor of type destination.
See also hw_getanchors().
Returns the document with object ID
objectID. If the document
has anchors which can be inserted, they will be inserted already.
The optional parameter rootID/prefix can
be a string or an integer. If it is an integer it determines
how links are inserted
into the document. The default is 0 and will result in links that
are constructed from the name of the link's destination object. This
is useful for web applications. If a link points to an object with
name 'internet_movie' the HTML link will be
<A HREF="/internet_movie">. The actual location of the source and
destination object in the document hierarchy is disregarded. You
will have to set up your web browser, to rewrite that URL to for
example '/my_script.php3/internet_movie'. 'my_script.php3' will
have to evaluate $PATH_INFO and retrieve the document.
All links will have the prefix '/my_script.php3/'. If you do not
want this you can set the optional parameter
rootID/prefix to any prefix which
is used instead. Is this case it has to be a string.
If rootID/prefix is an integer and
unequal to 0 the link is constructed from all the names
starting at the object with the id rootID/prefix
separated by a slash relative to the current object.
If for example the above document 'internet_movie' is located
at 'a-b-c-internet_movie' with '-' being the separator between
hierarchy levels on the Hyperwave server and the source document is
located at 'a-b-d-source' the resulting HTML link would be:
<A HREF="../c/internet_movie">. This is useful if you want
to download the whole server content onto disk and map
the document hierarchy onto the file system.
This function will only work for pure text documents. It will not open a special data connection and therefore blocks the control connection during the transfer.
See also hw_pipedocument(), hw_free_document(), hw_document_bodytag(), hw_document_size(), and hw_output_document().
Identifies as user with username and
password. Identification
is only valid for the current session. I do not think this
function will be needed very often. In most cases it will
be easier to identify with the opening of the connection.
See also hw_connect().
Checks whether a set of objects (documents or collections)
specified by the object_id_array is part of
the collections listed in collection_id_array.
When the fourth parameter return_collections is 0,
the subset of object ids that is part of the collections (i.e.,
the documents or collections that are children of one or more
collections of collection ids or their subcollections, recursively)
is returned as an array. When the fourth parameter is 1, however, the
set of collections that have one or more objects of this subset as
children are returned as an array. This option allows a client to,
e.g., highlight the part of the collection hierarchy that contains
the matches of a previous query, in a graphical overview.
Returns information about the current connection. The returned string has the following format: <Serverstring>, <Host>, <Port>, <Username>, <Port of Client>, <Byte swapping>
Inserts a new collection with attributes as in
object_array into
collection with object ID objectID.
Inserts a new document with attributes as in
object_record into collection with object ID
parentID. This function inserts either
an object record only or an object record and a pure ascii text in
text if text is given.
If you want to insert a general document of any kind use
hw_insertdocument() instead.
See also hw_insertdocument(), and hw_inscoll().
| Warning |
This function is currently not documented; only the argument list is available. |
Uploads a document into the collection with
parent_id.
The document has to be created before with
hw_new_document(). Make sure that
the object record of the new document contains at least
the attributes: Type, DocumentType, Title and Name. Possibly
you also want to set the MimeType. The functions returns the
object id of the new document or FALSE.
See also hw_pipedocument().
Inserts an object into the server. The object can be any valid hyperwave object. See the HG-CSP documentation for a detailed information on how the parameters have to be.
Note: If you want to insert an Anchor, the attribute Position has always been set either to a start/end value or to 'invisible'. Invisible positions are needed if the annotation has no corresponding link in the annotation text.
See also hw_pipedocument(), hw_insertdocument(), hw_insdoc(), and hw_inscoll().
Maps a global object id on any hyperwave server, even those you did not connect to with hw_connect(), onto a virtual object id. This virtual object id can then be used as any other object id, e.g. to obtain the object record with hw_getobject(). The server id is the first part of the global object id (GOid) of the object which is actually the IP number as an integer.
Note: In order to use this function you will have to set the F_DISTRIBUTED flag, which can currently only be set at compile time in hg_comm.c. It is not set by default. Read the comment at the beginning of hg_comm.c
This command allows to remove, add, or modify individual attributes
of an object record. The object is specified by the Object ID
object_to_change. The first array
remove is a list of attributes to remove.
The second array add is a list of attributes
to add. In order to modify an attribute one will have to remove
the old one and add a new one. hw_modifyobject()
will always remove the attributes before it adds attributes unless
the value of the attribute to remove is not a string or array.
The last parameter determines if the modification is performed recursively. 1 means recursive modification. If some of the objects cannot be modified they will be skipped without notice. hw_error() may not indicate an error though some of the objects could not be modified.
The keys of both arrays are the attributes name. The value of each array element can either be an array, a string or anything else. If it is an array each attribute value is constructed by the key of each element plus a colon and the value of each element. If it is a string it is taken as the attribute value. An empty string will result in a complete removal of that attribute. If the value is neither a string nor an array but something else, e.g. an integer, no operation at all will be performed on the attribute. This is necessary if you want to add a completely new attribute not just a new value for an existing attribute. If the remove array contained an empty string for that attribute, the attribute would be tried to be removed which would fail since it doesn't exist. The following addition of a new value for that attribute would also fail. Setting the value for that attribute to e.g. 0 would not even try to remove it and the addition will work.
If you would like to change the attribute 'Name' with the current value 'books' into 'articles' you will have to create two arrays and call hw_modifyobject().
Note: Multilingual attributes, e.g. 'Title', can be modified in two ways. Either by providing the attributes value in its native form 'language':'title' or by providing an array with elements for each language as described above. The above example would than be:
Note: This will remove all attributes with the name 'Title' and adds a new 'Title' attribute. This comes in handy if you want to remove attributes recursively.
Note: If you need to delete all attributes with a certain name you will have to pass an empty string as the attribute value.
Note: Only the attributes 'Title', 'Description' and 'Keyword' will properly handle the language prefix. If those attributes don't carry a language prefix, the prefix 'xx' will be assigned.
Note: The 'Name' attribute is somewhat special. In some cases it cannot be complete removed. You will get an error message 'Change of base attribute' (not clear when this happens). Therefore you will always have to add a new Name first and than remove the old one.
Note: You may not surround this function by calls to hw_getandlock() and hw_unlock(). hw_modifyobject() does this internally.
Returns TRUE on success or FALSE on failure.
Moves the objects with object ids as specified in the second
parameter from the collection with id source_id
to the collection with the id destination_id.
If the destination id is 0 the objects will
be unlinked from the source collection. If this is the last instance
of that object it will be deleted. If you want to delete all instances
at once, use hw_deleteobject().
The value returned is the number of moved objects.
See also hw_cp(), and hw_deleteobject().
Returns a new Hyperwave document with document data set to
document_data and object record set to
object_record. The length of the
document_data has to passed in
document_sizeThis function does not
insert the document into the Hyperwave server.
See also hw_free_document(), hw_document_size(), hw_document_bodytag(), hw_output_document(), and hw_insertdocument().
(PHP 3 >= 3.0.3, PHP 4, PECL)
hw_objrec2array -- Convert attributes from object record to object array
Converts an object_record into an object array.
The keys of the resulting array are the attributes names.
Multi-value attributes like 'Title' in different languages form its own
array. The keys of this array are the left part to the colon of the
attribute value. This left part must be two characters long.
Other multi-value attributes without a prefix form an indexed array.
If the optional parameter is missing the
attributes 'Title', 'Description'
and 'Keyword' are treated as language attributes and the attributes
'Group', 'Parent' and 'HtmlAttr' as non-prefixed multi-value attributes.
By passing an array holding the type for each attribute you can
alter this behaviour. The array is an associated array with the attribute
name as its key and the value being one of
HW_ATTR_LANG or HW_ATTR_NONE.
See also hw_array2objrec().
Prints the document without the BODY tag.
For backward compatibility, hw_outputdocument() is also accepted. This is deprecated, however.
Returns a connection index on success, or FALSE if the connection
could not be made. Opens a persistent connection to a Hyperwave
server. Each of the arguments should be a quoted string,
except for the port number. The username
and password arguments are
optional and can be left out. In such a case no identification with
the server will be done. It is similar to identify as user anonymous.
This function returns a connection
index that is needed by other Hyperwave functions. You can have
multiple persistent connections open at once.
See also hw_connect().
Returns the Hyperwave document with object ID
objectID. If the document
has anchors which can be inserted, they will have been inserted already.
The document will be transferred via a special data connection which
does not block the control connection.
See also hw_gettext() for more on link insertion, hw_free_document(), hw_document_size(), hw_document_bodytag(), and hw_output_document().
Returns the object ID of the hyperroot collection. Currently this is always 0. The child collection of the hyperroot is the root collection of the connected server.
| Warning |
This function is currently not documented; only the argument list is available. |
| Warning |
This function is currently not documented; only the argument list is available. |
Unlocks a document, so other users regain access.
See also hw_getandlock().
Returns an array of users currently logged into the Hyperwave server. Each entry in this array is an array itself containing the elements id, name, system, onSinceDate, onSinceTime, TotalTime and self. 'self' is 1 if this entry belongs to the user who initiated the request.
Hyperwave has been developed at IICM in Graz. It started with the name Hyper-G and changed to Hyperwave when it was commercialised (in 1996).
Hyperwave is not free software. The current version, 5.5, is available at http://www.hyperwave.com/. A time limited version can be ordered for free (30 days).
See also the Hyperwave module.
Hyperwave is an information system similar to a database (HIS, Hyperwave Information Server). Its focus is the storage and management of documents. A document can be any possible piece of data that may as well be stored in file. Each document is accompanied by its object record. The object record contains meta data for the document. The meta data is a list of attributes which can be extended by the user. Certain attributes are always set by the Hyperwave server, other may be modified by the user.
Note: This extension has been moved to the PECL repository and is no longer bundled with PHP as of PHP 5.2.0.
Since 2001 there is a Hyperwave SDK available. It supports Java, JavaScript and C++. This PHP Extension is based on the C++ interface. In order to activate the hwapi support in PHP you will have to install the Hyperwave SDK first.
The integration with Apache and possible other servers is already described in the Hyperwave module which has been the first extension to connect a Hyperwave Server.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Hyperwave API configuration options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| hwapi.allow_persistent | "0" | PHP_INI_SYSTEM |
The API provided by the HW_API extension is fully object oriented. It is very similar to the C++ interface of the Hyperwave SDK. It consist of the following classes.
HW_API
HW_API_Object
HW_API_Attribute
HW_API_Error
HW_API_Content
HW_API_Reason
Each class has certain method, whose names are identical to its counterparts in the Hyperwave SDK. Passing arguments to this function differs from all the other PHP extensions but is close to the C++ API of the HW SDK. Instead of passing several parameters they are all put into an associated array and passed as one parameter. The names of the keys are identical to those documented in the HW SDK. The common parameters are listed below. If other parameters are required they will be documented if needed.
objectIdentifier The name or id of an object, e.g. "rootcollection", "0x873A8768 0x00000002".
parentIdentifier The name or id of an object which is considered to be a parent.
object An instance of class HW_API_Object.
parameters An instance of class HW_API_Object.
version The version of an object.
mode An integer value determine the way an operation is executed.
attributeSelector Any array of strings, each containing a name of an attribute. This is used if you retrieve the object record and want to include certain attributes.
objectQuery A query to select certain object out of a list of objects. This is used to reduce the number of objects which was delivered by a function like hw_api->children() or hw_api->find().
Note: Methods returning boolean can return TRUE, FALSE or HW_API_Error object.
(no version information, might be only in CVS)
hw_api_attribute->langdepvalue -- Returns value for a given languageReturns the value in the given language of the attribute.
(no version information, might be only in CVS)
hw_api_attribute->value -- Returns value of the attribute(no version information, might be only in CVS)
hw_api_attribute->values -- Returns all values of the attribute(no version information, might be only in CVS)
hw_api_attribute -- Creates instance of class hw_api_attributeCreates a new instance of hw_api_attribute with the given name and value.
This function checks in an object or a whole hierarchy of objects. The parameters array contains the required element 'objectIdentifier' and the optional element 'version', 'comment', 'mode' and 'objectQuery'. 'version' sets the version of the object. It consists of the major and minor version separated by a period. If the version is not set, the minor version is incremented. 'mode' can be one of the following values:
Checks in and commits the object. The object must be a document.
If the object to check in is a collection, all children will be checked in recursively if they are documents. Trying to check in a collection would result in an error.
Checks in an object even if it is not under version control.
Check if the new version is different from the last version. Unless this is the case the object will be checked in.
Keeps the time modified from the most recent object.
The object is not automatically committed on check-in.
This function checks out an object or a whole hierarchy of objects.
parameterThe parameters array contains the required element 'objectIdentifier' and the optional element 'version', 'mode' and 'objectQuery'. 'mode' can be one of the following values:
Checks out an object. The object must be a document.
If the object to check out is a collection, all children will be checked out recursively if they are documents. Trying to check out a collection would result in an error.
Retrieves the children of a collection or the attributes of a document. The children can be further filtered by specifying an object query.
parameterThe parameter array contains the required elements 'objectIdentifier' and the optional elements 'attributeSelector' and 'objectQuery'.
Reads len bytes from the content into the given
buffer.
This function returns the content of a document as an object of type hw_api_content.
parameterThe parameter array contains the required elements 'objectidentifier' and the optional element 'mode'. The mode can be one of the constants HW_API_CONTENT_ALLLINKS, HW_API_CONTENT_REACHABLELINKS or HW_API_CONTENT_PLAIN.
HW_API_CONTENT_ALLLINKS means to insert all anchors even if the destination is not reachable.
HW_API_CONTENT_REACHABLELINKS tells this method to insert only reachable links and HW_API_CONTENT_PLAIN will lead to document without any links.
This function will make a physical copy including the content if it exists and returns the new object or an error object.
parameterThe parameter array contains the required elements 'objectIdentifier' and 'destinationParentIdentifier'. The optional parameter is 'attributeSelector'`
(no version information, might be only in CVS)
hw_api->dbstat -- Returns statistics about database serverReturns statistics about database server.
(no version information, might be only in CVS)
hw_api->dcstat -- Returns statistics about document cache serverReturns statistics about document cache server.
(no version information, might be only in CVS)
hw_api->dstanchors -- Returns a list of all destination anchorsRetrieves all destination anchors of an object.
parameterThe parameter array contains the required element 'objectIdentifier' and the optional elements 'attributeSelector' and 'objectQuery'.
(no version information, might be only in CVS)
hw_api->dstofsrcanchor -- Returns destination of a source anchorRetrieves the destination object pointed by the specified source anchors. The destination object can either be a destination anchor or a whole document.
parameterThe parameters array contains the required element 'objectIdentifier' and the optional element 'attributeSelector'.
This functions searches for objects either by executing a key or/and full text query. The found objects can further be filtered by an optional object query. They are sorted by their importance. The second search operation is relatively slow and its result can be limited to a certain number of hits. This allows to perform an incremental search, each returning just a subset of all found documents, starting at a given index.
parameterThe parameter array contains the 'keyquery' or/and 'fulltextquery' depending on who you would like to search. Optional parameters are 'objectquery', 'scope', 'languages' and 'attributeselector'. In case of an incremental search the optional parameters 'startIndex', 'numberOfObjectsToGet' and 'exactMatchUnit' can be passed.
(no version information, might be only in CVS)
hw_api->ftstat -- Returns statistics about fulltext serverReturns statistics about fulltext server.
Opens a connection to the Hyperwave server on host
hostname. The protocol used is HGCSP.
(no version information, might be only in CVS)
hw_api->hwstat -- Returns statistics about Hyperwave serverReturns statistics about Hyperwave server.
Returns an object of typeHW_API_Error if identification failed or TRUE if it was successful.
(no version information, might be only in CVS)
hw_api->info -- Returns information about server configurationReturns information about server configuration.
Insert a new object. The object type can be user, group, document or anchor. Depending on the type other object attributes has to be set.
parameterThe parameter array contains the required elements 'object' and 'content' (if the object is a document) and the optional parameters 'parameters', 'mode' and 'attributeSelector'. The 'object' must contain all attributes of the object. 'parameters' is an object as well holding further attributes like the destination (attribute key is 'Parent'). 'content' is the content of the document. 'mode' can be a combination of the following flags:
The object in inserted into the server.
(no version information, might be only in CVS)
hw_api->insertanchor -- Inserts a new object of type anchorThis function is a shortcut for hwapi_insert(). It inserts an object of type anchor and sets some of the attributes required for an anchor.
parameterThe parameter array contains the required elements 'object' and 'documentIdentifier' and the optional elements 'destinationIdentifier', 'parameter', 'hint' and 'attributeSelector'. The 'documentIdentifier' specifies the document where the anchor shall be inserted. The target of the anchor is set in 'destinationIdentifier' if it already exists. If the target does not exists the element 'hint' has to be set to the name of object which is supposed to be inserted later. Once it is inserted the anchor target is resolved automatically.
(no version information, might be only in CVS)
hw_api->insertcollection -- Inserts a new object of type collectionThis function is a shortcut for hwapi_insert(). It inserts an object of type collection and sets some of the attributes required for a collection.
parameterThe parameter array contains the required elements 'object' and 'parentIdentifier' and the optional elements 'parameter' and 'attributeSelector'. See hwapi_insert() for the meaning of each element.
(no version information, might be only in CVS)
hw_api->insertdocument -- Inserts a new object of type documentThis function is a shortcut for hwapi_insert(). It inserts an object with content and sets some of the attributes required for a document.
parameterThe parameter array contains the required elements 'object', 'parentIdentifier' and 'content' and the optional elements 'mode', 'parameter' and 'attributeSelector'.
See hwapi_insert() for the meaning of each element.
Creates a link to an object. Accessing this link is like accessing the object to links points to.
parameterThe parameter array contains the required elements 'objectIdentifier' and 'destinationParentIdentifier'. 'destinationParentIdentifier' is the target collection.
Locks an object for exclusive editing by the user calling this function. The object can be only unlocked by this user or the system user.
parameterThe parameter array contains the required element 'objectIdentifier' and the optional parameters 'mode' and 'objectquery'.
'mode' determines how an object is locked. HW_API_LOCK_NORMAL means, an object is locked until it is unlocked. HW_API_LOCK_RECURSIVE is only valid for collection and locks all objects within the collection and possible subcollections. HW_API_LOCK_SESSION means, an object is locked only as long as the session is valid.
(no version information, might be only in CVS)
hw_api_content -- Create new instance of class hw_api_content
Creates a new content object from the string
content.
Clones the attributes of an object.
(no version information, might be only in CVS)
hw_api_object->attreditable -- Checks whether an attribute is editableChecks whether an attribute is editable.
Adds an attribute to the object.
(no version information, might be only in CVS)
hw_api_object -- Creates a new instance of class hw_api_objectCreates a new instance of the class hw_api_object.
Removes the attribute with the given name.
This function retrieves the attribute information of an object of any version. It will not return the document content.
parameterThe parameter array contains the required elements 'objectIdentifier' and the optional elements 'attributeSelector' and 'version'.
The returned object is an instance of class HW_API_Object on success or HW_API_Error if an error occurred.
This simple example retrieves an object and checks for errors.
Example 1. Retrieve an object
|
(no version information, might be only in CVS)
hw_api->objectbyanchor -- Returns the object an anchor belongs toThis function retrieves an object the specified anchor belongs to.
parameterThe parameter array contains the required element 'objectIdentifier' and the optional element 'attributeSelector'.
Retrieves the parents of an object. The parents can be further filtered by specifying an object query.
parameterThe parameter array contains the required elements 'objectidentifier' and the optional elements 'attributeselector' and 'objectquery'.
(no version information, might be only in CVS)
hw_api_reason->description -- Returns description of reasonRemoves an object from the specified parent. Collections will be removed recursively.
parameterYou can pass an optional object query to remove only those objects which match the query. An object will be deleted physically if it is the last instance.
The parameter array contains the required elements 'objectidentifier' and 'parentidentifier'. If you want to remove a user or group 'parentidentifier' can be skipped.
The optional parameter 'mode' determines how the deletion is performed. In normal mode the object will not be removed physically until all instances are removed. In physical mode all instances of the object will be deleted immediately. In removelinks mode all references to and from the objects will be deleted as well. In nonrecursive the deletion is not performed recursive. Removing a collection which is not empty will cause an error.
Replaces the attributes and the content of an object.
parameterThe parameter array contains the required elements 'objectIdentifier' and 'object' and the optional parameters 'content', 'parameters', 'mode' and 'attributeSelector'. 'objectIdentifier' contains the object to be replaced. 'object' contains the new object. 'content' contains the new content. 'parameters' contain extra information for HTML documents. HTML_Language is the letter abbreviation of the language of the title. HTML_Base sets the base attribute of the HTML document.
'mode' can be a combination of the following flags:
The object on the server is replace with the object passed.
(no version information, might be only in CVS)
hw_api->setcommittedversion -- Commits version other than last versionCommits a version of a document. The committed version is the one which is visible to users with read access. By default the last version is the committed version.
(no version information, might be only in CVS)
hw_api->srcanchors -- Returns a list of all source anchorsRetrieves all source anchors of an object.
parameterThe parameter array contains the required element 'objectIdentifier' and the optional elements 'attributeSelector' and 'objectQuery'.
(no version information, might be only in CVS)
hw_api->srcsofdst -- Returns source of a destination objectRetrieves all the source anchors pointing to the specified destination. The destination object can either be a destination anchor or a whole document.
parameterThe parameters array contains the required element 'objectIdentifier' and the optional element 'attributeSelector' and 'objectQuery'. The function returns an array of objects or an error.
Unlocks a locked object. Only the user who has locked the object and the system user may unlock an object.
parameterThe parameter array contains the required element 'objectIdentifier' and the optional parameters 'mode' and 'objectquery'. The meaning of 'mode' is the same as in function hwapi_lock().
(no version information, might be only in CVS)
hw_api->userlist -- Returns a list of all logged in usersi18n support.
| Warning |
This extension is still in development and it isn't available to public yet. |
This function returns the default Locale, which is used by PHP to localize certain features. Please note that this isn't influenced by setlocale() or the system settings.
Sets the default Locale for PHP programs. Please note that this has nothing to do with setlocale() nor with the system locale.
nameThe new Locale name. A comprehensive list of the supported locales is available at http://www-950.ibm.com/software/globalization/icu/demo/locales/en/?d_=en.
Example 1. A locale_set_default() example This example demonstrates a possible usage of locale_set_default() to localize the sort() functions.
The above example will output:
If we didn't use the locale, PHP would sort the string using the ASCII characters value, thus returning (wrongly):
|
PDO_IBM is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to IBM databases.
To build the PDO_IBM extension, the DB2 Client v9.1 or later must be installed on the same system as PHP. The DB2 Client can be downloaded from the IBM Application Development Site.
Note: The DB2 Client v9.1 or later supports direct access to DB2 for Linux, UNIX, and Windows v8 and v9.1 servers.
The DB2 Client v9.1 also supports access to DB2 UDB for i5 and DB2 UDB for z/OS servers using the separately purchased DB2 Connect product.
PDO_IBM is a PECL extension, so follow the instructions in Chapter 7 to install the PDO_IBM extension. Issue the configure command to point to the location of your DB2 Client header files and libraries as follows:
bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared] |
The PDO_IBM Data Source Name (DSN) is based on the IBM CLI DSN. The major components of the PDO_IBM DSN are:
The DSN prefix is ibm:.
The DSN can be any of the following:
a) Data source setup using db2cli.ini or odbc.ini
b) Catalogued database name i.e. database alias in the DB2 client catalog
c) Complete connection string in the following format:
DRIVER={IBM DB2 ODBC DRIVER};DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;
where the parameters represent the following values:
databaseThe name of the database.
hostnameThe hostname or IP address of the database server.
portThe TCP/IP port on which the database is listening for requests.
usernameThe username with which you are connecting to the database.
passwordThe password with which you are connecting to the database.
Example 2. PDO_IBM DSN example using a connection string The following example shows a PDO_IBM DSN for connecting to an DB2 database named testdb using the DB2 CLI connection string syntax.
|
These functions enable you to access IBM DB2 Universal Database, IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface (DB2 CLI).
To connect to IBM DB2 Universal Database for Linux, UNIX, and Windows, or IBM Cloudscape, or Apache Derby, you must install an IBM DB2 Universal Database client on the same computer on which you are running PHP. The extension has been developed and tested with DB2 Version 8.2.
To connect to IBM DB2 Universal Database for z/OS or iSeries, you also require IBM DB2 Connect or the equivalent DRDA gateway software.
The user invoking the PHP executable or SAPI must specify the DB2 instance before accessing these functions. You can set the name of the DB2 instance in php.ini using the ibm_db2.instance_name configuration option, or you can source the DB2 instance profile before invoking the PHP executable.
If you created a DB2 instance named db2inst1 in /home/db2inst1/, for example, you can add the following line to php.ini:
ibm_db2.instance_name=db2inst1 |
bash$ source /home/db2inst1/sqllib/db2profile |
To build the ibm_db2 extension, the DB2 application development header files and libraries must be installed on your system. DB2 does not install these by default, so you may have to return to your DB2 installer and add this option. The header files are included with the DB2 Application Development Client freely available for download from the IBM DB2 Universal Database support site.
If you add the DB2 application development header files and libraries to a Linux or Unix operating system on which DB2 was already installed, you must issue the command db2iupdt -e to update the symbolic links to the header files and libraries in your DB2 instances.
ibm_db2 is a PECL extension, so follow the instructions in Chapter 7 to install the ibm_db2 extension for PHP. Issue the configure command to point to the location of your DB2 header files and libraries as follows:
bash$ ./configure --with-IBM_DB2=/path/to/DB2 |
Note for IIS users: If you are using the ibm_db2 driver with Microsoft Internet Information Server (IIS) you may have to do the following:
Install DB2 with extended operating system security. Add the PHP binary path to the PATH system environment variable (default C:\php\). Create another system environment variable equal to the path where the PHP.INI file is located (eg: PHPRC = C:\php\). Add the IUSR_COMPUTERNAME to the DB2USERS group.
The behaviour of these functions is affected by settings in php.ini.
Table 1. ibm_db2 Configure Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| ibm_db2.binmode | "1" | PHP_INI_ALL | |
| ibm_db2.i5_allow_commit | "0" | PHP_INI_SYSTEM | |
| ibm_db2.i5_dbcs_alloc | "0" | PHP_INI_SYSTEM | |
| ibm_db2.instance_name | NULL | PHP_INI_SYSTEM |
Here's a short explanation of the configuration directives.
ibm_db2.binmode
integerThis option controls the mode used for converting to and from binary data in the PHP application.
1 (DB2_BINARY)
2 (DB2_CONVERT)
3 (DB2_PASSTHRU)
ibm_db2.i5_allow_commit
integerThis option controls the commit mode used for i5 schema collections in the PHP application.
0 no commit (see i5_commit for override)
1 allow commit (see i5_commit for override)
ibm_db2.i5_dbcs_alloc
integerThis option controls the internal ibm_db2 allocation scheme for large DBCS column buffers.
0 no expanded allocations (see i5_dbcs_alloc for override)
1 use expanded allocations (see i5_dbcs_alloc for override)
ibm_db2.instance_name
stringOn Linux and UNIX operating systems, this option defines the name of the instance to use for cataloged database connections. If this option is set, its value overrides the DB2INSTANCE environment variable setting.
This option is ignored on Windows operating systems.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Specifies that binary data shall be returned as is. This is the default mode.
Specifies that binary data shall be converted to a hexadecimal encoding and returned as an ASCII string.
Specifies that binary data shall be converted to a NULL value.
Specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
Specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
Specifies the PHP variable should be bound as an IN parameter for a stored procedure.
Specifies the PHP variable should be bound as an OUT parameter for a stored procedure.
Specifies the PHP variable should be bound as an INOUT parameter for a stored procedure.
Specifies that the column should be bound directly to a file for input.
Specifies that autocommit should be turned on.
Specifies that autocommit should be turned off.
Specifies that the variable should be bound as a DOUBLE, FLOAT, or REAL data type.
Specifies that the variable should be bound as a SMALLINT, INTEGER, or BIGINT data type.
Specifies that the variable should be bound as a CHAR or VARCHAR data type.
Specifies that column names will be returned in their natural case.
Specifies that column names will be returned in lower case.
Specifies that column names will be returned in upper case.
Specifies that deferred prepare should be turned on for the specified statement resource.
Specifies that deferred prepare should be turned off for the specified statement resource.
The ibm_db2 extension returns connection resources, statement resources, and result set resources.
Sets or gets the AUTOCOMMIT behavior of the specified connection resource.
connectionA valid database connection resource variable as returned from db2_connect() or db2_pconnect().
valueOne of the following constants:
Turns AUTOCOMMIT off.
Turns AUTOCOMMIT on.
When db2_autocommit() receives only the
connection parameter, it returns the current state
of AUTOCOMMIT for the requested connection as an integer value. A value of
0 indicates that AUTOCOMMIT is off, while a value of 1 indicates that
AUTOCOMMIT is on.
When db2_autocommit() receives both the
connection parameter and
autocommit parameter, it attempts to set the
AUTOCOMMIT state of the requested connection to the corresponding state.
Returns TRUE on success or FALSE on failure.
Example 1. Retrieving the AUTOCOMMIT value for a connection In the following example, a connection which has been created with AUTOCOMMIT turned off is tested with the db2_autocommit() function.
The above example will output:
|
Example 2. Setting the AUTOCOMMIT value for a connection In the following example, a connection which was initially created with AUTOCOMMIT turned off has its behavior changed to turn AUTOCOMMIT on.
The above example will output:
|
Binds a PHP variable to an SQL statement parameter in a statement resource returned by db2_prepare(). This function gives you more control over the parameter type, data type, precision, and scale for the parameter than simply passing the variable as part of the optional input array to db2_execute().
stmtA prepared statement returned from db2_prepare().
parameter-numberSpecifies the 1-indexed position of the parameter in the prepared statement.
variable-name
A string specifying the name of the PHP variable to bind to the
parameter specified by parameter-number.
parameter-typeA constant specifying whether the PHP variable should be bound to the SQL parameter as an input parameter (DB2_PARAM_IN), an output parameter (DB2_PARAM_OUT), or as a parameter that accepts input and returns output (DB2_PARAM_INOUT). To avoid memory overhead, you can also specify DB2_PARAM_FILE to bind the PHP variable to the name of a file that contains large object (BLOB, CLOB, or DBCLOB) data.
data-typeA constant specifying the SQL data type that the PHP variable should be bound as: one of DB2_BINARY, DB2_CHAR, DB2_DOUBLE, or DB2_LONG .
precisionSpecifies the precision with which the variable should be bound to the database.
scaleSpecifies the scale with which the variable should be bound to the database.
Example 1. Binding PHP variables to a prepared statement The SQL statement in the following example uses two input parameters in the WHERE clause. We call db2_bind_param() to bind two PHP variables to the corresponding SQL parameters. Notice that the PHP variables do not have to be declared or assigned before the call to db2_bind_param(); in the example, $lower_limit is assigned a value before the call to db2_bind_param(), but $upper_limit is assigned a value after the call to db2_bind_param(). The variables must be bound and, for parameters that accept input, must have any value assigned, before calling db2_execute().
The above example will output:
|
Example 2. Calling stored procedures with IN and OUT parameters The stored procedure match_animal in the following example accepts three different parameters:
The above example will output:
|
Example 3. Inserting a binary large object (BLOB) directly from a file The data for large objects are typically stored in files, such as XML documents or audio files. Rather than reading an entire file into a PHP variable, and then binding that PHP variable into an SQL statement, you can avoid some memory overhead by binding the file directly to the input parameter of your SQL statement. The following example demonstrates how to bind a file directly into a BLOB column.
|
(no version information, might be only in CVS)
db2_client_info -- Returns an object with properties that describe the DB2 database clientThis function returns an object with read-only properties that return information about the DB2 database client. The following table lists the DB2 client properties:
Table 1. DB2 client properties
| Property name | Return type | Description |
|---|---|---|
| APPL_CODEPAGE | int | The application code page. |
| CONN_CODEPAGE | int | The code page for the current connection. |
| DATA_SOURCE_NAME | string | The data source name (DSN) used to create the current connection to the database. |
| DRIVER_NAME | string | The name of the library that implements the DB2 Call Level Interface (CLI) specification. |
| DRIVER_ODBC_VER | string | The version of ODBC that the DB2 client supports. This returns a
string "MM.mm" where MM is the major version and
mm is the minor version. The DB2 client always
returns "03.51".
|
| DRIVER_VER | string | The version of the client, in the form of a string "MM.mm.uuuu" where
MM is the major version,
mm is the minor version,
and uuuu is the update. For example, "08.02.0001"
represents major version 8, minor version 2, update 1.
|
| ODBC_SQL_CONFORMANCE | string | The level of ODBC SQL grammar supported by the client:
|
| ODBC_VER | string | The version of ODBC that the ODBC driver manager supports. This
returns a string "MM.mm.rrrr" where MM is the major
version, mm is the minor version, and
rrrr is the release. The DB2 client always returns
"03.01.0000".
|
Example 1. A db2_client_info() example To retrieve information about the client, you must pass a valid database connection resource to db2_client_info().
The above example will output:
|
This function closes a DB2 client connection created with db2_connect() and returns the corresponding resources to the database server.
If you attempt to close a persistent DB2 client connection created with db2_pconnect(), the close request is ignored and the persistent DB2 client connection remains available for the next caller.
Example 1. Closing a connection The following example demonstrates a successful attempt to close a connection to an IBM DB2, Cloudscape, or Apache Derby database.
The above example will output:
|
(PECL)
db2_column_privileges -- Returns a result set listing the columns and associated privileges for a tableReturns a result set listing the columns and associated privileges for a table.
connectionA valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
qualifierA qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass NULL or an empty string.
schemaThe schema which contains the tables. To match all schemas, pass NULL or an empty string.
table-nameThe name of the table or view. To match all tables in the database, pass NULL or an empty string.
column-nameThe name of the column. To match all columns in the table, pass NULL or an empty string.
Returns a statement resource with a result set containing rows describing the column privileges for columns matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | Name of the catalog. The value is NULL if this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema. |
| TABLE_NAME | Name of the table or view. |
| COLUMN_NAME | Name of the column. |
| GRANTOR | Authorization ID of the user who granted the privilege. |
| GRANTEE | Authorization ID of the user to whom the privilege was granted. |
| PRIVILEGE | The privilege for the column. |
| IS_GRANTABLE | Whether the GRANTEE is permitted to grant this privilege to other users. |
| db2_columns() |
| db2_foreign_keys() |
| db2_primary_keys() |
| db2_procedure_columns() |
| db2_procedures() |
| db2_special_columns() |
| db2_statistics() |
| db2_table_privileges() |
| db2_tables() |
Returns a result set listing the columns and associated metadata for a table.
connectionA valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
qualifierA qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass NULL or an empty string.
schemaThe schema which contains the tables. To match all schemas, pass '%'.
table-nameThe name of the table or view. To match all tables in the database, pass NULL or an empty string.
column-nameThe name of the column. To match all columns in the table, pass NULL or an empty string.
Returns a statement resource with a result set containing rows describing the columns matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | Name of the catalog. The value is NULL if this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema. |
| TABLE_NAME | Name of the table or view. |
| COLUMN_NAME | Name of the column. |
| DATA_TYPE | The SQL data type for the column represented as an integer value. |
| TYPE_NAME | A string representing the data type for the column. |
| COLUMN_SIZE | An integer value representing the size of the column. |
| BUFFER_LENGTH | Maximum number of bytes necessary to store data from this column. |
| DECIMAL_DIGITS | The scale of the column, or NULL where scale is not applicable. |
| NUM_PREC_RADIX | An integer value of either 10 (representing an exact numeric data type), 2 (representing an approximate numeric data type), or NULL (representing a data type for which radix is not applicable). |
| NULLABLE | An integer value representing whether the column is nullable or not. |
| REMARKS | Description of the column. |
| COLUMN_DEF | Default value for the column. |
| SQL_DATA_TYPE | An integer value representing the size of the column. |
| SQL_DATETIME_SUB | Returns an integer value representing a datetime subtype code, or NULL for SQL data types to which this does not apply. |
| CHAR_OCTET_LENGTH | Maximum length in octets for a character data type column, which matches COLUMN_SIZE for single-byte character set data, or NULL for non-character data types. |
| ORDINAL_POSITION | The 1-indexed position of the column in the table. |
| IS_NULLABLE | A string value where 'YES' means that the column is nullable and 'NO' means that the column is not nullable. |
| db2_column_privileges() |
| db2_foreign_keys() |
| db2_primary_keys() |
| db2_procedure_columns() |
| db2_procedures() |
| db2_special_columns() |
| db2_statistics() |
| db2_table_privileges() |
| db2_tables() |
Commits an in-progress transaction on the specified connection resource and begins a new transaction. PHP applications normally default to AUTOCOMMIT mode, so db2_commit() is not necessary unless AUTOCOMMIT has been turned off for the connection resource.
Note: If the specified connection resource is a persistent connection, all transactions in progress for all applications using that persistent connection will be committed. For this reason, persistent connections are not recommended for use in applications that require transactions.
connectionA valid database connection resource variable as returned from db2_connect() or db2_pconnect().
(PECL)
db2_conn_error -- Returns a string containing the SQLSTATE returned by the last connection attemptdb2_conn_error() returns an SQLSTATE value representing the reason the last attempt to connect to a database failed. As db2_connect() returns FALSE in the event of a failed connection attempt, you do not pass any parameters to db2_conn_error() to retrieve the SQLSTATE value.
If, however, the connection was successful but becomes invalid over time,
you can pass the connection parameter to retrieve
the SQLSTATE value for a specific connection.
To learn what the SQLSTATE value means, you can issue the following command
at a DB2 Command Line Processor prompt:
db2 '? sqlstate-value'. You
can also call db2_conn_errormsg() to retrieve an
explicit error message and the associated SQLCODE value.
connectionA connection resource associated with a connection that initially succeeded, but which over time became invalid.
Returns the SQLSTATE value resulting from a failed connection attempt. Returns an empty string if there is no error associated with the last connection attempt.
Example 1. Retrieving an SQLSTATE value for a failed connection attempt The following example demonstrates how to return an SQLSTATE value after deliberately passing invalid parameters to db2_connect().
The above example will output:
|
db2_conn_errormsg() returns an error message and SQLCODE value representing the reason the last database connection attempt failed. As db2_connect() returns FALSE in the event of a failed connection attempt, do not pass any parameters to db2_conn_errormsg() to retrieve the associated error message and SQLCODE value.
If, however, the connection was successful but becomes invalid over time,
you can pass the connection parameter to retrieve
the associated error message and SQLCODE value for a specific connection.
connectionA connection resource associated with a connection that initially succeeded, but which over time became invalid.
Returns a string containing the error message and SQLCODE value resulting from a failed connection attempt. If there is no error associated with the last connection attempt, db2_conn_errormsg() returns an empty string.
Example 1. Retrieving the error message returned by a failed connection attempt The following example demonstrates how to return an error message and SQLCODE value after deliberately passing invalid parameters to db2_connect().
The above example will output:
|
Creates a new connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database.
database
For a cataloged connection to a database, database
represents the database alias in the DB2 client catalog.
For an uncataloged connection to a database,
database represents a complete connection
string in the following format:
DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;
where the parameters represent the following values:
databaseThe name of the database.
hostnameThe hostname or IP address of the database server.
portThe TCP/IP port on which the database is listening for requests.
usernameThe username with which you are connecting to the database.
passwordThe password with which you are connecting to the database.
usernameThe username with which you are connecting to the database.
For uncataloged connections, you must pass a NULL value or empty string.
passwordThe password with which you are connecting to the database.
For uncataloged connections, you must pass a NULL value or empty string.
optionsAn associative array of connection options that affect the behavior of the connection, where valid array keys include:
autocommitPassing the DB2_AUTOCOMMIT_ON value turns autocommit on for this connection handle.
Passing the DB2_AUTOCOMMIT_OFF value turns autocommit off for this connection handle.
DB2_ATTR_CASEPassing the DB2_CASE_NATURAL value specifies that column names are returned in natural case.
Passing the DB2_CASE_LOWER value specifies that column names are returned in lower case.
Passing the DB2_CASE_UPPER value specifies that column names are returned in upper case.
CURSORPassing the DB2_FORWARD_ONLY value specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
Passing the DB2_SCROLLABLE value specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
The following new i5/OS options are available as of ibm_db2 version 1.5.1. Note: prior versions of ibm_db2 do not support these new i5 options.
i5_libA character value that indicates the default library that will be used for resolving unqualified file references. This is not valid if the connection is using system naming mode.
i5_namingDB2_I5_NAMING_ON value turns on DB2 UDB CLI iSeries system naming mode. Files are qualified using the slash (/) delimiter. Unqualified files are resolved using the library list for the job.
DB2_I5_NAMING_OFF value turns off DB2 UDB CLI default naming mode, which is SQL naming. Files are qualified using the period (.) delimiter. Unqualified files are resolved using either the default library or the current user ID.
i5_commit
The i5_commit attribute should be set before the
db2_connect(). If the value is changed after the
connection has been established, and the connection is to a remote data
source, the change does not take effect until the next successful
db2_connect() for the connection handle.
Note: php.ini setting ibm_db2.i5_allow_commit==0
or DB2_I5_TXN_NO_COMMIT is the default, but may be
overridden with the i5_commit option.
DB2_I5_TXN_NO_COMMIT - Commitment control is not used.
DB2_I5_TXN_READ_UNCOMMITTED - Dirty reads, nonrepeatable reads, and phantoms are possible.
DB2_I5_TXN_READ_COMMITTED - Dirty reads are not possible. Nonrepeatable reads, and phantoms are possible.
DB2_I5_TXN_REPEATABLE_READ - Dirty reads and nonrepeatable reads are not possible. Phantoms are possible.
DB2_I5_TXN_SERIALIZABLE - Transactions are serializable. Dirty reads, non-repeatable reads, and phantoms are not possible
i5_query_optimizeDB2_FIRST_IO All queries are optimized with the goal of returning the first page of output as fast as possible. This goal works well when the output is controlled by a user who is most likely to cancel the query after viewing the first page of output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause.
DB2_ALL_IO All queries are optimized with the goal of running the entire query to completion in the shortest amount of elapsed time. This is a good option when the output of a query is being written to a file or report, or the interface is queuing the output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. This is the default.
i5_dbcs_allocDB2_I5_DBCS_ALLOC_ON value turns on DB2 6X allocation scheme for DBCS translation column size growth.
DB2_I5_DBCS_ALLOC_OFF value turns off DB2 6X allocation scheme for DBCS translation column size growth.
Note: php.ini setting ibm_db2.i5_dbcs_alloc==0 or
DB2_I5_DBCS_ALLOC_OFF is the default, but may be overridden
with the i5_dbcs_alloc option.
i5_date_fmtSQL_FMT_ISO - The International Organization for Standardization (ISO) date format yyyy-mm-dd is used. This is the default.
DB2_I5_FMT_USA - The United States date format mm/dd/yyyy is used.
DB2_I5_FMT_EUR - The European date format dd.mm.yyyy is used.
DB2_I5_FMT_JIS - The Japanese Industrial Standard date format yyyy-mm-dd is used.
DB2_I5_FMT_MDY - The date format mm/dd/yyyy is used.
DB2_I5_FMT_DMY - The date format dd/mm/yyyy is used.
DB2_I5_FMT_YMD - The date format yy/mm/dd is used.
DB2_I5_FMT_JUL - The Julian date format yy/ddd is used.
DB2_I5_FMT_JOB - The job default is used.
i5_date_sepDB2_I5_SEP_SLASH - A slash ( / ) is used as the date separator. This is the default.
DB2_I5_SEP_DASH - A dash ( - ) is used as the date separator.
DB2_I5_SEP_PERIOD - A period ( . ) is used as the date separator.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the date separator.
DB2_I5_SEP_BLANK - A blank is used as the date separator.
DB2_I5_SEP_JOB - The job default is used
i5_time_fmtDB2_I5_FMT_ISO - The International Organization for Standardization (ISO) time format hh.mm.ss is used. This is the default.
DB2_I5_FMT_USA - The United States time format hh:mmxx is used, where xx is AM or PM.
DB2_I5_FMT_EUR - The European time format hh.mm.ss is used.
DB2_I5_FMT_JIS - The Japanese Industrial Standard time format hh:mm:ss is used.
DB2_I5_FMT_HMS - The hh:mm:ss format is used.
i5_time_sepDB2_I5_SEP_COLON - A colon ( : ) is used as the time separator. This is the default.
DB2_I5_SEP_PERIOD - A period ( . ) is used as the time separator.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the time separator.
DB2_I5_SEP_BLANK - A blank is used as the time separator.
DB2_I5_SEP_JOB - The job default is used.
i5_decimal_sepDB2_I5_SEP_PERIOD - A period ( . ) is used as the decimal separator. This is the default.
DB2_I5_SEP_COMMA - A comma ( , ) is used as the decimal separator.
DB2_I5_SEP_JOB - The job default is used.
Returns a connection handle resource if the connection attempt is successful. If the connection attempt fails, db2_connect() returns FALSE.
Example 1. Creating a cataloged connection Cataloged connections require you to have previously cataloged the target database through the DB2 Command Line Processor (CLP) or DB2 Configuration Assistant.
The above example will output:
|
Example 2. Creating an uncataloged connection An uncataloged connection enables you to dynamically connect to a database.
The above example will output:
|
Example 3. Creating a connection with autocommit off by default Passing an array of options to db2_connect() enables you to modify the default behavior of the connection handle.
The above example will output:
|
Example 4. i5/OS best performance To achieve best performance for your i5/OS ibm_db2 1.5.1 PHP application use the default host, userid, and password for your db2_connect().
The above example will output:
|
Returns the cursor type used by a statement resource. Use this to determine if you are working with a forward-only cursor or scrollable cursor.
Returns either DB2_FORWARD_ONLY if the statement resource uses a forward-only cursor or DB2_SCROLLABLE if the statement resource uses a scrollable cursor.
(no version information, might be only in CVS)
db2_escape_string -- Used to escape certain characters.Prepends backslashes to special characters in the string argument.
string_literalThe string that contains special characters that need to be modified. Characters that are prepended with a backslash are \x00, \n, \r, \, ', " and \x1a.
Returns string_literal with the special characters
noted above prepended with backslashes.
Example 1. A db2_escape_string() example Result of using the db2_escape_string() function
The above example will output:
|
Executes an SQL statement directly.
If you plan to interpolate PHP variables into the SQL statement, understand that this is one of the more common security exposures. Consider calling db2_prepare() to prepare an SQL statement with parameter markers for input values. Then you can call db2_execute() to pass in the input values and avoid SQL injection attacks.
If you plan to repeatedly issue the same SQL statement with different parameters, consider calling db2_prepare() and db2_execute() to enable the database server to reuse its access plan and increase the efficiency of your database access.
connectionA valid database connection resource variable as returned from db2_connect() or db2_pconnect().
statementAn SQL statement. The statement cannot contain any parameter markers.
optionsAn associative array containing statement options. You can use this parameter to request a scrollable cursor on database servers that support this functionality.
cursorPassing the DB2_FORWARD_ONLY value requests a forward-only cursor for this SQL statement. This is the default type of cursor, and it is supported by all database servers. It is also much faster than a scrollable cursor.
Passing the DB2_SCROLLABLE value requests a scrollable cursor for this SQL statement. This type of cursor enables you to fetch rows non-sequentially from the database server. However, it is only supported by DB2 servers, and is much slower than forward-only cursors.
Returns a statement resource if the SQL statement was issued successfully, or FALSE if the database failed to execute the SQL statement.
Example 1. Creating a table with db2_exec() The following example uses db2_exec() to issue a set of DDL statements in the process of creating a table.
The above example will output:
|
Example 2. Executing a SELECT statement with a scrollable cursor The following example demonstrates how to request a scrollable cursor for an SQL statement issued by db2_exec().
The above example will output:
|
Example 3. Returning XML data as a SQL ResultSet The following example demonstrates how to work with documents stored in a XML column using the SAMPLE database. Using some pretty simple SQL/XML, this example returns some of the nodes in a XML document in a SQL ResultSet format that most users are familiar with.
The above example will output:
|
Example 4. Performing a "JOIN" with XML data The following example works with documents stored in 2 different XML columns in the SAMPLE database. It creates 2 temporary tables from the XML documents from 2 different columns and returns a SQL ResultSet with information regarding shipping status for the customer.
The above example will output:
|
Example 5. Returning SQL data as part of a larger XML document The following example works with a portion of the PRODUCT.DESCRIPTION documents in the SAMPLE database. It creates a XML document containing product description (XML data) and pricing info (SQL data).
The above example will output:
|
db2_execute() executes an SQL statement that was prepared by db2_prepare().
If the SQL statement returns a result set, for example, a SELECT statement or a CALL to a stored procedure that returns one or more result sets, you can retrieve a row as an array from the stmt resource using db2_fetch_assoc(), db2_fetch_both(), or db2_fetch_array(). Alternatively, you can use db2_fetch_row() to move the result set pointer to the next row and fetch a column at a time from that row with db2_result().
Refer to db2_prepare() for a brief discussion of the advantages of using db2_prepare() and db2_execute() rather than db2_exec().
stmtA prepared statement returned from db2_prepare().
parametersAn array of input parameters matching any parameter markers contained in the prepared statement.
Example 1. Preparing and executing an SQL statement with parameter markers The following example prepares an INSERT statement that accepts four parameter markers, then iterates over an array of arrays containing the input values to be passed to db2_execute().
The above example will output:
|
Example 2. Calling a stored procedure with an OUT parameter The following example prepares a CALL statement that accepts one parameter marker representing an OUT parameter, binds the PHP variable $my_pets to the parameter using db2_bind_param(), then issues db2_execute() to execute the CALL statement. After the CALL to the stored procedure has been made, the value of $num_pets changes to reflect the value returned by the stored procedure for that OUT parameter.
The above example will output:
|
Example 3. Returning XML data as a SQL ResultSet The following example demonstrates how to work with documents stored in a XML column using the SAMPLE database. Using some pretty simple SQL/XML, this example returns some of the nodes in a XML document in a SQL ResultSet format that most users are familiar with.
The above example will output:
|
Example 4. Performing a "JOIN" with XML data The following example works with documents stored in 2 different XML columns in the SAMPLE database. It creates 2 temporary tables from the XML documents from 2 different columns and returns a SQL ResultSet with information regarding shipping status for the customer.
The above example will output:
|
Example 5. Returning SQL data as part of a larger XML document The following example works with a portion of the PRODUCT.DESCRIPTION documents in the SAMPLE database. It creates a XML document containing product description (XML data) and pricing info (SQL data).
The above example will output:
|
| db2_exec() |
| db2_fetch_array() |
| db2_fetch_assoc() |
| db2_fetch_both() |
| db2_fetch_row() |
| db2_prepare() |
| db2_result() |
(PECL)
db2_fetch_array -- Returns an array, indexed by column position, representing a row in a result setReturns an array, indexed by column position, representing a row in a result set. The columns are 0-indexed.
stmtA valid stmt resource containing a result set.
row_numberRequests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Returns a 0-indexed array with column values indexed by the column position
representing the next or requested row in the result set. Returns FALSE if
there are no rows left in the result set, or if the row requested by
row_number does not exist in the result set.
Example 1. Iterating through a forward-only cursor If you call db2_fetch_array() without a specific row number, it automatically retrieves the next row in the result set.
The above example will output:
|
Example 2. Retrieving specific rows with db2_fetch_array() from a scrollable cursor If your result set uses a scrollable cursor, you can call db2_fetch_array() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.
The above example will output:
|
(PECL)
db2_fetch_assoc -- Returns an array, indexed by column name, representing a row in a result setReturns an array, indexed by column name, representing a row in a result set.
stmtA valid stmt resource containing a result set.
row_numberRequests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Returns an associative array with column values indexed by the column name
representing the next or requested row in the result set. Returns FALSE if
there are no rows left in the result set, or if the row requested by
row_number does not exist in the result set.
Example 1. Iterating through a forward-only cursor If you call db2_fetch_assoc() without a specific row number, it automatically retrieves the next row in the result set.
The above example will output:
|
Example 2. Retrieving specific rows with db2_fetch_assoc() from a scrollable cursor If your result set uses a scrollable cursor, you can call db2_fetch_assoc() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.
The above example will output:
|
(PECL)
db2_fetch_both -- Returns an array, indexed by both column name and position, representing a row in a result setReturns an array, indexed by both column name and position, representing a row in a result set. Note that the row returned by db2_fetch_both() requires more memory than the single-indexed arrays returned by db2_fetch_assoc() or db2_fetch_array().
stmtA valid stmt resource containing a result set.
row_numberRequests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Returns an associative array with column values indexed by both the column
name and 0-indexed column number. The array represents the next or
requested row in the result set. Returns FALSE if there are no rows left
in the result set, or if the row requested by
row_number does not exist in the result set.
Example 1. Iterating through a forward-only cursor If you call db2_fetch_both() without a specific row number, it automatically retrieves the next row in the result set. The following example accesses columns in the returned array by both column name and by numeric index.
The above example will output:
|
Example 2. Retrieving specific rows with db2_fetch_both() from a scrollable cursor If your result set uses a scrollable cursor, you can call db2_fetch_both() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.
The above example will output:
|
Returns an object in which each property represents a column returned in the row fetched from a result set.
stmtA valid stmt resource containing a result set.
row_numberRequests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.
Returns an object representing a single row in the result set. The properties of the object map to the names of the columns in the result set.
The IBM DB2, Cloudscape, and Apache Derby database servers typically fold column names to upper-case, so the object properties will reflect that case.
If your SELECT statement calls a scalar function to modify the value of a column, the database servers return the column number as the name of the column in the result set. If you prefer a more descriptive column name and object property, you can use the AS clause to assign a name to the column in the result set.
Returns FALSE if no row was retrieved.
Example 1. A db2_fetch_object() example The following example issues a SELECT statement with a scalar function, RTRIM, that removes whitespace from the end of the column. Rather than creating an object with the properties "BREED" and "2", we use the AS clause in the SELECT statement to assign the name "name" to the modified column. The database server folds the column names to upper-case, resulting in an object with the properties "BREED" and "NAME".
The above example will output:
|
Use db2_fetch_row() to iterate through a result set, or to point to a specific row in a result set if you requested a scrollable cursor.
To retrieve individual fields from the result set, call the db2_result() function.
Rather than calling db2_fetch_row() and db2_result(), most applications will call one of db2_fetch_assoc(), db2_fetch_both(), or db2_fetch_array() to advance the result set pointer and return a complete row as an array.
stmtA valid stmt resource.
row_numberWith scrollable cursors, you can request a specific row number in the result set. Row numbering is 1-indexed.
Returns TRUE if the requested row exists in the result set. Returns FALSE if the requested row does not exist in the result set.
Example 1. Iterating through a result set The following example demonstrates how to iterate through a result set with db2_fetch_row() and retrieve columns from the result set with db2_result().
The above example will output:
|
Example 2. i5/OS recommended alternatives to db2_fetch_row/db2_result On i5/OS it is recommended that you use db2_fetch_both(), db2_fetch_array(), or db2_fetch_object() over db2_fetch_row()/db2_result(). In general db2_fetch_row()/db2_result() have more issues with various column types in EBCIDIC to ASCII translation, including possible truncation in DBCS applications. You may also find the performance of db2_fetch_both(), db2_fetch_array(), and db2_fetch_object() to be superior to db2_fetch_row()/db2_result().
The above example will output:
|
Returns the maximum number of bytes required to display a column in a result set.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns an integer value with the maximum number of bytes required to display the specified column. If the column does not exist in the result set, db2_field_display_size() returns FALSE.
| db2_field_name() |
| db2_field_num() |
| db2_field_precision() |
| db2_field_scale() |
| db2_field_type() |
| db2_field_width() |
Returns the name of the specified column in the result set.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns a string containing the name of the specified column. If the specified column does not exist in the result set, db2_field_name() returns FALSE.
| db2_field_display_size() |
| db2_field_num() |
| db2_field_precision() |
| db2_field_scale() |
| db2_field_type() |
| db2_field_width() |
Returns the position of the named column in a result set.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns an integer containing the 0-indexed position of the named column in the result set. If the specified column does not exist in the result set, db2_field_num() returns FALSE.
| db2_field_display_size() |
| db2_field_name() |
| db2_field_precision() |
| db2_field_scale() |
| db2_field_type() |
| db2_field_width() |
Returns the precision of the indicated column in a result set.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns an integer containing the precision of the specified column. If the specified column does not exist in the result set, db2_field_precision() returns FALSE.
| db2_field_display_size() |
| db2_field_name() |
| db2_field_num() |
| db2_field_scale() |
| db2_field_type() |
| db2_field_width() |
Returns the scale of the indicated column in a result set.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns an integer containing the scale of the specified column. If the specified column does not exist in the result set, db2_field_scale() returns FALSE.
| db2_field_display_size() |
| db2_field_name() |
| db2_field_num() |
| db2_field_precision() |
| db2_field_type() |
| db2_field_width() |
Returns the data type of the indicated column in a result set.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns a string containing the defined data type of the specified column. If the specified column does not exist in the result set, db2_field_type() returns FALSE.
| db2_field_display_size() |
| db2_field_name() |
| db2_field_num() |
| db2_field_precision() |
| db2_field_scale() |
| db2_field_width() |
(PECL)
db2_field_width -- Returns the width of the current value of the indicated column in a result setReturns the width of the current value of the indicated column in a result set. This is the maximum width of the column for a fixed-length data type, or the actual width of the column for a variable-length data type.
stmtSpecifies a statement resource containing a result set.
columnSpecifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.
Returns an integer containing the width of the specified character or binary data type column in a result set. If the specified column does not exist in the result set, db2_field_width() returns FALSE.
| db2_field_display_size() |
| db2_field_name() |
| db2_field_num() |
| db2_field_precision() |
| db2_field_scale() |
| db2_field_type() |
Returns a result set listing the foreign keys for a table.
connectionA valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
qualifierA qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass NULL or an empty string.
schema
The schema which contains the tables. If schema
is NULL, db2_foreign_keys() matches the schema for
the current connection.
table-nameThe name of the table.
Returns a statement resource with a result set containing rows describing the foreign keys for the specified table. The result set is composed of the following columns:
| Column name | Description |
|---|---|
| PKTABLE_CAT | Name of the catalog for the table containing the primary key. The value is NULL if this table does not have catalogs. |
| PKTABLE_SCHEM | Name of the schema for the table containing the primary key. |
| PKTABLE_NAME | Name of the table containing the primary key. |
| PKCOLUMN_NAME | Name of the column containing the primary key. |
| FKTABLE_CAT | Name of the catalog for the table containing the foreign key. The value is NULL if this table does not have catalogs. |
| FKTABLE_SCHEM | Name of the schema for the table containing the foreign key. |
| FKTABLE_NAME | Name of the table containing the foreign key. |
| FKCOLUMN_NAME | Name of the column containing the foreign key. |
| KEY_SEQ | 1-indexed position of the column in the key. |
| UPDATE_RULE | Integer value representing the action applied to the foreign key when the SQL operation is UPDATE. |
| DELETE_RULE | Integer value representing the action applied to the foreign key when the SQL operation is DELETE. |
| FK_NAME | The name of the foreign key. |
| PK_NAME | The name of the primary key. |
| DEFERRABILITY | An integer value representing whether the foreign key deferrability is SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE, or SQL_NOT_DEFERRABLE. |
| db2_column_privileges() |
| db2_columns() |
| db2_primary_keys() |
| db2_procedure_columns() |
| db2_procedures() |
| db2_special_columns() |
| db2_statistics() |
| db2_table_privileges() |
| db2_tables() |
Frees the system and database resources that are associated with a result set. These resources are freed implicitly when a script finishes, but you can call db2_free_result() to explicitly free the result set resources before the end of the script.
Frees the system and database resources that are associated with a statement resource. These resources are freed implicitly when a script finishes, but you can call db2_free_stmt() to explicitly free the statement resources before the end of the script.
(no version information, might be only in CVS)
db2_get_option -- Retrieves an option value for a statement resource or a connection resourceRetrieves the value of a specified option value for a statement resource or a connection resource.
resourceA valid statement resource as returned from db2_prepare() or a valid connection resource as returned from db2_connect() or db2_pconnect().
optionA valid statement or connection options. The following new options are available as of ibm_db2 version 1.6.0. They provide useful tracking information that can be set during execution with db2_get_option().
Note: Prior versions of ibm_db2 do not support these new options.
When the value in each option is being set, some servers might not handle the entire length provided and might truncate the value.
To ensure that the data specified in each option is converted correctly when transmitted to a host system, use only the characters A through Z, 0 through 9, and the underscore (_) or period (.).
useridSQL_ATTR_INFO_USERID - A pointer to a null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 16 characters. This user-id is not to be confused with the authentication user-id, it is for identification purposes only and is not used for any authorization.
acctstrSQL_ATTR_INFO_ACCTSTR - A pointer to a null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 200 characters.
applnameSQL_ATTR_INFO_APPLNAME - A pointer to a null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 32 characters.
wrkstnnameSQL_ATTR_INFO_WRKSTNNAME - A pointer to a null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 18 characters.
The following table specifies which options are compatible with the available resource types:
Returns the current setting of the connection attribute provided on success or FALSE on failure.
Example 1. Setting and retrieving parameters through a connection resource
The above example will output:
|
(no version information, might be only in CVS)
db2_lob_read -- Gets a user defined size of LOB files with each invocationUse db2_lob_read() to iterate through a specified column of a result set and retrieve a user defined size of LOB data.
stmtA valid stmt resource containing LOB data.
colnumA valid column number in the result set of the stmt resource.
lengthThe size of the LOB data to be retrieved from the stmt resource.
Returns the amount of data the user specifies. Returns FALSE if the data cannot be retrieved.
Example 1. Iterating through different types of data
The above example will output:
|
A stored procedure can return zero or more result sets. While you handle the first result set in exactly the same way you would handle the results returned by a simple SELECT statement, to fetch the second and subsequent result sets from a stored procedure you must call the db2_next_result() function and return the result to a uniquely named PHP variable.
Returns a new statement resource containing the next result set if the stored procedure returned another result set. Returns FALSE if the stored procedure did not return another result set.
Example 1. Calling a stored procedure that returns multiple result sets In the following example, we call a stored procedure that returns three result sets. The first result set is fetched directly from the same statement resource on which we invoked the CALL statement, while the second and third result sets are fetched from statement resources returned from our calls to the db2_next_result() function.
The above example will output:
|
Returns the number of fields contained in a result set. This is most useful for handling the result sets returned by dynamically generated queries, or for result sets returned by stored procedures, where your application cannot otherwise know how to retrieve and use the results.
Returns an integer value representing the number of fields in the result set associated with the specified statement resource. Returns FALSE if the statement resource is not a valid input value.
Example 1. Retrieving the number of fields in a result set The following example demonstrates how to retrieve the number of fields returned in a result set.
The above example will output:
|
| db2_execute() |
| db2_field_display_size() |
| db2_field_name() |
| db2_field_num() |
| db2_field_precision() |
| db2_field_scale() |
| db2_field_type() |
| db2_field_width() |
Returns the number of rows deleted, inserted, or updated by an SQL statement.
To determine the number of rows that will be returned by a SELECT statement, issue SELECT COUNT(*) with the same predicates as your intended SELECT statement and retrieve the value.
If your application logic checks the number of rows returned by a SELECT statement and branches if the number of rows is 0, consider modifying your application to attempt to return the first row with one of db2_fetch_assoc(), db2_fetch_both(), db2_fetch_array(), or db2_fetch_row(), and branch if the fetch function returns FALSE.
Note: If you issue a SELECT statement using a scrollable cursor, db2_num_rows() returns the number of rows returned by the SELECT statement. However, the overhead associated with scrollable cursors significantly degrades the performance of your application, so if this is the only reason you are considering using scrollable cursors, you should use a forward-only cursor and either call SELECT COUNT(*) or rely on the boolean return value of the fetch functions to achieve the equivalent functionality with much better performance.
Returns the number of rows affected by the last SQL statement issued by the specified statement handle.
Returns a persistent connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database. For more information on persistent connections, refer to Chapter 41.
Calling db2_close() on a persistent connection always returns TRUE, but the underlying DB2 client connection remains open and waiting to serve the next matching db2_pconnect() request.
databaseThe database alias in the DB2 client catalog.
usernameThe username with which you are connecting to the database.
passwordThe password with which you are connecting to the database.
optionsAn associative array of connection options that affect the behavior of the connection, where valid array keys include:
autocommitPassing the DB2_AUTOCOMMIT_ON value turns autocommit on for this connection handle.
Passing the DB2_AUTOCOMMIT_OFF value turns autocommit off for this connection handle.
DB2_ATTR_CASEPassing the DB2_CASE_NATURAL value specifies that column names are returned in natural case.
Passing the DB2_CASE_LOWER value specifies that column names are returned in lower case.
Passing the DB2_CASE_UPPER value specifies that column names are returned in upper case.
CURSORPassing the DB2_FORWARD_ONLY value specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
Passing the DB2_SCROLLABLE value specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
Returns a connection handle resource if the connection attempt is
successful. db2_pconnect() tries to reuse an existing
connection resource that exactly matches the
database, username, and
password parameters. If the connection attempt fails,
db2_pconnect() returns FALSE.
Example 1. A db2_pconnect() example In the following example, the first call to db2_pconnect() returns a new persistent connection resource. The second call to db2_pconnect() returns a persistent connection resource that simply reuses the first persistent connection resource.
The above example will output:
|
db2_prepare() creates a prepared SQL statement which can include 0 or more parameter markers (? characters) representing parameters for input, output, or input/output. You can pass parameters to the prepared statement using db2_bind_param(), or for input values only, as an array passed to db2_execute().
There are three main advantages to using prepared statements in your application:
Performance: when you prepare a statement, the database server creates an optimized access plan for retrieving data with that statement. Subsequently issuing the prepared statement with db2_execute() enables the statements to reuse that access plan and avoids the overhead of dynamically creating a new access plan for every statement you issue.
Security: when you prepare a statement, you can include parameter markers for input values. When you execute a prepared statement with input values for placeholders, the database server checks each input value to ensure that the type matches the column definition or parameter definition.
Advanced functionality: Parameter markers not only enable you to pass input values to prepared SQL statements, they also enable you to retrieve OUT and INOUT parameters from stored procedures using db2_bind_param().
connectionA valid database connection resource variable as returned from db2_connect() or db2_pconnect().
statementAn SQL statement, optionally containing one or more parameter markers..
optionsAn associative array containing statement options. You can use this parameter to request a scrollable cursor on database servers that support this functionality.
cursorPassing the DB2_FORWARD_ONLY value requests a forward-only cursor for this SQL statement. This is the default type of cursor, and it is supported by all database servers. It is also much faster than a scrollable cursor.
Passing the DB2_SCROLLABLE value requests a scrollable cursor for this SQL statement. This type of cursor enables you to fetch rows non-sequentially from the database server. However, it is only supported by DB2 servers, and is much slower than forward-only cursors.
Returns a statement resource if the SQL statement was successfully parsed and prepared by the database server. Returns FALSE if the database server returned an error. You can determine which error was returned by calling db2_stmt_error() or db2_stmt_errormsg().
Example 1. Preparing and executing an SQL statement with parameter markers The following example prepares an INSERT statement that accepts four parameter markers, then iterates over an array of arrays containing the input values to be passed to db2_execute().
|
Returns a result set listing the primary keys for a table.
connectionA valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
qualifierA qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass NULL or an empty string.
schema
The schema which contains the tables. If schema
is NULL, db2_primary_keys() matches the schema for
the current connection.
table-nameThe name of the table.
Returns a statement resource with a result set containing rows describing the primary keys for the specified table. The result set is composed of the following columns:
| Column name | Description |
|---|---|
| TABLE_CAT | Name of the catalog for the table containing the primary key. The value is NULL if this table does not have catalogs. |
| TABLE_SCHEM | Name of the schema for the table containing the primary key. |
| TABLE_NAME | Name of the table containing the primary key. |
| COLUMN_NAME | Name of the column containing the primary key. |
| KEY_SEQ | 1-indexed position of the column in the key. |
| PK_NAME | The name of the primary key. |
| db2_column_privileges() |
| db2_columns() |
| db2_foreign_keys() |
| db2_procedure_columns() |
| db2_procedures() |
| db2_special_columns() |
| db2_statistics() |
| db2_table_privileges() |
| db2_tables() |
Returns a result set listing the parameters for one or more stored procedures.
connectionA valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
qualifierA qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass NULL or an empty string.
schemaThe schema which contains the procedures. This parameter accepts a search pattern containing _ and % as wildcards.
procedureThe name of the procedure. This parameter accepts a search pattern containing _ and % as wildcards.
parameterThe name of the parameter. This parameter accepts a search pattern containing _ and % as wildcards. If this parameter is NULL, all parameters for the specified stored procedures are returned.
Returns a statement resource with a result set containing rows describing the parameters for the stored procedures matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| PROCEDURE_CAT | The catalog that contains the procedure. The value is NULL if this table does not have catalogs. |
| PROCEDURE_SCHEM | Name of the schema that contains the stored procedure. |
| PROCEDURE_NAME | Name of the procedure. |
| COLUMN_NAME | Name of the parameter. |
| COLUMN_TYPE |
An integer value representing the type of the parameter: |
| DATA_TYPE | The SQL data type for the parameter represented as an integer value. |
| TYPE_NAME | A string representing the data type for the parameter. |
| COLUMN_SIZE | An integer value representing the size of the parameter. |
| BUFFER_LENGTH | Maximum number of bytes necessary to store data for this parameter. |
| DECIMAL_DIGITS | The scale of the parameter, or NULL where scale is not applicable. |
| NUM_PREC_RADIX | An integer value of either 10 (representing an exact numeric data type), 2 (representing an approximate numeric data type), or NULL (representing a data type for which radix is not applicable). |
| NULLABLE | An integer value representing whether the parameter is nullable or not. |
| REMARKS | Description of the parameter. |
| COLUMN_DEF | Default value for the parameter. |
| SQL_DATA_TYPE | An integer value representing the size of the parameter. |
| SQL_DATETIME_SUB | Returns an integer value representing a datetime subtype code, or NULL for SQL data types to which this does not apply. |
| CHAR_OCTET_LENGTH | Maximum length in octets for a character data type parameter, which matches COLUMN_SIZE for single-byte character set data, or NULL for non-character data types. |
| ORDINAL_POSITION | The 1-indexed position of the parameter in the CALL statement. |
| IS_NULLABLE | A string value where 'YES' means that the parameter accepts or returns NULL values and 'NO' means that the parameter does not accept or return NULL values. |
| db2_column_privileges() |
| db2_columns() |
| db2_foreign_keys() |
| db2_primary_keys() |
| db2_procedures() |
| db2_special_columns() |
| db2_statistics() |
| db2_table_privileges() |
| db2_tables() |
Returns a result set listing the stored procedures registered in a database.
connectionA valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
qualifierA qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass NULL or an empty string.
schemaThe schema which contains the procedures. This parameter accepts a search pattern containing _ and % as wildcards.
procedureThe name of the procedure. This parameter accepts a search pattern containing _ and % as wildcards.
Returns a statement resource with a result set containing rows describing the stored procedures matching the specified parameters. The rows are composed of the following columns:
| Column name | Description |
|---|---|
| PROCEDURE_CAT | The catalog that contains the procedure. The value is NULL if this table does not have catalogs. |
| PROCEDURE_SCHEM | Name of the schema that contains the stored procedure. |
| PROCEDURE_NAME | Name of the procedure. |
| NUM_INPUT_PARAMS | Number of input (IN) parameters for the stored procedure. |
| NUM_OUTPUT_PARAMS | Number of output (OUT) parameters for the stored procedure. |
| NUM_RESULT_SETS | Number of result sets returned by the stored procedure. |
| REMARKS | Any comments about the stored procedure. |
| PROCEDURE_TYPE | Always returns 1, indicating that the stored procedure does not return a return value. |
| db2_column_privileges() |
| db2_columns() |
| db2_foreign_keys() |
| db2_primary_keys() |
| db2_procedure_columns() |
| db2_special_columns() |
| db2_statistics() |
| db2_table_privileges() |
| db2_tables() |
Use db2_result() to return the value of a specified column in the current row of a result set. You must call db2_fetch_row() before calling db2_result() to set the location of the result set pointer.
stmtA valid stmt resource.
columnEither an integer mapping to the 0-indexed field in the result set, or a string matching the name of the column.
Returns the value of the requested field if the field exists in the result set. Returns NULL if the field does not exist, and issues a warning.
Example 1. A db2_result() example The following example demonstrates how to iterate through a result set with db2_fetch_row() and retrieve columns from the result set with db2_result().
The above example will output:
|
Rolls back an in-progress transaction on the specified connection resource and begins a new transaction. PHP applications normally default to AUTOCOMMIT mode, so db2_rollback() normally has no effect unless AUTOCOMMIT has been turned off for the connection resource.
Note: If the specified connection resource is a persistent connection, all transactions in progress for all applications using that persistent connection will be rolled back. For this reason, persistent connections are not recommended for use in applications that require transactions.
connectionA valid database connection resource variable as returned from db2_connect() or db2_pconnect().
Example 1. Rolling back a DELETE statement In the following example, we count the number of rows in a table, turn off AUTOCOMMIT mode on a database connection, delete all of the rows in the table and return the count of 0 to prove that the rows have been removed. We then issue db2_rollback() and return the updated count of rows in the table to show that the number is the same as before we issued the DELETE statement. The return to the original state of the table demonstrates that the roll back of the transaction succeeded.
The above example will output:
|
(no version information, might be only in CVS)
db2_server_info -- Returns an object with properties that describe the DB2 database serverThis function returns an object with read-only properties that return information about the IBM DB2, Cloudscape, or Apache Derby database server. The following table lists the database server properties:
Table 1. Database server properties
| Property name | Return type | Description |
|---|---|---|
| DBMS_NAME | string | The name of the database server to which you are connected. For DB2 servers this is a combination of DB2 followed by the operating system on which the database server is running. |
| DBMS_VER | string | The version of the database server, in the form of a string
"MM.mm.uuuu" where MM is the major version,
mm is the minor version,
and uuuu is the update. For example, "08.02.0001"
represents major version 8, minor version 2, update 1.
|
| DB_CODEPAGE | int | The code page of the database to which you are connected. |
| DB_NAME | string | The name of the database to which you are connected. |
| DFT_ISOLATION | string | The default transaction isolation level supported by the
server:
|
| IDENTIFIER_QUOTE_CHAR | string | The character used to delimit an identifier. |
| INST_NAME | string | The instance on the database server that contains the database. |
| ISOLATION_OPTION | array | An array of the isolation options supported by the database server. The isolation options are described in the DFT_ISOLATION property. |
| KEYWORDS | array | An array of the keywords reserved by the database server. |
| LIKE_ESCAPE_CLAUSE | bool | TRUE if the database server supports the use of % and _ wildcard characters. FALSE if the database server does not support these wildcard characters. |
| MAX_COL_NAME_LEN | int | Maximum length of a column name supported by the database server, expressed in bytes. |
| MAX_IDENTIFIER_LEN | int | Maximum length of an SQL identifier supported by the database server, expressed in characters. |
| MAX_INDEX_SIZE | int | Maximum size of columns combined in an index supported by the database server, expressed in bytes. |
| MAX_PROC_NAME_LEN | int | Maximum length of a procedure name supported by the database server, expressed in bytes. |
| MAX_ROW_SIZE | int | Maximum length of a row in a base table supported by the database server, expressed in bytes. |
| MAX_SCHEMA_NAME_LEN | int | Maximum length of a schema name supported by the database server, expressed in bytes. |
| MAX_STATEMENT_LEN | int | Maximum length of an SQL statement supported by the database server, expressed in bytes. |
| MAX_TABLE_NAME_LEN | int | Maximum length of a table name supported by the database server, expressed in bytes. |
| NON_NULLABLE_COLUMNS | bool | TRUE if the database server supports columns that can be defined as NOT NULL, FALSE if the database server does not support columns defined as NOT NULL. |
| PROCEDURES | bool | TRUE if the database server supports the use of the CALL statement to call stored procedures, FALSE if the database server does not support the CALL statement. |
| SPECIAL_CHARS | string | A string containing all of the characters other than a-Z, 0-9, and underscore that can be used in an identifier name. |
| SQL_CONFORMANCE | string | The level of conformance to the ANSI/ISO SQL-92 specification
offered by the database server:
|
Example 1. A db2_server_info() example To retrieve information about the server, you must pass a valid database connection resource to db2_server_info().
The above example will output:
|
Sets options for a statement resource or a connection resource. You cannot set options for result set resources.
resourceA valid statement resource as returned from db2_prepare() or a valid connection resource as returned from db2_connect() or db2_pconnect().
optionsAn associative array containing valid statement or connection options. This parameter can be used to change autocommit values, cursor types (scrollable or forward), and to specify the case of the column names (lower, upper, or natural) that will appear in a result set.
autocommitPassing DB2_AUTOCOMMIT_ON turns autocommit on for the specified connection resource.
Passing DB2_AUTOCOMMIT_OFF turns autocommit off for the specified connection resource.
cursorPassing DB2_FORWARD_ONLY specifies a forward-only cursor for a statement resource. This is the default cursor type, and is supported by all database servers.
Passing DB2_SCROLLABLE specifies a scrollable cursor for a statement resource. Scrollable cursors enable result set rows to be accessed in non-sequential order, but are only supported by IBM DB2 Universal Database databases.
binmodePassing DB2_BINARY specifies that binary data will be returned as is. This is the default mode. This is the equivalent of setting ibm_db2.binmode=1 in php.ini.
Passing DB2_CONVERT specifies that binary data will be converted to hexadecimal encoding, and will be returned as such. This is the equivalent of setting ibm_db2.binmode=2 in php.ini.
Passing DB2_PASSTHRU specifies that binary data will be converted to NULL. This is the equivalent of setting ibm_db2.binmode=3 in php.ini.
db2_attr_casePassing DB2_CASE_LOWER specifies that column names of the result set are returned in lower case.
Passing DB2_CASE_UPPER specifies that column names of the result set are returned in upper case.
Passing DB2_CASE_NATURAL specifies that column names of the result set are returned in natural case.
deferred_preparePassing DB2_DEFERRED_PREPARE_ON turns deferred prepare on for the specified statement resource.
Passing DB2_DEFERRED_PREPARE_OFF turns deferred prepare off for the specified statement resource.
The following new i5/OS options are available as of ibm_db2 version 1.5.1.
Note: Prior versions of ibm_db2 do not support these new i5 options.
i5_fetch_onlyDB2_I5_FETCH_ON - Cursors are read-only and cannot be used for positioned updates or deletes. This is the default unless SQL_ATTR_FOR_FETCH_ONLY environment has been set to SQL_FALSE.
DB2_I5_FETCH_OFF - Cursors can be used for positioned updates and deletes.
The following new options are available as of ibm_db2 version 1.6.0. They provide useful tracking information that can be accessed during execution with db2_get_option().
Note: Prior versions of ibm_db2 do not support these new options.
When the value in each option is being set, some servers might not handle the entire length provided and might truncate the value.
To ensure that the data specified in each option is converted correctly when transmitted to a host system, use only the characters A through Z, 0 through 9, and the underscore (_) or period (.).
useridSQL_ATTR_INFO_USERID - A pointer to a null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 16 characters. This user-id is not to be confused with the authentication user-id, it is for identification purposes only and is not used for any authorization.
acctstrSQL_ATTR_INFO_ACCTSTR - A pointer to a null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 200 characters.
applnameSQL_ATTR_INFO_APPLNAME - A pointer to a null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 32 characters.
wrkstnnameSQL_ATTR_INFO_WRKSTNNAME - A pointer to a null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.
Note: DB2 for z/OS and OS/390 servers support up to a length of 18 characters.
typeAn integer value that specifies the type of resource that was passed into the function. The type of resource and this value must correspond.
Passing 1 as the value specifies that a connection resource has been passed into the function.
Passing any integer not equal to 1 as the value specifies that a statement resource has been passed into the function.
The following table specifies which options are compatible with the available resource types:
Table 1. Resource-Parameter Matrix
| Key | Value | Resource Type | ||
|---|---|---|---|---|
| Connection | Statement | Result Set | ||
| autocommit | DB2_AUTOCOMMIT_ON | X | - | - |
| autocommit | DB2_AUTOCOMMIT_OFF | X | - | - |
| cursor | DB2_SCROLLABLE | - | X | - |
| cursor | DB2_FORWARD_ONLY | - | X | - |
| binmode | DB2_BINARY | X | X | - |
| binmode | DB2_CONVERT | X | X | - |
| binmode | DB2_PASSTHRU | X | X | - |
| db2_attr_case | DB2_CASE_LOWER | X | X | - |
| db2_attr_case | DB2_CASE_UPPER | X | X | - |
| db2_attr_case | DB2_CASE_NATURAL | X | X | - |
| deferred_prepare | DB2_DEFERRED_PREPARE_ON | - | X | - |
| deferred_prepare | DB2_DEFERRED_PREPARE_OFF | - | X | - |
| i5_fetch_only | DB2_I5_FETCH_ON | - | X | - |
| i5_fetch_only | DB2_I5_FETCH_OFF | - | X | - |
| userid | SQL_ATTR_INFO_USERID | X | X | - |
| acctstr | SQL_ATTR_INFO_ACCTSTR | X | X | - |
| applname | SQL_ATTR_INFO_APPLNAME | X | X | - |
| wrkstnname | < | |||