Manual de PHP

Stig Sæther Bakken
Alexander Aulbach
Egon Schmid
Jim Winstead
Lars Torben Wilson
Rasmus Lerdorf
Andrei Zmievski
Jouni Ahto

Editado por

Rafael Martínez (Coordinador)
Víctor Fernández
Leonardo Boshell

27-01-2003

Copyright

Este manual es © Copyright 1997, 1998, 1999, 2000, 2001, 2002 por el Grupo de documentación de PHP. Los miembros de este grupo se encuentran listados en la primera página de este manual.

Este manual puede ser redistribuido bajo los términos de la "GNU General Public License" publicada por la "Free Software Foundation"; tanto bajo la versión 2 de esta licencia o bajo versiones posteriores.

La sección 'Extendiendo PHP 4.0' de este manual es copyright © 2000 por Zend Technologies, Ltd. Este material puede ser distribuido solamente bajo los terminos y condiciones de la Open Publication License, v1.0 ó posterior (la última versión está disponible en http://www.opencontent.org/openpub/).


Tabla de contenidos
Prefacio
I. Conceptos Básicos
1. Introducción
2. A simple tutorial
3. Instalación
4. Configuración
5. Seguridad
II. Referencia del Lenguaje
6. Síntaxis básica
7. Types
8. Variables
9. Constantes
10. Expresiones
11. Operadores
12. Estructuras de Control
13. Funciones
14. Clases y Objetos
15. References Explained
III. Características
16. Autentificación HTTP con PHP
17. Cookies
18. Manejo de envío de ficheros
19. Usando archivos remotos
20. Manejando conexiones
21. Conexiones persistentes a bases de datos
22. Modo Seguro (Safe Mode)
23. Using PHP from the command line
IV. Referencia de las Funciones
I. Funciones específicas de Apache
II. Funciones de matrices
III. Funciones Aspell [deprecated]
IV. Funciones matemáticas de precisión arbitraria BCMath
V. Funciones de compresión Bzip2
VI. Funciones de calendario
VII. Funciones del API de CCVS
VIII. soporte de las funciones COM para Windows
IX. Funciones de Clases/Objectos
X. Funciones de ClibPDF
XI. Crack functions
XII. CURL, Client URL Library Functions
XIII. Funciones de pago electrónico
XIV. Crédit Mutuel CyberMUT functions
XV. Cyrus IMAP administration functions
XVI. Character type functions
XVII. Funciones de la capa de abstraccion de bases de datos (dbm-style)
XVIII. Funciones de fecha y hora
XIX. Funciones para dBase
XX. Funciones dbm
XXI. dbx functions
XXII. DB++ Functions
XXIII. Direct IO functions
XXIV. Funciones con directorios
XXV. Funciones de DOM XML
XXVI. .NET functions
XXVII. Error Handling and Logging Functions
XXVIII. FrontBase Functions
XXIX. Funciones filePro
XXX. Funciones del sistema de ficheros
XXXI. Funciones Forms Data Format (Formato de Datos de Formularios)
XXXII. FriBiDi functions
XXXIII. Funciones FTP
XXXIV. Function Handling functions
XXXV. GNU Gettext
XXXVI. GMP functions
XXXVII. Funciones HTTP
XXXVIII. Funciones para Hyperwave
XXXIX. Hyperwave API functions
XL. iconv functions
XLI. Funciones para imágenes
XLII. Funciones IMAP
XLIII. Funciones para Informix
XLIV. Funciones InterBase
XLV. Ingres II functions
XLVI. IRC Gateway Functions
XLVII. PHP / Java Integration
XLVIII. Funciones LDAP
XLIX. Funciones de Correo
L. mailparse functions
LI. Funciones matemáticas
LII. Multi-Byte String Functions
LIII. MCAL functions
LIV. Funciones Criptográficas
LV. MCVE Payment Functions
LVI. Funciones Hash
LVII. Mimetype Functions
LVIII. Funciones de Microsoft SQL Server
LIX. Ming functions for Flash
LX. Miscelánea de funciones
LXI. mnoGoSearch Functions
LXII. funciones mSQL
LXIII. Funciones MySQL
LXIV. Mohawk Software session handler functions
LXV. muscat functions
LXVI. Funciones de Red
LXVII. Ncurses terminal screen control functions
LXVIII. Lotus Notes functions
LXIX. ODBC functions
LXX. Object Aggregation/Composition Functions
LXXI. Funciones de Oracle 8
LXXII. OpenSSL functions
LXXIII. Funciones Oracle
LXXIV. Ovrimos SQL functions
LXXV. Output Control Functions
LXXVI. Object property and method call overloading
LXXVII. PDF functions
LXXVIII. Verisign Payflow Pro functions
LXXIX. opciones e información de PHP
LXXX. Funciones POSIX
LXXXI. Funciones de PostgreSQL
LXXXII. Process Control Functions
LXXXIII. Funciones de ejecución de programas
LXXXIV. Printer functions
LXXXV. Pspell Functions
LXXXVI. GNU Readline
LXXXVII. Funciones GNU Recode
LXXXVIII. Funciones de expresiones regulares compatibles con Perl
LXXXIX. qtdom functions
XC. Funciones para expresiones regulares
XCI. Funciones Semáforo y de memoria compartida
XCII. SESAM database functions
XCIII. Funciones para el manejo de sesiones
XCIV. Shared Memory Functions
XCV. Shockwave Flash functions
XCVI. Funciones SNMP
XCVII. Socket functions
XCVIII. Stream functions
XCIX. Funciones de cadenas
C. Funciones de Sybase
CI. Tokenizer functions
CII. Funciones URL
CIII. Funciones sobre variables
CIV. vpopmail functions
CV. W32api functions
CVI. Funciones WDDX
CVII. Funciones de intérprete XML
CVIII. XML-RPC functions
CIX. XSLT functions
CX. YAZ
CXI. NIS funciona
CXII. Zip File Functions (Read Only Access)
CXIII. Funciones de Compresión
V. Extending PHP 4.0
24. Overview
25. Extension Possibilities
26. Source Layout
27. PHP's Automatic Build System
28. Creating Extensions
29. Using Extensions
30. Troubleshooting
31. Source Discussion
32. Accepting Arguments
33. Creating Variables
34. Duplicating Variable Contents: The Copy Constructor
35. Returning Values
36. Printing Information
37. Startup and Shutdown Functions
38. Calling User Functions
39. Initialization File Support
40. Where to Go from Here
41. Reference: Some Configuration Macros
42. API Macros
43. Streams API for PHP Extension Authors
Overview
Streams Basics
Streams as Resources
Streams Common API Reference
Streams Dir API Reference
Streams File API Reference
Streams Socket API Reference
Streams Structures
Streams Constants
VI. FAQ: Preguntas frecuentes
44. General Information
45. Mailing lists
46. Obtaining PHP
47. Database issues
48. Installation
49. Build Problems
50. Using PHP
51. PHP and HTML
52. PHP and COM
53. PHP and other languages
54. Migrating from PHP 2 to PHP 3
55. Migrating from PHP 3 to PHP 4
56. Miscellaneous Questions
VII. Apéndices
A. Historia de PHP y proyectos relacionados
B. Migrating from PHP 3 to PHP 4
C. Migrando de PHP/FI 2.0 a PHP 3.0
D. El debugger de PHP
E. Desarrollo en PHP
F. Lista de alias de funciones
G. List of Reserved Words
H. List of Resource Types
I. List of Supported Protocols/Wrappers
J. Lista de Identificadores (tokens) del Analizador
K. Sobre el manual
L. Materia que falta

Prefacio

PHP, acrónimo de "PHP: Hypertext Preprocessor", es un lenguaje "Open Source" interpretado de alto nivel, especialmente pensado para desarrollos web y el cual puede ser embebido en páginas HTML. La mayoría de su sintaxis es similar a C, Java y Perl y es fácil de aprender. La meta de este lenguaje es permitir escribir a los creadores de páginas web, páginas dinámicas de una manera rápida y fácil, aunque se pueda hacer mucho más con PHP.

Este manual contiene principalmente una referencia de funciones PHP, tambien contiene una referencia del lenguaje, explicaciones de caracteristicas importantes de PHP y alguna información suplementaria.

Este manual se puede conseguir en diferentes formatos en http://www.php.net/docs.php. Estos ficheros son actualizados a medida que el manual vaya cambiando. Más información sobre como este manual es desarrollado puede encontrarse en el apéndice'Sobre este manual'

I. Conceptos Básicos


Capítulo 1. Introducción

Qué es PHP?

PHP (acronimo de "PHP: Hypertext Preprocessor") es un lenguaje "open source" interpretado de alto nivel embebido en páginas HTML y ejecutado en el servidor.

Una respuesta corta y concisa, pero que significa realmente? Un ejemplo nos aclarará las cosas:

Ejemplo 1-1. Un ejemplo introductorio

<html>
    <head>
        <title>Example</title>
    </head>
    <body>

        <?php 
        echo "Hi, I'm a PHP script!"; 
        ?>

    </body>
</html>

Podemos ver que no es lo mismo que un script escrito en otro lenguaje de programación como Perl o C -- En vez de escribir un programa con muchos comandos para crear una salida en HTML, escribimos el código HTML con cierto código PHP embebido (introducido) en el mismo, que producirá cierta salida (en nuestro ejemplo, producir un texto). El código PHP se incluye entre etiquetas especiales de comienzo y final que nos permitirán entrar y salir del modo PHP.

Lo que distingue a PHP de la tecnología Javascript, la cual se ejecuta en la máquina cliente, es que el código PHP es ejecutado en el servidor. Si tuviesemos un script similar al de nuestro ejemplo en nuestro servidor, el cliente sólamente recibiría el resultado de su ejecución en el servidor, sin ninguna posibilidad de determinar que código ha producido el resultado recibido. El servidor web puede ser incluso configurado para que procese todos los ficheros HTML con PHP.

Lo mejor de usar PHP es que es extremadamente simple para el principiante, pero a su vez, ofrece muchas caracteristicas avanzadas para los programadores profesionales. No tengais miedo de leer la larga lista de caracteristicas de PHP, en poco tiempo podreis empezar a escribir vuestros primeros scripts.

Aunque el desarrollo de PHP está concentrado en la programación de scripts en la parte del servidor, se puede utilizar para muchas otras cosas. Sigue leyendo y descubre más sobre PHP en la sección Qué se puede hacer con PHP?.


Qué se puede hacer con PHP?

PHP puede hacer cualquier cosa que se pueda hacer con un script CGI, como procesar la información de formularios, generar páginas con contenidos dinámicos, o mandar y recibir cookies. Y esto no es todo, se puede hacer mucho más.

Existen tres campos en los que scripts escritos en PHP son usados.

  • Scripts en la parte del servidor. Este es el campo más tradicional y el principal campo de trabajo. Se necesitan tres cosas para que esto funcione. El analizador PHP (CGI ó módulo), un servidor web y un navegador. Se necesita correr el servidor web con PHP instalado. El resultado del programa PHP se puede obtener a través del navegador, conectando con el servidor web. Consultar la sección Instrucciones de instalación para más información.

  • Scripts en linea de comandos. Podeis crear un script PHP y correrlo sin ningún servidor web ó navegador. Solamente necesitais el parseador PHP para usarlo de esta manera. Este tipo de uso es ideal para scripts ejecutados regularmente desde cron (en *nix ó Linux) ó el Planificador de tareas (en Windows). Estos scripts tambien pueden ser usados para tareas simples de procesado de texto. Consultar la sección Usos de PHP en la linea de comandos para más información.

  • Escribir aplicaciones gráficas clientes. PHP no es probablemente el mejor lenguaje para escribir aplicaciones gráficas, pero si sabeis bien PHP, y os gustaria utilizar algunas características avanzadas en programas clientes, podeis utilizar PHP-GTK para escribir dichos programas. Es tambien posible escribir aplicaciones independientes de una plataforma. PHP-GTK es una extensión de PHP, no disponible en la distribución principal. Si te interesa PHP-GTK, puedes visitar las páginas web del projecto.

PHP puede ser utilizado en cualquiera de los principales sistemas operativos del mercado, incluyendo Linux, muchas variantes Unix (incluido HP-UX, Solaris y OpenBSD), Microsoft Windows, Mac OS X, RISC OS y probablemente alguno más. PHP soporta la mayoría de servidores web de hoy en día, incluyendo Apache, Microsoft Internet Information Server, Personal Web Server, Netscape y iPlanet, Oreilly Website Pro server, Caudium, Xitami, OmniHTTPd y muchos otros. PHP tiene módulos disponibles para la mayoría de los servidores, para aquellos otros que soporten el estándar CGI, PHP puede usarse como procesador CGI.

Asi que, con PHP teneis la libertad de escoger el sistema operativo y el servidor de vuestro gusto. Tambien teneis la posibilidad de usar programación de procediminetos ó programación orientada a objetos. Aunque no todas la características estándares de la programación orientada a objetos están implementadas en la versión actual de PHP, muchas librerías y aplicaciones grandes (incluyendo la libreria PEAR) están escritas íntegramente usando programación orientada a objetos.

Con PHP no estais limitados a resultados en HTML. Entre las habilidades de PHP se incluyen, creación de imágenes, ficheros PDF y películas Flash (usando libswf y Ming) sobre la marcha. Tambien podeis presentar otros resultados, como XHTM y ficheros XML. PHP puede autogenerar estos ficheros y grabarlos en el sistema de ficheros en vez de presentarlos en la pantalla.

Quizas la característica más potente y destacable de PHP es su soporte para una gran cantidad de bases de datos. Escribir un interfaz via web para una base de datos es una tarea simple con PHP. Las siguientes bases de datos están soportadas actualmente:

Adabas DIngresOracle (OCI7 and OCI8)
dBaseInterBaseOvrimos
EmpressFrontBasePostgreSQL
FilePro (read-only)mSQLSolid
HyperwaveDirect MS-SQLSybase
IBM DB2MySQLVelocis
InformixODBCUnix dbm

Tambien tenemos una extensión DBX de abstracción de base de datos que permite usar de forma transparente cualquier base de datos soportada por la extension. Adicionalmente, PHP soporta ODBC (The Open Database Connection standard), asi que podeis conectar a cualquier base de datos que soporte este estandar.

PHP tambien tiene soporte para comunicarse con otros servicios usando protocolos tales como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (en Windows) y muchos otros. Tambien se pueden crear raw sockets. PHP soporta WDDX para intercambio de datos entre lenguajes de programación en web. Y hablando de interconexión, PHP puede utilizar objetos Java de forma transparente como objetos PHP Y la extensión de CORBA puede ser utilizada para acceder a objetos remotos.

PHP tiene unas características muy útiles para el proceso de texto, desde expresiones regulares POSIX Extended ó Perl hasta parseador de documentos XML. Para parsear y acceder documentos XML, soportamos los estandares SAX y DOM. Podeis utilizar la extensión XSLT para transformar documentos XML.

Si usais PHP en el campo del comercio electrónico, encontrareis muy útiles las funciones Cybercash, CyberMUT, VeriSign Payflow Pro y CCVS para vuestros programas de pago.

Para terminar, tenemos muchas otras extensiones muy interesantes, las funciones del motor de búsquedas mnoGoSearch, funciones para pasarelas de IRC, utilidades de compresión (gzip, bz2),, conversión de calendarios, traducción .....

Como podeis ver esta página no es suficiente para enumerar todas las características y beneficios que PHP ofrece. Consultar las secciones Instalando PHP y Referencia de las funciones para una explicación de las extensiones mencionadas aqui.


Capítulo 2. A simple tutorial

Here we would like to show the very basics of PHP in a short simple tutorial. This text only deals with dynamic webpage creation with PHP, though PHP is not only capable of creating webpages. 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.


What do I need?

In this tutorial we assume that your server has support for PHP activated 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 don't need to do anything. Just create your .php files and put them in your web directory and the server will magically 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.

Let's say you want to save precious bandwidth and develop locally. In this case, you'll want to install a web server, such as Apache, and of course PHP. You'll most likely want to install a database as well, such as MySQL. You can install these individually or a simpler way is to locate a pre-configured package that automatically installs all of these with just a few mouse clicks. It's easy to setup a web server with PHP support on any operating system, including Linux and Windows. In linux, you may find rpmfind helpful for locating RPMs.


Your first PHP-enabled page

Create a file named hello.php and put it in your web servers root directory (DOCUMENT_ROOT) with the following content:

Ejemplo 2-1. Our first PHP script: hello.php

<html>
 <head>
  <title>PHP Test</title>
 </head>
 <body>
 <?php echo "<p>Hello World</p>"; ?>
 </body>
</html>

Use your browser to access the file with your web access URL, ending with the "/hello.php" file reference. When developing locally this url will be something like http://localhost/hello.php or http://127.0.0.1/hello.php but this depends on the web servers configuration. Although this is outside the scope of this tutorial, see also the DocumentRoot and ServerName directives in your web servers configuration file. (on Apache this is httpd.conf). If everything is setup correctly, this file will be parsed by PHP and the following output will make it to your browser:

<html>
 <head>
  <title>PHP Test</title>
 </head>
 <body>
 <p>Hello World</p>
 </body>
</html>

Note that this is not like a CGI script. The file does not need to be executable or special in any way. Think of it as a normal HTML file which happens to have a set of special tags available to you that do a lot of interesting things.

This program is extremely simple and you really didn't need to use PHP to create a page like this. All it does is display: Hello World using the PHP echo() statement.

If you tried this example and it didn't output anything, or 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. Ask your administrator to enable it for you using the Installation chapter of the manual. If you're developing locally, also read the installation chapter to make sure everything is configured properly. If problems continue to persist, don't 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 all you want. For more details, read the manual section on basic PHP syntax.

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 Editor's 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 good choices 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"). Alternately, 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've successfully created a simple PHP script that works, it's time to create the most famous PHP script! Make a call to the phpinfo() function and you'll 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.


Something Useful

Let's do something a bit more useful now. We are going to check what sort of browser the person viewing the page is using. In order to do that we check the user agent string that the browser sends as part of its 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"].

PHP Autoglobals Note: $_SERVER is a special reserved PHP variable that contains all web server information. It's known as an Autoglobal (or Superglobal). See the related manual page on Autoglobals for more information. These special variables were introduced in PHP 4.1.0. Before this time, we used the older $HTTP_*_VARS arrays instead, such as $HTTP_SERVER_VARS. Although deprecated, these older variables still exist. (See also the note on old code.)

To display this variable, we can simply do:

Ejemplo 2-2. Printing a variable (Array element)

<?php echo $_SERVER["HTTP_USER_AGENT"]; ?>

A sample output of this script may be:
Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)

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's automatically made available to you by PHP. A list can be seen in the Reserved Variables section of the manual or you can get a complete list of them by creating a file that looks like this:

Ejemplo 2-3. Show all predefined variables with phpinfo()

<?php phpinfo(); ?>

If you load up this file in your browser you will see a page full of information about PHP along with a list of all the variables available to you.

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 we wanted to check for Internet Explorer we could do something like this:

Ejemplo 2-4. Example using control structures and functions

<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
	echo "You are using Internet Explorer<br />";
}
?>

A sample output of this script may be:
You are using Internet Explorer<br />

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. If you don't know enough C or some other language where the syntax used above is used, you should probably pick up any introductory PHP book and read the first couple of chapters, or read the Language Reference part of the manual. You can find a list of PHP books at http://www.php.net/books.php.

The second concept we introduced was the strstr() function call. strstr() is a function built into PHP which searches a string for another string. In this case we are looking for "MSIE" inside $_SERVER["HTTP_USER_AGENT"]. If the string is found, the function returns TRUE and if it isn't, it returns FALSE. If it returns TRUE, the if statement evaluates to TRUE and the code within its {braces} is executed. Otherwise, it's not. Feel free to create similar examples, with if, else, and other functions such as strtoupper() and strlen(). Each related manual page contains examples too.

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:

Ejemplo 2-5. Mixing both HTML and PHP modes

<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
?>
<h3>strstr must have returned true</h3>
<center><b>You are using Internet Explorer</b></center>
<?php
} else {
?>
<h3>strstr must have returned false</h3>
<center><b>You are not using Internet Explorer</b></center>
<?php
}
?>

A sample output of this script may be:
<h3>strstr must have returned true</h3>
<center><b>You are using Internet Explorer</b></center>

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 if strstr() returned TRUE or FALSE In other words, if the string MSIE was found or not.


Dealing with Forms

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 in a form 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's an example HTML form:

Ejemplo 2-6. A simple HTML form

<form action="action.php" method="POST">
 Your name: <input type="text" name="name" />
 Your age: <input type="text" name="age" />
 <input type="submit">
</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 have something like this:

Ejemplo 2-7. Printing data from our form

Hi <?php echo $_POST["name"]; ?>.
You are <?php echo $_POST["age"]; ?> years old.

A sample output of this script may be:
Hi Joe.
You are 22 years old.

It should be obvious what this does. There is nothing more to it. The $_POST["name"] and $_POST["age"] variables are automatically set for you by PHP. Earlier we used the $_SERVER autoglobal, now above we just introduced the $_POST autoglobal 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 autoglobal instead. You may also use the $_REQUEST autoglobal if you don't care the source of your request data. It contains a mix of GET, POST, COOKIE and FILE data. See also the import_request_variables() function.


Using old code with new versions of PHP

Now that PHP has grown to be a popular scripting language, there are more resources out there that have listings of code you can reuse in your own scripts. For the most part the developers of the PHP language have tried to be backwards compatible, so a script written for an older version should 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 autoglobal arrays were introduced in PHP 4.1.0. They are: $_GET, $_POST, $_COOKIE, $_SERVER, $_ENV, $_REQUEST, and $_SESSION. The older $HTTP_*_VARS arrays, such as $HTTP_POST_VARS, still exist and have since PHP 3.

  • 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 autoglobal arrays mentioned above. Older scripts, books, and tutorials may rely on this directive being on. If 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.

For more details on these changes, see the section on predefined variables and links therein.


What's next?

With what you know now 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.


Capítulo 3. Instalación

Bajándose la última versión

El código fuente y las distribuciones binarias para algunas plataformas (incluído Windows) se pueden encontrar en http://www.php.net/.


Instalación en sistemas UNIX

Esta sección le guiará a través de la configuración e instalación del PHP. Conocimientos y software necesarios:

  • Habilidades básicas en UNIX (ser capaz de manejar el "make" y un compilador de C)

  • Un compilador ANSI de C

  • Un servidor web


Instrucciones Rápidas de Instalación (Versión Módulo de Apache)

1.  gunzip apache_1.3.x.tar.gz
2.  tar xvf apache_1.3.x.tar
3.  gunzip php-3.0.x.tar.gz
4.  tar xvf php-3.0.x.tar
5.  cd apache_1.3.x
6.  ./configure --prefix=/www
7.  cd ../php-3.0.x
8.  ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars
9.  make
10. make install
11. cd ../apache_1.3.x
12. ./configure --prefix=/www --activate-module=src/modules/php3/libphp3.a
13. make
14. make install

  En lugar de este paso quizás prefiera simplemente copiar el binario
  httpd encima del binario existente. Si lo hace, asegúrese antes de
  cerrar su servidor.

15. cd ../php-3.0.x
16. cp php3.ini-dist /usr/local/lib/php3.ini

  Puede editar el archivo /usr/local/lib/php3.ini para ajustar opciones
  del PHP. Si prefiere tenerlo en otro sitio, utilice
  --with-config-file-path=/path en el paso 8.

17. Edite su archivo httpd.conf o srm.conf y añada: 
      
            AddType application/x-httpd-php3 .php3
 
  Puede elegir la extensión que desee aquí. .php3 es simplemente nuestra
  sugerencia.

18. Utilice su método habitual para iniciar el servidor Apache (debe detener
    y reiniciar el servidor, no solamente hacerlo recargarse usando una
    señal HUP o USR1.)


Configuración

Hay dos maneras de configurar el PHP.

  • Utilizando el script de "setup" que viene con el PHP. Este script le hace una serie de preguntas (casi como el script "install" del PHP/FI 2.0) y ejecuta el "configure" al final. Para ejecutar este script, escriba ./setup.

    Este script también creará un archivo llamado "do-conf", que contendrá las opciones pasadas a la configuración. Puede editar este archivo para cambiar algunas opciones sin tener que re-ejecutar el "setup". Escriba luego ./do-conf para ejecutar la configuración con las nuevas opciones.

  • Ejecutar el "configure" a mano. Para ver las opciones de que dispone, escriba ./configure --help.

Los detalles sobre las distintas opciones de configuración son listados a continuación.


Módulo del Apache

Para configurar el PHP como módulo de Apache, responda "yes" a "Build as an Apache module?" (la opción --with-apache=DIR es la que lo configura) y especifique el directorio base de la distribución de Apache. Si ha desempacado el Apache en /usr/local/www/apache_1.2.4, este será su directorio base de la distribución de Apache. El directorio por defecto es /usr/local/etc/httpd.


Módulo fhttpd

Para configurar el PHP como módulo fhttpd, responda "yes" a "Build as an fhttpd module?" (la opción --with-fhttpd=DIR es la que lo configura) y especifique el directorio base del fuente del fhttpd. El directorio por defecto es /usr/local/src/fhttpd. Si está ejecutando fhttpd, configurar PHP como módulo le dará mejor rendimiento, más control y capacidad de ejecución remota.


CGI version

El valor por defecto es configurar el PHP como programa CGI. Si está ejecutando un servidor web para el que el PHP tiene soporte como módulo, debería elegir dicha solución por motivos de rendimiento. Sin embargo, la versión CGI permite a los usuarios del Apache el ejecutar distintas páginas con PHP bajo distintos identificadores de usuario. Por favor, asegúrese de haber leído el capítulo sobre Seguridad si va a ejecutar el PHP como CGI.


Opciones de soporte para Base de Datos

El PHP tiene soporte nativo para bastantes bases de datos (así como para ODBC):


Adabas D

--with-adabas=DIR

Compila con soporte para Adabas D. El parámetro es el directorio de instalación de Adabas D y por defecto vale /usr/local/adabasd.

Página de Adabas


dBase

--with-dbase

Habilita el soporte integrado para DBase. No se precisan librerías externas.


filePro

--with-filepro

Habilita el soporte integrado de sólo lectura para filePro. No se precisan librerías externas.


mSQL

--with-msql=DIR

Habilita el soporte para mSQL. El parámetro es el directorio de instalación de mSQL y por defecto vale /usr/local/Hughes. Este es el directorio por defecto de la distribución mSQL 2.0. configure detecta automáticamente qué versión de mSQL está ejecutándose y el PHP soporta tanto 1.0 como 2.0, pero si compila el PHP con mSQL 1.0 sólo podrá acceder a bases de datos de esa versión y viceversa.

Vea también Directivas de Configuración de mSQL en el archivo de configuración.

Página de mSQL


MySQL

--with-mysql=DIR

Habilita el soporte para MySQL. El parámetro es el directorio de instalación de MySQL y por defecto vale /usr/local. Este es el directorio de instalación de la distribución de MySQL.

Vea también Directivas de Configuración de MySQL en el archivo de configuración.

Página de MySQL


iODBC

--with-iodbc=DIR

Incluye soporte para iODBC. Esta característica se desarrolló inicialmente para el iODBC Driver Manager, un gestor de controlador de ODBC de redistribución libre que ese ejecuta bajo varios sabores de UNIX. El parámetro es el directorio de instalación de iODBC y por defecto vale /usr/local.

Página de FreeODBC o página de iODBC


OpenLink ODBC

--with-openlink=DIR

Incluye soporte para OpenLink ODBC. El parámetro es el directorio de instalación de OpenLink ODBC y por defecto vale /usr/local/openlink.

Página de OpenLink Software


Oracle

--with-oracle=DIR

Incluye soporte para Oracle. Se ha probado y debería funcionar al menos con las versiones de la 7.0 a la 7.3. El parámetro es el directorio ORACLE_HOME. No necesita especificar este parámetro si su entorno de Oracle ya está ajustado.

Página de Oracle


PostgreSQL

--with-pgsql=DIR

Incluye soporte para PostgreSQL. El parámetro es el directorio base de la instalación de PostgreSQL y por defecto vale /usr/local/pgsql.

Vea también Directivas de Configuración de Postgres en el archivo de configuración.

Página de PostgreSQL


Solid

--with-solid=DIR

Incluye soporte para Solid. El parámetro es el directorio de instalación y vale por defecto /usr/local/solid.

Página de Solid


Sybase

--with-sybase=DIR

Incluye soporte para Sybase. El parámetro es el directorio de instalación y vale por defecto /home/sybase.

Vea también Directivas de Configuración de Sybase en el archivo de configuración.

Página de Sybase


Sybase-CT

--with-sybase-ct=DIR

Incluye soporte para Sybase-CT. El parámetro es el directorio de instalación de Sybase-CT y por defecto vale /home/sybase.

Vea también Directovas de Configuración de Sybase-CT en el archivo de configuración.


Velocis

--with-velocis=DIR

Incluye soporte para Velocis. El parámetro es el directorio de instalación de Velocis y vale por defecto /usr/local/velocis.

Página de Velocis


Una librería a medida de ODBC

--with-custom-odbc=DIR

Incluye soporte para una librería a medida arbitraria de ODBC. El parámetro es el directorio base y por defecto vale /usr/local.

Esta opción implica que se ha definido CUSTOM_ODBC_LIBS cuando se ejecutó el script de configuración. También deberá tener una cabecera odbc.h válida en algún lugar de su sendero (path) de inclusión. Si no tiene uno, créelo e incluya su cabecera específica desde ahí. Su cabecera puede requerir algunas definiciones extra, particularmente si es multiplataforma. Defínalas en CFLAGS.

Por ejemplo, puede usar Sybase SQL Anywhere bajo QNX como sigue: CFLAGS=-DODBC_QNX LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib -lodbc" ./configure --with-custom-odbc=/usr/lib/sqlany50


ODBC Unificado

--disable-unified-odbc

Deshabilita el módulo de ODBC Unificado, que es un interfaz común a todas las bases de datos con interfaces basados en ODBC, tales como Solid y Adabas D. También funciona para librerías normales de ODBC. Ha sido probado con iODBC, Solid, Adabas D y Sybase SQL Anywhere. Requiere que uno (y sólo uno) de estos módulos o el módulo de Velocis esté habilitado, o que se especifique una librería a medida de ODBC. Esta opción sólo se puede aplicar si alguna de estas opciones es usada: --with-iodbc, --with-solid, --with-adabas, --with-velocis, o --with-custom-odbc.

Vea también Directivas de Configuración de ODBC Unificado en el archivo de configuración.


LDAP

--with-ldap=DIR

Incluye soporte para LDAP (Lightweight Directory Access Protocol - Protocolo Ligero de Acceso a Directorios). El parámetro es el directorio base de instalación de LDAP, y por defecto vale /usr/local/ldap.

Puede encontrar más información sobre LDAP en RFC1777 y en RFC1778.


Otras opciones de configuración

--with-mcrypt=DIR

--with-mcrypt

Incluye soporte para la librería mcrypt. Vea la documentación de mcrypt para más información. Si utiliza el argumento opcional DIR, el PHP buscará mcrypt.h en DIR/include.


--enable-sysvsem

--enable-sysvsem

Incluye soporte para semáforos Sys V (soportados por muchos derivados Unix). Vea la documentación sobre Semáforos y Memoria Compartida para más información.


--enable-sysvshm

--enable-sysvshm

Incluye soporte para la memoria compartida Sys V (soportada por muchos derivados Unix). Vea la documentación sobre Semáforos y Memoria Compartida para más información.


--with-xml

--with-xml

Incluye soporte para un parser XML no validador que utiliza la librería expat de James Clark. Vea la referencia de funciones XML para más detalles.


--enable-maintainer-mode

--enable-maintainer-mode

Activa avisos extra de dependencias y del compilador utilizados por algunos de los desarrolladores del PHP.


--with-system-regex

--with-system-regex

Utiliza la librería de expresiones regulares del sistema en lugar de la incluída. Si está compilando PHP como módulo de servidor, debe utilizar la misma librería cuando genere el PHP y cuando lo enlace con el servidor. Active esto si la librería del sistema proporciona características especiales que pueda necesitar. Se recomienda utilizar la librería incluída siempre que sea posible.


--with-config-file-path

--with-config-file-path=DIR

El path utilizado para buscar el archivo de configuración cuando arranca el PHP.


--with-exec-dir

--with-exec-dir=DIR

Sólo permite ejecutar programas en DIR cuando está en modo seguro. Por defecto vale /usr/local/bin. Esta opción sólo fija el valor por defecto. Puede ser cambiado posteriormente mediante la directiva safe_mode_exec_dir en el fichero de configuración .


--enable-debug

--enable-debug

Habilita información de depuración adicional. Esto hace posible obtener información más detallada cuando hay problemas con el PHP. (Nótese que esto no tiene que ver con las facilidades de depuración o con la información disponible para los script PHP).


--enable-safe-mode

--enable-safe-mode

Habilita el "modo seguro" por defecto. Esto impone varias restricciones sobre lo que el PHP puede hacer, tales como abrir fichero sólo en el raiz de documentos. Lea el capítulo de Seguridad para más información. Los usuarios de CGI deberán siempre habilitar el modo seguro. Esta opción sólo fija el valor por defecto. Puede ser habilitado o deshabilitado posteriormente mediante la directiva safe_mode en el archivo de configuración.


--enable-track-vars

--enable-track-vars

Hace que el PHP lleve el control de dónde proceden las variables GET/POST/cookie usando las matrices HTTP_GET_VARS, HTTP_POST_VARS y HTTP_COOKIE_VARS. Esta opción sólo fija el valor por defecto. Puede ser habilitado o deshabilitado posteriormente mediante la directiva track_vars en el archivo de configuración.


--enable-magic-quotes

--enable-magic-quotes

Habilita las comillas mágicas por defecto. Esta opción sólo fija el valor por defecto. Puede ser habilitada o deshabilitada posteriormente mediante la directiva magic_quotes_runtime en el archivo de configuración. Vea también las directivas magic_quotes_gpc y magic_quotes_sybase.


--enable-debugger

--enable-debugger

Habilita el soporte de depuración interno del PHP. Esta característica aún está en estado experimental. Vea también las directivas de Configuración del Depurador en el archivo de configuración.


--enable-discard-path

--enable-discard-path

Si está habilitado, el ejecutable CGI del PHP se puede situar tranquilamente fuera del árbol de la web y la gente no podrá saltarse la seguridad del .htaccess. Lea la sección en el capítulo de seguridad sobre esta opción.


--enable-bcmath

--enable-bcmath

Habilita las funciones matemáticas de precisión arbitraria estilo bc. Vea también la opción bcmath.scale en el archivo de configuración.


--enable-force-cgi-redirect

--enable-force-cgi-redirect

Habilita la comprobación de seguridad para redirecciones internas del servidor. Deberá usar esta opción si está ejecutando la versión CGI bajo Apache.

Cuando se utiliza el PHP como un ejecutable CGI, siempre comprueba primero is está siendo utilizado bajo redirección (por ejemplo bajo Apache, usando directivas Action). Esto asegura que el ejecutable del PHP no se puede usar para saltarse los mecanismos estánder de autentificación del servidor web llamando al ejecutale directamente, como en http://my.host/cgi-bin/php/secret/doc.html. Este ejemplo accede al archivo http://my.host/secret/doc.html pero sin respetar ningún ajuste de seguridad del httpd para el directorio /secret.

No habilitando esta opción se deshabilita la comprobación y se permite el saltarse los ajustes de seguridad y autenticación del httpd. Haga esto sólo si el software de su servidor no puede indicar que se ha realizado una redirección segura y que todos sus archivos bajo la raiz de documentos y los directorios de los usuarios pueden ser accedidos por cualquiera.

Lea la sección en el capítulo de seguridad acerca de esta opción.


--disable-short-tags

--disable-short-tags

Deshabilita las etiquetas de PHP en formato corto <? ?>. Debe deshabilitar el formato corto si desea usar PHP con XML. Con el formato corto deshabilitado, la única etiqueta de código de PHP es <?php ?>. Esta opción sólo fija el valor por defecto. Puede ser habilitada o deshabilitada posteriormente mediante la directiva short_open_tag en el archivo de configuración.


--enable-url-includes

--enable-url-includes

Hace posible ejecutar código en otros servidores HTTP o FTP directamente desde el PHP usando include(). Vea también la opción include_path en el archivo de configuración.


--disable-syntax-hl

--disable-syntax-hl

Desconecta el resalte de sintáxis.


CPPFLAGS y LDFLAGS

Para hacer que la instalación de PHP busque los archivos de cabecera o de librería en distintos directorios, modifique las variables de entorno CPPFLAGS y LDFLAGS respectivamente. Si está utilizando un shell "sensible", podrá ejecutar LDFLAGS=-L/my/lib/dir CPPFLAGS=-I/my/include/dir ./configure


Construyendo

Cuando el PHP está configurado, ya está listo para construir el ejecutable CGI o la librería PERL. El comando make debería ocuparse de esto. Si fallara y no puede saber el motivo, vea la sección de Problemas.


Probando

Si ha construído el PHP como un programa CGI, puede probar su funcionamiento tecleando make test. Siempre es buena idea probar su construcción. Así puede atrapar pronto los problemas del PHP en su plataforma sin tener que batallar con ellos luego.


Comprobando la velocidad

Si ha construído el PHP como un programa CGI, puede comprobar la velocidad de su código escribiendo make bench. Nótese que se el modo seguro está habilitado por defecto, el test no podrá finalizar si se toma más de los 30 segundos disponibles. Esto se debe a que la función set_time_limit() no se puede usar en modo seguro. Use el ajuste de configuración max_execution_time para controlar este tiempo en sus propios script. make bench ignora el archivo de configuración.


Instalación en sistemas Windows 95/98/NT

Esta guía de instalación le ayudará a instalar y configurar el PHP en sus servidores web bajo Windows 9x/NT. Esta guía fue compilada por Bob Silva. La última revisión puede encontrarse en http://www.umesd.k12.or.us/php/win32install.html.

Esta guía proporciona soporte de instalacion para:

  • Personal Web Server (se recomienda la última versión)

  • Internet Information Server 3 ó 4

  • Apache 1.3.x

  • Omni HTTPd 2.0b1


Pasos Generales de Instalación

Los siguientes pasos deben realizarse en todas las instalaciones antes de las instrucciones específicas de cada servidor.

  • Extraiga el archivo de distribución a un directorio de su elección. "C:\PHP3\" es un buen comienzo.

  • Copie el archivo 'php3.ini-dist' a su directorio '%WINDOWS%' y renómbrelo a 'php3.ini'. Su directorio '%WINDOWS%' es típicamente:

    c:\windows para Windows 95/98
    c:\winnt o c:\winnt40 para servidores NT

  • Edite su archivo 'php3.ini':

    • Necesitaá cambiar la opción 'extension_dir' para que apunte a su php-install-dir, o a donde quiera que haya puesto sus archivos 'php3_*.dll'. P.ej.: c:\php3

    • Si está utilizando Omni Httpd, no siga el siguiente paso. Fije el 'doc_root' para que apunte a la raiz web de sus servidores. P.ej.: c:\apache\htdocs o c:\webroot

    • Elija qué módulos desearía cargar cuando comience el PHP. Puede descomentar las líneas: 'extension=php3_*.dll' para cargar estos módulos. Algunos módulos requieren que tenga instaladas en sus sistema librerías adicionales para que el módulo funcione correctamente. El FAQ de PHP tiene más información sobre dónde obtener librerías de soporte. También puede cargar un módulo dinámicamente en su script utilizando: dl("php_*.dll");

    • En el PWS y el IIS puede fijar el browscap.ini para que apunte a: 'c:\windows\system\inetsrv\browscap.ini' bajo Windows 95/98 y a 'c:\winnt\system32\inetsrv\browscap.ini' bajo NT Server.

Las DLL para las extensiones del PHP van precedidas de 'php3_'. Esto evita confusiones entre las extensiones del PHP y sus librerías de soporte.


Windows 95/98/NT y PWS/IIS 3

El método recomendado para configurar estos servidores es usar el archivo INF incluído con la distribución (php_iis_reg.inf). Quizás desee editar este archivo y asegurarse que las extensiones y directorios de instalación se ajustan a su configuración. O puede seguir los pasos que siguen para hacerlo de forma manual.

AVISO: Estos pasos conllevan el trabajar directamente con el registro de windows. Un error aquí puede dejar su sistema en un estado inestable. Le recomendamos encarecidamente que haga una copia de seguridad del registro con antelación. El equipo de Desarrollo del PHP no se hará responsable si se daña su registro.

  • Ejecute Regedit.

  • Navegue hasta: HKEY_LOCAL_MACHINE /System /CurrentControlSet /Services /W3Svc /Parameters /ScriptMap.

  • En el menú de edición elija: New->String Value.

  • Escriba la extensión que desea usar para sus script PHP. P.ej.: .php3

  • Haga doble click en el nuevo valor de cadena y escriba la ruta al php.exe en el campo del valor. P.ej.: c:\php3\php.exe %s %s. La parte '%s %s' son MUY importantes, pues el PHP no funcionará correctamente sin ella.

  • Repita estos pasos para cada extensión que desee asociar con los scripts PHP.

  • Ahora navegue hasta: HKEY_CLASSES_ROOT

  • En el menú de edición elija: New->Key.

  • Déle a la clave el nombre de la extensión que preparó en la sección anterior. P.ej.: .php3

  • Marque la nueva clave y en el panel del lado derecho haga doble click en "default value" y escriba phpfile.

  • Repita el último paso para cada extensión que haya preparado en la sección previa.

  • Ahora cree otra New->Key bajo HKEY_CLASSES_ROOT y denomínela phpfile.

  • Marque la nueva clave phpfile y haga doble click en el panel derecho sobre "default value" y escriba PHP Script.

  • Pulse el botón derecho sobre la clave phpfile y seleccione New->Key y llámela Shell.

  • Pulse el botón derecho sobre la clave Shell y elija New->Key y llámela open.

  • Pulse el botón derecho sobre la clave open y elija New->Key y llámela command.

  • Marque la nueva clave command y en el panel derecho haga doble click sobre "default value" y entre la ruta hasta el php.exe. P.ej.: c:\php3\php.exe -q %1. (no olvide el %1).

  • Salga del Regedit.

Los usuarios de PWS e IIS3 tienen ahora un sistema completamente operativo. Los usuarios del IIS3 también pueden usar una curiosa herramienta de Steven Genusa para configurar sus mapeados de script.


Windows NT e IIS 4

Para instalar el PHP en un NT Server con IIS 4, siga estas instrucciones:

  • En el Controlador de Servicios de Internet (MMC), elija el sitio Web o el directorio de comienzo de una aplicación.

  • Abra las propiedades del directorio (haciendo click derecho y eligiendo propiedades) y luego pulse sobre la pestaña Carpeta Inicial, Directorio Virtual o Directorio.

  • Pulse el botón Configuración y luego pulse sobre la pestaña Mapas de Aplicación.

  • Pulse en Añadir, y en la caja Programa, escriba: c:\path-to-php-dir\php.exe %s %s. DEBE mantene los %s %s al final, pues el PHP no funcionará correctamente si se equivoca al hacerlo.

  • En la caja Extensión, escriba la extensión de fichero que desea asociar a los script de PHP. Debe repetir los pasos 5 y 6 para cada extensión que desee asociar con los scripts PHP ( .php3 y .phtml son habituales).

  • Ajuste la seguridad apropiada (esto se realiza en el Controlador de Servicio de Internet (ISM)), y si su NT Server usa el sistema de archivos NTFS, añada derechos de ejecución para I_USR_ al directorio que contenga el php.exe.


Windows 9x/NT y Apache 1.3.x

Debe editar sus archivos srm.conf o httpd.conf para configurar el Apache para que trabaje con el ejecutable CGI del PHP.

Aunque puede haber algunas variaciones al configurar PHP bajo Apache, esta es lo suficientemente simple para ser usada por el novato. Por favor, consulte la Documentación del Apache para saber de las subsiguientes directivas de configuración.

  • ScriptAlias /php3/ "c:/ruta-al-dir-del-php/"

  • AddType application/x-httpd-php3 .php3

  • AddType application/x-httpd-php3 .phtml

  • Action application/x-httpd-php3 "/php3/php.exe"

Para utilizar la capacidad de marcado del código fuente, cree simplemente un script de PHP y pegue este código en él: <?php show_source("script_original_php.php3"); ?>. Sustituya script_original_php.php3 por el nombre del archivo del que desea visualizar el código fuente (esta es la única forma de hacerlo). Nota: Bajo Win-Apache todas las barras invertidas de una ruta tal como: "c:\directory\file.ext", deben ser convertidas a barras hacia adelante.


Omni HTTPd 2.0b1 para Windows

Esta ha resultado ser la configuración más sencilla:

Paso 1: Instale el servidor Omni
Paso 2: Pulse el botón derecho sobre el icono azul del OmniHTTPd que está en la barrita del sistema y elija Propiedades
Paso 3: Pulse sobre Web Server Global Settings
Paso 4: En la pestaña 'External', escriba: virtual = .php3 | actual = c:\ruta-al-dir-del-php\php.exe
Paso 5: En la pestaña Mime, escriba: virtual = wwwserver/stdcgi | actual = .php3
Paso 6: Pulse en OK

Repita los pasos 2 a 6 para cada extensión que desee asociar al PHP.


Módulos del PHP

Tabla 3-1. Módulos del PHP

php3_calendar.dllFunciones de conversión de calendario
php3_crypt.dllFunciones de criptografía
php3_dbase.dllFunciones para DBase
php3_dbm.dllEmulación GDBM con la librería Berkeley DB2
php3_filepro.dllAcceso SÓLO LECTURA a bases de datos filepro
php3_gd.dllFunciones de librería GD para manipular GIF
php3_hyperwave.dllFunciones de HyperWave
php3_imap4r2.dllFunciones de IMAP 4
php3_ldap.dllFunciones de LDAP
php3_msql1.dllCliente de mSQL 1
php3_msql2.dllCliente de mSQL 2
php3_mssql.dllCliente de MSSQL client (requiere las librerías de MSSQL DB
php3_mysql.dllFunciones de MySQL
php3_nsmail.dllFunciones de correo de Netscape
php3_oci73.dllFunciones de Oracle
php3_snmp.dllFunciones get y walk de SNMP (¡sólo en NT!)
php3_zlib.dllFunciones de ZLib


¿Problemas?

Lea las PMF (FAQ)

Algunos problemas son más comunes que otros. Los más comunes están listados en las PMF (Preguntas Más Frecuentes) del PHP, que están en http://www.php.net/FAQ.php


Informes de error

Si cree que ha encontrado un error en el PHP, por favor infórmenos. Los desarrolladores del PHP probablemente no tengan conocimiento del mismo, y salvo si informa del mismo, pocas probabilidades habrá de que lo solucionen. Puede informar de los errores usando el sistema de rastreo de errores en http://bugs.php.net/.


Otros problemas

Si aún se encuentra atascado, alguien de la lista de correos del PHP puede ser capaz de ayudarle. Deberá buscar primero en los archivos, por si acaso alguien ya ha respondido a otra persona que tuvo el mismo problema que usted. Los archivos están disponibles desde la página de soporte en http://www.php.net/. Para suscribirse a la lista de correo de PHP, envíe un correo vacío a php-general-subscribe@lists.php.net. La dirección de la lista de correo es php-general@lists.php.net.

Si desea ayuda sobre la lista de correo, intente ser preciso y de los detalles necesarios sobre su entorno (qué sistema operativo, qué versión de PHP, qué servidor web, si está ejecutando el PHP como CGI o como módulo de servidor, etc.) y también código suficiente para que otros puedan reproducir y comprobar su problema.


Capítulo 4. Configuración

El archivo de configuración

El archivo de configuración (llamado php3.ini en PHP 3.0, y simplemente php.ini a partir del PHP 4.0) es leído cuando arranca el PHP. Para las versiones de PHP como módulo de servidor esto sólo ocurre una vez al arrancar el servidor web. Para la versión CGI, esto ocurre en cada llamada.

Cuando se utiliza PHP como módulo Apache, también puede cambiar los ajustes de configuración utilizando directivas en los archivos de configuración del Apache y en los .htaccess.

Con el PHP 3.0 hay directivas Apache que se corresponden a cada uno de los ajustes de configuración del php3.ini, con la excepción que su nombre va precedido de "php3_".

Con el PHP 4.0 sólo hay unas pocas directivas de Apache que le permiten cambiar los ajustes de configuración del PHP.

php_value nombre valor

Fija el valor de la variable especificada.

php_flag nombre on|off

Fija una opción de configuración de tipo Boolean.

php_admin_value nombre valor

Fija el valor de la variable especificada. Los ajustes de configuración de tipo "Admin" sólo se pueden fijar desde los archivos principales de configuración del Apache, y no desde los .htaccess.

php_admin_flag nombre on|off

Fija una opción de configuración de tipo Boolean.

Puede ver los ajustes de los valores de configuración en la salida de phpinfo(). También puede acceder a los valores individuales de los ajustes de configuración utilizando get_cfg_var().


Directivas Generales de Configuración

asp_tags boolean

Permite el uso de las etiquetas estilo ASP <% %> además de las habituales etiquetas <?php ?>. También se incluye el atajo para imprimir variables <%= $valor %>. Para más información, vea Escapando del HTML.

Nota: El soporte para etiquetas estilo ASP se añadió en la 3.0.4.

auto_append_file string

Especifica el nombre de un archivo que es troceado automáticamente después del archivo principal. El archivo se incluye como si fuese llamado mediante la función include(), así que se utiliza include_path.

El valor especial none desconecta la adición automática de archivos.

Nota: Si el script es terminado con exit(), no tendrá lugar la adición automática.

auto_prepend_file string

Especifica el nombre de un archivo que es troceado automáticamente antes del archivo principal. Specifies the name of a file that is automatically parsed before the main file. El archivo se incluye como si fuese llamado mediante la función include(), así que se utiliza include_path.

El valor especial none desconecta la adición automática de archivos.

cgi_ext string

display_errors boolean

Determina si los errores se visualizan en pantalla como parte de la salida en HTML o no.

doc_root string

"Directorio raiz" del PHP en el servidor. Sólo se usa si no está vacío. Si el PHP se configura con safe mode, no se sirven archivos fuera de este directorio.

engine boolean

Esta directiva sólo es realmente útil en la versión de PHP como módulo Apache. Se utiliza por sitios que desean habilitar la ejecución del PHP directorio por directorio o en base a cada servidor virtual. Poniendo php3_engine off en los sitios apropiados del archivo httpd.conf, se puede habilitar o deshabilitar el PHP.

error_log string

Nombre del fichero para registrar los errores de un script. Si se utiliza el valor especial syslog, los errores se envían al registro de errores del sistema. En UNIX se refiere a syslog(3) y en Windows NT al registro de eventos. El registro de errores del sistema no es soportado bajo Windows 95.

error_reporting integer

Fija el nivel de informe de errores. El parámetro es un entero que representa un campo de bits. Sume los valores de los niveles de informe de error que desea.

Tabla 4-1. Niveles de Informe de Errores

valor de bitinforme habilitado
1errores normales
2avisos normales
4errores del troceador (parser)
8avisos de estilo no críticos
El valor por defecto para esta directiva es 7 (se muestran los errores normales, avisos normales y errores de parser).

open_basedir string

Limita los archivos que se pueden abrir por el PHP al árbol de directorios especificado.

Cuando un script intenta abrir un archivo con, por ejemplo, fopen o gzopen, se comprueba su localización. Si el fichero está fuera del árbol de directorios especificado, PHP se negará a abrirlo. Todos los enlaces simbólicos son resueltos, de modo que no es posible evitar esta limitación usando uno de ellos.

El valor especial . indica que el directorio base será aquel en el que reside el script.

Bajo Windows, separe los directorios mediante punto y coma. En el resto de sistemas, sepárelos con dos puntos ":". Como módulo de Apache, los senderos para open_basedir de los directorios padre se heredan ahora automáticamente.

Nota: El soporte para directorios múltiples se añadió en la 3.0.7.

El valor por defecto es permitir abrir todos los archivos.

gpc_order string

Fija el order de troceo de variables GET/POST/COOKIE. El valor por defecto de esta directiva es "GPC". Fijándola, por ejemplo, a "GP", hará que el PHP ignore por completo las cookies y que sobreescriba las variables recibidas por GET con las que tengan el mismo nombre y vengan por POST.

ignore_user_abort string

Por defecto está a on. Si se cambia a off, los script terminarán tan pronto como intenten enviar algo después de que un cliente ha roto la conexión. ignore_user_abort().

include_path string

Especifica una lista de directorios en los que las funciones require(), include() y fopen_with_path() buscan los archivos. El formato es similar a la variable de entorno de sistema PATH: una lista de directorios separados por dos puntos en UNIX o por punto y coma en Windows.

Ejemplo 4-1. include_path en UNIX

include_path=.:/home/httpd/php-lib

Ejemplo 4-2. include_path en Windows

include_path=".;c:\www\phplib"
El valor por defecto para esta directiva es . (sólo el directorio actual).

isapi_ext string

log_errors boolean

Dice si los mensajes de error de los script deben ser registrados o no en el registro del servidor. Esta opción, por tanto, es específica del mismo.

magic_quotes_gpc boolean

Fija el estado magic_quotes para operaciones GPC (Get/Post/Cookie). Si magic_quotes vale on, todas las ' (comilla sencilla), " (comilla doble), \ (barra invertida) y los NUL son automáticamente marcados con una barra invertida. Si además magic_quotes_sybase vale on, la comilla sencilla es marcada con otra comilla sencilla en lugar de la barra invertida.

magic_quotes_runtime boolean

Si se habilita magic_quotes_runtime, muchas de las funciones que devuelven datos de algún tipo de fuente externa incluyendo bases de datos y archivos de texto devolverán las comillas marcadas con una barra invertida. Si también está activo magic_quotes_sybase, la comilla simple es marcada con una comilla simple en lugar de la barra invertida.

magic_quotes_sybase boolean

Si magic_quotes_sybase está a on, la comilla simple es marcada con una comilla simple en lugar de la barra invertida cuando están habilitados magic_quotes_gpc o magic_quotes_runtime.

max_execution_time integer

Fija el tiempo máximo en segundos que se le permite usar a un script antes de ser finalizado por el intérprete. Así se evita que scripts mal escritos puedan bloquear el servidor.

memory_limit integer

Fija el tamaño máximo de memoria en bytes que se permite reclamar a un script. Así se evita que script mal escritos se coman toda la memoria dispomible de un servidor.

nsapi_ext string

short_open_tag boolean

Indica si se debe permitir el formato corto (<? ?>) de la etiqueta de apertura del PHP. Si desea utilizar PHP en combinación con XML, deberá desactivar esta opción. Si está desactivada, deberá utilizar el formato largo de la etiqueta de apertura (<?php ?>).

sql.safe_mode boolean

track_errors boolean

Si está habilitada, el último mensaje de error estará siempre presente en la variable global $php_errormsg.

track_vars boolean

Si está activada, la información de entrada de GET, POST y de las cookies se puede encontrar en las matrices asociativas $HTTP_GET_VARS,$HTTP_POST_VARS y $HTTP_COOKIE_VARS respectivamente.

upload_tmp_dir string

El directorio temporal utilizado para almacenar archivos cuando se envían al servidor. Debe tener permiso de escritura para el usuario bajo el que corra el PHP.

user_dir string

El nombre base del directorio utilizado bajo el directorio inicial de un usuario para los archivos PHP. Por ejemplo: paginas_html.

warn_plus_overloading boolean

Si está activada, esta opción hace que el PHP muestre un aviso cuando el operador suma (+) se utiliza en cadenas. Así es más fácil encontrar scripts que necesitan ser reescritos utilizando en su lugar el concatenador de cadenas (.).


Directivas de Configuración de Correo

SMTP string

Nombre DNS o dirección IP del servidor de SMTP que el PHP bajo Windows deberá usar para enviar correo con la función mail().

sendmail_from string

La dirección del remitente ("De:") para los correos enviados desde PHP bajo Windows.

sendmail_path string

Localización del programa sendmail. Generalmente /usr/sbin/sendmail o /usr/lib/sendmail. configure intenta localizarle este archivo lo mejor que puede y fijar un valor por defecto, pero en caso de fallo, lo puede usted fijar aquí.

Los sistemas que no usan sendmail deberán fijar esta directiva al nombre del programa alternativo que ofrezca su sistema de correo, si es que existe. Por ejemplo, los usuarios del Qmail pueden fijarlo normalmente a /var/qmail/bin/sendmail.


Directivas de Configuración de Modo Seguro

safe_mode boolean

Para activar el modo seguro del PHP. Lea el Capítulo de seguridad para más información.

safe_mode_exec_dir string

Si el PHP se utiliza en modo seguro, la función system() y el resto de funciones que ejecutan programas del sistema se niegan a ejecutar programas que no estén en este directorio.


Directivas de Configuración del Debugger

debugger.host string

Nombre DNS o dirección IP del servidor usado por el debugger.

debugger.port string

Número de puerto usado por el debugger.

debugger.enabled boolean

Indica si el debugger está habilitado o no.


Directivas de Carga de Extensiones

enable_dl boolean

Esta directiva sólo es útil en la versión del PHP como módulo del Apache. Puede habilitar o deshabilitar para un servidor virtual o para un directorio la carga dinámica de extensiones de PHP mediante dl().

La razón principal para deshabilitar la carga dinámica es la seguridad. Con la carga dinámica es posible ignorar las restricciones safe_mode y open_basedir.

El valor por defecto es permitir la carga dinámica, excepto cuando se usa el modo seguro. En modo seguro, siempre es imposible usar dl().

extension_dir string

En qué directorio debe buscar el PHP las extensiones cargables dinámicamente.

extension string

Qué extensiones dinámicas debe cargar el PHP cuando arranca.


Directivas de Configuración de MySQL

mysql.allow_persistent boolean

Si permitir o no conexiones MySQL persistentes.

mysql.default_host string

El servidor por defecto para utilizar cuando se conecte al servidor de bases de datos si no se especifica otro distinto.

mysql.default_user string

El nombre de usuario por defecto para utilizar cuando se conecta al servidor de base de datos si no se especifica otro.

mysql.default_password string

La clave por defecto para utilizar cuando se conecta al servidor de base de datos si no se especifica otro.

mysql.max_persistent integer

El número máximo de conexiones persistentes de MySQL por proceso.

mysql.max_links integer

El número máximo de conexiones de MySQL por proceso, incluyendo las persistentes.


Directivas de Configuración de mSQL

msql.allow_persistent boolean

Si se permiten o no conexiones persistentes de mSQL.

msql.max_persistent integer

El número máximo de conexiones persistentes mSQL por proceso.

msql.max_links integer

El número máximo de conexiones de mSQL por proceso, incluyendo las persistentes.


Directivas de Configuración de Postgres

pgsql.allow_persistent boolean

Si se permiten o no conexiones persistentes de Postgres.

pgsql.max_persistent integer

El número máximo de conexiones persistentes Postgres por proceso.

pgsql.max_links integer

El número máximo de conexiones de Postgres por proceso, incluyendo las persistentes.


SESAM Configuration Directives

sesam_oml string

Name of BS2000 PLAM library containing the loadable SESAM driver modules. Required for using SESAM functions. The BS2000 PLAM library must be set ACCESS=READ,SHARE=YES because it must be readable by the apache server's user id.

sesam_configfile string

Name of SESAM application configuration file. Required for using SESAM functions. The BS2000 file must be readable by the apache server's user id.

The application configuration file will usually contain a configuration like (see SESAM reference manual):

CNF=B
NAM=K
NOTYPE

sesam_messagecatalog string

Name of SESAM message catalog file. In most cases, this directive is not neccessary. Only if the SESAM message file is not installed in the system's BS2000 message file table, it can be set with this directive.

The message catalog must be set ACCESS=READ,SHARE=YES because it must be readable by the apache server's user id.


Directivas de Configuración de Sybase

sybase.allow_persistent boolean

Si se permiten o no conexiones persistentes de Sybase.

sybase.max_persistent integer

El número máximo de conexiones persistentes Sybase por proceso.

sybase.max_links integer

El número máximo de conexiones de Sybase por proceso, incluyendo las persistentes.


Directivas de Configuración de Sybase-CT

sybct.allow_persistent boolean

Si se permiten o no conexiones persistentes de Sybase-CT. El valor por defecto es on.

sybct.max_persistent integer

El número máximo de conexiones persistentes Sybase-CT por proceso. El valor por defecto es -1, que significa ilimitadas.

sybct.max_links integer

El número máximo de conexiones de Sybase-CT por proceso, incluyendo las persistentes. El valor por defecto es -1, que significa ilimitadas.

sybct.min_server_severity integer

Los mensajes de servidor con gravedad mayor o igual que sybct.min_server_severity serán reportados como avisos. Este valor también se puede cambiar desde un script usando la función sybase_min_server_severity(). El valor por defecto es 10, que reporta los errores de información con gravedad o mayores.

sybct.min_client_severity integer

Los mensajes de librería de cliente con gravedad mayor o igual que sybct.min_client_severity serán reportados como avisos. Este valor también se puede cambiar desde un script usando la función sybase_min_client_severity(). El valor por defecto es 10, que desconecta los avisos.

sybct.login_timeout integer

El número máximo de segundos de espera por un intento de conexión con éxito antes de indicar un fallo. Nótese que si se ha excedido max_execution_time cuando finaliza la espera de un intento de conexión, el script será finalizado antes de que se pueda tomar una acción en caso de fallo. El valor por defecto es 1 minuto.

sybct.timeout integer

El número máximo de segundos de espera por una operación de consulta o select_db con éxito antes de indicar un fallo. Nótese que si se ha excedido max_execution_time cuando finaliza la espera de un intento de conexión, el script será finalizado antes de que se pueda tomar una acción en caso de fallo. El valor por defecto es sin límite.

sybct.hostname string

El nombre de la máquina desde la que dice estarse conectando, para que se visualize con sp_who(). El valor por defecto es "none".


Directivas de Configuración de Informix

ifx.allow_persistent boolean

Si se permiten o no conexiones persistentes de Informix.

ifx.max_persistent integer

El número máximo de conexiones persistentes de Informix por proceso.

ifx.max_links integer

El número máximo de conexiones Informix por proceso, incluyendo las persistentes.

ifx.default_host string

El servidor por defecto al que conectarse si no se especifica uno en ifx_connect() o en ifx_pconnect().

ifx.default_user string

El id de usuario por defecto para utilizar si no se especifica uno en ifx_connect() o en ifx_pconnect().

ifx.default_password string

La clave por defecto para utilizar si no se especifica uno en ifx_connect() o en ifx_pconnect().

ifx.blobinfile boolean

Fíjelo a TRUE si desea recibir las columnas blob (objetos binarios grandes) en un archivo, y a FALSE si las desea en memoria. Puede cambiar el ajuste en tiempo de ejecución utilizando ifx_blobinfile_mode().

ifx.textasvarchar boolean

Fíjelo a TRUE si desea recibir las columnas TEXT como cadenas normales en las instrucciones select, y a FALSE si quiere usar parámetros de identificador de blobs. Puede cambiar el ajuste en tiempo de ejecución utilizando ifx_textasvarchar().

ifx.byteasvarchar boolean

Fíjelo a TRUE si desea devolver las columnas BYTE como cadenas normales en las instrucciones select, y a FALSE si quiere usar parámetros de identificador de blobs. Puede cambiar el ajuste en tiempo de ejecución utilizando ifx_byteasvarchar().

ifx.charasvarchar boolean

Fíjelo a TRUE si desea suprimir los espacios a la derecha de las columnas CHAR cuando las solicita.

ifx.nullformat boolean

Fíjelo a TRUE si desea que las columnas NULL (nulas) se devuelvan como la cadena literal "NULL", y a FALSE si desea que se devuelvan como la cadena vacía "". Puede cambiar el ajuste en tiempo de ejecución utilizando ifx_nullformat().


Directivas de Configuración de Matemática BC

bcmath.scale integer

Número de dígitos decimales para todas las funciones de bcmath.


Directivas de Configuración de Capacidades de los Navegadores

browscap string

Nombre del archivo de capacidades del navegador. Vea también get_browser().


Directivas Unificadas de Configuración de ODBC

uodbc.default_db string

Fuentes de datos ODBC a utilizar si no se especifica una en odbc_connect() o en odbc_pconnect().

uodbc.default_user string

Nombre de usuario si no se especifica uno en odbc_connect() o en odbc_pconnect().

uodbc.default_pw string

Clave para usar si no se especifica una en odbc_connect() o en odbc_pconnect().

uodbc.allow_persistent boolean

Si se permiten o no conexiones persistentes de ODBC.

uodbc.max_persistent integer

El número máximo de conexiones persistentes de ODBC por proceso.

uodbc.max_links integer

El número máximo de conexiones ODBC por proceso, incluyendo las persistentes.


Capítulo 5. Seguridad

PHP es un potente lenguaje y el interprete, tanto incluido en el servidor web como modulo o ejecutado como un binario CGI, puede acceder a ficheros, ejecutar comandos y abrir comunicaciones de red en el servidor. Todas estas caracteristicas hacen que lo que se ejecute en el servidor web sea inseguro por defecto. PHP ha sido disenado especificamente, para ser un lenguaje mas seguro para escribir programas CGI, que Perl o C y con la correcta seleccion de las opciones de configuración del tiempo de compilación y ejecucion se consigue la exacta combinación de libertad y seguridad que se necesita.

Ya que existen diferentes modos de utilizar PHP, existen multitud de opciones de configuración que permiten controlar su funcionamiento. Una gran selección de opciones garantiza que se pueda usar PHP para diferentes usos, pero tambien significa que existen combinaciones de estas opciones y configuraciones del servidor que producen instalaciones inseguras. Este capitulo explica las diferentes combinaciones de opciones de configuración y las situaciones donde pueden ser usadas de manera segura.


Binarios CGI

Posibles ataques

Usando PHP como un binario CGI es una opción para instalaciones que por cualquier causa no quieren integrar PHP como modulo en el software servidor (p.ej: Apache), o usaran PHP con diferentes clases de CGI wrappers para crear entornos chroot y setuid seguros para los scripts. Esta configuración implica generalmente el instalar el binario ejecutable de PHP en el directorio cgi-bin del servidor web. El documento del CERT CA-96.11 recomienda no instalar interpretes en cgi-bin. Aunque el binario PHP puede ser usado como interprete independiente, PHP esta diseñado para prevenir los ataques que esta configuración hace posible.

  • Accediendo a ficheros del sistema: http://my.host/cgi-bin/php?/etc/passwd

    La información introducida despues del signo de interrogación (?) es transferida como argumento de la línea de comando al intérprete por el interfaz del CGI. Normalmente los interpretes abren y ejecutan el fichero especificado como el primer argumento en la línea de comando.

    Cuando se ejecuta como un CGI script, PHP rechaza interpretar los argumentos de la línea de comando.

  • Accediendo cualquier documento web en el servidor: http://my.host/cgi-bin/php/secret/doc.html

    La información con el camino (path) de la URL despues del nombre del binario PHP, /secret/doc.html es usada convencionalmente para especificar el nombre del fichero que sera abierto e interpretado por el programa CGI. Normalmente, algunas directivas del servidor web (Apache:Action) son usadas para redireccionar peticiones de documentos como http://my.host/secret/script.php3 al interprete PHP. Con esta configuración, el servidor web comprueba primero los permisos de acceso al directorio /secret, y despues crea la petición redireccionada http://my.host/cgi-bin/php/secret/script.php3. Desafortunadamente, si la petición es hecha de esta forma en un principio, el servidor web no comprueba los permisos de acceso del fichero /secret/script.php3, sino solamente del fichero /cgi-bin/php. De esta manera cualquier usuario que pueda acceder /cgi-bin/php tambien puede acceder a cualquier documento protegido en el servidor web.

    En PHP, a la hora de compilar, la opción de configuracion --enable-force-cgi-redirect y las directivas de configuracion a la hora de ejecutar doc_root y user_dir pueden ser usadas para prevenir este ataque, si el arbol de documentos del servidor tiene cualquier directorio con acceso restringido. Ver mas adelante la explicacion de las diferentes combinaciones.


Caso 1: solamente se sirven ficheros publicos

Si tu servidor no contiene informacion que este protegida con clave o acceso de control de IPs, no se necesitan estas opciones de configuracion. Si tu servidor web no permite realizar redireccionamientos, o el servidor no tiene modo de comunicar al binario PHP que la peticion es una peticion segura redireccionada, podeis especificar la opcion --disable-force-cgi-redirect en el script de configuracion. De todas maneras, teneis que aseguraros que vuestros scripts PHP no confíen en la manera al llamar al script, ni de forma directa http://my.host/cgi-bin/php/dir/script.php3 o por redireccion http://my.host/dir/script.php3.

Redireccionamiento puede ser configurado en Apache usando las directivas AddHandler y Action (ver mas abajo).


Caso 2: usando --enable-force-cgi-redirect

Esta opcion a la hora de compilar previene que alguien llame PHP directamente con una url como la siguiente http://my.host/cgi-bin/php/secretdir/script.php3. PHP solamente analizara en este modo si ha pasado por una regla de redireccionamiento en el servidor.

Normalmente la redireccion en la configuracion de Apache es hecha con la siguientes directivas:

Action php3-script /cgi-bin/php
    AddHandler php3-script .php3

Esta opcion ha sido solo comprobada con el servidor web Apache, y depende de Apache para fijar la variable de entorno CGI no estandar REDIRECT_STATUS en las peticiones de redireccionamiento. Si tu servidor web no soporta ningun modo para informar si una peticion es directa o redireccionada, no podeis usar esta opcion y debereis usar alguno de los otros modos de ejecucion de la version CGI documentados aqui.


Caso 3: Usando doc_root or user_dir

Incluir contenidos activos, como script y ejecutables, en el directorio de documentos del servidor web, es algunas veces considerada una practica insegura. Si por algun fallo de configuracion, los scripts no son ejecutados pero mostrados como documentos HTML, cualquiera podra conseguir codigo registrado o informacion de seguridad, como p.ej: claves de acceso. Por ello, muchos administradores prefieren utilizar otra estructura de directorios que contenga solamente los scripts, los cuales seran solamente accesibles via PHP CGI, y por ello siempre seran interpretados y no mostrados.

Habra que tener en cuenta que si el metodo que asegura que las peticiones no son redireccionadas, como hemos descrito en la seccion anterior, no esta disponible, sera necesario configurar un script doc_root que sea diferente del "web document root".

Podeis definir el script PHP "document root" con la directiva de configuracion doc_root en el fichero de configuracion, o definir la variable de entorno PHP_DOCUMENT_ROOT. Si esta definida, la version CGI de PHP siempre obtendra el nombre del fichero a abrir con doc_root y el camino (path) utilizado en la peticion, asi podeis estar seguros que ningun script sera ejecutado fuera de este directorio (excepto para user_dir, ver a continuacion)

Otra opcion que se puede usar aqui es user_dir. Cuando user_dir no esta definido, lo unico que controla la apertura del fichero es doc_root. Si intentamos abrir una url tal como esta http://my.host/~user/doc.php3 no se abrira un fichero en el directorio de usuarios, en su lugar se abrira un fichero llamado ~user/doc.php3 en el directorio doc_root. (si, un directorio que empieza por tilde [~]).

Si user_dir esta definido por ejemplo como public_php, una peticion tal como http://my.host/~user/doc.php3, abrira un fichero llamado doc.php3 en el directorio llamado public_php del directorio "home" del usuario. Si el directorio del usuario es /home/user, el fichero ejecutado sera /home/user/public_php/doc.php3.

La expansion de user_dir ocurre sin tener en cuenta la configuracion de doc_root, de este modo se puede controlar los accesos al directorio principal (document root) y al directorio de usuario separadamente.


Caso 4: Analizador PHP fuera del arbol web.

Una opcion muy segura es poner el analizador binario PHP, en algun lugar fuera del arbol de ficheros web. Por ejemplo en /usr/local/bin. La unica pega real de esta opcion es que habra que poner una linea similar a:

#!/usr/local/bin/php

como primera linea en cualquier fichero que contenga codigo PHP. Tambien sera necesario asignar al fichero permisos de ejecucion. De esta manera, es tratado de la misma manera que cualquier otro CGI script escrito en Perl o sh o otro lenguaje utilizado para scripts y que utilicen el mecanismo #! para ejecutarse.

Para conseguir que PHP maneje correctamente con esta configuracion, la informacion de PATH_INFO y PATH_TRANSLATED, el analizador PHP deberia ser compilado con la opcion de configuracion --enable-discard-path.


Modulo Apache

Cuando PHP es usado como modulo Apache, hereda los permisos de usuario de Apache (normalmente "nobody")


Capítulo 6. Síntaxis básica

Saliendo de HTML

Para interpretar un archivo, php símplemente interpreta el texto del archivo hasta que encuentra uno de los carácteres especiales que delimitan el inicio de código PHP. El intérprete ejecuta entonces todo el código que encuentra, hasta que encuentra una etiqueta de fin de código, que le dice al intérprete que siga ignorando el código siguiente. Este mecanismo permite embeber código PHP dentro de HTML: todo lo que está fuera de las etiquetas PHP se deja tal como está, mientras que el resto se interpreta como código.

Hay cuatro conjuntos de etiquetas que pueden ser usadas para denotar bloques de código PHP. De estas cuatro, sólo 2 (<?php. . .?> y <script language="php">. . .</script>) están siempre disponibles; el resto pueden ser configuradas en el fichero de php.ini para ser o no aceptadas por el intérprete. Mientras que el formato corto de etiquetas (short-form tags) y el estilo ASP (ASP-style tags) pueden ser convenientes, no son portables como la versión de formato largo de etiquetas. Además, si se pretende embeber código PHP en XML o XHTML, será obligatorio el uso del formato <?php. . .?> para la compatibilidad con XML.

Las etiquetas soportadas por PHP son:

Ejemplo 6-1. Formas de escapar de HTML

1.  <?php echo("si quieres servir documentos XHTML o XML, haz como aqu&iacute;\n"); ?>

2.  <? echo ("esta es la m&aacute;s simple, una instrucci&oacute;n de procesado SGML \n"); ?>
    <?= expression ?> Esto es una abreviatura de "<? echo expression ?>"

3.  <script language="php">
        echo ("muchos editores (como FrontPage) no
              aceptan instrucciones de procesado");
    </script>

4.  <% echo ("Opcionalmente, puedes usar las etiquetas ASP"); %>
    <%= $variable; # Esto es una abreviatura de "<% echo . . ." %>

El método primero, <?php. . .?>, es el más conveniente, ya que permite el uso de PHP en código XML como XHTML.

El método segundo no siempre está disponible. El formato corto de etiquetas está disponible con la función short_tags() (sólo PHP 3), activando el parámetro del fichero de configuración de PHP short_open_tag, o compilando PHP con la opción --enable-short-tags del comando configure. Aunque esté activa por defecto en php.ini-dist, se desaconseja el uso del formato de etiquetas corto.

El método cuarto sólo está disponible si se han activado las etiquetas ASP en el fichero de configuración: asp_tags.

Nota: El soporte de etiquetas ASP se añadió en la versión 3.0.4.

Nota: No se debe usar el formato corto de etiquetas cuando se desarrollen aplicaciones o librerías con intención de redistribuirlas, o cuando se desarrolle para servidores que no están bajo nuestro control, porque puede ser que el formato corto de etiquetas no esté soportado en el servidor. Para generar código portable y redistribuíble, asegúrate de no usar el formato corto de etiquetas.

La etiqueta de fin de bloque incluirá tras ella la siguiente línea si hay alguna presente. Además, la etiqueta de fin de bloque lleva implícito el punto y coma; no necesitas por lo tanto añadir el punto y coma final de la última línea del bloque PHP.

PHP permite estructurar bloques como:

Ejemplo 6-2. Métodos avanzados de escape

<?php
if ($expression) {
    ?>
    <strong>This is true.</strong>
    <?php
} else {
    ?>
    <strong>This is false.</strong>
    <?php
}
?>
Este ejemplo realiza lo esperado, ya que cuando PHP encuentra las etiquetas ?> de fin de bloque, empieza a escribir lo que encuentra tal cual hasta que encuentra otra etiqueta de inicio de bloque. El ejemplo anterior es, por supuesto, inventado. Para escribir bloques grandes de texto generamente es más eficiente separalos del código PHP que enviar todo el texto mediante las funciones echo(), print() o similares.


Separación de instrucciones

Las separación de instrucciones se hace de la misma manera que en C o Perl - terminando cada declaración con un punto y coma.

La etiqueta de fin de bloque (?>) implica el fin de la declaración, por lo tanto lo siguiente es equivalente:

<?php
    echo "This is a test";
?>

<?php echo "This is a test" ?>


Comentarios

PHP soporta el estilo de comentarios de 'C', 'C++' y de la interfaz de comandos de Unix. Por ejemplo:

<?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 shell-style style comment
?>

Los estilos de comentarios de una linea actualmente sólo comentan hasta el final de la linea o el bloque actual de código PHP, lo primero que ocurra.

<h1>This is an <?php # echo "simple";?> example.</h1>
<p>The header above will say 'This is an example'.

Hay que tener cuidado con no anidar comentarios de estilo 'C', algo que puede ocurrir al comentar bloques largos de código.

<?php
 /*
    echo "This is a test"; /* This comment will cause a problem */
 */
?>

Los estilos de comentarios de una linea actualmente sólo comentan hasta el final de la linea o del bloque actual de código PHP, lo primero que ocurra. Esto implica que el código HTML tras // ?> seráa impreso: ?> sale del modo PHP, retornando al modo HTML, el comentario // no le influye.


Capítulo 7. Types

PHP soporta los siguientes tipos:

El tipo de una variable normalmente no lo indica el programador; en su lugar, lo decide PHP en tiempo de ejecución dependiendo del contexto en el que se utilice esa variable.

Si se quisiese obligar a que una variable se convierta a un tipo concreto, se podría forzar la variable o usar la función settype() para ello.

Nótese que una variable se puede comportar de formas diferentes en ciertas situaciones, dependiendo de qué tipo sea en ese momento. Para más información, vea la sección Conversión de Tipos.


Enteros

Los enteros se puede especificar usando una de las siguientes sintaxis:

$a = 1234; # número decimal
$a = -123; # un número negativo
$a = 0123; # número octal (equivalente al 83 decimal)
$a = 0x12; # número hexadecimal (equivalente al 18 decimal)


Números en punto flotante

Los números en punto flotante ("double") se pueden especificar utilizando cualquiera de las siguientes sintaxis:

$a = 1.234; $a = 1.2e3;


Cadenas

Las cadenas de caracteres se pueden especificar usando uno de dos tipos de delimitadores.

Si la cadena está encerrada entre dobles comillas ("), las variables que estén dentro de la cadena serán expandidas (sujetas a ciertas limitaciones de interpretación). Como en C y en Perl, el carácter de barra invertida ("\") se puede usar para especificar caracteres especiales:

Tabla 7-1. Caracteres protegidos

secuenciasignificado
\nNueva línea
\rRetorno de carro
\tTabulación horizontal
\\Barra invertida
\$Signo del dólar
\"Comillas dobles
\[0-7]{1,3} la secuencia de caracteres que coincida con la expresión regular es un carácter en notación octal
\x[0-9A-Fa-f]{1,2} la secuencia de caracteres que coincida con la expresión regular es un carácter en notación hexadecimal

Se puede proteger cualquier otro carácter, pero se producirá una advertencia en el nivel de depuración más alto.

La segunda forma de delimitar una cadena de caracteres usa el carácter de comilla simple ("'"). Cuando una cadena va encerrada entre comillas simples, los únicos caracteres de escape que serán comprendidos son "\\" y "\'". Esto es por convenio, así que se pueden tener comillas simples y barras invertidas en una cadena entre comillas simples. Las variables no se expandirán dentro de una cadena entre comillas simples.

Otra forma de delimitar cadenas es usando la sintaxis de documento incrustado ("<<<"). Se debe proporcionar un identificador después de <<<, después la cadena, y después el mismo identificador para cerrar el entrecomillado.

Ejemplo 7-1. He aquí un ejemplo de entrecomillado de cadenas con sintaxis de documento incrustado

$str = <<<EOD
Ejemplo de cadena
Expandiendo múltiples líneas
usando sintaxis de documento incrustado.
EOD;

Nota: La sintaxis de documento incristado fue añadida en PHP 4.

Las cadenas se pueden concatenar usando el operador '.' (punto). Nótese que el operador '+' (suma) no sirve para esto. Por favor mire Operadores de cadena para más información.

Se puede acceder a los caracteres dentro de una cadena tratándola como un array de caracteres indexado numéricamente, usando una sintaxis similar a la de C. Vea un ejemplo más abajo.

Ejemplo 7-2. Algumos ejemplos de cadenas

<?php
/* Asignando una cadena. */
$str = "Esto es una cadena";

/* Añadiendo a la cadena. */
$str = $str . " con algo más de texto";

/* Otra forma de añadir, incluye un carácter de nueva línea protegido. */
$str .= " Y un carácter de nueva línea al final.\n";

/* Esta cadena terminará siendo '<p>Número: 9</p>' */
$num = 9;
$str = "<p>Número: $num</p>";

/* Esta será '<p>Número: $num</p>' */
$num = 9;
$str = '<p>Número: $num</p>';

/* Obtener el primer carácter de una cadena  */
$str = 'Esto es una prueba.';
$first = $str[0];

/* Obtener el último carácter de una cadena. */
$str = 'Esto es aún una prueba.';
$last = $str[strlen($str)-1];
?>


Conversión de cadenas

Cuando una cadena se evalúa como un valor numérico, el valor resultante y el tipo se determinan como sigue.

La cadena se evaluará como un doble si contiene cualquiera de los caracteres '.', 'e', o 'E'. En caso contrario, se evaluará como un entero.

El valor viene dado por la porción inicial de la cadena. Si la cadena comienza con datos de valor numérico, este será el valor usado. En caso contrario, el valor será 0 (cero). Los datos numéricos válidos son un signo opcional, seguido por uno o más dígitos (que opcionalmente contengan un punto decimal), seguidos por un exponente opcional. El exponente es una 'e' o una 'E' seguidos por uno o más dígitos.

Cuando la primera expresión es una cadena, el tipo de la variable dependerá de la segunda expresión.

$foo = 1 + "10.5";              // $foo es doble (11.5)
$foo = 1 + "-1.3e3";            // $foo es doble (-1299)
$foo = 1 + "bob-1.3e3";         // $foo es entero (1)
$foo = 1 + "bob3";              // $foo es entero (1)
$foo = 1 + "10 Cerditos";     // $foo es entero (11)
$foo = 1 + "10 Cerditos"; // $foo es entero (11)
$foo = "10.0 cerdos " + 1;        // $foo es entero (11)
$foo = "10.0 cerdos " + 1.0;      // $foo es double (11)

Para más información sobre esta conversión, mire en la página del manual de Unix strtod(3).

Si quisiera probar cualquiera de los ejemplos de esta sección, puede cortar y pegar los ejemplos e insertar la siguiente línea para ver por sí mismo lo que va ocurriendo:

echo "\$foo==$foo; el tipo es " . gettype( $foo ) . "<br>\n";


Arrays

Los arrays actualmente actúan tanto como tablas hash (arrays asociativos) como arrays indexados (vectores).


Arrays unidimensionales

PHP soporta tanto arrays escalares como asociativos. De hecho, no hay diferencias entre los dos. Se puede crear una array usando las funciones list() o array(), o se puede asignar el valor de cada elemento del array de manera explícita.

$a[0] = "abc"; 
$a[1] = "def"; 
$b["foo"] = 13;

También se puede crear un array simplemente añadiendo valores al array. Cuando se asigna un valor a una variable array usando corchetes vacíos, el valor se añadirá al final del array.

$a[] = "hola"; // $a[2] == "hola"
$a[] = "mundo"; // $a[3] == "mundo"

Los arrays se pueden ordenar usando las funciones asort(), arsort(), ksort(), rsort(), sort(), uasort(), usort(), y uksort() dependiendo del tipo de ordenación que se desee.

Se puede contar el número de elementos de un array usando la función count().

Se puede recorrer un array usando las funciones next() y prev(). Otra forma habitual de recorrer un array es usando la función each().


Arrays Multidimensionales

Los arrays multidimensionales son bastante simples actualmente. Para cada dimensión del array, se puede añadir otro valor [clave] al final:

$a[1]      = $f;           # ejemplos de una sola dimensión
$a["foo"]  = $f;   

$a[1][0]     = $f;         # bidimensional
$a["foo"][2] = $f;         # (se pueden mezclar índices numéricos y asociativos)
$a[3]["bar"] = $f;         # (se pueden mezclar índices numéricos y asociativos)

$a["foo"][4]["bar"][0] = $f;   # tetradimensional!

En PHP3 no es posible referirse a arrays multidimensionales directamente dentro de cadenas. Por ejemplo, lo siguiente no tendrá el resultado deseado:

$a[3]['bar'] = 'Bob';
echo "Esto no va a funcionar: $a[3][bar]";

En PHP3, lo anterior tendrá la salida Esto no va a funcionar: Array[bar]. De todas formas, el operador de concatenación de cadenas se puede usar para solucionar esto:

$a[3]['bar'] = 'Bob';
echo "Esto no va a funcionar: " . $a[3][bar];

En PHP4, sin embargo, todo el problema se puede circunvenir encerrando la referencia al array (dentro de la cadena) entre llaves:

$a[3]['bar'] = 'Bob';
echo "Esto va a funcionar: {$a[3][bar]}";

Se pueden "rellenar" arrays multidimensionales de muchas formas, pero la más difícil de comprender es cómo usar el comando array() para arrays asociativos. Estos dos trozos de código rellenarán el array unidimensional de la misma manera:

# Ejemplo 1:

$a["color"]	= "rojo";
$a["sabor"]	= "dulce";
$a["forma"]	= "redondeada";
$a["nombre"]	= "manzana";
$a[3]		= 4;

# Example 2:
$a = array(
     "color" => "rojo",
     "sabor" => "dulce",
     "forma" => "redondeada",
     "nombre"  => "manzana",
     3       => 4
);

La función array() se puede anidar para arrays multidimensionales:

<?
$a = array(
     "manzana"  => array(
          "color"  => "rojo",
          "sabor"  => "dulce",
          "forma"  => "redondeada"
     ),
     "naranja"  => array(
          "color"  => "naranja",
          "sabor"  => "ácido",
          "forma"  => "redondeada"
     ),
     "plátano"  => array(
          "color"  => "amarillo",
          "sabor"  => "paste-y",
          "forma"  => "aplatanada"
     )
);

echo $a["manzana"]["sabor"];    # devolverá "dulce"
?>


Objetos

Inicialización de Objetos

Para inicializar un objeto, se usa la sentencia new para instanciar el objeto a una variable.

class foo {
    function do_foo () { 
        echo "Doing foo."; 
    }
}

$bar = new foo;
$bar->do_foo();


Type juggling

PHP no requiere (o soporta) la declaración explícita del tipo en la declaración de variables; el tipo de una variable se determina por el contexto en el que se usa esa variable. Esto quiere decir que si se asigna un valor de cadena a la variable var, var se convierte en una cadena. Si después se asigna un valor entero a la variable var, se convierte en una variable entera.

Un ejemplo de conversión de tipo automática en PHP3 es el operador suma '+'. Si cualquiera de los operandos es un doble, entonces todos los operandos se evalúan como dobles, y el resultado será un doble. En caso contrario, los operandos se interpretarán como enteros, y el resultado será también un entero. Nótese que esto NO cambia los tipos de los operandos propiamente dichos; el único cambio está en cómo se evalúan los operandos.

$foo = "0";  // $foo es una cadena (ASCII 48)
$foo++;      // $foo es la cadena "1" (ASCII 49)
$foo += 1;   // $foo ahora es un entero (2)
$foo = $foo + 1.3;  // $foo ahora es un doble (3.3)
$foo = 5 + "10 Cerditos Pequeñitos"; // $foo es entero (15)
$foo = 5 + "10 Cerditos";     // $foo es entero (15)

Si los últimos dos ejemplos anteriores parecen confusos, vea Conversión de cadenas.

Si se desea obligar a que una variable sea evaluada con un tipo concreto, mire la sección Forzado de tipos. Si se desea cambiar el tipo de una variable, vea la función settype().

Si quisiese probar cualquiera de los ejemplos de esta sección, puede cortar y pegar los ejemplos e insertar la siguiente línea para ver por sí mismo lo que va ocurriendo:

echo "\$foo==$foo; el tipo es " . gettype( $foo ) . "<br>\n";

Nota: La posibilidad de una conversión automática a array no está definida actualmente.

$a = 1;       // $a es un entero
$a[0] = "f";  // $a se convierte en un array, en el que $a[0] vale "f"

Aunque el ejemplo anterior puede parecer que claramente debería resultar en que $a se convierta en un array, el primer elemento del cual es 'f', consideremos esto:

$a = "1";     // $a es una cadena
$a[0] = "f";  // ¿Qué pasa con los índices de las cadenas? ¿Qué ocurre?

Dado que PHP soporta indexación en las cadenas vía offsets usando la misma sintaxis que la indexación de arrays, el ejemplo anterior nos conduce a un problema: ¿debería convertirse $a en un array cuyo primer elemento sea "f", o debería convertirse "f" en el primer carácter de la cadena $a?

Por esta razón, tanto en PHP 3.0.12 como en PHP 4.0b3-RC4, el resultado de esta conversión automática se considera que no está definido. Los parches se están discutiendo, de todas formas.


Forzado de tipos

El forzado de tipos en PHP funciona como en C: el nombre del tipo deseado se escribe entre paréntesis antes de la variable a la que se pretende forzar.

$foo = 10;   // $foo es un entero
$bar = (double) $foo;   // $bar es un doble

Los forzados de tipo permitidos son:

  • (int), (integer) - fuerza a entero (integer)

  • (real), (double), (float) - fuerza a doble (double)

  • (string) - fuerza a cadena (string)

  • (array) - fuerza a array (array)

  • (object) - fuerza a objeto (object)

Nótese que las tabulaciones y espacios se permiten dentro de los paréntesis, así que los siguientes ejemplos son funcionalmente equivalentes:

$foo = (int) $bar;
$foo = ( int ) $bar;

Puede no ser obvio que ocurrirá cuando se fuerce entre ciertos tipos. Por ejemplo, lo siguiente debería ser tenido en cuenta.

Cuando se fuerza el cambio de un escalar o una variable de cadena a un array, la variable se convertirá en el primer elemento del array:

$var = 'ciao';
$arr = (array) $var;
echo $arr[0];  // produce la salida 'ciao'

Cuando se fuerza el tipo de una variable escalar o de una cadena a un objeto, la variable se convertirá en un atributo del objeto; el nombre del atributo será 'scalar':

$var = 'ciao';
$obj = (object) $var;
echo $obj->scalar;  // produce la salida 'ciao'


Capítulo 8. Variables

Conceptos Básicos

En PHP las variables se representan como un signo de dólar seguido por el nombre de la variable. El nombre de la variable es sensible a minúsculas y mayúsculas.

$var = "Bob";
$Var = "Joe";
echo "$var, $Var"; // produce la salida "Bob, Joe"

En PHP3, las variables siempre se asignan por valor. Esto significa que cuando se asigna una expresión a una variable, el valor íntegro de la expresión original se copia en la variable de destino. Esto quiere decir que, por ejemplo, después e asignar el valor de una variable a otra, los cambios que se efectúen a una de esas variables no afectará a la otra. Para más información sobre este tipo de asignación, vea Expresiones.

PHP4 ofrece otra forma de asignar valores a las variables: asignar por referencia. Esto significa que la nueva variable simplemente referencia (en otras palabras, "se convierte en un alias de" o "apunta a") la variable original. Los cambios a la nueva variable afectan a la original, y viceversa. Esto también significa que no se produce una copia de valores; por tanto, la asignación ocurre más rápidamente. De cualquier forma, cualquier incremento de velocidad se notará sólo en los bucles críticos cuando se asignen grandes arrays u objetos.

Para asignar por referencia, simplemente se antepone un ampersand (&) al comienzo de la variable cuyo valor se está asignando (la variable fuente). Por ejemplo, el siguiente trozo de código produce la salida 'Mi nombre es Bob' dos veces:

<?php
$foo = 'Bob';              // Asigna el valor 'Bob' a $foo
$bar = &$foo;              // Referencia $foo vía $bar.
$bar = "Mi nombre es $bar";  // Modifica $bar...
echo $foo;                 // $foo también se modifica.
echo $bar;
?>

Algo importante a tener en cuenta es que sólo las variables con nombre pueden ser asignadas por referencia.

<?php
$foo = 25;
$bar = &$foo;      // Esta es una asignación válida.
$bar = &(24 * 7);  // Inválida; referencia una expresión sin nombre.

function test() {
   return 25;
}

$bar = &test();    // Inválida.
?>


Variables predefinidas

PHP proporciona una gran cantidad de variables predefinidas a cualquier script que se ejecute. De todas formas, muchas de esas variables no pueden estar completamente documentadas ya que dependen de sobre qué servidor se esté ejecutando, la versión y configuración de dicho servidor, y otros factores. Algunas de estas variables no estarán disponibles cuando se ejecute PHP desde la línea de comandos.

A pesar de estos factores, aquí tenemos una lista de variables predefinidas disponibles en una instalación por defecto de PHP 3 corriendo como modulo de un Apache 1.3.6 con su configuración también por defecto.

Para una lista de variables predefinidas (y muchas más información útil), por favor, vea (y use) phpinfo().

Nota: Esta lista no es exhaustiva ni pretende serlo. Simplemente es una guía de qué tipo de variables predefinidas se puede esperar tener disponibles en un script.


Variables de Apache

Estas variables son creadas por el servidor web Apache. Si se está utilizando otro servidor web, no hay garantía de que proporcione las mismas variables; pueden faltar algunas, o proporcionar otras no listadas aquí. Dicho esto, también están presentes las variables de la especificación CGI 1.1, por lo que también se deben tener en cuenta.

Tenga en cuenta que unas pocas, como mucho, de estas variables van a estar disponibles (o simplemente tener sentido) si se ejecuta PHP desde la línea de comandos.

GATEWAY_INTERFACE

Qué revisión de la especificación CGI está usando el servidor; por ejemplo 'CGI/1.1'.

SERVER_NAME

El nombre del equipo servidor en el que se está ejecutando el script. Si el script se está ejecutando en un servidor virtual, este será el valor definido para dicho servidor virtual.

SERVER_SOFTWARE

Una cadena de identificación del servidor, que aparece en las cabeceras al responderse a las peticiones.

SERVER_PROTOCOL

Nombre y revisión del protocolo a través del que se solicitó la página; p.ej. 'HTTP/1.0';

REQUEST_METHOD

Qué método de petición se usó para acceder a la página; p.ej. 'GET', 'HEAD', 'POST', 'PUT'.

QUERY_STRING

La cadena de la petición, si la hubo, mediante la que se accedió a la página.

DOCUMENT_ROOT

El directorio raíz del documento bajo el que se ejecuta el script, tal y como está definido en el fichero de configuración del servidor.

HTTP_ACCEPT

Los contenidos de la cabecera Accept: de la petición actual, si hay alguna.

HTTP_ACCEPT_CHARSET

Los contenidos de la cabecera Accept-Charset: de la petición actual, si hay alguna. Por ejemplo: 'iso-8859-1,*,utf-8'.

HTTP_ACCEPT_ENCODING

Los contenidos de la cabecera Accept-Encoding: de la petición actual, si la hay. Por ejemplo: 'gzip'.

HTTP_ACCEPT_LANGUAGE

Los contenidos de la cabecera Accept-Language: de la petición actual, si hay alguna. Por ejemplo: 'en'.

HTTP_CONNECTION

Los contenidos de la cabecera Connection: de la petición actual, si hay alguna. Por ejemplo: 'Keep-Alive'.

HTTP_HOST

Los contenidos de la cabecera Host: de la petición actual, si hay alguna.

HTTP_REFERER

La dirección de la página (si la hay) desde la que el navegador saltó a la página actual. Esto lo establece el navegador del usuario; no todos los navegadores lo hacen.

HTTP_USER_AGENT

Los contenidos de la cabecera User_Agent: de la petición actual, si hay alguna. Indica el navegador que se está utilizando para ver la página actual; p.ej. Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Entre otras cosas, se puede usar este valor con get_browser() para adaptar la funcionalidad de la página a las posibilidades del navegador del usuario.

REMOTE_ADDR

La dirección IP desde la que el usuario está viendo la página actual.

REMOTE_PORT

El puerto que se está utilizando en la máquina del usuario para comunicarse con el servidor web.

SCRIPT_FILENAME

La vía de acceso absoluta del script que se está ejecutando.

SERVER_ADMIN

El valor que se haya dado a la directiva SERVER_ADMIN (en Apache) en el fichero de configuración del servidor web. Si el script se está ejecutando en un servidor virtual, será el valor definido para dicho servidor virtual.

SERVER_PORT

El puerto del equipo servidor que está usando el servidor web para la comunicación. Para configuraciones por defecto, será '80'; al usar SSL, por ejemplo, cambiará al puerto que se haya definido como seguro para HTTP.

SERVER_SIGNATURE

Una cadena que contiene la versión del servidor y el nombre del servidor virtual que es añadida a las páginas generadas por el servidor, si está característica está activa.

PATH_TRANSLATED

Vía de acceso basada en el sistema de ficheros- (no el directorio raíz del documento-) del script en cuestión, después de que el servidor haya hecho la conversión virtual-a-real.

SCRIPT_NAME

Contiene la vía de acceso del script actual. Es útil para páginas que necesitan apuntar a sí mismas.

REQUEST_URI

La URI que se dió para acceder a esta página; por ejemplo, '/index.html'.


Variables de entorno

Estas variables se importan en el espacio de nombres global de PHP desde el entorno en el que se esté ejecutando el intérprete PHP. Muchas son proporcionadas por el intérprete de comandos en el que se está ejecutando PHP, y dado que a sistemas diferentes les gusta ejecutar diferentes tipos de intérpretes de comandos, es imposible hacer una lista definitiva. Por favor, mire la documentación de su intérprete de comandos para ver una lista de las variables de entorno definidas.

Otras variables de entorno son las de CGI, que están ahí sin importar si PHP se está ejecutando como un módulo del servidor o como un intérprete CGI.


Variables de PHP

Estas variables son creadas por el propio PHP.

argv

Array de argumentos pasados al script. Cuando el script se ejecuta desde la línea de comandos, esto da un acceso, al estilo de C, a los parámetros pasados en línea de comandos. Cuando se le llama mediante el método GET, contendrá la cadena de la petición.

argc

Contiene el número de parámetros de la línea de comandos pasados al script (si se ejecuta desde la línea de comandos).

PHP_SELF

El nombre del fichero que contiene el script que se esta ejecutando, relativo al directorio raíz de los documentos. Si PHP se está ejecutando como intérprete de línea de comandos, esta variable no está disponible.

HTTP_COOKIE_VARS

Un array asociativo de variables pasadas al script actual mediante cookies HTTP. Sólo está disponible si el seguimiento de variables ha sido activado mediante la directiva de configuración track_vars o la directiva <?php_track_vars?>.

HTTP_GET_VARS

Un array asociativo de variables pasadas al script actual mediante el método HTTP GET. Sólo está disponible si --variable tracking-- ha sido activado mediante la directiva de configuración track_vars o la directiva <?php_track_vars?>.

HTTP_POST_VARS

Un array asociativo de variables pasadas al script actual mediante el método HTTP POST. Sólo está disponible si --variable tracking-- ha sido activado mediante la directiva de configuración track_vars o la directiva <?php_track_vars?>.


Ambito de las variables

El ámbito de una variable es el contexto dentro del que la variable está definida. La mayor parte de las variables PHP sólo tienen un ámbito simple. Este ámbito simple también abarca los ficheros incluidos y los requeridos. Por ejemplo:

$a = 1;
include "b.inc";

Aquí, la variable $a dentro del script incluido b.inc. De todas formas, dentro de las funciones definidas por el usuario aparece un ámbito local a la función. Cualquier variables que se use dentro de una función está, por defecto, limitada al ámbito local de la función. Por ejemplo:

$a = 1; /* ámbito global */ 

Function Test () { 
    echo $a; /* referencia a una variable de ámbito local */ 
} 

Test ();

Este script no producirá salida, ya que la orden echo utiliza una versión local de la variable $a, a la que no se ha asignado ningún valor en su ámbito. Puede que usted note que hay una pequeña diferencia con el lenguaje C, en el que las variables globales están disponibles automáticamente dentro de la función a menos que sean expresamente sobreescritas por una definición local. Esto puede causar algunos problemas, ya que la gente puede cambiar variables globales inadvertidamente. En PHP, las variables globales deben ser declaradas globales dentro de la función si van a ser utilizadas dentro de dicha función. Veamos un ejemplo:

$a = 1;
$b = 2;

Function Sum () {
    global $a, $b;

    $b = $a + $b;
} 

Sum ();
echo $b;

El script anterior producirá la salida "3". Al declarar $a y $b globales dentro de la función, todas las referencias a tales variables se referirán a la versión global. No hay límite al número de variables globales que se pueden manipular dentro de una función.

Un segundo método para acceder a las variables desde un ámbito global es usando el array $GLOBALS propio de PHP3. El ejemplo anterior se puede reescribir así:

$a = 1;
$b = 2;

Function Sum () {
    $GLOBALS["b"] = $GLOBALS["a"] + $GLOBALS["b"];
} 

Sum ();
echo $b;

El array $GLOBALS es un array asociativo con el nombre de la variable global como clave y los contenidos de dicha variable como el valor del elemento del array.

Otra característica importante del ámbito de las variables es la variable static. Una variable estática existe sólo en el ámbito local de la función, pero no pierde su valor cuando la ejecución del programa abandona este ámbito. Consideremos el siguiente ejemplo:

Function Test () {
    $a = 0;
    echo $a;
    $a++;
}

Esta función tiene poca utilidad ya que cada vez que es llamada asigna a $a el valor 0 y representa un "0". La sentencia $a++, que incrementa la variable, no sirve para nada, ya que en cuanto la función termina la variable $a desaparece. Para hacer una función útil para contar, que no pierda la pista del valor actual del conteo, la variable $a debe declararse como estática:

Function Test () {
    static $a = 0;
    echo $a;
    $a++;
}

Ahora, cada vez que se llame a la función Test(), se representará el valor de $a y se incrementará.

Las variables estáticas también proporcionan una forma de manejar funciones recursivas. Una función recursiva es la que se llama a sí misma. Se debe tener cuidado al escribir una función recursiva, ya que puede ocurrir que se llame a sí misma indefinidamente. Hay que asegurarse de implementar una forma adecuada de terminar la recursión. La siguiente función cuenta recursivamente hasta 10, usando la variable estática $count para saber cuándo parar:

Function Test () {
    static $count = 0;

    $count++;
    echo $count;
    if ($count < 10) {
        Test ();
    }
    $count--;
}


Variables variables

A veces es conveniente tener nombres de variables variables. Dicho de otro modo, son nombres de variables que se pueden establecer y usar dinámicamente. Una variable normal se establece con una sentencia como:

$a = "hello";

Una variable variable toma el valor de una variable y lo trata como el nombre de una variable. En el ejemplo anterior, hello, se puede usar como el nombre de una variable utilizando dos signos de dólar. p.ej.

$$a = "world";

En este momento se han definido y almacenado dos variables en el árbol de símbolos de PHP: $a, que contiene "hello", y $hello, que contiene "world". Es más, esta sentencia:

echo "$a ${$a}";

produce el mismo resultado que:

echo "$a $hello";

p.ej. ambas producen el resultado: hello world.

Para usar variables variables con arrays, hay que resolver un problema de ambigüedad. Si se escribe $$a[1] el intérprete necesita saber si nos referimos a utilizar $a[1] como una variable, o si se pretendía utilizar $$a como variable y el índice [1] como índice de dicha variable. La sintaxis para resolver esta ambiguedad es: ${$a[1]} para el primer caso y ${$a}[1] para el segundo.


Variables externas a PHP

Formularios HTML (GET y POST)

Cuando se envía un formulario a un script PHP, las variables de dicho formulario pasan a estar automáticamente disponibles en el script gracias a PHP. Por ejemplo, consideremos el siguiente formulario:

Ejemplo 8-1. Variables de formulario simples

<form action="foo.php3" method="post">
    Name: <input type="text" name="name"><br>
    <input type="submit">
</form>

Cuando es enviado, PHP creará la variable $name, que contendrá lo que sea que se introdujo en el campo Name: del formulario.

PHP también maneja arrays en el contexto de variables de formularios, pero sólo en una dimensión. Se puede, por ejemplo, agrupar juntas variables relacionadas, o usar esta característica para recuperar valores de un campo select input múltiple:

Ejemplo 8-2. Variables de formulario más complejas

<form action="array.php" method="post">
    Name: <input type="text" name="personal[name]"><br>
    Email: <input type="text" name="personal[email]"><br>
    Beer: <br>
    <select multiple name="beer[]">
        <option value="warthog">Warthog
        <option value="guinness">Guinness
        <option value="stuttgarter">Stuttgarter Schwabenbräu
        </select>
    <input type="submit">
</form>

Si la posibilidad de PHP de track_vars está activada, ya sea mediante la opción de configuración track_vars o mediante la directiva <?php_track_vars?>, las variables enviadas con los métodos POST o GET también se encontrarán en los arrays asociativos globales $HTTP_POST_VARS y $HTTP_GET_VARS.


IMAGE SUBMIT variable names

Cuando se envía un formulario, es posible usar una imagen en vez del botón submit estándar con una etiqueta como:

<input type=image src="image.gif" name="sub">

Cuando el usuario hace click en cualquier parte de la imagen, el formulario que la acompaña se transmitirá al servidor con dos variables adicionales, sub_x y sub_y. Estas contienen las coordenadas del click del usuario dentro de la imagen. Los más experimentados puede notar que los nombres de variable enviados por el navegador contienen un guión en vez de un subrayado (guión bajo), pero PHP convierte el guión en subrayado automáticamente.


Cookies HTTP

PHP soporta cookies de HTTP de forma transparente tal y como están definidas en en las Netscape's Spec. Las cookies son un mecanismo para almacenar datos en el navegador y así rastrear o identificar a usuarios que vuelven. Se pueden crear cookies usando la función SetCookie(). Las cookies son parte de la cabecera HTTP, así que se debe llamar a la función SetCookie antes de que se envíe cualquier salida al navegador. Es la misma restricción que para la función header(). Cualquier cookie que se reciba procedente del cliente será convertida automáticamente en una variable de PHP como con los datos en los métodos GET y POST.

Si se quieren asignar múltiples valores a una sola cookie, basta con añadir [] al nombre de la. Por ejemplo:

SetCookie ("MyCookie[]", "Testing", time()+3600);

Nótese que una cookie reemplazará a una cookie anterior que tuviese el mismo nombre en el navegador a menos que el camino (path) o el dominio fuesen diferentes. Así, para una aplicación de carro de la compra se podría querer mantener un contador e ir pasándolo. P.ej.

Ejemplo 8-3. SetCookie Example

$Count++;
SetCookie ("Count", $Count, time()+3600);
SetCookie ("Cart[$Count]", $item, time()+3600);

Variables de entorno

PHP hace accesibles las variables de entorno automáticamente tratándolas como variables normales.

echo $HOME;  /* Shows the HOME environment variable, if set. */

Dado que la información que llega vía mecanismos GET, POST y Cookie crean automáticamente variables de PHP, algunas veces es mejor leer variables del entorno explícitamente para asegurarse de que se está trabajando con la versión correcta. La función getenv() se puede usar para ello. También se puede asignar un valor a una variable de entorno con la función putenv().


Puntos en los nombres de variables de entrada

Típicamente, PHP no altera los nombres de las variables cuando se pasan a un script. De todas formas, hay que notar que el punto no es un carácter válido en el nombre de una variable PHP. Por esta razón, mire esto:
$varname.ext;  /* nombre de variable no válido */
Lo que el intérprete ve es el nombre de una variable $varname, seguido por el operador de concatenación, y seguido por la prueba (es decir, una cadena sin entrecomillar que no coincide con ninguna palabra clave o reservada conocida) 'ext'. Obviamente, no se pretendía que fuese este el resultado.

Por esta razón, es importante hacer notar que PHP reemplazará automáticamente cualquier punto en los nombres de variables de entrada por guiones bajos (subrayados).


Determinando los tipos de variables

Dado que PHP determina los tipos de las variables y los convierte (generalmente) según necesita, no siempre resulta obvio de qué tipo es una variable dada en un momento concreto. PHP incluye varias funciones que descubren de qué tipo es una variable. Son gettype(), is_long(), is_double(), is_string(), is_array(), y is_object().


Capítulo 9. Constantes

Una constante es un identificador para expresar un valor simple. Como el nombre sugiere, este valor no puede variar durante la ejecución del script. (Las constantes especiales __FILE__ y __LINE__ son una excepción a esto, ya que actualmente no lo soin). Una constante es sensible a mayúsculas por defecto. Por convención, los identificadores de constantes suelen declararse en mayúsculas

El nombre de una constante sigue las mismas reglas que cualquier etiqueta en PHP. Un nombre de constante válido empieza con una letra o un caracter de subrayado, seguido por cualquier número de letras, números, o subrayados. Se podrían expresar mediante la siguiente expresión regular: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

Nota: Para nuestros propósitos , entenderemos como letra los carácteres a-z, A-Z, y los ASCII del 127 hasta el 255 (0x7f-0xff).

El alcanze de una constante es global, Es decir, es posible acceder a ellas sin preocuparse por el ámbito de alcance.


Sintaxis

Se puede definir una constante usando la función define(). Una vez definida, no puede ser modificada ni eliminada .

Solo se puede definir como constantes valores escalares (boolean, integer, float y string ).

Para obtener el valor de una constante solo es necesario especificar su nombre. A diferencia de las variables, no se tiene que especificar el prefijo $. Tambien se puede utilizar la función constant(), para obtener el valor de una constante, en el caso de que queramos expresarla de forma dinámica Usa la función get_defined_constants() parar obtener una lista de todas las constantes definidas.

Nota: Las contantes y las variables (globales) se encuentran en un espacio de nombres distinto. Esto implica que por ejemplo TRUE y $TRUE son diferentes.

Si usas una constante todavia no definida, PHP asume que estás refiriéndote al nombre de la constante en si. Se lanzará un aviso si esto sucede. Usa la función defined() para comprobar la existencia de dicha constante.

Estas son las diferencias entre constantes y variables:

  • Las constantes no son precedidas por un símbolo de dolar ($)

  • Las contantes solo pueden ser definidas usando la función() define , nunca por simple asignación

  • Las constantes pueden ser definidas y accedidas sin tener en cuenta las reglas de alcanze del ámbito.

  • Las constantes no pueden ser redefinidas o eliminadas despues de establecerse; y

  • Las constantes solo puede albergar valores escalares

Ejemplo 9-1. Definiendo constantes

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // outputs "Hello world."
echo Constant; // outputs "Constant" and issues a notice.
?>


Constantes predefinidas

PHP ofrece un largo número de constantes predefinidas a cualquier script en ejecución. Muchas de estas constantes, sin embargo, son creadas por diferentes extensiones, y solo estarán presentes si dichas extensiones están disponibles, bien por carga dinámica o porque has sido compiladas.

Se puede encontrar una lista de constantes predefinidas en la seccion Constantes predefinidas.


Capítulo 10. Expresiones

Las expresiones son la piedra angular de PHP. En PHP, casi cualquier cosa que escribes es una expresión. La forma más simple y ajustada de definir una expresión es "cualquier cosa que tiene un valor".

Las formas más básicas de expresiones son las constantes y las variables. Cuando escribes "$a = 5", estás asignando '5' a $a. '5', obviamente, tiene el valor 5 o, en otras palabras '5' es una expresión con el valor 5 (en este caso, '5' es una constante entera).

Después de esta asignación, esperarás que el valor de $a sea 5 también, de manera que si escribes $b = $a, esperas que se comporte igual que si escribieses $b = 5. En otras palabras, $a es una expresión también con el valor 5. Si todo va bien, eso es exactamente lo que pasará.

Las funciones son un ejemplo algo más complejo de expresiones. Por ejemplo, considera la siguiente función:

function foo () {
    return 5;
}

Suponiendo que estés familiarizado con el concepto de funciones (si no lo estás échale un vistazo al capítulo sobre funciones), asumirás que teclear $c = foo() es esencialmente lo mismo que escribir $c = 5, y has acertado. Las funciones son expresiones que valen el valor que retornan. Como foo() devuelve 5, el valor de la expresión 'foo()' es 5. Normalmente las funciones no devuelven un valor fijo, sino que suele ser calculado.

Desde luego, los valores en PHP no se limitan a enteros, y lo más normal es que no lo sean. PHP soporta tres tipos escalares: enteros, punto flotante y cadenas (los tipos escalares son aquellos cuyos valores no pueden 'dividirse' en partes menores, no como los arrays, por ejemplo). PHP también soporta dos tipos compuestos (no escalares): arrays y objetos. Se puede asignar cada uno de estos tipos de valor a variables o bien retornarse de funciones, sin ningún tipo de limitación.

Hasta aquí, los usuarios de PHP/FI 2 no deberían haber notado ningún cambio. Sin embargo, PHP lleva las expresiones mucho más allá, al igual que otros lenguajes. PHP es un lenguaje orientado a expresiones, en el sentido de que casi todo es una expresión. Considera el ejemplo anterior '$a = 5'. Es sencillo ver que hay dos valores involucrados, el valor de la constante entera '5', y el valor de $a que está siendo actualizado también a 5. Pero la verdad es que hay un valor adicional implicado aquí, y es el valor de la propia asignación. La asignación misma se evalúa al valor asignado, en este caso 5. En la práctica, quiere decir que '$a = 5', independientemente de lo que hace, es una expresión con el valor 5. De esta manera, escribir algo como '$b = ($a = 5)' es como escribir '$a = 5; $b = 5;' (un punto y coma marca el final de una instrucción). Como las asignaciones se evalúan de derecha a izquierda, puedes escribir también '$b = $a = 5'.

Otro buen ejemplo de orientación a expresiones es el pre y post incremento y decremento. Los usuarios de PHP/FI 2 y los de otros muchos lenguajes les sonará la notación variable++ y variable--. Esto son las operaciones de incremento y decremento. En PHP/FI 2, la instrucción '$a++' no tiene valor (no es una expresión), y no puedes asignarla o usarla de ningún otro modo. PHP mejora las características del incremento/decremento haciéndolos también expresiones, como en C. En PHP, como en C, hay dos tipos de incremento - pre-incremento y post-incremento. Ambos, en esencia, incrementan la variable y el efecto en la variable es idéntico. La diferencia radica en el valor de la propia expresion incremento. El preincremento , escrito '++$variable', se evalúa al valor incrementado (PHP incrementa la variable antes de leer su valor, de ahí el nombre 'preincremento'). El postincremento, escrito '$variable++', se evalúa al valor original de $variable antes de realizar el incremento (PHP incrementa la variable después de leer su valor, de ahí el nombre 'postincremento').

Un tipo muy corriente de expresiones son las expresiones de comparación. Estas expresiones se evalúan a 0 o 1, significando FALSO (FALSE) o CIERTO (TRUE), respectivamente. PHP soporta > (mayor que), >= (mayor o igual que), == (igual que), != (distinto), < (menor que) y <= (menor o igual que). Estas expresiones se usan frecuentemente dentro de la ejecución condicional como la instrucción if.

El último tipo de expresiones que trataremos, es la combinación operador-asignación. Ya sabes que si quieres incrementar $a en 1, basta con escribir '$a++' o ++$a'. Pero qué pasa si quieres añadir más de 1, por ejemplo 3? Podrías escribir '$a++' múltiples veces, pero no es una forma de hacerlo ni eficiente ni cómoda. Una práctica mucho más corriente es escribir '$a = $a + 3'. '$a + 3' se evalúa al valor de $a más 3, y se asigna de nuevo a $a, lo que resulta en incrementar $a en 3. En PHP, como en otros lenguajes como C, puedes escribir esto de una forma más concisa, que con el tiempo será más clara y también fácil de entender. Añadir 3 al valor actual de $a se puede escribir como '$a += 3'. Esto quiere decir exactamente "toma el valor de $a, súmale 3, y asígnalo otra vez a $a". Además de ser más corto y claro, también resulta en una ejecución más rápida. El valor de '$a += 3', como el valor de una asignación normal y corriente, es el valor asignado. Ten en cuenta que NO es 3, sino el valor combinado de $a más 3 (ése es el valor asignado a $a). Cualquier operación binaria puede ser usada en forma de operador-asignación, por ejemplo '$a -= 5' (restar 5 del valor de $a), '$b *= 7' (multiplicar el valor de $b por 5), etc.

Hay otra expresión que puede parecer extraña si no la has visto en otros lenguaes, el operador condicional ternario:

$first ? $second : $third

Si el valor de la primera subexpresión es verdadero (distinto de cero), entonces se evalúa la segunda subexpresión, si no, se evalúa la tercera y ése es el valor.

El siguiente ejemplo te ayudará a comprender un poco mejor el pre y post incremento y las expresiones en general:

function double($i) {
    return $i*2;
}
$b = $a = 5;        /* asignar el valor cinco a las variables $a y $b */
$c = $a++;          /* postincremento, asignar el valor original de $a (5) a $c */
$e = $d = ++$b;     /* preincremento, asignar el valor incrementado de $b (6) a 
                       $d y a $e */

/* en este punto, tanto $d como $e son iguales a 6 */

$f = double($d++);  /* asignar el doble del valor de $d antes
                       del incremento, 2*6 = 12 a $f */
$g = double(++$e);  /* asignar el doble del valor de $e después
                       del incremento, 2*7 = 14 a $g */
$h = $g += 10;      /* primero, $g es incrementado en 10 y termina valiendo 24.
                       después el valor de la asignación (24) se asigna a $h, 
                       y $h también acaba valiendo 24. */

Al principio del capítulo hemos dicho que describiríamos los distintos tipos de instrucciones y, como prometimos, las expresiones pueden ser instrucciones. Sin embargo, no todas las expresiones son instrucciones. En este caso, una instrucción tiene la forma 'expr' ';', es decir, una expresión seguida de un punto y coma. En '$b=$a=5;', $a=5 es una expresión válida, pero no es una instrucción en sí misma. Por otro lado '$b=$a=5:' sí es una instrucción válida.

Una última cosa que vale la pena mencionar, es el valor booleano de las expresiones. En muchas ocasiones, principalmente en condicionales y bucles, no estás interesado en el valor exacto de la expresión, sino únicamente si es CIERTA (TRUE) o FALSA (FALSE) (PHP no tiene un tipo booleano específico). El valor de verdad de las expresiones en PHP se calcula de forma similar a perl. Cualquier valor numérico distinto de cero es CIERTO (TRUE), cero es FALSO (FALSE). Fíjate en que los valores negativos son distinto de cero y considerados CIERTO (TRUE)! La cadena vacía y la cadena "0" son FALSO (FALSE); todas las demás cadenas son TRUE. Con los tipos no escalares (arrays y objetos) - si el valor no contiene elementos se considera FALSO (FALSE), en caso contrario se considera CIERTO (TRUE).

PHP te brinda una completa y potente implementación de expresiones, y documentarla enteramente está más allá del objetivo de ete manual. Los ejemplos anteriores, deberían darte una buena idea de qué son las expresiones y cómo construir expresiones útiles. A lo largo del resto del manual, escribiremos expr para indicar una expresión PHP válida.


Capítulo 11. Operadores


Operadores Aritméticos

¿Recuerdas la aritmética básica del colegio? Pues estos operadores funcionan exactamente igual.

Tabla 11-1. Operadores Aritméticos

ejemplonombreresultado
$a + $bAdiciónSuma de $a y $b.
$a - $bSubstracciónDiferencia entre $a y $b.
$a * $bMultiplicaciónProducto de $a and $b.
$a / $bDivisiónCociente de $a entre $b.
$a % $bMóduloResto de $a dividido entre $b.

Operadores de Asignación

El operador básico de asignación es "=". A primera vista podrías pensar que es el operador de comparación "igual que". Pero no. Realmente significa que el operando de la izquierda toma el valor de la expresión a la derecha, (esto es, "toma el valor de").

El valor de una expresión de asignación es el propio valor asignado. Esto es, el valor de "$a = 3" es 3. Esto permite hacer cosas curiosas como

$a = ($b = 4) + 5; // ahora $a es igual a 9, y $b vale 4.

Además del operador básico de asignación, existen los "operadores combinados" para todas las operaciones aritméticas y de cadenas que sean binarias. Este operador combinado te permite, de una sola vez, usar una variable en una expresión y luego establecer el valor de esa variable al resultado de la expresión. Por ejemplo:

$a = 3;
$a += 5; // establece $a a 8, como si hubiésemos escrito: $a = $a + 5;
$b = "Hola ";
$b .= "Ahí!"; // establece $b a "Hola Ahí!", igual que si hiciésemos $b = $b . "Ahí!";

Fíjate en que la asignación realiza una nueva copia de la variable original (asignación por valor), por lo que cambios a la variable original no afectan a la copia. Esto puede tener interés si necesitas copiar algo como un array con muchos elementos dentro de un bucle que se repita muchas veces (cada vez se realizará una nueva copia del array). PHP4 soporta asignación por referencia, usando la sintaxis $var = &$othervar;, pero esto no es posible en PHP3. 'Asignación por referencia' quiere decir que ambas variables acabarán apuntando al mismo dato y que nada es realmente copiado.


Operadores Bit a bit

Los operadores bit a bit te permiten activar o desactivar bits individuales de un entero.

Tabla 11-2. Operadores Bit a bit

ejemplonombreresultado
$a & $bYSe activan los bits que están activos tanto en $a como $b.
$a | $bOSe activan los bits que están activos en $a o que lo están en $b.
$a ^ $bXor ("o exclusiva")Se activan los bits que están activos en $a o en $b pero no en ambos a la vez.
~ $aNoSe activan los bits que no están activos en $a.
$a << $bDesplazamiento a la izquierdaDesplaza los bits de $a, $b posiciones hacia la izquierda (por aritmética binaria, cada posición desplazada equivale a multiplicar por dos el valor de $a)
$a >> $bDesplazamiento a la derechaDesplaza los bits de $a, $b posiciones hacia la derecha (por aritmética binaria, cada posición desplazada equivale a dividir entre dos el valor de $a)

Operadores de Comparación

Los operadores de comparación, como su nombre indica, permiten comparar dos valores.

Tabla 11-3. Operadores de Comparación

ejemplonombreresultado
$a == $bIgualdadCierto si $a es igual a $b.
$a === $bIdentidadCierto si $a es igual a $b y si son del mismo tipo (sólo PHP4)
$a != $bDesigualdadCierto si $a no es igual a $b.
$a < $bMenor queCierto si $a es estrictamente menor que $b.
$a > $bMayor queCierto si $a es estrictamente mayor que $b.
$a <= $bMenor o igual queCierto si $a es menor o igual que $b.
$a >= $bMayor o igual queCierto si $a es mayor o igual que $b.

Otro operador condicional es el operador "?:" (o ternario), que funciona como en C y otros muchos lenguajes.

(expr1) ? (expr2) : (expr3);

La expresión toma el valor expr2 si expr1 se evalúa a cierto, y expr3 si expr1 se evalúa a falso.


Operador de ejecución

PHP soporta un operador de ejecución: el apóstrofe invertido (``). ¡Fíjate que no son apostrofes normales! PHP intentará ejecutar la instrucción contenida dentro de los apóstrofes invertidos como si fuera un comando del shell; y su salida devuelta como el valor de esta expresión (i.e., no tiene por qué ser simplemente volcada como salida; puede asignarse a una variable).

$output = `ls -al`;
echo "<pre>$output</pre>";

Ver también system(), passthru(), exec(), popen(), y escapeshellcmd().


Operadores de Incremento/decremento

PHP soporta los operadores de predecremento y post incremento al estilo de C.

Tabla 11-4. Operadores de Incremento/decremento

ejemplonombreefecto
++$aPreincrementoIncrementa $a en uno y después devuelve $a.
$a++PostincrementoDevuelve $a y después incrementa $a en uno.
--$aPredecrementoDecrementa $a en uno y después devuelve $a.
$a--PostdecrementoDevuelve $a y después decrementa $a en uno.

He aquí un listado de ejemplo:

<?php
echo "<h3>Postincremento</h3>";
$a = 5;
echo "Debería ser 5: " . $a++ . "<br>\n";
echo "Debería ser 6: " . $a . "<br>\n";

echo "<h3>Preincremento</h3>";
$a = 5;
echo "Debería ser 6: " . ++$a . "<br>\n";
echo "Debería ser 6: " . $a . "<br>\n";

echo "<h3>Postdecremento</h3>";
$a = 5;
echo "Debería ser 5: " . $a-- . "<br>\n";
echo "Debería ser 4: " . $a . "<br>\n";

echo "<h3>Predecremento</h3>";
$a = 5;
echo "Debería ser 4: " . --$a . "<br>\n";
echo "Debería ser 4: " . $a . "<br>\n";
?>


Operadores Lógicos

Tabla 11-5. Operadores Lógicos

ejemplonombreresultado
$a and $bYCierto si tanto $a como $b son ciertos.
$a or $bOCierto si $a o $b son ciertos.
$a xor $bO exclusivaCierto si $a es cierto o $b es cierto, pero no ambos a la vez.
! $aNegaciónCierto si $a no es cierto.
$a && $bYCierto si tanto $a como $b son ciertos.
$a || $bOCierto si $a o $b son ciertos.

La razón de las dos variaciones de "y" y "o" es que operan con distinta precedencia (ver Precedencia de Operadores.)


Precedencia de Operadores

La precedencia de operadores especifica cómo se agrupan las expresiones. Por ejemplo, en la expresión 1 + 5 * 3, la respuesta es 16 y no 18 porque el operador de multiplicación ("*") tiene una mayor precedencia que el de adición ("+").

La siguiente tabla lista la precedencia de operadores, indicándose primero los de menor precedencia.

Tabla 11-6. Precedencia de Operadores

AsociatividadOperadores
izquierda,
izquierdaor
izquierdaxor
izquierdaand
derechaprint
izquierda= += -= *= /= .= %= &= |= ^= ~= <<= >>=
izquierda? :
izquierda||
izquierda&&
izquierda|
izquierda^
izquierda&
no asociativo== != ===
no asociativo< <= > >=
izquierda<< >>
izquierda+ - .
izquierda* / %
derecha! ~ ++ -- (int) (double) (string) (array) (object) @
derecha[
no asociativonew


Operadores de Cadenas

Hay dos operadores de cadenas. El primero es el operador de concatenación ('.'), que devuelve el resultado de concatenar sus operandos izquierdo y derecho. El segundo es el operador de concatenación y asignación ('.='). Consulta Operadores de Asignación para más información.

$a = "Hola ";
$b = $a . "Mundo!"; // ahora $b contiene "Hola Mundo!"

$a = "Hola ";
$a .= "Mundo!"; // ahora $a contiene "Hola Mundo!"


Capítulo 12. Estructuras de Control

Todo archivo de comandos PHP se compone de una serie de sentencias. Una sentencia puede ser una asignación, una llamada a función, un bucle, una sentencia condicional e incluso una sentencia que no haga nada (una sentencia vacía). Las sentencias normalmente acaban con punto y coma. Además, las sentencias se pueden agrupar en grupos de sentencias encapsulando un grupo de sentencias con llaves. Un grupo de sentencias es también una sentencia. En este capítulo se describen los diferentes tipos de sentencias.


if

La construcción if es una de las más importantes características de muchos lenguajes, incluido PHP. Permite la ejecución condicional de fragmentos de código. PHP caracteriza una estructura if que es similar a la de C:

if (expr)
     sentencia

Como se describe en la sección sobre expresiones, expr se evalúa a su valor condicional. Si expr se evalúa como TRUE, PHP ejecutará la sentencia, y si se evalúa como FALSE - la ignorará.

El siguiente ejemplo mostraría a es mayor que b si $a fuera mayor que $b:

if ($a > $b)
     print "a es mayor que b";

A menudo, se desea tener más de una sentencia ejecutada de forma condicional. Por supuesto, no hay necesidad de encerrar cada sentencia con una cláusula if. En vez de eso, se pueden agrupar varias sentencias en un grupo de sentencias. Por ejemplo, este código mostraría a es mayor que b si $a fuera mayor que $b, y entonces asignaría el valor de $a a $b:

if ($a > $b) {
     print "a es mayor que b";
     $b = $a;
 }

Las sentencias if se pueden anidar indefinidamente dentro de otras sentencias if, lo cual proporciona una flexibilidad completa para ejecuciones condicionales en las diferentes partes de tu programa.


else

A menudo queremos ejecutar una sentencia si se cumple una cierta condicion, y una sentencia distinta si la condición no se cumple. Esto es para lo que sirve else. else extiende una sentencia if para ejecutar una sentencia en caso de que la expresión en la sentencia if se evalúe como FALSE. Por ejemplo, el siguiente código mostraría a es mayor que b si $a fuera mayor que $b, y a NO es mayor que b en cualquier otro caso:

if ($a > $b) {
     print "a es mayor que b";
 } else {
     print "a NO es mayor que b";
 }

La sentencia else se ejecuta solamente si la expresión if se evalúa como FALSE, y si hubiera alguna expresión elseif - sólo si se evaluaron también a FALSE (Ver elseif).


elseif

elseif, como su nombre sugiere, es una combinación de if y else. Como else, extiende una sentencia if para ejecutar una sentencia diferente en caso de que la expresión if original se evalúa como FALSE. No obstante, a diferencia de else, ejecutará esa expresión alternativa solamente si la expresión condicional elseif se evalúa como TRUE. Por ejemplo, el siguiente código mostraría a es mayor que b, a es igual a b o a es menor que b:

if ($a > $b) {
     print "a es mayor que b";
 } elseif ($a == $b) {
     print "a es igual que b";
 } else {
     print "a es mayor que b";
 }

Puede haber varios elseifs dentro de la misma sentencia if. La primera expresión elseif (si hay alguna) que se evalúe como TRUE se ejecutaría. En PHP, también se puede escribir 'else if' (con dos palabras) y el comportamiento sería idéntico al de un 'elseif' (una sola palabra). El significado sintáctico es ligeramente distinto (si estas familiarizado con C, es el mismo comportamiento) pero la línea básica es que ambos resultarían tener exactamente el mismo comportamiento.

La sentencia elseif se ejecuta sólo si la expresión if precedente y cualquier expresión elseif precedente se evalúan como FALSE, y la expresión elseif actual se evalúa como TRUE.


Sintaxis Alternativa de Estructuras de Control

PHP ofrece una sintaxis altenativa para alguna de sus estructuras de control; a saber, if, while, for, y switch. En cada caso, la forma básica de la sintaxis alternativa es cambiar abrir-llave por dos puntos (:) y cerrar-llave por endif;, endwhile;, endfor;, or endswitch;, respectivamente.

<?php if ($a==5): ?>
 A es igual a 5
 <?php endif; ?>

En el ejemplo de arriba, el bloque HTML "A = 5" se anida dentro de una sentencia if escrita en la sintaxis alternativa. El bloque HTML se mostraría solamente si $a fuera igual a 5.

La sintaxis alternativa se aplica a else y también a elseif. La siguiente es una estructura if con elseif y else en el formato alternativo:

if ($a == 5):
     print "a es igual a 5";
     print "...";
 elseif ($a == 6):
     print "a es igual a 6";
     print "!!!";
 else:
     print "a no es ni 5 ni 6";
 endif;

Mirar también while, for, e if para más ejemplos.


while

Los bucles while son los tipos de bucle más simples en PHP. Se comportan como su contrapartida en C. La forma básica de una sentencia while es:

while (expr) sentencia

El significado de una sentencia while es simple. Le dice a PHP que ejecute la(s) sentencia(s) anidada(s) repetidamente, mientras la expresión while se evalúe como TRUE. El valor de la expresión es comprobado cada vez al principio del bucle, así que incluso si este valor cambia durante la ejecución de la(s) sentencia(s) anidada(s), la ejecución no parará hasta el fin de la iteración (cada vez que PHP ejecuta las sentencias en el bucle es una iteración). A veces, si la expresión while se evalúa como FALSE desde el principio de todo, la(s) sentencia(s) anidada(s) no se ejecutarán ni siquiera una vez.

Como con la sentencia if, se pueden agrupar multiples sentencias dentro del mismo bucle while encerrando un grupo de sentencias con llaves, o usando la sintaxis alternativa:

while (expr): sentencia ... endwhile;

Los siguientes ejemplos son idénticos, y ambos imprimen números del 1 al 10:

/* ejemplo 1 */
 
 $i = 1;
 while ($i <= 10) {
     print $i++;  /* el valor impreso sería
                     $i antes del incremento
                     (post-incremento) */
 }
 
 /* ejemplo 2 */
 
 $i = 1;
 while ($i <= 10):
     print $i;
     $i++;
 endwhile;


do..while

Los bucles do..while son muy similares a los bucles while, excepto que las condiciones se comprueban al final de cada iteración en vez de al principio. La principal diferencia frente a los bucles regulares while es que se garantiza la ejecución de la primera iteración de un bucle do..while (la condición se comprueba sólo al final de la iteración), mientras que puede no ser necesariamente ejecutada con un bucle while regular (la condición se comprueba al principio de cada iteración, si esta se evalúa como FALSE desde el principio la ejecución del bucle finalizará inmediatamente).

Hay una sola sintaxis para los bucles do..while:

$i = 0;
 do {
     print $i;
 } while ($i>0);

El bucle de arriba se ejecutaría exactamente una sola vez, después de la primera iteración, cuando la condición se comprueba, se evalúa como FALSE ($i no es más grande que 0) y la ejecución del bucle finaliza.

Los usuarios avanzados de C pueden estar familiarizados con un uso distinto del bucle do..while, para permitir parar la ejecución en medio de los bloques de código, encapsulandolos con do..while(0), y usando la sentencia break. El siguiente fragmento de código demuestra esto:

do {
     if ($i < 5) {
         print "i no es lo suficientemente grande";
         break;
     }
     $i *= $factor;
     if ($i < $minimum_limit) {
         break;
     }
     print "i es correcto";
     ...procesa i...
 } while(0);

No se preocupes si no entiende esto completamente o en absoluto. Se pueden codificar archivos de comandos e incluso archivos de comandos potentes sin usar esta 'propiedad'.


for

Los bucles for son los bucles más complejos en PHP. Se comportan como su contrapartida en C. La sintaxis de un bucle for es:

for (expr1; expr2; expr3) sentencia

La primera expresión (expr1) se evalúa (ejecuta) incondicionalmente una vez al principio del bucle.

Al comienzo de cada iteración, se evalúa expr2 . Si se evalúa como TRUE, el bucle continúa y las sentencias anidadas se ejecutan. Si se evalúa como FALSE, la ejecución del bucle finaliza.

Al final de cada iteración, se evalúa (ejecuta) expr3.

Cada una de las expresiones puede estar vacía. Que expr2 esté vacía significa que el bucle debería correr indefinidamente (PHP implicitamente lo considera como TRUE, al igual que C). Esto puede que no sea tan inútil como se podría pensar, puesto que a menudo se quiere salir de un bucle usando una sentencia break condicional en vez de usar la condición de for.

Considera los siguientes ejemplos. Todos ellos muestran números del 1 al 10:

/* ejemplo 1 */
 
 for ($i = 1; $i <= 10; $i++) {
     print $i;
 }
 
 /* ejemplo 2 */
 
 for ($i = 1;;$i++) {
     if ($i > 10) {
         break;
     }
     print $i;
 }
 
 /* ejemplo 3 */
 
 $i = 1;
 for (;;) {
     if ($i > 10) {
         break;
     }
     print $i;
     $i++;
 }
 
 /* ejemplo 4 */
 
 for ($i = 1; $i <= 10; print $i, $i++) ;

Por supuesto, el primer ejemplo parece ser el mas elegante (o quizás el cuarto), pero uno puede descubrir que ser capaz de usar expresiones vacías en bucles for resulta útil en muchas ocasiones.

PHP también soporta la "sintaxis de dos puntos" alternativa para bucles for.

for (expr1; expr2; expr3): sentencia; ...; endfor;

Otros lenguajes poseen una sentencia foreach para traducir un array o una tabla hash. PHP3 no posee tal construcción; PHP4 sí (ver foreach). En PHP3, se puede combinar while con las funciones list() y each() para conseguir el mismo efecto. Mirar la documentación de estas funciones para ver un ejemplo.


foreach

PHP4 (PHP3 no) incluye una construcción foreach, tal como perl y algunos otros lenguajes. Esto simplemente da un modo fácil de iterar sobre arrays. Hay dos sintaxis; la segunda es una extensión menor, pero útil de la primera:

foreach(expresion_array as $value) sentencia
foreach(expresion_array as $key => $value) sentencia

La primera forma recorre el array dado por expresion_array. En cada iteración, el valor del elemento actual se asigna a $value y el puntero interno del array se avanza en una unidad (así en el siguiente paso, se estará mirando el elemento siguiente).

La segunda manera hace lo mismo, salvo que la clave del elemento actual será asignada a la variable $key en cada iteración.

Nota: Cuando foreach comienza su primera ejecución, el puntero interno a la lista (array) se reinicia automáticamente al primer elemento del array. Esto significa que no se necesita llamar a reset() antes de un bucle foreach.

Nota: Hay que tener en cuanta queforeach con una copia de la lista (array) especificada y no la lista en si, por ello el puntero de la lista no es modificado como en la construcción each.

Puede haber observado que las siguientes son funcionalidades idénticas:

reset( $arr );
while( list( , $value ) = each( $arr ) ) {
   echo "Valor: $value<br>\n";
}

foreach( $arr as $value ) {
   echo "Valor: $value<br>\n";
}

Las siguientes también son funcionalidades idénticas:

reset( $arr );
while( list( $key, $value ) = each( $arr ) ) {
   echo "Key: $key; Valor: $value<br>\n";
}

foreach( $arr as $key => $value ) {
   echo "Key: $key; Valor: $value<br>\n";
}

Algunos ejemplos más para demostrar su uso:

/* foreach ejemplo 1: sólo valor*/
$a = array(1, 2, 3, 17);

foreach($a as $v) {
   print "Valor actual de \$a: $v.\n";
}

/* foreach ejemplo 2: valor (con clave impresa para ilustrar) */
$a = array(1, 2, 3, 17);

$i = 0; /* sólo para propósitos demostrativos */

foreach($a as $v) {
   print "\$a[$i] => $k.\n";
}

/* foreach ejemplo 3: clave y valor */
$a = array(
   "uno" => 1,
   "dos" => 2,
   "tres" => 3,
   "diecisiete" => 17
);

foreach($a as $k => $v) {
   print "\$a[$k] => $v.\n";
}


break

break escapa de la estructuras de control iterante (bucle) actuales for, while, o switch.

break accepta un parámetro opcional, el cual determina cuantas estructuras de control hay que escapar.

$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

continue se usa dentro de la estructura del bucle para saltar el resto de la iteración actual del bucle y continuar la ejecución al comienzo de la siguiente iteración.

continue accepta un parámetro opcional, el cual determina cuantos niveles (bluces) hay que saltar antes de continuar con la ejecución.

while (list($key,$value) = each($arr)) {
     if ($key % 2) { // salta los miembros impares
         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";
}


switch

La sentencia switch es similar a una serie de sentencias IF en la misma expresión. En muchas ocasiones, se quiere comparar la misma variable (o expresión) con nuchos valores diferentes, y ejecutar una parte de código distinta dependiendo de a qué valor es igual. Para ello sirve la sentencia switch.

Los siguientes dos ejemplos son dos modos distintos de escribir la misma cosa, uno usa una serie de sentencias if, y el otro usa la sentencia switch:

if ($i == 0) {
     print "i es igual a 0";
 }
 if ($i == 1) {
     print "i es igual a 1";
 }
 if ($i == 2) {
     print "i es igual a 2";
 }
 
 switch ($i) {
     case 0:
         print "i es igual a 0";
         break;
     case 1:
         print "i es igual a 1";
         break;
     case 2:
         print "i es igual a 2";
         break;
 }

Es importante entender cómo se ejecuta la sentencia switch para evitar errores. La sentencia switch ejecuta línea por línea (realmente, sentencia a sentencia). Al comienzo, no se ejecuta código. Sólo cuando se encuentra una sentencia case con un valor que coincide con el valor de la expresión switch PHP comienza a ejecutar las sentencias. PHP continúa ejecutando las sentencias hasta el final del bloque switch, o la primera vez que vea una sentencia break. Si no se escribe una sentencia break al final de una lista de sentencias case, PHP seguirá ejecutando las sentencias del siguiente case. Por ejemplo:

switch ($i) {
     case 0:
         print "i es igual a 0";
     case 1:
         print "i es igual a 1";
     case 2:
         print "i es igual a 2";
 }

Aquí, si $i es igual a 0, ¡PHP ejecutaría todas las sentecias print! Si $i es igual a 1, PHP ejecutaría las últimas dos sentencias print y sólo si $i es igual a 2, se obtendría la conducta 'esperada' y solamente se mostraría 'i es igual a 2'. Así, es importante no olvidar las sentencias break (incluso aunque pueda querer evitar escribirlas intencionadamente en ciertas circunstancias).

En una sentencia switch, la condición se evalúa sólo una vez y el resultado se compara a cada sentencia case. En una sentencia elseif, la condición se evalúa otra vez. Si tu condición es más complicada que una comparación simple y/o está en un bucle estrecho, un switch puede ser más rápido.

La lista de sentencias de un case puede también estar vacía, lo cual simplemente pasa el control a la lista de sentencias del siguiente case.

switch ($i) {
     case 0:
     case 1:
     case 2:
         print "i es menor que 3, pero no negativo";
         break;
     case 3:
         print "i es 3";
 }

Un case especial es el default case. Este case coincide con todo lo que no coincidan los otros case. Por ejemplo:

switch ($i) {
     case 0:
         print "i es igual a 0";
         break;
     case 1:
         print "i es igual a 1";
         break;
     case 2:
         print "i es igual a 2";
         break;
     default:
         print "i no es igual a 0, 1 o 2";
 }

La expresión case puede ser cualquier expresión que se evalúe a un tipo simple, es decir, números enteros o de punto flotante y cadenas de texto. No se pueden usar aquí ni arrays ni objetos a menos que se conviertan a un tipo simple.

La sintaxis alternativa para las estructuras de control está también soportada con switch. Para más información, ver Sintaxis alternativa para estructuras de control.

switch ($i):
     case 0:
         print "i es igual 0";
         break;
     case 1:
         print "i es igual a 1";
         break;
     case 2:
         print "i es igual a 2";
         break;
     default:
         print "i no es igual a 0, 1 o 2";
 endswitch;


require()

La sentencia require() se sustituye a sí misma con el archivo especificado, tal y como funciona la directiva #include de C.

Un punto importante sobre su funcionamiento es que cuando un archivo se incluye con include() o se requiere con require()), el intérprete sale del modo PHP y entra en modo HTML al principio del archivo referenciado, y vuelve de nuevo al modo PHP al final. Por esta razón, cualquier código dentro del archivo referenciado que debiera ser ejecutado como código PHP debe ser encerrado dentro de etiquetas válidas de comienzo y fin de PHP.

require() no es en realidad una función de PHP; es más una construcción del lenguaje. Está sujeta a algunas reglas distintas de las de funciones. Por ejemplo, require() no esta sujeto a ninguna estructura de control contenedora. Por otro lado, no devuelve ningún valor; intentar leer un valor de retorno de una llamada a un require() resulta en un error del intérprete.

A diferencia de include(), require() siempre leerá el archivo referenciado, incluso si la línea en que está no se ejecuta nunca. Si se quiere incluir condicionalmente un archivo, se usa include(). La sentencia conditional no afecta a require(). No obstante, si la línea en la cual aparece el require() no se ejecuta, tampoco se ejecutará el código del archivo referenciado.

De forma similar, las estructuras de bucle no afectan la conducta de require(). Aunque el código contenido en el archivo referenciado está todavía sujeto al bucle, el propio require() sólo ocurre una vez.

Esto significa que no se puede poner una sentencia require() dentro de una estructura de bucle y esperar que incluya el contenido de un archivo distinto en cada iteración. Para hacer esto, usa una sentencia include().

require( 'header.inc' );

When a file is require()ed, the code it contains inherits the variable scope of the line on which the require() occurs. Any variables available at that line in the calling file will be available within the called file. If the require() 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.

If the require()ed file is called via HTTP using the fopen wrappers, and if the target server interprets the target file as PHP code, variables may be passed to the require()ed file using an URL request string as used with HTTP GET. This is not strictly speaking the same thing as require()ing 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.

/* This example assumes that someserver is configured to parse .php
 * files and not .txt files. Also, 'works' here means that the variables 
 * $varone and $vartwo are available within the require()ed file. */

/* Won't work; file.txt wasn't handled by someserver. */
require ("http://someserver/file.txt?varone=1&vartwo=2");

/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
 * on the local filesystem. */
require ("file.php?varone=1&vartwo=2");               

/* Works. */
require ("http://someserver/file.php?varone=1&vartwo=2"); 

$varone = 1;
$vartwo = 2;
require ("file.txt");  /* Works. */
require ("file.php");  /* Works. */

En PHP3, es posible ejecutar una sentencia return dentro de un archivo referenciado con require(), en tanto en cuanto esa sentencia aparezca en el ámbito global del archivo requerido (require()). No puede aparecer dentro de ningún bloque (lo que siginifica dentro de llaves({})). En PHP4, no obstante, esta capacidad ha sido desestimada. Si se necesita esta funcionalidad, véase include().

Ver tambien include(), require_once(), include_once(), readfile(), y virtual().


include()

La sentencia include() incluye y evalúa el archivo especificado.

Si "URL fopen wrappers" esta activada en PHP (como está en la configuración inicial), se puede especificar el fichero que se va a incluir usando una URL en vez de un fichero local (con su Path) Ver Ficheros remotos y fopen() para más información.

Un punto importante sobre su funcionamiento es que cuando un archivo se incluye con include() o se requiere con require(), el intérprete sale del modo PHP y entra en modo HTML al principio del archivo referenciado, y vuelve de nuevo al modo PHP al final. Por esta razón, cualquier código dentro del archivo referenciado que debiera ser ejecutado como código PHP debe ser encerrado dentro de etiquetas válidas de comienzo y fin de PHP.

Esto sucede cada vez que se encuentra la sentencia include(), así que se puede usar una sentencia include() dentro de una estructura de bucle para incluir un número de archivos diferentes.

$archivos = array ('primero.inc', 'segundo.inc', 'tercero.inc');
for ($i = 0; $i < count($archivos); $i++) {
    include $archivos[$i];
}

include() difiere de require() en que la sentencia include se re-evalúa cada vez que se encuentra (y sólo cuando está siendo ejecutada), mientras que la sentencia require() se reemplaza por el archivo referenciado cuando se encuentra por primera vez, se vaya a evaluar el contenido del archivo o no (por ejemplo, si está dentro de una sentencia if cuya condición evaluada es falsa).

Debido a que include() es una construcción especial del lenguaje, se debe encerrar dentro de un bloque de sentencias si está dentro de un bloque condicional.

/* Esto es ERRÓNEO y no funcionará como se desea. */
 
 if ($condicion)
     include($archivo);
 else
     include($otro);
 
 /* Esto es CORRECTO. */
 
 if ($condicion) {
     include($archivo);
 } else {
     include($otro);
 }

En ambos, PHP3 y PHP4, es posible ejecutar una sentencia return dentro de un archivo incluido con include(), para terminar el procesado de ese archivo y volver al archivo de comandos que lo llamó. Existen algunas diferencias en el modo en que esto funciona, no obstante. La primera es que en PHP3, return no puede aparecer dentro de un bloque a menos que sea un bloque de función, en el cual return se aplica a esa función y no al archivo completo. En PHP4, no obstante, esta restricción no existe. También, PHP4 permite devolver valores desde archivos incluidos con include(). Se puede capturar el valor de la llamada a include() como se haría con una función normal. Esto genera un error de intérprete en PHP3.

Ejemplo 12-1. include() en PHP3 y PHP4

Asumamos la existencia del siguiente archivo (llamado test.inc) en el mismo directorio que el archivo principal:
<?php
echo "Antes del return <br>\n";
if ( 1 ) {
   return 27;
}
echo "Después del return <br>\n";
?>

Asumamos que el archivo principal (main.html) contiene lo siguiente:
<?php
$retval = include( 'test.inc' );
echo "El archivo devolvió: '$retval'<br>\n";
?>

Cuando se llama a main.html en PHP3, generará un error del intérprete en la linea 2; no se puede capturar el valor de un include() en PHP3. En PHP4, no obstante, el resultado será:
Antes del return
El archivo devolvió: '27'

Ahora, asumamos que se ha modificado main.html para que contenga lo siguiente:
<?php
include( 'test.inc' );
echo "De vuelta en main.html<br>\n";
?>

En PHP4, la salida será:
Antes del return
De vuelta en main.html
No obstante, PHP3 dará la siguiente salida:
Antes del return
27De vuelta en main.html

Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5

El error del intérprete es resultado del hecho de que la sentencia return está encerrada en un bloque de no-función dentro de test.inc. Cuando el return se mueve fuera del bloque, la salida es:
Antes del return
27De vuelta en main.html

El '27' espúreo se debe al hecho de que PHP3 no soporta devolver valores con return desde archivos como ese.

When a file is include()ed, 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. 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.

If the include()ed file is called via HTTP using the fopen wrappers, and if the target server interprets the target file as PHP code, variables may be passed to the include()ed file using an URL request string as used with HTTP GET. This is not strictly speaking the same thing as include()ing 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.

/* This example assumes that someserver is configured to parse .php
 * files and not .txt files. Also, 'works' here means that the variables 
 * $varone and $vartwo are available within the include()ed file. */

/* Won't work; file.txt wasn't handled by someserver. */
include ("http://someserver/file.txt?varone=1&vartwo=2");

/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
 * on the local filesystem. */
include ("file.php?varone=1&vartwo=2");               

/* Works. */
include ("http://someserver/file.php?varone=1&vartwo=2"); 

$varone = 1;
$vartwo = 2;
include ("file.txt");  /* Works. */
include ("file.php");  /* Works. */

See also require(), require_once(), include_once(), readfile(), and virtual().


require_once()

The require_once() statement replaces itself with the specified file, much like the C preprocessor's #include works, and in that respect is similar to the require() statement. The main difference is that in an inclusion chain, the use of require_once() will assure that the code is added to your script only once, and avoid clashes with variable values or function names that can happen.

For example, if you create the following 2 include files utils.inc and foolib.inc

Ejemplo 12-2. utils.inc

<?php
define(PHPVERSION, floor(phpversion()));
echo "GLOBALS ARE NICE\n";
function goodTea() {
        return "Oolong tea tastes good!";
}
?>

Ejemplo 12-3. foolib.inc

<?php
require ("utils.inc");
function showVar($var) {
        if (PHPVERSION == 4) {
                print_r($var);
        } else {
                dump_var($var);
        }
}

// bunch of other functions ...
?>
And then you write a script cause_error_require.php

Ejemplo 12-4. cause_error_require.php

<?php
require("foolib.inc");
/* the following will generate an error */
require("utils.inc");
$foo = array("1",array("complex","quaternion"));
echo "this is requiring utils.inc again which is also\n";
echo "required in foolib.inc\n";
echo "Running goodTea: ".goodTea()."\n";
echo "Printing foo: \n";
showVar($foo);
?>
When you try running the latter one, the resulting ouptut will be (using PHP 4.01pl2):

GLOBALS ARE NICE
GLOBALS ARE NICE

Fatal error:  Cannot redeclare causeerror() in utils.inc on line 5

By modifying foolib.inc and cause_errror_require.php to use require_once() instead of require() and renaming the last one to avoid_error_require_once.php, we have:

Ejemplo 12-5. foolib.inc (fixed)

...
require_once("utils.inc");
function showVar($var) {
...

Ejemplo 12-6. avoid_error_require_once.php

...
require_once("foolib.inc");
require_once("utils.inc");
$foo = array("1",array("complex","quaternion"));
...
And when running the latter, the output will be (using PHP 4.0.1pl2):

GLOBALS ARE NICE
this is requiring globals.inc again which is also
required in foolib.inc
Running goodTea: Oolong tea tastes good!
Printing foo:
Array
(
    [0] => 1
    [1] => Array
        (
            [0] => complex
            [1] => quaternion
        )

)

Also note that, analogous to the behavior of the #include of the C preprocessor, this statement acts at "compile time", e.g. when the script is parsed and before it is executed, and should not be used for parts of the script that need to be inserted dynamically during its execution. You should use include_once() or include() for that purpose.

For more examples on using require_once() and include_once(), look at the PEAR code included in the latest PHP source code distributions.

See also: require(), include(), include_once(), get_required_files(), get_included_files(), readfile(), and virtual().


include_once()

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 important difference that if the code from a file has already been included, it will not be included again.

As mentioned in the require_once() description, the include_once() should be used in the cases in which 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.

See also: require(), include(), require_once(), get_required_files(), get_included_files(), readfile(), and virtual().


Capítulo 13. Funciones

Funciones definidas por el usuario

Una función se define con la siguiente sintaxis:

function foo ($arg_1, $arg_2, ..., $arg_n) {
    echo "Función de ejemplo.\n";
    return $retval;
}

Cualquier instrucción válida de PHP puede aparecer en el cuerpo de la función, incluso otras funiones y definiciones de clases.

En PHP3, las funciones deben definirse antes de que se referencien. En PHP4 no existe tal requerimiento.

PHP no soporta la sobrecarga de funciones, y tampoco es posible redefinir u ocultar funciones previamente declaradas.

PHP3 no soporta un número variable de parámetros, aunque sí soporta parámetros por defecto (ver Valores por defecto de de los parámetros para más información). PHP4 soporta ambos: ver Listas de longitud variable de parámetros y las referencias de las funciones func_num_args(), func_get_arg(), y func_get_args() para más información.


Parámetros de las funciones

La información puede suministrarse a las funciones mediante la lista de parámetros, una lista de variables y/o constantes separadas por comas.

PHP soporta pasar parámetros por valor (el comportamiento por defecto), por referencia, y parámetros por defecto. Listas de longitud variable de parámetros sólo están soportadas en PHP4 y posteriores; ver Listas de longitud variable de parámetros y la referencia de las funciones func_num_args(), func_get_arg(), y func_get_args() para más información. Un efecto similar puede conseguirse en PHP3 pasando un array de parámetros a la función:

function takes_array($input) {
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}


Pasar parámetros por referencia

Por defecto, los parámetros de una función se pasan por valor (de manera que si cambias el valor del argumento dentro de la función, no se ve modificado fuera de ella). Si deseas permitir a una función modificar sus parámetros, debes pasarlos por referencia.

Si quieres que un parámetro de una función siempre se pase por referencia, puedes anteponer un ampersand (&) al nombre del parámetro en la definición de la función:

function add_some_extra(&$string) {
    $string .= ' y algo más.';
}
$str = 'Esto es una cadena, ';
add_some_extra($str);
echo $str;    // Saca 'Esto es una cadena, y algo más.'

Si deseas pasar una variable por referencia a una función que no toma el parámetro por referencia por defecto, puedes anteponer un ampersand al nombre del parámetro en la llamada a la función:

function foo ($bar) {
    $bar .= ' y algo más.';
}
$str = 'Esto es una cadena, ';
foo ($str);
echo $str;    // Saca 'Esto es una cadena, '
foo (&$str);
echo $str;    // Saca 'Esto es una cadena, y algo más.'


Parámetros por defecto

Una función puede definir valores por defecto para los parámetros escalares estilo C++:

function makecoffee ($type = "cappucino") {
    return "Hacer una taza de $type.\n";
}
echo makecoffee ();
echo makecoffee ("espresso");

La salida del fragmento anterior es:
Hacer una taza de cappucino.
Hacer una taza de espresso.

El valor por defecto tiene que ser una expresión constante, y no una variable o miembro de una clase.

En PHP 4.0 también es posible especificar unset como parámetro por defecto. Esto significa que el argumento no tomará ningún valor en absoluto si el valor no es suministrado.

Destacar que cuando se usan parámetros por defecto, estos tienen que estar a la derecha de cualquier parámetro sin valor por defecto; de otra manera las cosas no funcionarán de la forma esperada. Considera el siguiente fragmento de código:

function makeyogurt ($type = "acidophilus", $flavour) {
    return "Haciendo un bol de $type $flavour.\n";
}
 
echo makeyogurt ("mora");   // No funcionará de la manera esperada

La salida del ejemplo anterior es:
Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
Haciendo un bol de mora.

Y ahora, compáralo con:

function makeyogurt ($flavour, $type = "acidophilus") {
    return "Haciendo un bol de $type $flavour.\n";
}
 
echo makeyogurt ("mora");   // funciona como se esperaba

La salida de este ejemplo es:
Haciendo un bol de acidophilus mora.


Lista de longitud variable de parámetros

PHP4 soporta las listas de longitud variable de parámetros en las funciones definidas por el usuario. Es realmente fácil, usando las funciones func_num_args(), func_get_arg(), y func_get_args().

No necesita de ninguna sintaxis especial, y las listas de parámetros pueden ser escritas en la llamada a la función y se comportarán de la manera esperada.


Devolver valores

Los valores se retornan usando la instrucción opcional return. Puede devolverse cualquier tipo de valor, incluyendo listas y objetos.

function square ($num) {
    return $num * $num;
}
echo square (4);   // saca '16'.

No puedes devolver múltiples valores desde una función, pero un efecto similar se puede conseguir devolviendo una lista.

function small_numbers() {
    return array (0, 1, 2);
}
list ($zero, $one, $two) = small_numbers();


old_function

La instrucción old_function permite declarar una función usando una sintaxis idéntica a la de PHP/FI2 (excepto que debes reemplazar 'function' por 'old_function').

Es una característica obsoleta, y debería ser usada únicamente por el conversor PHP/FI2->PHP3.

Aviso

Las funciones declaradas como old_function no pueden llamarse desde el código interno de PHP. Entre otras cosas, esto significa que no puedes usarlas en funciones como usort(), array_walk(), y register_shutdown_function(). Puedes solventar esta limitación escribiendo un "wrapper" (en PHP3 normal) que a su vez llame a la función declarada como old_function.


Funciones variable

PHP soporta el concepto de funciones variable, esto significa que si una variable tiene unos paréntesis añadidos al final, PHP buscará una función con el mismo nombre que la evaluación de la variable, e intentará ejecutarla. Entre otras cosas, esto te permite implementar retrollamadas (callbacks), tablas de funciones y demás.

Ejemplo 13-1. Ejemplo de función variable

<?php
function foo() {
    echo "Dentro de foo()<br>\n";
}

function bar( $arg = '' ) {
    echo "Dentro de bar(); el parámetro fue '$arg'.<br>\n";
}

$func = 'foo';
$func();
$func = 'bar';
$func( 'test' );
?>


Capítulo 14. Clases y Objetos

class

Una clase es una colección de variables y de funciones que acceden a esas variables. Una clase se define con la siguiente sintaxis:

<?php
class Cart {
    var $items;  // Items en nuestro carro de la compra
   
    // Añadir $num artículos de tipo $artnr al carro
 
    function add_item ($artnr, $num) {
        $this->items[$artnr] += $num;
    }
   
    // Sacar $num artículos del tipo $artnr del carro
 
    function remove_item ($artnr, $num) {
        if ($this->items[$artnr] > $num) {
            $this->items[$artnr] -= $num;
            return true;
        } else {
            return false;
        }   
    }
}
?>

El ejemplo define una clase llamada Cart que consiste en un array asociativo de artículos en el carro y dos funciones para meter y sacar ítems del carro

Las clases son tipos, es decir, son plantillas para variables. Tienes que crear una variable del tipo deseado con el operador new.

$cart = new Cart;
 $cart->add_item("10", 1);

Este ejemplo crea un objeto $cart de clase Cart. La función add_item() de ese objeto se llama para añadir un item del artículo número 10 al carro.

Las Clases pueden ser extensiones de otras clases. Las clases extendidas o derivadas tienen todas las variables y funciones de la clase base y lo que les añadas al extender la definición. La herencia múltiple no está soportada.

class Named_Cart extends Cart {
    var $owner;
  
    function set_owner ($name) {
        $this->owner = $name;
    }
}

Ese ejemplo define una clase Named_Cart (carro con nombre o dueño) que tiene todas las variables y funciones de Cart, y además añade la variable $owner y una función adicional set_owner(). Un carro con nombre se crea de la forma habitual y, una vez hecho, puedes acceder al propietario del carro. En los carros con nombre también puedes acceder a las funciones normales del carro:

$ncart = new Named_Cart;    // Creamos un carro con nombre
$ncart->set_owner ("kris"); // Nombramos el carro
print $ncart->owner;        // Imprimimos el nombre del propietario
$ncart->add_item ("10", 1); // Funcionalidad heredada de Cart

Entre funciones de una clase, la variable $this hace referencia al propio objeto. Tienes que usar $this->loquesea para acceder a una variable o función llamada loquesea del objeto actual.

Los constructores son funciones de una clase que se llaman automáticamente al crear una nueva instancia (objeto) de una clase. Una función se convierte en constructor cuando tiene el mismo nombre que la clase.

class Auto_Cart extends Cart {
    function Auto_Cart () {
        $this->add_item ("10", 1);
    }
}

Este ejemplo define una clase Auto_Cart que es un Cart junto con un constructor que inicializa el carro con un item del tipo de artículo "10" cada vez que se crea un nuevo Auto_Cart con "new". Los constructores también pueden recibir parámetros y estos parámetros pueden ser opcionales, lo que los hace más útiles.

class Constructor_Cart extends Cart {
    function Constructor_Cart ($item = "10", $num = 1) {
        $this->add_item ($item, $num);
    }
}
 
// Compramos las mismas cosas aburridas de siempre
 
$default_cart   = new Constructor_Cart;
 
// Compramos las cosas interesantes
 
$different_cart = new Constructor_Cart ("20", 17);

Atención

Para las clases derivadas, el constructor de la clase padre no es llamado automáticamente cuando se llama al constructor de la clase derivada.


Capítulo 15. References Explained

What References Are

References in PHP are a means to access the same variable content by different names. They are not like C pointers, 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.


What References Do

PHP references allow you to make two variables to refer to the same content. Meaning, when you do:

$a =& $b

it means that $a and $b point to the same variable.

Nota: $a and $b are completely equal here, that's not $a is pointing to $b or vice versa, that's $a and $b pointing to the same place.

The same syntax can be used with functions, that return references, and with new operator (in PHP 4.0.4 and later):

$bar =& new fooclass();
$foo =& find_var ($bar);

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

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:

function foo (&$var)
{
    $var++;
}

$a=5;
foo ($a);

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.


What References Are Not

As said before, references aren't pointers. That means, the following construct won't do what you expect:

function foo (&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar);

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


Passing by Reference

You can pass variable to function by reference, so that function could modify its arguments. The syntax is as follows:

function foo (&$var)
{
    $var++;
}

$a=5;
foo ($a);
// $a is 6 here

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.

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

    function &bar()
    {
        $a = 5;
        return $a;
    }
    foo(bar());

    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:

function bar() // Note the missing &
{
    $a = 5;
    return $a;
}
foo(bar());

foo($a = 5) // Expression, not variable
foo(5) // Constant, not variable

These requirements are for PHP 4.0.4 and later.


Returning References

Returning by-reference is useful when you want to use a function to find which variable a reference should be bound to. When returning references, use this syntax:

function &find_var ($param)
{
    ...code...
    return $found_var;
}

$foo =& find_var ($bar);
$foo->x = 2;

In this example, the property of the object returned by the find_var function would be set, not the copy, as it would be without using reference syntax.

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


Unsetting References

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:

$a = 1;
$b =& $a;
unset ($a);

won't unset $b, just $a.

Again, it might be useful to think about this as analogous to Unix unlink call.


Spotting References

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:


global References

When you declare variable as global $var you are in fact creating reference to a global variable. That means, this is the same as:

$var =& $GLOBALS["var"];

That means, for example, that unsetting $var won't unset global variable.


$this

In an object method, $this is always reference to the caller object.


Capítulo 16. Autentificación HTTP con PHP

Las caracteríticas de autentificación HTTP en PHP solo estan disponibles cuando se está ejecutando como un módulo en Apache y hasta ahora no lo estan en la versión CGI. En un script PHP como módulo de Apache, se puede usar la función header() para enviar un mensaje de "Autentificación requerida" al navegador cliente haciendo que muestre una ventana de entrada emergente con nombre de usuario y contraseña. Una vez que el usuario ha rellenado el nombre y la contraseña, la URL que contiene el script PHP vuelve a ser llamada con las variables $PHP_AUTH_USER, $PHP_AUTH_PW y $PHP_AUTH_TYPE rellenas con el nombre de usuario, la contraseña y el tipo de autentificación respectivamente. Sólo autentificación "Básica" esta soportada en este momento. Consulte la función header() para más información.

Un fragmento de script de ejmplo que fuerce la autentificación del cliente en una página sería como el siguiente:

Ejemplo 16-1. Ejemplo de autentificación HTTP

<?php
  if (!isset($_SERVER['PHP_AUTH_USER'])) {
    header("WWW-Authenticate: Basic realm=\"My Realm\"");
    header("HTTP/1.0 401 Unauthorized");
    echo "Text to send if user hits Cancel button\n";
    exit;
  } else {
    echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
    echo "<p>You entered {$_SERVER['$PHP_AUTH_PW']} as your password.</p>";
  }
?>

Nota: Por favor tener cuidado cuando esteis programando las lines de cabecera HTTP. Para garantizar la maxima compatibilidad con todos los clientes, la palabra clave "Basic" debe de ser escrita con "B" mayúscula, la cadena de texto debe estar incluida entre comillas dobles (no simples) y un espacio debe preceder el código "401" en la linea de cabecera "HTTP/1.0 401"

En vez de, sencillamente, mostrar $PHP_AUTH_USER y $PHP_AUTH_PW, seguramente querais comprobar la validez del nombre de usuario y la contraseña. Tal vez enviando una consulta a una base de datos o buscando el usuario en un fichero dbm.

Vigilar aquí los navegadores Interner Explorer con bugs. Parecen muy quisquillosos con el orden de las cabeceras. Enviar la cabecera WWW-Autentificación antes que la cabecera HTTP/1.0 401 parece ser el truco por ahora.

Para prevenir que alguien escriba un script que revele la contraseña de una página que ha sido autentificada a través de algún mecanismo externo tradicional, las variables PHP_AUTH no serán rellenadas si algún tipo de autentificación externo ha sido activado para una página en particular. En este caso, la variable $REMOTE_USER puede ser usada para identificar al usuario autentificado externamente.

Configuration Note: PHP usa la directiva AuthType para determinar si una autentificación externa esta en uso. Recordar no usar esta directiva cuando querais usar la autentificación de PHP (si no todo intentento de autentificación fallará)

Nota, a pesar de todo, lo ya dicho no proteje de que alguien que controle una URL no autentificada robe contraseñas de URLs autentificadas en el mismo servidor.

Tanto Netscape como Internet Explorer borrarán la caché de la ventana de autentificación en el navegador local después de recibir una respuesta 401 del servidor. Esto puede usarse, de forma efectiva, para "desconectar" a un usuario, forzandole a reintroducir su nombre y contraseña. Algunas personas usan esto para "hacer caducar" entradas, o para proveer un botón de "desconectar".

Ejemplo 16-2. Ejemplo de autentificación HTTP forzando una reentrada

<?php
  function authenticate() {
    header( "WWW-Authenticate: Basic realm=\"Test Authentication System\"");
    header( "HTTP/1.0 401 Unauthorized");
    echo "You must enter a valid login ID and password to access this resource\n"
;
    exit;
  }
 
  if (!isset($_SERVER['PHP_AUTH_USER']) || ($SeenBefore == 1 && $OldAuth == $_SER
VER['$PHP_AUTH_USER']))) {
   authenticate();
  } 
  else {
   echo "<p>Welcome: {$_SERVER['$PHP_AUTH_USER']}<br>";
   echo "Old: {$_REQUEST['$OldAuth']}";
   echo "<form action='{$_SERVER['$PHP_SELF']}' METHOD='POST'>\n";
   echo "<input type='hidden' name='SeenBefore' value='1'>\n";
   echo "<input type='hidden' name='OldAuth' value='{$_SERVER['$PHP_AUTH_USER']}'
>\n";
   echo "<input type='submit' value='Re Authenticate'>\n";
   echo "</form></p>\n";
  }
?>

Este comportamiento no es requerido por el estándar de autentificación básica de HTTP, por lo que nunca debe depender de esto. Pruebas con Lynx han demostrado que Lynx no borra las credenciales de autentificación con una respuesta 401 del servidor, por lo que pulsando atrás y después adelante abriría el recurso de nuevo (siempre que los requerimientos de contraseña no hayan cambiado).

Además tener en cuanta que esto no funciona usando el servidor IIS de Microsoft y la versión CGI de PHP debido a una limitación del IIS


Capítulo 17. Cookies

PHP soporta transparentemente cookies HTTP. Las Cookies son un mecanismo que sirve para almacenar datos en el navegador del usuario remoto, para así poder identificar al usuario cuando vuelva. Se pueden poner cookies usando la función setcookies(). Las Cookies son parte de la cabecera HTTP, por tanto la función setcookie() debe ser llamada antes de que se produzca cualquier salida al navegador. Esta limitación es la misma a la de la función header(). Se pueden usar las funciones de almacenamiento intermedio del resultado para retrasar el resultado del script hasta que hayas decidido mandar o no una cookie o cabecera.

Cualquier cookie enviada a ti desde el cliente, automáticamente se convertirá en una variable PHP igual como ocurre con los métodos de datos GET y POST, dependiendo de las variables de configuración register_globals y variables_order. Si deseas asignar multiples valores a una cookie simple, añade simplemente [] a el nombre de la cookie.

En PHP 4.1.0 y posteriores, la array auto-global $_COOKIE será siempre actualizada con cualquier cookie mandada por el cliente. $HTTP_COOKIE_VARS es tambien actualizada en versiones anteriores de PHP cuando la variable de configuración track_vars esté activada.

Para más detalles ver la función setcookie().


Capítulo 18. Manejo de envío de ficheros

Envío de archivos con el método POST

PHP es capaz de recibir envíos de archivo de cualquier navegador que cumpla la norma RFC-1867 (entre los que se incluyen Netscape Navigator 3 o posterior, Microsoft Internet Explorer 3 con un parche o posterior sin éste). Ésta característica permite que los usuarios envien archivos de texto y binarios. Mediante la autentificación y funciones de manejo de archivos de PHP, es posible un control total de quién puede enviar archivos y que se hace con éstos una vez recibidos.

Es importante destacar que PHP también soporta el método PUT para envío de archivos tal y como lo utiliza Netscape Composer y el cliente Amaya de W3C. Consulte Soporte del método PUT para más detalles.

Una página de envío de archivos se puede crear mediante un formulario parecido a éste:

Ejemplo 18-1. Formulario de envío de archivo

<form enctype="multipart/form-data" action="_URL_" method="post">
<input type="hidden" name="MAX_FILE_SIZE" value="1000">
Send this file: <input name="userfile" type="file">
<input type="submit" value="Send File">
</form>
La _URL_ debe tener como destino un script PHP. El input oculto MAX_FILE_SIZE debe encontrarse antes del input de tipo "file" para indicar el tamaño máximo de archivo que se puede enviar en bytes

Aviso

MAX_FILE_SIZE debe ser consultado por el navegador; aun así es sencillo saltarse este máximo por lo tanto no se debe presuponer que el navegador siempre lo respetará. En contrapartida, la configuracion de PHP relativa al tamaño maximo no puede ser obviada.

Las variables definidas para los archivos enviados varian en función de la versión y configuración de PHP que se utilice. Las variables de las que hablamos a continuación serán definidas en la página destino despues de una recepción de fichero correcta. Cuando track_vars este activado, el array $HTTP_POST_FILES/$_FILES se inicializará. Por ultimo, las variables relacionadas seran inicializadas como globales cuando register_globals esté habilitado. Cabe señalar que el uso de las variables globales no esta recomendado en ningún caso.

Nota: track_vars esta activado siempre desde PHP 4.0.3. A partir de PHP 4.1.0 , $_FILES puede ser utilizado alternativamente a $HTTP_POST_FILES. $_FILES es siempre global asi que global no debe ser usado con $_FILES en el ámbito de función.

$HTTP_POST_FILES/$_FILES contienen la información sobre el fichero recibido.

A continuación se describe el contenido de $HTTP_POST_FILES. Se ha tomado el nombre 'userfile' para el fichero recibido tal y como se usaba en el script de ejemplo anterior:

$HTTP_POST_FILES['userfile']['name']

El nombre original del fichero en la máquina cliente.

$HTTP_POST_FILES['userfile']['type']

El tipo mime del fichero (si el navegador lo proporciona). Un ejemplo podría ser "image/gif".

$HTTP_POST_FILES['userfile']['size']

El tamaño en bytes del fichero recibido.

$HTTP_POST_FILES['userfile']['tmp_name']

El nombre del fichero temporal que se utiliza para almacenar en el servidor el archivo recibido.

Nota: A partir de PHP 4.1.0 se puede utilizar el variable corta $_FILES. PHP 3 no soporta $HTTP_POST_FILES.

Cuando register_globals se activa en el php.ini las siguientes variables son accesibles. Se ha tomado el nombre 'userfile' para el fichero recibido tal y como se usaba en el script de ejemplo del principio:

  • $userfile - El nombre del fichero temporal que se utiliza para almacenar en el servidor el archivo recibido.

  • $userfile_name - El nombre original del fichero en la máquina cliente.

  • $userfile_size - El tamaño en bytes del fichero recibido.

  • $userfile_type - El tipo mime del fichero (si el navegador lo proporciona). Un ejemplo podría ser "image/gif".

Se puede ver que "$userfile" (en las variables anteriores) toma el valor del atributo "name" que contenga el campo <input> de tipo "file" del formulario de envio. En el ejemplo anterior, elegimos llamarlo "userfile".

Nota: register_globals = On se desaconseja por razones de seguridad y rendimiento.

Por defecto, los ficheros serán almacenados en el directorio temporal por defecto del servidor a no ser que se especifique otra localizacion con la directiva upload_tmp_dir en php.ini. El directorio temporal por defecto del servidor puede ser modificado cambiando el valor de la variable de entorno TMPDIR en el contexto en que se ejecuta PHP La configuración de las variables de entorno no se puede realizar en PHP a través de la función putenv(). Esta variable de entorio puede ser utilizada también para asegurarnos que otras operaciones con archivos recibidos están funcionando correctamente.

Ejemplo 18-2. Verificando los archivos recibidos

Los siguientes ejemplos son validos para versiones de PHP 4 superiores a la 4.0.2. Veanse las funciones is_uploaded_file() y move_uploaded_file().

<?php 
// In PHP 4.1.0 or later, $_FILES should be used instead of $HTTP_POST_FILES.
if (is_uploaded_file($HTTP_POST_FILES['userfile']['tmp_name'])) {
    copy($HTTP_POST_FILES['userfile']['tmp_name'], "/place/to/put/uploaded/file");
} else {
    echo "Possible file upload attack. Filename: " . $HTTP_POST_FILES['userfile']['name'];
}
/* ...or... */
move_uploaded_file($HTTP_POST_FILES['userfile']['tmp_name'], "/place/to/put/uploaded/file");
?>

El script PHP que recibe el fichero, debe implementar la lógica necesaria para determinar que debe ser realizado con el fichero. Se puede utilizar, por ejemplo, la variable $HTTP_POST_FILES['userfile']['size'] para descartar los ficheros demasiado chicos o demasiado grandes; por otro lado, se puede usar la variable $HTTP_POST_FILES['userfile']['type'] para descartar los que no se ajusten a algun criterio de tipo. Cualquiera que sea la logica que utilicemos, se debe borrar o mover el archivo del directorio temporal.

El archivo será borrado del directorio temporal al final de la petición si no se ha movido o renombrado.


Errores comunes

A MAX_FILE_SIZE no se le puede dar un valor mayor que el valor que se haya especificado en la directivaupload_max_filesize. Por defecto se tiene un límite de 2 MegaBytes.

Si se ha activado el límite de memoria, se deben especificar un valor alto para memory_limit. En cualquier caso, se debe asegurar un valor suficientemente grande para memory_limit.

Si max_execution_time tiene un valor muy pequeño, la ejecución del script puede exceder este valor. De esta forma, se debe asegurar un valor suficientemente grande para max_execution_time.

Si post_max_size< tiene un valor muy pequeño, los ficheros mas grandes a este valor, no podrán ser enviados. Por ello, se debe asegurar un valor suficientemente grande para post_max_size.

No verificar que ficheros se estan manipulando puede tener como consecuencia que los usuarios puedan acceder a información sensible en otros directorios.

Cabe señalar que el httpd de CERN parece cortar todo a partir del primer espacio en blanco en el "content-type" de la cabecera mime que obtiene del cliente. Si este es el caso, con el httpd de CERN no se soporta la funcionalidad de envío de ficheros.


Envío de multiples ficheros

Se pueden enviar multiples ficheros usando diferentes nombres (name) para los input.

Así mismo, es posible enviar varios archivos simultaneamente y tener organizada en arrays la información. Para hacer esto, se utiliza la misma sintáxis que cuando tenemos multiples "selects" o "checkboxes" en el formulario HTML:

Nota: El soporte para envío multiple de ficheros fue añadido en la versión 3.0.10.

Ejemplo 18-3. Envío de multiples ficheros

<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send these files:<br>
  <input name="userfile[]" type="file"><br>
  <input name="userfile[]" type="file"><br>
  <input type="submit" value="Send files">
</form>

Cuando el formulario del ejemplo es enviado, los arrays $HTTP_POST_FILES['userfile'], $HTTP_POST_FILES['userfile']['name'] y $HTTP_POST_FILES['userfile']['size'] son inicializados. Así mismo pasa con $_FILES en PHP 4.1.0 o superiores y $HTTP_POST_VARS en PHP 3. Cuando register_globals esta activa, las variables globales para los archivos recibidos también son inicializadas. Cada uno de estos arrays tendrá en los índices numericos correspondientes los valores para cada fichero recibido.

Por ejemplo, si tomamos como nombres de archivo enviados /home/test/review.html y /home/test/xwp.out. Tendríamos en $HTTP_POST_FILES['userfile']['name'][0] el valor de review.html, y en $HTTP_POST_FILES['userfile']['name'][1] tendríamos xwp.out; analogamente, $HTTP_POST_FILES['userfile']['size'][0] contendría el tamaño del fichero review.html, y asi sucesivamente...

$HTTP_POST_FILES['userfile']['name'][0], $HTTP_POST_FILES['userfile']['tmp_name'][0], $HTTP_POST_FILES['userfile']['size'][0] y $HTTP_POST_FILES['userfile']['type'][0] tambien son asignadas.


Soporte del método PUT

PHP soporta el metodo HTTP PUT que usan aplicaciones como Netscape Composer y Amaya del W3C. Las peticiones PUT son más sencillas que el método POST. Un ejemplo:

PUT /path/filename.html HTTP/1.1

Esto normalmente significaría que el cliente remoto quiere salvar el contenido como: /path/filename.html en tu árbol web. Lógicamente no una buena idea que la gente pueda escribir en tu árbol web. Para manipular esta petición debes decirle al servidor que esta petición sea atendida por un script PHP. En Apache, por ejemplo, se utiliza para esto la directiva Script en los alguno de los archivos de configuración del servidor. Un sitio típico de uso es dentro del bloque &lt;Directory&gt; o quizás en el bloque &lt;Virtualhost&gt;. Una linia así deberia hacer ésta función:

Script PUT /put.php

Ésto le dice a Apache que envíe todas peticiones PUT para URIs que contengan esta linia al script put.php. Se asume que PHP se encuentra activo y con la extensión .php enlazada a él.

Dentro del script put.php3 se podría implementar algo así:

<?php copy($PHP_UPLOADED_FILE_NAME,$DOCUMENT_ROOT.$REQUEST_URI); ?>

Esto copiaría el archivo a la localización requerida por el cliente remoto. Aqui se pueden ejecutar funciones de autentificación de usuario o cualquier otro tipo de chequeo. El archivo se guarda en el archivo temporal del sistema servidor de la misma manera que el Método POST. Cuando la petición finaliza, el archivo temporal es eliminado. En consequencia el script dede proceder al trato de éste inmediatamente, ya sea para copiarlo, renombrarlo, etc. El archivo se encuentra en la variable $PHP_PUT_FILENAME, y el destino sugerido por el cliente en la variable $REQUEST_URI (puede variar en servidores web que no sean Apache). No es necesario hacer caso al destino sugerido por el cliente. Por ejemplo se podrían copiar los archivos enviados a directorios especialmente designados para esta tarea.


Capítulo 19. Usando archivos remotos

Siempre que el soporte para la "envoltura URL fopen" esté habilitado cuando se configura PHP (lo cual ocurre a menos que se pasa explícitamente la opción --disable-url-fopen-wrapper a configure (para versiones hasta la 4.0.3), ó configurar como "off" el parámetro allow_url_fopen en php.ini (para las nuevas versiones)) se pueden usar URLs HTTP y FTP con la mayoría de las funciones que toman un archivo como parámetro, incluyendo las sentencias require() e include().

Nota: La versión actual de PHP para Windows no soporta el acceso remoto a ficheros en las siguientes funciones: include(), include_once(), require() y require_once().

Por ejemplo, se puede usar este para abrir un archivo en un servidor web remoto, analizar en la salida la información que se quiera, y entonces, usar la información en una consulta a base de datos, o simplemente para sacarlas en un estilo que coincida con el resto de su sitio web.

Ejemplo 19-1. Obtener el título de una página remota

<?php
$file = fopen ("http://www.example.com/", "r");
if (!$file) {
    echo "<p>Unable to open remote file.\n";
    exit;
}
while (!feof ($file)) {
    $line = fgets ($file, 1024);
    /* This only works if the title and its tags are on one line */
    if (eregi ("<title>(.*)</title>", $line, $out)) {
        $title = $out[1];
        break;
    }
}
fclose($file);
?>

También se puede escribir a archivos en un FTP siempre que se conecte como un usuario con los correctos derechos de acceso, y el archivo no exista ya.Para conectar como un usuario distinto de 'anonymous', se necesita especificar el nombre de usuario (y posiblemente contraseña) dentro de la URL, tales como 'ftp://usuario:clave@ftp.ejemplo.com/camino/a/archivo'. (Se puede usar la misma clase de sintaxis para acceder a archivos via HTTP cuando se requería una autenticació de same sort of syntax to access files via HTTP when they require Basic authentication.)

Ejemplo 19-2. Almacenando datos en un servidor remoto

<?php
$file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
if (!$file) {
    echo "<p>Unable to open remote file for writing.\n";
    exit;
}
/* Write the data here. */
fputs ($file, $HTTP_SERVER_VARS['HTTP_USER_AGENT'] . "\n");
fclose ($file);
?>

Nota: Podeis captar la idea en el ejemplo anterior de como escribir en un registro remoto, pero como ya hemos comentado antes, solamente se puede escribir a un fichero nuevo usando la "envoltura URL fopen" Para registros distribuidos, consultar la función syslog().


Capítulo 20. Manejando conexiones

Nota: Todo lo siguiente se aplica a partir de la versión 3.0.7 y posterior.

Internamente en PHP se mantiene el estado de la conexión. Hay 3 posibles estados:

  • 0 - NORMAL

  • 1 - ABORTED (Abortado)

  • 2 - TIMEOUT (Fuera de tiempo)

Cuando un script PHP se está ejecutando se activa el estado NORMAL. Si el cliente remoto se desconecta, se pasa al estado ABORTED. Esto suele ocurrir cuando el usuario pulsa en el botón STOP del navegador. Si se alcanza el límite de tiempo impuesto por PHP (ver set_time_limit()), se pasa al estado TIMEOUT.

Puedes decidir si quieres que la desconexión de un cliente cause que tu script sea abortado. Algunas veces es cómodo que tus scripts se ejecuten por completo, incluso si no existe ya un navegador remoto que reciba la salida. El comportamiento por defecto es sin embargo, que tu script se aborte cuando el cliente remoto se desconecta. Este comportamiento puede ser configurado vía la directiva ignore_user_abort en el fichero php3.ini, o también con la función ignore_user_abort(). Si no le espeficicas al PHP que cuando un usuario aborte lo ignore, tu script terminará su ejecución. La única excepción es si tienes registrada un función de desconexión usando la función register_shutdown_function(). Con una función de desconexión, cuando un usuario remoto pulsa en el botón STOP, la próxima vez que tu script intenta mostrar algo, PHP detecta que la conexión ha sido abortada y se llama a la función de desconexión. Esta función de desconexión también se llama al final de la ejecución de tu script cuando se ha ejecutado normalmente, de manera que si quieres hacer algo diferente en caso de que un cliente se haya desconectado, puedes usar la función connection_aborted(). Esta función devuelve TRUE si la conexión fue abortada.

Vuestro script también se puede terminar por un temporizador interno. El timeout por defecto es de 30 segundos. Se puede cambiar usando la directiva max_execution_time en el fichero php.ini o la correspondiente directiva php_max_execution_time en la configuración del servidor de páginas Apache, como también con la función set_time_limit(). Cuando el temporizador expira, el script se aborta como en el caso de la desconexión del cliente, de manera que si se ha definido una función de desconexión, esta se llamará. Dentro de esta función de desconexión, puedes comprobar si fue el timeout el que causó que se llamara a la función de desconexión, llamando a la función connection_timeout(). Esta función devolverá verdadero si el timeout causa que se llame a la función de desconexión.

Hay que destacar que ambos, el estado ABORTED y el TIMEOUT, se pueden activar al mismo tiempo. Esto es posible si le dices a PHP que ignore las desconexiones intencionadas de los usuarios. PHP aún notará el hecho de que el usuario puede haberse desconectado, pero el script continuará ejecutándose. Si se alcanza el tiempo límite de ejecución será abortado y, si se ha definido una función de desconexión, esta será llamada. En este punto, encontrarás que las funciones connection_timeout() y connection_aborted() devuelven verdadero. Puedes comprobar ambos estados de una manera simple usando la función connection_status(). Esta función devuelve un campo de bit de los estados activos. De este modo, si ambos estados están activos devolvería por ejemplo un valor 3.


Capítulo 21. Conexiones persistentes a bases de datos

Las conexiones persistentes son enlaces SQL que no se cierran cuando termina la ejecución del archivo de comandos. Cuando se pide una conexión persistente, PHP comprueba si hay ya una conexión persistente idéntica (que permanecía abierta desde antes) - y si existe, la usa. Si no existe, crea un enlace. Una conexión 'idéntica' es una conexión que se abrió hacia el mismo "host", con el mismo nombre de usuario y la misma contraseña (donde sea aplicable).

Nota: Existen otras extensiones que proporcionan conexiones persistentes, tal como la extensión IMAP

La gente que no está familiarizada con el modo como trabajan y distribuyen la carga los servidores "web" puede confundir que significa conexiones persistentes. En particular, no te dan la habilidad de abrir 'sesiones de usuario' en el mismo enlace SQL, no dan la habilidad de construir una transacción de forma eficiente, y no hacen un montón de otras cosas. De hecho, para ser extremadamente claros sobre el tema las conexiones persistentes no te dan ninguna functionalidad que no fuera posible con sus hermanas no-persistentes.

¿Por qué?

Esto tiene que ver con el modo como funcionan los servidores "web". Hay tres modos en que un servidor "web" puede utilizar PHP para generar páginas web.

El primer método es usar PHP como una capa CGI. Cuando corre de este modo, se crea y destruye una instancia del intérprete PHP por cada página solicitada (para una página PHP) a tu servidor. Debido a que se destruye después de cada petición, cualquier recurso que adquiera (como un enlace a un servidor de base de datos SQL) se cierra cuando es destruido. En este caso, no se gana nada si se intentan usar conexiones persistentes, ya que simplemente no persisten.

El segundo, y más popular, método es correr PHP como un módulo en un servidor web multiproceso, lo cual actualmente sólo incluye Apache. Un servidor multiproceso tiene típicamente un proceso (el padre) que coordina un conjunto de procesos (sus hijos) que realmente hacen el trabajo se servir las páginas web. Cuando entra cada petición de un cliente, es entregada a uno de los hijos que no esté ya sirviendo a otro cliente. Esto significa que cuando el mismo cliente hace una segunda petción al servidor, puede ser atendido por un proceso hijo distinto del de la primera vez. Lo que una conexión persistente hace por ti en este caso es hacerlo de tal modo que cada proceso hijo sólo necesita conectar a tu SQL server la primera vez que sirve una página que hace uso de una conexión así. Cuando otra página solicita una conexión a SQL server, puede reutilizar la conexión que el hijo estableció previamente.

El último método es usar PHP como un "plug-in" para un servidor web multihilo. En la actualidad es solamente teórico -- PHP no funciona aún como "plug-in" para ningún servidor web multihilo. Actualmente PHP 4 soporta ISAPI, WSAPI y NSAPI (en Windows), lo cual permite a PHP ser utilizado como "plug-in" para servidores web multihilo como Netscape FastTrack, Internet Information Server (IIS) de Microsoft, y O'Reilly's WebSite Pro. El comportamiento es exactamente el mismo que para el modelo de multiprocesador descrito anteriormente. Tener en cuanta que el soporte para SAPI no está disponible en PHP 3.

Si las conexiones persistentes no aportan ninguna funcionalidad añadida, ¿para qué son buenas?

La respuesta aqui es extremadamente simple -- eficiencia. Las conexiones persistentes son buenas si las cabeceras de control para crear un enlace a tu servidor SQL es alta. Que estas cabeceras sean o no realmente altas depende de muchos factores. Como, qué clase de base de datos es, si esta o no situada en el mismo ordenador que el servidor web, cómo está de cargada la máquina donde se encuentre el servidor SQL, y otras así. El hecho fundamental es que si la cabecera de conexión es alta, las conexiones persistentes te ayudan considerablemente . Ellas hacen que el proceso hijo simplemente conecte solamente una vez durante todo su intervalo de vida, en vez de cada vez que procesa una pagina que requiere conectar al servidor SQL. Esto significa que por cada hijo que abrió una conexión persistente tendrá su propia conexión persistente al servidor. Por ejemplo, si tienes 20 procesos hijos distintos que corran un archivo de comandos que cree una conexión persistente a tu servidor SQL, tendrías 20 conexiones diferentes a ti servidor SQL, una por cada hijo.

No obstante, hay que tener en cuenta que esto puede tener desventajas si estais utilizando una base de datos con límites de conexión, por debajo del numero de procesos hijo con conexiones persistentes. Si tu base de datos tiene un límite de 16 conexiones simultaneas y en el curso de una sesión de servidor, 17 procesos hijo intentan conectarse, uno de ellos no podrá hacerlo. Si existen errores en los scripts, que no permitan terminar la conexion (p.ej.bucles infinitos), una base de datos con solo 32 conexiones puede ser rápidamente hundida. Comprobar la documentacion de vuestra base de datos para obtener información sobre que hacer con conexiones abandonadas ó libres.

Aviso

Un par de advertencias más a tener en cuenta cuando utiliceis conexiones persistentes. La primera, si utilizais bloqueos en una tabla desde una conexión persistente y por cualquier causa el script no puede desbloquear la tabla, todos los scripts posteriores que usen esta conexión, quedarán bloqueados indefinídamente y se requerirá que, ó bien el servidor httpd ó la base de datos sean arrancados de nuevo. La segunda, cuando utiliceis transacciones, un bloqueo por transacción será heredado por el próximo script usando la conexión, si la ejecución del primer script termina antes que el bloqueo. en ambos caso podeis utilizar register_shutdown_function() para registrar una funcion simple de limpieza que desbloquee las tablas ó deshaga la transacción. Lo mejor para evitar problemas es no usar conexiones persistentes en scripts que usen bloqueos de tablas ó transacciones (para todolo demás pueden ser usadas sin problemas)

Un resumen importante. Las conexiones persistentes fueron diseñadas para tener una equivalencia uno-a-uno con las conexiones normales. Eso significa que deberíais siempre ser capaz de reemplazar las conexiones persistentes por conexiones no persistentes y no cambiará, el modo como se comporta el archivo de comandos. Puede cambiar la eficiencia del archivo de comandos (y probablemete lo hará), ¡pero no su comportamiento!


Capítulo 22. Modo Seguro (Safe Mode)

El Modo Seguro de PHP es un intento para resolver el problema de la seguridad en un servidor compartido. Tratar de resolver este problema al nivel de PHP es arquitectónicamente incorrecto, pero ya que las alternativas en un servidor web y a niveles de sistemas operativos no son tan realistas, mucha gente, especialmente la de proveedores de Internet (ISP), usa el Modo Seguro por ahora.

Tabla 22-1. Las directivas de Configuración que controlan el Modo Seguro son:

DirectivaValor por Omisión
safe_mode Off
safe_mode_gid 0
safe_mode_include_dir ""
safe_mode_exec_dir 1
open_basedir ""
safe_mode_allowed_env_vars PHP_
safe_mode_protected_env_vars LD_LIBRARY_PATH
disable_functions ""

Cuando safe_mode está en On, el PHP verifica si el dueño del script actual coincide con el dueño del fichero a ser operado por una función de fichero. Por ejemplo:
-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
Corriendo este script.php
<?php
 readfile('/etc/passwd'); 
?>
resulta in este error cuando Modo Seguro está habilitado:
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

Sin embargo, pueden haber ambientes donde una estricta verificación del UID no es apropiada, y una relajada verificación del GID es suficiente. Esto es soportado por medio del switch safe_mode_gid. Seteándolo a On hace la verificación relajada GID, seteándolo a Off (el valor por omisión) hace la verificación del UID.

Si en vez del safe_mode, Ud. setea un directorio open_basedir, entonces todas las operaciones de fichero estarán limitadas a los ficheros bajo ese directorio especificado. Por ejemplo (ejemplo de httpd.conf de Apache):
<Directory /docroot>
  php_admin_value open_basedir /docroot 
</Directory>
Si Ud. corre el mismo script.php con este seteo open_basedir, entonces este es el resultado:
Warning: open_basedir restriction in effect. File is in wrong directory in 
/docroot/script.php on line 2

Ud. también puede inhabilitar funciones individuales. Note que la directiva disable_functions no puede ser usada fuera del fichero php.ini lo que significa que Ud. no puede inhabilitar funciones en los principios per-virtualhost o per-directory en su fichero httpd.conf. Si agregamos esto a nuestro fichero php.ini:
disable_functions readfile,system
Entonces obtenemos esta salida:
Warning: readfile() has been disabled for security reasons in 
/docroot/script.php on line 2


Funciones restringidas/inhabilitadas por Modo Seguro

Esta es una lista probablemente incompleta y posiblemente incorrecta de las funciones limitadas por safe mode.

Tabla 22-2. Funciones limitadas por Modo Seguro

FunciónLimitaciones
dbmopen()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

dbase_open()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

filepro()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

filepro_rowcount()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

filepro_retrieve()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

ifx_*()restricciones sql_safe_mode, (!= safe mode)
ingres_*()restricciones sql_safe_mode, (!= safe mode)
mysql_*()restricciones sql_safe_mode, (!= safe mode)
pg_loimport()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

posix_mkfifo()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

putenv()Obecede las ini-directivas safe_mode_protected_env_vars y safe_mode_allowed_env_vars. Vea también la documentación de putenv()
move_uploaded_file()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

chdir()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

dl()Esta función no está activada en safe-mode (modo-seguro)
backtick operatorEsta función no está activada en safe-mode (modo-seguro)
shell_exec() (equivalencia funcional de backticks)Esta función no está activada en safe-mode (modo-seguro)
exec()Ud. puede correr sólo ejecutables dentro delsafe_mode_exec_dir. Por razones prácticas, no está actualmente permitido tener componentes .. en la ruta del fichero ejecutable.
system()Ud. puede correr sólo ejecutatables dentro delsafe_mode_exec_dir. Por razones prácticas, no está actualmente permitido tener componentes .. en la ruta del fichero ejecutable.
passthru()Ud. puede correr sólo ejecutatables dentro delsafe_mode_exec_dir. Por razones prácticas, no está actualmente permitido tener componentes .. en la ruta del fichero ejecutable.
popen()Ud. puede correr sólo ejecutatables dentro delsafe_mode_exec_dir. Por razones prácticas, no está actualmente permitido tener componentes .. en la ruta del fichero ejecutable.
mkdir()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

rmdir()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

rename()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

unlink()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

copy()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

(en source y target)
chgrp()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

chown()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

chmod()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Además, Ud. no puede setear los bits de SUID, SGID y sticky
touch()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

symlink()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

(Nota: sólo el target es comprobado)
link()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

(Nota: sólo the target es comprobado)
getallheaders()En Modo Seguro, las cabeceras que empiezan con 'authorization' (insensitivo al tipo de letra) no serán retornadas. Advertencia: esto está roto por la implementación de aol-server de getallheaders()!
header()En Modo Seguro, el UID del script está agregado a la parte realm de la cabecera WWW-Authenticate si Ud. setea esta cabecera (usado por HTTP Authentication).
highlight_file(), show_source()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

(Nota: sólo afectado desde PHP 4.2.1)
parse_ini_file()

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si el fichero(s)/directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

Nota: Cuando safe-mode (modo-seguro) está activado, PHP comprueba si los directorios que vas a utilizar, tienen la misma UID que el script que está siendo ejecutado.

(Nota: sólo afectado desde PHP 4.2.1)
Cualquier función que usa php4/main/fopen_wrappers.c ??


Capítulo 23. Using PHP from the command line

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.

Nota: Because both --enable-cli and --enable-cgi are enabled by default, simply having --enable-cli in your configure line does not necessarily mean the CLI will be copied as {PREFIX}/bin/php during make install.

The windows package distributes the CGI as php.exe and has a folder named cli with the CLI in it, so: cli/php.exe.

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.

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 switch is kept for compatibility so that you can use older CGI scripts.

    It does not change the working directory to that of the script. (-C switch kept for compatibility)

    Plain text error messages (no HTML formatting).

  • There are certain php.ini directives which are overriden by the CLI SAPI because they do not make sense in shell environments:

    Tabla 23-1. Overriden php.ini directives

    DirectiveCLI SAPI default valueComment
    html_errorsFALSE 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_flushTRUE 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_time0 (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_argvTRUE

    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 $argc and $argv are registered and filled in with the appropriate values when using the CLI SAPI. Prior to this version, the creation of these variables behaved as they do in CGI and MODULE versions which requires the PHP directive register_globals to be on. Regardless of version or register_globals setting, you can always go through either $_SERVER or $HTTP_SERVER_VARS. Example: $_SERVER['argv']

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

    Tabla 23-2. CLI specific Constants

    ConstantDescription
    STDIN An already opened stream to stdin. This saves opening it with
    $stdin = fopen('php://stdin', 'r');
    STDOUT An already opened stream to stdout. This saves opening it with
    $stdout = fopen('php://stdout', 'w');
    STDERR An already opened stream to stderr. This saves opening it with
    $stderr = fopen('php://stderr', 'w');

    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");'
    You do not need to explicitly close these streams, as they are closed automatically by PHP when your script ends.

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

    Nota: The CGI SAPI supports the CLI SAPI behaviour by means of the -C switch 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] [-- args...]
  -s               Display colour syntax highlighted source.
  -w               Display source with stripped comments and whitespace.
  -f <file>        Parse <file>.
  -v               Version number
  -c <path>|<file> Look for php.ini file in this directory
  -a               Run interactively
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -z <file>        Load Zend extension <file>.
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -i               PHP information
  -r <code>        Run PHP <code> without using script tags <?..?>
  -h               This help

  args...          Arguments passed to script. Use -- args when first argument 
                   starts with - or script is read from stdin

The CLI SAPI has three different ways of getting the PHP code you want to execute:

  1. Telling PHP to execute a certain file.

    php my_script.php
    
    php -f my_script.php
    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.

  2. Pass the PHP code to execute directly on the command line.

    php -r 'print_r(get_defined_constants());'
    Special care has to be taken in regards of shell variable substitution and quoting usage.

    Nota: Read the example carefully, there are no beginning or ending tags! The -r switch simply does not need them. Using them will lead to a parser error.

  3. 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:
    $ some_application | some_filter | php | sort -u >final_output.txt

You cannot combine any of the three ways to execute code.

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:
#!/usr/bin/php
<?php
    var_dump($argv);
?>
Assuming this file is named test in the current directory, we can now do the following:
$ chmod 755 test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}
As you see, in this case no care needs to be taken when passing parameters which start with - to your script.

Tabla 23-3. Command line options

OptionDescription
-s

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.

Nota: This option does not work together with the -r option.

-w

Display source with stripped comments and whitespace.

Nota: This option does not work together with the -r option.

-f

Parses and executed the given filename to the -f option. This switch is optional and can be left out. Only providing the filename to execute is sufficient.

-v

Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

-c

With this option one can either specify a directory where to look for php.ini or you can specify a custom INI file directly (which does not need to be named php.ini), e.g.:
$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

-a

Runs PHP interactively.

-d

This option allows you to set a custom value for any of the configuration directives allowed in php.ini. The syntax is:
-d configuration_directive[=value]

Examples:
# Omitting the value part will set the given configuration directive to "1"
$ php -d max_execution_time -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passing an empty value part will set the configuration directive to ""
php -d max_execution_time= -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# The configuration directive will be set to anything passed after the '=' character
$  php -d max_execution_time=20 -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php -d max_execution_time=doesntmakesense -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

-e

Generate extended information for debugger/profiler.

-z

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.

-l

This option provides a convenient way to only perform a syntax check on the given PHP code. On succes, 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 -f if you would like to test for fatal errors too.

Nota: This option does not work together with the -r option.

-m

Using this option, PHP prints out the built in (and loaded) PHP and Zend modules:
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-i 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 the output is in HTML and therefore quite huge.
-r

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.

Nota: Care has to be taken when using this form of PHP to not collide with command line variable substitution done by the shell.

Example showing a parser error
$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
The problem here is that the sh/bash performs variable substitution even when using double quotes ". Since the variable $foo is unlikely to be defined, it expands to nothing which results in the code passed to PHP for execution actually reading:
$ php -r " = get_defined_constants();"
The correct way would be to use single quotes '. Variables in single-quoted strings are not expanded by sh/bash.
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]
If you are using a shell different from sh/bash, you might experience further issues. Feel free to open a bug report or send a mail to phpdoc@lists.php.net. One can still easily run into troubles when trying to get shell variables into the code or using backslashes for escaping. You've been warned.

Nota: -r is available in the CLI SAPI and not in the CGI SAPI.

-h With this option, you can get information about the actual list of command line options and some one line descriptions about what they do.

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.

Ejemplo 23-1. Script intended to be run from command line (script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

This is a command line PHP script with one option.

  Usage:
  <?php echo $argv[0]; ?> <option>

  <option> can be some word you would like
  to print out. With the --help, -help, -h,
  or -? options, you can get this help.

<?php
} else {
    echo $argv[1];
}
?>

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:

Ejemplo 23-2. Batch file to run a command line PHP script (script.bat)

@c:\php\cli\php.exe script.php %1 %2 %3 %4

Assuming you named the above program script.php, and you have your CLI php.exe in c:\php\cli\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.

IV. Referencia de las Funciones

Tabla de contenidos
I. Funciones específicas de Apache
II. Funciones de matrices
III. Funciones Aspell [deprecated]
IV. Funciones matemáticas de precisión arbitraria BCMath
V. Funciones de compresión Bzip2
VI. Funciones de calendario
VII. Funciones del API de CCVS
VIII. soporte de las funciones COM para Windows
IX. Funciones de Clases/Objectos
X. Funciones de ClibPDF
XI. Crack functions
XII. CURL, Client URL Library Functions
XIII. Funciones de pago electrónico
XIV. Crédit Mutuel CyberMUT functions
XV. Cyrus IMAP administration functions
XVI. Character type functions
XVII. Funciones de la capa de abstraccion de bases de datos (dbm-style)
XVIII. Funciones de fecha y hora
XIX. Funciones para dBase
XX. Funciones dbm
XXI. dbx functions
XXII. DB++ Functions
XXIII. Direct IO functions
XXIV. Funciones con directorios
XXV. Funciones de DOM XML
XXVI. .NET functions
XXVII. Error Handling and Logging Functions
XXVIII. FrontBase Functions
XXIX. Funciones filePro
XXX. Funciones del sistema de ficheros
XXXI. Funciones Forms Data Format (Formato de Datos de Formularios)
XXXII. FriBiDi functions
XXXIII. Funciones FTP
XXXIV. Function Handling functions
XXXV. GNU Gettext
XXXVI. GMP functions
XXXVII. Funciones HTTP
XXXVIII. Funciones para Hyperwave
XXXIX. Hyperwave API functions
XL. iconv functions
XLI. Funciones para imágenes
XLII. Funciones IMAP
XLIII. Funciones para Informix
XLIV. Funciones InterBase
XLV. Ingres II functions
XLVI. IRC Gateway Functions
XLVII. PHP / Java Integration
XLVIII. Funciones LDAP
XLIX. Funciones de Correo
L. mailparse functions
LI. Funciones matemáticas
LII. Multi-Byte String Functions
LIII. MCAL functions
LIV. Funciones Criptográficas
LV. MCVE Payment Functions
LVI. Funciones Hash
LVII. Mimetype Functions
LVIII. Funciones de Microsoft SQL Server
LIX. Ming functions for Flash
LX. Miscelánea de funciones
LXI. mnoGoSearch Functions
LXII. funciones mSQL
LXIII. Funciones MySQL
LXIV. Mohawk Software session handler functions
LXV. muscat functions
LXVI. Funciones de Red
LXVII. Ncurses terminal screen control functions
LXVIII. Lotus Notes functions
LXIX. ODBC functions
LXX. Object Aggregation/Composition Functions
LXXI. Funciones de Oracle 8
LXXII. OpenSSL functions
LXXIII. Funciones Oracle
LXXIV. Ovrimos SQL functions
LXXV. Output Control Functions
LXXVI. Object property and method call overloading
LXXVII. PDF functions
LXXVIII. Verisign Payflow Pro functions
LXXIX. opciones e información de PHP
LXXX. Funciones POSIX
LXXXI. Funciones de PostgreSQL
LXXXII. Process Control Functions
LXXXIII. Funciones de ejecución de programas
LXXXIV. Printer functions
LXXXV. Pspell Functions
LXXXVI. GNU Readline
LXXXVII. Funciones GNU Recode
LXXXVIII. Funciones de expresiones regulares compatibles con Perl
LXXXIX. qtdom functions
XC. Funciones para expresiones regulares
XCI. Funciones Semáforo y de memoria compartida
XCII. SESAM database functions
XCIII. Funciones para el manejo de sesiones
XCIV. Shared Memory Functions
XCV. Shockwave Flash functions
XCVI. Funciones SNMP
XCVII. Socket functions
XCVIII. Stream functions
XCIX. Funciones de cadenas
C. Funciones de Sybase
CI. Tokenizer functions
CII. Funciones URL
CIII. Funciones sobre variables
CIV. vpopmail functions
CV. W32api functions
CVI. Funciones WDDX
CVII. Funciones de intérprete XML
CVIII. XML-RPC functions
CIX. XSLT functions
CX. YAZ
CXI. NIS funciona
CXII. Zip File Functions (Read Only Access)
CXIII. Funciones de Compresión

I. Funciones específicas de Apache

Estas funciones están disponibles solamente si ejecutamos PHP como módulo de Apache.

Tabla de contenidos
apache_child_terminate -- Terminate apache process after this request
apache_lookup_uri --  Efectua una petición parcial a la URI especificada y devuelve toda la información sobre ella.
apache_note -- Recibe y establece los valores de una petición en una tabla de notas del Apache
apache_request_headers -- Fetch all HTTP request headers
apache_response_headers --  Fetch all HTTP response headers
apache_setenv -- Set an Apache subprocess_env variable
ascii2ebcdic -- Translate string from ASCII to EBCDIC
ebcdic2ascii -- Translate string from EBCDIC to ASCII
getallheaders -- Recibe todas las cabeceras de una petición HTTP
virtual -- Ejecuta una sub-petición al Apache

apache_child_terminate

(PHP 4 >= 4.0.5)

apache_child_terminate -- Terminate apache process after this request

Description

bool apache_child_terminate ( void)

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.

Nota: The availability of this feature is controlled by the php.ini directive apache.child_terminate, which is set to off by default.

This feature is also not available on multithreaded versions of apache like the win32 version.

See also exit().

apache_lookup_uri

(PHP 3>= 3.0.4, PHP 4 )

apache_lookup_uri --  Efectua una petición parcial a la URI especificada y devuelve toda la información sobre ella.

Descripción

class apache_lookup_uri ( string filename)

Esta función efectua una llamada parcial a URI. Esta llamada no hace sino obtener toda la información importante sobre el recurso pedido y la devuelve en un tipo clase .Las propiedades de esa clase son:

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

Nota: Nota: apache_lookup_uri solo funciona cuando el PHP está instalado como módule del Apache.

apache_note

(PHP 3>= 3.0.2, PHP 4 )

apache_note -- Recibe y establece los valores de una petición en una tabla de notas del Apache

Descripción

string apache_note ( string note_name [, string note_value])

apache_note() es una función específica del Apache que recibe y establece valores de la petición en una tabla de notas. Si se llama con un solo parámetro,devuelve el valor de note_name. Si se llama con dos parámetros, establece el valor de note_value en note_value y devuelve el valor que había en note_name.

apache_request_headers

(PHP 4 >= 4.3.0)

apache_request_headers -- Fetch all HTTP request headers

Description

array apache_request_headers ( void)

apache_request_headers() returns an associative array of all the HTTP headers in the current request. This is only supported when PHP runs as an Apache module.

Nota: 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().

Ejemplo 1. apache_request_headers() Example

<?php
$headers = apache_request_headers();

foreach ($headers as $header => $value) {
    echo "$header: $value <br />\n";
}
?>

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

apache_response_headers

(PHP 4 >= 4.3.0)

apache_response_headers --  Fetch all HTTP response headers

Description

array apache_response_headers ( void)

Returns an array of all Apache response headers. This functionality is only available in PHP version 4.3.0 and greater.

See also getallheaders() and headers_sent().

apache_setenv

(PHP 4 >= 4.2.0)

apache_setenv -- Set an Apache subprocess_env variable

Description

int apache_setenv ( string variable, string value [, bool walk_to_top])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ascii2ebcdic

(PHP 3>= 3.0.17)

ascii2ebcdic -- Translate string from ASCII to EBCDIC

Description

int ascii2ebcdic ( string ascii_str)

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.

See also the reverse function ebcdic2ascii()

ebcdic2ascii

(PHP 3>= 3.0.17)

ebcdic2ascii -- Translate string from EBCDIC to ASCII

Description

int ebcdic2ascii ( string ebcdic_str)

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.

See also the reverse function ascii2ebcdic()

getallheaders

(PHP 3, PHP 4 )

getallheaders -- Recibe todas las cabeceras de una petición HTTP

Descripción

array getallheaders ( void)

Esta función devuelve asociados en un vector todas las cabeceras de la actual petición HTTP.

Nota: También puedes obtener los valores de las variables de los CGIs mediante variables de entorno, que funcionan, esté o no el PHP funcionando como módulo del Apache. Utiliza phpinfo()para ver una lista de todas las variables de entorno definidas de esta forma.

Ejemplo 1. ObtenerTodaslasCabeceras() Ejemplo

$cabeceras = getallheaders();
while (list($cabecera, $valor) = each($cabeceras)) {
    echo "$cabecera: $valor<br>\n";
}
Este ejemplo visualiza todas las cabeceras de la petición actual.

Nota: ObtenerTodaslasCabeceras() actualmente solo funcionará si el PHP es cargado como módulo del Apache .

virtual

(PHP 3, PHP 4 )

virtual -- Ejecuta una sub-petición al Apache

Descripción

int virtual ( string filename)

virtual() es una función específica del Apache que es equivalente a <!--#include virtual...--> en mod_include. Esto ejecuta una sup-petición al Apache .Esto, es util para incluir CGI-scripts o páginas .shtml o cualquier tipo de fichero que puedas procesar mediante el Apache. Los CGI-scripts deberán generar cabeceras válidas. Esto, implica como mínimo un include() ó un require(); La función virtual() no puede ser usada para incluir un documento que sea por si mismo un documento PHP.

II. Funciones de matrices

Introducción

Estas funciones permiten trabajar y manipular matrices (arrays) de diferentes maneras. Las matrices se utilizan para guardar, manejar y operar grupos de variables.

Matrices simples y multi-dimensionales están soportadas y pueden ser creadas por el usuario u otras funciones. Existen funciones específicas de manejo de bases de datos que actualizan matrices con el resultado devuelto por la base de datos, numerosas otras funciones devuelven matrices como resultado.

Consultar la sección del manual Matrices si quereis una explicación detallada de como las matrices están implementadas en PHP.


Requerimientos

Estas funciones están disponibles como parte del módulo estandar, el cual está siempre disponible.


Instalación

No se necesita ninguna instalación para usar estas funciones, son parte del núcleo de PHP.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

Esta extensión no define ningún tipo de recurso.


Constantes predefinidas

CASE_UPPER y CASE_LOWER son usadas con la función array_change_key_case(). Son usadas respectivamente para cambiar una cadena literal de mayúsculas a minúsculas.


Ver tambien

Ver tambien is_array(), explode(), implode(), split(), y join().

Tabla de contenidos
array_change_key_case -- Returns an array with all string keys lowercased or uppercased
array_chunk -- Split an array into chunks
array_count_values -- Cuenta todos los valores de una matriz
array_diff_assoc -- Computes the difference of arrays with additional index check
array_diff -- Computes the difference of arrays
array_fill -- Fill an array with values
array_filter --  Filters elements of an array using a callback function
array_flip -- Intercambia los valores de una matriz
array_intersect_assoc -- Computes the intersection of arrays with additional index check
array_intersect -- Computes the intersection of arrays
array_key_exists -- Checks if the given key or index exists in the array
array_keys -- Devuelve todas las claves de una matriz
array_map --  Applies the callback to the elements of the given arrays
array_merge_recursive -- Merge two or more arrays recursively
array_merge -- Combina dos o más matrices
array_multisort -- Sort multiple or multi-dimensional arrays
array_pad --  Rellena una matriz con un valor hasta el tamaño especificado
array_pop -- Extrae el último elemento de la matriz
array_push --  Inserta uno o más elementos al final de la matriz
array_rand --  Pick one or more random entries out of an array
array_reduce --  Iteratively reduce the array to a single value using a callback function
array_reverse --  Devuelve una matriz con los elementos en orden inverso
array_search --  Searches the array for a given value and returns the corresponding key if successful
array_shift --  Extrae un elemento del comienzo de la matriz
array_slice -- Extrae una porción de la matriz
array_splice --  Suprime una porción de la matriz y la sustituye por otra cosa
array_sum --  Calculate the sum of values in an array.
array_unique -- Removes duplicate values from an array
array_unshift -- Introduce uno o más elementos al principio de la matriz
array_values -- Devuelve todos los valores de una matriz
array_walk --  Aplica una función del usuario a cada elemento de una matriz.
array --  Crear una matriz
arsort --  Ordena una matriz en orden inverso y mantiene la asociación de índices
asort -- Ordena una matriz y mantiene la asociación de índices
compact --  Crea una matriz que contiene variables y sus valores
count -- Cuenta los elementos de una variable
current -- Devuelve el elemento actual de una matriz
each --  Devuelve el siguiente par clave/valor de una matriz
end --  Mueve el puntero interno de una tabla al último elemento
extract --  Importa variables a la tabla de símbolos desde una matriz
in_array -- Devuelve TRUE si un valor está en una matriz
key -- Obtiene una clave de una matriz asociativa
krsort -- Ordena una matriz por clave en orden inverso
ksort -- Ordena una matriz por clave
list --  Asigna variables como si fueran una matriz
natcasesort --  Sort an array using a case insensitive "natural order" algorithm
natsort --  Sort an array using a "natural order" algorithm
next --  Avanza el puntero interno de una matriz
pos -- Obtiene el elemento actual de una matriz
prev -- Rebobina el puntero interno de una matriz
rango --  Crea una matriz que contiene un rango de enteros
reset --  Fija el puntero interno de una matriz a su primer elemento
rsort -- Ordena una matriz en orden inverso
shuffle -- Mezcla una matriz
sizeof -- Obtiene el número de elementos de una matriz
sort -- Ordena una matriz
uasort --  Ordena una matriz mediante una función de comparación definida por el usuario y mantiene la asociación de índices
uksort --  Ordena una matriz por claves mediante una función definida por el usuario
usort --  Ordena una matriz por valores mediante una funcion definida por el usuario

array_change_key_case

(PHP 4 >= 4.2.0)

array_change_key_case -- Returns an array with all string keys lowercased or uppercased

Description

array array_change_key_case ( array input [, int case])

array_change_key_case() changes the keys in the input array to be all lowercase or uppercase. The change depends on the last optional case parameter. You can pass two constants there, CASE_UPPER and CASE_LOWER. The default is CASE_LOWER. The function will leave number indices as is.

Ejemplo 1. array_change_key_case() example

$input_array = array("FirSt" => 1, "SecOnd" => 4);
print_r(array_change_key_case($input_array, CASE_UPPER));

The printout of the above program will be:
Array
(
    [FIRST] => 1
    [SECOND] => 2
)

array_chunk

(PHP 4 >= 4.2.0)

array_chunk -- Split an array into chunks

Description

array array_chunk ( array input, int size [, bool preserve_keys])

array_chunk() splits the array into several arrays with size values in them. You may also have an array with less values at the end. You get the arrays as members of a multidimensional array indexed with numbers starting from zero.

By setting the optional preserve_keys parameter to TRUE, you can force PHP to preserve the original keys from the input array. If you specify FALSE new number indices will be used in each resulting array with indices starting from zero. The default is FALSE.

Ejemplo 1. array_chunk() example

$input_array = array('a', 'b', 'c', 'd', 'e');
print_r(array_chunk($input_array, 2));
print_r(array_chunk($input_array, 2, TRUE));

The printout of the above program will be:
Array
(
    [0] => Array
        (
            [0] => a
            [1] => b
        )

    [1] => Array
        (
            [0] => c
            [1] => d
        )

    [2] => Array
        (
            [0] => e
        )

)
Array
(
    [0] => Array
        (
            [0] => a
            [1] => b
        )

    [1] => Array
        (
            [2] => c
            [3] => d
        )

    [2] => Array
        (
            [4] => e
        )

)

array_count_values

(PHP 4 )

array_count_values -- Cuenta todos los valores de una matriz

Descripción

array array_count_values ( array entrada)

array_count_values() devuelve una matriz usando los valores de la matriz entrada como claves y su frecuencia de aparición en la entrada como valores.

Ejemplo 1. Ejemplo de array_count_values()

$matriz = array(1, "hola", 1, "mundo", "hola");
array_count_values($matriz); // devuelve array(1=>2, "hola"=>2, "mundo"=>1)

Nota: Esta función fue añadida en el PHP 4.0.

array_diff_assoc

(PHP 4 >= 4.3.0)

array_diff_assoc -- Computes the difference of arrays with additional index check

Description

array array_diff_assoc ( array array1, array array2 [, array ...])

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

Ejemplo 1. array_diff_assoc() example

<?php
$array1 = array ("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array ("a" => "green", "yellow", "red");
$result = array_diff_assoc ($array1, $array2);

/* The result is:
Array
(
    [b] => brown
    [c] => blue
    [0] => red
)
*/
?>

In our example above 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.

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.

Nota: 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_diff_assoc($array1[0], $array2[0]);.

See also array_diff(), array_intersect(), and array_intersect_assoc().

array_diff

(PHP 4 >= 4.0.1)

array_diff -- Computes the difference of arrays

Description

array array_diff ( array array1, array array2 [, array ...])

array_diff() returns an array containing all the values of array1 that are not present in any of the other arguments. Note that keys are preserved.

Ejemplo 1. array_diff() example

$array1 = array ("a" => "green", "red", "blue", "red");
$array2 = array ("b" => "green", "yellow", "red");
$result = array_diff ($array1, $array2);

This makes $result have array ("blue");. Multiple occurrences in $array1 are all treated the same way.

Nota: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.

Nota: Please note that 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]);.

Aviso

This was broken in PHP 4.0.4!

See also array_diff_assoc(), array_intersect() and array_intersect_assoc().

array_fill

(PHP 4 >= 4.2.0)

array_fill -- Fill an array with values

Description

array array_fill ( int start_index, int num, mixed value)

array_fill() fills an array with num entries of the value of the value parameter, keys starting at the start_index parameter.

Ejemplo 1. array_fill() example

$a = array_fill(5, 6, 'banana');

$a now has the following entries using print_r():
Array
(
    [5]  => banana
    [6]  => banana
    [7]  => banana
    [8]  => banana
    [9]  => banana
    [10] => banana
)

array_filter

(PHP 4 >= 4.0.6)

array_filter --  Filters elements of an array using a callback function

Description

array array_filter ( array input [, callback function])

array_filter() returns an array containing all the elements of input filtered according a callback function. If the input is an associative array the keys are preserved.

Ejemplo 1. array_filter() example

function odd($var) {
    return ($var % 2 == 1);
}

function even($var) {
    return ($var % 2 == 0);
}

$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5);
$array2 = array (6, 7, 8, 9, 10, 11, 12);

echo "Odd :\n";
print_r(array_filter($array1, "odd"));
echo "Even:\n";
print_r(array_filter($array2, "even"));

The printout of the program above will be:
Odd :
Array
(
    [a] => 1
    [c] => 3
    [e] => 5
)
Even:
Array
(
    [0] => 6
    [2] => 8
    [4] => 10
    [6] => 12
)

Users may not change the array itself from the callback function. e.g. Add/delete an element, unset the array that array_filter() is applied to. If the array is changed, the behavior of this function is undefined.

See also array_map() and array_reduce().

array_flip

(PHP 4 )

array_flip -- Intercambia los valores de una matriz

Descripción

array array_flip ( array trans)

array_flip() devuelve una matriz con los valores intercambiados.

Ejemplo 1. Ejemplo de array_flip()

$trans = array_flip ($trans);
$original = strtr ($str, $trans);

Nota: Esta función fue añadida en el PHP 4.0.

array_intersect_assoc

(PHP 4 >= 4.3.0)

array_intersect_assoc -- Computes the intersection of arrays with additional index check

Description

array array_intersect_assoc ( array array1, array array2 [, array ...])

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

Ejemplo 1. array_intersect_assoc() example

<?php
$array1 = array ("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array ("a" => "green", "yellow", "red");
$result_array = array_intersect_assoc ($array1, $array2);

/* $result_array will look like:

Array
(
    [a] => green
)

*/
?>

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 it's key is 2 while the key of "red" in $array2 it is 1.

The two values from the key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In otherwords a strict type check is executed so the string representation must be the same.

See also array_intersect(), array_diff() and array_diff_assoc().

array_intersect

(PHP 4 >= 4.0.1)

array_intersect -- Computes the intersection of arrays

Description

array array_intersect ( array array1, array array2 [, array ...])

array_intersect() returns an array containing all the values of array1 that are present in all the arguments. Note that keys are preserved.

Ejemplo 1. array_intersect() example

$array1 = array ("a" => "green", "red", "blue");
$array2 = array ("b" => "green", "yellow", "red");
$result = array_intersect ($array1, $array2);

This makes $result have
Array
(
    [a] => green
    [0] => red
)

Nota: Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same.

Aviso

This was broken in PHP 4.0.4!

See also array_intersect_assoc(), array_diff(), array_diff_assoc().

array_key_exists

(PHP 4 >= 4.1.0)

array_key_exists -- Checks if the given key or index exists in the array

Description

bool array_key_exists ( mixed key, array search)

array_key_exists() returns TRUE if the given key is set in the array. key can be any value possible for an array index.

Ejemplo 1. array_key_exists() example

$search_array = array("first" => 1, "second" => 4);
if (array_key_exists("first", $search_array)) {
    echo "The 'first' element is in the array";
}

Nota: The name of this function is key_exists() in PHP version 4.0.6.

See also isset().

array_keys

(PHP 4 )

array_keys -- Devuelve todas las claves de una matriz

Descripción

array array_keys ( array entrada [, mixed val_a_buscar])

array_keys() devuelve las claves, numéricas y de cadena, de la matriz entrada.

Si se especifica el parámetro opcional val_a_buscar, sólo se devuelven las claves para dicho valor. De otro modo, se devuelven todas las claves de la entrada.

Ejemplo 1. Ejemplo de array_keys()

$matriz = array(0 => 100, "color" => "rojo");
array_keys ($matriz);       // devuelve array (0, "color")

$matriz = array(1, 100, 2, 100);
array_keys ($matriz, 100);  // devuelve array (0, 2)

Vea también: array_values().

Nota: Esta función fue añadida en el PHP 4.0.

array_map

(PHP 4 >= 4.0.6)

array_map --  Applies the callback to the elements of the given arrays

Description

array array_map ( callback function, array arr1 [, array arr2...])

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

Ejemplo 1. array_map() example

<?php
function cube($n) {
    return $n*$n*$n;
}

$a = array(1, 2, 3, 4, 5);
$b = array_map("cube", $a);
print_r($b);
?>

This makes $b have:
Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)

Ejemplo 2. array_map() - using more arrays

<?php
function show_Spanish($n, $m) {
    return "The number $n is called $m in Spanish";
}

function map_Spanish($n, $m) {
    return array ($n => $m);
}

$a = array(1, 2, 3, 4, 5);
$b = array("uno", "dos", "tres", "cuatro", "cinco");

$c = array_map("show_Spanish", $a, $b);
print_r($c);

$d = array_map("map_Spanish", $a , $b);
print_r($d);
?>

This results:
// printout of $c
Array
(
    [0] => The number 1 is called uno in Spanish
    [1] => The number 2 is called dos in Spanish
    [2] => The number 3 is called tres in Spanish
    [3] => The number 4 is called cuatro in Spanish
    [4] => The number 5 is called cinco in Spanish
)

// printout of $d
Array
(
    [0] => Array
        (
            [1] => uno
        )

    [1] => Array
        (
            [2] => dos
        )

    [2] => Array
        (
            [3] => tres
        )

    [3] => Array
        (
            [4] => cuatro
        )

    [4] => Array
        (
            [5] => cinco
        )

)

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

Ejemplo 3. Creating an array of arrays

<?php
$a = array(1, 2, 3, 4, 5);
$b = array("one", "two", "three", "four", "five");
$c = array("uno", "dos", "tres", "cuatro", "cinco");

$d = array_map(null, $a, $b, $c);
print_r($d);
?>

The printout of the program above will be:
Array
(
    [0] => Array
        (
            [0] => 1
            [1] => one
            [2] => uno
        )

    [1] => Array
        (
            [0] => 2
            [1] => two
            [2] => dos
        )

    [2] => Array
        (
            [0] => 3
            [1] => three
            [2] => tres
        )

    [3] => Array
        (
            [0] => 4
            [1] => four
            [2] => cuatro
        )

    [4] => Array
        (
            [0] => 5
            [1] => five
            [2] => cinco
        )

)

See also array_filter(), array_reduce(), and array_walk().

array_merge_recursive

(PHP 4 >= 4.0.1)

array_merge_recursive -- Merge two or more arrays recursively

Description

array array_merge_recursive ( array array1, array array2 [, array ...])

array_merge_recursive() merges the elements of two 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.

Ejemplo 1. array_merge_recursive() example

$ar1 = array ("color" => array ("favorite" => "red"), 5);
$ar2 = array (10, "color" => array ("favorite" => "green", "blue"));
$result = array_merge_recursive ($ar1, $ar2);

The $result will be:
Array
(
    [color] => Array
        (
            [favorite] => Array
                (
                    [0] => red
                    [1] => green
                )

            [0] => blue
        )

    [0] => 5
    [1] => 10
)

See also array_merge().

array_merge

(PHP 4 )

array_merge -- Combina dos o más matrices

Descripción

array array_merge ( array matriz1, array matriz2 [, ...])

array_merge() combina los elementos de dos o más matrices conjuntamente de modo que los valores de una son agregados al final de los valores de la anterior. Devuelve la matriz resultante.

Si las matrices de entrada tienen las mismas claves de cadena, el último valor para cada clave reemplazará el valor previo de la misma. Si, por el contrario, las matrices tienen la misma clave numérica, esto no pasa y los valores son simplemente agregados.

Ejemplo 1. Ejemplo de array_merge()

$matriz1 = array ("color" => "rojo", 2, 4);
$matriz2 = array ("a", "b", "color" => "verde", "forma" => "trapezoide");
array_merge ($matriz1, $matriz2);

La matriz resultante sería array("color" => "verde", 2, 4, "a", "b", "forma" => "trapezoide").

Nota: Esta función fue añadida en el PHP 4.0.

array_multisort

(PHP 4 )

array_multisort -- Sort multiple or multi-dimensional arrays

Description

bool array_multisort ( array ar1 [, mixed arg [, mixed ... [, array ...]]])

array_multisort() can be used to sort several arrays at once or a multi-dimensional array according by one of more dimensions. It maintains key association when sorting.

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

Devuelve TRUE si todo fue bien, FALSE en caso de fallo.

Ejemplo 1. Sorting multiple arrays

$ar1 = array ("10", 100, 100, "a");
$ar2 = array (1, 3, "2", 1);
array_multisort ($ar1, $ar2);

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.

Ejemplo 2. Sorting multi-dimensional array

$ar = array (array ("10", 100, 100, "a"), array (1, 3, "2", 1));
array_multisort ($ar[0], SORT_ASC, SORT_STRING,
                 $ar[1], SORT_NUMERIC, SORT_DESC);

In this example, after sorting, the first array will contain 10, 100, 100, "a" (it was sorted as strings in ascending order), and the second one will contain 1, 3, "2", 1 (sorted as numbers, in descending order).

array_pad

(PHP 4 )

array_pad --  Rellena una matriz con un valor hasta el tamaño especificado

Descripción

array array_pad ( array entrada, int tama_relleno, mixed valor_relleno)

array_pad() Devuelve una copia de la entrada rellenada hasta el tamaño tama_relleno con el valor valor_relleno. Si tama_relleno es positivo, entonces la matriz es rellenada por la derecha, y si es negativo, por la izquierda. Si el valor absoluto de tama_relleno es menor o igual que el tamaño de la entrada no se produce relleno alguno.

Ejemplo 1. Ejemplo de array_pad()

$entrada = array (12, 10, 9);

$resultado = array_pad ($entrada, 5, 0);
// el resultado es array (12, 10, 9, 0, 0)

$resultado = array_pad ($entrada, -7, -1);
// el resultado es array (-1, -1, -1, -1, 12, 10, 9)

$resultado = array_pad ($entrada, 2, "no");
// no rellenado

array_pop

(PHP 4 )

array_pop -- Extrae el último elemento de la matriz

Descripción

mixed array_pop ( array matriz)

array_pop() extrae y devuelve el último valor de la matriz, acortando la matriz en un elemento.

Ejemplo 1. Ejemplo de array_pop()

$pila = array ("naranja", "manzana", "frambuesa");
$fruta = array_pop ($pila);

Tras esto, $pila contiene sólo 2 elementos: "naranja" y "manzana", y $fruta contiene "frambuesa".

Vea también: array_push(), array_shift(), y array_unshift().

Nota: Esta función fue añadida en el PHP 4.0.

array_push

(PHP 4 )

array_push --  Inserta uno o más elementos al final de la matriz

Descripción

int array_push ( array matriz, mixed var [, ...])

array_push() considera a la matriz como una pila, e inserta las variables que se le pasan al final de la matriz. La longitud de la matriz se incrementa en el número de variables insertadas. Tiene el mismo efecto que ejecutar:
$matriz[] = $var;
para cada var.

Devuelve el nuevo número de elementos de la matriz.

Ejemplo 1. Ejemplo de array_push()

$pila = array (1, 2);
array_push($pila, "+", 3);
Este ejemplo dejará $pila conteniendo 4 elementos: 1, 2, "+", y 3.

Vea también: array_pop(), array_shift(), y array_unshift().

Nota: Esta función fue añadida en el PHP 4.0.

array_rand

(PHP 4 )

array_rand --  Pick one or more random entries out of an array

Description

mixed array_rand ( array input [, int num_req])

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.

Don't forget to call srand() to seed the random number generator.

Ejemplo 1. array_rand() example

srand ((float) microtime() * 10000000);
$input = array ("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
$rand_keys = array_rand ($input, 2);
print $input[$rand_keys[0]]."\n";
print $input[$rand_keys[1]]."\n";

array_reduce

(PHP 4 >= 4.0.5)

array_reduce --  Iteratively reduce the array to a single value using a callback function

Description

mixed array_reduce ( array input, callback function [, int initial])

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.

Ejemplo 1. array_reduce() example

function rsum($v, $w) {
    $v += $w;
    return $v;
}

function rmul($v, $w) {
    $v *= $w;
    return $v;
}

$a = array(1, 2, 3, 4, 5);
$x = array();
$b = array_reduce($a, "rsum");
$c = array_reduce($a, "rmul", 10);
$d = array_reduce($x, "rsum", 1);

This will result in $b containing 15, $c containing 1200 (= 1*2*3*4*5*10), and $d containing 1.

See also array_filter() and array_map().

array_reverse

(PHP 4 )

array_reverse --  Devuelve una matriz con los elementos en orden inverso

Descripción

array array_reverse ( array matriz)

array_reverse() toma la matriz de entrada y devuelve una nueva matriz con los elementos en orden inverso.

Ejemplo 1. Ejemplo de array_reverse()

$entrada = array ("php", 4.0, array ("verde", "rojo"));
$resultado = array_reverse ($entrada);
Esto hace que $resultado contenga array (array ("verde", "rojo"), 4.0, "php").

Nota: Esta función fue añadida en PHP 4.0 Beta 3.

array_search

(PHP 4 >= 4.0.5)

array_search --  Searches the array for a given value and returns the corresponding key if successful

Description

mixed array_search ( mixed needle, array haystack [, bool strict])

Searches haystack for needle and returns the key if it is found in the array, FALSE otherwise.

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

Aviso

Esta función puede devolver el Boolean FALSE, pero también puede devolver un valor no-Boolean que será evaluado FALSE, como por ejemplo 0 o "". Por favor, lea la sección Booleans para más información. Utilice el operador === para comprobar el valor devuelto por esta función.

See also array_keys() and in_array().

array_shift

(PHP 4 )

array_shift --  Extrae un elemento del comienzo de la matriz

Descripción

mixed array_shift ( array matriz)

array_shift() extrae el primer valor de la matriz y lo devuele, acortando la matriz en un elemnto y moviendo todo hacia arriba.

Ejemplo 1. Ejemplo de array_shift()

$args = array ("-v", "-f");
$opcion = array_shift ($args);
Esto da como resultado que $args tenga como elemento restante "-f" y que $opcion valga "-v".

Vea también: array_unshift(), array_push(), y array_pop().

Nota: Esta función fue añadida en el PHP 4.0.

array_slice

(PHP 4 )

array_slice -- Extrae una porción de la matriz

Descripción

array array_slice ( array matriz, int desplazamiento [, int tamano])

array_slice() devuelve una secuencia de elementos de la matriz especificada por los parámetros desplazamiento y tamano.

Si el desplazamiento es positivo, la secuencia comenzará en dicha posición de la matriz. Si el desplazamiento es negativo, la secuencia comenzará en esa posición desde el final de la matriz.

Si se especifica el tamano y éste es positivo, la secuencia contendrá tantos elementos como se diga en él. Si fuese negativo, la secuencia se detendrá a tantos elementos del final de la matriz. Si se omite, la secuencia contendrá todos los elementos desde el desplazamiento hasta el final de la matriz.

Ejemplo 1. Ejemplo de array_slice() examples

$entrada = array ("a", "b", "c", "d", "e");

$salida = array_slice ($entrada, 2);      // devuelve "c", "d", y "e"
$salida = array_slice ($entrada, 2, -1);  // devuelve "c", "d"
$salida = array_slice ($entrada, -2, 1);  // devuelve "d"
$salida = array_slice ($entrada, 0, 3);   // devuelve "a", "b", y "c"

Vea también: array_splice().

Nota: Esta función fue añadida en el PHP 4.0.

array_splice

(PHP 4 )

array_splice --  Suprime una porción de la matriz y la sustituye por otra cosa

Descripción

array array_splice ( array entrada, int desplazamiento [, int tamano [, array sustitucion]])

array_splice() suprime los elementos designados por el desplazamiento y el tamano de la matriz entrada, y los sustituye con los elementos de la matriz de sustitucion si se especifica.

Si el desplazamiento es positivo, el comienzo de la parte suprimida sería en esa posición desde el comienzo de la matriz de entrada. Si el desplazamiento es negativo, se cuenta la posición desde el final de la matriz de entrada.

Si se omite tamano, se suprime todo desde el desplazamiento hasta el final de la matriz. Si se especifica el tamano y es positivo, se suprimirán tantos elementos como se especifica. Si fuera negativo, el final de la porción eliminada estará a tantos elementos del final de la matriz. Truco: para eliminar todo desde el desplazamiento hasta el final de la matriz cuando también se especifica sustitucion, utilice count($entrada) como tamano.

Si se especifia la matriz de sustitucion, entonces los elementos suprimidos son reemplazados con los elementos de dicha matriz. Si los valores de desplazamiento y tamano son tales que nada es borrado, los elementos de la matriz sustitucion se insertarán en la posición indicada por el desplazamiento. Truco: si sólo se va a sustituir algo por un elemento nada más, no hace falta poner array() alrededor del mismo, salvo que dicho elemento sea una matriz en sí mismo.

Las siguientes funciones son equivalentes:
array_push($entrada, $x, $y)     array_splice($entrada, count($entrada), 0, array($x, $y))
array_pop($entrada)              array_splice($entrada, -1)
array_shift($entrada)            array_splice($entrada, 0, 1)
array_unshift($entrada, $x, $y)  array_splice($entrada, 0, 0, array($x, $y))
$a[$x] = $y                    array_splice($entrada, $x, 1, $y)

Devuelve una matriz que tiene los elementos eliminados

Ejemplo 1. Ejemplos de array_splice()

$entrada = array("rojo", "verde", "azul", "amarillo");

array_splice($entrada, 2);      // $entrada vale ahora array("rojo", "verde")
array_splice($entrada, 1, -1);  // $entrada vale ahora array("rojo", "amarillo")
array_splice($entrada, 1, count($entrada), "naranja");  
                              // $entrada vale ahora array("rojo", "naranja")
array_splice($entrada, -1, 1, array("negro", "marrón")); 
                              // $entrada vale ahora array("rojo", "verde", 
                              //          "azul", "negro", "marrón")

Vea también: array_slice().

Nota: Esta función fue añadida en el PHP 4.0.

array_sum

(PHP 4 >= 4.0.4)

array_sum --  Calculate the sum of values in an array.

Description

mixed array_sum ( array array)

array_sum() returns the sum of values in an array as an integer or float.

Ejemplo 1. array_sum() examples

$a = array(2, 4, 6, 8);
echo "sum(a) = ".array_sum($a)."\n";

$b = array("a"=>1.2,"b"=>2.3,"c"=>3.4);
echo "sum(b) = ".array_sum($b)."\n";

The printout of the program above will be:
sum(a) = 20
sum(b) = 6.9

Nota: PHP versions prior to 4.0.6 modified the passed array itself and converted strings to numbers (which most of the time converted them to zero, depending on their value).

array_unique

(PHP 4 >= 4.0.1)

array_unique -- Removes duplicate values from an array

Description

array array_unique ( array array)

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.

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

Aviso

This was broken in PHP 4.0.4!

Ejemplo 1. array_unique() example

$input = array ("a" => "green", "red", "b" => "green", "blue", "red");
$result = array_unique ($input);
print_r($result);

This will output:
Array
(
    [b] => green
    [1] => blue
    [2] => red
)

Ejemplo 2. array_unique() and types

$input = array (4,"4","3",4,3,"3");
$result = array_unique ($input);
var_dump($result);

The printout of the program above will be (PHP 4.0.6):
array(2) {
  [3]=>
  int(4)
  [4]=>
  int(3)
}

array_unshift

(PHP 4 )

array_unshift -- Introduce uno o más elementos al principio de la matriz

Descripción

int array_unshift ( array matriz, mixed var [, ...])

array_unshift() añade los elementos que se le pasan al principio de la matriz. Nótese que la lista de elementos es añadida como un todo, de modo que los elementos añadidos mantienen su orden.

Devuelve el número de elementos en la matriz.

Ejemplo 1. Ejemplo de array_unshift()

$cola = array("p1", "p3");
array_unshift($cola, "p4", "p5", "p6");
Esto hará que $cola contenga 5 elementos: "p4", "p5", "p6", "p1", y "p3".

Vea también: array_shift(), array_push(), y array_pop().

Nota: Esta función fue añadida en el PHP 4.0.

array_values

(PHP 4 )

array_values -- Devuelve todos los valores de una matriz

Descripción

array array_values ( array entrada)

array_values() devuelve todos los valores de la matriz entrada.

Ejemplo 1. Ejemplo de array_values()

$matriz = array("talla" => "XL", "color" => "dorado");
array_values($matriz);    // devuelve array("XL", "dorado")

Nota: Esta función fue añadida en el PHP 4.0.

array_walk

(PHP 3>= 3.0.3, PHP 4 )

array_walk --  Aplica una función del usuario a cada elemento de una matriz.

Descripción

int array_walk ( array matriz, string func, mixed datosvarios)

Aplica la función llamada func a cada elemento de la matriz. La función func recibirá el valor de la matriz como primer parámetro y la clave como segundo. Si se proporciona el parámetro datosvarios será pasado como tercer parámetro a la función de usuario.

Si func necesita más de dos o 3 argumentos, dependiendo de datosvarios, se generará un aviso cada vez que array_walk() llama a func. Estos avisos pueden suprimirse si se pone '@' antes de la llamada a array_walk(), o usando la función error_reporting().

Nota: Si func precisa trabajar con los valores reales de la matriz, especifique que el valor del primer parámetro de func debe pasarse por referencia. Desde ese instante, los cambios realizados sobre dichos elementos también serán realizados en la propia matriz.

Nota: El pasar la clave y los datos de usuario a func fue una característica añadida en PHP 4.0.

En PHP 4 se debe llamar reset() las veces necesarias, pues array_walk() no reajusta la matriz por defecto.

Ejemplo 1. Ejemplo de array_walk()

$frutas = array ("d"=>"limón", "a"=>"naranja", "b"=>"plátano", "c"=>"manzana");

function test_alterar (&$item1, $clave, $prefix) {
   $item1 = "$prefix: $item1";
}

function test_ver ($item2, $clave) {
   echo "$clave. $item2<br>\n";
}

array_walk ($frutas, 'test_ver');
reset ($frutas);
array_walk ($frutas, 'test_alterar', 'fruta');
reset ($frutas);
array_walk ($frutas, 'test_ver');

Vea también: each() y list().

array

(PHP 3, PHP 4 )

array --  Crear una matriz

Descripción

array array ( mixed ...)

Devuelve una matriz con los parámetros que se le pasan. A dichos parámetros se les puede dar un índice usando el operador =>.

Nota: array() es una construcción del lenguaje que se utiliza para representar matrices literales, no una función regular.

El siguiente ejemplo demuestra cómo crear una matriz bidimensional, cómo especificar claves para matrices asociativas, y cómo especificar índices no consecutivos en matrices normales.

Ejemplo 1. Ejemplo de array()

$frutas = array (
    "frutas"  => array("a"=>"naranja", "b"=>"plátano", "c"=>"manzana"),
    "números" => array(1, 2, 3, 4, 5, 6),
    "hoyos"   => array("primero", 5 => "segundo", "tercero")
);

Vea también: list().

arsort

(PHP 3, PHP 4 )

arsort --  Ordena una matriz en orden inverso y mantiene la asociación de índices

Descripción

void arsort ( array matriz)

Esta función ordena una matriz de modo que los índices mantengan su correlación con los elementos de la misma a los que están asociados. Esto se utiliza principalmente para ordenar matrices asociativas en las que el orden de los elementos es importante.

Ejemplo 1. Ejemplo de arsort()

$frutas = array ("d"=>"limón", "a"=>"naranja", "b"=>"plátano", "c"=>"manzana");
arsort ($frutas);
for (reset ($frutas); $clave = key ($frutas); next ($frutas)) {
    echo "frutas[$clave] = ".$frutas[$clave]."\n";
}
Este ejemplo mostraría: frutas[b] = plátano frutas[a] = naranja frutas[c] = manzana frutas[d] = limón Las frutas han sido ordenadas en orden alfabético inverso y los índices asociados con cada elemento se han mantenido.

Vea también: asort(), rsort(), ksort(), y sort().

asort

(PHP 3, PHP 4 )

asort -- Ordena una matriz y mantiene la asociación de índices

Descripción

void asort ( array matriz)

Esta función ordena una matriz de modo que los índices mantengan su correlación con los elementos de la misma a los que están asociados. Esto se utiliza principalmente para ordenar matrices asociativas en las que el orden de los elementos es importante.

Ejemplo 1. Ejemplo de asort()

$frutas = array ("d"=>"limón", "a"=>"naranja", "b"=>"plátano", "c"=>"manzana");
asort ($frutas);
for (reset ($frutas); $clave = key ($frutas); next ($frutas)) {
    echo "frutas[$clave] = ".$frutas[$clave]."\n";
}
Este ejemplo mostrará: frutas[d] = limón frutas[a] = naranja frutas[c] = manzana frutas[d] = plátano Las frutas han sido ordenadas en orden alfabético y los índices asociados con cada elemento se han mantenido.

Vea también: arsort(), rsort(), ksort(), y sort().

compact

(PHP 4 )

compact --  Crea una matriz que contiene variables y sus valores

Descripción

array compact ( string nombrevar | array nombrevars [, ...])

compact() toma un número variable de parámetros. Cada uno puede ser tanto una cadena que contiene el nombre de la variable, como una matriz de nombres de variable. La matriz puede contener otras matrices de nombres de variable en su interior; compact() los procesa recursivamente.

Para cada uno de estos, compact() busca una variable con dicho nombre en la tabla de símbolos y la añade a la matriz de salida de modo que el nombre de la variable es la clave y el contenido de ésta es el valor para dicha clave. Para resumir, hace lo contrario de extract(). Devuelve la matriz de salida con las variables añadidas a la misma.

Ejemplo 1. Ejemplo de compact()

$ciudad = "San Francisco";
$estado = "CA";
$evento = "SIGGRAPH";

$location_vars = array ("ciudad", "estado");

$resultado = compact ("evento", $location_vars);

Tras esto, $resultado valdrá array ("evento" => "SIGGRAPH", "ciudad" => "San Francisco", "estado" => "CA").

Vea también: extract().

Nota: Esta función fue añadida en el PHP 4.0.

count

(PHP 3, PHP 4 )

count -- Cuenta los elementos de una variable

Descripción

int count ( mixed var)

Devuelve el número de elementos en var, que típicamente es una matriz (porque cualquier otra cosa tendría sólo un elemento).

Devuele 1 si la variable no es una matriz.

Devuelve 0 si la variable no tiene valor.

Aviso

count() puede devolver 0 para una variable sin valor, pero también puede devolver 0 para una variable ya inicializada pero con una matriz vacía. Utilice isset() para comprobar si una variable está inicializada.

Vea también: sizeof(), isset(), y is_array().

current

(PHP 3, PHP 4 )

current -- Devuelve el elemento actual de una matriz

Descripción

mixed current ( array matriz)

Cada matriz tiene un puntero interno al elemento "actual", que se inicializa al primer elemento insertado en la misma.

La función current() simplemente devuelve el elemento de la tabla al que apunta el puntero interno. No mueve el puntero de ninguna manera. Si el puntero interno apunta fuera del final de la lista de elementos, current() devuelve FALSE.

Aviso

Si la matriz contiene elementos vacíos (0 ó "", la cadena vacía) esta función devolverá FALSE también para dichos elementos. Esto hace imposible determinar si se está realmente al final de la lista en tales matrices usando current(). Para recorrer adecuadamente una matriz que pueda contener elementos vacíos, utilice la función each().

Vea también: end(), next(), prev() y reset().

each

(PHP 3, PHP 4 )

each --  Devuelve el siguiente par clave/valor de una matriz

Descripción

array each ( array matriz)

Devuelve el par clave/valor actual para la matriz y avanza el cursor de la misma. Esta pareja se devuele en una matriz de 4 elementos, con las claves 0, 1, key, y value. Los elementos 0 y key contienen el nombre de clave del elemento de la matriz, y 1 y value contienen los datos.

Si el puntero interno para la matriz apunta pasado el final del contenido de la matriz, each() devuelve FALSE.

Ejemplo 1. Ejemplos de each()

$chorrada = array ("bob", "fred", "jussi", "jouni", "egon", "marliese");
$tonteria = each ($chorrada);

$tonteria contiene ahora los siguientes pares clave/valor:

  • 0 => 0
  • 1 => 'bob'
  • key => 0
  • value => 'bob'
$chorrada = array ("Robert" => "Bob", "Seppo" => "Sepi");
$tonteria = each ($chorrada);

$tonteria contiene ahora los siguientes pares clave/valor:

  • 0 => 'Robert'
  • 1 => 'Bob'
  • key => 'Robert'
  • value => 'Bob'

each() se usa normalmente de forma conjunta a list() para recorrer una matriz; por ejemplo, $HTTP_POST_VARS:

Ejemplo 2. Recorriendo $HTTP_POST_VARS con each()

echo "Valores enviados con el método POST:<br>";
reset ($HTTP_POST_VARS);
while (list ($clave, $val) = each ($HTTP_POST_VARS)) {
    echo "$clave => $val<br>";
}

Cuando se ha ejecutado each(), el cursor de la matriz quedará en el siguiente elemento de la misma, o en el último si llega al final de ésta.

Vea también: key(), list(), current(), reset(), next(), y prev().

end

(PHP 3, PHP 4 )

end --  Mueve el puntero interno de una tabla al último elemento

Descripción

end ( array matriz)

end() avanza el puntero interno de la matriz al último elemento.

Vea también: current(), each(), end(), next(), y reset().

extract

(PHP 3>= 3.0.7, PHP 4 )

extract --  Importa variables a la tabla de símbolos desde una matriz

Descripción

void extract ( array matriz_vars [, int tipo_extraccion [, string prefijo]])

Esta función se utiliza para importar variables desde una matriz a la tabla de símbolos actual. Toma la matriz asoiativa matriz_vars y trata las claves como nombres de variable y los valores como los valores de éstas. Para cada par clave/valor creará una variable en la tabla de símbolos actual, sujeto a los parámetros tipo_extraccion y prefijo.

extract() controla las colisiones con las variables que ya existen. La forma de tratar éstas se determina por el tipo_extraccion. Puede tener únicamente uno de los siguientes valores:

EXTR_OVERWRITE

Si hay colisión, sobreescribe la variable existente.

EXTR_SKIP

Si hay colisión, no sobreescribas la variable existente.

EXTR_PREFIX_SAME

Si hay una colisión, añade el prefijo a la nueva variable.

EXTR_PREFIX_ALL

Añade el prefijo a todas las variables.

Si no se especifica tipo_extraccion, se asume que vale EXTR_OVERWRITE.

Nótese que el prefijo sólo se necisita si tipo_extraccion vale EXTR_PREFIX_SAME o EXTR_PREFIX_ALL.

extract() comprueba si cada clave es un nombre válido de variable, y sólo lo importa si lo es.

Nota: N.T.: En el caso español, no valdría "año" como nombre variable (pero sí como clave en una matriz cualquiera).

Un uso posible para extract sería importar en la tabla de símbolos las variables contenidas en la matriz asociativa que devuelve wddx_deserialize().

Ejemplo 1. Ejemplo de extract()

<php?

/* Suponemos que $matriz_var es una matriz devuelta por 
   wddx_deserialize */

$tamano = "grande";
$matriz_var = array ("color" => "azul",
                    "tamano"  => "media",
                    "forma" => "esfera");
extract ($matriz_var, EXTR_PREFIX_SAME, "wddx");

print "$color, $tamano, $forma, $wddx_tamano\n";

?>

El programa anterior producirá:
azul, grande, esfera, media

La variable $tamano no fue sobreescrita porque especificamos EXTR_PREFIX_SAME, que provocó la creación de $wddx_tamano. Si se hubiera especificado EXTR_SKIP, $wddx_tamano ni siquiera habría sido creada. EXTR_OVERWRITE habría provocado que $tamano tuviera el valor "media", y EXTR_PREFIX_ALL habría provocado que aparecieran nuevas variables llamadas $wddx_color, $wddx_tamano, y $wddx_forma.

in_array

(PHP 4 )

in_array -- Devuelve TRUE si un valor está en una matriz

Descripción

bool in_array ( mixed aguja, array pajar)

Busca la aguja en el pajar, y devuelve TRUE si se encuentra y FALSE en caso contrario.

Ejemplo 1. Ejemplo de in_array()

$os = array ("Mac", "NT", "Irix", "Linux");
if (in_array ("Irix", $os))
    print "Encontrado Irix";

Nota: Esta función fue añadida en el PHP 4.0.

key

(PHP 3, PHP 4 )

key -- Obtiene una clave de una matriz asociativa

Descripción

mixed key ( array matriz)

key() devuelve el elemento índice de la posición actual en la matriz.

Vea también: current(), next()

krsort

(PHP 3>= 3.0.13, PHP 4 )

krsort -- Ordena una matriz por clave en orden inverso

Descripción

int krsort ( array matriz)

Ordena una matriz por clave en orden inverso, manteniendo las correlaciones clave a dato. Esto es útil principalmente en matrices asociativas.

Ejemplo 1. Ejemplo de krsort()

$frutas = array ("d"=>"limón", "a"=>"naranja", "b"=>"plátano", "c"=>"manzana");
krsort ($frutas);
for (reset ($frutas); $clave = key ($frutas); next ($frutas)) {
    echo "frutas[$clave] = ".$frutas[$clave]."\n";
}
Este ejemplo mostrará: frutas[d] = limón frutas[c] = manzana frutas[b] = plátano frutas[a] = naranja

Vea también: asort(), arsort(), ksort() sort(), y rsort().

ksort

(PHP 3, PHP 4 )

ksort -- Ordena una matriz por clave

Descripción

int ksort ( array matriz)

Ordena una matriz por clave, manteniendo las correlaciones clave a dato. Esto es útil principalmente en matrices asociativas.

Ejemplo 1. Ejemplo de ksort()

$frutas = array ("d"=>"limón", "a"=>"naranja", "b"=>"plátano", "c"=>"manzana");
ksort ($frutas);
for (reset ($frutas); $clave = key ($frutas); next ($frutas)) {
    echo "frutas[$clave] = ".$frutas[$clave]."\n";
}
Este ejemplo mostrará: frutas[a] = naranja frutas[b] = plátano frutas[c] = manzana frutas[d] = limón

Vea también: asort(), arsort(), sort(), y rsort().

list

(PHP 3, PHP 4 )

list --  Asigna variables como si fueran una matriz

Descripción

void list ( mixed ...)

Como array(), esta no es realmente una función, sino una construcción del lenguaje. list() se usa para asignar una lista de variables en una sola operación.

Ejemplo 1. Ejemplo de list()

<table>
 <tr>
  <th>Nombre empleado</th>
  <th>Sueldo</th>
 </tr>

<?php

$resultado = mysql($conn, "SELECT id, nombre, salario FROM empleados");
while (list($id, $nombre, $salario) = mysql_fetch_row($resultado)) {
    print(" <tr>\n".
          "  <td><a href=\"info.php3?id=$id\">$nombre</a></td>\n".
          "  <td>$salario</td>\n".
          " </tr>\n");
}

?>

</table>

Vea también: each(), array().

natcasesort

(PHP 4 )

natcasesort --  Sort an array using a case insensitive "natural order" algorithm

Description

void natcasesort ( array array)

This function implements a sort algorithm that orders alphanumeric strings in the way a human being would. This is described as a "natural ordering".

natcasesort() is a case insensitive version of natsort(). See natsort() for an example of the difference between this algorithm and the regular computer string sorting algorithms.

For more information see: Martin Pool's Natural Order String Comparison page.

See also sort(), natsort(), strnatcmp(), and strnatcasecmp().

natsort

(PHP 4 )

natsort --  Sort an array using a "natural order" algorithm

Description

void natsort ( array array)

This function implements a sort algorithm that orders alphanumeric strings in the way a human being would. 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:

Ejemplo 1. natsort() example

<?php
$array1 = $array2 = array ("img12.png", "img10.png", "img2.png", "img1.png");

sort($array1);
echo "Standard sorting\n";
print_r($array1);

natsort($array2);
echo "\nNatural order sorting\n";
print_r($array2);
?>

The code above will generate the following output:

Standard sorting
Array
(
    [0] => img1.png
    [1] => img10.png
    [2] => img12.png
    [3] => img2.png
)

Natural order sorting
Array
(
    [3] => img1.png
    [2] => img2.png
    [1] => img10.png
    [0] => img12.png
)
For more information see: Martin Pool's Natural Order String Comparison page.

Nota: If you're wanting to maintain index/value associations, consider using usort($arr, 'strnatcmp').

See also natcasesort(), strnatcmp(), and strnatcasecmp().

next

(PHP 3, PHP 4 )

next --  Avanza el puntero interno de una matriz

Descripción

mixed next ( array matriz)

Devuelve el elemento de la matriz que ocupa el lugar siguiente al apuntado por el puntero interno, o FALSE si no hay más elementos.

next() se comporta como current(), con una diferencia. Avanza el puntero interno de la matriz en una posición antes de devolver el elemento. Eso significa que devuelve el siguiente elemento de la matriz y que avanza el puntero interno en uno. Si al avanzar se pasa del final de la lista de elementos, next() devuelve FALSE.

Aviso

Si la matriz contiene elementos vacíos, esta función también devolverá FALSE para dichos elementos. Para recorrer adecuadamente una matriz que pueda contener elementos vacíos, vea la función each().

Vea también: current(), end() prev() y reset()

pos

(PHP 3, PHP 4 )

pos -- Obtiene el elemento actual de una matriz

Descripción

mixed pos ( array matriz)

Este es un alias para current().

Vea también: end(), next(), prev() y reset().

prev

(PHP 3, PHP 4 )

prev -- Rebobina el puntero interno de una matriz

Descripción

mixed prev ( array matriz)

Devuelve el elemento de la matriz que está en la posición anterior a la que apuntaba previamente el puntero interno, o FALSE si no hay más elementos.

Aviso

Si la matriz contiene elementos vacíos, esta función también devolverá FALSE para dichos elementos. Para recorrer adecuadamente una matriz que puede contener elementos vacíos, vea la función each().

prev() se comporta igual que next(), excepto que rebobina el puntero interno una posición en lugar de avanzarlo.

Vea también: current(), end() next() y reset()

rango

(no version information, might be only in CVS)

rango --  Crea una matriz que contiene un rango de enteros

Descripción

array rango ( int bajo, int alto)

rango() devuelve una matriz de enteros desde bajo hasta alto, ambos inclusive.

Vea un ejemplo de su uso en la función shuffle().

reset

(PHP 3, PHP 4 )

reset --  Fija el puntero interno de una matriz a su primer elemento

Descripción

mixed reset ( array matriz)

reset() rebobina el puntero interno de la matriz a su primer elemento.

reset() devuelve el valor del primer elemento de la matriz.

Vea también: current(), each(), next(), prev(), y reset().

rsort

(PHP 3, PHP 4 )

rsort -- Ordena una matriz en orden inverso

Descripción

void rsort ( array matriz)

Esta función ordena una matriz en orden inverso (mayor a menor).

Ejemplo 1. Ejemplo de rsort()

$frutas = array ("limón", "naranja", "plátano", "manzana");
rsort ($frutas);
for (reset ($frutas); list ($clave, $valor) = each ($frutas); ) {
    echo "frutas[$clave] = ", $valor, "\n";
}
Este ejemplo mostrará: frutas[0] = plátano frutas[1] = naranja frutas[2] = manzana frutas[3] = limón Las frutas han sido ordenadas en orden alfabético inverso.

Vea también: arsort(), asort(), ksort(), sort(), y usort().

shuffle

(PHP 3>= 3.0.8, PHP 4 )

shuffle -- Mezcla una matriz

Descripción

void shuffle ( array matriz)

Esta función mezcla (cambia aleatoriamente el orden de los elementos de) una matriz.

Ejemplo 1. Ejemplo de shuffle()

$numeros = range (1,20);
srand (time());
shuffle ($numeros);
while (list(, $numero) = each ($numeros)) {
    echo "$numero ";
}

Vea también: arsort(), asort(), ksort(), rsort(), sort() y usort().

sizeof

(PHP 3, PHP 4 )

sizeof -- Obtiene el número de elementos de una matriz

Descripción

int sizeof ( array matriz)

Devueve el número de elementos de la matriz.

Vea también: count()

sort

(PHP 3, PHP 4 )

sort -- Ordena una matriz

Descripción

void sort ( array matriz)

Esta función ordena una matriz. Los elementos estarán ordenados de menor a mayor cuando la función termine.

Ejemplo 1. Ejemplo de sort()

$frutas = array ("limón", "naranja", "plátano", "manzana");
sort ($frutas);
for (reset ($frutas); $clave = key ($frutas); next ($frutas)) {
    echo "frutas[$clave] = ".$frutas[$clave]."\n";
}
Este ejemplo mostrará: frutas[0] = limón frutas[1] = manzana frutas[2] = naranja frutas[3] = plátano Las frutas han sido ordenadas en orden alfabético.

Vea también: arsort(), asort(), ksort(), rsort(), y usort().

uasort

(PHP 3>= 3.0.4, PHP 4 )

uasort --  Ordena una matriz mediante una función de comparación definida por el usuario y mantiene la asociación de índices

Descripción

void uasort ( array matriz, function func_comparar)

Esta función ordena una matriz de modo que los índices de la misma mantengan su correlación con los elementos a los que están asociados. Esto se utiliza principalmente para ordenar matrices asociativas en las que el orden de los elementos es importante. La función de comparación viene definida por el usuario.

uksort

(PHP 3>= 3.0.4, PHP 4 )

uksort --  Ordena una matriz por claves mediante una función definida por el usuario

Descripción

void uksort ( array matriz, function func_comparar)

Esta función ordenará las claves de una matriz utilizando una función de comparación suministrada por el usuario. Si la matriz a ordenar necesita utilizar un criterio poco trivial, esta es la función que deberá usar.

Ejemplo 1. Ejemplo de uksort()

function micomparar ($a, $b) {   
    if ($a == $b) return 0;
    return ($a > $b) ? -1 : 1;
}
$a = array (4 => "cuatro", 3 => "tres", 20 => "veinte", 10 => "diez");
uksort ($a, micomparar);
while (list ($clave, $valor) = each ($a)) {
    echo "$clave: $valor\n";
}
Este ejemplo mostrará: 20: veinte 10: diez 4: cuatro 3: tres

Vea también: arsort(), asort(), uasort(), ksort(), rsort(), y sort().

usort

(PHP 3>= 3.0.3, PHP 4 )

usort --  Ordena una matriz por valores mediante una funcion definida por el usuario

Descripción

void usort ( array matriz, function func_comparar)

Esta función ordenará una matriz por sus valores utilizando una función suministrada por el usuario. Si la matriz que desea ordenar necesita utilizar un criterio poco trivial, esta es la función que deberá usar.

La función de comparación deberá devolver un entero menor, igual, o mayor que cero, si el primer argumento se considera respectivamente menor que, igual que, o mayor que el segundo. Si dos miembros resultan ser iguales, su orden en la matriz ordenada será cualquiera.

Ejemplo 1. Ejemplo de usort()

function cmp ($a, $b) {   
    if ($a == $b) return 0;
    return ($a > $b) ? -1 : 1;
}
$a = array (3, 2, 5, 6, 1);
usort ($a, cmp);
while (list ($clave, $valor) = each ($a)) {
    echo "$clave: $valor\n";
}
Este ejemplo mostrará: 0: 6 1: 5 2: 3 3: 2 4: 1

Nota: Obviamente en este caso trivial la función rsort() habría sido más apropiada.

Aviso

La función quicksort subyacente en ciertas librerías de C (tales como las de Solaris) pueden hacer que el PHP falle si la función de comparación no devuelve valores consistentes.

Vea también: arsort(), asort(), ksort(), rsort() y sort().

III. Funciones Aspell [deprecated]

Introducción

La función aspell() permite comprobar la ortografía de una palabra y ofrece alternativas a la misma.


Requerimientos

aspell funciona solamente con versiones muy antiguas (hasta la .27.* mas ó menos) de la biblioteca aspell. Ni este módulo ni las versiones de la biblioteca aspell se soportan actualmente. Si quereis utilizar capacidades de comprobación ortográfica en php, usar pspell. Utiliza la biblioteca pspell y funciona con versiones recientes de aspell.


Instalación

Necesitais la biblioteca aspell disponible en: http://aspell.sourceforge.net/.


Ver tambien

Ver tambien pspell.

Tabla de contenidos
aspell_check-raw -- Comprueba una palabra sin cambiarla ó intentar arreglarla [deprecated]
aspell_check -- Comprueba una palabra[deprecated]
aspell_new -- Lee un nuevo diccionario [deprecated]
aspell_suggest -- Sugiere la ortografía para una palabra [deprecated]

aspell_check-raw

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_check-raw -- Comprueba una palabra sin cambiarla ó intentar arreglarla [deprecated]

Descripción

boolean aspell_check_raw ( int dictionary_link, string word)

aspell_check_raw() comprueba la ortografía de una palabra,sin cambiarla ni intentar arreglarla esté bien o mal. Si está bien, devuelve cierto (TRUE), si no lo está, devuelve falso(FALSE).

Ejemplo 1. aspell_check_raw

$aspell_link = aspell_new("english");

if (aspell_check_raw($aspell_link, "test")) {
    echo "This is a valid spelling";
} else {
    echo "Sorry, wrong spelling";
}

aspell_check

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_check -- Comprueba una palabra[deprecated]

Descripción

boolean aspell_check ( int dictionary_link, string word)

aspell_check() comprueba la ortografía de una palabra, y devuelve cierto(TRUE) si la ortografía es correcta ,falso (FALSE) si no lo es .

Ejemplo 1. aspell_check

$aspell_link = aspell_new("english");

if (aspell_check($aspell_link, "testt")) {
    echo "This is a valid spelling";
} else {
    echo "Sorry, wrong spelling";
}

aspell_new

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_new -- Lee un nuevo diccionario [deprecated]

Descripción

int aspell_new ( string master, string personal)

aspell_new() Abre un nuevo diccionario devolviendo el identificador de este para ser utilizado en otras funciones ortográficas.

Ejemplo 1. Nuevo_diccionario

$aspell_link = aspell_new("english");

aspell_suggest

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_suggest -- Sugiere la ortografía para una palabra [deprecated]

Descripción

array aspell_suggest ( int dictionary_link, string word)

aspell_suggest() devuelve una matriz con posibles correciones ortográficas para la palabra dada.

Ejemplo 1. aspell_suggest

$aspell_link = aspell_new("english");

if (!aspell_check($aspell_link, "test")) {
    $suggestions = aspell_suggest($aspell_link, "test");

    foreach ($suggestions as $suggestion) {
        echo "Possible spelling: $suggestion<br>\n"; 
    }
}

IV. Funciones matemáticas de precisión arbitraria BCMath

Introducción

Para operaciones matemáticas de precisión arbitraria, PHP tiene disponible la Calculadora Binaria que soporta números de cualquier tamaño y precisión, representados como cadenas de texto.


Requerimientos

Desde PHP 4.0.4, libbcmath se encuentra incorporada en PHP. No se necesitan bibliotecas externas para esta extensión.


Instalación

En PHP 4, estas funciones están disponibles solamente si PHP ha sido configurado con --enable-bcmath en PHP 3, estas funciones están disponibles solamente si PHP no ha sido configurado con --disable-bcmath.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

Esta extensión no define ningún tipo de recurso.


Constantes predefinidas

Esta extensión no define ninguna constante.

Tabla de contenidos
bcadd -- Suma dos números de precisión arbitriaria.
bccomp -- Compara dos números de precisión arbitraria.
bcdiv -- Divide dos números de precisión arbitraria.
bcmod -- Obtiene el módulo de un número de precisión arbitraria.
bcmul -- Multiplica dos números de precisión arbitraria.
bcpow -- Eleva un número de precisión arbitraria a otro.
bcpowmod --  Raise an arbitrary precision number to another, reduced by a specified modulus.
bcscale --  Fija el parámetro de escala por defecto para todas las funciones matemáticas bc.
bcsqrt -- Obtiene la raíz cuadrada de un número de precisión arbitraria.
bcsub -- Resta un número de precisión arbitraria de otro.

bcadd

(PHP 3, PHP 4 )

bcadd -- Suma dos números de precisión arbitriaria.

Descripción

string bcadd ( string operando izq, string operando der [, int escala])

Suma el operando izq con el operando der y devuelve la suma en una cadena de texto. El parámetro opcional escala se usa para fijar el número de dígitos tras el punto decimal que aparecerán en el resultado.

Vea también bcsub().

bccomp

(PHP 3, PHP 4 )

bccomp -- Compara dos números de precisión arbitraria.

Descripción

int bccomp ( string operando izq, string operando der [, int escala])

Compara el operando izq con el operando der y devuelve el resultado como un entero. El parámetro opcional escala se usa para fijar el número de dígitos tras el punto decimal que se utilizarán en la comparación. El valor devuelto es 0 si los dos operandos son iguales. Si el operando izq es mayor que el operando der el valor devuelto es +1 y si el operando izq es menor que el operando der el valor devuelto es -1.

bcdiv

(PHP 3, PHP 4 )

bcdiv -- Divide dos números de precisión arbitraria.

Descripción

string bcdiv ( string operando izq, string operando der [, int escala])

Divide el operando izq por el operando der y devuelve el resultado. El parámetro opcional escala fija el número de dígitos tras el punto decimal a usar en el resultado.

Ver también bcmul().

bcmod

(PHP 3, PHP 4 )

bcmod -- Obtiene el módulo de un número de precisión arbitraria.

Descripción

string bcmod ( string operando izq, string modulo)

Obtiene el módulo del operando izq usando modulo.

Ver también bcdiv().

bcmul

(PHP 3, PHP 4 )

bcmul -- Multiplica dos números de precisión arbitraria.

Descripción

string bcmul ( string operando izq, string operando der [, int escala])

Multiplica el operando izq por el operando der y devuelve el resultado. El parámetro opcional escala fija el número de dígitos tras el punto decimal del resultado.

Ver también bcdiv().

bcpow

(PHP 3, PHP 4 )

bcpow -- Eleva un número de precisión arbitraria a otro.

Descripción

string bcpow ( string x, string y [, int escala])

Eleva x a la potencia de y. El parámetro opcional escala se puede usar para fijar el número de dígitos tras el punto decimal del resultado.

Ver también bcsqrt().

bcpowmod

(PHP 5 CVS only)

bcpowmod --  Raise an arbitrary precision number to another, reduced by a specified modulus.

Description

string bcpowmod ( string x, string y, string modulus [, int scale])

Use the fast-exponentiation method to raise x to the power y with respect to the modulus modulus. The optional scale can be used to set the number of digits after the decimal place in the result.

The following two statements are functionally identical. The bcpowmod() version however, executes in less time and can accept larger parameters.

<?php
$a = bcpowmod($x,$y,$mod);

$b = bcmod(bcpow($x,$y),$mod);

/* $a and $b are equal to each other. */
?>

Nota: Because this method uses the modulus operation, non-natural numbers may give unexpected results. A natural number is any positive non-zero integer.

See also bcpow(), and bcmod().

bcscale

(PHP 3, PHP 4 )

bcscale --  Fija el parámetro de escala por defecto para todas las funciones matemáticas bc.

Descripción

string bcscale ( int escala)

Esta función fija el parámetro de escala por defecto para las subsiguientes funciones matemáticas bc que no especifican dicho parámetro explícitamente.

bcsqrt

(PHP 3, PHP 4 )

bcsqrt -- Obtiene la raíz cuadrada de un número de precisión arbitraria.

Descripción

string bcsqrt ( string operando, int escala)

Devuelve la raíz cuadrada del operando. El parámetro opcional escala fija el número de dígitos tras el punto decimal del resultado.

Ver también bcpow().

bcsub

(PHP 3, PHP 4 )

bcsub -- Resta un número de precisión arbitraria de otro.

Descripción

string bcsub ( string operando izq, string operando der [, int escala])

Resta el operando der del operando izq y devuelve el resultado en una cadena. El parámetro opcional escala se utiliza para fijar el número de dígitos tras el punto decimal del resultado.

Ver también bcadd().

V. Funciones de compresión Bzip2

Introducción

Las funciones bzip2 son usadas para leer y escribir de forma transparente, ficheros comprimidos bzip2 (.bz2)


Requerimientos

Este módulo usa las funciones de la biblioteca bzip2 de Julian Seward.


Instalación

El soporte Bzip2 en PHP no está activado por defecto. Necesitais usar la opción de configuración --with-bz2 cuando vayais a compilar PHP, si quereis soporte bzip2. Este módulo requiere bzip2/libbzip2 versión >= 1.0.x.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

Esta extensión define un tipo de recurso: un puntero de fichero que identifica el fichero bz2 con el que se va a trabajar.


Constantes predefinidas

Esta extensión no define ninguna constante.


Ejemplos

Este ejemplo abre un fichero temporal, escribe una cadena literal en el y presenta el contenido de dicho fichero.

Ejemplo 1. Ejemplo simple de bzip2

<?php

$filename = "/tmp/testfile.bz2";
$str = "This is a test string.\n";

// open file for writing
$bz = bzopen($filename, "w");

// write string to file
bzwrite($bz, $str);

// close file
bzclose($bz);

// open file for reading
$bz = bzopen($filename, "r");

// read 10 characters
print bzread($bz, 10);

// output until end of the file (or the next 1024 char) and close it.  
print bzread($bz);

bzclose($bz);

?>
Tabla de contenidos
bzclose -- Close a bzip2 file pointer
bzcompress -- Compress a string into bzip2 encoded data
bzdecompress -- Decompresses bzip2 encoded data
bzerrno -- Returns a bzip2 error number
bzerror -- Returns the bzip2 error number and error string in an array
bzerrstr -- Returns a bzip2 error string
bzflush -- Force a write of all buffered data
bzopen -- Open a bzip2 compressed file
bzread -- Binary safe bzip2 file read
bzwrite -- Binary safe bzip2 file write

bzclose

(PHP 4 >= 4.0.4)

bzclose -- Close a bzip2 file pointer

Description

int bzclose ( resource bz)

Closes the bzip2 file referenced by the pointer bz.

Devuelve TRUE si todo fue bien, FALSE en caso de fallo.

The file pointer must be valid, and must point to a file successfully opened by bzopen().

See also bzopen().

bzcompress

(PHP 4 >= 4.0.4)

bzcompress -- Compress a string into bzip2 encoded data

Description

string bzcompress ( string source [, int blocksize [, int workfactor]])

bzcompress() compresses the source string and returns it as bzip2 encoded data.

The optional parameter 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.

The optional parameter workfactor controls 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.

Ejemplo 1. bzcompress() Example

<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
print( $bzstr );
?>

See also bzdecompress().

bzdecompress

(PHP 4 >= 4.0.4)

bzdecompress -- Decompresses bzip2 encoded data

Description

string bzdecompress ( string source [, int small])

bzdecompress() decompresses the source string containing bzip2 encoded data and returns it. If the optional parameter small is 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.

Ejemplo 1. bzdecompress()

<?php
$start_str = "This is not an honest face?";
$bzstr = bzcompress($start_str);

print( "Compressed String: " );
print( $bzstr );
print( "\n<br>\n" );

$str = bzdecompress($bzstr);
print( "Decompressed String: " );
print( $str );
print( "\n<br>\n" );
?>

See also bzcompress().

bzerrno

(PHP 4 >= 4.0.4)

bzerrno -- Returns a bzip2 error number

Description

int bzerrno ( resource bz)

Returns the error number of any bzip2 error returned by the file pointer bz.

See also bzerror() and bzerrstr().

bzerror

(PHP 4 >= 4.0.4)

bzerror -- Returns the bzip2 error number and error string in an array

Description

array bzerror ( resource bz)

Returns the error number and error string, in an associative array, of any bzip2 error returned by the file pointer bz.

Ejemplo 1. bzerror() Example

<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>

See also bzerrno() and bzerrstr().

bzerrstr

(PHP 4 >= 4.0.4)

bzerrstr -- Returns a bzip2 error string

Description

string bzerrstr ( resource bz)

Returns the error string of any bzip2 error returned by the file pointer bz.

See also bzerrno() and bzerror().

bzflush

(PHP 4 >= 4.0.4)

bzflush -- Force a write of all buffered data

Description

int bzflush ( resource bz)

Forces a write of all buffered bzip2 data for the file pointer bz.

Devuelve TRUE si todo fue bien, FALSE en caso de fallo.

See also bzread() and bzwrite().

bzopen

(PHP 4 >= 4.0.4)

bzopen -- Open a bzip2 compressed file

Description

resource bzopen ( string filename, string mode)

Opens a bzip2 (.bz2) file for reading or writing. filename is the name of the file to open. mode is similar to the fopen() function (`r' for read, `w' for write, etc.).

If the open fails, the function returns FALSE, otherwise it returns a pointer to the newly opened file.

Ejemplo 1. bzopen() Example

<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$decompressed_file = bzread($bz, filesize("/tmp/foo.bz2"));
bzclose($bz);

print( "The contents of /tmp/foo.bz2 are: " );
print( "\n<br>\n" );
print( $decompressed_file );
?>

See also bzclose().

bzread

(PHP 4 >= 4.0.4)

bzread -- Binary safe bzip2 file read

Description

string bzread ( resource bz [, int length])

bzread() reads up to length bytes from the bzip2 file pointer referenced by bz. Reading stops when length (uncompressed) bytes have been read or EOF is reached, whichever comes first. If the optional parameter length is not specified, bzread() will read 1024 (uncompressed) bytes at a time.

Ejemplo 1. bzread() Example

<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$str = bzread($bz, 2048);
print( $str );
?>

See also bzwrite() and bzopen().

bzwrite

(PHP 4 >= 4.0.4)

bzwrite -- Binary safe bzip2 file write

Description

int bzwrite ( resource bz, string data [, int length])

bzwrite() writes the contents of the string data to the bzip2 file stream pointed to by bz. If the optional length argument is given, writing will stop after length (uncompressed) bytes have been written or the end of string is reached, whichever comes first.

Ejemplo 1. bzwrite() Example

<?php
$str = "uncompressed data";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>

See also bzread() and bzopen().

VI. Funciones de calendario

Introducción

La extensión calendar pone a disposición una serie de funciones para simplificar la conversión entre los distintos formatos de calendario. El intermediario ó estándar en que se basa es la Cuenta de Días Juliana. La Cuenta de Días Juliana es una cuenta que comienza mucho antes que lo que mucha gente podría necesitar contar (como alrededor del 4000 AC). Para convertir entre sistemas de calendario, primero deberá convertir a la Cuenta de Días Juliana y luego al sistema de su elección. ¡La Cuenta de Días es muy diferente del Calendario Juliano! Para más información sobre la Cuenta de Días Juliana visitar http://serendipity.magnet.ch/hermetic/cal_stud/jdn.htm. Para más información sobre sistemas de calendario, visitar http://genealogy.org/~scottlee/cal-overview.html. En estas instrucciones se han incluído extractos entrecomillados de dicha página.


Instalación

Para que estas funciones funcionen, hay que compilar PHP con la opción --enable-calendar.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

Esta extensión no define ningún tipo de recurso.


Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinamicamente en tiempo de ejecución.

CAL_GREGORIAN (entero)

CAL_JULIAN (entero)

CAL_JEWISH (entero)

CAL_FRENCH (entero)

CAL_NUM_CALS (entero)

CAL_DOW_DAYNO (entero)

CAL_DOW_SHORT (entero)

CAL_DOW_LONG (entero)

CAL_MONTH_GREGORIAN_SHORT (entero)

CAL_MONTH_GREGORIAN_LONG (entero)

CAL_MONTH_JULIAN_SHORT (entero)

CAL_MONTH_JULIAN_LONG (entero)

CAL_MONTH_JEWISH (entero)

CAL_MONTH_FRENCH (entero)

Las siguientes constantes se pueden utilizar desde PHP 4.3.0 :

CAL_EASTER_DEFAULT (entero)

CAL_EASTER_ROMAN (entero)

CAL_EASTER_ALWAYS_GREGORIAN (entero)

CAL_EASTER_ALWAYS_JULIAN (entero)

Tabla de contenidos
cal_days_in_month -- Devuelve el número de dias en un mes para un determinado año y calendario
cal_from_jd -- Convierte de Cuenta de Días Juliana a un calendario soportado y devuelve información adicional.
cal_info -- Devuelve información sobre un calendario den particular.
cal_to_jd -- Convierte de un calendario soportado a Cuenta de Días Juliana.
easter_date -- devuelve la marca de tiempo UNIX para la medianoche de Pascua de un año dado
easter_days -- Obtiene el número de días tras el 21 de marzo en que cae la Pascua en un año dado
FrenchToJD -- Convierte del Calendario Republicano Francés a la Cuenta de Días Juliana
GregorianToJD -- Convierte de fecha Gregoriana a la Cuenta de Días Juliana
JDDayOfWeek -- Devuelve el día de la semana
JDMonthName -- Devuelve el nombre de un mes
JDToFrench -- Convierte de Cuenta de Días al Calendario Republicano Francés
JDToGregorian -- Convierte de Cuenta de Días a fecha Gregoriana
JDToJewish -- Convierte de Cuenta de Días Juliana a Calendario Judío
JDToJulian -- Convierte de Cuenta de Días Juliana a Calendario Juliano
jdtounix -- Convierte un dia Juliano a UNIX timestamp
JewishToJD -- Convierte del Calendario Judío a la Cuenta de Días Juliana
JulianToJD -- Convierte de Calendario Juliano a Cuenta de Días Juliana
unixtojd -- Convierte de UNIX timestamp a dia Juliano

cal_days_in_month

(PHP 4 >= 4.1.0)

cal_days_in_month -- Devuelve el número de dias en un mes para un determinado año y calendario

Descripción

int cal_days_in_month ( int calendario, int mes, int año)

Esta función devuelve el numero de dias en el mes del año para el calendario especificado calendario.

Ver también jdtounix().

cal_from_jd

(PHP 4 >= 4.1.0)

cal_from_jd -- Convierte de Cuenta de Días Juliana a un calendario soportado y devuelve información adicional.

Descripción

array cal_from_jd ( int jd, int calendario)

cal_info

(PHP 4 >= 4.1.0)

cal_info -- Devuelve información sobre un calendario den particular.

Descripción

array cal_info ( int calendario)

cal_to_jd

(PHP 4 >= 4.1.0)

cal_to_jd -- Convierte de un calendario soportado a Cuenta de Días Juliana.

Descripción

int cal_to_jd ( int calendario, int mes, int dia, int año)

easter_date

(PHP 3>= 3.0.9, PHP 4 )

easter_date -- devuelve la marca de tiempo UNIX para la medianoche de Pascua de un año dado

Descripción

int easter_date ( [int anno])

Devuelve la marca de tiempo UNIX que corresponde a la medianoche de Pascua del año dado.

A partir de PHP 4.3.0, el parametro anno es opcional y si se omite, usa por defecto el año en curso según "localtime".

Aviso: Esta función generará un aviso si el año está fuera del rango para las marcas de tiempo del UNIX (es decir, antes de 1970 o después del 2037).

Ejemplo 1. ejemplo de easter_date()

echo date ("M-d-Y", easter_date(1999));        /* "Apr-04-1999" */
echo date ("M-d-Y", easter_date(2000));        /* "Apr-23-2000" */
echo date ("M-d-Y", easter_date(2001));        /* "Apr-15-2001" */

La fecha del Día de Pascua fue definida por el Concilio de Nicea en el 325 D.C. como el domingo tras la primera luna llena que cayera en ó después del equinoccio de Primavera. El equinoccio se supone que siempre cae en el 21 de marzo, de modo que el cálculo se reduce a determinar la fecha de la luna llena y la del domingo siguiente. El algoritmo usado aquí fue introducido en el año 532 por Dionisio Exiguo. Bajo el Calendario Juliano (para años anteriores al 1753), se usa un ciclo simple de 19 años para calcular las fases de la luna. Bajo el Calendario Gregoriano (años posteriores al 1753, diseñado por Clavio y Lilio, e introducido por el Papa Gregorio XIII en Octubre de 1582, y en Gran Bretaña y sus colonias en septiembre de 1752) se añaden dos factores de corrección para hacer el ciclo más preciso.

(El código se basa en un programa en C de Simon Kershaw, <webmaster@ely.anglican.org>)

Ver easter_days() para calcular la Pascua antes del 1970 o después del 2037.

easter_days

(PHP 3>= 3.0.9, PHP 4 )

easter_days -- Obtiene el número de días tras el 21 de marzo en que cae la Pascua en un año dado

Descripción

int easter_days ( [int anno [, int metodo]])

Devuelve el número de días tras el 21 de marzo en que cae la Pascua en un año dado. Si no se especifica año, se asume el actual.

A partir de PHP 4.3.0, el parametro anno es opcional y si se omite, usa por defecto el año en curso según "localtime".

El parámetro metodo fue introducido en la version PHP 4.3.0 y permite calcular fechas de pascua basadas en el Calendario Gregoriano durante los años 1582 - 1752 si se le da el valor CAL_EASTER_ROMAN. Ver las constantes de calendario para más información sobre estas constantes.

Esta función se puede usar en lugar de easter_date() para calcular la Pascua para años que se salen del rango de las marcas de fecha del UNIX (o sea, antes del 1970 o después del 2037).

Ejemplo 1. ejemplo de easter_date()

echo easter_days (1999);        /* 14, i.e. April 4   */
echo easter_days (1492);        /* 32, i.e. April 22  */
echo easter_days (1913);        /*  2, i.e. March 23  */

La fecha del Día de Pascua fue definida por el Concilio de Nicea en el 325 D.C. como el domingo tras la primera luna llena que cayera en o después del equinoccio de Primavera. El equinoccio se supone que siempre cae en el 21 de marzo, de modo que el cálculo se reduce a determinar la fecha de la luna llena y la del domingo siguiente. El algoritmo usado aquí fue introducido en el año 532 por Dionisio Exiguo. Bajo el Calendario Juliano (para años anteriores al 1753), se usa un ciclo simple de 19 años para calcular las fases de la luna. Bajo el Calendario Gregoriano (años posteriores al 1753, diseñado por Clavio y Lilio, e introducido por el Papa Gregorio XIII en Octubre de 1582, y en Gran Bretaña y sus colonias en septiembre de 1752) se añaden dos factores de corrección para hacer el ciclo más preciso.

(El código se basa en un programa en C de Simon Kershaw, <webmaster@ely.anglican.org>)

Vea también easter_date().

FrenchToJD

(PHP 3, PHP 4 )

FrenchToJD -- Convierte del Calendario Republicano Francés a la Cuenta de Días Juliana

Descripción

int frenchtojd ( int mes, int dia, int anno)

Convierte una fecha del Calendario Republicano Francés a la Cuenta de Días Juliana.

Estas rutinas sólo convierten fechas entre los años 1 y 14 (fechas Gregorianas del 22 de septiembre de 1792 al 22 de septiembre de 1806). Esto cubre ampliamente el periodo en el que estuvo en uso este calendario.

GregorianToJD

(PHP 3, PHP 4 )

GregorianToJD -- Convierte de fecha Gregoriana a la Cuenta de Días Juliana

Descripción

int gregoriantojd ( int mes, int dia, int anno)

El rango válido para el Calendario Gregoriano es desde el 4714 A.C. hasta el 9999 D.C.

Aunque este programa puede manejar fechas tan lejanas como el 4714 A.C., usarlo no tendría sentido. El calendario Gregoriano fue instituído el 15 de octubre de 1582 (o el 5 de octubre de 1582 en el calendario Juliano). Algunos países no lo aceptaron hasta mucho después. Por ejemplo, Gran Bretaña se convirtió en 1752, la URSS en 1918 y Grecia en 1923. Muchos países europeos usaron el calendario Juliano antes que el Gregoriano.

Ejemplo 1. Funciones de calendario

<?php
$jd = GregorianToJD (10,11,1970);
echo "$jd\n";
$gregorian = JDToGregorian ($jd);
echo "$gregorian\n";
?>

JDDayOfWeek

(PHP 3, PHP 4 )

JDDayOfWeek -- Devuelve el día de la semana

Descripción

mixed jddayofweek ( int diajuliano, int modo)

Devuelve el día de la semana. Dependiendo del modo, devuelve un entero ó una cadena.

Tabla 1. Modos para el día de la semana

ModoSignificado
0devuelve el día de la semana como entero (0=domingo, 1=lunes, etc)
1devuelve una cadena con el día de la semana (inglés, gregoriano)
2devuelve una cadena con el día de la semana abreviado (inglés, gregoriano)

JDMonthName

(PHP 3, PHP 4 )

JDMonthName -- Devuelve el nombre de un mes

Descripción

string jdmonthname ( int diajuliano, int modo)

Devuelve una cadena que contiene el nombre del mes. modo le dice a esta función a qué calendario debe convertir la Cuenta de Días Juliana, y qué tipo de nombres de mes debe devolver.

Tabla 1. Modos de calendario

ModoSignificadoValores
0Gregoriano - abreviadoJan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
1GregorianoJanuary, February, March, April, May, June, July, August, September, October, Novemb er, December
2Juliano - abreviadoJan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
3JulianoJanuary, February, March, April, May, June, July, August, September, October, Novemb er, December
4JudíoTishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
5Republicano FrancésVendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prair ial, Messidor, Thermidor, Fructidor, Extra

JDToFrench

(PHP 3, PHP 4 )

JDToFrench -- Convierte de Cuenta de Días al Calendario Republicano Francés

Descripción

string jdtofrench ( int diajuliano)

Convierte una Cuenta de Días Juliana al Calendario Republicano Francés.

JDToGregorian

(PHP 3, PHP 4 )

JDToGregorian -- Convierte de Cuenta de Días a fecha Gregoriana

Descripción

string jdtogregorian ( int diajuliano)

Convierte de Cuenta de Días Juliana a una cadena que contiene la fecha Gregoriana en formato "mes/día/año"

JDToJewish

(PHP 3, PHP 4 )

JDToJewish -- Convierte de Cuenta de Días Juliana a Calendario Judío

Descripción

string jdtojewish ( int diajuliano)

Convierte una Cuenta de Días Juliana al Calendario Judío.

JDToJulian

(PHP 3, PHP 4 )

JDToJulian -- Convierte de Cuenta de Días Juliana a Calendario Juliano

Descripción

string jdtojulian ( int diajuliano)

Convierte una Cuenta de Días Juliana a una cadena que contiene la fecha del Calendario Juliano en formato "mes/día/año".

jdtounix

(PHP 4 )

jdtounix -- Convierte un dia Juliano a UNIX timestamp

Descripción

int jdtounix ( int jday)

Esta funció devuelve el "UNIX timestamp" correspondiante a el dia Juliano definido en jday ó falso (FALSE) si jday no se encuentra en la época UNIX (años entre 1970 y 2037 ó 2440588 <= jday <= 2465342 ). El tiempo devuelto es localtime (y no GMT).

Ver también unixtojd().

JewishToJD

(PHP 3, PHP 4 )

JewishToJD -- Convierte del Calendario Judío a la Cuenta de Días Juliana

Descripción

int jewishtojd ( int mes, int dia, int anno)

Aunque este programa puede manejar fechas tan lejanas como el año 1 (3761 A.C.), usarlo no tendría sentido. El Calendario Judío ha estado en uso miles de años, pero en los días primeros no había una fórmula que calculara el comienzo de un mes. Un mes comenzaba cuando se veía por primera vez la luna nueva.

JulianToJD

(PHP 3, PHP 4 )

JulianToJD -- Convierte de Calendario Juliano a Cuenta de Días Juliana

Descripción

int juliantojd ( int mes, int dia, int anno)

Rango válido para el Calendario Juliano: del 4713 A.C al 9999 D.C.

Aunque este programa puede manejar fechas tan lejanas como el 4713 A.C., usarlo no tendría sentido. El calendario se creó en el 46 A.C., pero sus detalles no se estabilizaron hasta al menos el 8 D.C., y quizás no lo hiciera hasta el siglo IV. Además, el comienzo de un año variaba de una a otra cultura: no todas aceptaban enero como el primer mes.

Atención

Recordar que el actual sistema de calendario en uso en todo el mundo es el calendario Gregoriano. gregoriantojd() puede ser usada para convertir los dias del calendario Gregoriano a Cuenta de Días Juliana.

unixtojd

(PHP 4 )

unixtojd -- Convierte de UNIX timestamp a dia Juliano

Descripción

int unixtojd ( [int timestamp])

Devuelve el dia Juliano correspondiente a un UNIX timestamp (segundos desde 01.01.1970), ó al dia actual si no se especifica timestamp

Ver tambienjdtounix().

VII. Funciones del API de CCVS

Introducción

Estas funciones interaccionan con el API de CCVS, permitiendo trabajar con CCVS directamente desde un script PHP. CCVS es la solución de RedHat para el intermediario en el procesamiento de tarjetas de crédito. Permite conectar directamente con las centrales de las tarjetas desde una máquina *nix con un módem.

Nota: CCVS ha sido discontinuado por Red Hat y no existen planes de ofrecer nuevas funcionalidades ó contratos de ayuda. Los que necesiten usar esta funcionalidad pueden probar MCVE by Main Street Softworks. Es similar en diseño y tiene documentación para su uso con PHP


Instalación

Para activar el soporte de CCVS en PHP hay que tener instalado CCVS en vuestro sistema. Seguidamente es necesario configurar PHP con la opción --with-ccvs. Si se usa esta opcion sin especificar el directorio donde CCVS está instalado, PHP intentará encontrar CCVS en la localización por defecto (/usr/local/ccvs). Si CCVS está instalado en una localización no estándar, ejecutar configure con: --with-ccvs=$ccvs_path, donde $ccvs_path es el directorio donde CCVS esta instalado. Tener en cuenta que el soporte de CCVS en PHP necesita que $ccvs_path/lib y $ccvs_path/include existan, que cv_api.h se encuentre en el directorio include y que libccvs.a se encuentre en el directorio lib.

Adicionalmente se necesita un proceso ccvs ejecutandose en el sistema para las configuraciones que se ejecuten desde PHP. Los procesos PHP deben ejecutarse bajo el mismo usuario que use CCVS (p.ej. Si ccvs usa el usuario 'ccvs', PHP debe ejecutarse como 'ccvs' tambien).


Ver tambien

Información adicional sobre CCVS se puede encontrar en http://www.redhat.com/products/ccvs. Red Hat casi no mantiene la documentación de CCVS, pero todavia es de gran ayuda, se puede encontrar en http://www.redhat.com/products/ccvs/support/CCVS3.3docs/ProgPHP.html.

Tabla de contenidos
ccvs_add -- Añadir datos a una transacción
ccvs_auth --  Realiza un test de una autorización a crédito en una transacción
ccvs_command --  Ejecuta un comando que es peculiar para un protocolo concreto, y que no está disponible en el API general de CCVS
ccvs_count --  Encuentra cuantas transacciones de un tipo dado están almacenadas en el sistema
ccvs_delete -- Borra una transacción
ccvs_done -- Finaliza el motor de CCVS y hace una limpieza
ccvs_init -- Inicializa un CCVS para usarlo
ccvs_lookup --  Busca un item de un tipo en particular en la base de datos #
ccvs_new -- Crea una nueva, transacción en blanco
ccvs_report -- Devuelve el estado del proceso de comunicación en background
ccvs_return --  Transfiere fondos del comerciante al titular de la tarjeta
ccvs_reverse --  Realiza una revocación completa en una autorización ya procesada
ccvs_sale --  Transfiere fondos del titular de la tarjeta al comerciante
ccvs_status -- Chequear el estado de una factura
ccvs_textvalue -- Obtiene el valor de retorno de texto para una llamada anterior a una función
ccvs_void --  Realizar una revocación completa en una transacción completada

ccvs_add

(4.0.2 - 4.2.3 only)

ccvs_add -- Añadir datos a una transacción

Descripción

cadena ccvs_add ( cadena sesión, cadena factura, cadena argtype, cadena argval)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_auth

(4.0.2 - 4.2.3 only)

ccvs_auth --  Realiza un test de una autorización a crédito en una transacción

Descripcion

cadena ccvs_auth ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_command

(4.0.2 - 4.2.3 only)

ccvs_command --  Ejecuta un comando que es peculiar para un protocolo concreto, y que no está disponible en el API general de CCVS

Descripcion

cadena ccvs_command ( cadena sesión, cadena tipo, cadena argval)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_count

(4.0.2 - 4.2.3 only)

ccvs_count --  Encuentra cuantas transacciones de un tipo dado están almacenadas en el sistema

Descripción

entero ccvs_count ( cadena sesión, cadena tipo)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_delete

(4.0.2 - 4.2.3 only)

ccvs_delete -- Borra una transacción

Descripción

cadena ccvs_delete ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_done

(4.0.2 - 4.2.3 only)

ccvs_done -- Finaliza el motor de CCVS y hace una limpieza

Descripcion

cadena ccvs_done ( cadena sesió)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_init

(4.0.2 - 4.2.3 only)

ccvs_init -- Inicializa un CCVS para usarlo

Descripción

cadena ccvs_init ( cadena nombre)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_lookup

(4.0.2 - 4.2.3 only)

ccvs_lookup --  Busca un item de un tipo en particular en la base de datos #

Descripción

cadena ccvs_lookup ( cadena sesión, cadena factura, entero inum)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_new

(4.0.2 - 4.2.3 only)

ccvs_new -- Crea una nueva, transacción en blanco

Descripcion

cadena ccvs_new ( cadena sesión, cadena cadena)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_report

(4.0.2 - 4.2.3 only)

ccvs_report -- Devuelve el estado del proceso de comunicación en background

Descripcion

cadena ccvs_report ( cadena sesión, cadena tipo)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_return

(4.0.2 - 4.2.3 only)

ccvs_return --  Transfiere fondos del comerciante al titular de la tarjeta

Descripción

cadena ccvs_return ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_reverse

(4.0.2 - 4.2.3 only)

ccvs_reverse --  Realiza una revocación completa en una autorización ya procesada

Descripcion

cadena ccvs_reverse ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_sale

(4.0.2 - 4.2.3 only)

ccvs_sale --  Transfiere fondos del titular de la tarjeta al comerciante

Descripción

cadena ccvs_sale ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_status

(4.0.2 - 4.2.3 only)

ccvs_status -- Chequear el estado de una factura

Descripción

cadena ccvs_status ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_textvalue

(4.0.2 - 4.2.3 only)

ccvs_textvalue -- Obtiene el valor de retorno de texto para una llamada anterior a una función

Descripción

cadena ccvs_textvalue ( cadena sesión)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

ccvs_void

(4.0.2 - 4.2.3 only)

ccvs_void --  Realizar una revocación completa en una transacción completada

Descripción

cadena ccvs_void ( cadena sesión, cadena factura)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

VIII. soporte de las funciones COM para Windows

Estas funciones solo están disponibles en la versión para Windows de PHP. Estas funciones han sido añadidas en PHP4.

Tabla de contenidos
COM -- COM class
VARIANT -- VARIANT class
com_addref --  Increases the components reference counter.
com_get -- ???
com_invoke -- ???
com_isenum -- Grabs an IEnumVariant
com_load_typelib -- Loads a Typelib
com_load -- ???
com_propget -- ???
com_propput -- ???
com_propset -- ???
com_release --  Decreases the components reference counter.
com_set -- ???

COM

(no version information, might be only in CVS)

COM -- COM class

Synopsis

$obj = new COM("server.object")

Description

The COM class provides a framework to integrate (D)COM components into your php scripts.

Methods

string COM::COM ( string module_name [, string server_name [, int codepage]])

COM class constructor. Parameters:

module_name

name or class-id of the requested component.

server_name

name of the DCOM server from which the component should be fetched. If NULL, localhost is assumed. To allow DCOM com.allow_dcom has to be set to TRUE in php.ini.

codepage

specifies the codepage that is used to convert php-strings to unicode-strings and vice versa. Possible values are CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 and CP_UTF8.

Ejemplo 1. COM example (1)

// starting word
$word = new COM("word.application") or die("Unable to instanciate Word");
print "Loaded Word, version {$word->Version}\n";

//bring it to front
$word->Visible = 1;

//open an empty document
$word->Documents->Add();

//do some weird stuff
$word->Selection->TypeText("This is a test...");
$word->Documents[1]->SaveAs("Useless test.doc");

//closing word
$word->Quit();

//free the object
$word->Release();
$word = null;

Ejemplo 2. COM example (2)

$conn = new COM("ADODB.Connection") or die("Cannot start ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

$rs = $conn->Execute("SELECT * FROM sometable");    // Recordset

$num_columns = $rs->Fields->Count();
echo $num_columns . "\n";

for ($i=0; $i < $num_columns; $i++)
{
    $fld[$i] = $rs->Fields($i);
}

$rowcount = 0;
while (!$rs->EOF)
{
    for ($i=0; $i < $num_columns; $i++)
    {
        echo $fld[$i]->value . "\t";
    }
    echo "\n";
    $rowcount++;            // increments rowcount
    $rs->MoveNext();
}

$rs->Close();
$conn->Close();

$rs->Release();
$conn->Release();

$rs = null;
$conn = null;

VARIANT

(no version information, might be only in CVS)

VARIANT -- VARIANT class

Synopsis

$vVar = new VARIANT($var)

Description

A simple container to wrap variables into VARIANT structures.

Methods

string VARIANT::VARIANT ( [mixed value [, int type [, int codepage]]])

VARIANT class constructor. Parameters:

value

initial value. if omitted an VT_EMPTY object is created.

type

specifies the content type of the VARIANT object. Possible values are VT_UI1, VT_UI2, VT_UI4, VT_I1, VT_I2, VT_I4, VT_R4, VT_R8, VT_INT, VT_UINT, VT_BOOL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DECIMAL, VT_UNKNOWN, VT_DISPATCH and VT_VARIANT. These values are mutual exclusive, but they can be combined with VT_BYREF to specify being a value. If omitted, the type of value is used. Consult the msdn library for additional information.

codepage

specifies the codepage that is used to convert php-strings to unicode-strings and vice versa. Possible values are CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 and CP_UTF8.

com_addref

(4.1.0 - 4.3.0 only)

com_addref --  Increases the components reference counter.

Description

void com_addref ( void)

Increases the components reference counter.

com_get

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_get -- ???

Descripción

mixed com_get ( resource object, string property)

com_invoke

(PHP 3>= 3.0.3)

com_invoke -- ???

Descripción

mixed com_invoke ( resource object, string function_name [, mixed function parameters, ...])

com_isenum

(4.1.0 - 4.3.0 only)

com_isenum -- Grabs an IEnumVariant

Description

void com_isenum ( object com_module)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

com_load_typelib

(4.1.0 - 4.3.0 only)

com_load_typelib -- Loads a Typelib

Description

void com_load_typelib ( string typelib_name [, int case_insensitive])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

com_load

(PHP 3>= 3.0.3)

com_load -- ???

Descripción

string com_load ( string module name [, string server name])

com_propget

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_propget -- ???

Descripción

mixed com_propget ( resource object, string property)

com_propput

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_propput -- ???

Descripción

void com_propput ( resource object, string property, mixed value)

com_propset

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_propset -- ???

Descripción

void com_propset ( resource object, string property, mixed value)

Esta función es un alias para com_propput().

com_release

(4.1.0 - 4.3.0 only)

com_release --  Decreases the components reference counter.

Description

void com_release ( void)

Decreases the components reference counter.

com_set

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_set -- ???

Descripción

void com_set ( resource object, string property, mixed value)

Esta función es un alias para com_set().

IX. Funciones de Clases/Objectos

Introducción

Estas funciones permiten obtener informacion sobre clases y objetos. Se puede obtener el nombre de la clase a la que pertenece un objeto, asi como las propiedades de sus miembros y métodos. Usando estas funciones se puede obtener no solo lo comentado en la frase anterior, tambien se puede obtener la familia del objeto (p.ej. que clase está extendiendo la clase a la que pertenece el objeto)


Ejemplos

En este ejemplo, definimos primero una clase base y una extensión de esta clase. La clase base define un vegetal genérico, si es comestible y su color. La subclase Spinach añade un metodo para cocinarlo y otro para saber si esta cocinado.

Ejemplo 1. classes.inc

<?php

// base class with member properties and methods
class Vegetable {

    var $edible;
    var $color;

    function Vegetable( $edible, $color="green" ) {
        $this->edible = $edible;
        $this->color = $color;
    }

    function is_edible() {
        return $this->edible;
    }

    function what_color() {
        return $this->color;
    }
    
} // end of class Vegetable

// extends the base class
class Spinach extends Vegetable {

    var $cooked = false;

    function Spinach() {
        $this->Vegetable( true, "green" );
    }

    function cook_it() {
        $this->cooked = true;
    }

    function is_cooked() {
        return $this->cooked;
    }
    
} // end of class Spinach

?>

Creamos 2 objetos de estas clases e imprimimos información sobre ellos, incluyendo la jerarquia de clases a la que pertenecen. También definimos algunas funciones, especialmente para imprimir las variables de una manera ordenada.

Ejemplo 2. test_script.php

<pre>
<?php

include "classes.inc";

// utility functions

function print_vars($obj) {
    $arr = get_object_vars($obj);
    while (list($prop, $val) = each($arr))
        echo "\t$prop = $val\n";
}

function print_methods($obj) {
    $arr = get_class_methods(get_class($obj));
    foreach ($arr as $method)
        echo "\tfunction $method()\n";
}

function class_parentage($obj, $class) {
    global $$obj;
    if (is_subclass_of($$obj, $class)) {
        echo "Object $obj belongs to class ".get_class($$obj);
        echo " a subclass of $class\n";
    } else {
        echo "Object $obj does not belong to a subclass of $class\n";
    }
}

// instantiate 2 objects

$veggie = new Vegetable(true,"blue");
$leafy = new Spinach();

// print out information about objects
echo "veggie: CLASS ".get_class($veggie)."\n";
echo "leafy: CLASS ".get_class($leafy);
echo ", PARENT ".get_parent_class($leafy)."\n";

// show veggie properties
echo "\nveggie: Properties\n";
print_vars($veggie);

// and leafy methods
echo "\nleafy: Methods\n";
print_methods($leafy);

echo "\nParentage:\n";
class_parentage("leafy", "Spinach");
class_parentage("leafy", "Vegetable");
?>
</pre>

One important thing to note in the example above is that the object $leafy is an instance of the class Spinach which is a subclass of Vegetable, therefore the last part of the script above will output:

[...]
Parentage:
Object leafy does not belong to a subclass of Spinach
Object leafy belongs to class spinach a subclass of Vegetable

Tabla de contenidos
call_user_method_array --  Call a user method given with an array of parameters [deprecated]
call_user_method --  Call a user method on an specific object [deprecated]
class_exists -- Checks if the class has been defined
get_class_methods -- Devuelve un vector (matriz unidimensional) con los nombres de los métodos de la clase en question.
get_class_vars --  Devuelve un vector con las propiedades (inicializadas por defecto) de la clase
get_class -- Returns the name of the class of an object
get_declared_classes -- Returns an array with the name of the defined classes
get_object_vars -- Devuelve un vector de propiedades del objecto
get_parent_class -- Retrieves the parent class name for object or class
is_a --  Returns TRUE if the object is of this class or has this class as one of its parents
is_subclass_of --  Returns TRUE if the object has this class as one of its parents
method_exists -- Comprueba que el metódo de clase existe

call_user_method_array

(PHP 4 >= 4.0.5)

call_user_method_array --  Call a user method given with an array of parameters [deprecated]

Description

mixed call_user_method_array ( string method_name, object obj [, array paramarr])

Aviso

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.

Calls the method referred by method_name from the user defined obj object, using the parameters in paramarr.

See also: call_user_func_array(), call_user_func(), call_user_method().

Nota: This function was added to the CVS code after release of PHP 4.0.4pl1

call_user_method

(PHP 3>= 3.0.3, PHP 4 )

call_user_method --  Call a user method on an specific object [deprecated]

Description

mixed call_user_method ( string method_name, object obj [, mixed parameter [, mixed ...]])

Aviso

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.

Calls the method referred by method_name from the user defined obj object. An example of usage is below, where we define a class, instantiate an object and use call_user_method() to call indirectly its print_info method.

<?php
class Country {
    var $NAME;
    var $TLD;
    
    function Country($name, $tld) {
        $this->NAME = $name;
        $this->TLD = $tld;
    }

    function print_info($prestr="") {
        echo $prestr."Country: ".$this->NAME."\n";
        echo $prestr."Top Level Domain: ".$this->TLD."\n";
    }
}

$cntry = new Country("Peru","pe");

echo "* Calling the object method directly\n";
$cntry->print_info();

echo "\n* Calling the same method indirectly\n";
call_user_method ("print_info", $cntry, "\t");
?>

See also call_user_func_array(), call_user_func(), and call_user_method_array().

class_exists

(PHP 4 )

class_exists -- Checks if the class has been defined

Description

bool class_exists ( string class_name)

This function returns TRUE if the class given by class_name has been defined, FALSE otherwise.

See also get_declared_classes().

get_class_methods

(PHP 4 )

get_class_methods -- Devuelve un vector (matriz unidimensional) con los nombres de los métodos de la clase en question.

Descripción

vector get_class_methods ( string class_name)

Esta función devuelve un vector con los nombres de los métodos definidos en la clase especificada como class_name.

Nota: A partir de PHP 4.0.6, se puede especificar el objeto a sí mismo en vez de class_name. Por ejemplo:

$class_methods = get_class_methods($my_class); // see below the full example

Ejemplo 1. get_class_methods() ejemplo

<?php

class myclass {
    // constructor
    function myclass() {
        return(TRUE);
    }
    
    // method 1
    function myfunc1() {
        return(TRUE);
    }

    // method 2
    function myfunc2() {
        return(TRUE);
    }
}

$my_object = new myclass();

$class_methods = get_class_methods(get_class($my_object));

foreach ($class_methods as $method_name) {
    echo "$method_name\n";
}

?>

Producira:

myclass
myfunc1
myfunc2

Ver también get_class_vars() y get_object_vars().

get_class_vars

(PHP 4 )

get_class_vars --  Devuelve un vector con las propiedades (inicializadas por defecto) de la clase

Descripción

array get_class_vars ( string class_name)

Esta función devuelve un vector con las propiedades que han sido inicializadas por defecto en la clase. Los elementos de este vector están estan organizados de la forma varname => value.

Nota: Las variables de la clase que no estén inicializadas, no será presentadas por get_class_vars().

Ejemplo 1. get_class_vars() ejemplo

<?php

class myclass {

    var $var1; // this has no default value...
    var $var2 = "xyz";
    var $var3 = 100;
    
    // constructor
    function myclass() {
        return(TRUE);
    }
}

$my_class = new myclass();

$class_vars = get_class_vars(get_class($my_class));

foreach ($class_vars as $name => $value) {
    echo "$name : $value\n";
}

?>

Producira:

var2 : xyz
var3 : 100

Ver también get_class_methods(), get_object_vars()

get_class

(PHP 4 )

get_class -- Returns the name of the class of an object

Description

string get_class ( object obj)

This function returns the name of the class of which the object obj is an instance. Returns FALSE if obj is not an object.

Nota: get_class() returns a user defined class name in lowercase. A class defined in a PHP extension is returned in its original notation.

See also get_parent_class(), gettype(), and is_subclass_of().

get_declared_classes

(PHP 4 )

get_declared_classes -- Returns an array with the name of the defined classes

Description

array get_declared_classes ( void)

This function returns an array of the names of the declared classes in the current script.

Nota: In PHP 4.0.1pl2, 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 libraries you have compiled 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.

See also class_exists().

get_object_vars

(PHP 4 )

get_object_vars -- Devuelve un vector de propiedades del objecto

Descripción

array get_class_vars ( object obj)

Esta función devuelve un vector con las propiedades definidas en el objecto especificado como obj. Las variables declaradas en la clase a la que pertenece obj, que no les ha sido asignado un valor, no serán devueltas en el vector.

Ejemplo 1. Uso de get_object_vars()

<?php
class Point2D {
    var $x, $y;
    var $label;

    function Point2D($x, $y) {
        $this->x = $x;
        $this->y = $y;
    }

    function setLabel($label) {
        $this->label = $label;
    }

    function getPoint() {
        return array("x" => $this->x,
                     "y" => $this->y,
                     "label" => $this->label);
    }
}

// "$label" is declared but not defined
$p1 = new Point2D(1.233, 3.445);
print_r(get_object_vars($p1));

$p1->setLabel("point #1");
print_r(get_object_vars($p1));

?>
El resultado de este programa es:
Array
 (
     [x] => 1.233
     [y] => 3.445
 )

 Array
 (
     [x] => 1.233
     [y] => 3.445
     [label] => point #1
 )

Ver tambien get_class_methods() y get_class_vars()!

get_parent_class

(PHP 4 )

get_parent_class -- Retrieves the parent class name for object or class

Description

string get_parent_class ( mixed obj)

If obj is an object, returns the name of the parent class of the class of which obj is an instance.

If obj is a string, returns the name of the parent class of the class with that name. This functionality was added in PHP 4.0.5.

See also get_class() and is_subclass_of()

is_a

(PHP 4 >= 4.2.0)

is_a --  Returns TRUE if the object is of this class or has this class as one of its parents

Description

bool is_a ( object object, string class_name)

This function returns TRUE if the object is of this class or has this class as one of its parents, FALSE otherwise.

See also get_class(), get_parent_class(), and is_subclass_of().

is_subclass_of

(PHP 4 )

is_subclass_of --  Returns TRUE if the object has this class as one of its parents

Description

bool is_subclass_of ( object object, string class_name)

This function returns TRUE if the object object, belongs to a class which is a subclass of class_name, FALSE otherwise.

See also get_class(), get_parent_class() and is_a().

method_exists

(PHP 4 )

method_exists -- Comprueba que el metódo de clase existe

Descripción

bool method_exists ( object object, string method_name)

Esta función devuelve verdadero (TRUE) si el metódo referido por method_name ha sido definido en el objecto object, en cualquier otro caso devuelve falso (FALSE)

X. Funciones de ClibPDF

ClibPDF Le permite crear documentos PDF con PHP. Está disponible en FastIO pero no es software libre. Debería leer la licencia antes de comenzar a utilizar ClibPDF. Si usted no puede cumplir el acuerdo de la licencia considere el utilizar la pdflib de Thomas Merz, que tambien es muy potente. La funcionalidad y la API de ClibPDF son similares a la pdflib de Thomas Merz pero, de acuerdo con FastIO, ClibPDF es mas rápida y crea documentos mas pequeños. Esto puede haber cambiado con la nueva versión 2.0 de pdflib. Un simple banco de pruebas (el ejemplo pdfclock.c de pdflib 2.0 trasformado en un script php) en realidad no muestra ninguna diferencia en velocidad. Por tanto, pruebe las dos y vea cual hace el mejor trabajo para usted.

Esta documentación debería ser leída junto con el manual de ClibPDF ya que este explica la librería con mucho mas detalle.

Muchas funciones en le ClibPDF nativa y el módulo PHP, así como en pdflib, tienen el mismo nombre. Todas las funciones excepto cpdf_open() toman el manejador del documento com el primer parámetro. Actualmente este manejador no se usa internamente desde que ClibPDF no soporta la creación de varios documentos PDF al mismo tiempo. Realmente, ni debería intentarlo, los resultados son impredecibles. No puedo supervisar cuales son las consecuencias en un sistema multihilo. De acuerdo con el autor de ClibPDF, esto cambiará en alguno de las próximas veriones (la versión actual, cuando eto fue escrito es 1.10). Si usted necesita esta capacidad, use el módulo pdflib.

Nota: La función cpdf_set_font() ha cambiado desde que PHP3 soporta fuentes asiáticas. El parámetro que codifica ya no es un entero sino una cadena.

Una gran ventaja de ClibPDF sobre pdflib es la posibilidad de crear el documento PDF completamente en memoria sin usar ficheros temporales. Esto también proporciona la capaciad de pasar coordenadas en una unidad de longitud predefinida. Esta es una cualidad útil pero puede ser simulada con pdf_translate().

La mayoría de las funciones son fáciles de usar. La parte mas difícil es, probablemente, crear un documento PDF muy simple. El siguiente ejemplo debería ayudarle a comenzar. En él se crea un documento con una página. La página contiene el texto "Times-Roman" con una fuente de 30pt. El texto está subrayado.

Ejemplo 1. Ejemplo simple de ClibPDF

<?php
$cpdf = cpdf_open(0);
cpdf_page_init($cpdf, 1, 0, 595, 842);
cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");
cpdf_set_font($cpdf, "Times-Roman", 30, "WinAnsiEncoding");
cpdf_set_text_rendering($cpdf, 1);
cpdf_text($cpdf, "Times Roman outlined", 50, 750);
cpdf_moveto($cpdf, 50, 740);
cpdf_lineto($cpdf, 330, 740);
cpdf_stroke($cpdf);
cpdf_finalize($cpdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($cpdf);
cpdf_close($cpdf);
?>

La distribución de pdflib contiene un ejemplo mas comlejo que crea una serie de páginas con un reloj analógico. Aquí está ese ejemplo convertido en PHP usando la extensión ClibPDF:

Ejemplo 2. Ejemplo con pdfclock de la distribución pdflib 2.0

<?php
$radius = 200;
$margin = 20;
$pagecount = 40;

$pdf = cpdf_open(0);
cpdf_set_creator($pdf, "pdf_clock.php3");
cpdf_set_title($pdf, "Reloj Analógico");
  
while($pagecount-- > 0) {
  cpdf_page_init($pdf, $pagecount+1, 0, 2 * ($radius + $margin), 2 * ($radius + $margin), 1.0);
  
  cpdf_set_page_animation($pdf, 4, 0.5, 0, 0, 0);  /* limpiar */
  
  cpdf_translate($pdf, $radius + $margin, $radius + $margin);
  cpdf_save($pdf);
  cpdf_setrgbcolor($pdf, 0.0, 0.0, 1.0);
  
  /*  cambio de minuto */
  cpdf_setlinewidth($pdf, 2.0);
  for ($alpha = 0; $alpha < 360; $alpha += 6)
    {
    cpdf_rotate($pdf, 6.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin/3, 0.0);
    cpdf_stroke($pdf);
    }
  
  cpdf_restore($pdf);
  cpdf_save($pdf);
 
  /* cambios de 5 minutos */
  cpdf_setlinewidth($pdf, 3.0);
  for ($alpha = 0; $alpha < 360; $alpha += 30)
  {
    cpdf_rotate($pdf, 30.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin, 0.0);
    cpdf_stroke($pdf);
  }

  $ltime = getdate();

  /* dibujar la aguja de las horas */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['minutos']/60.0) + $ltime['horas'] - 3.0) * 30.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius/2, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* dibujar el minutero */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['segundos']/60.0) + $ltime['minutos'] - 15.0) * 6.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius * 0.8, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* dibujar la seguna mano */
  cpdf_setrgbcolor($pdf, 1.0, 0.0, 0.0);
  cpdf_setlinewidth($pdf, 2);
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['segundos'] - 15.0) * 6.0));
  cpdf_moveto($pdf, -$radius/5, 0.0);
  cpdf_lineto($pdf, $radius, 0.0);
  cpdf_stroke($pdf);
  cpdf_restore($pdf);

  /* dibujar un pequeño círculo en el centro */
  cpdf_circle($pdf, 0, 0, $radius/30);
  cpdf_fill($pdf);

  cpdf_restore($pdf);

  cpdf_finalize_page($pdf, $pagecount+1);
}

cpdf_finalize($pdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($pdf);
cpdf_close($pdf);
?>
Tabla de contenidos
cpdf_add_annotation -- Añade una anotación
cpdf_add_outline -- Añade una marca en la página actual
cpdf_arc -- Dibuja un arco
cpdf_begin_text -- Inicializa una sección de texto
cpdf_circle -- Dibuja un círculo
cpdf_clip -- Ajusta al camino actual
cpdf_close -- Cierra un documento PDF
cpdf_closepath_fill_stroke -- Cierra, llena y traza el camino actual
cpdf_closepath_stroke -- Cierra el camino y dibuja una línea a lo largo del camino
cpdf_closepath -- Cierra el camino
cpdf_continue_text -- Pone texto en la línea siguiente
cpdf_curveto -- Dibuja una curva
cpdf_end_text -- Finaliza una sección de texto
cpdf_fill_stroke -- LLena y traza el camino actual
cpdf_fill -- LLena el camino actual
cpdf_finalize_page -- Finaliza una página
cpdf_finalize -- Finaliza un documento
cpdf_global_set_document_limits -- Sets document limits for any pdf document
cpdf_import_jpeg -- Abre una imagen JPEG
cpdf_lineto -- Dibuja una línea
cpdf_moveto -- Define el punto actual
cpdf_newpath -- Starts a new path
cpdf_open -- Abre un nuevo documento PDF
cpdf_output_buffer -- Pone el documento PDF en el buffer de memoria
cpdf_page_init -- Comienza una nueva página
cpdf_place_inline_image -- Situa una imagen en la página
cpdf_rect -- Dibuja un rectángulo
cpdf_restore -- Restaura un entorno formalmente salvado
cpdf_rlineto -- Dibuja una línea
cpdf_rmoveto -- Define el punto actual
cpdf_rotate_text --  Sets text rotation angle
cpdf_rotate -- Define la rotación
cpdf_save_to_file -- Escribe el documento PDF en un fichero
cpdf_save -- Salva el entorno actual
cpdf_scale -- Define la escala
cpdf_set_action_url --  Sets hyperlink
cpdf_set_char_spacing -- Determina el espacio entre caracteres
cpdf_set_creator -- Define el campo creator en el documento PDF
cpdf_set_current_page -- Define la página actual
cpdf_set_font_directories --  Sets directories to search when using external fonts
cpdf_set_font_map_file --  Sets fontname to filename translation map when using external fonts
cpdf_set_font -- Selecciona la fuente y el tamaño actual
cpdf_set_horiz_scaling -- Define la escala horizontal del texto
cpdf_set_keywords -- Pone el valor del campo 'keywords'(palabras clave) de un documento PDF
cpdf_set_leading -- Define la distancias entre las líneas de texto
cpdf_set_page_animation -- Define la separación entre páginas
cpdf_set_subject -- Define el valor del campo subjet de un documento PDF
cpdf_set_text_matrix -- Define la matriz de texto
cpdf_set_text_pos -- Define la posición del texto
cpdf_set_text_rendering -- Determina cómo es presentado el texto
cpdf_set_text_rise -- Define la elevación del texto
cpdf_set_title -- Define el campo title de un documento PDF
cpdf_set_viewer_preferences --  How to show the document in the viewer
cpdf_set_word_spacing -- Define el espacio entre palabras
cpdf_setdash -- Defina el patrón de la raya
cpdf_setflat -- Define la monotonía
cpdf_setgray_fill -- Pone el color de relleno al valor gris
cpdf_setgray_stroke -- Define el color para dibujar al valor gris
cpdf_setgray -- Pone el color de relleno y dibujo a gris
cpdf_setlinecap -- Define el parámetro linecap
cpdf_setlinejoin -- Define el parámetro linejoin
cpdf_setlinewidth -- Define la profundidad de la línea
cpdf_setmiterlimit -- Define el límite del inglete
cpdf_setrgbcolor_fill -- Pone el color de relleno a l valor de clor rgb
cpdf_setrgbcolor_stroke -- Pone el color de dibujo al valor de color rgb
cpdf_setrgbcolor -- Pone el color de relleno y dibujo al valor de color rgb
cpdf_show_xy -- Muestra texto en la posición
cpdf_show -- Muestra el texto en la posición actual
cpdf_stringwidth -- Devuelve la anchura del texto en la fuente actual
cpdf_stroke -- Dibuja una línea a lo largo del camino
cpdf_text -- Muestra texto conparámetros
cpdf_translate -- Define el sistema de origen de coordenadas

cpdf_add_annotation

(PHP 3>= 3.0.12, PHP 4 )

cpdf_add_annotation -- Añade una anotación

Descripción

void cpdf_add_annotation ( int pdf document, double llx, double lly, double urx, double ury, string title, string content, int mode)

La función cpdf_add_annotation() añade una nota con la esquina inferior izquierda en (llx, lly) y la esquina superior derecha en (urx, ury).

El últomo parámetro opcional determina el tamaño de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada para la página. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad actual.

cpdf_add_outline

(PHP 3>= 3.0.9, PHP 4 )

cpdf_add_outline -- Añade una marca en la página actual

Descripción

void cpdf_add_outline ( int pdf document, string text)

La función cpdf_add_outline() añade una marca con el texto text que apunta a la página actual.

Ejemplo 1. Añadiendo un contorno de página

<?php
$cpdf = cpdf_open(0);
cpdf_page_init($cpdf, 1, 0, 595, 842);
cpdf_add_outline($cpdf, 0, 0, 0, 1, "Página 1");
// ...
// Algún dibujo
// ...
cpdf_finalize($cpdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($cpdf);
cpdf_close($cpdf);
?>

cpdf_arc

(PHP 3>= 3.0.8, PHP 4 )

cpdf_arc -- Dibuja un arco

Descripión

void cpdf_arc ( int pdf document, double x-koor, double y-koor, double radius, double start, double end, int mode)

La función cpdf_arc() dibuja un arco con el centro rn el punto (x-koor, y-koor) y radio radius, empezando en el ángulo start y terminando en el ángulo end.

El último parámetro opcional especifica el tamaño de la unidad. Si es 0 o se omite, se usa la unidad especificada por defecto. De otro modo las coordenadas son medidas en puntos postscript,despreciando la unidad actual.

Vea también cpdf_circle().

cpdf_begin_text

(PHP 3>= 3.0.8, PHP 4 )

cpdf_begin_text -- Inicializa una sección de texto

Descripción

void cpdf_begin_text ( int pdf document)

La función cpdf_begin_text() comienza una sección de texto. Debe ser terminada con cpdf_end_text().

Ejemplo 1. Salida de texto

<?php cpdf_begin_text($pdf);
cpdf_set_font($pdf, 16, "Helvetica", "WinAnsiEncoding");
cpdf_text($pdf, 100, 100, "Algún texto");
cpdf_end_text($pdf) ?>

Vea también cpdf_end_text().

cpdf_circle

(PHP 3>= 3.0.8, PHP 4 )

cpdf_circle -- Dibuja un círculo

Descripción

void cpdf_circle ( int pdf document, double x-koor, double y-koor, double radius, int mode)

La función cpdf_circle() dibuja un círculo con centro en el punto (x-koor, y-koor) y radio radius.

El último parámetro opcional define el tamaño de la unidad. Si es 0 o se omite, se usa el valor por defecto para la página. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad actual.

Vea también cpdf_arc().

cpdf_clip

(PHP 3>= 3.0.8, PHP 4 )

cpdf_clip -- Ajusta al camino actual

Descripción

void cpdf_clip ( int pdf document)

La función cpdf_clip() ajusta todos los dibujos al camino actual.

cpdf_close

(PHP 3>= 3.0.8, PHP 4 )

cpdf_close -- Cierra un documento PDF

Descripción

void cpdf_close ( int pdf document)

La función cpdf_close() cierra un documento PDF. Esta debería ser la última operación incluso después de cpdf_finalize(), cpdf_output_buffer() y cpdf_save_to_file().

Vea también cpdf_open().

cpdf_closepath_fill_stroke

(PHP 3>= 3.0.8, PHP 4 )

cpdf_closepath_fill_stroke -- Cierra, llena y traza el camino actual

Descripción

void cpdf_closepath_fill_stroke ( int pdf document)

La función cpdf_closepath_fill_stroke() cierra, llena el interior del caminoa catual con el color actual de relleno y dibuja el camino actual.

Vea también cpdf_closepath(), cpdf_stroke(), cpdf_fill(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill(), cpdf_setrgbcolor().

cpdf_closepath_stroke

(PHP 3>= 3.0.8, PHP 4 )

cpdf_closepath_stroke -- Cierra el camino y dibuja una línea a lo largo del camino

Descripción

void cpdf_closepath_stroke ( int pdf document)

La función cpdf_closepath_stroke() es una combinación de cpdf_closepath() y cpdf_stroke(). Después limpia el camino.

Vea también cpdf_closepath(), cpdf_stroke().

cpdf_closepath

(PHP 3>= 3.0.8, PHP 4 )

cpdf_closepath -- Cierra el camino

Descripción

void cpdf_closepath ( int pdf document)

La función cpdf_closepath() cierra el camino actual.

cpdf_continue_text

(PHP 3>= 3.0.8, PHP 4 )

cpdf_continue_text -- Pone texto en la línea siguiente

Descripción

void cpdf_continue_text ( int pdf document, string text)

La función cpdf_continue_text() pone la cadena text en la línea siguiente.

Vea también cpdf_show_xy(), cpdf_text(), cpdf_set_leading(), cpdf_set_text_pos().

cpdf_curveto

(PHP 3>= 3.0.8, PHP 4 )

cpdf_curveto -- Dibuja una curva

Descripción

void cpdf_curveto ( int pdf document, double x1, double y1, double x2, double y2, double x3, double y3, int mode)

La función cpdf_curveto() dibuja una curva Bezier desde el punto actual al punto (x3, y3) usando (x1, y1) y (x2, y2) como puntos de control.

El último parámetro opcional especifica el tamaño de la unidad. Si es 0 o se omite, se usa la unidad especificada para la página. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad en curso.

Vea también cpdf_moveto(), cpdf_rmoveto(), cpdf_rlineto(), cpdf_lineto().

cpdf_end_text

(PHP 3>= 3.0.8, PHP 4 )

cpdf_end_text -- Finaliza una sección de texto

Descripción

void cpdf_end_text ( int pdf document)

La función cpdf_end_text() finaliza unasección de texto que fue inicializada con cpdf_begin_text().

Ejemplo 1. Salida de texto

<?php cpdf_begin_text($pdf);
cpdf_set_font($pdf, 16, "Helvetica", "WinAnsiEncoding");
cpdf_text($pdf, 100, 100, "Algún texto");
cpdf_end_text($pdf) ?>

Vea también cpdf_begin_text().

cpdf_fill_stroke

(PHP 3>= 3.0.8, PHP 4 )

cpdf_fill_stroke -- LLena y traza el camino actual

Descripción

void cpdf_fill_stroke ( int pdf document)

La función cpdf_fill_stroke() llena el interior del camino actual con el color de relleno actual y dibuja el camino actual.

Vea también cpdf_closepath(), cpdf_stroke(), cpdf_fill(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill(), cpdf_setrgbcolor().

cpdf_fill

(PHP 3>= 3.0.8, PHP 4 )

cpdf_fill -- LLena el camino actual

Descripción

void cpdf_fill ( int pdf document)

La función cpdf_fill() llena el interior del camino actual con el color alctual de relleno.

Vea también cpdf_closepath(), cpdf_stroke(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill(), cpdf_setrgbcolor().

cpdf_finalize_page

(PHP 3>= 3.0.10, PHP 4 )

cpdf_finalize_page -- Finaliza una página

Descripción

void cpdf_finalize_page ( int pdf document, int page number)

La función cpdf_finalize_page() finaliza una página con número de página page number. Esta función es sólo para ahorrar memoria. Una página terminada ocupa menos memoria pero no puede volver a ser modificada.

Vea también cpdf_page_init().

cpdf_finalize

(PHP 3>= 3.0.8, PHP 4 )

cpdf_finalize -- Finaliza un documento

Descripción

void cpdf_finalize ( int pdf document)

La función cpdf_finalize() finaliza un documento. Aún se tiene que llamar a cpdf_close().

Vea también cpdf_close().

cpdf_global_set_document_limits

(PHP 4 )

cpdf_global_set_document_limits -- Sets document limits for any pdf document

Description

void cpdf_global_set_document_limits ( int maxpages, int maxfonts, int maximages, int maxannotations, int maxobjects)

La función cpdf_global_set_document_limits() define varios límites del documento. Esta función debe ser llamada antes de cpdf_open() para que haga efecto. Ello define los límites de cualquier documento abierto con anterioridad.

Vea también cpdf_open().

cpdf_import_jpeg

(PHP 3>= 3.0.9, PHP 4 )

cpdf_import_jpeg -- Abre una imagen JPEG

Descripción

int cpdf_open_jpeg ( int pdf document, string file name, double x-koor, double y-koor, double angle, double width, double height, double x-scale, double y-scale, int mode)

La función cpdf_import_jpeg() abre una imagen almacenada en el fichero de nombre file name. El formato de la imagen debe ser JPEG. La imagen es situada en la página actual en la posición (x-koor, y-koor). La imagen es rotada angle grados.

El último parámetro opcional determina el tamaño de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada para la página. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad actual.

Vea también cpdf_place_inline_image(),

cpdf_lineto

(PHP 3>= 3.0.8, PHP 4 )

cpdf_lineto -- Dibuja una línea

Descripción

void cpdf_lineto ( int pdf document, double x-koor, double y-koor, int mode)

La función cpdf_lineto() dibuja una línea desde el punto actual al punto con coordenadas (x-koor, y-koor).

El último parámetro opcional determina el tamaño de la unidad. Si es 0 o se omite, se usa el valor especificado para la página por defecto. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad actual.

Vea también cpdf_moveto(), cpdf_rmoveto(), cpdf_curveto().

cpdf_moveto

(PHP 3>= 3.0.8, PHP 4 )

cpdf_moveto -- Define el punto actual

Descripción

void cpdf_moveto ( int pdf document, double x-koor, double y-koor, int mode)

La funcióncpdf_moveto() pone el punto actual en las coordenadas x-koor y y-koor.

El último parámetro opcional determina la longitud de la unidad. Si es 0 o se omite, la unidad por defecto será la especificada para la página. De otro modo las coordenadas se medirán en puntos postscript despreciando la unidad en curso.

cpdf_newpath

(PHP 3>= 3.0.9, PHP 4 )

cpdf_newpath -- Starts a new path

Description

void cpdf_newpath ( int pdf document)

The cpdf_newpath() starts a new path on the document given by the pdf document parameter.

cpdf_open

(PHP 3>= 3.0.8, PHP 4 )

cpdf_open -- Abre un nuevo documento PDF

Descripción

int cpdf_open ( int compression, string filename)

LA función cpdf_open() abre un documento PDF nuevo. El primer parámetro activa la compresión del documento si no es igual a 0. El segundo parámetro, opcional, es el fichero en el que el documento es escrito. Si es omitido, el documento es creado en memoria y puede ser escrito en un fichero mediante la función cpdf_save_to_file() o escrito por la salida estándar con cpdf_output_buffer().

Nota: El valor de retorno será necesario en nuevas versiones de ClibPDF como el primer parámetro en todas las demás funciones que escriben en el documento PDF.

La librería ClibPDF toma el nombre de fichero "-" como sinónimo de stdout (salida estándar). Si se compila PHP como módulo de apache esto no funcionará porque la manera en que ClibPDF direcciona a la salida estándar no funciona con apache. Usted puede solucionar este problema evitando el enobre de fichero y usando cpdf_output_buffer() para la salida de documentos PDF.

Vea también cpdf_close(), cpdf_output_buffer().

cpdf_output_buffer

(PHP 3>= 3.0.9, PHP 4 )

cpdf_output_buffer -- Pone el documento PDF en el buffer de memoria

Descripción

void cpdf_output_buffer ( int pdf document)

La función cpdf_output_buffer() muestra el documento PDF por la salida estándar. El documento debe ser creado en memoria, que es el caso de la función cpdf_open() cuando ha sido llamada sin parámetros.

Vea también cpdf_open().

cpdf_page_init

(PHP 3>= 3.0.8, PHP 4 )

cpdf_page_init -- Comienza una nueva página

Descripción

void cpdf_page_init ( int pdf document, int page number, int orientation, double height, double width, double unit)

La función cpdf_page_init() crea una nueva página de altura height y profundidad width. La página tiene el número page number y orientación orientation. orientation puede ser 0 para retrato y 1 para paisaje. El último parámetro opcional unit define la unidad del sistema de coordenadas. El valor debería ser el número de puntos postscript por unidad. Como el valor de una pulgada el igual a 72 puntos, un valor de 72 sería la unidad para una pulgada. Por defecto es 72.

Vea también cpdf_set_current_page().

cpdf_place_inline_image

(PHP 3>= 3.0.9, PHP 4 )

cpdf_place_inline_image -- Situa una imagen en la página

Descripción

void cpdf_place_inline_image ( int pdf document, int image, double x-koor, double y-koor, double angle, double width, double height, int mode)

La función cpdf_place_inline_image() situa una imagen creada con las funciones de imagenes de PHP en la posición de la página (x-koor, y-koor). La imagen puede ser escalada al mismo tiempo.

El último parámetro opcional determina el tamaño de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada para la página. De otro modo las coordenadas son medidas en puntos postscript, descartando la unidad actual.

Vea también cpdf_import_jpeg(),

cpdf_rect

(PHP 3>= 3.0.8, PHP 4 )

cpdf_rect -- Dibuja un rectángulo

Descripción

void cpdf_rect ( int pdf document, double x-koor, double y-koor, double width, double height, int mode)

La función cpdf_rect() dibuja un rectángulo con su esquina inferior izquierda en el punto (x-koor, y-koor). La anchura es widgth. La altura es height.

El último parámetro opcional define el tamaño de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada para la página. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad actual.

cpdf_restore

(PHP 3>= 3.0.8, PHP 4 )

cpdf_restore -- Restaura un entorno formalmente salvado

Descripción

void cpdf_restore ( int pdf document)

La función cpdf_restore() restaura el entorno salvado con cpdf_save(). Funciona como el comando grestore de postscript. Muy útil si se quiere trasladar o rotar un objeto sin afectar ortros objetos.

Ejemplo 1. Salvar/Restaurar

<?php cpdf_save($pdf);
// hacer todo tipo de rotaciones, transformaciones, ...
cpdf_restore($pdf) ?>

Vea también cpdf_save().

cpdf_rlineto

(PHP 3>= 3.0.9, PHP 4 )

cpdf_rlineto -- Dibuja una línea

Descripción

void cpdf_rlineto ( int pdf document, double x-koor, double y-koor, int mode)

La función cpdf_rlineto() dibuja una línea desde el punto actual al punto relativo con coordenadas (x-koor, y-koor).

El último parámetro opcional determina la longitud de la unidad. Si es 0 o se omite, se usa el valor por defecto para la página. De otro modo las coordenadas se miden en puntos postscript, despreciando la unidad actual.

Vea también cpdf_moveto(), cpdf_rmoveto(), cpdf_curveto().

cpdf_rmoveto

(PHP 3>= 3.0.9, PHP 4 )

cpdf_rmoveto -- Define el punto actual

Descripción

void cpdf_rmoveto ( int pdf document, double x-koor, double y-koor, int mode)

La función cpdf_rmoveto() pone el punto actual relativo a las coordenadas x-koor y y-koor.

El último parámetro opciona determina la loingitud de la unidad. Si es 0 o se omite, la unidad por defecto será la especificada para la página. De otro modo las coordenadas se medirán en puntos postscript, despreciando la unidad en curso.

Vea también cpdf_moveto().

cpdf_rotate_text

(PHP 3>= 3.0.9, PHP 4 )

cpdf_rotate_text --  Sets text rotation angle

Description

void cpdf_rotate_text ( int pdfdoc, float angle)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cpdf_rotate

(PHP 3>= 3.0.8, PHP 4 )

cpdf_rotate -- Define la rotación

Descripción

void cpdf_rotate ( int pdf document, double angle)

La función cpdf_rotate() define la rotación en angle grados.

cpdf_save_to_file

(PHP 3>= 3.0.8, PHP 4 )

cpdf_save_to_file -- Escribe el documento PDF en un fichero

Descripción

void cpdf_save_to_file ( int pdf document, string filename)

La función cpdf_save_to_file() guarda el documento PDF en un fichero si este documeto ha sido creado en memoria. Esta función no es necesaria si el documento PDF ha sido abierto mediante la especificación de un nombre de fichero en la función cpdf_open().

Vea también cpdf_output_buffer(), cpdf_open().

cpdf_save

(PHP 3>= 3.0.8, PHP 4 )

cpdf_save -- Salva el entorno actual

Descripción

void cpdf_save ( int pdf document)

La función cpdf_save() salva el entorno actual. Funciona como el comando gsave de postscript. Muy útil si se quiere trasladar o trotar un objeto sin afetar a los demás.

Vea también cpdf_restore().

cpdf_scale

(PHP 3>= 3.0.8, PHP 4 )

cpdf_scale -- Define la escala

Descripción

void cpdf_scale ( int pdf document, double x-scale, double y-scale)

La función cpdf_scale() define el factor de escala en los dos sentidos.

cpdf_set_action_url

(PHP 3>= 3.0.9, PHP 4 )

cpdf_set_action_url --  Sets hyperlink

Description

void cpdf_set_action_url ( int pdfdoc, float xll, float yll, float xur, float xur, string url [, int mode])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cpdf_set_char_spacing

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_char_spacing -- Determina el espacio entre caracteres

Descripción

void cpdf_set_char_spacing ( int pdf document, double space)

LA función cpdf_set_char_spacing() define el espacio entre caracteres.

Vea también cpdf_set_word_spacing(), cpdf_set_leading().

cpdf_set_creator

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_creator -- Define el campo creator en el documento PDF

Descripción

void cpdf_set_creator ( string creator)

La función cpdf_set_creator() define el creador de un documento PDF.

Vea también cpdf_set_subject(), cpdf_set_title(), cpdf_set_keywords().

cpdf_set_current_page

(PHP 3>= 3.0.9, PHP 4 )

cpdf_set_current_page -- Define la página actual

Descripción

void cpdf_set_current_page ( int pdf document, int page number)

La función cpdf_set_current_page() define la página en la que se van a realizar todas las operaciones. Uno puede cambiar entre páginas a menos que una página ha sido finalizada con cpdf_finalize_page().

Vea también cpdf_finalize_page().

cpdf_set_font_directories

(PHP 4 >= 4.0.6)

cpdf_set_font_directories --  Sets directories to search when using external fonts

Description

void cpdf_set_font_directories ( int pdfdoc, string pfmdir, string pfbdir)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cpdf_set_font_map_file

(PHP 4 >= 4.0.6)

cpdf_set_font_map_file --  Sets fontname to filename translation map when using external fonts

Description

void cpdf_set_font_map_file ( int pdfdoc, string filename)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cpdf_set_font

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_font -- Selecciona la fuente y el tamaño actual

Descripción

void cpdf_set_font ( int pdf document, string font name, double size, string encoding)

La función cpdf_set_font() define la fuente actual, el tamaño y la codificación. Actualmente solo son soportadas las fuentes estándar de postscript. El último parámetro encoding puede tomar los siguientes valores: "MacRomanEncoding", "MacExpertEncoding", "WinAnsiEncoding", y "NULL". "NULL" es para el cifrado incluído en la fuente. Para mas información vea el manual de ClibPDF, especialmente para cómo soportar las fuentes asiáticas.

cpdf_set_horiz_scaling

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_horiz_scaling -- Define la escala horizontal del texto

Descripción

void cpdf_set_horiz_scaling ( int pdf document, double scale)

La función cpdf_set_horiz_scaling() define la escala horizontal al scale por ciento.

cpdf_set_keywords

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_keywords -- Pone el valor del campo 'keywords'(palabras clave) de un documento PDF

Descripción

void cpdf_set_keywords ( string keywords)

La función cpdf_set_keywords() define las palabras clave de un documento PDF.

Vea también cpdf_set_title(), cpdf_set_creator(), cpdf_set_subject().

cpdf_set_leading

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_leading -- Define la distancias entre las líneas de texto

Descripción

void cpdf_set leading ( int pdf document, double distance)

La función cpdf_set_leading() define la distancia entre las líneas de texto. Esto se usará si el texto es la salida de cpdf_continue_text().

Vea también cpdf_continue_text().

cpdf_set_page_animation

(PHP 3>= 3.0.9, PHP 4 )

cpdf_set_page_animation -- Define la separación entre páginas

Descripción

void cpdf_set_page_animation ( int pdf document, int transition, double duration)

La función cpdf_set_page_animation() define la transición entre páginas que se siguen.

El valor de transition puede ser

0 para ninguno,
1 para dos líneas que se barren a través de la pantalla, revelen la página,
2 para múltiples líneas,
3 para que una caja revele la página,
4 para una única línea,
5 para que la página naterior se disipe para revelar la pagina,
6 para que el efecto de disolución se mueva de un extremop de la página al otro,
7 para que la página antígua simplemente sea reemplazada por la nueva página (default)

El valor de duration es el número de segundos entre las páginas que se pasan.

cpdf_set_subject

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_subject -- Define el valor del campo subjet de un documento PDF

Descripción

void cpdf_set_subject ( string subject)

La función cpdf_set_subject() define el asunto de un documento PDF

Vea también cpdf_set_title(), cpdf_set_creator(), cpdf_set_keywords().

cpdf_set_text_matrix

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_text_matrix -- Define la matriz de texto

Descripción

void cpdf_set_text_matrix ( int pdf document, array matrix)

La función cpdf_set_text_matrix() define una matriz que describe una transformación aplicada a la fuente actual de texto.

cpdf_set_text_pos

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_text_pos -- Define la posición del texto

Descripción

void cpdf_set_text_pos ( int pdf document, double x-koor, double y-koor, int mode)

La función cpdf_set_text_pos() define la posición del texto para la siguiente llamada a cpdf_show().

El último parámetro opcional mode determina la longitud de la unidad. Si es 0 o se omite, se usa el valor por defecto para la página. De otro modo, las coordenadas son medidas en puntos postscript, despreciando la unidad actual.

Vea también cpdf_show(), cpdf_text().

cpdf_set_text_rendering

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_text_rendering -- Determina cómo es presentado el texto

Descripción

void cpdf_set_text_rendering ( int pdf document, int mode)

La función cpdf_set_text_rendering() determina cómo es presentado el texto. Los posibles valores para mode son 0=llenar texto, 1=poner texto, 2=llenar y poner texto, 3=invisible, 4=llenar texto y añadirlo al camino de corte, 5=poner texto y añadirlo al camino de corte, 6=llenar y poner texto y añadirlo al camino de corte, 7=añadirlo al camino de corte

cpdf_set_text_rise

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_text_rise -- Define la elevación del texto

Descripción

void cpdf_set_text_rise ( int pdf document, double value)

La función cpdf_set_text_rise() define la elevación del texto a value unidades.

cpdf_set_title

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_title -- Define el campo title de un documento PDF

Descripción

void cpdf_set_title ( string title)

La función cpdf_set_title() define el título de un documento PDF

Vea también cpdf_set_subject(), cpdf_set_creator(), cpdf_set_keywords().

cpdf_set_viewer_preferences

(PHP 3>= 3.0.9, PHP 4 )

cpdf_set_viewer_preferences --  How to show the document in the viewer

Description

void cpdf_set_viewer_preferences ( int pdfdoc, array preferences)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cpdf_set_word_spacing

(PHP 3>= 3.0.8, PHP 4 )

cpdf_set_word_spacing -- Define el espacio entre palabras

Descripción

void cpdf_set_word_spacing ( int pdf document, double space)

La función cpdf_set_word_spacing() especifica el espacio entre palabras.

Vea también cpdf_set_char_spacing(), cpdf_set_leading().

cpdf_setdash

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setdash -- Defina el patrón de la raya

Descripción

void cpdf_setdash ( int pdf document, double white, double black)

La función cpdf_setdash() define el patrón de la raya white unidades blancas y black unidades negras. Si los dos son 0 se pone una línea sólida.

cpdf_setflat

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setflat -- Define la monotonía

Descripción

void cpdf_setflat ( int pdf document, double value)

La función cpdf_setflat() pone la monotonía a un valor de entre 0 y 100.

cpdf_setgray_fill

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setgray_fill -- Pone el color de relleno al valor gris

Descripción

void cpdf_setgray_fill ( int pdf document, double value)

La función cpdf_setgray_fill() define el valor de gris actual para rellelanr un camino.

Vea también cpdf_setrgbcolor_fill().

cpdf_setgray_stroke

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setgray_stroke -- Define el color para dibujar al valor gris

Descripción

void cpdf_setgray_stroke ( int pdf document, double gray value)

La función cpdf_setgray_stroke() pone el color de dibujo actual al valor de gris dado.

Vea también cpdf_setrgbcolor_stroke().

cpdf_setgray

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setgray -- Pone el color de relleno y dibujo a gris

Descripción

void cpdf_setgray ( int pdf document, double gray value)

La función cpdf_setgray_stroke() pone el color de relleno y dibujo al color gris dado.

Vea también cpdf_setrgbcolor_stroke(), cpdf_setrgbcolor_fill().

cpdf_setlinecap

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setlinecap -- Define el parámetro linecap

Description

void cpdf_setlinecap ( int pdf document, int value)

La función cpdf_setlinecap() define el parámetro linecap entre los valores 0 y 2. 0 = empalmar al final, 1 = redondear, 2 = esquina proyectada

cpdf_setlinejoin

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setlinejoin -- Define el parámetro linejoin

Descripción

void cpdf_setlinejoin ( int pdf document, long value)

La función cpdf_setlinejoin() define el parámetro entre un valor de 0 y 2. 0 = ingletes, 1 = redondear, 2 = ángulo oblícuo

cpdf_setlinewidth

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setlinewidth -- Define la profundidad de la línea

Descripción

void cpdf_setlinewidth ( int pdf document, double width)

La función cpdf_setlinewidth() define la preofundidad de la línea a width.

cpdf_setmiterlimit

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setmiterlimit -- Define el límite del inglete

Descripción

void cpdf_setmiterlimit ( int pdf document, double value)

La función cpdf_setmiterlimit() define el límite del inglete a un valor mayor o igual a 1.

cpdf_setrgbcolor_fill

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setrgbcolor_fill -- Pone el color de relleno a l valor de clor rgb

Descripción

void cpdf_setrgbcolor_fill ( int pdf document, double red value, double green value, double blue value)

La función cpdf_setrgbcolor_fill() pone el color rgb actual para rellenar un camino.

Vea también cpdf_setrgbcolor_stroke(), cpdf_setrgbcolor().

cpdf_setrgbcolor_stroke

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setrgbcolor_stroke -- Pone el color de dibujo al valor de color rgb

Descripción

void cpdf_setrgbcolor_stroke ( int pdf document, double red value, double green value, double blue value)

La función cpdf_setrgbcolor_stroke() pone el color de dibujo actual al valor de color rgb dado.

Vea también cpdf_setrgbcolor_fill(), cpdf_setrgbcolor().

cpdf_setrgbcolor

(PHP 3>= 3.0.8, PHP 4 )

cpdf_setrgbcolor -- Pone el color de relleno y dibujo al valor de color rgb

Descripción

void cpdf_setrgbcolor ( int pdf document, double red value, double green value, double blue value)

La función cpdf_setrgbcolor_stroke() pone el color de relleno y dibujo actual al color rgb dado.

Vea también cpdf_setrgbcolor_stroke(), cpdf_setrgbcolor_fill().

cpdf_show_xy

(PHP 3>= 3.0.8, PHP 4 )

cpdf_show_xy -- Muestra texto en la posición

Descripción

void cpdf_show_xy ( int pdf document, string text, double x-koor, double y-koor, int mode)

La función cpdf_show_xy() muestra la cadena text en la posición con coordenadas (x-coor, y-coor). El último parámetro opcional determina la longitud de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada para la página. De otro modo las coordenadas son medidas en puntos postscript, despreciando la unidad actual.

Nota: La función cpdf_show_xy() es idéntica a cpdf_text() sin el parámetro opcional.

Vea también cpdf_text().

cpdf_show

(PHP 3>= 3.0.8, PHP 4 )

cpdf_show -- Muestra el texto en la posición actual

Descripción

void cpdf_show ( int pdf document, string text)

La función cpdf_show() muestra la cadena text en la posixción actual.

Vea también cpdf_text(), cpdf_begin_text(), cpdf_end_text().

cpdf_stringwidth

(PHP 3>= 3.0.8, PHP 4 )

cpdf_stringwidth -- Devuelve la anchura del texto en la fuente actual

Descripción

double cpdf_stringwidth ( int pdf document, string text)

La función cpdf_stringwidth() devuelve la anchura de la cadena text. Requiere haber definido antes una fuente.

Vea también cpdf_set_font().

cpdf_stroke

(PHP 3>= 3.0.8, PHP 4 )

cpdf_stroke -- Dibuja una línea a lo largo del camino

Descripción

void cpdf_stroke ( int pdf document)

La función cpdf_stroke() dibuja una línea a lo largo del camino actual.

Vea también cpdf_closepath(), cpdf_closepath_stroke().

cpdf_text

(PHP 3>= 3.0.8, PHP 4 )

cpdf_text -- Muestra texto conparámetros

Descripción

void cpdf_text ( int pdf document, string text, double x-koor, double y-koor, int mode, double orientation, int alignmode)

La función cpdf_text() muestra la cadena text en la posición de coordenadas (x-coor, y-coor). El parámero opcional determina la longitud de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada para la página. De otro modo las coordenadas son medidas en puntos postscript despreciando la unidad actual. El parámetro opcional orientation es la rotación del texto en grados. El parámetro opcional alignmode determina cómo está alineado el texto. Vea la documentación de ClibPDF para los posibles valores.

Vea también cpdf_show_xy().

cpdf_translate

(PHP 3>= 3.0.8, PHP 4 )

cpdf_translate -- Define el sistema de origen de coordenadas

Descripción

void cpdf_translate ( int pdf document, double x-koor, double y-koor, int mode)

La función cpdf_translate() define el sistema origen de coordenadas en el punto (x-coor, y-coor).

El último parámetro opcional determina la longitud de la unidad. Si es 0 o se omite, se usa la unidad por defecto especificada en la página. De otro modo las coordenadas son medidas en puntos postscript, depreciando la unidad actual.

XI. Crack functions

Introducción

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.


Requerimientos

More information regarding CrackLib along with the library can be found at http://www.users.dircon.co.uk/~crypto/.


Instalación

In order to use these functions, you must compile PHP with Crack support by using the --with-crack[=DIR] option.


Configuración en tiempo de ejecución

The behaviour of these functions is affected by settings in php.ini.

Tabla 1. Crack configuration options

NameDefaultChangeable
crack.default_dictionaryNULLPHP_INI_SYSTEM
For further details and definition of the PHP_INI_* constants see ini_set().


Tipos de recursos

Esta extensión no define ningún tipo de recurso.


Constantes predefinidas

Esta extensión no define ninguna constante.


Ejemplos

This example shows how to open a CrackLib dictionary, test a given password, retrieve any diagnostic messages, and close the dictionary.

Ejemplo 1. CrackLib example

<?php
// Open CrackLib Dictionary
$dictionary = crack_opendict('/usr/local/lib/pw_dict')
     or die('Unable to open CrackLib dictionary');

// Perform password check
$check = crack_check($dictionary, 'gx9A2s0x');

// Retrieve messages
$diag = crack_getlastmessage();
echo $diag; // 'strong password'

// Close dictionary
crack_closedict($dictionary);
?>

Nota: If crack_check() returns TRUE, crack_getlastmessage() will return 'strong password'.

Tabla de contenidos
crack_check -- Performs an obscure check with the given password
crack_closedict -- Closes an open CrackLib dictionary
crack_getlastmessage -- Returns the message from the last obscure check
crack_opendict -- Opens a new CrackLib dictionary

crack_check

(PHP 4 >= 4.0.5)

crack_check -- Performs an obscure check with the given password

Description

bool crack_check ( [resource dictionary, string password])

Returns TRUE if password is strong, or FALSE otherwise.

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

crack_check() performs an obscure check with the given password on the specified dictionary . If dictionary is not specified, the last opened dictionary is used.

crack_closedict

(PHP 4 >= 4.0.5)

crack_closedict -- Closes an open CrackLib dictionary

Description

bool crack_closedict ( [resource dictionary])

Devuelve TRUE si todo fue bien, FALSE en caso de fallo.

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

crack_closedict() closes the specified dictionary identifier. If dictionary is not specified, the current dictionary is closed.

crack_getlastmessage

(PHP 4 >= 4.0.5)

crack_getlastmessage -- Returns the message from the last obscure check

Description

string crack_getlastmessage ( void)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

crack_getlastmessage() returns the message from the last obscure check.

crack_opendict

(PHP 4 >= 4.0.5)

crack_opendict -- Opens a new CrackLib dictionary

Description

resource crack_opendict ( string dictionary)

Returns a dictionary resource identifier on success, or FALSE on failure.

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

crack_opendict() opens the specified CrackLib dictionary for use with crack_check().

Nota: Only one dictionary may be open at a time.

See also: crack_check(), and crack_closedict().

XII. CURL, Client URL Library Functions

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.

In order to use the CURL functions you need to install the CURL package. PHP requires that you use CURL 7.0.2-beta or higher. PHP will not work with any version of CURL below version 7.0.2-beta.

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.

These functions have been added in PHP 4.0.2.

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_exec() and then you finish off your session using the curl_close(). Here is an example that uses the CURL functions to fetch the PHP homepage into a file:

Ejemplo 1. Using PHP's CURL module to fetch the PHP homepage

<?php

$ch = curl_init ("http://www.php.net/");
$fp = fopen ("php_homepage.txt", "w");

curl_setopt ($ch, CURLOPT_INFILE, $fp);
curl_setopt ($ch, CURLOPT_HEADER, 0);

curl_exec ($ch);
curl_close ($ch);
fclose ($fp);
?>

Tabla de contenidos
curl_close -- Close a CURL session
curl_errno -- Return an integer containing the last error number
curl_error --  Return a string containing the last error for the current session
curl_exec -- Perform a CURL session
curl_getinfo --  Get information regarding a specific transfer
curl_init -- Initialize a CURL session
curl_setopt -- Set an option for a CURL transfer
curl_version -- Return the current CURL version

curl_close

(PHP 4 >= 4.0.2)

curl_close -- Close a CURL session

Description

void curl_close ( int ch)

This functions closes a CURL session and frees all ressources. The CURL handle, ch, is also deleted.

curl_errno

(PHP 4 >= 4.0.3)

curl_errno -- Return an integer containing the last error number

Description

int curl_errno ( resource ch)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

curl_error

(PHP 4 >= 4.0.3)

curl_error --  Return a string containing the last error for the current session

Description

string curl_error ( resource ch)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

curl_exec

(PHP 4 >= 4.0.2)

curl_exec -- Perform a CURL session

Description

bool curl_exec ( int ch)

This function is should be called after you initialize a CURL session and all the options for the session are set. Its purpose is simply to execute the predefined CURL session (given by the ch).

curl_getinfo

(PHP 4 >= 4.0.4)

curl_getinfo --  Get information regarding a specific transfer

Description

string curl_getinfo ( resource ch [, int opt])

Returns information about the last transfer, opt may be one of the following:

  • "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 transfered

  • "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_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 called without the optional parameter opt an assoctive array is returned with the following array elements which correspond to opt options:

  • "url"

  • "content_type"

  • "http_encode"

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

curl_init

(PHP 4 >= 4.0.2)

curl_init -- Initialize a CURL session

Description

int curl_init ( [string url])

The curl_init() will initialize a new session and return a CURL handle for use with the curl_setopt(), curl_exec(), and curl_close() functions. If the optional url parameter is supplied then the CURLOPT_URL option will be set to the value of the parameter. You can manually set this using the curl_setopt() function.

Ejemplo 1. Initializing a new CURL session and fetching a webpage

<?php
$ch = curl_init();

curl_setopt ($ch, CURLOPT_URL, "http://www.zend.com/");
curl_setopt ($ch, CURLOPT_HEADER, 0);

curl_exec ($ch);

curl_close ($ch);
?>

See also: curl_close(), curl_setopt()

curl_setopt

(PHP 4 >= 4.0.2)

curl_setopt -- Set an option for a CURL transfer

Description

bool curl_setopt ( int ch, string option, mixed value)

The curl_setopt() function will set options for a CURL session identified by the ch parameter. The option parameter is the option you want to set, and the value is the value of the option given by the option.

The value should be a long for the following options (specified in the option parameter):

  • CURLOPT_INFILESIZE: When you are uploading a file to a remote site, this option should be used to tell PHP what the expected size of the infile will be.

  • CURLOPT_VERBOSE: Set this option to a non-zero value if you want CURL to report everything that is happening.

  • CURLOPT_HEADER: Set this option to a non-zero value if you want the header to be included in the output.

  • CURLOPT_NOPROGRESS: Set this option to a non-zero value if you don't want PHP to display a progress meter for CURL transfers

    Nota: PHP automatically sets this option to a non-zero parameter, this should only be changed for debugging purposes.

  • CURLOPT_NOBODY: Set this option to a non-zero value if you don't want the body included with the output.

  • CURLOPT_FAILONERROR: Set this option to a non-zero value if you want PHP to fail silently if the HTTP code returned is greater than 300. The default behaviour is to return the page normally, ignoring the code.

  • CURLOPT_UPLOAD: Set this option to a non-zero value if you want PHP to prepare for an upload.

  • CURLOPT_POST: Set this option to a non-zero value if you want PHP to do a regular HTTP POST. This POST is a normal application/x-www-from-urlencoded kind, most commonly used by HTML forms.

  • CURLOPT_FTPLISTONLY: Set this option to a non-zero value and PHP will just list the names of an FTP directory.

  • CURLOPT_FTPAPPEND: Set this option to a non-zero value and PHP will append to the remote file instead of overwriting it.

  • CURLOPT_NETRC: Set this option to a non-zero value and PHP will scan your ~./netrc file to find your username and password for the remote site that you're establishing a connection with.

  • CURLOPT_FOLLOWLOCATION: Set this option to a non-zero value to follow any "Location: " header that the server sends as a part of the HTTP header (note this is recursive, PHP will follow as many "Location: " headers that it is sent.)

  • CURLOPT_PUT: Set this option a non-zero value to HTTP PUT a file. The file to PUT must be set with the CURLOPT_INFILE and CURLOPT_INFILESIZE.

  • CURLOPT_MUTE: Set this option to a non-zero value and PHP will be completely silent with regards to the CURL functions.

  • CURLOPT_TIMEOUT: Pass a long as a parameter that contains the maximum time, in seconds, that you'll allow the curl functions to take.

  • CURLOPT_LOW_SPEED_LIMIT: Pass a long as a parameter that contains the transfer speed in bytes per second that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for PHP to consider it too slow and abort.

  • CURLOPT_LOW_SPEED_TIME: Pass a long as a parameter that contains the time in seconds that the transfer should be below the CURLOPT_LOW_SPEED_LIMIT for PHP to consider it too slow and abort.

  • CURLOPT_RESUME_FROM: Pass a long as a parameter that contains the offset, in bytes, that you want the transfer to start from.

  • CURLOPT_SSLVERSION: Pass a long as a parameter that contains the SSL version (2 or 3) to use. By default PHP will try and determine this by itself, although, in some cases you must set this manually.

  • CURLOPT_TIMECONDITION: Pass a long as a parameter that defines how the CURLOPT_TIMEVALUE is treated. You can set this parameter to TIMECOND_IFMODSINCE or TIMECOND_ISUNMODSINCE. This is a HTTP-only feature.

  • CURLOPT_TIMEVALUE: Pass a long as a parameter that is the time in seconds since January 1st, 1970. The time will be used as specified by the CURLOPT_TIMEVALUE option, or by default the TIMECOND_IFMODSINCE will be used.

The value parameter should be a string for the following values of the option parameter:

  • CURLOPT_URL: This is the URL that you want PHP to fetch. You can also set this option when initializing a session with the curl_init() function.

  • CURLOPT_USERPWD: Pass a string formatted in the [username]:[password] manner, for PHP to use for the connection. connection.

  • CURLOPT_PROXYUSERPWD: Pass a string formatted in the [username]:[password] format for connection to the HTTP proxy.

  • CURLOPT_RANGE: Pass the specified range you want. It should be in the "X-Y" format, where X or Y may be left out. The HTTP transfers also support several intervals, seperated with commas as in X-Y,N-M.

  • CURLOPT_POSTFIELDS: Pass a string containing the full data to post in an HTTP "POST" operation.

  • CURLOPT_REFERER: Pass a string containing the "referer" header to be used in an HTTP request.

  • CURLOPT_USERAGENT: Pass a string containing the "user-agent" header to be used in an HTTP request.

  • CURLOPT_FTPPORT: Pass a string containing the which will be used to get the IP address to use for the ftp "PORT" 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_COOKIE: Pass a string containing the content of the cookie to be set in the HTTP header.

  • CURLOPT_SSLCERT: Pass a string containing the filename of PEM formatted certificate.

  • CURLOPT_SSLCERTPASSWD: Pass a string containing the password required to use the CURLOPT_SSLCERT certificate.

  • CURLOPT_COOKIEFILE: Pass a string containing the name of the file containing the cookiee data. The cookie file can be in Netscape format, or just plain HTTP-style headers dumped into a file.

  • CURLOPT_CUSTOMREQUEST: Pass a string to be used instead of GET or HEAD when doing an HTTP request. This is useful for doing DELETE or another, more obscure, HTTP request.

    Nota: Don't do this without making sure your server supports the command first.

The following options expect a file descriptor that is obtained by using the fopen() function:

  • CURLOPT_FILE: The file where the output of your transfer should be placed, the default is STDOUT.

  • CURLOPT_INFILE: The file where the input of your transfer comes from.

  • CURLOPT_WRITEHEADER: The file to write the header part of the output into.

  • CURLOPT_STDERR: The file to write errors to instead of stderr.

curl_version

(PHP 4 >= 4.0.2)

curl_version -- Return the current CURL version

Description

string curl_version ( void)

The curl_version() function returns a string containing the current CURL version.

XIII. Funciones de pago electrónico

Estas funciones solo están disponibles si el intérprete ha sido compilado con --with-cybercash=[DIR]. Estas funciones han sido añadidas en PHP4.

Tabla de contenidos
cybercash_base64_decode -- 
cybercash_base64_encode -- ???
cybercash_decr -- ???
cybercash_encr -- ???

cybercash_base64_decode

(PHP 4 <= 4.2.3)

cybercash_base64_decode -- 

Descripción

string cybercash_base64_decode ( string inbuff)

cybercash_base64_encode

(PHP 4 <= 4.2.3)

cybercash_base64_encode -- ???

Descripción

string cybercash_base64_encode ( string inbuff)

cybercash_decr

(PHP 4 <= 4.2.3)

cybercash_decr -- ???

Descripción

array cybercash_decr ( string wmk, string sk, string inbuff)

La función devuelve un array asociativo con los elementos "errcode" y, si "errcode" es FALSE, "outbuff" (string), "outLth" (long) y "macbuff" (string).

cybercash_encr

(PHP 4 <= 4.2.3)

cybercash_encr -- ???

Descripción

array cybercash_encr ( string wmk, string sk, string inbuff)

La función devuelve un array asociativo con los elementos "errcode" y, si "errcode" es FALSE, "outbuff" (string), "outLth" (long) y "macbuff" (string).

XIV. Crédit Mutuel CyberMUT functions

Introducción

This extension allows you to process credit cards transactions using Crédit Mutuel CyberMUT system (http://www.creditmutuel.fr/centre_commercial/vendez_sur_internet.html).

CyberMUT is a popular Web Payment Service in France, provided by the Crédit 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 SDK functions, except for the parameters of return for cybermut_creerformulairecm() and cybermut_creerreponsecm(), which are returned directly by functions PHP, whereas they had passed in reference in the original functions.

These functions have been added in PHP 4.0.6.

Nota: These functions only provide a link to CyberMUT SDK. Be sure to read the CyberMUT Developers Guide for full details of the required parameters.


Instalación

These functions are only available if PHP has been compiled with the --with-cybermut[=DIR] option, where DIR is the location of libcm-mac.a and cm-mac.h . 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 Crédit Mutuel).

Nota: This extension is not available on Windows platforms.

Tabla de contenidos
cybermut_creerformulairecm -- Generate HTML form of request for payment
cybermut_creerreponsecm --  Generate the acknowledgement of delivery of the confirmation of payment
cybermut_testmac --  Make sure that there no was data diddling contained in the received message of confirmation

cybermut_creerformulairecm

(4.0.5 - 4.2.3 only)

cybermut_creerformulairecm -- Generate HTML form of request for payment

Description

string cybermut_creerformulairecm ( string url_CM, string version, string TPE, string montant, string ref_commande, string texte_libre, string url_retour, string url_retour_ok, string url_retour_err, string langue, string code_societe, string texte_bouton)

cybermut_creerformulairecm() is used to generate the HTML form of request for payment.

Ejemplo 1. First step of payment (equiv cgi1.c)

<?php
// Directory where the keys are located
putenv("CMKEYDIR=/var/creditmut/cles");
 
// Version number
$VERSION="1.2";

  $retour =  cybermut_creerformulairecm(
  "https://www.creditmutuel.fr/test/telepaiement/paiement.cgi",
  $VERSION,
  "1234567890",
  "300FRF",
  $REFERENCE,
  $TEXTE_LIBRE,
  $URL_RETOUR,
  $URL_RETOUR_OK,
  $URL_RETOUR_ERR,
  "francais",
  "company",
  "Paiement par carte bancaire");
 
  echo $retour;                                                               
?>

See also cybermut_testmac() and cybermut_creerreponsecm().

cybermut_creerreponsecm

(4.0.5 - 4.2.3 only)

cybermut_creerreponsecm --  Generate the acknowledgement of delivery of the confirmation of payment

Description

string cybermut_creerreponsecm ( string phrase)

cybermut_creerreponsecm() returns a string containing delivery acknowledgement message.

The parameter is "OK" if the message of confirmation of the payment was correctly identified by cybermut_testmac(). Any other chain is regarded as an error message.

See also cybermut_creerformulairecm() and cybermut_testmac().

cybermut_testmac

(4.0.5 - 4.2.3 only)

cybermut_testmac --  Make sure that there no was data diddling contained in the received message of confirmation

Description

bool cybermut_testmac ( string code_MAC, string version, string TPE, string cdate, string montant, string ref_commande, string texte_libre, string code-retour)

cybermut_testmac() is used to make sure that there was not data diddling contained in the received message of confirmation. Pay attention to parameters code-retour and texte-libre, which cannot be evaluated as is, because of the dash. You must retrieve them by using:
<?php
  $code_retour = $_GET["code-retour"];
  $texte_libre = $_GET["texte-libre"];
?>

Ejemplo 1. Last step of payment (equiv cgi2.c)

<?php
// Make sure that Enable Track Vars is ON.
// Directory where are located the keys
putenv("CMKEYDIR=/var/creditmut/cles");
 
// Version number
$VERSION="1.2";

$texte_libre = $_GET["texte-libre"];
$code_retour = $_GET["code-retour"];                                     

$mac_ok = cybermut_testmac($MAC,$VERSION,$TPE,$date,$montant,$reference,$texte_libre,$code_retour);

if ($mac_ok) {

  //
  // insert data processing here
  //
  //

  $result=cybermut_creerreponsecm("OK");
} else {
  $result=cybermut_creerreponsecm("Document Falsifie");
}
 
?>

See also cybermut_creerformulairecm() and cybermut_creerreponsecm().

XV. Cyrus IMAP administration functions

Introducción

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

Nota: This extension is not available on Windows platforms.


Instalación

To enable Cyrus IMAP support and to use these functions you have to compile PHP with the --with-cyrus option.


Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinamicamente en tiempo de ejecución.

CYRUS_CONN_NONSYNCLITERAL (integer)

CYRUS_CONN_INITIALRESPONSE (integer)

CYRUS_CALLBACK_NUMBERED (integer)

CYRUS_CALLBACK_NOLITERAL (integer)

Tabla de contenidos
cyrus_authenticate -- Authenticate against a Cyrus IMAP server
cyrus_bind -- Bind callbacks to a Cyrus IMAP connection
cyrus_close -- Close connection to a Cyrus IMAP server
cyrus_connect -- Connect to a Cyrus IMAP server
cyrus_query -- Send a query to a Cyrus IMAP server
cyrus_unbind -- Unbind ...

cyrus_authenticate

(PHP 4 >= 4.1.0)

cyrus_authenticate -- Authenticate against a Cyrus IMAP server

Description

bool cyrus_authenticate ( resource connection [, string mechlist [, string service [, string user [, int minssf [, int maxssf]]]]])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cyrus_bind

(PHP 4 >= 4.1.0)

cyrus_bind -- Bind callbacks to a Cyrus IMAP connection

Description

bool cyrus_bind ( resource connection, array callbacks)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cyrus_close

(PHP 4 >= 4.1.0)

cyrus_close -- Close connection to a Cyrus IMAP server

Description

bool cyrus_close ( resource connection)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cyrus_connect

(PHP 4 >= 4.1.0)

cyrus_connect -- Connect to a Cyrus IMAP server

Description

resource cyrus_connect ( [string host [, string port [, int flags]]])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cyrus_query

(PHP 4 >= 4.1.0)

cyrus_query -- Send a query to a Cyrus IMAP server

Description

bool cyrus_query ( resource connection, string query)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

cyrus_unbind

(PHP 4 >= 4.1.0)

cyrus_unbind -- Unbind ...

Description

bool cyrus_unbind ( resource connection, string trigger_name)

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parametros.

XVI. Character type functions

Introducción

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.

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.

Passing anything else but a string or integer will return FALSE immediately.


Requerimientos

None besides functions from the standard C library which are always available.


Instalación

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.

Nota: Builtin support for ctype is available with PHP 4.3.0.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

Esta extensión no define ningún tipo de recurso.


Constantes predefinidas

Esta extensión no define ninguna constante.

Tabla de contenidos
ctype_alnum -- Check for alphanumeric character(s)
ctype_alpha -- Check for alphabetic character(s)
ctype_cntrl -- Check for control character(s)
ctype_digit -- Check for numeric character(s)
ctype_graph -- Check for any printable character(s) except space
ctype_lower -- Check for lowercase character(s)
ctype_print -- Check for printable character(s)
ctype_punct --  Check for any printable character which is not whitespace or an alphanumeric character
ctype_space -- Check for whitespace character(s)
ctype_upper -- Check for uppercase character(s)
ctype_xdigit --  Check for character(s) representing a hexadecimal digit

ctype_alnum

(PHP 4 >= 4.0.4)

ctype_alnum -- Check for alphanumeric character(s)

Description

bool ctype_alnum ( string text)

Returns TRUE if every character in text is either a letter or a digit, FALSE otherwise. In the standard C locale letters are just [A-Za-z]. The function is equivalent to (ctype_alpha($text) || ctype_digit($text)).

See also ctype_alpha(), ctype_digit(), and setlocale().

ctype_alpha

(PHP 4 >= 4.0.4)

ctype_alpha -- Check for alphabetic character(s)

Description

bool ctype_alpha ( string text)

Returns TRUE if every character in text is a letter from the current locale, FALSE otherwise. In the standard C locale letters are just [A-Za-z] and ctype_alpha() is equivalent to (ctype_upper($text) || ctype_lower($text)), but other languages have letters that are considered neither upper nor lower case.

See also ctype_upper(), ctype_lower(), and setlocale().

ctype_cntrl

(PHP 4 >= 4.0.4)

ctype_cntrl -- Check for control character(s)

Description

bool ctype_cntrl ( string text)

Returns TRUE if every character in text has a special control function, FALSE otherwise. Control characters are e.g. line feed, tab, esc.

ctype_digit

(PHP 4 >= 4.0.4)

ctype_digit -- Check for numeric character(s)

Description

bool ctype_digit ( string text)

Returns TRUE if every character in text is a decimal digit, FALSE otherwise.

See also ctype_alnum() and ctype_xdigit().

ctype_graph

(PHP 4 >= 4.0.4)

ctype_graph -- Check for any printable character(s) except space

Description

bool ctype_graph ( string text)

Returns TRUE if every character in text is printable and actually creates visible output (no white space), FALSE otherwise.

See also ctype_alnum(), ctype_print(), and ctype_punct().

ctype_lower

(PHP 4 >= 4.0.4)

ctype_lower -- Check for lowercase character(s)

Description

bool ctype_lower ( string text)

Returns TRUE if every character in text is a lowercase letter in the current locale.

See also ctype_alpha() and ctype_upper().

ctype_print

(PHP 4 >= 4.0.4)

ctype_print -- Check for printable character(s)

Description

bool ctype_print ( string text)

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.

See also ctype_cntrl(), ctype_graph(), and ctype_punct().

ctype_punct

(PHP 4 >= 4.0.4)

ctype_punct --  Check for any printable character which is not whitespace or an alphanumeric character

Description

bool ctype_punct ( string text)

Returns TRUE if every character in text is printable, but neither letter, digit or blank, FALSE otherwise.

See also ctype_cntrl(), ctype_graph(), and ctype_punct().

ctype_space

(PHP 4 >= 4.0.4)

ctype_space -- Check for whitespace character(s)

Description

bool ctype_space ( string text)

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.

ctype_upper

(PHP 4 >= 4.0.4)

ctype_upper -- Check for uppercase character(s)

Description

bool ctype_upper ( string text)

Returns TRUE if every character in text is a uppercase letter in the current locale.

See also ctype_alpha() and ctype_lower().

ctype_xdigit

(PHP 4 >= 4.0.4)

ctype_xdigit --  Check for character(s) representing a hexadecimal digit

Description

bool ctype_xdigit ( string text)

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.

See also ctype_digit().

XVII. Funciones de la capa de abstraccion de bases de datos (dbm-style)

Estas funciones son la base para el acceso a bases de datos del estilo Berkeley DB.

Este es un nivel de abstraccion general para varias bases de datos. Como tal su funcionalidad esta limitada a un grupo de modernas bases de datos como Sleepycat Software's DB2. (Esta no debe confundirse con IBM DB2 software, la cual es soportada mediante las funciones ODBC.)

El comportamiento de varios aspectos depende de la implementacion de la base de datos. Funciones como dba_optimize() y dba_sync() cumpliran su funcionalidad con unas bases de datos pero no con otras.

Los siguientes manejadores (handlers) estan soportados:

  • dbm es el mas antiguo (original) tipo de base de datos de la familia de Berkeley DB. Se debe evitar su uso, si es posible. Nosotros no soportamos las funciones de compatibilidad de DB2 y gdbm, porque ellas solo son compatibles a nivel de codigo fuente, pero no pueden manejar el formato original dbm.

  • ndbm es un tipo mas nuevo y mas flexible que dbm. Todavia tiene la mayoria de las limitaciones de dbm (Por lo tanto es descartado).

  • gdbm es el gestor de bases de datos de GNU (database manager).

  • db2 es Sleepycat Software's DB2. Es descrito como "un conjunto de herramientas de programacion que proveen acceso de alto nivel a bases de datos en aplicaciones standalone o en el modelo cliente/servidor. "

  • cdb es "una rapida, de confianza, sencilla herramienta para la creacion y lectura de bases de datos constantes." Fue creada por el autor de qmail y puede encontrarse en here. Como la base es constante solo se soportan las operaciones de lectura.

Ejemplo 1. Ejemplo de DBA

<?php

$id = dba_open("/tmp/test.db", "n", "db2");

if(!$id) {
    echo "dba_open failed\n";
    exit;
}

dba_replace("key", "This is an example!", $id);

if(dba_exists("key", $id)) {
    echo dba_fetch("key", $id);
    dba_delete("key", $id);
}

dba_close($id);
?>

DBA es "binary safe" y no tiene ningun limite arbitrario. Hereda todas sus limitaciones de la implementacion de base de datos que tenga.

Todos las bases de datos basadas en ficheros deben proveer un mecanismo para establecer el modo a la hora de crear nuevas bases de datos, si ello es posible. Habitualmente este modo es pasado como el cuarto argumento en dba_open() o en dba_popen().

Se puede acceder a todas las entradas de una base de datos de modo secuencial (lineal) usando las funciones dba_firstkey() y dba_nextkey(). No se puede cambiar la base de datos mientras se recorre (traversing) por ella.

Ejemplo 2. Recorriendo una base de datos

<?php

# ...open database...

$key = dba_firstkey($id);

while($key != false) {
    if(...) { # remember the key to perform some action later
        $handle_later[] = $key;
    }
    $key = dba_nextkey($id);
}

for($i = 0; $i < count($handle_later); $i++)
    dba_delete($handle_later[$i], $id);

?>

Tabla de contenidos
dba_close -- Cerrar uba base de datos
dba_delete -- Borra una entrada especificada por la clave key
dba_exists -- Comprueba si la clave key existe
dba_fetch -- Extrae los datos especificados por la clave key
dba_firstkey -- Conseguir la primera clave
dba_handlers -- List handlers available
dba_insert -- Insertar una entrada
dba_list -- List all open database files
dba_nextkey -- Extraer la siguiente clave
dba_open -- Abrir una base de datos
dba_optimize -- Optimiza la base de datos
dba_popen -- Apertura persistente de una base de datos
dba_replace -- Reemplaza o inserta una entrada
dba_sync -- Sincroniza la base de datos

dba_close

(PHP 3>= 3.0.8, PHP 4 )

dba_close -- Cerrar uba base de datos

Descripcion

void dba_close ( int handle)

dba_close() cierra la conexion con una base de datos previamente abierta y libera todos los recursos especificados por handle.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_close() no devuelve ningun valor.

Ver tambien: dba_open() dba_popen()

dba_delete

(PHP 3>= 3.0.8, PHP 4 )

dba_delete -- Borra una entrada especificada por la clave key

Descripcion

bool dba_delete ( string key, int handle)

dba_delete() borra la entrada especificada por key de la base de datos especificada por handle.

key es la clave de la entrada que es borrada.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_delete() devuelve TRUE o FALSE, si la entrada es borrada o no, respectivamente.

Ver tambien: dba_exists() dba_fetch() dba_insert() dba_replace()

dba_exists

(PHP 3>= 3.0.8, PHP 4 )

dba_exists -- Comprueba si la clave key existe

Descripcion

bool dba_exists ( string key, int handle)

dba_exists() comprueba si la clave key existe en la base de datos especificada por handle.

key es la clave para la que se realiza la comprobacion.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_exists() devuelve TRUE o FALSE, si la clave es hallada o no, respectivamente.

Ver tambien: dba_fetch() dba_delete() dba_insert() dba_replace()

dba_fetch

(PHP 3>= 3.0.8, PHP 4 )

dba_fetch -- Extrae los datos especificados por la clave key

Descripcion

string dba_fetch ( string key, int handle)

dba_fetch() extrae los datos especificados por la clave key de la base de datos determinada por handle.

key es la clave de la entrada de los datos que queremos extraer.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_fetch() devuelve la cadena asociada o FALSE, si el par key/data es hallado o no, respectivamente.

Ver tambien: dba_exists() dba_delete() dba_insert() dba_replace()

dba_firstkey

(PHP 3>= 3.0.8, PHP 4 )

dba_firstkey -- Conseguir la primera clave

Descripcion

string dba_firstkey ( int handle)

dba_firstkey() devuelve la primera clave de la base de datos especificada por handle y resetea el puntero interno de claves. Esto permite una busqueda lineal por toda la base de datos.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_firstkey() devuelve la clave o FALSE en funcion de si tiene exito o falla, respectivamente.

Ver tambien: dba_nextkey()

dba_handlers

(PHP 4 >= 4.3.0)

dba_handlers -- List handlers available

Description

array dba_handlers ( void)

dba_handlers() returns an array with all handlers suppoerted by this extension.

When the internal cdb library is used you will see 'cdb' and 'cdb_make'.

dba_insert

(PHP 3>= 3.0.8, PHP 4 )

dba_insert -- Insertar una entrada

Descripcion

bool dba_insert ( string key, string value, int handle)

dba_insert() inserta la entrada descrita con key y value dentro de la base de datos especificada por handle. Fallara si ya existe una entrada con el mismo parametro key.

key es la clave de la entrada a ser insertada.

value es el valor a ser insertado.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_insert() devuelve TRUE o FALSE, en funcion de si tiene exito o falla, respectivamente.

Ver tambien: dba_exists() dba_delete() dba_fetch() dba_replace()

dba_list

(PHP 4 >= 4.3.0)

dba_list -- List all open database files

Description

array dba_list ( void)

dba_list() returns an associative array with all open database files. This array is in the form: resourceid=>filename.

dba_nextkey

(PHP 3>= 3.0.8, PHP 4 )

dba_nextkey -- Extraer la siguiente clave

Descripcion

string dba_nextkey ( int handle)

dba_nextkey() devuelve la siguiente clave de la base de datos especificada por handle e incrementa el puntero de claves interno.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_nextkey() devuelve la clave o FALSE dependiendo de si tiene exito o falla, respectivamente.

Ver tambien: dba_firstkey()

dba_open

(PHP 3>= 3.0.8, PHP 4 )

dba_open -- Abrir una base de datos

Descripcion

int dba_open ( string path, string mode, string handler [, ...])

dba_open() establece una instancia para path con mode usando handler.

path normalmente es el "path" en el sistema de ficheros.

mode es "r" para acceso de lectura, "w" para lectura/escritura de una base de datos ya existente, "c" para lectura/escritura y creacion de una base datos si esta no existe, y "n" para crear, truncar y lectura/escritura.

handler es el nombre de el manejador (handler) que sera usado para el acceso al path. Es pasado como un parametro opcional a dba_open() y puede usarse en lugar de ella.

dba_open() devuelve un valor positivo de handler o FALSE, en el caso de que la apertura de la base de datos se realice o si falla, respectivamente.

Ver tambien: dba_popen() dba_close()

dba_optimize

(PHP 3>= 3.0.8, PHP 4 )

dba_optimize -- Optimiza la base de datos

Descripcion

bool dba_optimize ( int handle)

dba_optimize() optimiza la base de datos especificada por handle.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_optimize() devuelve TRUE o FALSE, si la optimizacion tiene exito o falla, respectivamente.

Ver tambien: dba_sync()

dba_popen

(PHP 3>= 3.0.8, PHP 4 )

dba_popen -- Apertura persistente de una base de datos

Descripcion

int dba_popen ( string path, string mode, string handler [, ...])

dba_popen() establece una instancia persistente para path con mode usando handler.

path normalmente es el "path" en el sistema de ficheros.

mode es "r" para acceso de lectura, "w" para lectura/escritura de una base de datos ya existente, "c" para lectura/escritura y creacion de una base datos si esta no existe, y "n" para crear, truncar y lectura/escritura.

handler es el nombre del manejador (handler) que sera usado para el acceso al path. Es pasado como un parametro opcional a dba_popen() y puede usarse en lugar de ella.

dba_popen() devuelve un valor positivo de handler o FALSE, en el caso de que la apertura de la base de datos se realice o si falla, respectivamente.

Ver tambien: dba_open() dba_close()

dba_replace

(PHP 3>= 3.0.8, PHP 4 )

dba_replace -- Reemplaza o inserta una entrada

Descripcion

bool dba_replace ( string key, string value, int handle)

dba_replace() reemplaza o inserta la entrada descrita con key y value dentro de la base de datos especificada por handle.

key es la clave de la entrada a insertar.

value es el valor a ser insertado.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_replace() devuelve TRUE o FALSE, dependiendo de si tiene exito o falla respectivamente.

Ver tambien: dba_exists() dba_delete() dba_fetch() dba_insert()

dba_sync

(PHP 3>= 3.0.8, PHP 4 )

dba_sync -- Sincroniza la base de datos

Descripcion

bool dba_sync ( int handle)

dba_sync() sincroniza la base de datos especificada por handle. Esto probablemente realice una escritura fisica en el disco, si es soportado.

handle es un manejador (handle) de la base de datos devuelto por dba_open().

dba_sync() devuelve TRUE o FALSE, si la sincronizacion tiene exito o falla, respectivamente.

Ver tambien: dba_optimize()

XVIII. Funciones de fecha y hora

Tabla de contenidos
checkdate -- valida una fecha u hora
date -- da formato a la fecha/hora local
getdate -- obtiene información de fecha y hora
gettimeofday -- obtiene la hora actual
gmdate -- da formato a una fecha/hora GMT/CUT
gmmktime -- obtiene el valor timestamp UNIX de una fecha GMT
gmstrftime -- da formato a una fecha/hora GMT/CUT según las convenciones locales
localtime -- Obtener la hora local
microtime -- devuelve el valor timestamp UNIX actual con microsegundos
mktime -- obtiene el timestamp UNIX de una fecha
strftime -- da formato a la hora o fecha local de acuerdo con las convenciones locales
strtotime --  Procesar cualquier descripción textual de fecha/hora en Inglés convirtiéndola en una timestamp de UNIX.
time -- devuelve el timestamp UNIX actual

checkdate

(PHP 3, PHP 4 )

checkdate -- valida una fecha u hora

Descripción

int checkdate ( int month, int day, int year)

Devuelve un valor verdadero si la fecha dada es válida; en caso contrario, devuelve un valor falso. Comprueba la validez de la fecha formada por los argumentos. Se considera válida una fecha si:

  • el año está entre 0 y 32767, ambos incluidos

  • el mes está entre 1 y 12, ambos incluidos

  • el día está en el rango permitido para el mes dado. Se tienen en consideración los años bisiestos.

date

(PHP 3, PHP 4 )

date -- da formato a la fecha/hora local

Descripción

string date ( string format [, int timestamp])

Devuelve una cadena formateada de acuerdo con la cadena de formato dada, utilizando el valor de timestamp dado o la hora local actual si no hay parámetro.

Se reconocen los siguientes caracteres en la cadena de formato:

  • a - "am" o "pm"

  • A - "AM" o "PM"

  • d - día del mes, dos dígitos con cero a la izquierda; es decir, de "01" a "31"

  • D - día de la semana, en texto, con tres letras; por ejemplo, "Fri"

  • F - mes, en texto, completo; por ejemplo, "January"

  • h - hora, de "01" a "12"

  • H - hora, de "00" a "23"

  • g - hour, sin ceros, de "1" a "12"

  • G - hour, sin ceros; de "0" a "23"

  • i - minutos; de "00" a "59"

  • j - día del mes sin cero inicial; de "1" a "31"

  • l ('L' minúscula) - día de la semana, en texto, completo; por ejemplo, "Friday"

  • L - "1" or "0", según si el año es bisiesto o no

  • m - mes; de "01" a "12"

  • n - mes sin cero inicial; de "1" a "12"

  • M - mes, en texto, 3 letras; por ejemplo, "Jan"

  • s - segundos; de "00" a "59"

  • S - sufijo ordinal en inglés, en texto, 2 caracteres; por ejemplo, "th", "nd"

  • t - número de días del mes dado; de "28" a "31"

  • U - segundos desde el valor de 'epoch'

  • w - día de la semana, en número, de "0" (domingo) a "6" (sábado)

  • Y - año, cuatro cifras; por ejemplo, "1999"

  • y - año, dos cifras; por ejemplo, "99"

  • z - día del año; de "0" a "365"

  • Z - diferencia horaria en segundos (de "-43200" a "43200")

Los caracteres no reconocidos se imprimen tal cual. El formato "Z" siempre devuelve "0" en la función gmdate()()

Ejemplo 1. Ejemplo de date()

print (date("l dS of F Y h:i:s A"));
print ("July 1, 2000 is on a " . date("l", mktime(0,0,0,7,1,2000)));

Es posible usar date() y mktime() juntas para obtener fechas futuras o pasadas.

Ejemplo 2. Ejemplo de date() y mktime()

$tomorrow  = mktime(0,0,0,date("m")  ,date("d")+1,date("Y"));
$lastmonth = mktime(0,0,0,date("m")-1,date("d"),  date("Y"));
$nextyear  = mktime(0,0,0,date("m"),  date("d"),  date("Y")+1);

Para dar formato a fechas en otros idiomas, se deben usar las funciones setlocale() y strftime().

Ver también gmdate() y mktime().

getdate

(PHP 3, PHP 4 )

getdate -- obtiene información de fecha y hora

Descripción

array getdate ( int timestamp)

Devuelve un array asociativo que contiene la información de fecha del valor timestamp como los siguientes elementos:

  • "seconds" - segundos

  • "minutes" - minutos

  • "hours" - horas

  • "mday" - día del mes

  • "wday" - día de la semana, en número

  • "mon" - mes, en número

  • "year" - año, en número

  • "yday" - día del año, en número; por ejemplo, "299"

  • "weekday" - día de la semana, en texto, completo; por ejemplo, "Friday"

  • "month" - mes, en texto, completo; por ejemplo, "January"

gettimeofday

(PHP 3>= 3.0.7, PHP 4 )

gettimeofday -- obtiene la hora actual

Descripción

array gettimeofday ( void)

Es un interfaz para gettimeofday(2). Devuelve un array asociativo que contiene los datos devueltos por esta llamada al sistema.

  • "sec" - segundos

  • "usec" - microsegundos

  • "minuteswest" - minutos al oeste de Greenwich

  • "dsttime" - tipo de corrección dst

gmdate

(PHP 3, PHP 4 )

gmdate -- da formato a una fecha/hora GMT/CUT

Descripción

string gmdate ( string format, int timestamp)

Idéntica a la función data() excepto en que la hora devuelta es la de Greenwich (GMT). Por ejemplo, si se utiliza en Finlandia (GMT +0200), la primera línea del ejemplo devuelve "Jan 01 1998 00:00:00", mientras la segunda imprime "Dec 31 1997 22:00:00".

Ejemplo 1. Ejemplo de gmdate()

echo date( "M d Y H:i:s",mktime(0,0,0,1,1,1998) );
echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) );

Ver también date(), mktime() y gmmktime().

gmmktime

(PHP 3, PHP 4 )

gmmktime -- obtiene el valor timestamp UNIX de una fecha GMT

Descripción

int gmmktime ( int hour, int minute, int second, int month, int day, int year [, int is_dst])

Idéntica a mktime(), excepto en que los parámetros representan una fecha GMT.

gmstrftime

(PHP 3>= 3.0.12, PHP 4 )

gmstrftime -- da formato a una fecha/hora GMT/CUT según las convenciones locales

Descripción

string gmstrftime ( string format, int timestamp)

Se comporta como strftime(), excepto en que la hora devuelta es la de Greenwich (GMT). Por ejemplo, si se utiliza en la zona horaria EST (GMT -0500), la primera línea del ejemplo imprime "Dec 31 1998 20:00:00", mientras la segunda imprime "Jan 01 1999 01:00:00".

Ejemplo 1. Ejemplo de gmstrftime()

setlocale ('LC_TIME','en_US');
echo strftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n";
echo gmstrftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n";

Ver también strftime().

localtime

(PHP 4 )

localtime -- Obtener la hora local

Descripción

array localtime ( [int muestra_de_tiempo [, bool es_asociativo]])

La función localtime() devuelve un vector idético al de la estructura devuelta en C por la llamada a la misma función. El primer parámetro que se le pasa a localtime() es el timestamp, una representació de una fecha/hora concretas. Si no se proporciona, se utilizará la hora actual. El segundo argumento de localtime() es es_asociativo. Si está a 0 o no es proporcionado, el vector se devuelve como un vector normal, indizado numéricamente. Si el argumento está a 1, el vector devuelto es un vector asociativo conteniendo los diferentes elementos de la estructura devuelta por C al llamar a la función localtime. Los nombres de las diferentes claves del vector asociativo se encuentran a continuación:

  • "tm_sec" - segundos

  • "tm_min" - minutos

  • "tm_hour" - horas

  • "tm_mday" - día del mes

  • "tm_mon" - mes del año, empezando en 0 que es Enero

  • "tm_year" - Años que hacen desde 1900

  • "tm_wday" - Día de la semana

  • "tm_yday" - Día del año

  • "tm_isdst" - Si el cambio de hora para el ahorro energético tiene efecto o no

microtime

(PHP 3, PHP 4 )

microtime -- devuelve el valor timestamp UNIX actual con microsegundos

Descripción

string microtime ( void)

Devuelve la cadena "msec sec", donde sec es la hora actual en número de segundos desde el valor Unix Epoch (0:00:00 del 1 de enero de 1970, hora GMT), y msec es la parte de microsegundos. Esta función sólo está disponible en sistemas operativos con admiten la llamada al sistema gettimeofday().

Ver también time().

mktime

(PHP 3, PHP 4 )

mktime -- obtiene el timestamp UNIX de una fecha

Descripción

int mktime ( int hour, int minute, int second, int month, int day, int year [, int is_dst])

Advertencia: Véase el extraño orden de los argumentos, que se diferencia del orden de argumentos en una llamada mktime() de UNIX y que no permite eliminar parámetros de derecha a izquierda (ver abajo). Es un error común mezclar estos valores en un script.

Devuelve el valor timestamp Unix correspondiente a los argumentos dados. El timestamp es un entero de tipo long que contiene el número de segundos entre el valor Unix Epoch (1 de enero de 1970) y la hora especificada.

Se pueden eliminar argumentos en orden de derecha a izquierda; en los argumentos omitidos se toma el valor de la fecha y hora locales.

is_dst puede ponerse a 1 si la hora corresponde a horario de verano, 0 si no, o -1 (valor por omisión) si no se sabe.

Nota: is_dst se añadió en la versión 3.0.10.

mktime() es útil para realizar cálculos y validaciones con fechas, ya que calcula automáticamente el valor correcto para una entrada fuera de rango. Por ejemplo, cada una de las líneas siguientes produce la cadena "Jan-01-1998".

Ejemplo 1. Ejemplo de mktime()

echo date( "M-d-Y", mktime(0,0,0,12,32,1997) );
echo date( "M-d-Y", mktime(0,0,0,13,1,1997) );
echo date( "M-d-Y", mktime(0,0,0,1,1,1998) );

El último día de cada mes se puede expresar como el día "0" del mes siguiente, no el día -1. Los dos ejemplos siguientes producen la cadena "The last day in Feb 2000 is: 29".

Ejemplo 2. El último día del próximo mes

$lastday=mktime(0,0,0,3,0,2000);
echo strftime("Last day in Feb 2000 is: %d",$lastday);
     
$lastday=mktime(0,0,0,4,-31,2000);
echo strftime("Last day in Feb 2000 is: %d",$lastday);

Ver también date() y time().

strftime

(PHP 3, PHP 4 )

strftime -- da formato a la hora o fecha local de acuerdo con las convenciones locales

Descripción

string strftime ( string format, int timestamp)

Devuelve una cadena formateada según la cadena de formato dada utilizando el valor timestamp o la hora local actual. Los nombres del mes y el día de la semana y otras cadenas dependientes del idioma respetan lo establecido con setlocale().

Se reconocen los siguientes especificadores de conversión en la cadena de formato:

  • %a - nombre del día de la semana abreviado

  • %A - nombre del día de la semana completo

  • %b - nombre del mes abreviado

  • %B - nombre del mes completo

  • %c - representación de fecha y hora preferidas en el idioma actual

  • %d - día del mes en número (de 00 a 31)

  • %H - hora como un número de 00 a 23

  • %I - hora como un número de 01 a 12

  • %j - día del año como un número de 001 a 366

  • %m - mes como un número de 01 a 12

  • %M - minuto en número

  • %p - `am' o `pm', según la hora dada, o las cadenas correspondientes en el idioma actual

  • %S - segundos en número

  • %U - número de la semana en el año, empezando con el primer domingo como el primer día de la primera semana

  • %W - número de la semana en el año, empezando con el primer lunes como el primer día de la primera semana

  • %w - día de la semana en número (el domingo es el 0)

  • %x - representación preferida de la fecha sin la hora

  • %X - representación preferida de la hora sin la fecha

  • %y - año en número de 00 a 99

  • %Y - año en número de cuatro cifras

  • %Z - nombre o abreviatura de la zona horaria

  • %% - carácter `%'

Ejemplo 1. Ejemplo de strftime()

setlocale ("LC_TIME", "C");
print(strftime("%A in Finnish is "));
setlocale ("LC_TIME", "fi_FI");
print(strftime("%A, in French "));
setlocale ("LC_TIME", "fr_CA");
print(strftime("%A and in German "));
setlocale ("LC_TIME", "de_DE");
print(strftime("%A.\n"));
Este ejemplo funciona si se tienen los respectivos `locales' instalados en el sistema.

Ver también setlocale() y mktime().

strtotime

(PHP 3>= 3.0.12, PHP 4 )

strtotime --  Procesar cualquier descripción textual de fecha/hora en Inglés convirtiéndola en una timestamp de UNIX.

Descripción

int strtotime ( string hora [, int ahora])

La función espera que se le pase una cadena conteniendo una fecha en formato Inglés e intentará procesarla y convertirla a una timestamp (muestra de tiempo) de UNIX relativa a la timestamp proporcionada en ahora, o la hora actual si no se indica ninguna. Si falla, devolverá -1.

Dado que strtotime() obra de acuerdo con la sintaxis de fechas de GNU, puede echar un vistazo a la página del manual GNU titulada Date Input Formats (Formatos de entrada de fechas). La sintaxis descrita ahí es válida para el parátro hora.

Ejemplo 1. Ejemplos con strtotime()

echo strtotime ("now"), "\n";
echo strtotime ("10 September 2000"), "\n";
echo strtotime ("+1 day"), "\n";
echo strtotime ("+1 week"), "\n";
echo strtotime ("+1 week 2 days 4 hours 2 seconds"), "\n";
echo strtotime ("next Thursday"), "\n";
echo strtotime ("last Monday"), "\n";

Ejemplo 2. Comprobando si falla

$str = 'No v&aacute;lida';
if (($timestamp = strtotime($str)) === -1) {
    echo "La cadena ($str) no es v&aacute;lida.";
} else {
    echo "$str == ". date('l dS of F Y h:i:s A',$timestamp);
}

Nota: El rango válido de una timestamp suele ser desde Fri, 13 Dec 1901 20:45:54 GMT (Viernes, 13 de diciembre) a Tue, 19 Jan 2038 03:14:07 GMT (Martes, 19 de enero). (Estas son las fechas que corresponden a los valores mínimo y máximo de un entero con signo de 32 bits.)

time

(PHP 3, PHP 4 )

time -- devuelve el timestamp UNIX actual

Descripción

int time ( void)

Devuelve la hora actual como número de segundos transcurridos desde las 00:00:00 del 1 de enero de 1970 GMT (Unix Epoch).

Ver también date().

XIX. Funciones para dBase

Estas funciones permiten el acceso a datos almacenados en formato dBase (dbf).

No hay soporte para índices o campos Memo. Tampoco hay soporte para bloqueo: si dos procesos concurrentes en el servidor modifican el mismo fichero dBase, probablemente se destruirán los datos.

A diferencia de las bases de datos SQL, las "bases de datos" dBase no pueden cambiar su definición. Una vez creado el fichero, la definición de la base de datos es fija. No hay índices que aceleren la búsqueda u organicen los datos de distinto modo. Los ficheros dBase son simples ficheros secuenciales con registros de longitud fija. Los nuevos registros se añaden al final del fichero y los registros borrados se conservan hasta que se llama a la función dbase_pack()().

Se recomienda no utilizar ficheros dBase como bases de datos, sino elegir cualquier servidor SQL; MySQL o Postgres son opciones habituales con PHP. El soporte para dBase se proporciona para permitir importar y exportar datos a y desde la base de datos web, ya que este formato de ficheros es aceptado habitualmente por las hojas de datos y los organizadores de Windows. La importación y exportación de datos es lo único para lo que sirve el soporte dBase.

Tabla de contenidos
dbase_add_record -- añade un registro a un fichero dBase
dbase_close -- cierra un fichero dBase
dbase_create -- crea una base de datos dBase
dbase_delete_record -- borra un registro del fichero dBase
dbase_get_record_with_names -- lee un registro de un fichero dBase como array asociativo
dbase_get_record -- lee un registro de un fichero dBase
dbase_numfields -- cuenta el número de campos en un fichero dBase
dbase_numrecords -- cuenta el número de registros en un fichero dBase
dbase_open -- abre un fichero dBase
dbase_pack -- "empaqueta" un fichero dBase
dbase_replace_record -- reemplaza un registro en un fichero dBase

dbase_add_record

(PHP 3, PHP 4 )

dbase_add_record -- añade un registro a un fichero dBase

Descripción

bool dbase_add_record ( int dbase_identifier, array record)

Añade los datos de record a la base de datos. Si el número de elementos del registro proporcionado no es igual al número de campos de la base de datos, la operación fallará y la función devolverá FALSE.

dbase_close

(PHP 3, PHP 4 )

dbase_close -- cierra un fichero dBase

Descripción

bool dbase_close ( int dbase_identifier)

Cierra el fichero asociado con dbase_identifier.

dbase_create

(PHP 3, PHP 4 )

dbase_create -- crea una base de datos dBase

Descripción

int dbase_create ( string filename, array fields)

El parámetro fields es un array de arrays, cada uno de los cuales describe el formato de un campo de la base de datos. Cada campo consiste de un nombre, un carácter que indica el tipo de campo, una longitud, y una precisión.

Los tipos de campos disponibles son:

L

Lógico. No tienen longitud ni precisión.

M

Memo. (Sin soporte en PHP.) No tienen longitud ni precisión.

D

Fecha (almacenada como AAAAMMDD). No tienen longitud ni precisión.

N

Número. Tienen longitud y precisión (número de cifras tras el punto decimal).

C

Cadena.

Si la base de datos se crea con éxito, se devuelve un dbase_identifier; en caso contrario, devuelve FALSE.

Ejemplo 1. Crear un fichero dBase

// "database" name
$dbname = "/tmp/test.dbf";

// database "definition"
$def =
    array(
        array("date",     "D"),
        array("name",     "C",  50),
        array("age",      "N",   3, 0),
        array("email",    "C", 128),
        array("ismember", "L")
    );

// creation
if (!dbase_create($dbname, $def))
    print "<strong>Error!</strong>";

dbase_delete_record

(PHP 3, PHP 4 )

dbase_delete_record -- borra un registro del fichero dBase

Descripción

bool dbase_delete_record ( int dbase_identifier, int record)

Marca el registro record para ser borrado del fichero de datos. Para eliminar realmente el registro del fichero, debe llamarse a la función dbase_pack().

dbase_get_record_with_names

(PHP 3>= 3.0.4, PHP 4 )

dbase_get_record_with_names -- lee un registro de un fichero dBase como array asociativo

Descripción

array dbase_get_record_with_names ( int dbase_identifier, int record)

Devuelve los datos del registro record en un array asociativo. El array incluye también un elemento con índice 'deleted' que vale 1 si el registro ha sido marcado para borrar (ver dbase_delete_record().

Cada campo se convierte al tipo PHP apropiado. (Las fechas se transforman en cadenas.)

dbase_get_record

(PHP 3, PHP 4 )

dbase_get_record -- lee un registro de un fichero dBase

Descripción

array dbase_get_record ( int dbase_identifier, int record)

Devuelve los datos del registro record en un array. El array se indexa a partir de 0, e incluye un elemento con el índice asociativo 'deleted', que vale 1 si el registro ha sido marcado para borrar (ver dbase_delete_record().

Cada campo se convierte al tipo PHP apropiado. (Las fechas se guardan como cadenas.)

dbase_numfields

(PHP 3, PHP 4 )

dbase_numfields -- cuenta el número de campos en un fichero dBase

Descripción

int dbase_numfields ( int dbase_identifier)

Devuelve el número de campos (columnas) en el fichero especificado. Los números de campo va de 0 a dbase_numfields($db)-1, mientras los números de registros van de 1 a dbase_numrecords($db).

Ejemplo 1. Uso de dbase_numfields()

$rec = dbase_get_record($db, $recno);
$nf  = dbase_numfields($db);
for ($i=0; $i < $nf; $i++) {
    print $rec[$i]."<br>\n";
}

dbase_numrecords

(PHP 3, PHP 4 )

dbase_numrecords -- cuenta el número de registros en un fichero dBase

Descripción

int dbase_numrecords ( int dbase_identifier)

Devuelve el número de registros (filas) en el fichero especificado. Los números de registro van de 1 a dbase_numrecords($db), mientras los números de campo van de 0 a dbase_numfields($db)-1.

dbase_open

(PHP 3, PHP 4 )

dbase_open -- abre un fichero dBase

Descripción

int dbase_open ( string filename, int flags)

Los "flags" son los que utiliza la llamada al sistema open(). Normalmente, 0 significa sólo lectura, 1 sólo escritura y 2 lectura y escritura.

Devuelve un dbase_identifier del fichero abierto, o FALSE si no pudo abrirse el fichero.

dbase_pack

(PHP 3, PHP 4 )

dbase_pack -- "empaqueta" un fichero dBase

Descripción

bool dbase_pack ( int dbase_identifier)

Empaqueta el fichero especificado, borrando definitivamente todos los registros marcados con la función dbase_delete_record().

dbase_replace_record

(PHP 3>= 3.0.11, PHP 4 )

dbase_replace_record -- reemplaza un registro en un fichero dBase

Descripción

bool dbase_replace_record ( int dbase_identifier, array record, int dbase_record_number)

Reemplaza los datos asociados con el registro record_number con los datos de record en el fichero de datos. Si el número de elementos del registro proporcionado no es igual al número de campos de la base de datos, la operación fallará y la función devolverá FALSE.

dbase_record_number es un entero en el rango de 1 al número de registros en el fichero de datos (devuelto por la función dbase_numrecords()).

XX. Funciones dbm

Estas funcione le permiten almacenar registros en una base de datos estilo dbm. Este tipo de base de datos (soportadas por las librerías db y gdbm de Berkeley, así como por algunas librerías del sistema y por una librería incluída para acceso a archivos de texto) guarda pares clave/valor (en oposición a los registros completos soportados por las bases de datos relacionales).

Ejemplo 1. ejemplo de dbm

$dbm = dbmopen("vistoya", "w");
if (dbmexists($dbm, $idusuario)) {
  $visto_ya = dbmfetch($dbm, $idusuario);
} else {
  dbminsert($dbm, $idusuario, time());
}
do_stuff();
dbmreplace($dbm, $idusuario, time());
dbmclose($dbm);

Tabla de contenidos
dblist -- describe la librería compatible dbm que se está usando
dbmclose -- cierra una base de datos dbm
dbmdelete -- borra el valor de una clave de una base de datos dbm
dbmexists -- dice si existe un valor para una clave dada en la base de datos dbm
dbmfetch -- obtiene un valor para una clave desde la base de datos dbm
dbmfirstkey -- obtiene la primera clave de una base de datos dbm
dbminsert -- inserta un valor para una clave en la base de datos dbm
dbmnextkey -- obtiene la siguiente clave de una base de datos dbm
dbmopen -- abre una base de datos dbm
dbmreplace -- sustituye el valor de una clave en la base de datos dbm

dblist

(PHP 3, PHP 4 )

dblist -- describe la librería compatible dbm que se está usando

Descripción

string dblist ( void)

dbmclose

(PHP 3, PHP 4 )

dbmclose -- cierra una base de datos dbm

Descripción

bool dbmclose ( int identif_dbm)

Desbloquea y cierra la base de datos especificada.

dbmdelete

(PHP 3, PHP 4 )

dbmdelete -- borra el valor de una clave de una base de datos dbm

Descripción

bool dbmdelete ( int identif_dbm, string clave)

Borra el valor para la clave en la base de datos.

Devuelve FALSE si la clave no existía en la base de datos.

dbmexists

(PHP 3, PHP 4 )

dbmexists -- dice si existe un valor para una clave dada en la base de datos dbm

Descripción

bool dbmexists ( int identif_dbm, string clave)

Devuelve TRUE si hay un valor asociado con la clave.

dbmfetch

(PHP 3, PHP 4 )

dbmfetch -- obtiene un valor para una clave desde la base de datos dbm

Descripción

string dbmfetch ( int identif_dbm, string clave)

Devuelve el valor asociado con la clave.

dbmfirstkey

(PHP 3, PHP 4 )

dbmfirstkey -- obtiene la primera clave de una base de datos dbm

Descripción

string dbmfirstkey ( int identif_dbm)

Devuelve la primera clave de la base de datos. Nótese que no se garantiza ningún orden en particular, pues la base de datos se crea utilizando una tabla hash, que no garantiza ordenación alguna.

dbminsert

(PHP 3, PHP 4 )

dbminsert -- inserta un valor para una clave en la base de datos dbm

Descripción

int dbminsert ( int identif_dbm, string clave, string valor)

Añade el valor a la base de datos con la clave especificada.

Devuelve -1 si la base de datos se abrío en modo sólo lectura, 0 si la inserción tuvo éxito y 1 si la clave ya existía (para sustituir el valor, utilice dbmreplace().)

dbmnextkey

(PHP 3, PHP 4 )

dbmnextkey -- obtiene la siguiente clave de una base de datos dbm

Descripción

string dbmnextkey ( int identif_dbm, string clave)

Devuelve la clave que sigue a clave. Llamando a dbmfirstkey() seguida de llamadas sucesivas a dbmnextkey() se pueden visitar todos los pares clave/valor de la base de datos dbm. Por ejemplo:

Ejemplo 1. Visitanco cada par clave/valor en una base de datos dbm.

$clave = dbmfirstkey($id_dbm);
while ($clave) {
    echo "$clave = " . dbmfetch($id_dbm, $clave) . "\n";
    $clave = dbmnextkey($id_dbm, $clave);
}

dbmopen

(PHP 3, PHP 4 )

dbmopen -- abre una base de datos dbm

Descripción

int dbmopen ( string fichero, string indicadores)

El primer argumento es el nombre con sendero completo del archivo dbm que se va a abrir y el segundo es el modo de apertura, que puede ser "r", "n", "c" o "w", que significan sólo lectura, nuevo (implica lectura/escritura y suele truncar una base de datos si ya existía con ese nombre), crear (implica lectura/escritura, pero sin truncar la base de datos) y abrir para lectura/escritura, respectivamente.

Devuelve un identificador que se pasa al resto de funciones dbm si tiene éxito, o FALSE si falla.

Si se utiliza el soporte de ndbm, este creará los archivos fichero.dir y fichero.pag. gdbm sólo utiliza un archivo y lo mismo hace el soporte interno de archivos de texto, mientras que el db de Berkeley crea un archivo fichero.db. Nótese que el PHP hace su propio bloqueo de archivo sobre el que pudiera realizar la propia librería dbm. El PHP no borra los archivos .lck que crea. Los utiliza simplemente como i-nodos fijos en los que hacer el bloqueo. Para más información sobre archivos dbm, vea las páginas man de su Unix o obtenga el gdbm de GNU desde ftp://prep.ai.mit.edu/pub/gnu.

dbmreplace

(PHP 3, PHP 4 )

dbmreplace -- sustituye el valor de una clave en la base de datos dbm

Descripción

bool dbmreplace ( int identif_dbm, string clave, string valor)

Sustituye el valor para la clave especificada de la base de datos.

También añadirá la clave a la base de datos si no existía antes.

XXI. dbx functions

Introducción

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.


Requerimientos

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, following databases are supported, but others will follow:

Documentation for adding additional database support to dbx can be found at http://www.guidance.nl/php/dbx/doc/.


Instalación

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.


Configuración en tiempo de ejecución

The behaviour of these functions is affected by settings in php.ini.

Tabla 1. DBX Configuration Options

NameDefaultChangeable
dbx.colnames_case"unchanged"PHP_INI_SYSTEM
For further details and definition of the PHP_INI_* constants see ini_set().

Nota: This ini-option is available available from PHP 4.3.0.

Here is a short explanation of the configuration directives.

dbx.colnames_case string

Columns names can be returned "unchanged" or converted to "uppercase" or "lowercase". This directive can be overridden with a flag to dbx_query().


Tipos de recursos

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 helds the result of a query.


Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinamicamente en tiempo de ejecución.

DBX_MYSQL (integer)

DBX_ODBC (integer)

DBX_PGSQL (integer)

DBX_MSSQL (integer)

DBX_FBSQL (integer)

DBX_OCI8 (integer) (available from PHP 4.3.0)

DBX_SYBASECT (integer)

DBX_PERSISTENT (integer)

DBX_RESULT_INFO (integer)

DBX_RESULT_INDEX (integer)

DBX_RESULT_ASSOC (integer)

DBX_COLNAMES_UNCHANGED (integer) (available from PHP 4.3.0)

DBX_COLNAMES_UPPERCASE (integer) (available from PHP 4.3.0)

DBX_COLNAMES_LOWERCASE (integer) (available from PHP 4.3.0)

DBX_CMP_NATIVE (integer)

DBX_CMP_TEXT (integer)

DBX_CMP_NUMBER (integer)

DBX_CMP_ASC (integer)

DBX_CMP_DESC (integer)

Tabla de contenidos
dbx_close -- Close an open connection/database
dbx_compare -- Compare two rows for sorting purposes
dbx_connect -- Open a connection/database
dbx_error --  Report the error message of the latest function call in the module (not just in the connection)
dbx_escape_string --  Escape a string so it can safely be used in an sql-statement.
dbx_query -- Send a query and fetch all results (if any)
dbx_sort --  Sort a result from a dbx_query by a custom sort function

dbx_close

(PHP 4 >= 4.0.6)

dbx_close -- Close an open connection/database

Description

bool dbx_close ( object link_identifier)

Devuelve TRUE si todo fue bien, FALSE en caso de fallo.

Ejemplo 1. dbx_close() example

<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Could not connect");

print("Connected successfully");
dbx_close($link);
?>

Nota: Always refer to the module-specific documentation as well.

See also: dbx_connect().

dbx_compare

(PHP 4 >= 4.1.0)

dbx_compare -- Compare two rows for sorting purposes

Description

int dbx_compare ( array row_a, array row_b, string column_key [, int flags])

dbx_compare() 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. dbx_compare() is a helper function for dbx_sort() to ease the make and use of the custom sorting function.

The flags can be set to specify comparison direction:

  • DBX_CMP_ASC - ascending order

  • DBX_CMP_DESC - descending order

and the preferred comparison type:

  • DBX_CMP_NATIVE - no type conversion

  • DBX_CMP_TEXT - compare items as strings

  • DBX_CMP_NUMBER - compare items numerically

One of the direction and one of the type constant can be combined with bitwise OR operator (|). The default value for the flags parameter is DBX_CMP_ASC | DBX_CMP_NATIVE.

Ejemplo 1. dbx_compare() example

<?php
function user_re_order ($a, $b) {
    $rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
    if ( !$rv ) {
        $rv = dbx_compare ($a, $b, "id", DBX_CMP_NUMBER);
    }
    return $rv;
}

$link   = dbx_connect (DBX_ODBC, "", "db", "username", "password")
    or die ("Could not connect");

$result = dbx_query ($link, "SELECT id, parentid, description FROM table ORDER BY id");
    // data in $result is now ordered by id

dbx_sort ($result, "user_re_order");
    // date in $result is now ordered by parentid (descending), then by id

dbx_close ($link);
?>

See also dbx_sort().

dbx_connect

(PHP 4 >= 4.0.6)

dbx_connect -- Open a connection/database

Description

object dbx_connect ( mixed module, string host, string database, string username, string password [, int persistent])

dbx_connect() 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 persistent parameter can be set to DBX_PERSISTENT, if so, a persistent connection will be created.

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)

The host, database, username and password parameters are expected, but not always used depending on the connect functions for the abstracted module.

The returned object has three properties:

database

It is the name of the currently selected database.

handle

It is a valid handle for the connected database, and as such it can be used in module-specific functions (if required).

$link = dbx_connect (DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close ($link->handle); // dbx_close($link) would be better here

module

It is used internally by dbx only, and is actually the module number mentioned above.

Ejemplo 1. dbx_connect() example

<?php
$link = dbx_connect (DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT)
    or die ("Could not connect");

print ("Connected successfully");
dbx_close ($link);
?>

Nota: Always refer to the module-specific documentation as well.

See also: dbx_close().

dbx_error

(PHP 4 >= 4.0.6)

dbx_error --  Report the error message of the latest function call in the module (not just in the connection)

Description

string dbx_error ( object link_identifier)

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

Ejemplo 1. dbx_error() example

<?php
$link   = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Could not connect");

$result = dbx_query($link, "select id from non_existing_table");
if ( $result == 0 ) {
    echo dbx_error ($link);
}
dbx_close ($link);
?>

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

dbx_escape_string

(PHP 4 >= 4.3.0)

dbx_escape_string --  Escape a string so it can safely be used in an sql-statement.

Description

string dbx_escape_string ( object link_identifier, string text)

dbx_escape_string() returns the text, escaped where necessary (such as quotes, backslashes etc). It returns NULL on error.

Ejemplo 1. dbx_escape_string() example

<?php
$link   = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Could not connect");

$text = dbx_escape_string($link, "It\'s quoted and backslashed (\\).");
$result = dbx_query($link, "insert into tbl (txt) values ('".$text."')");
if ( $result == 0 ) {
    echo dbx_error ($link);
}
dbx_close ($link);
?>

See also: dbx_query().

dbx_query

(PHP 4 >= 4.0.6)

dbx_query -- Send a query and fetch all results (if any)

Description

object dbx_query ( object link_identifier, string sql_statement [, long flags])

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.

Ejemplo 1. How to handle the returned value

<?php
$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, 'SELECT id, parentid, description FROM table');

if ( is_object($result) ) {
    // ... do some stuff here, see detailed examples below ...
    // first, print out field names and types 
    // then, draw a table filled with the returned field values
}
else if ( $result == 1 ) {
    echo("Query executed successfully, but no result set returned");
}
else {
    exit("Query failed");
}

dbx_close($link);
?>

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.

DBX_RESULT_INDEX

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.

DBX_RESULT_INFO

It provides info about columns, such as field names and field types.

DBX_RESULT_ASSOC

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.

DBX_COLNAMES_UNCHANGED (available from PHP 4.3.0)

The case of the returned column names will not be changed.

DBX_COLNAMES_UPPERCASE (available from PHP 4.3.0)

The case of the returned column names will be changed to uppercase.

DBX_COLNAMES_LOWERCASE (available from PHP 4.3.0)

The case of the returned column names will be changed to lowercase.

Note that DBX_RESULT_INDEX is always used, regardless of the actual value of flags parameter. This means that the following combinations is effective only:

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

The returing object has four or five properties depending on flags:

handle

It is a valid handle for the connected database, and as such it can be used in module specific functions (if required).

$result = dbx_query ($link, "SELECT id FROM table");
mysql_field_len ($result->handle, 0);

cols and rows

These contain the number of columns (or fields) and rows (or records) respectively.

$result = dbx_query ($link, 'SELECT id FROM table');
echo $result->rows; // number of records
echo $result->cols; // number of fields

info (optional)

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.

Ejemplo 2. lists each field's name and type

$result = dbx_query ($link, 'SELECT id FROM table',
                     DBX_RESULT_INDEX | DBX_RESULT_INFO);

for ($i = 0; $i < $result->cols; $i++ ) {
    echo $result->info['name'][$i] . "\n";
    echo $result->info['type'][$i] . "\n";  
}
data

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

Ejemplo 3. outputs the content of data property into HTML table

$result = dbx_query ($link, 'SELECT id, parentid, description FROM table');

echo "<table>\n";
foreach ( $result->data as $row ) {
    echo "<tr>\n";
    foreach ( $row as $field ) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";

Nota: Always refer to the module-specific documentation as well.

Column names for queries on an Oracle database are returned in lowercase.

See also: dbx_escape_string() and dbx_connect().

dbx_sort

(PHP 4 >= 4.0.6)

dbx_sort --  Sort a result from a dbx_query by a custom sort function

Description

bool dbx_sort ( object result, string user_compare_function)

Devuelve TRUE si todo fue bien, FALSE en caso de fallo.

Nota: It is always better to use ORDER BY SQL clause instead of dbx_sort(), if possible.

Ejemplo 1. dbx_sort() example

<?php
function user_re_order ($a, $b) {
    $rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
    if ( !$rv ) {
        $rv = dbx_compare ($a, $b, "id", DBX_CMP_NUMBER);
    }
    return $rv;
}

$link   = dbx_connect (DBX_ODBC, "", "db", "username", "password")
    or die ("Could not connect");

$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
    // data in $result is now ordered by id

dbx_sort ($result, "user_re_order");
    // data in $result is now ordered by parentid (descending), then by id

dbx_close ($link);
?>

See also dbx_compare().

XXII. DB++ Functions

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.


Introducción

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


Requerimientos

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


Instalación

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.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

dbplus_relation

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.


Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinamicamente en tiempo de ejecución.


db++ error codes

Tabla 1. DB++ Error Codes

PHP Constantdb++ constantmeaning
DBPLUS_ERR_NOERR (integer) ERR_NOERRNull error condition
DBPLUS_ERR_DUPLICATE (integer) ERR_DUPLICATETried to insert a duplicate tuple
DBPLUS_ERR_EOSCAN (integer) ERR_EOSCANEnd of scan from rget()
DBPLUS_ERR_EMPTY (integer) ERR_EMPTYRelation is empty (server)
DBPLUS_ERR_CLOSE (integer) ERR_CLOSEThe server can't close
DBPLUS_ERR_WLOCKED (integer) ERR_WLOCKEDThe record is write locked
DBPLUS_ERR_LOCKED (integer) ERR_LOCKEDRelation was already locked
DBPLUS_ERR_NOLOCK (integer) ERR_NOLOCKRelation cannot be locked
DBPLUS_ERR_READ (integer) ERR_READRead error on relation
DBPLUS_ERR_WRITE (integer) ERR_WRITEWrite error on relation
DBPLUS_ERR_CREATE (integer) ERR_CREATECreate() system call failed
DBPLUS_ERR_LSEEK (integer) ERR_LSEEKLseek() system call failed
DBPLUS_ERR_LENGTH (integer) ERR_LENGTHTuple exceeds maximum length
DBPLUS_ERR_OPEN (integer) ERR_OPENOpen() system call failed
DBPLUS_ERR_WOPEN (integer) ERR_WOPENRelation already opened for writing
DBPLUS_ERR_MAGIC (integer) ERR_MAGICFile is not a relation
DBPLUS_ERR_VERSION (integer) ERR_VERSIONFile is a very old relation
DBPLUS_ERR_PGSIZE (integer) ERR_PGSIZERelation uses a different page size
DBPLUS_ERR_CRC (integer) ERR_CRCInvalid crc in the superpage
DBPLUS_ERR_PIPE (integer) ERR_PIPEPiped relation requires lseek()
DBPLUS_ERR_NIDX (integer) ERR_NIDXToo many secondary indices
DBPLUS_ERR_MALLOC (integer) ERR_MALLOCMalloc() call failed
DBPLUS_ERR_NUSERS (integer) ERR_NUSERSError use of max users
DBPLUS_ERR_PREEXIT (integer) ERR_PREEXITCaused by invalid usage
DBPLUS_ERR_ONTRAP (integer) ERR_ONTRAPCaused by a signal
DBPLUS_ERR_PREPROC (integer) ERR_PREPROCError in the preprocessor
DBPLUS_ERR_DBPARSE (integer) ERR_DBPARSEError in the parser
DBPLUS_ERR_DBRUNERR (integer) ERR_DBRUNERRRun error in db
DBPLUS_ERR_DBPREEXIT (integer) ERR_DBPREEXITExit condition caused by prexit() * procedure
DBPLUS_ERR_WAIT (integer) ERR_WAITWait a little (Simple only)
DBPLUS_ERR_CORRUPT_TUPLE (integer) ERR_CORRUPT_TUPLEA 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_FIFOCan't create a fifo
DBPLUS_ERR_PERM (integer) ERR_PERMPermission denied
DBPLUS_ERR_TCL (integer) ERR_TCLTCL_error
DBPLUS_ERR_RESTRICTED (integer) ERR_RESTRICTEDOnly 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 

Tabla de contenidos
dbplus_add -- Add a tuple to a relation
dbplus_aql -- Perform AQL query
dbplus_chdir -- Get/Set database virtual current directory
dbplus_close -- Close a relation
dbplus_curr -- Get current tuple from relation
dbplus_errcode --  Get error string for given errorcode or last error
dbplus_errno -- Get error code for last operation
dbplus_find -- Set a constraint on a relation
dbplus_first -- Get first tuple from relation
dbplus_flush -- Flush all changes made on a relation
dbplus_freealllocks -- Free all locks held by this client
dbplus_freelock -- Release write lock on tuple
dbplus_freerlocks -- Free all tuple locks on given relation
dbplus_getlock -- Get a write lock on a tuple
dbplus_getunique -- Get a id number unique to a relation
dbplus_info -- ???
dbplus_last -- Get last tuple from relation
dbplus_lockrel -- Request write lock on relation
dbplus_next -- Get next tuple from relation
dbplus_open -- Open relation file
dbplus_prev -- Get previous tuple from relation
dbplus_rchperm -- Change relation permissions
dbplus_rcreate -- Creates a new DB++ relation
dbplus_rcrtexact -- Creates an exact but empty copy of a relation including indices
dbplus_rcrtlike -- Creates an empty copy of a relation with default indices
dbplus_resolve -- Resolve host information for relation
dbplus_restorepos -- ???
dbplus_rkeys -- Specify new primary key for a relation
dbplus_ropen -- Open relation file local
dbplus_rquery -- Perform local (raw) AQL query
dbplus_rrename -- Rename a relation
dbplus_rsecindex --  Create a new secondary index for a relation
dbplus_runlink -- Remove relation from filesystem
dbplus_rzap -- Remove all tuples from relation
dbplus_savepos -- ???
dbplus_setindex -- ???
dbplus_setindexbynumber -- ???
dbplus_sql -- Perform SQL query
dbplus_tcl -- Execute TCL code on server side
dbplus_tremove -- Remove tuple and return new current tuple
dbplus_undo -- ???
dbplus_undoprepare -- ???
dbplus_unlockrel -- Give up write lock on relation
dbplus_unselect -- Remove a constraint from relation
dbplus_update -- Update specified tuple in relation
dbplus_xlockrel -- Request exclusive lock on relation
dbplus_xunlockrel -- Free exclusive lock on relation

dbplus_add

(4.1.0 - 4.2.3 only)

dbplus_add -- Add a tuple to a relation

Description

int dbplus_add ( resource relation, array tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

This function will add a tuple to a relation. The tuple data is an array of attribute/value pairs to be inserted into the given relation. After successful execution the tuple array will contain the complete data of the newly created tuple, including all implicitly set domain fields like sequences.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

dbplus_aql

(4.1.0 - 4.2.3 only)

dbplus_aql -- Perform AQL query

Description

resource dbplus_aql ( string query [, string server [, string dbpath]])

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_aql() will execute an AQL query on the given server and dbpath.

On success it will return a relation handle. 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.

Further information on the AQL A... Query Language is provided in the original db++ manual.

dbplus_chdir

(4.1.0 - 4.2.3 only)

dbplus_chdir -- Get/Set database virtual current directory

Description

string dbplus_chdir ( [string newdir])

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_chdir() will change the virtual current directory where relation files will be looked for by dbplus_open(). dbplus_chdir() will return the absolute path of the current directory. Calling dbplus_chdir() without giving any newdir may be used to query the current working directory.

dbplus_close

(4.1.0 - 4.2.3 only)

dbplus_close -- Close a relation

Description

int dbplus_close ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Calling dbplus_close() will close a relation previously opened by dbplus_open().

dbplus_curr

(4.1.0 - 4.2.3 only)

dbplus_curr -- Get current tuple from relation

Description

int dbplus_curr ( resource relation, array tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_curr() will read the data for the current tuple for the given relation and will pass it back as an associative array in tuple.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

See also dbplus_first(), dbplus_prev(), dbplus_next(), and dbplus_last().

dbplus_errcode

(4.1.0 - 4.2.3 only)

dbplus_errcode --  Get error string for given errorcode or last error

Description

string dbplus_errcode ( int errno)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_errcode() returns a cleartext error string for the error code passed as errno of for the result code of the last db++ operation if no parameter is given.

dbplus_errno

(4.1.0 - 4.2.3 only)

dbplus_errno -- Get error code for last operation

Description

int dbplus_errno ( void)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_errno() will return the error code returned by the last db++ operation.

See also dbplus_errcode().

dbplus_find

(4.1.0 - 4.2.3 only)

dbplus_find -- Set a constraint on a relation

Description

int dbplus_find ( resource relation, array constraints, mixed tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_find() will place a constraint on the given relation. Further calls to functions like dbplus_curr() or dbplus_next() will only return tuples matching the given 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.

See also dbplus_unselect().

dbplus_first

(4.1.0 - 4.2.3 only)

dbplus_first -- Get first tuple from relation

Description

int dbplus_first ( resource relation, array tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_curr() will read the data for the first tuple for the given relation, make it the current tuple and pass it back as an associative array in tuple.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

See also dbplus_curr(), dbplus_prev(), dbplus_next(), and dbplus_last().

dbplus_flush

(4.1.0 - 4.2.3 only)

dbplus_flush -- Flush all changes made on a relation

Description

int dbplus_flush ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_flush() will write all changes applied to relation since the last flush to disk.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

dbplus_freealllocks

(4.1.0 - 4.2.3 only)

dbplus_freealllocks -- Free all locks held by this client

Description

int dbplus_freealllocks ( void)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_freeaalllocks() will free all tuple locks held by this client.

See also dbplus_getlock(), dbplus_freelock(), and dbplus_freerlocks().

dbplus_freelock

(4.1.0 - 4.2.3 only)

dbplus_freelock -- Release write lock on tuple

Description

int dbplus_freelock ( resource relation, string tname)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_freelock() will release a write lock on the given tuple previously obtained by dbplus_getlock().

See also dbplus_getlock(), dbplus_freerlocks(), and dbplus_freealllocks().

dbplus_freerlocks

(4.1.0 - 4.2.3 only)

dbplus_freerlocks -- Free all tuple locks on given relation

Description

int dbplus_freerlocks ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_freerlocks() will free all tuple locks held on the given relation.

See also dbplus_getlock(), dbplus_freelock(), and dbplus_freealllocks().

dbplus_getlock

(4.1.0 - 4.2.3 only)

dbplus_getlock -- Get a write lock on a tuple

Description

int dbplus_getlock ( resource relation, string tname)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_getlock() will request a write lock on the specified tuple. It will return zero on success or a non-zero error code, especially DBPLUS_ERR_WLOCKED, on failure.

See also dbplus_freelock(), dbplus_freerlocks(), and dbplus_freealllocks().

dbplus_getunique

(4.1.0 - 4.2.3 only)

dbplus_getunique -- Get a id number unique to a relation

Description

int dbplus_getunique ( resource relation, int uniqueid)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_getunique() will obtain a number guaranteed to be unique for the given relation and will pass it back in the variable given as uniqueid.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

dbplus_info

(4.1.0 - 4.2.3 only)

dbplus_info -- ???

Description

int dbplus_info ( resource relation, string key, array )

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_last

(4.1.0 - 4.2.3 only)

dbplus_last -- Get last tuple from relation

Description

int dbplus_last ( resource relation, array tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_curr() will read the data for the last tuple for the given relation, make it the current tuple and pass it back as an associative array in tuple.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

See also dbplus_first(), dbplus_curr(), dbplus_prev(), and dbplus_next().

dbplus_lockrel

(no version information, might be only in CVS)

dbplus_lockrel -- Request write lock on relation

Description

int dbplus_lockrel ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_lockrel() will request a write lock on the given relation. Other clients may still query the relation, but can't alter it while it is locked.

dbplus_next

(4.1.0 - 4.2.3 only)

dbplus_next -- Get next tuple from relation

Description

int dbplus_next ( resource relation, array )

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_curr() will read the data for the next tuple for the given relation, will make it the current tuple and will pass it back as an associative array in tuple.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

See also dbplus_first(), dbplus_curr(), dbplus_prev(), and dbplus_last().

dbplus_open

(4.1.0 - 4.2.3 only)

dbplus_open -- Open relation file

Description

resource dbplus_open ( string name)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

The relation file name will be opened. name can 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().

dbplus_prev

(4.1.0 - 4.2.3 only)

dbplus_prev -- Get previous tuple from relation

Description

int dbplus_prev ( resource relation, array tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_curr() will read the data for the next tuple for the given relation, will make it the current tuple and will pass it back as an associative array in tuple.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

See also dbplus_first(), dbplus_curr(), dbplus_next(), and dbplus_last().

dbplus_rchperm

(4.1.0 - 4.2.3 only)

dbplus_rchperm -- Change relation permissions

Description

int dbplus_rchperm ( resource relation, int mask, string user, string group)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rchperm() will change access permissions as specified by mask, user and group. The values for these are operating system specific.

dbplus_rcreate

(4.1.0 - 4.2.3 only)

dbplus_rcreate -- Creates a new DB++ relation

Description

resource dbplus_rcreate ( string name, mixed domlist [, boolean overwrite])

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rcreate() will create a new relation named name. An existing relation by the same name will only be overwritten if the relation is currently not in use and overwrite is set to TRUE.

domlist should contain the domain specification for the new relation within an array of domain description strings. ( dbplus_rcreate() will also accept a string with space delimited domain description strings, but it is recommended to use an array). 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.

dbplus_rcrtexact

(4.1.0 - 4.2.3 only)

dbplus_rcrtexact -- Creates an exact but empty copy of a relation including indices

Description

resource dbplus_rcrtexact ( string name, resource relation, boolean overwrite)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rcrtexact() will create an exact but empty copy of the given relation under a new name. An existing relation by the same name will only be overwritten if overwrite is TRUE and no other process is currently using the relation.

dbplus_rcrtlike

(4.1.0 - 4.2.3 only)

dbplus_rcrtlike -- Creates an empty copy of a relation with default indices

Description

resource dbplus_rcrtlike ( string name, resource relation, int flag)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rcrtexact() will create an empty copy of the given relation under a new name, but with default indices. An existing relation by the same name will only be overwritten if overwrite is TRUE and no other process is currently using the relation.

dbplus_resolve

(4.1.0 - 4.2.3 only)

dbplus_resolve -- Resolve host information for relation

Description

int dbplus_resolve ( string relation_name)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

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. The function will return an array containing these values under the keys 'sid', 'host' and 'host_path' or FALSE on error.

See also dbplus_tcl().

dbplus_restorepos

(4.1.0 - 4.2.3 only)

dbplus_restorepos -- ???

Description

int dbplus_restorepos ( resource relation, array tuple)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_rkeys

(4.1.0 - 4.2.3 only)

dbplus_rkeys -- Specify new primary key for a relation

Description

resource dbplus_rkeys ( resource relation, mixed domlist)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rkeys() will replace the current primary key for relation with the combination of domains specified by domlist.

domlist may be passed as a single domain name string or as an array of domain names.

dbplus_ropen

(4.1.0 - 4.2.3 only)

dbplus_ropen -- Open relation file local

Description

resource dbplus_ropen ( string name)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

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.

dbplus_rquery

(4.1.0 - 4.2.3 only)

dbplus_rquery -- Perform local (raw) AQL query

Description

int dbplus_rquery ( string query, string dbpath)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

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.

dbplus_rrename

(4.1.0 - 4.2.3 only)

dbplus_rrename -- Rename a relation

Description

int dbplus_rrename ( resource relation, string name)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rrename() will change the name of relation to name.

dbplus_rsecindex

(4.1.0 - 4.2.3 only)

dbplus_rsecindex --  Create a new secondary index for a relation

Description

resource dbplus_rsecindex ( resource relation, mixed domlist, int type)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rsecindex() will create a new secondary index for relation with consists of the domains specified by domlist and is of type type

domlist may be passed as a single domain name string or as an array of domain names.

dbplus_runlink

(4.1.0 - 4.2.3 only)

dbplus_runlink -- Remove relation from filesystem

Description

int dbplus_runlink ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_unlink() will close and remove the relation.

dbplus_rzap

(4.1.0 - 4.2.3 only)

dbplus_rzap -- Remove all tuples from relation

Description

int dbplus_rzap ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_rzap() will remove all tuples from relation.

dbplus_savepos

(4.1.0 - 4.2.3 only)

dbplus_savepos -- ???

Description

int dbplus_savepos ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_setindex

(4.1.0 - 4.2.3 only)

dbplus_setindex -- ???

Description

int dbplus_setindex ( resource relation, string idx_name)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_setindexbynumber

(4.1.0 - 4.2.3 only)

dbplus_setindexbynumber -- ???

Description

int dbplus_setindexbynumber ( resource relation, int idx_number)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_sql

(4.1.0 - 4.2.3 only)

dbplus_sql -- Perform SQL query

Description

resource dbplus_sql ( string query, string server, string dbpath)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_tcl

(4.1.0 - 4.2.3 only)

dbplus_tcl -- Execute TCL code on server side

Description

int dbplus_tcl ( int sid, string script)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

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.

See also dbplus_resolve().

dbplus_tremove

(4.1.0 - 4.2.3 only)

dbplus_tremove -- Remove tuple and return new current tuple

Description

int dbplus_tremove ( resource relation, array tuple [, array current])

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

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

dbplus_undo

(4.1.0 - 4.2.3 only)

dbplus_undo -- ???

Description

int dbplus_undo ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_undoprepare

(4.1.0 - 4.2.3 only)

dbplus_undoprepare -- ???

Description

int dbplus_undoprepare ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Not implemented yet.

dbplus_unlockrel

(4.1.0 - 4.2.3 only)

dbplus_unlockrel -- Give up write lock on relation

Description

int dbplus_unlockrel ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_unlockrel() will release a write lock previously obtained by dbplus_lockrel().

dbplus_unselect

(4.1.0 - 4.2.3 only)

dbplus_unselect -- Remove a constraint from relation

Description

int dbplus_unselect ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

Calling dbplus_unselect() will remove a constraint previously set by dbplus_find() on relation.

dbplus_update

(4.1.0 - 4.2.3 only)

dbplus_update -- Update specified tuple in relation

Description

int dbplus_update ( resource relation, array old, array new)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_update() replaces the tuple given by old with the data from new if and only if old completely matches a tuple within relation.

dbplus_xlockrel

(4.1.0 - 4.2.3 only)

dbplus_xlockrel -- Request exclusive lock on relation

Description

int dbplus_xlockrel ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_xlockrel() will request an exclusive lock on relation preventing even read access from other clients.

See also dbplus_xunlockrel().

dbplus_xunlockrel

(4.1.0 - 4.2.3 only)

dbplus_xunlockrel -- Free exclusive lock on relation

Description

int dbplus_xunlockrel ( resource relation)

Aviso

Este módulo es EXPERIMENTAL. Esto significa que el comportamineto de estas funciones, nombre de funciones y en definitiva TODO lo documentado aqui, puede cambiar en una futura version de PHP SIN AVISO. Quedas avisado, y utilizar este módulo es tu responsabiliad.

dbplus_xunlockrel() will release an exclusive lock on relation previously obtained by dbplus_xlockrel().

XXIII. Direct IO functions

Introducción

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.

Nota: This extension is not available on Windows platforms.


Requerimientos

Estas funciones están disponibles como parte del módulo estandar, el cual está siempre disponible.


Instalación

To get these functions to work, you have to configure PHP with --enable-dio.


Configuración en tiempo de ejecución

Esta extensión no define ninguna directiva de configuración.


Tipos de recursos

One resource type is defined by this extension: a file descriptor returnded by dio_open().


Constantes predefinidas

Esta extensión no define ninguna constante.

Tabla de contenidos
dio_close -- Closes the file descriptor given by fd
dio_fcntl -- Performs a c library fcntl on fd
dio_open --  Opens a new filename with specified permissions of flags and creation permissions of mode
dio_read --  Reads n bytes from fd and returns them, if n is not specified, reads 1k block
dio_seek -- Seeks to pos on fd from whence
dio_stat --  Gets stat information about the file descriptor fd
dio_tcsetattr --  Sets terminal attributes and baud rate for a serial port
dio_truncate --  Truncates file descriptor fd to offset bytes
dio_write --  Writes data to fd with optional truncation at length

dio_close

(PHP 4 >= 4.2.0)

dio_close -- Closes the file descriptor given by fd

Description

void dio_close ( resource fd)

The function dio_close() closes the file descriptor resource.

dio_fcntl

(PHP 4 >= 4.2.0)

dio_fcntl -- Performs a c library fcntl on fd

Description

mixed dio_fcntl ( resource fd, int cmd [, mixed arg])

The dio_fcntl() function performs the operation specified by cmd on the file descriptor fd. Some commands require additional arguments args to be supplied.

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

cmd can 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 or equal than arg and returns them.

  • F_SETFL - Sets the file descriptors flags to the value specified by arg, Which can be O_APPEND,O_NONBLOCK or O_ASYNC . To use O_ASYNC you will need to use the pcntl extension.

dio_open

(PHP 4 >= 4.2.0)

dio_open --  Opens a new filename with specified permissions of flags and creation permissions of mode

Description

resource dio_open ( string filename, int flags [, int mode])

dio_open() opens a file and returns a new file descriptor for it, or FALSE if any error occurred. If flags is O_CREAT, optional third parameter mode will set the mode of the file (creation permissions). The flags parameter can be one of the following options:

  • 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 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 file already exists

  • O_TRUNC - if file exists, and its opened for write access, file will be truncated to zero length.

  • O_APPEND - write operations write data at the end of file

  • O_NONBLOCK - sets non blocking mode

dio_read

(PHP 4 >= 4.2.0)

dio_read --  Reads n bytes from fd and returns them, if n is not specified, reads 1k block

Description

string dio_read ( resource fd [, int n])

The function dio_read() reads and returns n bytes from file with descriptor resource. If n is not specified, dio_read() reads 1K sized block and returns them.

dio_seek

(PHP 4 >= 4.2.0)

dio_seek -- Seeks to pos on fd from whence

Description

int dio_seek ( resource fd, int pos, int whence)

The function dio_seek() is used to change the file position of the file with descriptor resource. The parameter whence specifies how the position pos should be interpreted:

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

dio_stat

(PHP 4 >= 4.2.0)

dio_stat --  Gets stat information about the file descriptor fd

Description

array dio_stat ( resource fd)

Function dio_stat() returns information about the file with file descriptor fd. dio_stat() 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

On error dio_stat() returns NULL.

dio_tcsetattr

(PHP 4 >= 4.3.0)

dio_tcsetattr --  Sets terminal attributes and baud rate for a serial port

Description

dio_tcsetattr ( resource fd, array options)

The function dio_tcsetattr() sets the terminal attributes and baud rate of the open resource. The 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

Ejemplo 1. Setting the baud rate on a serial port

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_fcntl($fd,F_SETFL, O_SYNC );

dio_tcsetattr($fd, array(
  'baud' => 9600,
  'bits' => 8,
  'stop'  =>1,
  'parity' => 0
)); 

while (1) {

  $data = dio_read($fd,256);

  if ($data) {
      echo $data;
  }
} 

?>

Nota: This function was introduced in PHP 4.3.0.

dio_truncate

(PHP 4 >= 4.2.0)

dio_truncate --  Truncates file descriptor fd to offset bytes

Description

bool dio_truncate ( resource fd, int offset)

Function dio_truncate() causes the file referenced by fd to be truncated 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. Returns 0 on success, otherwise -1.

dio_write

(PHP 4 >= 4.2.0)

dio_write --  Writes data to fd with optional truncation at length

Description

int dio_write ( resource fd, string data [, int len])

The function dio_write() writes up to len bytes from data to file fd. If len is not specified, dio_write() writes all data to the specified file. dio_write() returns the number of bytes written to fd.

XXIV. Funciones con directorios

Tabla de contenidos
chdir -- cambia de directorio
chroot -- Change the root directory
dir -- clase directorio
closedir -- cierra el manejador de directorios
getcwd -- gets the current working directory
opendir -- abre el manejador de directorios
readdir -- lee las entradas del manejador de directorios
rewinddir -- rebobinar el manejador de directorios

chdir

(PHP 3, PHP 4 )

chdir -- cambia de directorio

Description

int chdir ( string directory)

Cambia el directorio PHP actual a directory. Devuelve FALSE si no puede cambiar al directorio, TRUE si todo va bien.

chroot<