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
Angela Pardo
Federico Finos
Pablo Daniel Rigazzi
Robert Sánchez
Leonardo Boshell
Javier Eguiluz Perez
Javier Tacón Iglesias

02-07-2004

Copyright

© Copyright 1997 - 2004 por el Grupo de documentación de PHP. Este manual puede ser distribuido solamente bajo los términos y condiciones definidos en la "Open Publication License" version 1.0 ó posterior. (La última versión se encuentra disponible en http://www.opencontent.org/openpub/).

La distribución de versiones modificadas de este documento está prohibida sin el permiso explícito del titular de este copyright.

La distribución de la documentación ó cualquier derivado de la misma, en cualquier tipo de formato escrito, está prohibido a menos que se obtenga permiso del titular de este copyright.

Los miembros del equipo de documentación de PHP están mencionados en la página primera de este manual. en caso de querer contactar con el grupo, escribir a phpdoc@lists.php.net.

La sección 'Extendiendo PHP 4.0' de este manual es copyright © 2000 por Zend Technologies, Ltd. Esta sección puede ser distribuida solamente bajo los términos y condiciones de la "Open Publication License", versión 1.0 ó posterior (la última versión se encuentra disponible en http://www.opencontent.org/openpub/).

Con este manual se distribuye una copia de la Licencia de Publicación Abierta.


Tabla de contenidos
Prefacio
I. Conceptos Básicos
1. Introducción
2. Una explicación sencilla
3. Instalación
4. Configuración del comportamiento de PHP
II. Referencia del Lenguaje
5. Sintaxis básica
6. Tipos
7. Variables
8. Constantes
9. Expresiones
10. Operadores
11. Estructuras de Control
12. Funciones
13. Clases y Objetos
14. Explicando las Referencias
III. Seguridad
15. Seguridad
IV. Características
16. Autentificación HTTP con PHP
17. Cookies
18. Manejo de XForms
19. Manejo de envío de archivos
20. Usando archivos remotos
21. Manejando conexiones
22. Conexiones persistentes a bases de datos
23. Modo Seguro (Safe Mode)
24. Usando PHP desde la línea de comando
V. 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. Funciones COM y .Net (Windows)
IX. Funciones de Clases/Objetos
X. Funciones ClibPDF
XI. Crack Functions
XII. Funciones CURL (Client URL Library)
XIII. Funciones de pago electrónico
XIV. Cyrus IMAP administration Functions
XV. Funciones de Tipo de Caracter
XVI. Funciones de la capa de abstraccion de bases de datos (dbm-style)
XVII. Funciones de Fecha y Hora
XVIII. Funciones para dBase
XIX. Funciones DBM Functions [obsoletas]
XX. dbx Functions
XXI. DB++ Functions
XXII. Funciones de acceso directo a E/S
XXIII. Funciones de Directorio
XXIV. DOM Functions
XXV. Funciones DOM XML
XXVI. .NET Functions
XXVII. Funciones de Gestión de Errores y Registros
XXVIII. File Alteration Monitor Functions
XXIX. FrontBase Functions
XXX. Funciones filePro
XXXI. Funciones del Sistema de Archivos
XXXII. Funciones del Formato de Datos de Formulario
XXXIII. FriBiDi Functions
XXXIV. Funciones FTP
XXXV. Funciones de Gestión de Funciones
XXXVI. Gettext
XXXVII. GMP Functions
XXXVIII. Funciones HTTP
XXXIX. Funciones para Hyperwave
XL. Hyperwave API Functions
XLI. iconv Functions
XLII. Funciones para imágenes
XLIII. Funciones IMAP, POP3 y NNTP
XLIV. Funciones de Informix
XLV. Funciones InterBase
XLVI. ID3 Functions
XLVII. Ingres II functions
XLVIII. IRC Gateway Functions
XLIX. Integración de Java y PHP
L. Funciones LDAP
LI. LZF Functions
LII. Funciones de Correo
LIII. Funciones mailparse
LIV. Funciones matemáticas
LV. Multibyte String Functions
LVI. MCAL functions
LVII. Funciones de Cifrado Mcrypt
LVIII. MCVE Payment Functions
LIX. Funciones Mhash
LX. Funciones Mimetype
LXI. Funciones de Microsoft SQL Server
LXII. Ming functions for Flash
LXIII. Funciones de Miscelánea
LXIV. mnoGoSearch Functions
LXV. Funciones mSQL
LXVI. Funciones MySQL
LXVII. Extensión mejorada de MySQL
LXVIII. Mohawk Software Session Handler Functions
LXIX. muscat Functions
LXX. Funciones de Red
LXXI. Funciones de Control de Pantalla con Terminal Ncurses
LXXII. Lotus Notes Functions
LXXIII. NSAPI-specific Functions
LXXIV. ODBC functions
LXXV. Object Aggregation/Composition Functions
LXXVI. Funciones de Oracle 8
LXXVII. OpenSSL Functions
LXXVIII. Funciones Oracle
LXXIX. Ovrimos SQL functions
LXXX. Funciones de Control de Salida
LXXXI. Object property and method call overloading
LXXXII. Funciones PDF
LXXXIII. Verisign Payflow Pro functions
LXXXIV. Opciones e Información de PHP
LXXXV. Funciones POSIX
LXXXVI. Funciones PostgreSQL
LXXXVII. Process Control Functions
LXXXVIII. Funciones de Ejecución de Programas
LXXXIX. Printer Functions
XC. Pspell Functions
XCI. GNU Readline
XCII. Funciones GNU Recode
XCIII. Funciones de Expresiones Regulares (Compatibles con Perl)
XCIV. qtdom Functions
XCV. Funciones de Expresiones Regulares (POSIX Extendido)
XCVI. Funciones Semáforo y de memoria compartida
XCVII. SESAM database functions
XCVIII. Funciones para el manejo de sesiones
XCIX. Funciones de Memoria Compartida
C. SimpleXML functions
CI. SOAP Functions
CII. SQLite
CIII. Shockwave Flash functions
CIV. Funciones SNMP
CV. Funciones de Socket
CVI. Standard PHP Library (SPL) Functions
CVII. Funciones de Secuencias
CVIII. Funciones de Cadenas
CIX. Funciones de Sybase
CX. TCP Wrappers Functions
CXI. Tidy Functions
CXII. Tokenizer Functions
CXIII. Funciones de URL
CXIV. Funciones de Variables
CXV. vpopmail Functions
CXVI. W32api Functions
CXVII. Funciones WDDX
CXVIII. Funciones de intérprete XML
CXIX. XML-RPC Functions
CXX. xdiff Functions
CXXI. XSL functions
CXXII. XSLT functions
CXXIII. YAZ
CXXIV. NIS funciona
CXXV. Funciones de manejo de archivos Zip (sólo lectura)
CXXVI. Funciones de Compresión Zlib
VI. Zend API
25. Overview
26. Extension Possibilities
27. Source Layout
28. PHP's Automatic Build System
29. Creating Extensions
30. Using Extensions
31. Troubleshooting
32. Source Discussion
33. Accepting Arguments
34. Creating Variables
35. Duplicating Variable Contents: The Copy Constructor
36. Returning Values
37. Printing Information
38. Startup and Shutdown Functions
39. Calling User Functions
40. Initialization File Support
41. Where to Go from Here
42. Reference: Some Configuration Macros
43. API Macros
VII. PHP API: Interfaces para autores de extensiones
44. API de Secuencia para Autores de Extensiones PHP
VIII. FAQ: Preguntas frecuentes
45. General Information
46. Listas de correo
47. Obtención de PHP
48. Database issues
49. Instalación
50. Build Problems
51. Uso de PHP
52. PHP and HTML
53. PHP and COM
54. PHP y otros lenguajes
55. Migración de PHP 2 a PHP 3
56. Migración de PHP 3 a PHP 4
57. Preguntas Varias
IX. Apéndices
A. Historia de PHP y proyectos relacionados
B. Migrating from PHP 4 to PHP 5
C. Migración de PHP 3 a PHP 4
D. Migración desde PHP/FI 2 hacia PHP 3
E. Depuración en PHP
F. Extensión de PHP 3
G. Configure options
H. Lista de directivas de núcleo en php.ini
I. Lista de alias de funciones
J. Lista de Palabras Reservadas
K. Lista de Tipos de Recurso
L. Lista de Protocolos/Envolturas Soportadas
M. List of Available Filters
N. Lista de Transportes de Sockets Soportados
O. Tablas de comparación de tipos PHP
P. Lista de Identificadores (tokens) del Analizador
Q. Sobre el manual
R. Open Publication License
S. Índice de funciones
T. Material 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. Más información sobre como este manual es desarrollado puede encontrarse en el apéndice 'Sobre este manual'.

Ver tambien Historia de PHP


Capítulo 1. Introducción

¿Qué es PHP?

PHP (acrónimo de "PHP: Hypertext Preprocessor") es un lenguaje de "código abierto" interpretado, de alto nivel, embebido en páginas HTML y ejecutado en el servidor.

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

Ejemplo 1-1. Un ejemplo introductorio

<html>
    <head>
        <title>Ejemplo</title>
    </head>
    <body>

        <?php 
        echo "Hola, &iexcl;soy un script PHP!"; 
        ?>

    </body>
</html>

Puede apreciarse 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 (incluido) 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 tuviésemos un script similar al de nuestro ejemplo en nuestro servidor, el cliente solamente recibiría el resultado de su ejecución en el servidor, sin ninguna posibilidad de determinar qué código ha producido el resultado recibido. El servidor web puede ser incluso configurado para que procese todos los archivos HTML con PHP.

Lo mejor de usar PHP es que es extremadamente simple para el principiante, pero a su vez, ofrece muchas características avanzadas para los programadores profesionales. No sienta miedo de leer la larga lista de características de PHP, en poco tiempo podrá empezar a escribir sus primeros scripts.

Aunque el desarrollo de PHP está concentrado en la programación de scripts en el lado del servidor, se puede utilizar para muchas otras cosas. Siga leyendo y descubra 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 enviar y recibir cookies. Y esto no es todo, se puede hacer mucho más.

Existen tres campos en los que se usan scripts escritos en PHP.

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

  • Scripts en la línea de comandos. Puede crear un script PHP y correrlo sin ningún servidor web o navegador. Solamente necesita el intérprete PHP para usarlo de esta manera. Este tipo de uso es ideal para scripts ejecutados regularmente desde cron (en *nix o Linux) o el Planificador de tareas (en Windows). Estos scripts también pueden ser usados para tareas simples de procesamiento de texto. Consultar la sección Usos de PHP en la línea de comandos para más información.

  • Escribir aplicaciones de interfaz gráfica. Probablemente PHP no sea el lenguaje más apropiado para escribir aplicaciones gráficas, pero si conoce bien PHP, y quisiera utilizar algunas características avanzadas en programas clientes, puede utilizar PHP-GTK para escribir dichos programas. También es posible escribir aplicaciones independientes de una plataforma. PHP-GTK es una extensión de PHP, no disponible en la distribución principal. Si está interesado en PHP-GTK, puedes visitar las páginas web del proyecto.

PHP puede ser utilizado en cualquiera de los principales sistemas operativos del mercado, incluyendo Linux, muchas variantes Unix (incluyendo 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 e 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.

De modo que, con PHP tiene la libertad de elegir el sistema operativo y el servidor de su gusto. También tiene la posibilidad de usar programación procedimental o programación orientada a objetos. Aunque no todas las características estándar de la programación orientada a objetos están implementadas en la versión actual de PHP, muchas bibliotecas y aplicaciones grandes (incluyendo la biblioteca PEAR) están escritas íntegramente usando programación orientada a objetos.

Con PHP no se encuentra limitado a resultados en HTML. Entre las habilidades de PHP se incluyen: creación de imágenes, archivos PDF y películas Flash (usando libswf y Ming) sobre la marcha. Tambié puede presentar otros resultados, como XHTM y archivos XML. PHP puede autogenerar éstos archivos y almacenarlos en el sistema de archivos en vez de presentarlos en la pantalla.

Quizás la característica más potente y destacable de PHP es su soporte para una gran cantidad de bases de datos. Escribir un interfaz vía 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

También contamos con una extensión DBX de abstracción de base de datos que permite usar de forma transparente cualquier base de datos soportada por la extensión. Adicionalmente, PHP soporta ODBC (el Estándar Abierto de Conexión con Bases de Datos), asi que puede conectarse a cualquier base de datos que soporte tal estándar.

PHP también cuenta con soporte para comunicarse con otros servicios usando protocolos tales como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (en Windows) y muchos otros. También se pueden crear sockets puros. PHP soporta WDDX para el 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 procesamiento de texto, desde expresiones regulares POSIX extendidas o tipo Perl hasta procesadores de documentos XML. Para procesar y acceder a documentos XML, soportamos los estándares SAX y DOM. Puede utilizar la extensión XSLT para transformar documentos XML.

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

Para terminar, contamos con 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 puede apreciar, esta página no es suficiente para enumerar todas las características y beneficios que PHP ofrece. Consulte las secciones Instalación de PHP y Referencia de las funciones para una explicación de las extensiones mencionadas aquí.


Capítulo 2. Una explicación sencilla

A continuación, le introduciremos a PHP en un pequeño y sencillo manual. Este documento explica cómo crear páginas web dinámicas para Internet con PHP, aunque PHP no solamente está diseñado para la creación de éstas. Consulte la sección titulada ¿Qué se puede hacer con PHP? para más información.

Las páginas web que utilizan PHP son tratadas como páginas de HTML comunes y corrientes, y puede crearlas y editarlas de la misma manera que lo hace con documentos normales de HTML.


¿Qué necesito?

En este manual vamos a asumir que usted cuenta con un servidor que soporta PHP y que todos los archivos con la extensión .php son manejados por PHP. En la mayoría de servidores, ésta es la extensión que toman los archivos PHP por defecto, pero pregunte al administrador de su servidor para estar seguro. Si su servidor soporta PHP, entonces no necesita hacer nada, solamente crear sus archivos .php y guardarlos en su directorio web, y el servidor, como por arte de magia, los analizará para usted. No hay necesidad de compilar nada, tampoco tiene necesidad de instalar otras herramientas. Mírelo de esta manera, estos archivos de PHP son tan simples como archivos de HTML con una nueva familia de etiquetas que le permiten una gran cantidad de cosas. La mayoría de las compañías de hospedaje de páginas web ofrecen el soporte que necesita para usar PHP, pero si por alguna razón ellos no lo hacen, considere leer la sección titulada Recursos PHP para mas información acerca de compañías de hospedaje que soportan PHP

Digamos que usted tiene limitado acceso a internet y se encuentra programando localmente. En este caso, querrá instalar un servidor de web como Apache, y PHP. Lo más seguro es que también quiera instalar una base de datos como MySQL. Puede instalar estos productos individualmente o simplemente localizar un paquete pre-configurado que automáticamente instale todos estos productos con solamente unos movimientos de su ratón. Es muy fácil instalar un servidor web con soporte para PHP en cualquier sistemas operativo, incluyendo Linux y Windows. En Linux, rpmfind y PBone le ayudarán a encontrar un RPM.


Su primera página con PHP

Comienze por crear un archivo llamado hola.php y colocarle en el "directorio raíz" (DOCUMENT_ROOT) con el siguiente contenido:

Ejemplo 2-1. Nuestro primer script PHP: hola.php

<html>
 <head>
  <title>Ejemplo de PHP</title>
 </head>
 <body>
 <?php echo "<p>Hola Mundo</p>"; ?>
 </body>
</html>

Utilice su navegador web para acceder al archivo, con la URL terminando en "/hola.php". Si está programando localmente este URL lucirá algo como http://localhost/hola.php o http://127.0.0.1/hola.php pero esto depende de la configuración de su servidor web. Aunque este tema está fuera del alcance de este tutorial, también puede ver las directivas DocumentRoot y ServerName en la configuración de su servidor (en Apache, esto es httpd.conf). Si todo está configurado correctamente, el archivo será analizado por PHP y el siguiente contenido aparecerá en su navegador:

<html>
 <head>
  <title>Ejemplo de PHP</title>
 </head>
 <body>
 <p>Hola Mundo</p>
 </body>
</html>

Note que esto no es como los scripts de CGI. El archivo no necesita ninguna clase especial de permisos para ser ejecutado. Piense en ellos como si fueran archivos HTML con un conjunto muy especial de etiquetas disponibles, y que hacen muchas cosas interesantes.

Este programa es extremadamente simple, y no necesita usar PHP para crear una página como ésta. Todo lo que hace es mostrar: Hola Mundo usando la sentencia echo().

Si ha intentado usar este ejemplo, y no produjo ningún resultado, preguntando si deseaba descargar el archivo, o mostró todo el archivo como texto, lo más seguro es que PHP no se encuentra habilitado en su servidor. Pídale a su administrador que active esta función por usted, o use el capítulo titulado Instalación en el manual. Si está trabajando localmente, lea también el capítulo dedicado a la instalación, y asegúrese de que todo esté configurado apropiadamente. Si el problema continúa, por favor use una de las muchas opciones para obtener ayuda con PHP.

El objetivo de este ejemplo es demostrar cómo puede usar las etiquetas PHP. En este ejemplo usamos <?php para indicar el inicio de la etiqueta PHP. Después indicamos la sentencia y abandonamos el modo PHP usando ?>. Puede salir de PHP y regresar cuantas veces lo desee usando este método. Para más información, puede leer la sección en el manual titulada Sintaxis básica de PHP.

Una nota acerca de editores de texto: Hay muchos editores de texto y Entornos Integrados de Desarrollo (IDE por sus siglas en Inglés) que puede usar para crear, editar, y organizar archivos PHP. Puede encontrar una lista parcial de éstos en Lista de editores de PHP. Si desea recomendar un editor, por favor visite la página mencionada anteriormente, y comunique su recomendación a las personas encargadas del mantenimiento para que lo incluyan en la lista. Contar con un editor que resalte la sintaxis de PHP puede ser de mucha ayuda.

Una nota acerca de los procesadores de palabras: Los procesadores de palabras como "StarOffice", "Microsoft word" y "Abiword" no son buenas opciones para editar archivos de PHP. Si desea usar uno de éstos programas para probar sus scripts, primero debe asegurarse de guardar el documento en formato de "Texto" puro, o PHP no será capaz de ejecutar el script.

Una nota acerca del "Bloc de Notas de Windows": Si desea escribir sus archivos PHP usando el "Bloc de Notas de Windows" o en algún otro editor de texto para Windows necesita asegurarse de que sus archivos sean guardados con la extensión .php (la mayoría de editores de texto en Windows automáticamente tratarán de añadir la extensión .txt a los archivos a menos que tome los siguientes pasos para prevenirlo). Cuando guarde sus archivos y el programa le pregunte qué nombre le desea dar al archivo, use comillas para indicar el nombre (es decir, "hola.php"). Una alternativa es, en la lista de opciones "Archivos de Texto *.txt", seleccionar la opción "Todos los archivos *.*". Aquí puede escribir el nombre del archivo sin las comillas.

Ahora que ha creado un pequeño script de PHP que funciona correctamente, es hora de trabajar con el script de PHP más famoso; vamos a hacer una llamada a la función phpinfo() para obtener información acerca de su sistema y configuración como las variables predefinidas disponibles, los módulos utilizados por PHP, y las diferentes opciones de configuración. Tomemos unos segundos para revisar esta información.


Algo útil

Hagamos ahora algo que puede ser más útil. Vamos a chequear qué clase de navegador web utiliza. Para hacerlo, vamos a consultar la información que el navegador nos envía como parte de su petición HTTP. Esta información es guardada en una variable. Las variables siempre comienzan con un signo de dólar ("$") en PHP. La variable que vamos a utilizar en esta situación es $_SERVER["HTTP_USER_AGENT"].

Nota: $_SERVER es una variable reservada por PHP que contiene toda la información del servidor web. Es conocida como Autoglobal (o Superglobal). Consulte el manual en su sección titulada Autoglobales para mas información. Éstas son variables especiales que fueron introducidas en la versión 4.1.0 de PHP. Antes podíamos usar las matrices $HTTP_*_VARS, tales como $HTTP_SERVER_VARS. Aunque éstas han sido marcadas como obsoletas, tales matrices todavía existen. (También puede echar un vistazo a las notas relacionadas con el código antiguo.)

Para poder ver esta variable solo necesita:

Ejemplo 2-2. Impresión de una variable (elemento de la matriz)

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

Un ejemplo de los resultados de este programa sería:

Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)

Hay muchos tipos de variables en PHP. En el ejemplo anterior imprimimos una matriz. Las matrices pueden ser muy útiles.

$_SERVER es simplemente una variable que se encuentra disponible automáticamente para usted en PHP. Puede encontrar una lista en la sección titulada Variables Reservadas del manual, o puede generar una lista completa creando un archivo como el presentado a continuación:

Ejemplo 2-3. Consultar todas las variables predefinidas con phpinfo()

<?php phpinfo(); ?>

Si abre este archivo con su navegador, puede ver una página con información acerca de PHP, junto a una lista de todas las variables que puede usar.

Puede usar más de un declaración PHP dentro de una etiqueta PHP, y crear pequeños segmentos de código que pueden hacer más que un "echo". Por ejemplo, si quisiéramos detectar el uso de "Internet Explorer", haríamos algo así:

Ejemplo 2-4. Ejemplos de uso de estructuras de control y funciones

<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
	echo "Est&aacute; usando Internet Explorer<br />";
}
?>

Un ejemplo de los resultado del script puede ser:

Est&aacute; usando Internet Explorer<br />

A continuación introduciremos un par de conceptos nuevos. Tenemos una declaración "if". Si está familiarizado con la sintaxis básica del lenguaje "C", esto se vera lógico, Pero si no entiende "C", u otros lenguajes de programación donde encuentra la sintaxis usada anteriormente, probablemente debería conseguir un libro que le introduzca mejor a PHP, y lea los primeros capítulos, o también puede ver la parte del manual titulada Referencia del lenguaje. Puedes encontrar una lista de libros sobre PHP en http://www.php.net/books.php.

El segundo concepto que introducimos fue la función llamada strstr(). strstr() es una función integrada de PHP que busca un cadena dentro de otra cadena más larga. En el caso anterior estamos buscando "MSIE" dentro de $_SERVER["HTTP_USER_AGENT"]. Si la cadena fue encontrada, la función devolverá verdadero ("TRUE"), la declaración "if" se evalúa a verdadero ("TRUE") y el código adentro de las llaves {} es ejecutado. De otra manera no resulta ejecutado. Tómese la libertad de crear ejemplos similares usando "if", "else" ("de otra manera"), y otras funciones como strtoupper() y strlen(). Cada página del manual contiene ejemplos que puede usar. Si no está seguro sobre el modo de uso éstas funciones, es recomendable que lea las páginas del manual tituladas Cómo leer una definición de función y la sección relacionada a Funciones en PHP

Podemos continuar y demostrar cómo puede saltar adentro y afuera del modo PHP en el medio de un bloque de código.

Ejemplo 2-5. Mezcla de los modos HTML y PHP

<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
?>
<h3>strstr debe haber devuelto verdadero</h3>
<center><b>Est&aacute; usando Internet Explorer</b></center>
<?php
} else {
?>
<h3>strstr debi&oacute; devolver falso</h3>
<center><b>No est&aacute; usando Internet Explorer</b></center>
<?php
}
?>

Un ejemplo de los resultados de este script puede ser:

<h3>strstr debe haber devuelto verdadero </h3>
<center><b>Est&aacute; usando Internet Explorer</b></center>

En vez de usar una sentencia PHP "echo" para demostrar algo, saltamos fuera del código PHP y escribimos HTML puro. Este es un punto muy importante y potente que debemos observar aquí, y es que la fluidez lógica del script está intacta. Sólamente las partes donde hay HTML serán enviadas a su navegador dependiendo de los resultados que strstr() devuelve (si fue verdadero [TRUE], o falso [FALSE]). En otras palabras, si la cadena MSIE fue encontrada o no.


Uso de Formularios HTML

Otra de las características de PHP es que gestiona formularios de HTML. El concepto básico que es importante entender es que cualquier elemento de los formularios estará disponible automáticamente en su código PHP. Por favor refiérase a la sección titulada Variables fuera de PHP en el manual para más información y ejemplos sobre cómo usar formularios HTML con PHP. Observemos un ejemplo:

Ejemplo 2-6. Un formulario HTML sencillo

<form action="accion.php" method="POST">
 Su nombre: <input type="text" name="nombre" />
 Su edad: <input type="text" name="edad" />
 <input type="submit">
</form>

No hay nada especial en este formularo, es HTML limpio sin ninguna clase de etiquetas desconocidas. Cuando el cliente llena éste formulario y oprime el botón etiquetado "Submit", una página titulada accion.php es llamada. En este archivo encontrará algo así:

Ejemplo 2-7. Procesamiento de información de nuestro formulario HTML

Hola <?php echo $_POST["nombre"]; ?>.
Tiene <?php echo $_POST["edad"]; ?> a&ntilde;os

Un ejemplo del resultado de este script podría ser:

Hola José.
Tiene 22 años

Es aparentemente obvio lo que hace. No hay mucho más que decir al respecto. Las variables $_POST["nombre"] y $_POST["edad"] son definidas automáticamente por PHP. Hace un momento usamos la variable autoglobal $_SERVER, ahora hemos introducido autoglobal $_POST, que contiene toda la información enviada por el método POST. Fíjese en el atributo method en nuestro formulario; es POST. Si hubiéramos usado GET, entonces nuestra información estaría en la variable autoglobal $_GET. También puede utilizar la autoglobal $_REQUEST si no le importa el origen de la petición. Ésta variable contiene una mezcla de información GET, POST y COOKIE. También puede ver la función import_request_variables().


Use de código antiguo con nuevas versiones de PHP

Ahora que PHP ha crecido y se ha convertido en un lenguaje popular, hay muchos más recursos que contienen código que puede reusar en sus propios programas. Por lo general, las personas que se encargan del desarrollo de PHP tratan de que el lenguaje sea compatible con versiones anteriores, para que los programas escritos con versiones antiguas continúen funcionando cuando instale una nueva versión de PHP. En un mundo perfecto, nunca necesitaría modificar su código para hacerlo funcionar con versiones nuevas del lenguaje; pero, como todos sabemos, este no es un mundo perfecto, y usualmente son necesarios los cambios en su código.

Dos de los cambios mas importantes que afectan el código viejo son:

  • La desaparición de las matrices $HTTP_*_VARS (que usualmente son usadas como globales al interior de una función o método). Las siguientes matrices autoglobales fueron introducidas en la versión 4.1.0 de PHP. Estas son: $_GET, $_POST, $_COOKIE, $_SERVER, $_FILES, $_ENV, $_REQUEST, y $_SESSION. Las antiguas $HTTP_*_VARS, como $HTTP_POST_VARS, todavía existen, y han existido desde PHP 3.

  • Las variables externas que ya no son registradas automáticamente. En otras palabras, a partir de PHP 4.2.0, la directiva PHP register_globals está deshabilitada (su valor es off) en php.ini. El método preferido para obtener acceso a éstos valores es por medio de las "matrices autoglobales" mencionados anteriormente. Los scripts, libros y tutoriales antiguos pueden asumir que ésta directiva es definida automáticamente como "on". Si es así, puede usar, por ejemplo, $id desde la URL http://www.example.com/foo.php?id=42. Por otra parte, no importa si el valor de la directiva es "on" u "off", $_GET['id'] está siempre disponible.

Para más detalles relacionados con estos cambios, puede ver la sección sobre variables predefinidas.


¿Y ahora qué?

Con lo que hemos visto, puede entender la mayor parte del manual, y también los ejemplos que están disponibles en los archivos. También puede encontrar otros ejemplos en los diferentes sitios de php.net en la sección de enlaces: http://www.php.net/links.php.

Para ver una presentación que muestra más acerca de lo que puede hacer PHP, visite los diferentes sitios con material relacionado a las conferencias realizadas: http://conf.php.net/ y http://talks.php.net/.


Capítulo 3. Instalación


Consideraciones generales de instalación

Antes de instalar PHP, necesitais saber porque quereis utilizarlo. Existen tres campos principales en donde PHP es usado, tal y como se describe en la sección Qué se puede hacer con PHP?:

  • Scripts en la parte del servidor

  • Scripts en linea de comandos

  • Aplicaciones gráficas clientes

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. Dependiendo de la versión de sistema operativo que utiliceis, probablemente tengais un servidor web (p.ej: Apache en Linux ó IIS en Windows). Tambien se puede alquilar espacio web en una empresa que ofrezca este servicio. De esta manera no se necesita instalar nada, solamente escribir los scripts PHP, subirlos al espacio alquilado y ver el resultado en vuestro navegador.

Teneis dos maneras de utilizar PHP, si instalais vosotros el servidor y PHP. Existen modulos directos (también llamados SAPI) para muchos servidores web, como Apache, Microsoft Internet Information Server, Netscape e iPlanet. Muchos otros servidores soportan ISAPI, (p.ej.:OmniHTTPd). Si PHP no soporta un módulo para tu servidor web, siempre se puede usar como binario CGI. Esto significa que el servidor se configura para usar el ejecutable para linea de comandos de PHP php.exe en Windows) en el procesado de peticiones de ficheros PHP.

Si estais interesados en usar PHP desde la linea de comandos (p.ej.: para generar imagenes offline ó precesar ficheros de textos, etc) necesitais el ejecutable para linea de comandos. Para más información, lea la sección Usando PHP desde la línea de comandos. en este caso no se necesita ni servidor web, ni navegador.

Con PHP tambien se puede escribir aplicaciones gráficas usando la extensión PHP-GTK. Esta es una forma totalmente distinta de utilizar PHP que cuando se utiliza para escribir páginas web, ya que no se genera código HTML sino que se trabaja con ventanas y objetos dentro de las mismas. Para más información sobre PHP-GTK, visitar las páginas dedicadas a esta extensión. PHP-GTK no se incluye en la distribución oficial de PHP.

A partir de ahora, esta sección tratará sobre la configuración de PHP con servidores web, en Unix y Windows, tanto como módulo, como binario CGI.

PHP, el código fuente y distribuciones binarias para Windows se pueden encontrar en http://www.php.net/. Recomendamos utilizar un servidor espejo cerca de donde esteis para bajaros la versión de PHP que querais.


Instalación en Unix/HP-UX

Esta sección contiene notas y ayudas específicas para instalar PHP en sistemas HP-UX.

Nota: Notas para PHP 4.0.4 y Apache v1.3.9

  1. Necesitais gzip, podeis bajar una distribución binaria de http://hpux.connect.org.uk/ftp/hpux/Gnu/gzip-1.2.4a/gzip-1.2.4a-sd-10.20.depot.Z descomprimir el fichero e instalar usando swinstall.

  2. Necesitais gcc, podeis bajar una distribución binaria de http://gatekeep.cs.utah.edu/ftp/hpux/Gnu/gcc-2.95.2/gcc-2.95.2-sd-10.20.depot.gz descomprimir el fichero e instalar usando swinstall.

  3. Necesitais GNU binutils, podeis bajar una distribución binaria de http://hpux.connect.org.uk/ftp/hpux/Gnu/binutils-2.9.1/binutils-2.9.1-sd-10.20.depot.gz descomprimir el fichero e instalar usando swinstall.

  4. Necesitais bison, podeis bajar una distribución binaria de http://hpux.connect.org.uk/ftp/hpux/Gnu/bison-1.28/bison-1.28-sd-10.20.depot.gz descomprimir el fichero e instalar usando swinstall.

  5. Necesitais flex, podeis bajar el código fuente de uno de los servidores espejo de http://www.gnu.org. Se encuentra en el directorio non-gnu en el servidor ftp. Bajar el fichero y ejecutar tar -xvf en el mismo. Entrar en el nuevo directorio flex creado y ejecutar ./configure, make, y por ultimo make install.

    Si teneis errores, es probablemente porque gcc, etc no se encuentra en vuestro PATH, actualizar la variable PATH para corregir esto.

  6. Bajar el codigo fuente de PHP y Apache

  7. Ejecutar gunzip y tar -xvf en ellos. Necesitamos cambiar una par de ficheros para que compilen sin problemas.

  8. Para empezar el fichero de configuracion necesita cambiarse porque parece que olvida que estamos en una maquina hpux. Existe otra manera de hacer esto, pero una manera rapida y faciel es introducir la linea lt_target=hpux10.20 em la linea 47286 del script de configuración.

  9. Tambien tenemos que cambiar el fichero de apache GuessOS. En el fichero apache_1.3.9/src/helpers cambiar la linea 89 de echo "hp${HPUXMACH}-hpux${HPUXVER}"; exit 0 a echo "hp${HPUXMACH}-hp-hpux${HPUXVER}"; exit 0

  10. No se puede instalar PHP como modulo compartido en HP-UX, se debe compilar estaticamente, seguir las instrucciones en la documentación de Apache.

  11. PHP y apache deberian de haber compilado sin problemas, pero Apache no arrancara. Necesitamos crear un nuevo usuario para ejecutar Apache, p.ej: www o apache. Cambiar la linea 252 y 253 en el fichero de configuracion de Apache conf/httpd.conf, para en vez de:

    User nobody 
    Group nogroup

    tener

    User www 
    Group sys

    Esto hay que hacerlo porque Apache no puede ejecutarse como nobody en hp-ux. Apache y PHP deberian de funcionar ahora.


Instalación en Unix/Linux

Esta sección contiene información específica sobre la instalación de PHP en sistemas Linux.


Usando paquetes

Muchas distribuciones de Linux tienen algún tipo de sistema de instalación por medio de paquetes, por ejemplo el llamado RPM. Esto puede ayudar a instalar una configuración estandar, pero si quereis tener caracteristicas especiales (como servidor seguro, ó soporte para otra base de datos, etc) seguramente tendreis que compilar PHP y/ó vuestro servidor web. Si no estais familiarizados con la compilación de vuestro propio software, podeis intentar comprobar si existe algún paquete precompilado con las caracteristicas que necesitais.


Instalación en Unix/Mac OS X

Esta sección contiene informacion específica de como instalar PHP en Mac OS X Server.


Usando paquetes

Existen unos cuantos paquetes precompilados de PHP para Mac OS X. Esto puede ayudar a instalar una configuración estandar, pero si necesitais utilizar caracteristicas diferentes a las compiladas (p.ej.: servidor seguro, ó un controlador de bases de datos diferentes) tendreis que compilar PHP y vuestro servidor web ustedes mismos. Si no estais familiarizados con la compilación de vuestro propio software, no está de más comprobar si alguien ya ha creado un paquete con las caracteristicas que necesitais.


Compilando en OS X server

Existen dos versiones diferentes de Mac OS X, clente y servidor. A continuación teneis información para la versión servidor.

Ejemplo 3-1. Instalación en Mac OS X server

1. Bajarse las ultimas distribuciones de Apache y PHP.
2. Desempaquetarlas y ejecutar el programa configure en el directorio
    de apache:
    ./configure --exec-prefix=/usr \ 
    --localstatedir=/var \ 
    --mandir=/usr/share/man \ 
    --libexecdir=/System/Library/Apache/Modules \ 
    --iconsdir=/System/Library/Apache/Icons \ 
    --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ 
    --enable-shared=max \ 
    --enable-module=most \ 
    --target=apache 

4. Podeis agregar esta linea:
    setenv OPTIM=-O2 
   si quereis que el compilador optimize el c&oacute;digo.
    
5. Ir al directorio de PHP y configurarlo con: 
    ./configure --prefix=/usr \ 
    --sysconfdir=/etc \ 
    --localstatedir=/var \ 
    --mandir=/usr/share/man \ 
    --with-xml \ 
    --with-apache=/src/apache_1.3.12 

    Si teneis otras caracteristicas que querais a&ntilde;adir (MySQL,
    GD, etc.), asegurarse de a&ntilse;adirlas aqu&iacute;. En  --with-apache=
    teneis que poner el PATH de vuestro directorio Apache con el
    c&oacute;digo fuente del mismo, p.ej.: "/src/apache_1.3.12".

6. make
7. make install    
   Esto a&ntilde;adir&aacute; un directorio en vuestro directorio Apache con el
   c&oacute;digo fuente del mismo, bajo src/modules/php4.
    
8. Reconfigurar Apache para utilizar PHP4:
    ./configure --exec-prefix=/usr \ 
    --localstatedir=/var \ 
    --mandir=/usr/share/man \ 
    --libexecdir=/System/Library/Apache/Modules \ 
    --iconsdir=/System/Library/Apache/Icons \ 
    --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ 
    --enable-shared=max \ 
    --enable-module=most \ 
    --target=apache \ 
    --activate-module=src/modules/php4/libphp4.a 

    Podeis obtener un mensaje diciendo que libmodphp4.a no est&aacute;
    actualzido. Si esto ocurre, ir al directorio src/modules/php4 y
    ejecutar este comando:

    ranlib libmodphp4.a 

    Una vez ejecutado este comando, volver el directorio raiz de apache y ejecutar
    el comando de configuraci&oacute;n antes mencionado.

9. make

10. make install

11. Copiar y renombrar el fichero php.ini-dist de vuestro directorio
    con las fuentes de PHP al directorio "bin":

    cp php.ini-dist /usr/local/bin/php.ini 

    &oacute; (si no tenesi un directorio local/) 

    cp php.ini-dist /usr/bin/php.ini

Compilando en MacOS X client

Estos datos han sido proporcionados por Marc Liyanage.

El módulo de PHP para Apache incluido en Mac OS X incluye soporte para bases de datos MySQL y PostgreSQL.

NOTA: Tener cuidado cuando hagais esto, podeis estropear vuestro servidor Apache.

Hacer esto para instalar:

  • 1. Abrir una ventana terminal.

  • 2. Escribir "wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz", esperar a que termine

  • 3. Escribir "gunzip libphp4.so.gz"

  • 4. Escribir "sudo apxs -i -a -n php4 libphp4.so"

Ahora escribir "sudo open -a TextEdit /etc/httpd/httpd.conf" TextEdit se abrirá con el fichero de configuración de Apache. Localizar estas dos lineas al final del fichero (podeis utilizar el comando find)
#AddType application/x-httpd-php .php 
   #AddType application/x-httpd-php-source .phps
Borrar los dos caracteres (#), grabar y salir de TextEdit.

Finalmente escribir "sudo apachectl graceful" para rearrancar el servidor web.

PHP deberia de funcionar ahora. Podeis comprobar que funciona, grabando un fichero llamado "test.php" en vuestro directorio web. Escribir esta linea en este fichero: "<?php phpinfo() ?>".

Ahora abrir la dirección 127.0.0.1/~your_username/test.php en vuestro navegador. Deberiais de ver una tabla con información sobre el módulo PHP.


Instalación en Unix/OpenBSD

Esta sección contiene información específica sobre la instalación de PHP en OpenBSD 3.2.


Usando paquetes binarios

El uso de paquetes binarios para instalar PHP en OpenBSD es el método más simple y el recomendado. El paquete principal ha sido separado de los diferentes módulos y cada uno de ellos se puede instalar y desinstalar independientemente unos de otros. Los ficheros que necesitais se pueden encontrar en vuestro CD de OpenBSD ó en el servidor FTP.

El paquete principal que teneis que instalar es php4-core-4.2.3.tgz, el cual, contiene el motor básico (más gettext y iconv). A continuación podeis instalar los paquetes de módulos, tales como php4-mysql-4.2.3.tgz ó php4-imap-4.2.3.tgz. Debeis de usar el comando phpxs para activar y desactivar estos módulos en vuestro fichero php.ini.

Ejemplo 3-2. Ejemplo de instalación de los paquetes en OpenBSD

# pkg_add php4-core-4.2.3.tgz
# /usr/local/sbin/phpxs -s
# cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini
  (add in mysql)
# pkg_add php4-mysql-4.2.3.tgz
# /usr/local/sbin/phpxs -a mysql
  (add in imap)
# pkg_add php4-imap-4.2.3.tgz
# /usr/local/sbin/phpxs -a imap
  (remove mysql as a test)
# pkg_delete php4-mysql-4.2.3
# /usr/local/sbin/phpxs -r mysql
  (install the PEAR libraries)
# pkg_add php4-pear-4.2.3.tgz

Consultar las páginas del manual packages(7) para más información sobre paquetes binarios en OpenBSD.


Usando Ports

Tambien podeis compilar PHP vosotros mismos usando el árbol de "ports". De todas maneras, esto se recomienda solamente a usuarios que esten familiarizados con OpenBSD. El "port" de PHP4 se encuentra dividido en tres subdirectorios, core, extensions y pear. El subdirectorio de extensiones genera los sub-paquetes para todos los módulos de PHP soportados. Si no quereis crear algunos de estos módulos usar el comando no_* FLAVOR. Por ejemplo, para no crear el módulo imap, configurar FLAVOR con no_imap.


Versiones antiguas

Versiones antiguas de OpenBSD usaban FLAVORS para compilar y enlazar estáticamente PHP. Ya que es difícil generar paquetes binarios utilizando este método, no se soporta más. Podeis utilizar todavia los "ports" antiguos estables, si quereis, pero debeis de saber que no se soportan más por el equipo de OpenBSD. Si teneis algún comentario sobre esto, podeis contactar con el mantenedor actual del "port" Anil Madhavapeddy.


Instalación en Unix/Solaris

Esta sección contiene información específica sobre la instalación de PHP en sistemas Solaris.


Software requerido

Solaris suele instalar compiladores de C carentes de caracteristicas y sus herramientas. Esta es la lista de software es necesario:

  • gcc (recomendado, otros compiladores de C puede que funcionen)

  • make

  • flex

  • bison

  • m4

  • autoconf

  • automake

  • perl

  • gzip

  • tar

  • GNU sed

Ademas, debeis de instalar (y posiblemente compilar) todo software adicional necesario por vuestra configuración, tal como Oracle ó MySQL.


Usando paquetes

El proceso de instalación en Solaris se puede simplificar con el uso de pkgadd para instalar los componentes que necesiteis.


Instalación en sistemas Unix

Esta sección os guiará en el proceso de configuración e instalación de PHP de manera general en sistemas Unix. Consultar la sección específica de vuestra plataforma ó servidor web.

Conocimientos y software necesarios:

  • Conocimientos básicos de Unix (ser capaz de usar "make" y un compilador de C, si vais a compilar).

  • Un compilador ANSI C (si vais a compilar).

  • flex (si vais a compilar).

  • bison (si vais a compilar).

  • Un servidor web

  • Cualquier componente necesario por los modulos (p.ej: gd, pdf libs, etc.)

Existen diferentes maneras de instalar PHP en la plataforma Unix, bien por el método de compilar y configurar manualmente ó por medio de una serie de paquetes listos para instalar. Esta documentación se centra en el método de compilación y configuración manual.

El proceso inicial de configuración de PHP está controlado por las opciones en linea de comandos del script configure. Esta página muestra el uso de algunas de ellas, pero existen otras muchas. Consultar la lista completa de opciones con configure. Existen diferentes maneras de instalar PHP:


Referencia rápida como módulo de Apache

PHP se puede compilar de numerosas maneras, pero una de las más populares es como módulo de Apache. A continuación teneis una descripción de la instalación rápida

Ejemplo 3-3. Instrucciones para una instalación rápida de PHP 4 (Como módulo de Apache)

1.  gunzip apache_1.3.x.tar.gz
2.  tar xvf apache_1.3.x.tar
3.  gunzip php-x.x.x.tar.gz
4.  tar xvf php-x.x.x.tar
5.  cd apache_1.3.x
6.  ./configure --prefix=/www
7.  cd ../php-x.x.x
8.  ./configure --with-mysql --with-apache=../apache_1.3.x --enable-ftp
9.  make
10. make install
11. cd ../apache_1.3.x
12. ./configure --activate-module=src/modules/php4/libphp4.a
13. make
14. make install
15. cd ../php-x.x.x
16. cp php.ini-dist /usr/local/lib/php.ini
17. Editar vuestro fichero httpd.conf &oacute; srm.conf file y a&ntilde;adir: 
      AddType application/x-httpd-php .php

18. Rearrancar vuestro servidor Apache de la manera habitual (Debeis
    de parar y arrancar el servidor, no vale usar una se&ntilde;al HUP o USR1)

Crear

Cuando PHP esté configurado, se puede crear el binario CGI. El comando make se encarga de esto. si esto falla y no sabeis como solucionarlo, pasaros por la sección sobre problemas.


Instalación en sistemas Windows

Esta sección aplica para Windows 98/Me/NT/2000/XP. PHP no trabajará con plataformas de 16 bit, tales como Windows 3.1 y algunas veces nos referiremos a las plataformas soportadas como Win32. Windows 95 no es soportado desde la versión de PHP 4.3.0.

Hay principalmente dos formas de instalar PHP para Windows: ya sea manualmente o usando el instalador InstallShield.

Si usted tiene MicroSoft Visual Studio, también puede compilar PHP del código fuente original.

Una vez que ha instalado PHP en su sistema Windows, tal vez quiera instalar varias extensiones para agregar funcionalidad.


Windows InstallShield

El instalador de PHP en Windows está disponible de la página de descargas en http://www.php.net/downloads.php. Este instala la versión CGI de PHP, y para ISS, PWS y Xitami configura el servidor web también.

Nota: Mientras el instalador InstallShield es una forma sencilla de hacer trabajar PHP, está restringido en muchos aspectos, como por ejemplo la configuración automática de extensiones no está soportada. Todo el conjunto de extensiones soportadas está solo disponible descargando la distribución binaria zip.

Primero que nada instale el servidor HTTP de su elección en su equipo y asegurese de que funciona.

Ejecute el instalador y siga las instrucciones dadas por el instalador. Son soportadas dos tipos de instalación - estándar, la cuál provee los valores por defecto sensibles a los ajustes "settings", y avanzada, la cuál va preguntando segun avanza la configuración.

El "wizard" obtiene suficiente información para configurar el archivo php.ini y configura el servidor web para usar PHP. Para IIS y también para PWS en estaciones de trabajo NT, se despliega un listado de todos los nodos en el servidor que pueden utilizar "scripts", de tal forma que puede seleccionar de entre esos nodos cuál desea agregarle los mapeos de los "scripts" PHP.

Una vez que se ha completado la instalación, el instalador le informará si necesita reiniciar el sistema, reiniciar el servidor web o solo comenzar a utilizar PHP.

Aviso

Tenga en cuenta que esta configuración de PHP no es segura. Si desea tener una configuración de PHP segura, es mejor que instale de forma manual, y cambiar cada opción cuidadosamente. Esta manera de configuración automática da una instalación de PHP lista para usarse instantáneamente, pero no significa que puede ser usada en servidores web que vayan a estar en línea en Internet.


Pasos de instalación manual

Esta guia de instalación le ayudará a manualmente isntalar y configurar PHP en su servidor web en Windows. La versión original de esta guia fue proveida por Bob Silva, y puede ser encontrada en http://www.umesd.k12.or.us/php/win32install.html. Usted necesita descargar la distribución binaria zip de la página de descargas en http://www.php.net/downloads.php.

PHP 4 para Windows vienen en tres presentaciones - un ejecutable CGI, un ejecutable CLI (sapi/php.exe) y algunos otros modulos SAPI:

php4apache.dll - modulo Apache 1.3.x
php4apache2.dll - modulo Apache 2.0.x
php4isapi.dll - Modulo ISAPI para servidores web que cumplen con ISAPI como IIS 4.0/PWS 4.0 o recientes.
php4nsapi.dll - modulo Netscape/iPlanet

El último modulo es nuevo en PHP4, y provee un incremento en desempeño significativo y alguna nueva funcionalidad. La versión CLI está designada para "scripting" en línea de comandos. Para más información acerca de CLI está disponible en el capítulo acerca de usar PHP desde la línea de comandos

Aviso

Los modulos SAPI han sido mejorados significativamente en la entrega 4.1, sin embargo, puede que encuentre algunos errores del servidor u otros modulos del servidor tales como falla de ASP, en sistemas más viejos.

requerimientos DCOM y MDAC: Si usted escoge uno de los modulos SAPI y usa Windows 95, asegurese de descargar e instalar la actualización de DCOM de las Páginas DCOM de Microsoft. si usa Microsoft Windows 9x/NT4 descargue la última versión de los Componentes de Acceso de Datos Microsoft (MDAC por sus siglas en inglés) para su plataforma. MDAC está disponible en http://msdn.microsoft.com/data/.

Los siguientes pasos deben ser realizados en todas las instalaciones antes de instrucciones específicas de cualquier servidor.

  • Extraiga el archivo de distribución en el directorio que haya escogido, es un buen comienzo c:\. El paquete zip se extrae en una carpeta como php-4.3.1-Win32 la cuál se asume que se renombrará a php. Por razones de conveniencia y para trabajar independiente de la versión los siguientes pasos asumen que la versión de PHP vive en c:\php. Puede escoger cualquier otra ubicaión, pero probablemente no deba usar una ruta que incluya espacios (por ejemplo: C:\Program Files\PHP no es una buena idea). Algunos servidores pueden fallar si lo usa de esta manera. La estructira del directorio donde extrajo el archivo zip se parecerá a:

c:\php
   |
   +--cli
   |  |
   |  |-php.exe           -- ejecutable CLI  - SOLO para linea de comandos
   |
   |
   +--dlls                -- soporte dll para extensiones --> Windows system directory
   |  |
   |  |-expat.dll
   |  |
   |  |-fdftk.dll
   |  |
   |  |-...
   |
   +--extensions          -- dlls de extension para PHP
   |  |
   |  |-php_bz2.dll
   |  |
   |  |-php_cpdf.dll
   |  |
   |  |-..
   |
   +--mibs                -- archivos de soporte para SNMP
   |
   |
   +--openssl             -- archivos de soporte para Openssl
   |
   |
   +--pdf-related         -- archivos de soporte para PDF
   |
   |
   +--sapi                -- SAPI dlls
   |  |
   |  |-php4apache.dll
   |  |
   |  |-php4apache2.dll
   |  |
   |  |-php4isapi.dll
   |  |
   |  |-..
   |
   |-install.txt
   |
   |-..
   |
   |-php.exe              -- ejecutable CGI
   |
   |-..
   |
   |-php.ini-dist
   |
   |-php.ini-recommended
   | 
   |-php4ts.dll           -- dll principal --> Windows system directory
   | 
   |-...

El binario CGI - c:\php\php.exe -, el binario CLI - c:\php\cli\php.exe - y los modulos SAPI - c:\php\sapi\*.dll - dependen del dll principal c:\php\php4ts.dll. Usted debe asegurarse, que este dll puede ser encontrado por su instalación PHP. El orden de la búsqueda para este dll es como sigue:

El mismo directorio en donde se llama a php.exe. En caso que use un modulo SAPI, el mismo directorio de donde su servidor web carga el dll (ej. php4apache.dll).
Cualquier directorio en su variable de ambiente PATH de Windows.

  • Lo mejor es apostar por asegurarse de hacer disponible php4ts.dll, sin importar que interface planee usar (CGI o modulo SAPI). Para esto, debe copiar este dll en un directorio de su PATH en Windows. El mejor lugar es el directorio de sistema de Windows:

    C:\Windows\System para Windows 9x/ME
    C:\WINNT\System32 para Windows NT/2000 o C:\WINNT40\System32 para NT/2000 server
    C:\Windows\System32 para Windows XP

    Si planea usar un modulo SAPI de c:\php\sapi y no quiere copiar archivos dll a su directorio de sistema Windows, tiene la opción alternativa de simplemente copiar php4ts.dll a la carpeta sapi de su paquete zip extraído, c:\php\sapi.

  • El siguiente paso es fijar un archivo configuración valido para PHP, php.ini hay dos archivos .ini distribuidos en el archivo zip, php.ini-dist y php.ini-recommended. Le aconsejamos que use php.ini-recommended, porque optimizamos por defecto los ajustes de rendimiento y seguridad. Lea cuidadosamente este documento y ademas estudie los ajustes iniciales y fije cada elemento manualmente. Si quiere alcanzar la mejor seguridad, entonces este es el camino para usted, aunque PHP trabaja bien con estos archivos ini. Copie el archivo ini de su elección al directorio donde PHP lo encuentre y renombrelo a php.ini. Por defecto PHP busca php.ini en su directorio de Windows:

    En Windows 9x/Me/XP copie el archivo ini a su %WINDIR%, el cuál es típicamente C:\Windows.
    En Windows NT/2000 copie el archivo ini a su %WINDIR% o %SYSTEMROOT%, los cuales son típicamente C:\WINNT o C:\WINNT40 para servidores NT/2000.

  • Si está usando NTFS en Windows NT, 2000 o XP, asegurese de que el usuario que corre el servidor web tiene permisos de lectura sobre php.ini (ej. hagalo leíble para todos).

Los siguientes pasos son opcionales.

  • Edite su archivo nuevo php.ini. Si planea usar OmniHTTPd, no siga el siguiente paso. Fije el doc_root para que apunte al document_root de sus servidores web. Por ejemplo:

    doc_root = c:\inetpub        // para IIS/PWS
    
    doc_root = c:\apache\htdocs // para Apache

  • escoja cuales extensiones quiere cargar cuando inicia PHP. Vea la sección acerca extensiones de Windows, sobre como fijar una, y saber que está ya integrado. Note que en una nueva instalación es recomendable primero tener PHP trabajando y probado sin extensiones antes de habilitarlas en php.ini

  • En PWS y IIS, puede fijar las opciones de configuración browscap para que apunten a: c:\windows\system\inetsrv\browscap.ini en Windows 9x/Me, c:\winnt\system32\inetsrv\browscap.ini en NT/2000 y c:\windows\system32\inetsrv\browscap.ini en XP.

Estas son las instrucciones básicas para que usted pueda fácilmente configurar PHP en Windows. El siguiente paso es escoger un servidor web y habilitarle que ejecute PHP. Estan disponibles las instrucciones de instalación para los siguientes servidores web:


Compilar los fuentes

Antes de empezar, es necesario responder la pregunta: ¿Por qué es compilar en Windows tan díficil? dos razones tengo en mente:

  1. Windows no (todavía) se una a la gran comunidad de desarrolladores que desean libremente compartir sus fuentes. Como un resultado directo, la inversión necesaria en la infrastructura requerida para soportar tal desarrollo no se ha conseguido. Generalmente, lo que se está disponible ha sido posible por el uso de las necesarias utilidades de Unix. No se sorprenda si algo de esta herencia se muestra de cuando en cuando.

  2. Muchas de las instrucciones que siguen son de la variedad "fije y olvide". Así que sientese e intente seguir las instrucciones siguientes tan fielmente como pueda.


Requerimientos

Para compilar y construir PHP usted necesita un ambiente de desarrollo de Microsoft. se recomienda Microsoft Visual C++ 6.0. Para extraer los archivos descargados necesita una utilería de extracción (ej. winzip). Si todavía no tiene una utilería unzip, puede obtener una versión gratuita de InfoZip.

Antes comenzar, tiene que descargar...

Finalmente, usted va a necesitar los mismos fuentes de PHP 4. Puede obtener la última versión en desarrollo usando CVS anónimo, un snapshot o la entrega más reciente de los fuentes en tarball.


Poniendo todo junto

Después de descargar los paquetes requeridos tiene que extrerlos en un lugar apropiado.

  • Cree un directorio de trabajo donde todos los archivos vayan a dar despues de extraídos, ej. C:\work.

  • Cree el directorio win32build dentro de su directorio de trabajo (C:\work) y descomprima win32build.zip en él.

  • Cree el directorio bindlib_w32 dentro de su directorio de trabajo (C:\work) y descomprima bindlib_w32.zip en él.

  • Extraiga el código fuente PHP descargado en su directorio de trabajo (C:\work).

Siguiendo estos pasos la estructura de si directoria se verá como esto:

+--c:\work
|  |
|  +--bindlib_w32
|  |  |
|  |  +--arpa
|  |  |
|  |  +--conf
|  |  |
|  |  +--...
|  |
|  +--php-4.x.x
|  |  |
|  |  +--build
|  |  |
|  |  +--...
|  |  |
|  |  +--win32
|  |  |
|  |  +--...
|  |
|  +--win32build
|  |  |
|  |  +--bin
|  |  |
|  |  +--include
|  |  |
|  |  +--lib

Cree los directorios c:\usr\local\lib. Copie bison.simple de c:\work\win32build\bin a c:\usr\local\lib.

Nota: los usuarios de Cygwin deben omitir el último paso. Un ambiente Cygwin propiamente instalado provee los archivos mandatorios bison.simple y bison.exe.


Configure MVC ++

El siguiente paso es configurar MVC ++ para prepararnos para compilar. ejecute Microsoft Visual C++, y de el menu selecciones Herramientas (Tools) => Options. En el dialogo, seleccione la pestaña directorios (directories). Secuencialmente cambie el menu desplegable a los archivos de Ejecutables, Incluir, y Librerias. Sus cambios deben lucir como esto:

  • Archivos ejecutables: c:\work\win32build\bin, usuarios de Cygwin : cygwin\bin

  • Archivos incluidos: c:\work\win32build\include

  • Librerias: c:\work\win32build\lib


Compilar resolv.lib

Usted debe compilar la libreria resolv.lib. Decida si quiere tener simbolos de rastreo de errores disponible (bindlib - Win32 Debug) o no (bindlib - Win32 Release). Compile la configuración apropiada:

  • Para usuarios del ambiente gráico, arranquen VC++, y entonces seleccionen Archivo => Abrir área de trabajo, navegue a c:\work\bindlib_w32 y seleccione bindlib.dsw. entonces seleccione Compilar => Fijar Configuración activa y seleccione la configuración deseada. Finalmente seleccione Compilar => Compilar todo.

  • Para usuarios de línea de comandos, asegurense de que tiene las variables de ambiente de C++ registradas, o que ha ejecutado vcvars.bat, y entonces ejecute uno de los siguientes comandos:

    • msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"

    • msdev bindlib.dsp /MAKE "bindlib - Win32 Release"

En este punto, usted debe tener un resolv.lib disponible en cualquiere de sus subdirectorios c:\work\bindlib_w32\Debug o Release. Copie este archivo en su directorio c:\work\win32build\lib sobreescribiendo el archivo del mismo nombre que se encuentra ahi.


Compilando

La mejor manera de empezar es compilar la version CGI.

  • Para usuarios del ambiente gráfico, arranquen VC++, y entonces seleccionen Archivo => Abrir area de trabajo y seleccionen c:\work\php-4.x.x\win32\php4ts.dsw. Entonces seleccionen Compilar=>Fijar configuración activa y seleccione la configuración deseada, ya sea php4ts - Win32 Debug_TS o php4ts - Win32 Release_TS. Finalmente seleccione Compilar=>Compilar todo.

  • Para usuarios de línea de comandos, asegurese de que tiene ya sea las variables de ambiente de C++ registradas, o ejecutó vcvars.bat, y entonces ejecute uno de los siguientes comandos desde el directorio c:\work\php-4.x.x\win32 :

    • msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"

    • msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"

    • En este punto, usted debe tener un php.exe usable, en uno de sus subdirectorios c:\work\php-4.x.x.\Debug_TS o Release_TS.

Es posible hacer arreglos menores para requisitos particulares al proceso de compilación editando el archivo main/config.win32.h. Para un ejemplo puede cambiar la localización por defecto de php.ini, las extensiones integradas y la ubicación por defecto de las extensiones.

En seguida, puede que queires compular la versión CLI la cuál esta designada para usar PHP desde la línea de comandos. Los pasos a seguir son los mismos que para compilar la versión CGI, excepto que tiene que seleccionar php4ts_cli - Win32 Debug_TS o php4ts_cli - Win32 Release_TS como archivo del projecto. Después de una compilación exitosa, usted encontrará el php.exe en el directorio ya sea Release_TS\cli\ o Debug_TS\cli\.

Nota: Si quiere usar PEAR y el instalador confortable de línea de comandos, el CLI-SAPI es mandatorio. Para más información acerca de PEAR y el instalador lea la documentación en el sitio de PEAR.

Para poder compilar el modulo SAPI (php4isapi.dll) para integración de PHP con Microsoft IIS, fije su configuración activa a php4isapi-whatever-config y compile el dll deseado.


Instalacion de las extensiones de Windows

Después de instalar PHP y un servidor web en Windows, usted probablemente quiera instalar algunas extensiones para agregar funcionalidad. Puede escoger cuales extensioes quiere cargar cuando PHP inicia modificando su php.ini. Puede tambien cargar modulos dinámicamente en sus "scripts" usando la función dl().

Los DLLs para las extensiones de PHP tienen el prefijo 'php_' en PHP 4 (y 'php3_' en PHP 3). Esto prevee confusión entre las extensiones de PHP y sus librerias de soporte.

Nota: En PHP 4.3.1 BCMath, Calendar, COM, Ctype, FTP, MySQL, ODBC, Overload, PCRE, Session, Tokenizer, WDDX, XML y Zlib el soporte está integrado. Usted no necesita cargar ninguna extensión adicional para usar esas funciones. Vea en su distribución los archivos README.txt o install.txt o this table para una lista de los modulos integrados.

La ubicación por defecto en la que PHP busca por extensiones es c:\php4\extensions. Para cambiar está opción para reflejar tu configuración de PHP edita tu archivo php.ini:

  • Necesitará cambiar la opción extension_dir para apuntar al directorio donde sus extensiones están, o donde usted haya pueto sus archivos php_*.dll. Por favor no olvide la última diagonal invertida "\". Por ejemplo:

    extension_dir = c:/php/extensions/

  • Habilite las extensiones in php.ini que quiere usar quitando el comentario de las lineas extension=php_*.dll en php.ini. Esto es hecho quitando el (;) al principio de la linea para las extensiones que quiere utilizar.

    Ejemplo 3-4. Habilita extensión Bzip2 para PHP-Windows

    // change the following line from ...
    ;extension=php_bz2.dll
    
    // ... to
    extension=php_bz2.dll

  • Algunas de las extensiones necesitan algunos dlls extras para trabajar correctamente. Algunos de ellos pueden ser encontrados en el paquete que descomprimió en el directorio c:\php\dlls\, pero algunos, por ejemplo Oracle (php_oci8.dll) requieren dlls los cuales no estan disponibles en el paquete de distribución. Copie los dlls incluidos de la carpeta c:\php\dlls a su PATH de Windows, algunos lugares seguros son:

    c:\windows\system for Windows 9x/Me
    c:\winnt\system32 for Windows NT/2000
    c:\windows\system32 for Windows XP

    Si los tiene ya instalados en su sistema, sobreescribalos solo si algo no funciona correctamente (antes de sobreescribirlos, es una buena idea hacer un respaldo de ellos, o moverlos a otra carpeta, solo en caso de que algo salga mal).

Nota: Si está ejecutando una version de modulo de servidor de PHP recuerde reiniciar su servidor web para reflejar los cambios a php.ini.

La siguiente tabla describe algunas de las extensiones disponibles y los dlls extras requeridos.

Tabla 3-1. Extensiones PHP

ExtensionDescripciónNotas
php_bz2.dllfunciones de compresión bzip2Ninguna
php_calendar.dllfunciones de conversion de CalendarioIntegrada desde PHP 4.0.3
php_cpdf.dllfunciones ClibPDFNinguna
php_crack.dllfunciones CrackNinguna
php3_crypt.dllfunciones Cryptno se conocen
php_ctype.dllfamilia de funciones ctypeIntegrada desde PHP 4.3.0
php_curl.dlllibreria de funciones Cliente URL, CURLRequiere: libeay32.dll, ssleay32.dll (ligado)
php_cybercash.dllfunciones de pago eletrónico CybercashPHP <= 4.2.0
php_db.dllfunciones DBMObsoleta. Use DBA en vez de ésta (php_dba.dll)
php_dba.dllDBA: Funciones de abstraction layer DataBase (dbm-style)Ninguna
php_dbase.dllfunciones dBaseNinguna
php3_dbm.dlllibreria Berkeley DB2no se conocen
php_dbx.dllfunciones dbxNinguna
php_domxml.dllfunciones DOM XML PHP <= 4.2.0 requiere: libxml2.dll (incluida) PHP >= 4.3.0 requiere: iconv.dll (incluida)
php_dotnet.dllfunciones .NETPHP <= 4.1.1
php_exif.dllRead EXIF encabezados de JPEGNinguna
php_fbsql.dllfunciones FrontBasePHP <= 4.2.0
php_fdf.dllFDF: funciones de formato de formulario de datos.Requiere: fdftk.dll (ligado)
php_filepro.dllfunciones fileProAcceso de solo lectura
php_ftp.dllfunciones FTPIntegrada desde PHP 4.0.3
php_gd.dllGD libreria de funciones de imagenes Quitada en PHP 4.3.2. También note que las funciones de truecolor no están disponibles e GD1, en lugar de esto, usephp_gd2.dll.
php_gd2.dllGD libreria de funciones de imagenesGD2
php_gettext.dllfunciones Gettext PHP <= 4.2.0 requiere gnu_gettext.dll (incluida), PHP >= 4.2.3 requiere libintl-1.dll, iconv.dll (incluida).
php_hyperwave.dllfunciones HyperWaveNinguna
php_iconv.dllICONV conversión de caracteresRequiere: iconv-1.3.dll (incluida), PHP >=4.2.1 iconv.dll
php_ifx.dllfunciones InformixRequiere: librerias Informix
php_iisfunc.dllfunciones de administración IISNinguna
php_imap.dllIMAP funcuines POP3 y NNTPPHP 3: php3_imap4r1.dll
php_ingres.dllfunciones Ingres IIRequiere: Librerias Ingres II
php_interbase.dllfunciones InterBaseRequiere: gds32.dll (incluida)
php_java.dllfunciones JavaPHP <= 4.0.6 requiere: jvm.dll (incluida)
php_ldap.dllfunciones LDAP PHP <= 4.2.0 requiere libsasl.dll (incluida), PHP >= 4.3.0 requiere libeay32.dll, ssleay32.dll (incluida)
php_mbstring.dllfunciones Multi-Byte StringNinguna
php_mcrypt.dllfunciones Mcrypt EncryptionRequiere: libmcrypt.dll
php_mhash.dllfunciones MhashPHP >= 4.3.0 requiere: libmhash.dll (incluida)
php_mime_magic.dllfunciones MimetypeRequiere: magic.mime (incluida)
php_ming.dllMing funciones para flashNinguna
php_msql.dllfunciones mSQLRequiere: msql.dll (incluida)
php3_msql1.dllcliente mSQL 1no se conocen
php3_msql2.dllcliente mSQL 2no se conocen
php_mssql.dllfunciones MSSQLRequiere: ntwdblib.dll (incluida)
php3_mysql.dllfunciones MySQLIntegrada en PHP 4
php3_nsmail.dllfunciones de mail Netscapeno se conocen
php3_oci73.dllfunciones Oracleno se conocen
php_oci8.dllfunciones Oracle 8Requiere: librerias del cliente Oracle 8.1+
php_openssl.dllfunciones OpenSSLRequiere: libeay32.dll (incluida)
php_oracle.dllfunciones OracleRequiere: librerias de cliente Oracle 7
php_overload.dllfunciones sobrecarga de objetosintegrada desde PHP 4.3.0
php_pdf.dllfunciones PDFNinguna
php_pgsql.dllfunciones PostgreSQLNinguna
php_printer.dllfunciones de ImpresoraNinguna
php_shmop.dllfunciones Memoria compartidaNinguna
php_snmp.dllSNMP gunciones get y walk¡Sólo NT!
php_sockets.dllfunciones de SocketNinguna
php_sybase_ct.dllfunciones SybaseRequiere: librerias cliente de Sybase
php_tokenizer.dllfunciones TokenizerIntegrada desde PHP 4.3.0
php_w32api.dllfunciones W32apiNinguna
php_xmlrpc.dllfunciones XML-RPCPHP >= 4.2.1 requiere: iconv.dll (incluida)
php_xslt.dllfunciones XSLT PHP <= 4.2.0 requiere sablot.dll, expat.dll (incluida). PHP >= 4.2.1 requiere sablot.dll, expat.dll, iconv.dll (incluida).
php_yaz.dllfunciones YAZRequiere: yaz.dll (incluida)
php_zip.dllfunciones Zip FileAcceso de sólo lectura
php_zlib.dllfunciones de compresión ZLibIntegrada desde PHP 4.3.0


Servidores-CGI/Linea de comandos

Por defecto PHP se compila como un programa CGI. Esto crea un intérprete de comandos que puede ser usado para procesar CGI scripts ó scripts en PHP ejecutados directamente en linea de comandos. Si utilizais un servidor web que soporte PHP como módulo, deberiais de usarlo de este modo para sacarle el mejor partido. Sin embargo, la versión CGI permite correr páginas PHP bajo usuarios con identificaciones diferentes. Asegurarse de leer el Capítulo sobre seguridad si vais a utilizar PHP como CGI.

A partir de PHP 4.3.0, se han añadido caracteristicas importantes a PHP. Una nueva SAPI llamada CLI existe también y tiene el mismo nombre que el binario CGI. Lo que se instala en {PREFIX}/bin/php depende de vuestra configuración y se encuentra descrito detalladamente en la sección del manual Usando PHP desde la linea de comandos, Para más información, lea esa sección dl manual.


Comprobando

Si compilais PHP como binario CGI, podeis comprobar que todo funcione con el comando make test. Es siempre una buena idea el comprobar que todo funciona despues de una compilación. De esta manera podeis encontrar problemas con PHP en vuestra plataforma en una fase inicial.


Benchmarking

Si habeis compilado PHP 3 como binario CGI, podeis poner a prueba vuestra instalación utilizando el comando make bench. Tener en cuenta que si safe mode está activado por defecto, no se podra terminar la prueba si esta tarda en ejecutarse más de los 30 segundos permitidos. Esto ocurre porque la función set_time_limit() no puede ser usada en safe mode. Usar la opción de configuración max_execution_time para controlar el tiempo de ejecución de vuestros scripts. make bench ignora el fichero de configuración.

Nota: make bench se encuentra disponible solamente en PHP 3.


Usando variables

Algunas variables de entorno provistas por el servidor no se encuentran definidas en la especificación CGI/1.1 actual. Solamente las siguientes variables están definidas; todas las demás son se pueden definir como 'extensiones': AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL and SERVER_SOFTWARE


Servidores-Apache

Esta sección contiene información específica sobre la instalación de PHP con Apache, tanto para la versión Unix como Windows. Las instrucciones de instalación con apache2 se encuentran en su propia página.


Instalando PHP con Apache en Unix

Se pueden seleccionar argumentos a usar con el comando configure de la linea 10 de más abajo, de la lista completa de opciones de configuración. Los números de versiones han sido omitidos aqui para asegurarse que las instrucciones no son incorrectas, debeis cambiar 'xxx' con los valores correctos de vuestros ficheros.

Ejemplo 3-5. Instrucciones de instalación para PHP (Versión módulo compartido de Apache)

1.  gunzip apache_xxx.tar.gz
2.  tar -xvf apache_xxx.tar
3.  gunzip php-xxx.tar.gz
4.  tar -xvf php-xxx.tar
5.  cd apache_xxx
6.  ./configure --prefix=/www --enable-module=so
7.  make
8.  make install
9.  cd ../php-xxx

10. Ahora, configurar vuestro PHP. En este paso podeis configurar PHP
    con diferentes opciones, como por ejemplo que extensiones estaran
    dispobibles. Podeis ejecutar ./configure --help para obtener una
    lista con las opciones que podeis usar. En nuestro ejemplo,
    configuramos con Apache y soporte MySQL. Vuestro path a apxs puede
    diferir del nuestro, dependiendo donde lo tengais instalado. 

      ./configure --with-mysql --with-apxs=/www/bin/apxs

11. make
12. make install

    Si decides cambiar las opciones de configuraci&oacute;n despues de la
    instalaci&oacute;n, solamente se necesita repetir los tres ultimos
    pasos. Solamente se necesita arrancar de nuevo Apache para que
    cargue el nuevo modulo. No es necesario recompilar Apache.

    Tener en cuenta que si no se especifica lo contrario, 'make install'
    tambien instala PEAR, diferentes herramientas PHP tal como phpsize,
    PHP CLI y mas.

13. Configurar vuestro fichero php.ini  

     cp php.ini-dist /usr/local/lib/php.ini

    Se puede editar el fichero php.ini para configurar como PHP
    funciona. Si quereis tener este fichero en otra localizacion, podeis
    usar --with-config-file-path=/path en el paso 10.

    Si usais el fichero php.ini-recommended, asegurarse de leer la
    lista de cambios en este fichero, ya que afectan al modo de
    funcionamiento de PHP.

14. Editar httpd.conf para cargar el modulo PHP. El path a la derecha
    de 'LoadModule' debe de coincidir con el path donde el modulo PHP
    se encuentre en vuestro sistema. El comando que habeis ajecutado
    anteriormente 'make install' puede que haya anadido esto, pero
    asegurarse de comprobar que el cambio ha sido hecho.

    Para PHP 4:
            
      LoadModule php4_module libexec/libphp4.so

    Para PHP 5:
                      
      LoadModule php5_module libexec/libphp5.so
      
15. Y en la seccion 'AddModule' en httpd.conf, anadir:

    Para PHP 4:
    
      AddModule mod_php4.c
      
    Para PHP 5:
    
      AddModule mod_php5.c

16. Tenemos que decirle a Apache que extension vamos a utilizar en
    nuestros scripts PHP. Podemos utilizar la extension
    .php para PHP aunque podemos anadir la extension que queramos
    separadas con un espacio. En nuestro ejemplo utilizaremos por
    ejemplo .php y .phtml 

      AddType application/x-httpd-php .php .phtml

    Tambien se sulele utilizar la extension .phps para mostrar el
    codigo PHP coloreado. Para ello tenemos que anadir la siguiente linea:

      AddType application/x-httpd-php-source .phps

17. Utilizar el procedimiento habitual que utiliceis para arrancar
    Apache. (Debeis de parar y arrancar Apache, no vale recargar
    (reload) usando una se&ntilde;al HUP &oacute; USR1).

Dependiendo de vuestra instalación de Apache y variante Unix, existen numerosas maneras de parar y arrancar el servidor Apache. Más abajo teneis las maneras más típicas de parar y arrancar el servidor en diferentes instalaciones de apache/unix. /path/to/ se tiene que actualizar

Ejemplo 3-6. Ejemplos de comandos para rearrancar Apache

1. En ciertas variantes de Linux y SysV:
/etc/rc.d/init.d/httpd restart

2. Usando el script apachectl :
/path/to/apachectl stop
/path/to/apachectl start

3. httpdctl y httpsdctl (Usando OpenSSL), similar a apachectl:
/path/to/httpsdctl stop
/path/to/httpsdctl start

4. Usando mod_ssl, u otro servidor SSL, quizas querais parar y
     arrancar manualmente:
/path/to/apachectl stop
/path/to/apachectl startssl

La localización de los binarios apachectl y http(s)dctl suele variar. Si tu sistema tiene los comandos locate ó whereis ó which, podeis utilizarlos para localizar los programas de control de vuestro servidor.

Diferentes ejemplos de compilación de PHP para Apache:

./configure --with-apxs --with-pgsql

Esto creará una biblioteca compartida libphp4.so que será cargada por Apache usando una linea LoadModule en el fichero de configuración de Apache httpd.conf. Soporte para PostgreSQL es incorporado en la biblioteca libphp4.so.

./configure --with-apxs --with-pgsql=shared

Esto creará una biblioteca compartida libphp4.so que será cargada por Apache, pero creará tambien una biblioteca compartida pgsql.so que se puede cargar por PHP usando ó la directiva de la extensión en el fichero php.ini ó cargandola explicitamente en un script usando la función dl().

./configure --with-apache=/path/to/apache_source --with-pgsql

Esto creará una biblioteca libmodphp4.a, un fichero mod_php4.c y algunos otros pequeños ficheros y copiara todo al directorio src/modules/php4 en el directorio fuente de Apache. Apache hay que compilarlo entonces con --activate-module=src/modules/php4/libphp4.a y el sistema de generación de apache se encargará de crear el fichero libphp4.a y enlazarlo estáticamente al binario httpd. El soporte para PostgreSQL es incluido directamente en el binario httpd, asi que el resultado final en un solo fichero binario httpd que incluye todo el Apache y PHP.

./configure --with-apache=/path/to/apache_source --with-pgsql=shared

Igual que el ejemplo anterior, excepto que el soporte para PostgreSQL no se incluye directamente en httpd, se crea una biblioteca compartida pgsql.so que hay que cargar en PHP, bien desde el fichero php.ini ó directamente usando la función dl().

Antes de escoger el método a utilizar para instalar PHP, debeis considerar los pros y los contras de cada método. Compilarlo como una biblioteca compartida tiene la ventaja de poder compilar Apache por separado y de no tener que recompilar todo si añadimos ó cambiamos PHP. Compilando PHP estaticamente en Apache significa que PHP cargará más rapidamente y se ejecutará más rapido. Para más información, vea la página de Apache sobre soporte DSO.

Nota: El fichero de configuración por defecto de Apache, httpd.conf, viene con una sección como esta:

User nobody
Group "#-1"

A menos que esto se cambie a "Group nogroup" ("Group daemon" tambien es muy común), PHP no podra abrir ficheros.

Nota: Asegurarse que la versión especificada de apxs cuando se usa --with-apxs=/path/to/apxs, es la version instaladada en tu sistema y no la versión que se encuentra en directorio con las fuentes de Apache.


Instalando PHP con apache 1.3.x en Windows

Existen dos maneras de utilizar PHP con Apache 1.3.x en Windows. Una es usar el binario CGI (php.exe), la otra es usar el módulo Apache DLL. En ambos casos, hay que parar el servidor Apache y editar el fichero de configuración httpd.conf para configurar Apache con PHP.

Hay que decir que el módulo SAPI es más estable ahora bajo Windows, recomendamos utilizarlo en vez del binario CGI, ya que es más transparente y seguro.

Aunque existen diferentes maneras de configurar PHP con Apache, estas son lo suficientemente simples como para que un iniciado pueda usarlas. Consultar la documentación de Apache para más información sobre directivas de configuración.

Si descomprimimos PHP en c:\php\, tal y como se describe en la sección Pasos para una instalación manual, necesitamos introducir estas lineas en el fichero de configuración de Apache para configurar el binario CGI:

  • ScriptAlias /php/ "c:/php/"

  • AddType application/x-httpd-php .php .phtml

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

La segunda linea de esta lista, se encuentra en la versión actual de httpd.conf, pero esta comentada. Recordar que teneis que cambiar c:/php/ con el "path" a vuestro directorio PHP.

Aviso

El uso de la opción CGI abre la posibilidad de posibles ataques a tu servidor. Por favor, leer la sección sobre Seguridad con la versión CGI para aprender como defenderse de estos ataques.

Si vais a utilizar PHP como módulo de Apache, debeis copiar php4ts.dll al directorio windows/system (para Windows 9x/Me), winnt/system32 (para Windows NT/2000) ó windows/system32 (para Windows XP), sobreescribiendo cualquier fichero antiguo. Una vez copiado, debeis modificar el fichero httpd.conf:

  • Editar httpd.conf en vuestro editor favorito, localizar la directiva LoadModule y añadir la siguiente linea al final de la lista para PHP 4: LoadModule php4_module c:/php/sapi/php4apache.dll, o para PHP 5 LoadModule php5_module "c:/php/sapi/php5apache.dll"

  • Puede ocurrir que despues de usar el instalador de Apache para Windows, tengais que definir la directiva AddModule para mod_php4.c. Esto es especialmente importante si la directiva ClearModuleList está definida. Añadir AddModule mod_php4.c al final de la lista de directivas AddModule. Para PHP 5, usar AddModule mod_php5.c

  • Buscar una frase similar a # AddType allows you to tweak mime.types. Vereis algunas definiciones del tipo AddType, añadir al final de la lista: AddType application/x-httpd-php .php. Podeis elegir la extensión que querais para los ficheros PHP. .php es nuestra sugerencia. Se puede incluso tener .html y .php3 se puede añadir por asuntos de compatibilidad hacia atras.

Despues de cambiar el fichero de configuración, recordar que teneis que arrancar de nuevo Apache, por ejemplo, NET STOP APACHE seguido de NET START APACHE, si ejecutais Apache como un Servicio Windows, ó como lo hagais normalmente.

Existen dos maneras para usar la característica de destacar el código fuente, sin embargo, dependerá de nuestra instalación para que funcionen. Si Apache esta configurado para usar PHP como módulo SAPI, se puede usar esta carcterística añadiendo la linea AddType application/x-httpd-php-source .phps al fichero httpd.conf en el mismo lugar en donde añadimos AddType application/x-httpd-php .php.

Si Apache esta configurado para usar PHP como binario CGI, debereis utilizar la función show_source(). Para ello, crear un script PHP y añadir este código <?php show_source ("original_php_script.php"); ?>. Sustituir original_php_script.php con el nombre del fichero del que quereis presentar el código fuente.

Nota: En Apache para Windows, todos los "backslashes" en un "path", p.ej. "c:\directory\file.ext", deben de convertirse a "forward slashes" , "c:/directory/file.ext".


Servidores-Apache 2.0

Esta sección contiene información específica sobre la instalación de PHP con Apache 2.0, tanto para la versión Unix como Windows.

Aviso

No utilizar Apache 2.0 y PHP en sistemas que esten en producción, tanto en Unix como en Windows.

Animamos a que consulteis la Documentación de Apache para que tengais un conocimento básico sobre el servidor Apache 2.0.


Notas de compatibilidad entre PHP y Apache 2.0

Las siguientes versiones de PHP funcionan con las últimas versiones de Apache 2.0:

Estas versiones de PHP son compatibles con Apache 2.0.40 y posteriores.

Nota: El soporte para SAPI en Apache 2.0 empezó con PHP 4.2.0. PHP 4.2.3 funciona con Apache 2.0.39, no usar otra versión de apache con PHP 4.2.3. De todas maneras, la instalación recomendada es PHP 4.3.0 ó posterios con la versión más reciente de Apache2.

Todas las versiones de PHP mencionadas, tambien trabajan con Apache 1.3.x.


PHP y Apache 2 en Linux

Bajarse la versión más reciente de Apache 2.0 y una versión de PHP de uno de los sitios antes mencionados. Esta guia rápida cubre solamente lo básico para poder empezar a usar Apache 2.0 y PHP. Para más información, consultar la documentación de Apache. Los números de versiones han sido omitidos aqui para asegurarse que las instrucciones no son incorrectas, debeis cambiar 'NN' con los valores correctos de vuestros ficheros.

Ejemplo 3-7. Instrucciones de instalación (Apache 2 versión como módulo compartido)

1.  gzip -d httpd-2_0_NN.tar.gz
2.  tar xvf httpd-2_0_NN.tar
3.  gunzip php-NN.tar.gz
4.  tar -xvf php-NN.tar
5.  cd httpd-2_0_NN
6.  ./configure --enable-so
7.  make
8.  make install

    Ahora teneis Apache 2.0.NN disponible en /usr/local/apache2,
    configurado con soporte para m&oacute;dulos y el estandar "MPM prefork".
    Para comprobar que la instalaci&oacute;n funciona, podeis usar el
    procedimiento usado normalmente para arrancar el servidor Apache,
    p.ej.: /usr/local/apache2/bin/apachectl start , para configurar
    PHP parar el servidor: /usr/local/apache2/bin/apachectl stop.

9.  cd ../php4-NN
10. ./configure --with-apxs2=/usr/local/apache2/bin/apxs
11. make
12. make install
13. cp php.ini-dist /usr/local/lib/php.ini

    Se puede editar el fichero php.ini para configurar como PHP
    funciona. Si quereis tener este fichero en otra
    localizaci&oacute;n, podeis usar --with-config-file-path=/path en
    el paso 10.

14. Editar el fichero  httpd.conf y comprobar que estas
    lineas existen y no est&aacute;n comentadas:

   LoadModule php4_module        libexec/libphp4.so
   AddType application/x-httpd-php .php
 
    Podeis elegir la extension que querais aqui, .php es simplemente
    una sugerencia.

    El "path" a la derecha de LoadModule debe de coincidir con el
    "path" del m&oacute;dulo PHP en vuestro sistema. Si habeis seguido
    los pasos desde el punto 1. no necesitais alterar nada.

15. Utilizar el procedimiento habitual que utiliceis para arrancar
    Apache. P.ej.: /usr/local/apache2/bin/apachectl start

Si habeis seguido los pasos de más arriba, deberiais tener un instalación funcionando de Apache 2.0 con soporte para PHP como módulo SAPI. Por supuesto que existen muchas más opciones de configuración disponibles tanto para Apache como PHP. Para más información use ./configure --help en el directorio correspondiente con el código fuente. En el caso que querais crear una versión "multihilos" (multithreaded) de apache 2.0, debeis sobreescribir el módulo estandar MPM prefork con ó worker ó perchild. Para hacer esto añadir a la linea con "configure" en el paso 6 de más arriba, ó bien --with-mpm=worker ó --with-mpm=perchild. Tener cuidado con las consecuencias y entender que estais haciendo. Para más información, leer la documentación de Apache sobre Módulos MPM.

Nota: Para crear una version multihilos de Apache, vuestro sistema debe de tener soporte para hilos (threads). Esto supone que PHP se debe compilar con "Zend Thread Safety (ZTS)", el cual está en fase de experimentación. Por esto mismo, no todas las extensiones pueden estar disponibles. La configuración recomendada es compilar Apache con el módulo estandar MPM prefork.


PHP y Apache 2.0 en Windows

Se recomienda leer las notas específicas sobre Windows y apache 2.0

Aviso

Apache 2.0 está designado para ejecutarse con Windows NT 4.0, Windows 2000 ó Windows XP. Por el momento, el soporte para Windows9x es incompleto y Apache 2.0 no funcionará en estas plataformas.

Bajarse la versión más reciente de Apache 2.0 y una versión de PHP de uno de los sitios antes mencionados. Seguir las instrucciones del Manual de instalación y volver aqui para seguir con la integración de PHP y Apache.

Existen dos maneras de instalar PHP para que funcione con Apache 2.0 en Windows. Una, es usar el binario CGI y la otra, usar el módulo DLL de Apache. En ambos casos debeis de parar el servidor Apache y editar vuestro fichero httpd.conf para configurar Apache con PHP.

Debeis de insertar estas tres lineas en el fichero de configuración de Apache httpd.conf para utilizar el binario CGI :

Ejemplo 3-8. PHP y Apache 2.0, como binario CGI

ScriptAlias /php/ "c:/php/"
AddType application/x-httpd-php .php
Action application/x-httpd-php "/php/php.exe"

Si quereis utilizar PHP como módulo de Apache 2.0, asegurarse de mover php4ts.dll a winnt/system32 (para Windows NT/2000) ó windows/system32 (para Windows XP), sobreescribiendo cualquier fichero anterior. Debeis de insertar estas dos lineas en el fichero de configuración de Apache httpd.conf para configurar PHP como módulo en Apache 2.0:

Ejemplo 3-9. PHP y Apache 2.0, como módulo

LoadModule php4_module "c:/php/sapi/php4apache2.dll"
AddType application/x-httpd-php .php

Nota: Recordar que en los ejemplos anteriores, teneis que sustituir c:/php/ con vuestro "path" al directorio donde hayais instalado PHP. Usar php4apache2.dll y nophp4apche.dll con vuestra directiva LoadModule. La última de las mencionadas está diseñada para funcionar solo con Apache 1.3.x.

Aviso

No mezclar en vuestra instalación, ficheros dll de diferentes versiones de PHP si quereis que PHP funcione.


Servidores-Caudium

PHP 4 puede ser compilado como un módulo "Pike" para el servidor web Caudium. Tener en cuenta que esto no está soportado en PHP 3. Para instalar PHP 4 con Caudium, seguir las instruciones de mas abajo.

Ejemplo 3-10. Instrucciones de instalación con Caudium

1. Asegurarse que Caudium est&aacute; instalado antes de intentar instalar
   PHP 4. Para que PHP 4 trabaje correctamente se necesita Pike
   versi&oacute;n 7.0.268 &oacute; posterior. En este ejemplo asumimos que Caudium
   est&aacute; instalado en /opt/caudium/server/.

2. Cambiar al directorio php-x.y.z (en donde x.y.z es el n&uacute;mero de
   versi&oacute;n)

3. ./configure --with-caudium=/opt/caudium/server
4. make
5. make install
6. Arrancar de nuevo Caudium, si estaba ejecutandose.
7. Conectarse al interfaz gr&aacute;fico de configuraci&oacute;n e ir al servidor
   virtual en donde quereis a&ntilde;adir soporte para PHP 4. 

8. Pulsar "Add Module" y localizar y a&ntilde;adir "PHP 4 Script Support module".
9. Si la documentaci&oacute;n dice que "el interprete de PHP 4 no est&aacute;
   disponible", asegurarse de haber arrancado de nuevo el servidor. Si
   se hizo, comprobar si existe alg&uacute;n mensaje de error relacionado con
   <filename>PHP4.so</filename> en
   /opt/caudium/logs/debug/default.1. Asegurarse tambi&eacute;n que
   <filename>caudium/server/lib/[pike-version]/PHP4.so</filename> existe.
10. Si es necesario, configurar el soporte de m&oacute;dulos de PHP.

Se puede compilar el módulo Caudium con soporte para las diversas extensiones disponibles en PHP 4. Vea la lista completa de opciones de configuración para obtener información detallada.

Nota: Cuando se compila PHP 4 con soporte para MySQL, hay que asegurarse que el código normal del cliente MySQL es el usado. Si no, pueden existir conflictos si Pike ya tiene soporte para MySQL. Esto se arregla, especificando el directorio donde MySQL está instalado con la opción --with-mysql


Servidores-fhttpd

Para compilar PHP como módulo de fhttpd, contestar "yes" a la pregunta "Build as an fhttpd module?" (la opción de configuración --with-fhttpd=DIR) y especificar el directorio con el código fuente de fhttpd. El directorio por defecto es /usr/local/src/fhttpd. Si estais usando fhttpd, compilar PHP como módulo dará mejores prestaciones, más control y la capacidad de ejecución remota.

Nota: El soporte para fhttpd no se encuentra disponible a partir de PHP 4.3.0.


Servidores-IIS/PWS

Esta sección contiene información específica sobre la instalación de PHP con IIS (Microsoft Internet Information Server), versiones PWS/IIS 3, PWS 4 ó posterior y IIS 4 ó posterior

Importante para usuarios de la versión CGI: Leer la faq sobre cgi.force_redirect para más detalles. Esta directiva debe de tener el valor 0.


Windows y PWS/IIS 3

El método recomendado para configurar estos servidores es usar el archivo REG incluído con la distribución (pws-php4cgi.reg). 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.: .php

  • Haga una doble pulsación con el ratón en el nuevo valor de cadena y escriba la localización de php.exe en el campo del valor. P.ej.: c:\php\php.exe.

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

Los pasos siguientes no afectan a la instalación del servidor web y solamente sirven si quereis ejecutar vuestros scripts en PHP desde la linea de comandos (p.ej: c:\myscripts\test.php) ó haciendo una pulsación doble con el ratón desde una ventana del visualizador de directorios. Podeis saltaros estos pasos si quereis que los ficheros en PHP se abran en un editor cuando hagais una doble pulsación sobre ellos.

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

  • Marque la nueva clave y en el panel del lado derecho haga una doble pulsación 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, haga una doble pulsación en el panel derecho sobre "default value" y escriba PHP Script.

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

  • Pulse el botón derecho sobre la clave Shell ,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 una doble pulsación sobre "default value" y escriba la localización de php.exe. P.ej.: c:\php\php.exe -q %1. (no olvide el %1).

  • Salga de Regedit.

  • Si está usando PWS en Windows, tendra que arrancar la maquina de nuevo para que se carge el registro.

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 y PWS 4 ó posterior

Existen dos opciones para instalar PHP en Windows con PWS 4 ó posterior. Una es el binario CGI de PHP y la otra el módulo DLL ISAPI.

Si elegis el binario CGI, teneis que hacer lo siguiente:

  • Editar el fichero que se incluye con PHP llamado pws-php4cgi.reg (mirar en el directorio SAPI) para actualizarlo con la localización de vuestro php.exe. Las barras invertidas tienen que escaparse, p.ej: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="c:\\php\\php.exe". A continuación incluir este registro en vuestro sistema; podeis hacer esto haciendo una doble pulsación sobre el mismo, con el ratón.

  • En el administrador de PWS, hacer una doble pulsación con el botón derecho del ratón, sobre el directorio donde quereis añadir soporte para PHP, seleccionar "Properties", elegir "Execute" y confirmar.

Si elegis el módulo ISAPI, teneis que hacer lo siguiente:

  • Editar el fichero que se incluye con PHP llamado pws-php4isapi.reg (mirar en el directorio SAPI) para actualizarlo con la localización de vuestro php4isapi.dll. Las barras invertidas tienen que escaparse, p.ej: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="c:\\php\\sapi\\php4isapi.dll". A continuación incluir este registro en vuestro sistema; podeis hacer esto haciendo una doble pulsación sobre el mismo, con el ratón.

  • En el administrador de PWS, hacer una pulsación con el botón derecho del ratón, sobre el directorio donde quereis añadir soporte para PHP, seleccionar "Properties", elegir "Execute" y confirmar.


Windows NT/2000/XP y IIS 4 ó posterior

Para instalar PHP en un servidor NT/2000/XP con IIS 4 ó posterior, teneis que seguir estas instrucciones. Existen dos opciones para instalar PHP, una es el binario CGI de PHP (php.exe) y la otra el módulo ISAPI.

En ambos casos necesitais arrancar la "consola de administración de Microsoft" (Puede encontrarse como 'Administrador de servicios Internet", bien en vuestro "Windows NT 4.0 Option Pack" ó en el Control Panel=>Herramientas de administración bajo Windows 2000/XP). Hacer una pulsación con el botón derecho del ratón en el nodo perteneciente a vuestro servidor web (probablemente aparezca como "Servidor web por defecto") y seleccionar "Propiedades".

Si elegis el binario CGI, teneis que hacer lo siguiente:

  • Bajo "Carpeta Inicial", "Directorio Virtual" ó "Directorio", pulsar en el botón "Configuración" y entrar en la pestaña "Mapas de aplicaciones".

  • Pulse en ""Añadir", y en la caja Programa, escriba: c:\php\php.exe (suponemos que habeis descomprimido PHP en c:\php\).

  • En la caja Extensión, escriba la extensión de fichero que desea asociar a los script de PHP. Dejar "Exclusiones de método" vacio y elegir "Motor de scripts". Tambien podeis elegir "comprobar que el fichero existe" - por una pequeña perdida en el rendimiento, IIS (ó PWS) comprobará que el script existe antes de usar php. Esto significa que obtendremos errores del tipo 404 en vez de errores cgi diciendo que php no devolvio ningún dato.

    Debereis de repetir el paso anterior por cada extensión que querais asociar con PHP. .php y .phtml son valores comunes, aunque .php3 puede que sea necesaria para ejecutar scripts antiguos.

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

Si elegis el módulo ISAPI, teneis que hacer lo siguiente:

  • Si no quereis utilizar Autentificación HTTP usando PHP, podeis (y debeis) de saltaros este paso. Bajo "Filtros ISAPI", añadir un nuevo filtro ISAPI. Usar PHP como nombre del filtro y definir la localización del fichero php4isapi.dll.

  • Bajo "Carpeta Inicial" pulsar en el botón "Configuración" y añadir un nuevo valor en "Mapas de aplicaciones". Definir la localización del fichero php4isapi.dll como ejecutable y .php como la extensión. Dejar "Exclusiones de método" vacio y elegir "Motor de scripts"

  • Parar IIS completamente (NET STOP iisadmin)

  • Arrancar IIS de nuevo (NET START w3svc)


Servidores-Netscape e iPlanet

Esta sección contiene información específica sobre la instalación de PHP con Netscape e iPlanet, tanto en Sun Solaris como en Windows.

Podeis encontrar más información sobre como instalar PHP con "Netscape Enterprise Server" aqui: http://benoit.noss.free.fr/php/install-php4.html


Instalando PHP con Netscape en Sun Solaris

Para compilar PHP para que funcione con los servidores web NES ó iPlanet, definir la localización correcta en la opción --with-nsapi = DIR. La localización por defecto es normalmente /opt/netscape/suitespot/. Leer /php-xxx-version/sapi/nsapi/nsapi-readme.txt para más información.

Ejemplo 3-11. Ejemplo de instalación con Netscape Enterprise en Solaris

Instrucciones para Sun Solaris 2.6 con Netscape Enterprise Server 3.6
From: bhager@invacare.com

1. Instalar los siguientes paquetes (se pueden bajar de
   www.sunfreeware.com u otra servidor)

    flex-2_5_4a-sol26-sparc-local 
    gcc-2_95_2-sol26-sparc-local 
    gzip-1.2.4-sol26-sparc-local 
    perl-5_005_03-sol26-sparc-local 
    bison-1_25-sol26-sparc-local 
    make-3_76_1-sol26-sparc-local 
    m4-1_4-sol26-sparc-local 
    autoconf-2.13 
    automake-1.4 
    mysql-3.23.24-beta (si quereis soporte para MySQL) 
    tar-1.13 (GNU tar) 

2. Asegurarse que la variable PATH incluye los siguientes directorios:
    PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin 
    export PATH 

3. gunzip php-x.x.x.tar.gz 
4. tar xvf php-x.x.x.tar 
5. cd ../php-x.x.x 

6. Asegurarse que /opt/netscape/suitespot/ es el directorio donde
   teneis instalado vuestro servidor netscape, si no, cambiarlo por el
   directorio correcto:
    /configure --with-mysql=/usr/local/mysql --with-nsapi=/opt/netscape/suitespot/ --enable-track-vars --enable-libgcc 
7. make 
8. make install
Despues de terminar la instalación base y de leer el fichero readme apropiado, quizas necesiteis realizar unos cuantos ajustes en la configuración.

Para comenzar, quizas necesiteis añadir algunas localizaciones a la variable de entorno LD_LIBRARY_PATH, para que Netscape pueda encontrar todas las bibliotecas compartidas. Esto se puede hacer en el script de arranque del servidor Netscape. Usuarios de Windows pueden probablemente saltarse este paso. El script de arranque suele estar localizado en: /path/to/server/https-servername/start

Tambien puede que tengais que editar los ficheros de configuración localizados en: /path/to/server/https-servername/config/.

Ejemplo 3-12. Ejemplo de configuración para Netscape Enterprise

Instrucciones de configuraci&oacute;n para Netscape Enterprise Server
From: bhager@invacare.com

1. A&ntilde;adir la siguiente linea al fichero mime.types:

    type=magnus-internal/x-httpd-php exts=php

2. A&ntilde;adir la siguiente linea al fichero obj.conf, shlib
   depender&aacute; de vuestro SO, en Unix es:

    /opt/netscape/suitespot/bin/libphp4.so.

    Las siguientes lineas se deben a&ntilde;dir despues de las lineas
    que inicializan "mime types".

    Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="/php4/nsapiPHP4.dll"
    Init fn=php4_init errorString="Failed to initialize PHP!"

    <object name="default">
    . 
    . 
    . 
    .#NOTA Esta linea debe de a&ntilde;adirse despues de todas las
     lineas 'ObjectType' y antes de las lineas 'AddLog'.

    Service fn="php4_execute" type="magnus-internal/x-httpd-php" 
    . 
    . 
    </Object>


    <Object name="x-httpd-php"> 
    ObjectType fn="force-type" type="magnus-internal/x-httpd-php" 
    Service fn=php4_execute 
    </Object> 


    Configuraci&oacute;n de la autentificaci&oacute;n

    Para configurar autentificaci&oacute;n PHP en todo el servidor,
    a&ntilde;adir la siguiente linea:

    <Object name="default"> 
    AuthTrans fn=php4_auth_trans 
    . 
    . 
    . 
    . 
    </Object> 

    Para configurar autentificaci&oacute;n PHP en una localizaci&oacute;n,
    a&ntilde;adir lo siguiente:

    <Object ppath="d:\path\to\authenticated\dir\*"> 
    AuthTrans fn=php4_auth_trans 
    </Object>

Si estais usando Netscape Enterprise 4.x, debereis hacer lo siguiente:

Ejemplo 3-13. Ejemplo de configuración para Netscape Enterprise 4.x

A&ntilde;adir estas lineas despues de la secci&oacute;n que
inicializa "mime types", lo dem&aacute;s es similar al ejemplo anterior:
From: Graeme Hoose (GraemeHoose@BrightStation.com)

Init fn="load-modules" shlib="/path/to/server4/bin/libphp4.so" funcs="php4_init,php4_close,php4_execute,php4_auth_trans"
Init fn="php4_init" LateInit="yes"

Instalando PHP con Netscape en Windows

Para instalar PHP como binario CGI (con Netscape Enterprise Server, iPlanet y quizás Fastrack), hacer lo siguiente:

  • Copiar php4ts.dll al directorio donde instalasteis Windows.

  • Crear un fichero asociado desde la linea de comandos. Escribir lo siguiente:
    assoc .php=PHPScript
    ftype PHPScript=c:\php\php.exe %1 %*

  • En el servidor de administracion de "Netscape Enterprise", crear un directorio shellcgi señuelo y borrarlo (esto crea 5 lineas importantes en obj.conf y permite al servidor web manejar scripts shellcgi)

  • En el servidor de administracion de "Netscape Enterprise", crear un nuevo tipo mime (Categoria: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).

  • Hacerlo con todas las instancias del servidor web con las que quereis utilizar php.

Se pueden encontrar más detalles sobre como configurar PHP como binario CGI, aqui: http://benoit.noss.free.fr/php/install-php.html

Para instalar PHP como NSAPI (con Netscape Enterprise Server, iPlanet y quizás Fastrack), hacer lo siguiente:

  • Copiar php4ts.dll al directorio donde instalasteis Windows.

  • Crear un fichero asociado desde la linea de comandos. Escribir lo siguiente:
    assoc .php=PHPScript
    ftype PHPScript=c:\php\php.exe %1 %*

  • En el servidor de administracion de "Netscape Enterprise", crear un nuevo tipo mime (Categoria: type, Content-Type: magnus-internal/x-httpd-php, File Suffix:php).

  • Parar vuestro servidor web y editar obj.conf. Al final de la sección de inicialización, añadir estas dos lineas (despues de la sección mime type):
    Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll"
    Init fn="php4_init" errorString="Failed to initialise PHP!"

  • En la sección < Object name="default" > añadir lo siguiente despues de todas las lineas 'ObjectType' y antes de las lineas 'AddLog':
    Service fn="php4_execute" type="magnus-internal/x-httpd-php"

  • Al final del fichero, crear un nuevo objeto llamado x-httpd-php, insertando estas lineas:
    <Object name="x-httpd-php">
    ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
    Service fn=php4_execute
    </Object>

  • Rearrancar vuestro servidor web:

  • Hacerlo con todas las instancias del servidor web con las que quereis utilizar php.

Se pueden encontrar más detalles sobre como configurar PHP como un filtro NSAPI , aqui: http://benoit.noss.free.fr/php/install-php4.html


Servidores-Servidor OmniHTTPd

Esta sección contiene información específica sobre la instalación de PHP con OmniHTTPd.


OmniHTTPd 2.0b1 y posteriores en Windows

Los siguientes pasos se tienen que completar para que PHP funcione con OmniHTTPd. Nos referimos a la instalación de PHP como ejecutable CGI. SAPI es soportado por OmniHTTPd, pero diferentes comprobaciones han demostrado que PHP como módulo ISAPI no es estable.

Importante para usuarios de la versión CGI: Leer la faq sobre cgi.force_redirect para más detalles. Esta directiva debe de tener el valor 0.

  • Paso 1: Instalar el servidor OmniHTTPd.

  • Paso 2: Pulsar con el botón derecho del ratón en el icono azul de OmniHTTPd en la bandeja del sistema y seleccionar Propiedades.

  • Paso 3: Pulsar en Configuración global del servidor web

  • Paso 4: En la pestaña 'Externo', escribir: virtual = .php | actual = c:\path-to-php-dir\php.exe y pulsar el botón "añadir".

  • Paso 5: en la pestaña Mime, escribir: virtual = wwwserver/stdcgi | actual = .php y pulsar el botón "añadir".

  • Paso 6: Pulsar OK

Repetir los pasos 2-6 por cada extensión que querais asociar con PHP.

Nota: Algunos paquetes OmniHTTPd vienen con soporte para PHP. Podeis elegirlos para crear una configuración a medida y no utilizar el componente PHP. Recomendamos que useis los últimos binarios disponibles. Algunos servidores OmniHTTPd vienen con la versión beta de PHP 4, asi que no debeis de elegir esta versión e instalar mejor vuestra propia versión. Si el servidor está instalado en vuestra máquina, usar el botón "Cambiar" en los pasos 4 y 5 para configurar la información correcta.


Servidores-Sambar

Esta sección contiene información específica sobre la instalación de PHP con el servidor Sambar para Windows


Sambar para Windows

Esta lista describe como instalar el módulo ISAPI de PHP para que funcione conel servidor Sambar para Windows.

  • Localizar el fichero mappings.ini (en el directorio de configuración) en el directorio de Sambar.

  • Editar mappings.ini i añadir la siguiente linea bajo la etiqueta [ISAPI]:

    *.php = c:\php\php4isapi.dll

    (Esta linea asume que PHP está instalado en c:\php.)

  • Arrancar el servidor Sambar de nuevo.


Servidores-Xitami

Esta sección contiene información específica sobre la instalación de PHP con Xitami.


Xitami para Windows

A continuación se describe como instalar el binario CGI de PHP para que funcione con Xitami en Windows.

Importante para usuarios de la versión CGI: Leer la faq sobre cgi.force_redirect para más detalles. Esta directiva debe de tener el valor 0.

  • Asegurarse que el servidor está funcionando, conectar desde vuestro navegador con la consola de administración de xitamis (normalmente http://127.0.0.1/admin) y pulsar en "Configuración".

  • Ir a la sección de "Filtros" e introducir la extensión ha utilizar con PHP (p.ej: .php) en el campo "Extensiones de ficheros".

  • Como comando ó script en la sección "Filtros", introducir la localización y nombre del binario PHP, p.ej: c:\php\php.exe.

  • Pulsar el icono "Grabar".

  • Rearrancar el servidor para que carge los cambios.


Servidores-Otros servidores web

PHP se puede utilizar con un gran número de servidores web. Vea las opciones relativas a Servidores para conseguir la lista completa de opciones de configuración. La versión PHP CGI es compatible prácticamente con todos los servidores web que soporten el estandar CGI.


Problemas?

Lee la FAQ

Algunos problemas son más comunes que otros. Los más comunes se pueden consultar en la FAQ de PHP en este manual.


Otros problemas

Si todavia teneis el mismo problema, alguien en la lista de correos sobre instalación de PHP, puede ayudaros. Primero, comprobar en los archivos de la lista si vuestro problema ya ha sido contestado. Los archivos se encuentran disponibles en las página de soporte http://www.php.net/. Para subscribirse a esta lista de correos mandar un correo vacío a php-install-subscribe@lists.php.net. La dirección de la lista es php-install@lists.php.net.

Si quereis conseguir ayuda en la lista de correo, intentar describir lo más detalladamente posible vuestro problema, los datos sobre vuestro sistema (sistema operativo que utilizais, versión de PHP, servidor web, si usais PHP como binario CGI ó como módulo, safe mode, etc...) y a ser posible código suficiente para poder reproducir vuestro problema.


Informes sobre Bugs

Si creeis que habeis encontrado un bug (error de programación) en PHP, mandarnos un informe. Probablemente los desarrolladores de PHP no lo conozcan y si no informais sobre el mismo no podrá arreglarse. Podeis informar sobre bugs a traves del sistema de seguimiento de bugs en http://bugs.php.net/. No mandar informes a la lista de correos ó en mensajes privados a los desarrolladores. El sistema de seguimiento tambien se puede utilizar para pedir nuevas caracteristicas en versiones futuras.

Lea Como informar sobre un bug antes de mandar un informe.


Capítulo 4. Configuración del comportamiento de PHP

El archivo de configuración

El archivo de configuración (llamado php3.ini en PHP 3, y simplemente php.ini a partir de PHP 4) es leído cuando arranca 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 y CLI, esto ocurre en cada llamada.

La localización por defecto de php.ini es definida en tiempo de compilación (Consultar la FAQ), pero puede ser cambiada en la versión CGI y CLI con la opción de la linea de comandos -c, consultar el cápitulo sobre como usar PHP desde la linea de comandos. También se puede definir la variable de entorno PHPRC con un "path" adicional para la búsqueda del archivo php.ini

Nota: El servidor web Apache cambia al directorio raiz al arrancar, por ello PHP intentará leer el archivo php.ini en el directorio raiz, si existe.

Las directivas php.ini gestionadas por extensiones están documentadas en cada una de las páginas de las extensiones respectivamente. La lista de directivas de núcleo se encuentra disponible en el apéndice. En cualquier caso, es probable que no todas las directivas de PHP estén documentadas en el manual. Para obtener una lista completa de todas las directivas disponibles en su versión de PHP, por favor lea su archivo php.ini, el cual debe estar bien documentado. Alternativamente, puede encontrar útil la última versión del archivo php.ini desde CVS.

Ejemplo 4-1. Ejemplo php.ini

; any text on a line after an unquoted semicolon (;) is ignored
[php] ; section markers (text within square brackets) are also ignored
; Boolean values can be set to either:
;    true, on, yes
; or false, off, no, none
register_globals = off
track_errors = yes

; you can enclose strings in double-quotes
include_path = ".:/usr/local/lib/php"

; backslashes are treated the same as any other character
include_path = ".;c:\php\lib"


Como cambiar los valores de la configuración

Ejecución de PHP como un módulo de Apache

Cuando se usa PHP como un módulo de Apache, se pueden cambiar valores de la configuración usando directivas en los archivos de configuración de apache, httpd.conf y .htaccess. Necesitará de los privilegios "AllowOverride Options" o "AllowOverride All" para hacerlo.

Con PHP 4 y PHP 5, hay varias directivas Apache que permiten cambiar la configuración de PHP desde los archivos de configuración de apache. Para obtener una lista de que directivas son del tipo PHP_INI_ALL, PHP_INI_PERDIR, ó PHP_INI_SYSTEM, consultar la lista que se encuentra en la documentación de la función ini_set().

Nota: Con PHP 3, existen directivas que corresponden a cada parámetro de configuración en php3.ini, con el prefijo "php3_".

php_value nombre valor

Asigna el valor de la directiva especificada. Puede ser usado solamente con directivas del tipo PHP_INI_ALL y PHP_INI_PERDIR. Para borrar un valor previo, asignar none como valor

Nota: No use php_value para definir valores booleanos. Debería usarse php_flag en su lugar (vea más abajo).

php_flag nombre on|off

Usado para asignar una directiva de configuración booleana. Puede ser usado solamente con directivas del tipo PHP_INI_ALL y PHP_INI_PERDIR.

php_admin_value nombre valor

Asigna el valor de la directiva especificada. Esto no puede usarse en archivos .htaccess. Todo tipo de directiva asignada con php_admin_value no puede ser cambiada con .htaccess ó directivas "virtualhost". Para borrar un valor previo, asignar none como valor.

php_admin_flag nombre on|off

Usado para asignar una directiva de configuración booleana. Esto no puede usarse en archivos .htaccess. Todo tipo de directiva asignada con php_admin_flag no puede ser cambiada con .htaccess ó directivas.

Ejemplo 4-2. Ejemplo de configuración de Apache

<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag safe_mode on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag safe_mode on
</IfModule>
<IfModule mod_php3.c>
  php3_include_path ".:/usr/local/lib/php"
  php3_safe_mode on
</IfModule>

Atención

Las Constantes en PHP no existen fuera de PHP. Por ejemplo, en httpd.conf no se pueden usar constantes PHP tales como E_ALL ó E_NOTICE para definir la directiva error_reporting, ya que no tendrá ningún significado y será evaluada como 0. Usar los valores asociados de "bitmask" en su lugar. Estas constantes pueden ser usadas en php.ini


Modificación de la configuración de PHP usando el registro de Windows

Cuando se usa PHP en Windows, se pueden cambiar los valores de configuración para cada directorio por medio de los registros de Windows. Los valores de configuración se guardan en la llave de registro HKLM\SOFTWARE\PHP\Per Directory Values, en las subllaves correspondientes al PATH. Por ejemplo, los valores de configuracion del directorio c:\inetpub\wwwroot se guardarán en HKLM\SOFTWARE\PHP\Valores Por Directorio\c\inetpub\wwwroot. La configuración de un directorio es válida para todos los scripts ejecutados en el mismo y sus subdirectorios. Los valores en la llave deben de definirse con el nombre de la directiva de configuración de PHP y el valor tipo cadena. Las constantes PHP en los valores no son analizadas.


Otras interfaces con PHP

Independientemente del modo en que ejecute PHP, es posible cambiar ciertos valores en tiempo de ejecución usando ini_set(). Vea la documentación en la página sobre ini_set() para más información.

Si está interesado en una lista completa de parámetros de configuración en su sistema con sus valores actuales, puede ejecutar la función phpinfo(), y revisar la página resultante. También puede acceder a los valores de directivas de configuración individuales en tiempo de ejecución usando ini_get() o get_cfg_var().


Capítulo 5. Sintaxis 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 5-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 bibliotecas 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 5-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 6. Tipos

Introducción

PHP soporta ocho tipos primitivos.

Cuatro tipos escalares:

Dos tipos compuestos:

Y finalmente dos tipos especiales:

Este manual introduce también algunos pseudo-tipos por razones de legibilidad:

También puede encontrar algunas referencias al tipo "double". Considere al tipo double como el mismo que float, los dos nombres existen solo por razones históricas.

El tipo de una variable usualmente no es declarado por el programador; en cambio, es decidido en tiempo de compilación por PHP dependiendo del contexto en el que es usado la variable.

Nota: Si desea chequear el tipo y valor de una cierta expresión, use var_dump().

Nota: Si tan solo desea una representación legible para humanos del tipo para propósitos de depuración, use gettype(). Para chequear por un cierto tipo, no use gettype(); en su lugar utilice las funciones is_tipo. Algunos ejemplos:

<?php
$bool = TRUE;   // un valor booleano
$str  = "foo";  // una cadena
$int  = 12;     // un entero

echo gettype($bool); // imprime "boolean"
echo gettype($str);  // imprime "string"

// Si este valor es un entere, incrementarlo en cuatro
if (is_int($int)) {
    $int += 4;
}

// Si $bool es una cadena, imprimirla
// (no imprime nada)
if (is_string($bool)) {
    echo "Cadena: $bool";
}
?>

Si quisiera forzar la conversión de una variable a cierto tipo, puede moldear la variable, o usar la función settype() sobre ella.

Note que una variable puede ser evaluada con valores diferentes en ciertas situaciones, dependiendo del tipo que posee en cada momento. Para más información, vea la sección sobre Manipulación de Tipos. Asimismo, puede encontrarse interesado en consultar las tablas de comparación de tipos, ya que éstas muestran ejemplos de las varias comparaciones relacionadas con tipos.


Booleanos

Este es el tipo más simple. Un boolean expresa un valor de verdad. Puede ser TRUE or FALSE.

Nota: El tipo booleano fue introducido en PHP 4.


Sintaxis

Para especificar un literal booleano, use alguna de las palabras clave TRUE o FALSE. Ambas son insensibles a mayúsculas y minúsculas.

<?php
$foo = True; // asignar el valor TRUE a $foo
?>

Usualmente se usa algún tipo de operador que deuelve un valor boolean, y luego éste es pasado a una estructura de control.

<?php
// == es un operador que prueba por
// igualdad y devuelve un booleano
if ($accion == "mostrar_version") {
    echo "La versi&oacute;n es 1.23";
}

// esto no es necesario...
if ($mostrar_separadores == TRUE) {
    echo "<hr>\n";
}

// ...porque se puede escribir simplemente
if ($mostrar_separadores) {
    echo "<hr>\n";
}
?>


Conversión a booleano

Para convertir explícitamente un valor a boolean, use el moldeamiento (bool) o (boolean). Sin embargo, en la mayoría de casos no es necesario usar el moldeamiento, ya que un valor será convertido automáticamente si un operador, función o estructura de control requiere un argumento tipo boolean.

Vea también Manipulación de Tipos.

Cuando se realizan conversiones a boolean, los siguientes valores son considerados FALSE:

Cualquier otro valor es considerado TRUE (incluyendo cualquier resource).

Aviso

¡-1 es considerado TRUE, como cualquier otro número diferente a cero (ya sea negativo o positivo)!

<?php
echo gettype((bool) "");        // bool(false)
echo gettype((bool) 1);         // bool(true)
echo gettype((bool) -2);        // bool(true)
echo gettype((bool) "foo");     // bool(true)
echo gettype((bool) 2.3e5);     // bool(true)
echo gettype((bool) array(12)); // bool(true)
echo gettype((bool) array());   // bool(false)
?>


Enteros

Un integer es un número del conjunto Z = {..., -2, -1, 0, 1, 2, ...}.

Vea también: Entero de longitud arbitraria / GMP, Números de punto flotante, y Precisión arbitraria / BCMath


Sintaxis

Los enteros pueden ser especificados en notación decimal (base-10), hexadecimal (base-16) u octal (base-8), opcionalmente precedidos por un signo (- o +).

Si usa la notación octal, debe preceder el número con un 0 (cero), para usar la notación hexadecimal, preceda el número con 0x.

Ejemplo 6-1. Literales tipo entero

<?php
$a = 1234; // numero decimal
$a = -123; // un numero negativo
$a = 0123; // numero octal (equivalente al 83 decimal)
$a = 0x1A; // numero hexadecimal (equivalente al 26 decimal)
?>
Formalmente, la posible estructura para literales enteros es:

decimal     : [1-9][0-9]*
            | 0

hexadecimal : 0[xX][0-9a-fA-F]+

octal       : 0[0-7]+

integer     : [+-]?decimal
            | [+-]?hexadecimal
            | [+-]?octal

El tamaño de un entero es dependiente de la plataforma, aunque un valor máximo de aproximadamente dos billones es el valor usual (lo que es un valor de 32 bits con signo). PHP no soporta enteros sin signo.


Desbordamiento de enteros

Si especifica un número más allá de los límites del tipo integer, será interpretado en su lugar como un float. Asimismo, si realiza una operación que resulta en un número más allá de los límites del tipo integer, un float es retornado en su lugar.

<?php
$numero_grande =  2147483647;
var_dump($numero_grande);
// output: int(2147483647)

$numero_grande =  2147483648;
var_dump($numero_grande);
// output: float(2147483648)

// esto tambien ocurre con los enteros indicados como hexadecimales:
var_dump( 0x80000000 );
// output: float(2147483648)

$millon = 1000000;
$numero_grande =  50000 * $millon;
var_dump($numero_grande);
// output: float(50000000000)
?>

Aviso

Desafortunadamente, había un fallo en PHP que provocaba que esto no siempre funcionara correctamente cuando se presentaban números negativos. Por ejemplo: cuando hace -50000 * $millon, el resultado será -429496728. Sin embargo, cuando ambos operandos son positivos no se presenta ningún problema.

Este problema fue resuelto en PHP 4.1.0.

No hay un operador de división de enteros en PHP. 1/2 produce el float 0.5. Puede moldear el valor a un entero para asegurarse de redondearlo hacia abajo, o puede usar la función round().

<?php
var_dump(25/7);         // float(3.5714285714286) 
var_dump((int) (25/7)); // int(3)
var_dump(round(25/7));  // float(4) 
?>


Conversión a entero

Para convertir explícitamente un valor a integer, use alguno de los moldeamientos (int) o (integer). Sin embargo, en la mayoría de casos no necesita usar el moldeamiento, ya que un valor será convertido automáticamente si un operador, función o estructura de control requiere un argumento tipo integer. También puede convertir un valor a entero con la función intval().

Vea también Manipulación de Tipos.


Desde booleans

FALSE producirá 0 (cero), y TRUE producirá 1 (uno).


Desde números de punto flotante

Cuando se realizan conversiones desde un flotante a un entero, el número será redondeado hacia cero.

Si el flotante se encuentra más allá de los límites del entero (usualmente +/- 2.15e+9 = 2^31), el resultado es indefinido, ya que el flotante no tiene suficiente precisión para dar un resultado entero exacto. No se producirá una advertencia, ¡ni siquiera una noticia en este caso!

Aviso

Nunca moldee una fracción desconocida a integer, ya que esto en ocasiones produce resultados inesperados.

<?php
echo (int) ( (0.1+0.7) * 10 ); // imprime 7!
?>

Para más información, consulte la advertencia sobre precisión-flotante.


Desde otros tipos

Atención

El comportamiento de convertir desde entero no es definido para otros tipos. Actualmente, el comportamiento es el mismo que si el valor fuera antes convertido a booleano. Sin embargo, no confíe en este comportamiente, ya que puede ser modificado sin aviso.


Números de punto flotante

Los números de punto flotante (también conocidos como "flotantes", "dobles" o "números reales") pueden ser especificados usando cualquiera de las siguientes sintaxis:

<?php
$a = 1.234; 
$b = 1.2e3; 
$c = 7E-10;
?>

Formalmente:

LNUM          [0-9]+
DNUM          ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})

El tamaño de un flotante depende de la plataforma, aunque un valor común consiste en un máximo de ~1.8e308 con una precisión de aproximadamente 14 dígitos decimales (lo que es un valor de 64 bits en formato IEEE).

Precisión del punto flotante

Es bastante común que algunas fracciones decimales simples como 0.1 o 0.7 no puedan ser convertidas a su representación binaria interna sin perder un poco de precisión. Esto puede llevar a resultados confusos: por ejemplo, floor((0.1+0.7)*10) usualmente devolverá 7 en lugar del esperado 8 ya que el resultado de la representación interna es en realidad algo como 7.9999999999....

Esto se encuentra relacionado al hecho de que es imposible expresar de forma exacta algunas fracciones en notación decimal con un número finito de dígitos. Por ejemplo, 1/3 en forma decimal se convierte en 0.3333333. . ..

Así que nunca confíe en resultados de números flotantes hasta el último dígito, y nunca compare números de punto flotante para conocer si son equivalentes. Si realmente necesita una mejor precisión, es buena idea que use las funciones matemáticas de precisión arbitraria o las funciones gmp en su lugar.


Conversión a flotante

Para más información sobre cuándo y cómo son convertidas las cadenas a flotantes, vea la sección titulada Conversión de cadenas a números. Para valores de otros tipos, la conversión es la misma que si el valor hubiese sido convertido a entero y luego a flotante. Vea la sección Conversión a entero para más información.


Cadenas

Un valor string es una serie de caracteres. En PHP, un caracter es lo mismo que un byte, es decir, hay exactamente 256 tipos de caracteres diferentes. Esto implica también que PHP no tiene soporte nativo de Unicode. Vea utf8_encode() y utf8_decode() para conocer sobre el soporte Unicode.

Nota: El que una cadena se haga muy grande no es un problema. PHP no impone límite práctico alguno sobre el tamaño de las cadenas, así que no hay ninguna razón para preocuparse sobre las cadenas largas.


Sintaxis

Un literal de cadena puede especificarse en tres formas diferentes.


Comillas simples

La forma más simple de especificar una cadena sencilla es rodearla de comillas simples (el caracter ').

Para especificar una comilla sencilla literal, necesita escaparla con una barra invertida (\), como en muchos otros lenguajes. Si una barra invertida necesita aparecer antes de una comilla sencilla o al final de la cadena, necesitará doblarla. Note que si intenta escapar cualquier otro caracter, ¡la barra invertida será impresa también! De modo que, por lo general, no hay necesidad de escapar la barra invertida misma.

Nota: En PHP 3, se generará una advertencia de nivel E_NOTICE cuando esto ocurra.

Nota: A diferencia de las otras dos sintaxis, las variables y secuencias de escape para caracteres especiales no serán expandidas cuando ocurren al interior de cadenas entre comillas sencillas.

<?php
echo 'esta es una cadena simple';

echo 'Tambi&eacute;n puede tener saltos de l&iacute;nea embebidos
en las cadenas de esta forma, ya que
es v&aacute;lido';

// Imprime: Arnold dijo una vez: "I'll be back"
echo 'Arnold dijo una vez: "I\'ll be back"';

// Imprime: Ha eliminado C:\*.*?
echo 'Ha eliminado C:\\*.*?';

// Imprime: Ha eliminado C:\*.*?
echo 'Ha eliminado C:\*.*?';

// Imprime: Esto no va a expandirse: \n una nueva linea
echo 'Esto no va a expandirse: \n una nueva linea';

// Imprime: Las variables no se $expanden $tampoco
echo 'Las variables no se $expanden $tampoco';
?>


Comillas dobles

Si la cadena se encuentra rodeada de comillas dobles ("), PHP entiende más secuencias de escape para caracteres especiales:

Tabla 6-1. Caracteres escapados

secuenciasignificado
\nalimentación de línea (LF o 0x0A (10) en ASCII)
\rretorno de carro (CR o 0x0D (13) en ASCII)
\ttabulación horizontal (HT o 0x09 (9) en ASCII)
\\barra invertida
\$signo de dólar
\"comilla-doble
\[0-7]{1,3} la secuencia de caracteres que coincide con la expresión regular es un caracter en notación octal
\x[0-9A-Fa-f]{1,2} la secuencia de caracteres que coincide con la expresión regular es un caracter en notación hexadecimal

Nuevamente, si intenta escapar cualquier otro caracter, ¡la barra invertida será impresa también!

Pero la característica más importante de las cadenas entre comillas dobles es el hecho de que los nombres de variables serán expandidos. Vea procesamiento de cadenas para más detalles.


Heredoc

Otra forma de delimitar cadenas es mediante el uso de la sintaxis heredoc ("<<<"). Debe indicarse un identificador después de la secuencia <<<, luego la cadena, y luego el mismo identificador para cerrar la cita.

El identificador de cierre debe comenzar en la primera columna de la línea. Asimismo, el identificador usado debe seguir las mismas reglas que cualquier otra etiqueta en PHP: debe contener solo caracteres alfanuméricos y de subrayado, y debe iniciar con un caracter no-dígito o de subrayado.

Aviso

Es muy importante notar que la línea con el identificador de cierre no contenga otros caracteres, excepto quizás por un punto-y-coma (;). Esto quiere decir en especial que el identificador no debe usar sangría, y no debe haber espacios o tabuladores antes o después del punto-y-coma. Es importante también notar que el primer caracter antes del identificador de cierre debe ser un salto de línea, tal y como lo defina su sistema operativo. Esto quiere decir \r en Macintosh, por ejemplo.

Si esta regla es rota y el identificador de cierre no es "limpio", entonces no se considera un identificador de cierre y PHP continuará en busca de uno. Si, en tal caso, no se encuentra un identificador de cierre apropiado, entonces un error del analizador sintáctico resultará con el número de línea apuntando al final del script.

El texto heredoc se comporta tal como una cadena entre comillas dobles, sin las comillas dobles. Esto quiere decir que no necesita escapar tales comillas en sus bloques heredoc, pero aun puede usar los códigos de escape listados anteriormente. Las variables son expandidas, aunque debe tenerse el mismo cuidado cuando se expresen variables complejas al interior de un segmento heredoc, al igual que con otras cadenas.

Ejemplo 6-2. Ejemplo de uso de una cadena heredoc

<?php
$cadena = <<<FIN
Ejemplo de una cadena
que se extiende por varias l&iacute;neas
usando la sintaxis heredoc.
FIN;

/* Un ejemplo mas complejo, con variables. */
class foo
{
    var $foo;
    var $bar;

    function foo()
    {
        $this->foo = 'Foo';
        $this->bar = array('Bar1', 'Bar2', 'Bar3');
    }
}

$foo = new foo();
$nombre = 'MiNombre';

echo <<<FIN
Mi nombre es "$nombre". Estoy imprimiendo algo de $foo->foo.
Ahora, estoy imprimiendo algo de {$foo->bar[1]}.
Esto deber&iacute;a imprimir una letra 'A' may&uacute;scula: \x41
FIN;
?>

Nota: El soporte heredoc fue agregado en PHP 4.


Procesamiento de variables

Cuando una cadena es especificada en comillas dobles o al interior de un bloque heredoc, las variables son interpretadas en su interior.

Existen dos tipos de sintaxis: una simple y una compleja. La sintaxis simple es la más común y conveniente. Esta ofrece una forma de interpretar una variable, un valor array, o una propiedad de un object.

La sintaxis compleja fue introducida en PHP 4, y puede reconocerse por las llaves que rodean la expresión.


Sintaxis simple

Si un signo de dólar ($) es encontrado, el analizador sintáctico tomará ambiciosamente tantos lexemas como le sea posible para formar un nombre de variable válido. Rodee el nombre de la variable de llaves si desea especificar explícitamente el final del nombre.

<?php
$cerveza = 'Heineken';
echo "El sabor de varias $cerveza's es excelente"; // funciona, "'" no es un caracter valido para nombres de variables
echo "Tom&oacute; algunas $cervezas";   // no funciona, 's' es un caracter valido para nombres de variables
echo "Tom&oacute; algunas ${cerveza}s"; // funciona
echo "Tom&oacute; algunas {$cerveza}s"; // funciona
?>

De forma similar, puede hacer que un índice de un array o una propiedad de un object sean interpretados. En el caso de los índices de matrices, el corchete cuadrado de cierre (]) marca el final del índice. Para las propiedades de objetos, se aplican las mismas reglas de las variables simples, aunque con las propiedades de objetos no existe un truco como el que existe con las variables.

<?php
// Estos ejemplos son especificos al uso de matrices al interior de
// cadenas. Cuando se encuentre por fuera de una cadena, siempre rodee
// de comillas las claves tipo cadena de su matriz, y no use
// {llaves} por fuera de cadenas tampoco.

// Mostremos todos los errores
error_reporting(E_ALL);

$frutas = array('fresa' => 'roja', 'banano' => 'amarillo');

// Funciona pero note que esto trabaja de forma diferente por fuera de
// cadenas entre comillas
echo "Un banano es $frutas[banano].";

// Funciona
echo "Un banano es {$frutas['banano']}.";

// Funciona, pero PHP musca una constante llamada banano primero, como
// se describe mas adelante.
echo "Un banano es {$frutas[banano]}.";

// No funciona, use llaves. Esto resulta en un error de analisis sintactico.
echo "Un banano es $frutas['banano'].";

// Funciona
echo "Un banano es " . $frutas['banano'] . ".";

// Funciona
echo "Este cuadro tiene $cuadro->ancho metros de ancho.";

// No funciona. Para una solucion, vea la sintaxis compleja.
echo "Este cuadro tiene $cuadro->ancho00 cent&iacute;metros de ancho.";
?>

Para cualquier cosa más sofisticada, debería usarse la sintaxis compleja.


Sintaxis compleja (llaves)

Esta no es llamada compleja porque la sintaxis sea compleja, sino porque es posible incluir expresiones complejas de esta forma.

De hecho, de esta forma puede incluir cualquier valor que sea parte del espacio de nombres al interior de cadenas. Simplemente escriba la expresión en la misma forma que lo haría si se encontrara por fuera de una cadena, y luego la ubica entre { y }. Ya que no es posible escapar '{', esta sintaxis será reconocida únicamente cuando el caracter $ se encuentra inmediatamente después de {. (Use "{\$" o "\{$" para obtener una secuencia literal "{$"). Algunos ejemplos para aclarar el asunto:

<?php
// Mostremos todos los errores
error_reporting(E_ALL);

$genial = 'fant&aacute;stico';

// No funciona, imprime: Esto es { fant&aacute;stico}
echo "Esto es { $genial}";

// Funciona, imprime: Esto es fant&aacute;stico
echo "Esto es {$genial}";
echo "Esto es ${genial}";

// Funciona
echo "Este cuadro tiene {$cuadro->ancho}00 cent&iacute;metros de ancho.";

// Funciona
echo "Esto funciona: {$matriz[4][3]}";

// Esto esta mal por la misma razon por la que $foo[bar] esta mal por
// fuera de una cadena. En otras palabras, aun funciona pero ya que
// PHP busca primero una constante llamada foo, genera un error de
// nivel E_NOTICE (constante indefinida).
echo "Esto esta mal: {$matriz[foo][3]}"; 

// Funciona. Cuando se usan matrices multi-dimensionales, use siempre
// llaves alrededor de las matrices al interior de cadenas
echo "Esto funciona: {$matriz['foo'][3]}";

// Funciona.
echo "Esto funciona: " . $arr['foo'][3];

echo "Puede incluso escribir {$obj->valores[3]->nombre}";

echo "Este es el valor de la variable llamada $nombre: {${$nombre}}";
?>


Acceso a cadenas y modificación por caracter

Los caracteres al interior de una cadena pueden ser consultados y modificados al especificar el desplazamiento, comenzando en cero, del caracter deseado después de la cadena entre llaves.

Nota: Para efectos de compatibilidad con versiones anteriores, aun puede usar corchetes tipo matriz para el mismo propósito. Sin embargo, esta sintaxis es obsoleta a partir de PHP 4.

Ejemplo 6-3. Algunos ejemplos de cadenas

<?php
// Obtener el primer caracter de una cadena
$cadena = 'Esta es una prueba.';
$primer = $cadena{0};

// Obtener el tercer caracter de una cadena
$tercer = $cadena{2};

// Obtener el ultimo caracter de una cadena.
$cadena = 'Esta es tambien una prueba.';
$ultimo = $cadena{strlen($cadena)-1}; 

// Modificar el ultimo caracter de una cadena
$cadena = 'Observe el mar';
$cadena{strlen($cadena)-1} = 'l';
          
?>


Funciones y operadores útiles

Las cadenas pueden ser concatenadas usando el operador '.' (punto). Note que el operador '+' (adición) no funciona para este propósito. Por favor refiérase a la sección Operadores de cadena para más información.

Existen bastantes funciones útiles para la modificación de cadenas.

Vea la sección de funciones de cadena para consultar funciones de uso general, o las funciones de expresiones regulares para búsquedas y reemplazos avanzados (en dos sabores: Perl y POSIX extendido).

Existen también funciones para cadenas tipo URL, y funciones para encriptar/descifrar cadenas (mcrypt y mhash).

Finalmente, si aun no ha encontrado lo que busca, vea también las funciones de tipo de caracter.


Conversión a cadena

Es posible convertir un valor a una cadena usando el moldeamiento (string), o la función strval(). La conversión a cadena se realiza automáticamente para usted en el contexto de una expresión cuando se necesita una cadena. Esto ocurre cuando usa las funciones echo() o print(), o cuando compara el valor de una variable con una cadena. El contenido de las secciones del manual sobre Tipos y Manipulación de Tipos ayudan a aclarar este hecho. Vea también settype().

Un valor boolean TRUE es convertido a la cadena "1", el valor FALSE se representa como "" (una cadena vacía). De esta forma, usted puede convertir de ida y vuelta entre valores booleanos y de cadena.

Un número integer o de punto flotante (float) es convertido a una cadena que representa el número con sus dígitos (incluyendo la parte del exponente para los números de punto flotante).

Las matrices son siempre convertidas a la cadena "Array", de modo que no puede volcar los contenidos de un valor array con echo() o print() para ver lo que se encuentra en su interior. Para ver un elemento, usted tendría que hacer algo como echo $arr['foo']. Vea más adelante algunos consejos sobre el volcado/vista del contenido completo.

Los objetos son convertidos siempre a la cadena "Object". Si quisiera imprimir los valores de variables miembro de un object para efectos de depuración, lea los parágrafos siguientes. Si quiere conocer el nombre de clase del cual un objeto dado es instancia, use get_class().

Los recursos son siempre convertidos a cadenas con la estructura "Resource id #1" en donde 1 es el número único del valor resource asignado por PHP durante tiempo de ejecución. Si quisiera obtener el tipo del recurso, use get_resource_type().

NULL se convierte siempre a una cadena vacía.

Como puede apreciar, el imprimir matrices, objetos o recursos no le ofroce información útil sobre los valores mismos. Consulte las funciones print_r() y var_dump() para conocer mejores formas de imprimir valores para depuración.

También puede convertir valores PHP a cadenas y almacenarlas permanentemente. Este método es conocido como seriación, y puede ser efectuado con la función serialize(). También puede seriar valores PHP a estructuras XML, si cuenta con soporte WDDX en su configuración de PHP.


Conversión de cadenas a números

Cuando una cadena es evaluada como un valor numérico, el valor resultante y su tipo son determinados como sigue.

La cadena será evaluada como un float si contiene cualquier caracter entre '.', 'e', o 'E'. De otra forma, evaluará como un entero.

El valor es dado por la porción inicial de la cadena. Si la cadena comienza con datos numéricos válidos, éstos serán el valor usado. De lo contrario, el valor será 0 (cero). Un signo opcional es considerado un dato numérico válido, seguido por uno o más dígitos (que pueden contener un punto decimal), seguidos por un exponente opcional. El exponente es una 'e' o 'E' seguida de uno o más dígitos.

<?php
$foo = 1 + "10.5";                // $foo es flotante (11.5)
$foo = 1 + "-1.3e3";              // $foo es flotante (-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 = 4 + "10.2 Cerditos";       // $foo es flotante (14.2)
$foo = "10.0 cerdos " + 1;        // $foo es flotante (11)
$foo = "10.0 cerdos " + 1.0;      // $foo es flotante (11)     
?>

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

Si quisiera probar cualquiera de los ejemplos presentados en esta sección, puede cortar y pegar los ejemplos e insertar la siguiente línea para verificar por sí mismo lo que está sucediendo:

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

No espere obtener el código de un caractar convirtiéndolo a un entero (como lo haría en C, por ejemplo). Use las funciones ord() y chr() para convertir entre códigos de caracter y caracteres.


Matrices

Una matriz en PHP es en realidad un mapa ordenado. Un mapa es un tipo de datos que asocia valores con claves. Este tipo es optimizado en varias formas, de modo que puede usarlo como una matriz real, o una lista (vector), tabla asociativa (caso particular de implementación de un mapa), diccionario, colección, pila, cola y probablemente más. Ya que puede tener otra matriz PHP como valor, es realmente fácil simular árboles.

Una explicación sobre tales estructuras de datos se encuentra por fuera del propósito de este manual, pero encontrará al menos un ejemplo de cada uno de ellos. Para más información, le referimos a literatura externa sobre este amplio tema.


Sintaxis

Especificación con array()

Un array puede ser creado por la construcción de lenguaje array(). Ésta toma un cierto número de parejas clave => valor separadas con coma.

array( [clave =>] valor
     , ...
     )
// clave puede ser un integer o string
// valor puede ser cualquier valor

<?php
$matriz = array("foo" => "bar", 12 => true);

echo $matriz["foo"]; // bar
echo $matriz[12];    // 1
?>

Una clave puede ser un integer o un string. Si una clave es la representación estándar de un integer, será interpretada como tal (es decir, "8" será interpretado como 8, mientras que "08" será interpretado como "08"). No existen tipos diferentes para matrices indexadas y asociativas en PHP; sólo existe un tipo de matriz, el cual puede contener índices tipo entero o cadena.

Un valor puede ser de cualquier tipo en PHP.

<?php
$matriz = array("unamatriz" => array(6 => 5, 13 => 9, "a" => 42));

echo $matriz["unamatriz"][6];    // 5
echo $matriz["unamatriz"][13];   // 9
echo $matriz["unamatriz"]["a"];  // 42
?>

Si no especifica una clave para un valor dado, entonces es usado el máximo de los índices enteros, y la nueva clave será ese valor máximo + 1. Si especifica una clave que ya tiene un valor asignado, ése valor será sobrescrito.

<?php
// Esta matriz es la misma que ...
array(5 => 43, 32, 56, "b" => 12);

// ...esta matriz
array(5 => 43, 6 => 32, 7 => 56, "b" => 12);
?>

Aviso

A partir de PHP 4.3.0, el comportamiento de generación de índices descrito ha cambiado. Ahora, si agrega un elemento a una matriz cuya clave máxima actual es un valor negativo, entonces la siguiente clave creada será cero (0). Anteriormente, el nuevo índice hubiera sido establecido a la clave mayor existente + 1, al igual que con los índices positivos.

Al usar TRUE como clave, el valor será evaluado al integer 1. Al usar FALSE como clave, el valor será evaluado al integer 0. Al usar NULL como clave, el valor será evaluado a una cadena vacía. El uso de una cadena vacía como clave creará (o reemplazará) una clave con la cadena vacía y su valor; no es lo mismo que usar corchetes vacíos.

No es posible usar matrices u objetos como claves. Al hacerlo se producirá una advertencia: Illegal offset type.


Creación/modificación con sintaxis de corchetes cuadrados

Es posible modificar una matriz existente al definir valores explícitamente en ella.

Esto es posible al asignar valores a la matriz al mismo tiempo que se especifica la clave entre corchetes. También es posible omitir la clave, agregar una pareja vacía de corchetes ("[]") al nombre de la variable en ese caso.
$matriz[clave] = valor;
$matriz[] = valor;
// clave puede ser un integer o string
// valor puede ser cualquier valor
Si $matriz no existe aun, ésta será creada. De modo que esta es también una forma alternativa de especificar una matriz. Para modificar un cierto valor, simplemente asigne un nuevo valor a un elemento especificado con su clave. Si desea remover una pareja clave/valor, necesita eliminarla mediante unset().

<?php
$matriz = array(5 => 1, 12 => 2);

$matriz[] = 56;    // Esto es igual que $matriz[13] = 56;
                   // en este punto del script

$matriz["x"] = 42; // Esto agrega un nuevo elemento a la
                   // matriz con la clave "x"
                
unset($matriz[5]); // Esto elimina el elemento de la matriz

unset($matriz);    // Esto elimina la matriz completa
?>

Nota: Como se menciona anteriormente, si provee los corchetes sin ninguna clave especificada, entonces se toma el máximo de los índices enteros existentes, y la nueva clave será ese valor máximo + 1. Si no existen índices enteros aun, la clave será 0 (cero). Si especifica una clave que ya tenía un valor asignado, el valor será reemplazado.

Aviso

A partir de PHP 4.3.0, el comportamiento de generación de índices descrito ha cambiado. Ahora, si agrega un elemento al final de una matriz en la que la clave máxima actual es negativa, la siguiente clave creada será cero (0). Anteriormente, el nuevo índice hubiera sido definido como la mayor clave + 1, al igual que ocurre con los índices positivos.

Note que la clave entera máxima usada para este caso no necesita existir actualmente en la matriz. Tan solo debe haber existido en la matriz en algún punto desde que la matriz haya sido re-indexada. El siguiente ejemplo ilustra este caso:

<?php
// Crear una matriz simple.
$matriz = array(1, 2, 3, 4, 5);
print_r($matriz);

// Ahora eliminar cada item, pero dejar la matriz misma intacta:
foreach ($matriz as $i => $valor) {
    unset($matriz[$i]);
}
print_r($matriz);

// Agregar un item (note que la nueva clave es 5, en lugar de 0 como
// podria esperarse).
$matriz[] = 6;
print_r($matriz);

// Re-indexar:
$matriz = array_values($matriz);
$matriz[] = 7;
print_r($matriz);
?>

El anterior ejemplo produciría la siguiente salida:
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)


Funciones útiles

Existe un buen número de funciones útiles para trabajar con matrices. Consulte la sección funciones de matrices.

Nota: La función unset() le permite remover la definición de claves de una matriz. Tenga en cuenta que la matriz NO es re-indexada. Si sólo usa "índices enteros comunes" (comenzando desde cero, incrementando en uno), puede conseguir el efecto de re-indexación usando array_values().

<?php
$a = array(1 => 'uno', 2 => 'dos', 3 => 'tres');
unset($a[2]);
/* producira una matriz que hubiera sido definida como
   $a = array(1 => 'uno', 3 => 'tres');
   y NO
   $a = array(1 => 'uno', 2 =>'tres');
*/

$b = array_values($a);
// Ahora $b es array(0 => 'uno', 1 =>'tres')
?>

La estructura de control foreach existe específicamente para las matrices. Ésta provee una manera fácil de recorrer una matriz.


Recomendaciones sobre matrices y cosas a evitar

¿Porqué es incorrecto $foo[bar]?

Siempre deben usarse comillas alrededor de un índice de matriz tipo cadena literal. Por ejemplo, use $foo['bar'] y no $foo[bar]. ¿Pero qué está mal en $foo[bar]? Es posible que haya visto la siguiente sintaxis en scripts viejos:

<?php
$foo[bar] = 'enemigo';
echo $foo[bar];
// etc
?>

Esto está mal, pero funciona. Entonces, ¿porqué está mal? La razón es que este código tiene una constante indefinida (bar) en lugar de una cadena ('bar' - note las comillas), y puede que en el futuro PHP defina constantes que, desafortunadamente para su código, tengan el mismo nombre. Funciona porque PHP automáticamente convierte una cadena pura (una cadena sin comillas que no corresponda con símbolo conocido alguno) en una cadena que contiene la cadena pura. Por ejemplo, si no se ha definido una constante llamada bar, entonces PHP reemplazará su valor por la cadena 'bar' y usará ésta última.

Nota: Esto no quiere decir que siempre haya que usar comillas en la clave. No querrá usar comillas con claves que sean constantes o variables, ya que en tal caso PHP no podrá interpretar sus valores.

<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('html_errors', false);
// Matriz simple:
$matriz = array(1, 2);
$conteo = count($matriz);
for ($i = 0; $i < $conteo; $i++) {
    echo "\nRevisando $i: \n";
    echo "Mal: " . $matriz['$i'] . "\n";
    echo "Bien: " . $matriz[$i] . "\n";
    echo "Mal: {$matriz['$i']}\n";
    echo "Bien: {$matriz[$i]}\n";
}
?>

Nota: La salida del anterior fragmento es:
Revisando 0: 
Notice: Undefined index:  $i in /path/to/script.html on line 9
Mal: 
Bien: 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Mal: 
Bien: 1

Revisando 1: 
Notice: Undefined index:  $i in /path/to/script.html on line 9
Mal: 
Bien: 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Mal: 
Bien: 2

Más ejemplos para demostrar este hecho:

<?php
// Mostrar todos los errores
error_reporting(E_ALL);

$matriz = array('fruta' => 'manzana', 'vegetal' => 'zanahoria');

// Correcto
print $matriz['fruta'];   // manzana
print $matriz['vegetal']; // zanahoria

// Incorrecto. Esto funciona pero tambi&eacute;n genera un error de PHP de
// nivel E_NOTICE ya que no hay definida una constante llamada fruta
// 
// Notice: Use of undefined constant fruta - assumed 'fruta' in...
print $matriz[fruta];    // manzana

// Definamos una constante para demostrar lo que pasa. Asignaremos el
// valor 'vegetal' a una constante llamada fruta.
define('fruta', 'vegetal');

// Note la diferencia ahora
print $matriz['fruta'];  // manzana
print $matriz[fruta];    // zanahoria

// Lo siguiente esta bien ya que se encuentra al interior de una
// cadena. Las constantes no son procesadas al interior de
// cadenas, asi que no se produce un error E_NOTICE aqui
print "Hola $matriz[fruta]";  // Hola manzana

// Con una excepcion, los corchetes que rodean las matrices al
// interior de cadenas permiten el uso de constantes
print "Hola {$matriz[fruta]}";    // Hola zanahoria
print "Hola {$matriz['fruta']}";  // Hola manzana

// Esto no funciona, resulta en un error de interprete como:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// Esto se aplica tambien al uso de autoglobales en cadenas, por supuesto
print "Hola $matriz['fruta']";
print "Hola $_GET['foo']";

// La concatenacion es otra opcion
print "Hola " . $matriz['fruta']; // Hola manzana
?>

Cuando habilita error_reporting() para mostrar errores de nivel E_NOTICE (como por ejemplo definiendo el valor E_ALL) verá estos errores. Por defecto, error_reporting se encuentra configurado para no mostrarlos.

Tal y como se indica en la sección de sintaxis, debe existir una expresión entre los corchetes cuadrados ('[' y ']'). Eso quiere decir que puede escribir cosas como esta:

<?php
echo $matriz[alguna_funcion($bar)];
?>

Este es un ejemplo del uso de un valor devuelto por una función como índice de matriz. PHP también conoce las constantes, tal y como ha podido apreciar aquellas E_* antes.

<?php
$descripciones_de_error[E_ERROR]   = "Un error fatal ha ocurrido";
$descripciones_de_error[E_WARNING] = "PHP produjo una advertencia";
$descripciones_de_error[E_NOTICE]  = "Esta es una noticia informal";
?>

Note que E_ERROR es también un identificador válido, asi como bar en el primer ejemplo. Pero el último ejemplo es equivalente a escribir:

<?php
$descripciones_de_error[1] = "Un error fatal ha ocurrido";
$descripciones_de_error[2] = "PHP produjo una advertencia";
$descripciones_de_error[8] = "Esta es una noticia informal";
?>

ya que E_ERROR es igual a 1, etc.

Tal y como lo hemos explicado en los anteriores ejemplos, $foo[bar] aun funciona pero está mal. Funciona, porque debido a su sintaxis, se espera que bar sea una expresión constante. Sin embargo, en este caso no existe una constante con el nombre bar. PHP asume ahora que usted quiso decir bar literalmente, como la cadena "bar", pero que olvidó escribir las comillas.


¿Entonces porqué está mal?

En algún momento en el futuro, el equipo de PHP puede querer usar otra constante o palabra clave, o puede que usted introduzca otra constante en su aplicación, y entonces se ve en problemas. Por ejemplo, en este momento no puede usar las palabras empty y default de esta forma, ya que son palabras clave reservadas especiales.

Nota: Reiterando, al interior de un valor string entre comillas dobles, es válido no rodear los índices de matriz con comillas, así que "$foo[bar]" es válido. Consulte los ejemplos anteriores para más detalles sobre el porqué, asi como la sección sobre procesamiento de variables en cadenas.


Conversión a matriz

Para cualquiera de los tipos: integer, float, string, boolean y resource, si convierte un valor a un array, obtiene una matriz con un elemento (con índice 0), el cual es el valor escalar con el que inició.

Si convierte un object a una matriz, obtiene las propiedades (variables miembro) de ese objeto como los elementos de la matriz. Las claves son los nombres de las variables miembro.

Si convierte un valor NULL a matriz, obtiene una matriz vacía.


Comparación

Es posible comparar matrices con array_diff() y mediante operadores de matriz.


Ejemplos

El tipo matriz en PHP es bastante versátil, así que aquí se presentan algunos ejemplos que demuestran el poder completo de las matrices.

<?php
// esto
$a = array( 'color'  => 'rojo',
            'sabor'  => 'dulce',
            'forma'  => 'redonda',
            'nombre' => 'manzana',
                       4        // la clave sera 0
          );

// es completamente equivalente con
$a['color']  = 'rojo';
$a['sabor']  = 'dulce';
$a['forma']  = 'redonda';
$a['nombre'] = 'manzana';
$a[]         = 4;        // la clave sera 0

$b[] = 'a';
$b[] = 'b';
$b[] = 'c';
// resultara en la matriz array(0 => 'a' , 1 => 'b' , 2 => 'c'),
// o simplemente array('a', 'b', 'c')
?>

Ejemplo 6-4. Uso de array()

<?php
// Array como mapa de propiedades
$mapa = array( 'version'          => 4,
               'SO'               => 'Linux',
               'idioma            => 'ingles',
               'etiquetas_cortas' => true
            );
            
// claves estrictamente numericas
$matriz = array( 7,
                 8,
                 0,
                 156,
                 -10
               );
// esto es lo mismo que array(0 => 7, 1 => 8, ...)

$cambios = array(         10, // clave = 0
                  5    =>  6,
                  3    =>  7, 
                  'a'  =>  4,
                          11, // clave = 6 (el indice entero maximo era 5)
                  '8'  =>  2, // clave = 8 (entero!)
                  '02' => 77, // clave = '02'
                  0    => 12  // el valor 10 sera reemplazado por 12
                );
                  
// matriz vacia
$vacio = array();         
?>

Ejemplo 6-5. Colección

<?php
$colores = array('rojo', 'azul', 'verde', 'amarillo');

foreach ($colores as $color) {
    echo "&iquest;Le gusta el $color?\n";
}

?>

Esto producirá la salida:

&iquest;Le gusta el rojo?
&iquest;Le gusta el azul?
&iquest;Le gusta el verde?
&iquest;Le gusta el amarillo?

Note que actualmente no es posible cambiar los valores de la matriz directamente en un ciclo de ese tipo. Una solución parcial es la siguiente:

Ejemplo 6-6. Colección

<?php
foreach ($colores as $clave => $color) {
    // no funciona:
    //$color = strtoupper($color);
    
    // funciona:
    $colores[$clave] = strtoupper($color);
}
print_r($colores);
?>

Esto genera la salida:

Array
(
    [0] => ROJO
    [1] => AZUL
    [2] => VERDE
    [3] => AMARILLO
)

Este ejemplo crea una matriz con base uno.

Ejemplo 6-7. Índice con base 1

<?php
$primercuarto  = array(1 => 'Enero', 'Febrero', 'Marzo');
print_r($primercuarto);
?>

Esto imprime:

Array 
(
    [1] => 'Enero'
    [2] => 'Febrero'
    [3] => 'Marzo'
)

Ejemplo 6-8. Llenado de una matriz

<?php
// llenar una matriz con todos los items de un directorio
$gestor = opendir('.');
while (false !== ($archivo = readdir($gestor))) {
    $archivos[] = $archivo;
}
closedir($gestor); 
?>

Las matrices son ordenadas. Puede también cambiar el orden usando varias funciones de ordenamiento. Vea la sección sobre funciones de matrices para más información. Puede contar el número de items en una matriz usando la función count().

Ejemplo 6-9. Ordenamiento de una matriz

<?php
sort($archivos);
print_r($archivos);
?>

Dado que el valor de una matriz puede ser cualquier cosa, también puede ser otra matriz. De esta forma es posible crear matrices recursivas y multi-dimensionales.

Ejemplo 6-10. Matrices recursivas y multi-dimensionales

<?php
$frutas = array ( "frutas"  => array ( "a" => "naranja",
                                       "b" => "banano",
                                       "c" => "manzana"
                                     ),
                  "numeros" => array ( 1,
                                       2,
                                       3,
                                       4,
                                       5,
                                       6
                                     ),
                  "hoyos"   => array (      "primero",
                                       5 => "segundo",
                                            "tercero"
                                     )
                );

// Algunos ejemplos que hacen referencia a los valores de la matriz anterior
echo $frutas["hoyos"][5];    // imprime "segundo"
echo $frutas["frutas"]["a"]; // imprime "naranja"
unset($frutas["hoyos"][0]);  // elimina "primero"

// Crear una nueva matriz multi-dimensional
$jugos["manzana"]["verde"] = "bien";
?>

Debe advertir que la asignación de matrices siempre involucra la copia de valores. Necesita usar el operador de referencia para copiar una matriz por referencia.

<?php
$matriz1 = array(2, 3);
$matriz2 = $matriz1;
$matriz2[] = 4; // $matriz2 cambia,
                // $matriz1 sigue siendo array(2, 3)
             
$matriz3 = &$matriz1;
$matriz3[] = 4; // ahora $matriz1 y $matriz3 son iguales
?>


Objetos

Inicialización de Objetos

Para inicializar un objeto, use la sentencia new, lo que instancia el objeto a una variable.

<?php
class foo
{
    function hacer_foo()
    {
        echo "Haciendo foo."; 
    }
}

$bar = new foo;
$bar->hacer_foo();
?>

Para una discusión completa, por favor refiérase a la sección Clases y Objetos.


Conversión a objeto

Si un objeto es convertido a un objeto, éste no es modificado. Si un valor de cualquier otro tipo es convertido a objeto, una nueva instancia de la clase stdClass es creada. Si el valor era nulo, la nueva instancia será vacía. Para cualquier otro valor, una variable miembro llamada scalar contendrá el valor.

<?php
$obj = (object) 'ciao';
echo $obj->scalar;  // imprime 'ciao'
?>


Recurso

Un recurso es una variable especial, que contiene una referencia a un recurso externo. Los recursos son creados y usados por funciones especiales. Vea el apéndice para un listado de todas estas funciones y los tipos de recurso correspondientes.

Nota: El tipo recurso fue introducido en PHP 4


Conversión a un recurso

Dado que los tipos de recurso contienen gestores especiales a archivos abiertos, conexiones con bases de datos, áreas de pintura de imágenes y cosas por el estilo, no es posible convertir cualquier valor a un recurso.


Liberación de recursos

Gracias al sistema de conteo de referencias introducido con el Motor Zend de PHP 4, se detecta automáticamente cuando un recurso ya no es referenciado (tal como en Java). Cuando este es el caso, todos los recursos que fueron usados para éste recurso se liberan por el recolector de basura. Por esta razón, rara vez se necesita liberar la memoria manualmente mediante el uso de alguna función free_result.

Nota: Los enlaces persistentes con bases de datos son especiales, ellos no son destruidos por el recolector de basura. Vea también la sección sobre conexiones persistentes.


NULL

El valor especial NULL representa que una variable no tiene valor. NULL es el único valor posible del tipo NULL.

Nota: El tipo null se introdujo en PHP 4

Una variable es considerada como NULL si

  • se ha asignado la constante NULL a la variable.

  • no ha sido definida con valor alguno.

  • ha sido eliminada con unset().


Sintaxis

Existe un solo valor de tipo NULL, y ese es la palabra clave NULL, insensible a mayúsculas y minúsculas.

<?php
$var = NULL;       
?>

Vea también is_null() y unset().


Pseudo-tipos usados en esta documentación

mixed

mixed indica que un parámetro puede aceptar múltiples tipos (pero no necesariamente todos).

gettype() por ejemplo aceptará todos los tipos PHP, mientras que str_replace() aceptará cadenas y matrices.


number

number indica que un parámetro puede ser integer o float.


callback

Algunas funciones como call_user_func() o usort() aceptan llamadas de retorno definidas por el usuario como un parámetro. Las funciones tipo llamada de retorno no sólo pueden ser funciones simples, también pueden ser métodos de objetos incluyendo métodos estáticos de clase.

Una función de PHP es simplemente pasada usando su nombre como una cadena. Puede pasar cualquier función incorporada o definida por el usuario con la excepción de array(), echo(), empty(), eval(), exit(), isset(), list(), print() y unset().

Un método de un objeto instanciado es pasado como una matriz que contiene un objeto como el elemento con el índice 0 y un nombre de método como el elemento con índice 1.

Los métodos estáticos de clase pueden ser pasados también sin instanciar un objeto de esa clase al pasar el nombre de clase en lugar de un objeto como el elemento con índice 0.

Ejemplo 6-11. Ejemplos de funciones tipo llamada de retorno

<?php 

// ejemplo simple de una llamada de retorno
function mi_llamada_de_retorno() {
    echo '&iexcl;Hola mundo!';
}
call_user_func('mi_llamada_de_retorno');

// ejemplos de un m&eacute;todo como llamada de retorno
class MiClase {
    function miMetodoDeRetorno() {
        echo '&iexcl;Hola Mundo!';
    }
}

// llamada de metodo estatico de clase sin instanciar un objeto
call_user_func(array('MiClase', 'miMetodoDeRetorno'));

// llamada a un metodo de objeto
$obj = new MiClase();
call_user_func(array(&$obj, 'miMetodoDeRetorno'));
?>


Manipulación de Tipos

PHP no requiere (o soporta) la definición explícita de tipos en la declaración de variables; el tipo de una variable es determinado por el contexto en el que la variable es usada. Lo que quiere decir que si asigna un valor de cadena a la variable $var, $var se convierte en una cadena. Si luego asigna un valor entero a $var, ésta se convierte en entera.

Un ejemplo de la conversión automática de tipos de PHP es el operador de adición '+'. Si cualquiera de los operandos es un flotante, entonces todos los operandos son evaluados como flotantes, y el resultado será un flotante. De otro modo, los operandos serán interpretados como enteros, y el resultado será también un entero. Note que este NO modifica los tipos de los operandos mismos; el único cambio está en la forma como los operandos son evaluados.

<?php
$foo = "0";  // $foo es una cadena (ASCII 48)
$foo += 2;   // $foo es ahora un entero (2)
$foo = $foo + 1.3;  // $foo es ahora un flotante (3.3)
$foo = 5 + "10 Cerditos"; // $foo es entero (15)
$foo = 5 + "10 Cerdos";   // $foo es entero (15)
?>

Si los dos últimos ejemplos lucen extraños, consulte Conversión de cadenas a números.

Si desea forzar que una variable sea evaluada como un cierto tipo, consulte la sección sobre Moldeamiento de tipos. Si desea cambiar el tipo de una variable, vea settype().

Si quisiera probar cualquiera de los ejemplos en esta sección, puede usar la función var_dump().

Nota: El comportamiento de una conversión automática a matriz no se encuentra definido en el momento.

<?php
$a = "1";     // $a es una cadena
$a[0] = "f";  // Que hay de las posiciones de cadena? Que sucede?
?>

Ya que PHP (por razones históricas) soporta el uso de índices en cadenas mediante desplazamientos de posición usando la misma sintaxis que la indexación de matrices, el ejemplo anterior lleva a un problema: ¿debería $a convertirse en una matriz con un primer elemento "f", o debería "f" convertirse en el primer caracter de la cadena $a?

Las versiones recientes de PHP interpretan la segunda asignación como una identificación de desplazamiento de cadena, así que $a se convierte en "f", sin embargo el resultado de esta conversión automática debe considerarse indefinido. PHP 4 introdujo la nueva sintaxis de llaves para acceder a los caracteres de una cadena, use esta sintaxis en lugar de la que fue presentada anteriormente:

<?php
$a    = "abc"; // $a es una cadena
$a{1} = "f";   // $a es ahora "afc"
?>

Vea la sección llamada Acceso a cadenas por caracter para más información.


Moldeamiento de Tipos

El moldeamiento de tipos en PHP funciona de forma muy similar a como ocurre en C: el nombre del tipo deseado es escrito entre paréntesis antes de la variable que debe ser moldeada.

<?php
$foo = 10;   // $foo es un entero
$bar = (boolean) $foo;   // $bar es un booleano
?>

Los moldeamiontos permitidos son:

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

  • (bool), (boolean) - moldeamiento a booleano

  • (float), (double), (real) - moldeamiento a flotante

  • (string) - moldeamiento a cadena

  • (array) - moldeamiento a matriz

  • (object) - moldeamiento a objeto

Note que las tabulaciones y los espacios son permitidos al interior de los paréntesis, así que las siguientes expresiones son funcionalmente equivalentes:

<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>

Nota: En lugar de moldear una variable a cadena, puede también rodear la variable de comillas dobles.

<?php
$foo = 10;            // $foo es un entero
$cad = "$foo";        // $cad es una cadena
$fst = (string) $foo; // $fst es tambien una cadena

// Esto imprime "son lo mismo"
if ($fst === $cad) {
    echo "son lo mismo";
}
?>

Puede que no sea obvio qué sucede exactamente cuando se moldea entre ciertos tipos. Para más información, consulte las secciones:


Capítulo 7. 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.

Los nombres de variables siguen las mismas reglas que otras etiquetas en PHP. Un nombre de variable valido tiene que empezar con una letra o una raya (underscore), seguido de cualquier número de letras, números y rayas. Como expresión regular se podria expresar como: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'

Nota: En nuestro caso, una letra es a-z, A-Z, y los caracteres ASCII del 127 al 255 (0x7f-0xff).

<?php
$var = "Bob";
$Var = "Joe";
echo "$var, $Var";      // outputs "Bob, Joe"

$4site = 'not yet';     // invalid; starts with a number
$_4site = 'not yet';    // valid; starts with an underscore
$täyte = 'mansikka';    // valid; 'ä' is ASCII 228 (Extendido)
?>

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" ó "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 matrices u objetos.

Para asignar por referencia, simplemente se antepone un ampersandsigno "&" 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 = &amp;$foo;              // Referencia $foo v&iacute;a $bar.
$bar = "Mi nombre es $bar";  // Modifica $bar...
echo $foo;                 // $foo tambi&eacute;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 = &amp;$foo;      // Esta es una asignaci&oacute;n v&aacute;lida.
$bar = &amp;(24 * 7);  // Inv&aacute;lida; referencia una expresi&oacute;n sin nombre.

function test() {
   return 25;
}

$bar = &amp;test();    // Inv&aacute;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.Para obtener una lista de estas variables podeis consultar la sección Variables predefinidas reservadas.

Aviso

A partir de PHP 4.2.0, el valor por defecto de la directiva PHP register_globals es off (desactivada). Este es un cambio importante en PHP. Teniendo register_globals off afecta el conjunto de variables predefinidas disponibles en el sistema. Por ejemplo, para obtener DOCUMENT_ROOT se usará $_SERVER['DOCUMENT_ROOT'] en vez de $DOCUMENT_ROOT ó $_GET['id'] de la URL http://www.example.com/test.php?id=3 en vez de $id ó $_ENV['HOME'] en vez de $HOME.

Para más información sobre este cambio, podeis consultar el apartado de configuración sobre register_globals, el capítulo sobre seguridad Usando "Register Globals" , asi como los anuncios de lanzamiento de PHP 4.1.0 y 4.2.0

El uso de las variables reservadas predefinidas en PHP, como matrices superglobales es recomendable.

A partir de PHP 4.1.0, PHP ofrece un conjunto adicional de matrices predefinidas, conteniendo variables del servidor web, el entorno y entradas del usuario. Estas nuevas matrices son un poco especiales porque son automáticamente globales. Por esta razón, son conocidas a menudo como "autoglobales" ó "superglobales". Las superglobales se mencionan más abajo; sin embargo para una lista de sus contenidos y más información sobre variables predefinidas en PHP, consultar la sección Variables predefinidas reservadas. Podreis ver como las variables predefinidas antiguas ($HTTP_*_VARS) todavía existen. A partir de PHP 5.0.0, las matrices de tipo "long" de variables predefinidas, se pueden desactivar con la directiva register_long_arrays.

Variables variables: Las superglobales no pueden usarse como variables variables.

Si ciertas variables no son definidas en variables_order, las matrices PHP predefinidas asociadas a estas, estarán vacias.

PHP superglobales

$GLOBALS

Contiene una referencia a cada variable disponible en el espectro de las variables del script. Las llaves de esta matriz son los nombres de las variables globales. $GLOBALS existe dese PHP 3.

$_SERVER

Variables definidas por el servidor web ó directamente relacionadas con el entorno en don el script se esta ejecutando. Análoga a la antigua matriz $HTTP_SERVER_VARS (la cual está todavía disponible, aunque no se use).

$_GET

Variables proporcionadas al script por medio de HTTP GET. Análoga a la antigua matriz $HTTP_GET_VARS (la cual está todavía disponible, aunque no se use).

$_POST

Variables proporcionadas al script por medio de HTTP POST. Análoga a la antigua matriz $HTTP_POST_VARS (la cual está todavía disponible, aunque no se use).

$_COOKIE

Variables proporcionadas al script por medio de HTTP cookies. Análoga a la antigua matriz $HTTP_COOKIE_VARS (la cual está todavía disponible, aunque no se use).

$_FILES

Variables proporcionadas al script por medio de la subida de ficheros via HTTP . Análoga a la antigua matriz $HTTP_POST_FILES (la cual está todavía disponible, aunque no se use). Vea también Subiendo ficheros por método POST para más información.

$_ENV

Variables proporcionadas al script por medio del entorno. Análoga a la antigua matriz $HTTP_ENV_VARS (la cual está todavía disponible, aunque no se use).

$_REQUEST

Variables proporcionadas al script por medio de cuaquier mecanismo de entrada del usuario y por lo tanto no se puede confiar en ellas. La presencia y el orden en que aparecen las variables en esta matriz es definido por la directiva de configuración variables_order. Esta matriz no tiene un análogo en versiones anteriores a PHP 4.1.0. Vea también import_request_variables().

Nota: Cuando se utiliza la linea de comandos, argv y argc no son incluidas aquí; estas variables se podrán encontrar en la matriz

$_SESSION

Variables registradas en la sesión del script. Análoga a la antigua matriz $HTTP_SESSION_VARS (la cual está todavía disponible, aunque no se use). Vea también la sección Funciones para el manejo de sessiones para más información.


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:

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

<?php
$a = 1; /* global scope */ 

function Test()
{ 
    echo $a; /* reference to local scope variable */ 
} 

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:

<?php
$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 la matriz $GLOBALS. El ejemplo anterior se puede reescribir así:

<?php
$a = 1;
$b = 2;

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

Sum();
echo $b;
?>

La matriz $GLOBALS es una matriz asociativa con el nombre de la variable global como clave y los contenidos de dicha variable como el valor del elemento de la matriz. $GLOBALS existe en cualquier ámbito, esto pasa porque $GLOBALS es una superglobal. Aqui teneis un ejemplo que demuestra el poder de las superglobales:

<?php
function test_global()
{
    // Most predefined variables aren't "super" and require 
    // 'global' to be available to the functions local scope.
    global $HTTP_POST_VARS;
    
    print $HTTP_POST_VARS['name'];
    
    // Superglobals are available in any scope and do 
    // not require 'global'.  Superglobals are available 
    // as of PHP 4.1.0
    print $_POST['name'];
}
?>

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:

<?php
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:

<?php
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:

<?php
function Test()
{
    static $count = 0;

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

En motor Zend 1, utilizado por PHP4, implementa los modificadores static y global para variables en términos de referencias. Por ejemplo, una variable global verdadera importada dentro del ámbito de una función con global, crea una referencia a la variable global. Esto puede ser causa de un comportamiento inesperado, tal y como podemos comprobar en el siguiente ejemplo:

<?php
function test_global_ref() {
    global $obj;
    $obj = &new stdclass;
}

function test_global_noref() {
    global $obj;
    $obj = new stdclass;
}

test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>

Al ejecutar este ejemplo obtendremos la siguiente salida:

NULL
object(stdClass)(0) {
}

Un comportamiento similar se aplica a static. Referencias no son guardadas estáticamente.

<?php
function &get_instance_ref() {
    static $obj;

    echo "Static object: ";
    var_dump($obj);
    if (!isset($obj)) {
        // Assign a reference to the static variable
        $obj = &new stdclass;
    }
    $obj->property++;
    return $obj;
}

function &get_instance_noref() {
    static $obj;

    echo "Static object: ";
    var_dump($obj);
    if (!isset($obj)) {
        // Assign the object to the static variable
        $obj = new stdclass;
    }
    $obj->property++;
    return $obj;
}

$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>

Al ejecutar este ejemplo obtendremos la siguiente salida:

Static object: NULL
Static object: NULL

Static object: NULL
Static object: object(stdClass)(1) {
  ["property"]=>
  int(1)
}

Este ejemplo demuestra que al asignar una referencia a una variable estática, esta no es recordada cuando se invoca la funcion &get_instance_ref() por segunda vez.


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:

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

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

<?php
echo "$a ${$a}";
?>

produce el mismo resultado que:

<?php
echo "$a $hello";
?>

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

Para usar variables variables con matrices, 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 ambigüedad es: ${$a[1]} para el primer caso y ${$a}[1] para el segundo.

Aviso

Tener en cuenta que variables variables no pueden usarse con Matrices superglobales. Esto significa que no se pueden hacer cosas como ${$_GET}. Si buscais un método para manejar la disponibilidad de superglobales y las antiguas HTTP_*_VARS, podeis intentar referiros a ellas.


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 7-1. Variables de formulario simples

<form action="foo.php" method="POST">
    Name:  <input type="text" name="username"><br>
    Email: <input type="text" name="email"><br>
    <input type="submit" name="submit" value="Submit me!">
</form>

Dependiendo de tu configuración y preferencias personales, existen muchas maneras de acceder a los datos de tus formularios HTML. Algunos ejemplos:

Ejemplo 7-2. Accediendo datos de un formulario simple HTML POST

<?php 
// Available since PHP 4.1.0

   print $_POST['username'];
   print $_REQUEST['username'];

   import_request_variables('p', 'p_');
   print $p_username;

// Available since PHP 3.  As of PHP 5.0.0, these long predefined
// variables can be disabled with the register_long_arrays directive.

   print $HTTP_POST_VARS['username'];

// Available if the PHP directive register_globals = on.  As of 
// PHP 4.2.0 the default value of register_globals = off.
// Using/relying on this method is not preferred.

   print $username;
?>

Usando un formulario GET es similar excepto en el uso de variables predefinidas, que en este caso serán del tipo GET. GET también se usa con QUERY_STRING (la información despues del símbolo '?' en una URL). Por ejemplo http://www.example.com/test.php?id=3 contiene datos GET que son accesibles con $_GET['id']. Vea también $_REQUEST y import_request_variables().

Nota: Matrices superglobales, como $_POST y$_GET, están disponibles desde PHP 4.1.0.

Como hemos dicho, antes de PHP 4.2.0, el valor por defecto de register_globals era on (activado). Y, en PHP 3 estba siempre activado. La comunidad PHP anima a no confiar en esta directiva ya que es preferible asumir que tiene el valor off (desactivada) y programar teniendo en cuenta esto.

Nota: La directiva de configuración magic_quotes_gpc afecta a valores Get, Post y Cookie, Si esta activada (on) el valor (It's "PHP!") sera convertido automaticamente a (It\'s \"PHP!\"). "Escaping" es necesario en inserciones a bases de datos. Vea también addslashes(), stripslashes() y magic_quotes_sybase.

PHP tambien entiende matrices en el contexto de variables de formularios. (vea la faq relacionada). Se puede, por ejemplo, agrupar juntas variables relacionadas ó usar esta característica para obtener valores de una entrada "select2 múltiple. Por ejemplo, vamos a mandar un formulario asi mismo y a presentar los datos cuando se reciban:

Ejemplo 7-3. Variables de formulario más complejas

<?php
if ($HTTP_POST_VARS['action'] == 'submitted') {
    print '<pre>';

    print_r($HTTP_POST_VARS);
    print '<a href="'. $HTTP_SERVER_VARS['PHP_SELF'] .'">Please try again</a>';

    print '</pre>';
} else {
?>
<form action="<?php echo $HTTP_SERVER_VARS['PHP_SELF']; ?>" 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>
        <option value="guinness">Guinness</option>
        <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
    </select><br>
    <input type="hidden" name="action" value="submitted">
    <input type="submit" name="submit" value="submit me!">
</form>
<?php
}
?>

en PHP 3, el uso de matrices de variables de formularios está limitado a matrices unidimensionales. En PHP 4, no existe esta restricción.


IMAGE SUBMIT variable names

Cuando mandamos un formulario, es posible usar una imagen en vez del botón estandar de "mandar":

<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(). Los datos de una cookie estan disponibles en la matriz con datos de cookies apropiada, tal como $_COOKIE, $HTTP_COOKIE_VARS y también en $_REQUEST. vea la función setcookie() para más detalles y ejemplos.

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

<?php
  setcookie("MyCookie[foo]", "Testing 1", time()+3600);
  setcookie("MyCookie[bar]", "Testing 2", time()+3600);
?>

Esto creara dos cookies separadas aunque MyCookie será una matriz simple en el script. Si se quiere definir una sola cookie con valores multiples, considerar primero el uso de la función serialize() ó explode() en el valor.

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 7-4. Ejemplo SetCookie

<?php
$count++;
setcookie("count", $count, time()+3600);
setcookie("Cart[$count]", $item, time()+3600);
?>

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:
<?php
$varname.ext;  /* nombre de variable invalido */
?>
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 lo 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: gettype(), is_array(), is_float(), is_int(), is_object(), y is_string(). Vea también el capítulo sobre Tipos.


Capítulo 8. 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 8-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 9. 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 ó, 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, se espera que el valor de $a sea 5 también, de manera que si escribes $b = $a, se espera también 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:

<?php
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 VERDADERO (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 7), etc.

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

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

<?php
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&eacute;s
                       del incremento, 2*7 = 14 a $g */
$h = $g += 10;      /* primero, $g es incrementado en 10 y termina valiendo 24.
                       despu&eacute;s el valor de la asignaci&oacute;n (24) se asigna a $h, 
                       y $h tambi&eacute;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 TRUE ó FALSE Las constantes TRUE y FALSE son los dos posibles valores booleanos. Cuando es necesario, una expresión se puede transformar automáticamente al tipo booleano. Consultar la sección sobre type-casting para obtener detalles de como se hace.

PHP brinda una completa y potente implementación de expresiones, y documentarla enteramente está más allá del objetivo de este 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 10. Operadores

Un operador es algo a lo que usted entrega uno o más valores (o expresiones, en jerga de programación) y produce otro valor (de modo que la construcción misma se convierte en una expresión). Así que puede pensar sobre las funciones o construcciones que devuelven un valor (como print) como operadores, y en aquellas que no devuelven nada (como echo) como cualquier otra cosa.

Existen tres tipos de operadores. En primer lugar se encuentra el operador unario, el cual opera sobre un único valor, por ejemplo ! (el operador de negación) o ++ (el operador de incremento). El segundo grupo se conoce como operadores binarios; éste grupo contiene la mayoría de operadores que soporta PHP, y una lista se encuentra disponible más adelante en la sección Precedencia de Operadores.

El tercer grupo consiste del operador ternario: ?:. Éste debe ser usado para seleccionar entre dos expresiones, en base a una tercera, en lugar de seleccionar dos sentencias o rutas de ejecución. Rodear las expresiones ternarias con paréntesis es una muy buena idea.


Precedencia de Operadores

La precedencia de un operador indica qué tan "cerca" se agrupan dos expresiones. Por ejemplo, en la expresión 1 + 5 * 3, la respuesta es 16 y no 18, ya que el operador de multiplicación ("*") tiene una mayor precedencia que el operador de adición ("+"). Los paréntesis pueden ser usados para marcar la precedencia, si resulta necesario. Por ejemplo: (1 + 5) * 3 evalúa a 18. Si la precedencia de los operadores es la misma, se utiliza una asociación de izquierda a derecha.

La siguiente tabla lista la precedencia de los operadores, con aquellos de mayor precedencia listados de primeros.

Tabla 10-1. Precedencia de Operadores

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

Nota: Aunque ! tiene una mayor precedencia que =, PHP permitirá aun expresionas similares a la siguiente: if (!$a = foo()), en cuyo caso la salida de foo() va a dar a $a.


Operadores de Aritmética

¿Recuerda la aritmética básica del colegio? Éstos operadores funcionan tal como aquéllos.

Tabla 10-2. Operadores de Aritmética

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

El operador de división ("/") devuelve un valor flotante en todos los casos, incluso si los dos operandos son enteros (o cadenas que son convertidas a enteros).

Vea también la página del manual sobre Funciones matemáticas.


Operadores de Asignación

El operador básico de asignación es "=". A primera vista, usted podría pensar en él como "es igual a". No lo haga. Lo que quiere decir en realidad es que el operando de la izquierda recibe el valor de la expresión a la derecha (es decir, "se define a").

El valor de una expresión de asignación es el valor que se asigna. Es decir, el valor de "$a = 3" es 3. Esto le permite hacer una que otra cosa curiosa:

<?php

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

?>

En conjunto con el operador básico de asignación, existen "operadores combinados" para todas las operaciones de aritmética binaria y de cadenas, que le permiten usar un valor en una expresión y luego definir su valor como el resultado de esa expresión. Por ejemplo:

<?php

$a = 3;
$a += 5; // define $a como 8, como si hubiesemos dicho: $a = $a + 5;
$b = "&iexcl;Hola ";
$b .= "a todos!"; // define $b como "&iexcl;Hola a todos!", tal como $b = $b . "a todos!";

?>

Note que la asignación copia la variable original en la nueva (asignación por valor), de modo que cualquier cambio a una no afecta a la otra. Esto puede resultar de importancia si necesita copiar algo como una matriz de gran tamaño al interior de un ciclo reducido. PHP4 soporta la asignación por referencia, usando la sintaxis $var = &$otra_var;, pero esto no es posible en PHP3. 'Asignación por referencia' quiere decir que ambas variables terminan apuntando a los mismos datos y que nada es realmente copiado. Para aprender más sobre las referencias, por favor refiérase a las Referencias explicadas.


Operadores Bit a Bit

Los operadores bit a bit le permiten activar o desactivar bits individuales de un entero. Si los parámetros tanto a la izquierda y a la derecha son cadenas, el operador bit a bit trabajará sobre los valores ASCII de los caracteres.

<?php
echo 12 ^ 9; // Imprime '5'

echo "12" ^ "9"; // Imprime el caracter Backspace (ascii 8)
                 // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

echo "hallo" ^ "hello"; // Imprime los valores ascii #0 #4 #0 #0 #0
                        // 'a' ^ 'e' = #4
?>

Tabla 10-3. Operadores Bit a Bit

EjemploNombreResultado
$a & $bYLos bits que están activos tanto en $a como en $b son activados.
$a | $bOLos bits que están activos ya sea en $a o en $b son activados.
$a ^ $bO exclusivo (Xor) Los bitos que estén activos en $a o $b, pero no en ambos, son activados.
~ $aNo Los bits que estén activos en $a son desactivados, y vice-versa.
$a << $bDesplazamiento a izquierda Desplaza los bits de $a, $b pasos a la izquierda (cada paso quiere decir "multiplicar por dos")
$a >> $bDesplazamiento a derecha Desplaza los bits de $a, $b pasos a la derecha (cada paso quiere decir "dividir por dos")

Operadores de Comparación

Los operadores de comparación, como su nombre indica, le permiten comparar dos valores. Puede que también se encuentre interesado en consultar las tablas de comparación de tipos, ya que éstas muestran ejemplos de varios tipos de comparaciones relacionadas con tipos.

Tabla 10-4. Operadores de Comparación

EjemploNombreResultado
$a == $bIgualTRUE si $a es igual a $b.
$a === $bIdéntico TRUE si $a es igual a $b, y son del mismo tipo. (Sólo en PHP 4)
$a != $bDiferenteTRUE si $a no es igual a $b.
$a <> $bDiferenteTRUE si $a no es igual a $b.
$a !== $bNo idénticos TRUE si $a no es igual a $b, o si no son del mismo tipo. (Sólo en PHP 4)
$a < $bMenor queTRUE si $a es escrictamente menor que $b.
$a > $bMayor queTRUE si $a es estrictamente mayor que $b.
$a <= $bMenor o igual queTRUE si $a es menor o igual que $b.
$a >= $bMayor o igual queTRUE si $a es mayor o igual que $b.

Otro operador condicional es el operador "?:" (o ternario).

<?php
// Ejemplo de uso de: el Operador Ternario
$accion = (empty($_POST['accion'])) ? 'predeterminada' : $_POST['accion'];

// La sentencia anterior es identica a este bloque if/else
if (empty($_POST['accion'])) {
    $accion = 'predeterminada';
} else {
    $accion = $_POST['accion'];
}
?>

La expresión (expr1) ? (expr2) : (expr3) evalúa a expr2 si expr1 evalúa a TRUE, y expr3 si expr1 evalúa a FALSE.

Vea también strcasecmp(), strcmp(), Operadores de matriz, y la sección del manual sobre Tipos.


Operadores de Control de Errores

PHP ofrece soporte para un operador de control de errores: el signo de arroba (@). Cuando es colocado al comienzo de una expresión en PHP, cualquier mensaje de error que pudiera generarse a causa de esa expresión será ignorado.

Si la característica track_errors está habilitada, cualquier mensaje de error generado por la expresión será almacenado en la variable $php_errormsg. La variable será sobrescrita en cada instancia de error, así que realice sus chequeos de forma temprana si quiere usarla.

<?php
/* Error intencional de archivo */
$mi_archivo = @file ('archivo_que_no_existe') or
    die ("La apertura de archivo ha fallado: el error fue '$php_errormsg'");

// esto funciona con cualquier expresion, no solo con funciones:
$valor = @$cache[$llave];
// no producira una anotacion si el indice $llave no existe.

?>

Nota: El operador @ trabaja sólo sobre expresiones. Una simple regla de oro es: si usted puede tomar el valor de algo, entonces puede usar el operador @ sobre ese algo. Por ejemplo, puede usarlo al inicio de variables, llamadas a funciones y sencencias include(), constantes, y así sucesivamente. No puede usarlo sobre definiciones de función o clase, ni sobre estructuras condicionales como if y foreach, y así sucesivamente.

Vea también error_reporting() y la sección del manual sobre funciones de Gestión de Errores y Registros.

Nota: El operador de prefijo "@" para control de errores no deshabilitará los mensajes que son resultado de errores en la fase de análisis sintáctico.

Aviso

En la actualidad, el operador de prefijo "@" para control de errores deshabilitará incluso el reporte de errores en casos de fallos críticos que terminarán la ejecución del script. Entre otras cosas, esto quiere decir que si usa "@" para eliminar los errores de una cierta función, y ésta no se encuentra disponible o ha sido escrita de forma incorrecta, el script se detendrá en ese punto sin dar indicación alguna del motivo.


Operadores de ejecución

PHP soporta un operador de ejecución: las comillas invertidas (``). ¡Note que no se trata de comillas sencillas! PHP intentará ejecutar el contenido entre las comillas como si se tratara de un comando del intérprete de comandos; su salida será devuelta (es decir, no será simplemente volcada como salida; puede ser asignada a una variable). El uso del operador de comillas invertidas es idéntico al de shell_exec().

<?php
$salida = `ls -al`;
echo "<pre>$salida</pre>";
?>

Nota: El operador de comillas invertidas es deshabilitado cuando se encuentra activo safe mode o cuando se deshabilita shell_exec().

Vea también la sección del manual sobre funciones de Ejecución de Programas, popen() proc_open(), y Uso de PHP desde la línea de comandos.


Operadores de Incremento/Decremento

PHP ofrece soporte de operadores de pre- y post-incremento y decremento, estilo-C.

Tabla 10-5. Operadores de Incremento/decremento

EjemploNombreEfecto
++$aPre-incrementoIncrementa $a en uno, y luego devuelve $a.
$a++Post-incrementoDevuelve $a, y luego incrementa $a en uno.
--$aPre-decrementoDecrementa $a en uno, luego devuelve $a.
$a--Post-decrementoDevuelve $a, luego decrementa $a en uno.

Aquí hay un script sencillo de ejemplo:

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

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

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

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

PHP sigue la convención de Perl cuando trabaja con operaciones aritméticas sobre variables de caracter, y no la convención de C. Por ejemplo, en Perl 'Z'+1 se convierte en 'AA', mientras que en C 'Z'+1 se convierte en '[' ( ord('Z') == 90, ord('[') == 91 ). Note que las variables de caracter pueden ser incrementadas pero no decrementadas.

Ejemplo 10-1. Operaciones Aritméticas sobre Variables de Caracter

<?php
$i = 'W';
for($n=0; $n<6; $n++)
  echo ++$i . "\n";

/*
  Produce una salida similar a la siguiente:

X
Y
Z
AA
AB
AC

*/
?>


Operadores de Lógica

Tabla 10-6. Operadores de Lógica

EjemploNombreResultado
$a and $bYTRUE si tanto $a como $b son TRUE.
$a or $bOTRUE si cualquiera de $a o $b es TRUE.
$a xor $bO exclusivo (Xor)TRUE si $a o $b es TRUE, pero no ambos.
! $aNoTRUE si $a no es TRUE.
$a && $bYTRUE si tanto $a como $b son TRUE.
$a || $bOTRUE si cualquiera de $a o $b es TRUE.

La razón para tener las dos variaciones diferentes de los operadores "and" y "or" es que ellos operan con precedencias diferentes. (Vea Precedencia de Operadores.)


Operadores de Cadena

Existen dos operadores para datos tipo string. El primero es el operador de concatenación ('.'), el cual devuelve el resultado de concatenar sus argumentas a lado derecho e izquierdo. El segundo es el operador de asignación sobre concatenación ('.='), el cual adiciona el argumento del lado derecho al argumento en el lado izquierdo. Por favor consulte Operadores de Asignación para más información.

<?php
$a = "&iexcl;Hola ";
$b = $a . "Mundo!"; // ahora $b contiene "&iexcl;Hola Mundo!"

$a = "&iexcl;Hola ";
$a .= "Mundo!";     // ahora $a contiene "&iexcl;Hola Mundo!"
?>

Vea también las secciones del manual sobre el tipo String y las funciones de Cadenas.


Operadores de Matrices

Tabla 10-7. Operadores de Matrices

EjemploNombreResultado
$a + $bUniónUnión de $a y $b.
$a == $bIgualdadTRUE si $a y $b tienen los mismos elementos.
$a === $bIdentidadTRUE si $a y $b tienen los mismos elementos en el mismo orden.
$a != $bNo-igualdadTRUE si $a no es igual a $b.
$a <> $bNo-igualdadTRUE si $a no es igual a $b.
$a !== $bNo-identidadTRUE si $a no es idéntico a $b.

El operador + adiciona la matriz del lado derecho a aquél al lado izquierdo, al mismo tiempo que cualquier llave duplicada NO es sobrescrita.

<?php
$a = array("a" => "manzana", "b" => "banano");
$b = array("a" => "pera", "b" => "fresa", "c" => "cereza");

$c = $a + $b; // Union de $a y $b
echo "Uni&oacute;n de \$a y \$b: \n";
var_dump($c);

$c = $b + $a; // Union de $b y $a
echo "Uni&oacute;n de \$b y \$a: \n";
var_dump($c);
?>

Cuando sea ejecutado, este script producirá la siguiente salida:
Uni&oacute;n de $a y $b:
array(3) {
  ["a"]=>
  string(7) "manzana"
  ["b"]=>
  string(6) "banano"
  ["c"]=>
  string(6) "cereza"
}
Uni&oacute;n de $b y $a:
array(3) {
  ["a"]=>
  string(4) "pera"
  ["b"]=>
  string(5) "fresa"
  ["c"]=>
  string(6) "cereza"
}

Los elementos de las matrices son considerados equivalentes en la comparación si éstos tienen la misma clave y valor.

Ejemplo 10-2. Comparación de matrices

<?php
$a = array("manzana", "banano");
$b = array(1 => "banano", "0" => "manzana");

var_dump($a == $b); // bool(true)
var_dump($a === $b); // bool(false)
?>

Vea también las secciones del manual sobre el tipo Array y funciones de Matrices.


Operadores de Tipo

PHP tiene un operador único de tipo: instanceof. instanceof es usado para determinar si un objeto dado es de una clase de objeto especificada.

El operador instanceof fue introducido en PHP 5. Antes de esta versión, is_a() era utilizado, pero is_a() ha sido marcado como obsoleto desde entonces en favor de instanceof.

<?php
class A { }
class B { }

$cosa = new A;

if ($cosa instanceof A) {
    echo 'A';
}
if ($cosa instanceof B) {
    echo 'B';
}
?>

Dado que $cosa es un object de tipo A, pero no de tipo B, sólo el bloque dependiente del tipo A será ejecutado:

A

Vea también get_class() e is_a().


Capítulo 11. Estructuras de Control

Todo script 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:

<?php
if (expr)
    sentencia
?>

Como se describe en la sección sobre expresiones, expr se evalúa a su valor condicional (boolean). Si expr se evalúa como TRUE, PHP ejecutará la sentencia, y si se evalúa como FALSE - la ignorará. Se puede encontrar más información sobre los valores evaluados como FALSE en la sección Convirtiendo a un valor condicional (boolean)'.

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

<?php
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:

<?php
 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:

<?php
 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:

<?php
 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 es igual 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:

<?php
 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:

<?php
/* ejemplo 1 */
 
 $i = 1;
 while ($i <= 10) {
     print $i++;  /* el valor impreso ser&iacute;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:

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

<?php
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:

<?php
 /* 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

PHP 4 (PHP3 no) incluye una construcción foreach, tal como perl y algunos otros lenguajes. Esto simplemente da un modo fácil de iterar sobre matrices. foreach funciona solamente con matrices y devolverá un error si se intenta utilizar con otro tipo de datos ó variables no inicializadas. 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 matriz se reinicia automáticamente al primer elemento de la matriz. Esto significa que no se necesita llamar a reset() antes de un bucle foreach.

Nota: Hay que tener en cuenta queforeach trabaja con una copia de la matriz especificada y no la lista en si, por ello el puntero de la lista no es modificado como en la función each(), y los cambios en el elemento de la matriz retornado no afectan a la matriz original. De todas maneras el puntero interno a la matriz original avanza al procesar la matriz. suponiendo que bucle foreach se ejecuta hasta el final, el puntero interno a la matriz estar/aacute; al final de la matriz.

Nota: foreach no soporta la caracteristica de suprimir mensajes de error con '@'.

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

<?php
$arr = array("one", "two", "three");
reset ($arr);
while (list(, $value) = each ($arr)) {
    echo "Value: $value<br>\n";
}

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

Las siguientes también son funcionalidades idénticas:

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

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

Algunos ejemplos más para demostrar su uso:

<?php
/* foreach ejemplo 1: s&oacute;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&oacute;lo para prop&oacute;sitos demostrativos */

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

/* 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";
}

/* foreach ejemplo 4: matriz multi-dimensional */

$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";

foreach($a as $v1) {
    foreach ($v1 as $v2) {
        print "$v2\n";
    }
}

/* foreach ejemplo 5: matriz din&aacute;mica */
     
foreach(array(1, 2, 3, 4, 5) as $v) {
    print "$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.

<?php
$arr = array ('one', 'two', 'three', 'four', 'stop', 'five');
while (list (, $val) = each ($arr)) {
    if ($val == 'stop') {
        break;    /* You could also write 'break 1;' here. */
    }
    echo "$val<br>\n";
}

/* Using the optional argument. */

$i = 0;
while (++$i) {
    switch ($i) {
    case 5:
        echo "At 5<br>\n";
        break 1;  /* Exit only the switch. */
    case 10:
        echo "Al 10; saliendo<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.

Nota: Tener en cuenta que en PHP la declaración switch es considerada una estructura de bucle por continue.

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

<?php
while (list ($key, $value) = each ($arr)) {
    if (!($key % 2)) { // skip odd members
        continue;
    }
    do_something_odd ($value);
}

$i = 0;
while ($i++ < 5) {
    echo "Outer<br>\n";
    while (1) {
        echo "&nbsp;&nbsp;Middle<br>\n";
        while (1) {
            echo "&nbsp;&nbsp;Inner<br>\n";
            continue 3;
        }
        echo "Esto nunca se imprime.<br>\n";
    }
    echo "Y esto tampoco.<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.

Nota: Tener en cuenta que al contrario que otros lenguajes de programación, continue se aplica a switch y funciona de manera similar a break. Si teneis un switch dentro de un bucle y deseais continuar con el paso siguiente en el bucle externo, usar continue 2.

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:

<?php
if ($i == 0) {
    print "i equals 0";
} elseif ($i == 1) {
    print "i equals 1";
} elseif ($i == 2) {
    print "i equals 2";
}

switch ($i) {
    case 0:
        print "i equals 0";
        break;
    case 1:
        print "i equals 1";
        break;
    case 2:
        print "i equals 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:

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

<?php
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 caso especial es el default case". Este "case" coincide con todo lo que no coincidan los otros case. Por ejemplo:

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

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


declare

La construcción declare es usada para definir directivas de ejecución para un bloque de código. La sintaxis de declare es similar a la de las otras estructuras de control:

declare (directiva) sentencia

Directiva permite asignar el comportamiento del bloque declare. Actualmente una sola directiva es reconocida: la directiva ticks (Consultar más abajo la información sobre la directiva ticks)

La sentencia es lo que se ejecuta -- Como se ejecuta y que efectos secundarios tiene depende de la directiva definida en la directiva.

El constructor declare se puede usar tambien globalmente, afectando a todo el código que le sigue.

<?php
// Estos son lo mismo:

// se puede usar este:
declare(ticks=1) {
    // script completo aqui
}

// o este:
declare(ticks=1);
// script completo aqui
?>


Ticks

Un "tick" es un evento que ocurre por cada N sentencias de bajo nivel ejecutadas dentro del bloque declare. El valor de N es especificado por ticks=N como directiva dentro de declare.

El evento que ocurre en cada "tick" es especificado usando la función register_tick_function(). Ver el ejemplo más abajo para más detalles. Tener en cuenta que mas de un evento puede ocurrir por cada "tick"

Ejemplo 11-1. Perfilar una sección de código PHP

<?php
// A function that records the time when it is called
function profile ($dump = FALSE)
{
    static $profile;

    // Return the times stored in profile, then erase it
    if ($dump) {
        $temp = $profile;
        unset ($profile);
        return ($temp);
    }

    $profile[] = microtime ();
}

// Set up a tick handler
register_tick_function("profile");

// Initialize the function before the declare block
profile ();

// Run a block of code, throw a tick every 2nd statement
declare (ticks=2) {
    for ($x = 1; $x < 50; ++$x) {
        echo similar_text (md5($x), md5($x*$x)), "<br />;";
    }
}

// Display the data stored in the profiler
print_r (profile (TRUE));
?>
Este ejemplo perfila el código PHP dentro del bloque 'declare', grabando la hora, una sentencia si y otra no, cuando fue ejecutada. Esta información puede ser usada para encontrar areas en donde el codigo es lento. Este proceso se puede implementar de diferentes maneras: usando "ticks" es más conveniente y facil de implementar.

"Ticks" es una manera muy buena de eliminar errores, implementando simples trabajos en paralelo, I/O en modo desatendido y otras tareas.

Ver también register_tick_function() y unregister_tick_function().


return

Si se llama desde una función, return() termina inmediatamente la ejecución de la función y retorna su argumento como valor de la función. return() tambien terminará la ejecución de una sentencia eval()ó un script PHP.

Si el script actual ha sido incluido ó requerido con include() ó require(), el control es transferido al script que llamo al script incluido. Además, si el script actual fue incluido, el valor dado a return() será retornado como el valor de la llamada include(). Si return() es invocado desde el script principal, la ejecución terminara inmediatamente. Si el script actual fue incluido con las opciones de configuración auto_prepend_file ó auto_append_file, la ejecución terminara inmediatamente.

Para más información, consultar Retornando valores.

Nota: Tener en cuenta que ya que return() es un constructor del lenguaje y no una función, los paréntesis alrededor de sus argumentos, son solo necesarios si el argumento contiene una expresion, no se suelen utilizar tan a menudo, cuando retornan una variable.


require()

La sentencia require() incluye y evalua el archivo especificado.

require() incluye y evalua el archivo especificado. Información detallada de como esta inclusión funciona se puede encontrar en la documentación de la función include().

require() y include() son idénticas en todos los aspectos excepto en el modo de actuar ante un error. include() produce un Warning mientras que require() produce un Error Fatal. En otras palabras, no dude en utilizar require() si quiere que un fichero no encontrado cuelgue el procesamiento de la página. include() no se comporta de esta manera, el script seguirá funcionando de todas maneras. Asegurarse que include_path este configurado bien.

Ejemplo 11-2. ejemplos básicos de require()

<?php

require 'prepend.php';

require $somefile;

require ('somefile.txt');

?>

consultar la documentación de include() para más ejemplos.

Nota: Con anterioridad a PHP 4.0.2, se aplica lo siguiente: require() siempre intentará leer el fichero a incluir, incluso si la linea donde se encuentra require() nunca es ejecutada. Sin embargo, si la linea donde se encuentra require() no es ejecutada, tampoco lo hará el código incluido.

Nota: Puesto que esto es una construcción del lenguaje y no una función, no puede ser llamado usando funciones variables

Aviso

Versiones de PHP para Windows anteriores a 4.3.0, no soportan el acceso remoto a archivos para esta función, no funcionará ni activando siquiera allow_url_fopen.

Ver también include(), require_once(), include_once(), eval(), file(), readfile(), virtual() y include_path.


include()

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

Esta documentación también se aplica a la función require(). require() y include() son idénticas en todos los aspectos excepto en el modo de actuar ante un error. include() produce un Warning mientras que require() produce un Error Fatal. En otras palabras, no dude en utilizar require() si quiere que un fichero no encontrado cuelgue el procesamiento de la página. include() no se comporta de esta manera, el script seguirá funcionando de todas maneras. Asegurarse que include_path este configurado bien.

Cuando un fichero es incluido, el código que contiene hereda la variable scope de la linea en donde el include ocurre. Cualquier variable disponible en esa linea en el fichero desde donde se hace la inclusión estará disponible en el fichero incluido a partir de ese momento.

Ejemplo 11-3. Ejemplo básico de la funcióninclude()

vars.php
<?php

$color = 'green';
$fruit = 'apple';

?>

test.php
<?php

echo "A $color $fruit"; // A

include 'vars.php';

echo "A $color $fruit"; // A green apple

?>

Si la inclusión ocurre dentro de una función en el fichero donde se incluye, todo el código contenido en el fichero incluido se comportará como si hubiese sido definido dentro de esta función.

Ejemplo 11-4. Incluyendo desde funciones

<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
 * $fruit is NOT available outside of this  *
 * scope.  $color is because we declared it *
 * as global.                               */

foo();                    // A green apple
echo "A $color $fruit";   // A green

?>

Cuando un fichero es incluido, 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.

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 (via HTTP u otro mecanismo soportado, consultar Apéndice L) en vez de un fichero local. Si el servidor destino interpreta el fichero destino como código PHP, variables pueden ser mandadas al fichero incluido usando una cadena URL de petición, tal como se hace con HTTP GET. Esto no es lo mismo que incluir un fichero y que este fichero herede las variables del fichero padre; el script es ejecutado en el servidor remoto y el resultado es incluido en en script local.

Aviso

Versiones de PHP para Windows anteriores a 4.3.0, no soportan el acceso remoto a archivos para esta función, no funcionará ni activando siquiera allow_url_fopen.

Ejemplo 11-5. include() a traves de HTTP

<?php

/* This example assumes that www.example.com is configured to parse .php 
 * files and not .txt files. Also, 'Works' here means that the variables 
 * $foo and $bar are available within the included file.*/

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'file.txt';  // Works.
include 'file.php';  // Works.

?>
Ver también Ficheros remotos, fopen() y file() para obtener información adicional.

Ya que include() y require() son contructores especiales del lenguaje, se deben de incluir dentro del bloque de una sentencia, si están dentro de un bloque condicional.

Ejemplo 11-6. include() y bloques condicionales

<?php

// This is WRONG and will not work as desired.
if ($condition)
    include $file;
else
    include $other;


// This is CORRECT.
if ($condition) {
    include $file;
} else {
    include $other;
}

?>

Es posible ejecutar una sentencia return dentro de un archivo incluido para terminar el procesado de ese archivo y volver al archivo de comandos que lo llamó. Tambien es posible retornar valores de ficheros incluidos. Se puede coger el valor de la llamada "include" como se haría con una función normal.

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

Ejemplo 11-7. include() y return()

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>

$bar es igual a 1 porque la inclusión salio bien. Notar la diferencia entre los dos ejemplos anteriores. el primero usa return() dentro del fichero incluido y el segundo no. Otras maneras de incluir ficheros en variables es con fopen(), file() ó usando include()con Funciones de control de salida.

Nota: Puesto que esto es una construcción del lenguaje y no una función, no puede ser llamado usando funciones variables

Ver también require(), require_once(), include_once(), readfile(), virtual(), y include_path.


require_once()

La función require_once() incluye y evalua el fichero especificado durante la ejecución del script. Se comporta de manera similar a require(), con la única diferencia que si el código ha sido ya incluido, no se volverá a incluir. Consultar la documentación de la función require() para obtener más información.

require_once() debería de usarse en casos en los que un mismo fichero puede ser incluido y evaluado más de una vez durante la ejecución de un script, y se quiere estar seguro que se incluye una sola vez para evitar problemas con redefiniciones de funciones, valores de funciones, etc.

Para consultar ejemplos que usen require_once() y include_once(), ver el código de PEAR incluido con las últimas versiones de PHP.

Nota: require_once() fue incorporado en PHP 4.0.1pl2

Nota: El comportamiento de de require_once() y include_once() puede que no sea el esperado en sistemas operativos en los que mayúsculas y minúsculas se traten igual (como en Windows)

Ejemplo 11-8. Con require_once() no importan las mayúsculas y minúsculas en Windows

<?php
require_once("a.php"); // this will include a.php
require_once("A.php"); // this will include a.php again on Windows!
?>

Aviso

Versiones de PHP para Windows anteriores a 4.3.0, no soportan el acceso remoto a archivos para esta función, no funcionará ni activando siquiera allow_url_fopen.

Ver también require(), include(), include_once(), get_required_files(), get_included_files(), readfile(), y virtual().


include_once()

La función include_once() incluye y evalua el fichero especificado durante la ejecución del script. Se comporta de manera similar a include(), con la única diferencia que si el código ha sido ya incluido, no se volverá a incluir.

include_once() debería de usarse en casos en los que, un mismo fichero puede ser incluido y evaluado más de una vez durante la ejecución de un script, y se quiere estar seguro que se incluye una sola vez para evitar problemas con redefiniciones de funciones, valores de funciones, etc.

Para consultar ejemplos que usen include_once() e require_once(), ver el código de PEAR incluido con las últimas versiones de PHP.

Nota: include_once() fue incorporado en PHP 4.0.1pl2

Nota: El comportamiento de de include_once() y require_once() puede que no sea el esperado en sistemas operativos en los que mayúsculas y minúsculas se traten igual (como en Windows)

Ejemplo 11-9. Con include_once() no importan las mayúsculas y minúsculas en Windows

<?php
include_once("a.php"); // this will include a.php
include_once("A.php"); // this will include a.php again on Windows!
?>

Aviso

Versiones de PHP para Windows anteriores a 4.3.0, no soportan el acceso remoto a archivos para esta función, no funcionará ni activando siquiera allow_url_fopen.

Ver también include(), require(), require_once(), get_required_files(), get_included_files(), readfile(), y virtual().


Capítulo 12. Funciones

Funciones definidas por el usuario

Una función se puede definir con la siguiente sintaxis:

Ejemplo 12-1. Psuedo código para demostrar el uso de funciones

<?php
function foo ($arg_1, $arg_2, ..., $arg_n) 
{
    echo "Funci&oacute;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.Excepto cuando una función es definida condicionalmente como en los ejemplos siguientes.

Cuando una función es definida condicionalmente como se puede ver en estos dos ejemplos, su definición debe ser procesada antes que sea llamada.

Ejemplo 12-2. Funciones Condicionales

<?php

$makefoo = true;

/* We can't call foo() from here 
   since it doesn't exist yet,
   but we can call bar() */

bar();

if ($makefoo) {
  function foo ()
  {
    echo "I don't exist until program execution reaches me.\n";
  }
}

/* Now we can safely call foo()
   since $makefoo evaluated to true */

if ($makefoo) foo();

function bar() 
{
  echo "I exist immediately upon program start.\n";
}

?>

Ejemplo 12-3. Funciones dentro de funciones

<?php
function foo() 
{
  function bar() 
  {
    echo "I don't exist until foo() is called.\n";
  }
}

/* We can't call bar() yet
   since it doesn't exist. */

foo();

/* Now we can call bar(),
   foo()'s processesing has
   made it accessible. */

bar();

?>

PHP no soporta la redefinición de funciones previamente declaradas.

Nota: Los nombres de funciones se pueden llamar con mayusculas o minusculas, aunque es una buena costumbre el llamar a las funciones tal y como aparecen en su definición.

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:

Ejemplo 12-4. Pasando matrices a funciones

<?php
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:

Ejemplo 12-5. Pasando parámetros de funciones por referencia

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


Parámetros por defecto

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

Ejemplo 12-6. Uso de parámetros por defecto en funciones

<?php
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, miembro de una clase ó llamada a una función.

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:

Ejemplo 12-7. Uso incorrecto de parámetros por defecto en funciones

<?php
function makeyogurt ($type = "acidophilus", $flavour) 
{
    return "Haciendo un bol de $type $flavour.\n";
}
 
echo makeyogurt ("mora");   // No funcionar&aacute; 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:

Ejemplo 12-8. Uso correcto de parámetros por defecto en funciones

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


Devolviendo valores

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

Ejemplo 12-9. Us0 de return()

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

Ejemplo 12-10. Retornando una matriz para obtener múltiples valores

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

Para retornar una referencia desde una función, se tiene que usar el operador de referencias & tanto en la declaración de la función como en la asignación del valor de retorno a una variable;

Ejemplo 12-11. Retornando una referencia desde una función

<?php
function &returns_reference()
{
    return $someref;
}

$newref =& returns_reference();
?>

Para más información sobre referencias,consultar Explicando Referencias.


Funciones variables

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.

Las funciones varibles no funcionarán con construcciones del lenguaje, tal como echo(), print(), unset(), isset(), empty(), include(), require() y derivados. Se necesitará usar una función propia para utilizar cualquiera de estos constructores como funciones variables.

Ejemplo 12-12. Ejemplo de función variable

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

function bar($arg = '')
{
    echo "In bar(); argument was '$arg'.<br>\n";
}

// This is a wrapper function around echo
function echoit($string)
{
    echo $string;
}

$func = 'foo';
$func();        // This calls foo()

$func = 'bar';
$func('test');  // This calls bar()

$func = 'echoit';
$func('test');  // This calls echoit()
?>

También se puede llamar a un metodo de un objeto usando la característica variable de las funciones.

Ejemplo 12-13. Ejemplo sobre el metodo variable

<?php
class Foo
{
    function Var()
    {
        $name = 'Bar';
        $this->$name(); // This calls the Bar() method
    }
    
    function Bar()
    {
        echo "This is Bar";
    }
}

$foo = new Foo();
$funcname = "Var";
$foo->$funcname();  // This calls $foo->Var()

?>

Ver también call_user_func(), variable variables y function_exists().


Funciones internas (incorporadas)

PHP tiene incorporadas muchas funciones y construcciones. Existen también funciones que requieren extensiones específicas de PHP para que no fallen con un error fatal del tipo "undefined function". Por ejemplo, para usar funciones image, tal como imagecreatetruecolor(), se necesita compilar PHP con soporte para GD. O para usar mysql_connect() se necesita compilar PHP con soporte para MySQL. Existen muchas funciones en el núcleo de PHP que se incluyen en cada version de PHP, como las funciones string y variable. Una llamada a la función phpinfo() ó get_loaded_extensions() mostrará que extensiones están cargadas en tu versión de PHP. Tener tambien en cuenta que muchas extensiones se encuentran activadas por defecto y que el manual de PHP se encuentra dividido en partes, según estas extensiones. Vea los capítulos configuración, instalación y los capitulos sobre cada extensión, para obtener información sobre como configurar vuestro PHP

La explicación de como leer e intrerpretar un prototipo de función se encuentra en la sección del manual titulada como leer la definición de una función. Es importante entender que devuelve una función ó si la función trabaja directamente en el valor entregado a la misma. Por ejemplo, str_replace() devuelve una cadena modificada mientras que usort() trabaja directamente en el valor entregado a la misma. Cada página del manual contiene información específica sobre las diferentes funciones existentes, parametros que utilizan, valores devueltos, cambios de comportamiento, etc. Es importante conocer estas diferencias para poder escribir correctamente código PHP.

Vea también function_exists(), referencias de funciones, get_extension_funcs() y dl().


Capítulo 13. 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 14. Explicando las Referencias

What References Are

Las Referencias en PHP son un medio para acceder al mismo contenido de una variable pero con diferentes nombres. No son como los punteros de C, sino que son alias en la tabla de símbolos. Hay que tener en cuenta, que en PHP el nombre de una variable y el contenido de una variable son diferentes, de manera que el mismo contenido, puede tener varios nombres. La analogía más cercana podría ser la de los archivos de Unix y sus nombres, dónde los nombres de las variables serían los directorios, y el contenido de las variables es el archivo en si. Las referencias también pueden ser pensadas como un enlace duro en un sistema de archivos Unix.


Lo que las Referencias son

Las Referencias en PHP te permiten lograr que dos variables "apunten" al mismo contenido. Cuando haces algo como:

$a =& $b

significa que $a y $b apuntan a la misma variable.

Nota: $a y $b son completamente iguales, no es que $a esté apuntando a $b o viceversa, sino que tanto $a como $b apuntan al mismo lugar.

La misma sintáxis puede ser utilizada con funciones, que devuelven Referencias, y con el operador new (en PHP 4.0.4 o superior):

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

Nota: El no utilizar el operador & causa que el objeto sea copiado en memoria. Si utilizamos $this en la clase, entonces actuaremos sobre la instancia actual de la clase. Las asignaciones sin & harán una copia de la instancia (por ejemplo, del objeto) y $this operará en la copia, lo que no siempre es el comportamiento deseado. Usualmente se desea utilizar una sola instancia, debido a razones de memoria y performance de la aplicación.

Mientras que se puede utilizar @ para silenciar cualquier error en el constructor utilizando @new, esto no funciona cuando utilizamos &new. Esto es una limitación del Zend Engine y por lo tanto, resultará en un error de sintáxis.

Otro uso que se le puede dar a las referencias es el traspaso de variables por-referencia. Esto se logra haciendo que una variable 'local' a la función y una variable en el script 'referencien' al mismo contenido. Por ejemplo:

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

$a=5;
foo ($a);

hará que $a valga 6. Esto es posible porque en la funció foo, la variable $var 'referencia' al mismo contenido que la variable $a. Más información acerca de paso por referencia.

Un tercer uso de las referencias es el retorno por referencia.


Lo que las Referencias no son

Como se ha mencionado antes, las Referencias NO son punteros. Esto significa que el siguiente ejemplo no hará lo que se espera:

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

Lo que ocurrirá aquí es que $var en foo será 'ligada' con $bar al momento de llamar a la función. Pero luego será 're-ligada' con $GLOBALS["baz"]. No existe manera de ligar $bar en el ámbito global del script con alguna otra cosa utilizando el mecanismo de Referencias, ya que $bar no existe dentro de foo (está representado por $var, pero $var solo está ligado por el contenido, no por el nombre en la tabla de símbolos).


Paso de variables por Referencia

Podemos pasar variables a una función por referencia, para que ésta pueda modificar sus argumentos. La sintáxis es la siguiente :

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

$a=5;
foo ($a);
// $a ser&aacute; 6 aqui

Notar que no hay signo de referencia en la llamada a la función - solo en la definición de la misma. Colocar el signo de referencia solo en la definición de la función alcanza para pasar correctamente el argumento por referencia.

La lista siguiente indica que puede ser pasado por referencia:

  • Variables, por ejemplo foo($a)

  • Operador New, por ejemplo foo(new foobar())

  • Referencias, devueltas por una función:

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

    Se recomienda leer también la explicación sobre retorno por referencia.

Cualquier otro tipo de expresión no debería pasarse por referencia, ya que el resultado sería indefinido. Los ejemplos de paso por referencia siguientes son inválidos:

function bar() // Notar que falta &
{
    $a = 5;
    return $a;
}
foo(bar());

foo($a = 5) // Expresi&oacute;n, no variable
foo(5) // Constante, no variable

Estos requerimientos son para PHP 4.0.4 y superior.


Retorno por Referencia

Devolver por Referencia es muy útil cuando se quiere utilizar una función para averiguar a que variable debe estar una referencia ligada. Cuando se devuelve por referencia, se debe utilizar esta sintáxis:

function &encontrar_var ($param)
{
    ...codigo...
    return $var_encontrada;
}

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

En este ejemplo, el atributo del objeto devuelto por la función encontrar_var fue asignado, no ya en la copia, como habría sucedido si no se utilizaba la sintáxis de referencias.

Nota: A diferencia del paso de parámetros, aquí se debe utilizar & en ambos lugares - para indicar que se pretende devolver por referencia ( y no una copia, como usualmente sucede) y que además esa referencia sea 'ligada' a una variable, y no solo asignada.


Borrando Referencias

Cuando de borra una referencia, solo se rompe esa unión entre el nombre de la variable y el contenido. Esto no significa que el contenido haya sido destruido. Por ejemplo :

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

no destruiría $b, solo $a.

Nuevamente, sería útil pensar el tema de las referencias como una analogía al comando unlink de Unix.


Más Referencias

Muchas construcciones sintácticas en PHP son implementadas utilizando el mecanismo referencial, de manera que todo lo dicho anteriormente sobre las referencias también se aplica a estas construcciones. Algunas de ellas, como pasar o retornar por referencia, se mencionaron antes. Otras construcciones que utilizan referencias son:


Referencias globales

Cuando declaramos una variable como global $var en realidad estamos creando una referencia a una variable global. Esto significa, que es lo mismo que hacer :

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

De esta manera, por ejemplo, si borramos $var no estaríamos borrando la variable global.


$this

En un método de objeto, $this es siempre una referencia al objeto que contiene el método.

III. Seguridad

Tabla de contenidos
15. Seguridad

Capítulo 15. Seguridad


Introducción

PHP es un poderoso lenguaje e intérprete, ya sea incluido como parte de un servidor web en forma de módulo o ejecutado como un binario CGI separado, es capaz de acceder a archivos, ejecutar comandos y abrir conexiones de red en el servidor. Estas propiedades hacen que cualquier cosa que sea ejecutada en un servidor web sea insegura por naturaleza. PHP está diseñado específicamente para ser un lenguaje más seguro para escribir programas CGI que Perl o C, y con la selección correcta de opciones de configuración en tiempos de compilación y ejecución, y siguiendo algunas prácticas correctas de programación, PHP le puede dar la combinación precisa de libertad y seguridad que usted necesita.

Ya que hay muchas maneras de utilizar PHP, existen varias opciones de configuración diseñadas para controlar su comportamiento. Un amplio rango de opciones le garantizan que pueda usar PHP para muchos propósitos distintos, pero también quiere decir que hay combinaciones de éstas opciones y configuraciones de servidor que pueden resultar en un entorno inseguro.

El nivel de flexibilidad en la configuración de PHP se compara quizás solo con su flexibilidad de desarrollo. PHP puede ser usado para escribir aplicaciones completas de servidor, con todo el poder de un usuario de un intérprete de comandos, o puede ser usado para inclusiones simples del lado del servidor con muy poco riesgo en un entorno minuciosamente controlado. Cómo construir ese entorno, y qué tan seguro es, básicamente depende del desarrollador PHP.

Este capítulo comienza con algunas recomendaciones generales de seguridad, explica las diferentes combinaciones de opciones de configuración y las situaciones en las que pueden ser usadas con seguridad, y describe diferentes consideraciones a la hora de programar para diferentes niveles de seguridad.


Consideraciones generales

Un sistema completamente seguro es prácticamente un imposible, de modo que el enfoque usado con mayor frecuencia en la profesión de seguridad es uno que busque el balance adecuado entre riesgo y funcionalidad. Si cada variable enviada por un usuario requiriera de dos formas de validación biométrica (como rastreo de retinas y análisis dactilar), usted contaría con un nivel extremadamente alto de confiabilidad. También implicaría que llenar los datos de un formulario razonablemente complejo podría tomar media hora, cosa que podría incentivar a los usuarios a buscar métodos para esquivar los mecanismos de seguridad.

La mejor seguridad con frecuencia es lo suficientemente razonable como para suplir los requerimientos dados sin prevenir que el usuario realice su labor de forma natural, y sin sobrecargar al autor del código con una complejidad excesiva. De hecho, algunos ataques de seguridad son simples recursos que aprovechan las vulnerabilidades de este tipo de seguridad sobrecargada, que tiende a erosionarse con el tiempo.

Una frase que vale la pena recordar: Un sistema es apenas tan bueno como el eslabón más débil de una cadena. Si todas las transacciones son registradas copiosamente basándose en la fecha/hora, ubicación, tipo de transacción, etc. pero la verificación del usuario se realiza únicamente mediante una cookie sencilla, la validez de atar a los usuarios al registro de transacciones es mermada severamente.

Cuando realice pruebas, tenga en mente que no será capaz de probar todas las diferentes posibilidades, incluso para las páginas más simples. Los datos de entrada que usted puede esperar en sus aplicaciones no necesariamente tendrán relación alguna con el tipo de información que podría ingresar un empleado disgustado, un cracker con meses de tiempo entre sus manos, o un gato doméstico caminando sobre el teclado. Es por esto que es mejor observar el código desde una perspectiva lógica, para determinar en dónde podrían introducirse datos inesperados, y luego hacer un seguimiento de cómo esta información es modificada, reducida o amplificada.

Internet está repleto de personas que tratan de crearse fama al romper la seguridad de su código, bloquear su sitio, publicar contenido inapropiado, y por lo demás haciendo que sus días sean más interesantes. No importa si usted administra un sitio pequeño o grande, usted es un objetivo por el simple hecho de estar en línea, por tener un servidor al cual es posible conectarse. Muchas aplicaciones de cracking no hacen distinciones por tamaños, simplemente recorren bloques masivos de direcciones IP en busca de víctimas. Trate de no convertirse en una.


Instalación como un binario CGI

Posibles ataques

El uso de PHP como un binario CGI es una opción para el tipo de situaciones en las que por alguna razón no se desea integrar PHP como módulo de algún software de servidor web (como Apache), o en donde se espera usar PHP con diferentes tipos de capas que envuelven el entorno CGI para crear ambientes chroot y setuid seguros para la ejecución de scripts. Esta configuración usualmente involucra la instalación de un binario ejecutable del intérprete PHP en el directorio cgi-bin del servidor web. El aviso de seguridad de CERT CA-96.11 recomienda que se evite la colocación de cualquier intérprete bajo cgi-bin. Incluso si el binario PHP puede ser usado como un intérprete independiente, PHP está diseñado para prevenir el tipo de ataques que esta configuración hace posible:

  • Acceso a archivos del sistema: http://mi.servidor/cgi-bin/php?/etc/passwd

    La información del query en una URL, la cual viene después del signo de interrogación (?), es pasada como argumentos de línea de comandos al intérprete por la interfaz CGI. Usualmente los intérpretes abren y ejecutan el archivo especificado como primer argumento de la línea de comandos.

    Cuando es invocado como un binario CGI, PHP se rehúsa a interpretar los argumentos de la línea de comandos.

  • Acceso a cualquier documento web en el servidor: http://mi.servidor/cgi-bin/php/zona_secreta/doc.html

    El segmento de la URL que sigue al nombre del binario de PHP, que contiene la información sobre la ruta /zona_secreta/doc.html es usada convencionalmente para especificar el nombre de un archivo que ha de ser abierto e interpretado por el programa CGI. Usualmente, algunas directivas de configuración del servidor web (Apache: Action) son usadas para redireccionar peticiones de documentos como http://mi.servidor/zona_secreta/script.php al intérprete de PHP. Bajo este modelo, el servidor web revisa primero los permisos de acceso al directorio /zona_secreta, y después de eso crea la petición de redireccionamiento a http://mi.servidor/cgi-bin/php/zona_secreta/script.php. Desafortunadamente, si la petición se hace originalmente en esta forma, no se realizan chequeos de acceso por parte del servidor web para el archivo /zona_secreta/script.php, únicamente para el archivo /cgi-bin/php. De este modo, cualquier usuario capaz de acceder a /cgi-bin/php es capaz también de acceder a cualquier documento protegido en el servidor web.

    En PHP, la configuración de tiempo de compilación --enable-force-cgi-redirect y las directivas de configuración en tiempo de ejecución doc_root y user_dir pueden ser usadas para prevenir este tipo de ataques, si el árbol de documentos del servidor llegara a tener directorio alguno con restricciones de acceso. Consulte las siguientes secciones para una explicación detallada de las diferentes combinaciones.


Caso 1: sólo se sirven archivos públicos

Si su servidor no tiene contenido alguno que no esté restringido por contraseñas o control de acceso basado en direcciones ip, no hay ninguna necesidad de recurrir a estas opciones de configuración. Si su servidor web no le permite hacer redireccionamientos, o el servidor no tiene una forma de comunicarle al binario PHP que la petición de redireccionamiento es segura, puede especificar la opción --enable-force-cgi-redirect en el script de configuración. Aun así debe asegurarse de que sus scripts PHP no dependan de alguna forma especial de hacer llamados al script, ya sea directamente mediante http://mi.servidor/cgi-bin/php/dir/script.php ni por la redirección http://mi.servidor/dir/script.php.

Los redireccionamientos pueden ser configurados en Apache mediante el uso de directivas AddHandler y Action (vea más adelante).


Caso 2: uso de --enable-force-cgi-redirect

Esta opción en tiempo de compilación previene que cualquier persona haga llamados a PHP directamente mediante una URL como http://mi.servidor/cgi-bin/php/directorio_secreto/script.php. En lugar de esto, PHP analizará documentos de esta forma únicamente si han pasado por una regla de redirección del servidor web.

Por lo general, el redireccionamiento en la configuración de Apache es realizada con alguna de las siguientes directivas:

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

Esta opción ha sido probada únicamente con el servidor web Apache, y depende de que Apache defina la variable de entorno no-estándar REDIRECT_STATUS a la hora de gestionar peticiones redirigidas. Si su servidor web no dispone de modo alguno de comunicar si la petición es directa o redirigida, no puede usar esta opción y debe recurrir a alguna de las otras formas documentadas aquí de ejecutar la versión CGI.


Caso 3: configuración de doc_root o user_dir

Incluir contenido activo en los directorios de documentos del servidor web, como scripts y ejecutables, es considerada en ocasiones una práctica insegura. Si, por algún fallo de configuración, los scripts no llegaran a ser ejecutados sino desplegados como documentos HTML normales, esto podría resultar en la revelación de información crítica como trabajos cubiertos por normas de propiedad intelectual o datos de seguridad como contraseñas. Por lo tanto muchos administradores de sistemas preferirán la configuración de otra estructura de directorios para los scripts que sean asequibles únicamente a través del CGI PHP, y por lo tanto deben ser interpretados siempre y no desplegados directamente.

Así mismo, si el método para asegurarse de que las peticiones no son redireccionadas, tal y como se describió en la sección anterior, no está disponible, es necesario entonces configurar un directorio raíz (doc_root) de scripts que sea diferente al directorio raíz de documentos web.

Puede definir el directorio raíz para scripts de PHP mediante la directiva de configuración doc_root en el archivo de configuración, o puede darle un valor a la variable de entorno PHP_DOCUMENT_ROOT. Si ésta está definida, la versión CGI de PHP construirá siempre el nombre del archivo a abrir con este doc_root y la información de la ruta dada en la petición, de modo que puede estar seguro de que ningún script será ejecutado por fuera de este directorio (excepto por aquellos indicados en user_dir, como se verá a continuación).

Otra opción que puede ser usada en este caso es user_dir. Cuando user_dir no está definida, lo único que controla la apretura de archivos es doc_root. Abrir una URL como http://mi.servidor/~usuario/doc.php no resulta en la apertura de un archivo bajo el directorio personal del usuario, sino de un archivo llamado ~usuario/doc.php bajo la ruta doc_root (así es, un directorio cuyo nombre comienza por el caracter de equivalencia [~]).

Si user_dir está definido como, por ejemplo, public_php, una petición como http://mi.servidor/~usuario/doc.php abrirá un archivo llamado doc.php bajo el directorio con el nombre public_php ubicado en el directorio personal del usuario. Si el directorio personal del usuario es /home/usuario, el archivo ejecutado es /home/usuario/public_php/doc.php.

La expansión del valor de user_dir ocurre independientemente del parámetro doc_root, de modo que es posible controlar el directorio raíz de los documentos y el acceso a los directorios de los usuarios en forma separada.


Caso 4: intérprete PHP por fuera del árbol web

Una opción bastante segura es colocar el intérprete binario de PHP en alguna parte por fuera del árbol de archivos web. En /usr/local/bin, por ejemplo. El único inconveniente real con esta alternativa es que ahora usted tendrá que colocar una línea como esta:

#!/usr/local/bin/php

al comienzo de cualquier archivo que contenga etiquetas PHP. También tendrá que hacer cada archivo ejecutable. Esto quiere decir que debe tratarlo exactamente igual a como trataría cualquier otro script CGI escrito en Perl o sh o cualquier otro lenguaje de scripting común que usara el mecanismo de escape-shell #! para el lanzamiento del intérprete.

Para lograr que PHP gestione correctamente la información de PATH_INFO y PATH_TRANSLATED con este tipo de configuración, el intérprete PHP debe haber sido compilado con la opción de configuración --enable-discard-path.


Instalación como módulo de Apache

Cuando PHP es usado como un módulo de Apache, hereda los permisos del usuario de Apache (generalmente los del usuario "nobody"). Este hecho representa varios impactos sobre la seguridad y las autorizaciones. Por ejemplo, si está usando PHP para acceder a una base de datos, a menos que tal base de datos disponga de un control de acceso propio, usted tendrá que hacer que la base de datos sea asequible por el usuario "nobody". Esto quiere decir que un script malicioso podría tener acceso y modificar la base de datos, incluso sin un nombre de usuario y contraseña. Es completamente posible que un archivador automatizado de documentos web pudiera toparse con la página web de administración de una base de datos, y eliminar todas sus bases de datos. Usted puede protegerse de este tipo de situaciones mediante mecanismos de autorización de Apache, o puede diseñar su propio modelo de acceso usando LDAP, archivos .htaccess, etc. e incluir ese código como parte de sus scripts PHP.

Con frecuencia, una vez la seguridad se ha establecido en un punto en donde el usuario de PHP (en este caso, el usuario de apache) tiene asociada una muy leve capacidad de riesgo, se descubre que PHP se encuentra ahora imposibilitado de escribir archivos en los directorios de los usuarios. O quizás se le haya desprovisto de la capacidad de acceder o modificar bases de datos. Se ha prevenido exitosamente que pudiera escribir tanto archivos buenos como malos, o que pudiera realizar transacciones buenas o malas en la base de datos.

Un error de seguridad cometido con frecuencia en este punto es darle permisos de administrador (root) a apache, o incrementar las habilidades del usuario de apache de alguna otra forma.

Escalar los permisos del usuario de Apache hasta el nivel de administrador es extremadamente peligroso y puede comprometer al sistema entero, así que el uso de entornos sudo, chroot, o cualquier otro mecanismo que sea ejecutado como root no debería ser una opción viable para aquellos que no son profesionales en seguridad.

Existen otras soluciones más simples. Mediante el uso de open_basedir usted puede controlar y restringir aquellos directorios que podrían ser usados por PHP. También puede definir áreas solo-Apache, para restringir todas las actividades basadas en web a archivos que no son de usuarios, o del sistema.


Seguridad del sistema de archivos

PHP está sujeto a la seguridad misma de la mayoría de sistemas de servidores en lo que a permisos sobre archivos y directorios se refiere. Esto le permite controlar cuáles archivos en el sistema de archivos pueden ser leídos. Debe tenerse cuidado con aquellos archivos que tengan permisos de lectura globales, para asegurarse de que su contenido es seguro y no represente peligro el que pueda ser leído por todos los usuarios con acceso al sistema de archivos.

Ya que PHP fue diseñado para permitir acceso al nivel de usuarios al sistema de archivos, es completamente posible escribir un script PHP que le permita leer archivos del sistema como /etc/passwd, modificar sus conexiones tipo ethernet, enviar trabajos de impresión masivos, etc. Esto tiene algunas implicaciones obvias, en el sentido en que usted tiene que asegurarse de que los archivos desde lo que lee y hacia los que escribe datos, sean los correctos.

Considere el siguiente script, en donde un usuario indica que quisiera eliminar un archivo ubicado en su directorio personal. Este caso asume que se trata de una situación en donde se usa normalmente una interfaz web que se vale de PHP para la gestión de archivos, así que el usuario de Apache tiene permitido eliminar archivos en los directorios personales de los usuarios.

Ejemplo 15-1. Un chequeo pobre de variables nos lleva a...

<?php
// eliminar un archivo del directorio personal del usuario

$nombre_usuario = $_POST['nombre_enviado_por_el_usuario'];
$directorio     = "/home/$nombre_usuario";

$archivo_a_eliminar = "$archivo_de_usuario";

unlink ("$directorio/$archivo_de_usuario");

echo "&iexcl;El archivo $archivo_a_eliminar ha sido eliminado!";
?>
Ya que el nombre de usuario es enviado desde un formulario de usuario, cualquiera puede enviar un nombre de usuario y archivo propiedad de otra persona, y eliminar archivos. En este caso, usted querrá usar otro método de autenticación. Considere lo que sucede si las variables enviadas son "../etc/" y "passwd". El código entonces se ejecutaría efectivamente como:

Ejemplo 15-2. ... un ataque al sistema de archivos

<?php
// elimina un archivo de cualquier parte del disco duro al que el
// usuario de PHP tiene acceso. Si PHP tiene acceso de root:

$nombre_usuario = "../etc/";
$directorio     = "/home/../etc/";

$archivo_a_eliminar = "passwd";

unlink ("/home/../etc/passwd");

echo "&iexcl;El archivo /home/../etc/passwd ha sido eliminado!";
?>
Hay dos importantes medidas que usted debe tomar para prevenir estas situaciones.

  • Otorgarle únicamente permisos limitados al usuario web del binario PHP.

  • Chequear todas las variables que son enviadas por usuarios.

Aquí hay una versión mejorada del script:

Ejemplo 15-3. Un chequeo de nombres de archivos más seguro

<?php
// elimina un archivo de cualquier parte del disco duro al que el
// usuario de PHP tiene acceso.

$nombre_usuario = $_SERVER['REMOTE_USER']; // uso de un mecanismo de
                                           // autenticacion

$directorio = "/home/$nombre_usuario";

$archivo_a_eliminar = basename("$archivo_de_usuario"); // remover rutas
unlink ($directorio/$archivo_a_eliminar);

$fp = fopen("/home/registros/eliminacion.log","+a"); // registrar el proceso

$cadena_de_registro = "$nombre_usuario $directorio $archivo_a_eliminar";

fwrite ($fp, $cadena_de_registro);
fclose($fp);

echo "&iexcl;El archivo $archivo_a_eliminar ha sido eliminado!";
?>
Sin embargo, incluso este caso no está libre de problemas. Si su sistema de autenticación le ha permitido a los usuarios la creación de sus propios nombres en el sistema, y un usuario elige "../etc/", el sistema se encuenrta nuevamente expuesto. Por esta razón, puede que uster prefiera escribir un chequeo más personalizado:

Ejemplo 15-4. Chequeo de nombres de archivos aun más seguro

<?php
$nombre_usuario = $_SERVER['REMOTE_USER']; // uso de un mecanismo de
                                           // autenticacion

$directorio = "/home/$nombre_usuario";

if (!ereg('^[^./][^/]*$', $archivo_de_usuario))
     die('nombre de archivo inv&aacute;lido'); // finalizar,
                                               // no ejecutar el proceso

if (!ereg('^[^./][^/]*$', $nombre_usuario))
     die('nombre de archivo inv&aacute;lido'); // finalizar,
                                               // no ejecutar el proceso

//etc...
?>

Dependiendo de su sistema operativo, existe una amplia variedad de archivos sobre los que usted debería estar atento, incluyendo las entradas de dispositivos (/dev/ o COM1), archivos de configuración (archivos /etc/ y los archivos .ini), areas conocidas de almacenamiento de datos (/home/, Mis Documentos), etc. Por esta razón, usualmente es más sencillo crear una política en donde se prohíba toda transacción excepto por aquellas que usted permita explícitamente.


Seguridad de Bases de Datos

Hoy en día, las bases de datos son componentes cardinales de cualquier aplicación basada en web, permitiendo que los sitios web provean contenido dinámico. Debido a que información considerablemente sensible o secreta puede ser almacenada en una base de datos, usted debe considerar seriamente la protección de sus bases de datos.

Para recuperar o almacenar cualquier información necesita conectarse a la base de datos, enviar una consulta válida, recoger el resultado y cerrar la conexión. Hoy en día, el lenguaje de consultas usado comúnmente en estas interacciones es el Lenguaje de Consultas Estructurado (SQL por sus siglas en Inglés). Puede apreciar cómo un atacante puede intentar acometidas con una consulta SQL.

Como puede suponer, PHP no puede proteger su base de datos por sí solo. Las siguientes secciones están dirigidas a servir de introducción a los conceptos básicos de cómo acceder y manipular bases de datos desde scripts PHP.

Mantenga en mente esta simple regla: protección en profundidad. Entre más acciones tome para incrementar la protección de su base de datos, menor será la probabilidad de que un atacante tenga éxito exponiendo o abusando de cualquier información almacenada. Un buen diseño del esquema de la base de datos y de la aplicación basta para lidiar con sus mayores temores.


Diseño de Bases de Datos

El primer paso siempre es crear la base de datos, a menos que desee usar una creada por alguien más. Cuando una base de datos es creada, ésta es asignada a un dueño, quien ejecutó la sentencia de creación. Usualmente, únicamente el dueño (o un super-usuario) puede hacer cualquier cosa con los objetos de esa base de datos, y para que otros usuarios puedan usarla, deben otorgarse privilegios.

Las aplicaciones nunca deberían conectarse a la base de datos bajo el usuario correspondiente a su dueño, o como un super-usuario, ya que éstos usuarios pueden, por ejemplo, ejecutar cualquier consulta a su antojo, modificando el esquema (p. ej. eliminando tablas) o borrando su contenido completo.

Usted puede crear diferentes usuarios de la base de datos para cada aspecto de su aplicación con derechos muy limitados sobre los objetos de la base de datos. Tan solo deben otorgarse los privilegios estrictamente necesarios, y evitar que el mismo usuario pueda interactuar con la base de datos en diferentes casos de uso. Esto quiere decir que si un intruso gana acceso a su base de datos usando las credenciales de sus aplicaciones, él solo puede efectuar tantos cambios como su aplicación se lo permita.

Es buena idea que no implemente toda la lógica del asunto en la aplicación web (es decir, en su script); en su lugar, hágalo en el esquema de la base de datos usando vistas, disparadores o reglas. Si el sistema evoluciona, se espera que nuevos puertos sean abiertos a la aplicación, y tendrá que re-implementar la lógica para cada cliente de la base de datos. Por sobre todo, los disparadores pueden ser usados para gestionar de forma transparente todos los campos automáticamente, lo cual con frecuencia provee información útil cuando se depuren problemas de su aplicación, o se realicen rastreos sobre transacciones particulares.


Conexión con la Base de Datos

Puede que desee establecer las conexiones sobre SSL para encriptar las comunicaciones cliente/servidor, incrementando el nivel de seguridad, o puede hacer uso de ssh para encriptar la conexión de red entre los clientes y el servidor de la base de datos. Si cualquiera de estos recursos es usado, entonces monitorear su tráfico y adquirir información sobre su base de datos será difícil para un atacante potencial.


Modelo de Almacenamiento Encriptado

SSL/SSH protege los datos que viajan desde el cliente al servidor, SSL/SSH no protege los datos persistentes almacenados en la base de datos. SSL es un protocolo sobre-el-cable.

Una vez el atacante adquiere acceso directo a su base de datos (evitando el paso por el servidor web), los datos críticos almacenados pueden estar expuestos o malutilizados, a menos que la información esté protegida en la base de datos misma. La encriptación de datos es una buena forma de mitigar esta amenaza, pero muy pocas bases de datos ofrecen este tipo de mecanismo de encriptación de datos.

La forma más sencilla de evitar este problema es crear primero su propio paquete de encriptación, y luego utilizarlo desde sus scripts de PHP. PHP puede ayudarle en este sentido con varias extensiones, como Mcrypt y Mhash, las cuales cubren una amplia variedad de algoritmos de encriptación. El script encripta los datos antes de insertarlos en la base de datos, y los decripta cuando los recupera. Vea las referencias para consultar más ejemplos de cómo opera la encriptación.

En el caso de datos realmente escondidos, si su representación original no se necesita (es decir, no debe ser desplegada), los resúmenes criptográficos pueden llegar a considerarse también. El ejemplo clásico de gestión de resúmenes criptográficos es el almacenamiento de secuencias MD5 de una contraseña en una base de datos, en lugar de la contraseña misma. Vea también crypt() y md5().

Ejemplo 15-5. Uso de un campo de contraseñas encriptado

<?php

// almacenamiento de resumen criptografico de la contrasenya

$consulta  = sprintf("INSERT INTO usuarios(nombre,contr) VALUES('%s','%s');",
                     addslashes($nombre_usuario), md5($contrasenya));
$resultado = pg_exec($conexion, $consulta);


// consulta de verificacion de la contrasenya enviada

$consulta  = sprintf("SELECT 1 FROM usuarios WHERE nombre='%s' AND contr='%s';",
                     addslashes($nombre_usuario), md5($contrasenya));
$resultado = pg_exec($conexion, $consulta);

if (pg_numrows($resultado) > 0) {
    echo "&iexcl;Bienvenido, $nombre_usuario!";
}
else {
    echo "No pudo autenticarse a $nombre_usuario.";
}

?>

Inyección de SQL

Muchos desarrolladores web no son conscientes de cómo pueden manipularse las consultas SQL, y asumen que una consulta SQL es un comando confiable. Esto representa que las consultas SQL pueden burlar los controles de acceso, y de este modo evitar los chequeos estándares de autenticación y autorización, y a veces las consultas SQL pueden incluso permitir acceso a comandos al nivel del sistema operativo de la máquina huésped.

La Inyección Directa de Comandos SQL es una técnica en la cual un atacante crea o altera comandos SQL existentes para exponer datos escondidos, o sobrescribir datos críticos, o incluso ejecutar comandos del sistema peligrosos en la máquina en donde se encuentra la base de datos. Esto se consigue cuando la aplicación toma información de entrada del usuario y la combina con parámetros estáticos para construir una consulta SQL. Los siguientes ejemplos, desafortunadamente, están basados en historias reales.

Debido a la falta de validación de la información de entrada y el establecimiento de conexiones con la base de datos desde un super-usuario o aquel que puede crear usuarios, el atacante podría crear un super-usuario en su base de datos.

Ejemplo 15-6. Paginación del conjunto de resultados ... y creación de super-usuarios (PostgreSQL y MySQL)

<?php

$offset   = argv[0]; // atencion, no se valida la entrada!
$consulta = "SELECT id, nombre FROM productos ORDER BY nombre LIMIT 20 " .
            "OFFSET $offset;";

// con PostgreSQL 
$resultado = pg_exec($conexion, $consulta);

// con MySQL
$resultado = mysql_query($consulta);

?>
Los usuarios normales pulsan sobre los enlaces 'siguiente' y 'anterior', en donde el desplazamiento ($offset) se encuentra codificado en la URL. El script espera que el valor entrante $offset sea un número decimal. Sin embargo, qué sucede si alguien intenta un ataque añadiendo una forma codificada (urlencode()) de lo siguiente en la URL

// en el caso de PostgreSQL
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
    select 'crack', usesysid, 't','t','crack'
    from pg_shadow where usename='postgres';
--

// en el caso de MySQL
0;
UPDATE user SET Password=PASSWORD('crack') WHERE user='root';
FLUSH PRIVILEGES;

Si esto ocurriera, entonces el script le presentaría un acceso de superusuario al atacante. Note que 0; es usado para ofrecer un desplazamiento válido a la consulta original y finalizarla.

Nota: Es una técnica común obligar al analizador sintáctico de SQL a que ignore el resto de la consulta escrita por el desarrollador mediante --, el cual es el signo de comentarios en SQL.

Una forma viable de adquirir contraseñas es jugar con las páginas de resultados de búsquedas. Lo único que necesita el atacante es ver si existen variables enviadas por el usuario que sean usadas en sentencias SQL, y que no sean tratadas apropiadamente. Estos filtros pueden ubicarse por lo general previos a cláusulas WHERE, ORDER BY, LIMIT y OFFSET en sentencias SELECT para personalizar la instrucción. Si su base de datos soporta la construcción UNION, el atacante puede intentar añadir una consulta completa a la consulta original para generar una lista de contraseñas desde una tabla cualquiera. El uso de campos encriptados de contraseñas es altamente recomendable.

Ejemplo 15-7. Listado de artículos ... y algunas contraseñas (en cualquier base de datos)

<?php

$consulta  = "SELECT id, nombre, insertado, tam FROM productos
                  WHERE tam = '$tam'
                  ORDER BY $orden LIMIT $limite, $offset;";
$resultado = odbc_exec($conexion, $consulta);

?>
La parte estática de la consulta puede combinarse con otra sentencia SELECT la cual revela todas las contraseñas:

'
union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
--

Si esta consulta (la cual juega con ' y --) fuera asignada a una de las variables usadas en $consulta, la bestia de la consulta habrá despertado.

Las sentencias UPDATE de SQL son también susceptibles a ataque. Éstas consultas también se encuentran amenazadas por un posible acotamiento y adición de una consulta completamente nueva. Pero en este caso el atacante puede amañar la información de una cláusula SET. En este caso se requiere contar con cierta información sobre el esquema de la base de datos para poder manipular la consulta satisfactoriamente. Esta información puede ser adquirida mediante el estudio de los nombres de variables de los formularios, o simplemente por fuerza bruta. No existen demasiadas convenciones para nombrar campos de contraseñas o nombres de usuario.

Ejemplo 15-8. De restablecer una contraseña ... a adquirir más privilegios (con cualquier servidor de base de datos)

<?php
$consulta = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
?>
Pero un usuario malicioso envía el valor ' or uid like'%admin%'; -- como $uid para cambiar la contraseña del administrador, o simplemente establece $pwd a "hehehe', admin='yes', trusted=100 " (con un espacio al inicio) para adquirir más privilegios. En tal caso, la consulta sería manipulada:

<?php

// $uid == ' or uid like'%admin%'; --
$consulta = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --";

// $pwd == "hehehe', admin='yes', trusted=100 "
$consulta = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE ...;"

?>

Un horrible ejemplo de cómo puede accederse a comandos del nivel del sistema operativo en algunas máquinas anfitrionas de bases de datos.

Ejemplo 15-9. Ataque al sistema operativo de la máquina anfitriona de la base de datos (MSSQL Server)

<?php

$consulta  = "SELECT * FROM productos WHERE id LIKE '%$prod%'";
$resultado = mssql_query($consulta);

?>
Si el atacante envía el valor a%' exec master..xp_cmdshell 'net user test testpass /ADD' -- a $prod, entones la $consulta será:

<?php

$consulta  = "SELECT * FROM productos
                    WHERE id LIKE '%a%'
                    exec master..xp_cmdshell 'net user test testpass /ADD'--";
$resultado = mssql_query($consulta);

?>

MSSQL Server ejecuta sentencias SQL en el lote, incluyendo un comando para agregar un nuevo usuario a la base de datos de cuentas locales. Si esta aplicación estuviera corriendo como sa y el servicio MSSQLSERVER está corriendo con los privilegios suficientes, el atacante tendría ahora una cuenta con la que puede acceder a esta máquina.

Nota: Algunos de los ejemplos anteriores están atados a un servidor de base de datos específico. Esto no quiere decir que un ataque similar sea imposible con otros productos. Su base de datos puede ser vulnerable de forma semejante, en alguna otra manera.


Técnicas de protección

Usted puede argumentar con justa razón que el atacante debe poseer cierta cantidad de información sobre el esquema de la base de datos en la mayoría de ejemplos que hemos visto. Tiene razón, pero usted nunca sabe cuándo y cómo puede filtrarse esta información, y si ocurre, su base de datos estará expuesta. Si está usando un paquete de gestión de bases de datos de código abierto, o cuyo código fuente está disponible públicamente, el cual puede pertenecer a algún sistema de administración de contenido o foro, los intrusos pueden producir fácilmente una copia de un trozo de su código. También puede ser un riesgo de seguridad si es un segmento de código pobremente diseñado.

Estos ataques se basan principalmente en la explotación del código que no ha sido escrito pensando en la seguridad. Nunca confíe en ningún tipo de información de entrada, especialmente aquella que proviene del lado del cliente, aun si lo hace desde una caja de selección, un campo de entrada hidden o una cookie. El primer ejemplo le muestra que una consulta así de descuidada puede causar desastres.

  • Nunca se conecte a la base de datos como un super-usuario o como el dueño de la base de datos. Use siempre usuarios personalizados con privilegios muy limitados.

  • Revise si la entrada recibida es del tipo apropiado. PHP posee un amplio rango de funciones de validación de datos, desde los más simples encontrados en Funciones sobre variables y en Funciones de tipo de caracter (p. ej. is_numeric(), ctype_digit() respectivamente) hasta el soporte para Expresiones Regulares compatibles con Perl.

  • Si la aplicación espera alguna entrada numérica, considere la verificación de información con is_numeric(), o modifique silenciosamente su tipo usando settype(), o utilice su representación numérica, dada por sprintf().

    Ejemplo 15-10. Una forma más segura de generar una consulta para paginado

    <?php
    
    settype($offset, 'integer');
    $consulta = "SELECT id, nombre FROM productos ORDER BY nombre " .
                "LIMIT 20 OFFSET $offset;";
    
    // note el simbolo %d en la cadena de formato, usar %s no tendria sentido
    $consulta = sprintf("SELECT id, nombre FROM productos ORDER BY nombre" .
                        "LIMIT 20 OFFSET %d;", $offset);
    
    ?>

  • Ubique cada entrada del usuario no-numérica que sea pasada a la base de datos entre comillas con addslashes() o addcslashes(). Vea el primer ejemplo. Como se ve allí, las comillas colocadas en la parte estática de la consulta no son suficientes, y pueden ser manipuladas fácilmente.

  • No imprima ninguna información específica sobre la base de datos, especialmente sobre su esquema, ya sea por razones justas o por equivocaciones. Vea también Reporte de Errores y Gestión de Errores y Funciones de Registro.

  • Puede usar procedimientos almacenados y cursores previamente definidos para abstraer el acceso a las bases de datos, de modo que los usuarios no tengan acceso directo a las tablas o vistas, aunque esta solución tiene otros impactos.

Además de estas acciones, usted puede beneficiarse del registro explícito de las consultas realizadas, ya sea desde su script o por la base de datos misma, si ésta soporta la gestión de registros. Por supuesto, el registro de acciones no puede prevenir cualquier intento peligroso, pero puede ser útil para rastrear cuáles aplicaciones han sido usadas para violar la seguridad. El registro en sí no es útil; lo es la información que contiene. Por lo general, es mejor contar con más detalles que con menos.


Reporte de Errores

Hablando de la seguridad en PHP, hay dos caras en lo que se concierne al reporte de errores. Una es benéfica al incremento de la seguridad, la otra va en dirección de su detrimento.

Una táctica de ataque típica involucra la acumulación de un perfil de datos del sistema alimentándolo con datos inapropiados, y luego chequear los tipos de errores que son devueltos, y sus contextos. Esto permite que el cracker del sistema pueda adquirir información del servidor, para así determinar posibles debilidades. Por ejemplo, si un atacante ha recogido información sobre una página creada a partir de los datos de un formulario, él podría intentar sobrescribir las variables, o modificarlas:

Ejemplo 15-11. Ataque a Variables con una página HTML personalizada

<form method="post" action="destino_del_ataque?username=badfoo&amp;password=badfoo">
<input type="hidden" name="username" value="badfoo" />
<input type="hidden" name="password" value="badfoo" />
</form>

Los errores de PHP que son devueltos normalmente pueden ser bastante útiles para un desarrollador que esté tratando de depurar un script, indicando cosas como la función o archivo que falló, el archivo PHP y el número de línea en donde ocurren los fallos. Toda esta es información de la que puede sacarse provecho. No es extraño que un desarrollador php use show_source(), highlight_string(), o highlight_file() como medida de depuración, pero en un sitio en producción, esta acción puede exponer variables ocultas, sintaxis sin chequear, y otra información peligrosa. Algo especialmente peligroso es ejecutar código que proviene de fuentes bien conocidas con gestores de depuración incorporados, o que usan técnicas de depuración comunes. Si el atacante puede determinar qué técnica general está usando, puede intentar un ataque de fuerza bruta sobre una página, enviando varias cadenas comunes de depuración:

Ejemplo 15-12. Explotación de variables comunes de depuración

<form method="post" action="destino_del_ataque?errors=Y&amp;showerrors=1&amp;debug=1">
<input type="hidden" name="errors" value="Y" />
<input type="hidden" name="showerrors" value="1" />
<input type="hidden" name="debug" value="1" />
</form>

Independientemente del método de gestión de errores, la capacidad de conseguir que un sistema revele sus posibles estados de error representa un camino para darle información al atacante.

Por ejemplo, el estilo mismo de un error de PHP genérico indica que el sistema está ejecutando PHP. Si el atacante estuviera viendo una página .html, y quisiera consultar qué está siendo usado para la generación de ella por detrás (en busca de debilidades conocidas en el sistema), podría determinar que el sistema fue creado usando PHP alimentándolo con información equivocada.

Un error de función puede indicar si el sistema está ejecutando un tipo particular de motor de base de datos, o dar pistas sobre cómo fue programada o diseñada una página web. Esto facilita posteriores investigaciones en determinados puertos abiertos de bases de datos, o en busca de fallos específicos o debilidades en una página web. Al entregar diferentes trozos de datos inválidos al sistema, por ejemplo, un atacante puede determinar el orden de autenticación en un script, (a partir de los números de línea de los errores) así como averiguar sobre vulnerabilidades que pueden aprovecharse en diferentes puntos del script.

Un error del sistema de archivos o en general de PHP puede indicar qué permisos tiene el servidor web, así como la estructura y organización de los archivos en el servidor web. Algún código de gestión de errores escrito por el desarrollador puede agravar este problema, llevando a la fácil explotación de información hasta entonces "escondida".

Existen tres soluciones principales a este problema. La primera es revisar cuidadosamente todas las funciones, y tratar de compensar por la mayoría de errores encontrados. La segunda es deshabilitar el reporte de errores completamente del código que está siendo ejecutado. La tercera es usar las funciones de gestión de errores personalizables de PHP para crear su propio gestor de errores. Dependiendo de su política de seguridad, puede encontrar que todas ellas pueden ser aplicables a su situación.

Una forma de detectar este problema por adelantado es hacer uso del reporte de errores propio de PHP (error_reporting()), para ayudarle a asegurar su código y encontrar uso de variables que pueda ser peligroso. Al probar su código, previamente a su entrega final, con E_ALL, puede encontrar rápidamente áreas en donde sus variables pueden estar abiertas a la manipulación y explotación en distintas formas. Una vez esté listo para liberar su código, usando E_NONE puede aislarlo de posibles intentos por adquirir información útil para un atacante.

Ejemplo 15-13. Detección de variables peligrosas con E_ALL

<?php
if ($nombre_usuario) {  // Variable no inicializada o chequeada antes de su uso
    $login_correcto = 1;
}
if ($login_correcto == 1) { // Si la condicion anterior falla, esta variable
                            // no se encuentra inicializada ni validada
                            // antes de su uso

    readfile ("/informacion/altamente/confidencial/index.html");
}
?>


Uso de Register Globals

Quizás el cambio más controversial en la historia de PHP se ha dado cuando la directiva register_globals pasó de tener como valor por defecto ON al valor OFF en PHP 4.2.0. La dependencia sobre esta directiva era bastante común y muchas personas nisiquiera estaban enteradas de que existía y asumían que ese era el modo en que PHP trabajaba. Esta página explicará cómo puede llegar a escribirse código inseguro con esta directiva pero tenga en mente que no es la directiva misma la que es insegura sino el uso inapropiado de ella.

Cuando se encuentra activa, la directiva register_globals inyectará (o envenenará) sus scripts con todo tipo de variables, como variables de peticiones provenientes de formularios HTML. Esto junto con el hecho de que PHP no requiere la inicialización de variables significa que es muy fácil escribir código inseguro. Fue una decisión difícil, pero la comunidad de PHP decidió desahibilar esta directiva por defecto. Cuando está habilitada, las personas usan variables sin saber con seguridad de dónde provienen y solo queda asumir. Las variables internas que son definidas en el script mismo son mezcladas con los datos enviados por los usuarios y al deshabilitar register_globals se modifica este comportamiento. Demostremos este caso con un ejemplo del uso incorrecto de register_globals:

Ejemplo 15-14. Ejemplo del uso inapropiado de register_globals = on

<?php
// definir $autorizado = true solo si el usuario ha sido autenticado

if (usuario_autenticado()) {
    $autorizado = true;
}

// Ya que no inicializamos $autorizado como false, esta podria estar
// definida a traves de register_globals, como en el caso de GET
// auth.php?autorizado=1

// De modo que cualquier persona podria verse como autenticada!

if ($autorizado) {
    include "/datos/muy/importantes.php";
}
?>

Cuando register_globals = on, nuestra lógica anterior podría verse comprometida. Cuando la directiva está deshabilitada, $autorizado no puede definirse a través de peticiones, así que no habrá ningún problema, aunque es cierto que siempre es una buena práctica de programación inicializar las variables primero. Por ejemplo, en nuestro ejemplo anterior pudimos haber realizado primero algo como $authorized = false. Hacer esto representa que el código anterior podría funcionar con register_globals establecido a on u off ya que los usuarios no serían autorizados por defecto.

Otro ejemplo es aquel de las sesiones. Cuando register_globals = on, podríamos usar también $nombre_usuario en nuestro siguiente ejemplo, pero nuevamente usted debe notar que $nombre_usuario puede provenir de otros medios, como GET (a través de la URL).

Ejemplo 15-15. Ejemplo del uso de sesiones con register_globals on u off

<?php
// No sabriamos de donde proviene $nombre_usuario, pero sabemos que
// $_SESSION es para datos de sesion

if (isset($_SESSION['nombre_usuario'])) {
    
    echo "Hola <b>{$_SESSION['nombre_usuario']}</b>";

} else {
    
    echo "Hola <b>Invitado</b><br />";
    echo "&iquest;Quisiera iniciar su sesi&oacute;n?";

}
?>

Incluso es posible tomar medidas preventivas para advertir cuando se intente falsificar la información. Si usted sabe previamente con exactitud el lugar de donde debería provenir una variable, usted puede chequear si los datos enviados provienen de una fuente inadecuada. Aunque esto no garantiza que la información no haya sido falsificada, esto requiere que un atacante adivine el medio apropiado para falsificar la información. Si no le importa de dónde proviene la información, puede usar $_REQUEST ya que allí se incluye una mezcla de variables que provienen de datos GET, POST y COOKIE. Consulte también la sección del manual sobre el uso de variables desde fuera de PHP.

Ejemplo 15-16. Detección de envenenamiento simple de variables

<?php
if (isset($_COOKIE['COOKIE_MAGICA'])) {
    
    // COOKIE_MAGICA proviene de una cookie.
    // Asegurese de validar los datos de la cookie!

} elseif (isset($_GET['COOKIE_MAGICA']) || isset($_POST['COOKIE_MAGICA'])) {
   
   mail("admin@ejemplo.com", "Posible intento de intromision",
        $_SERVER['REMOTE_ADDR']);
   echo "Violaci&oacute;n de seguridad, el administrador ha sido alertado.";
   exit;

} else {
   
   // COOKIE_MAGICA no fue definida en este REQUEST

}
?>

Por supuesto, deshabilitar register_globals no quiere decir que su código vaya a ser seguro. Por cada trozo de datos que sea enviado por el usuario, éste debe ser chequeado en otras formas. ¡Siempre valide los datos de los usuarios e inicialice sus variables! Para chequear por variables no inicializadas, usted puede usar error_reporting() para mostrar errores del nivel E_NOTICE.

Superglobals: Nota de disponibilidad: Desde 4.1.0, están disponibles algunas matrices superglobales tales como $_GET, $_POST, y $_SERVER, etc. Para más información puede consultar la sección superglobals


Datos Enviados por el Usuario

Las mayores debilidades de muchos programas PHP no son inherentes al lenguaje mismo, sino simplemente un problema generado cuando se escribe código sin pensar en la seguridad. Por esta razón, usted debería tomarse siempre el tiempo para considerar las implicaciones de cada pedazo de código, para averiguar el posible peligro involucrado cuando una variable inesperada es enviada.

Ejemplo 15-17. Uso Peligroso de Variables

<?php
// eliminar un archivo del directorio personal del usuario .. o
// quizas de alguien mas?

unlink ($variable_malvada);

// Imprimir el registro del acceso... o quizas una entrada de /etc/passwd?
fwrite ($desc_archivo, $variable_malvada);

// Ejecutar algo trivial.. o rm -rf *?
system ($variable_malvada);
exec ($variable_malvada);

?>
Usted debería examinar siempre, y cuidadosamente su código para asegurarse de que cualquier variable siendo enviada desde un navegador web sea chequeada apropiadamente, y preguntarse a sí mismo:

  • ¿Este script afectará únicamente los archivos que se pretende?

  • ¿Puede tomarse acción sobre datos inusuales o indeseados?

  • ¿Puede ser usado este script en formas malintencionadas?

  • ¿Puede ser usado en conjunto con otros scripts en forma negativa?

  • ¿Serán adecuadamente registradas las transacciones?

Al preguntarse adecuadamente estas preguntas mientras escribe su script, en lugar de hacerlo posteriormente, usted previene una desafortunada re-implementación del programa cuando desee incrementar el nivel de seguridad. Al comenzar con esta mentalidad, no garantizará la seguridad de su sistema, pero puede ayudar a mejorarla.

Puede que también desee considerar la deshabilitación de register_globals, magic_quotes, u otros parámetros convenientes que pueden causar confusión sobre la validez, fuente o valor de una determinada variable. Trabajar con PHP en modo error_reporting(E_ALL) también puede ayudarle a advertir variables que están siendo usadas antes de ser chequeadas o inicializadas (de modo que puede prevenir que datos inusuales produzcan operaciones inadvertidas).


Ocultando PHP

En general, la seguridad por oscuridad es una de las formas más débiles de seguridad. Pero, en algunos casos, cada pequeño elemento extra de seguridad es deseable.

Unas cuantas técnicas simples pueden ayudarle a esconder PHP, posiblemente retrasando a un atacante que esté intentando descubrir debilidades en su sistema. Al establecer expose_php = off en su archivo php.ini, usted reduce la cantidad de información disponible a posibles atacantes.

Otra táctica consiste en configurar los servidores web como apache para que procesen diferentes tipos de archivos como scripts de PHP, ya sea con una directiva .htaccess, o en el archivo de configuración de apache mismo. En ese caso puede usar extensiones de archivo que produzcan confusión:

Ejemplo 15-18. Ocultando PHP como otro lenguaje

# Hacer que el codigo PHP parezca como otro tipo de codigo
AddType application/x-httpd-php .asp .py .pl
U ocultarlo completamente:

Ejemplo 15-19. Uso de tipos desconocidos como extensiones para PHP

# Hacer que el codigo PHP parezca como de tipos desconocidos
AddType application/x-httpd-php .bop .foo .133t
O escóndalo como código HTML, lo que tiene un pequeño impacto de rendimiento ya que todos los documentos HTML serán procesados por el motor de PHP:

Ejemplo 15-20. Uso de tipos HTML para extensiones PHP

# Hacer que todo el codigo PHP luzca como HTML
AddType application/x-httpd-php .htm .html
Para que esto funcione de manera efectiva, usted debe renombrar sus archivos PHP con las extensiones anteriores. Aunque es una forma de seguridad por oscuridad, representa una medida preventiva menor con pocos inconvenientes.


Mantenerse al Día

PHP, como cualquier otro sistema de tamaño considerable, está bajo constante escrutinio y remodelación. Cada nueva versión incluye con frecuencia cambios mayores y menores para mejorar y reparar fallos de seguridad, problemas de configuración, y otros asuntos que puedan afectar la seguridad y estabilidad global de su sistema.

Como cualquier lenguaje y programa de scripting del nivel del sistema, el mejor enfoque es el de actualizar con frecuencia, y mantenerse alerta sobre las últimas versiones y sus cambios.


Capítulo 16. Autentificación HTTP con PHP

Las caracteríticas de autentificación HTTP en PHP solo están 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 será llamada de nuevo con las variables predefinidas PHP_AUTH_USER, PHP_AUTH_PW, y AUTH_TYPE asignadas con el nombre de usuario, la contraseña y el tipo de autentificación respectivamente. Estas variables predefinidas se pueden encontrar en las matrices $_SERVER y $HTTP_SERVER_VARS. Sólo autentificación "Básica" está soportada en este momento. Consulte la función header() para más información.

Nota sobre la versión PHP: Las Autoglobales, tales como $_SERVER, han estado disponibles desde la versión de PHP 4.1.0. $HTTP_SERVER_VARS ha estado disponible desde PHP 3.

Un script de ejemplo 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';
    exit;
  } else {
    echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
    echo "<p>You entered {$_SERVER['PHP_AUTH_PW']} as your password.</p>";
  }
?>

Nota de compatibilidad: Por favor tener cuidado cuando esteis programando las lineas de cabecera HTTP. Para garantizar la máxima 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 exactamente 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.

En fecha de la versión PHP 4.3.0, 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 asignadas si algún tipo de autentificación externa ha sido activada para la página en particular. En este caso, la variable REMOTE_USER puede ser usada para identificar al usuario autentificado externamente. Asi que se puedes utilizar $_SERVER['REMOTE_USER'].

Configuration Note: PHP usa la directiva AuthType para determinar si una autentificación externa esta en uso.

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']) ||
      ($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['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 cuenta que hasta la version de PHP 4.3.3, la autentificación HTTP no funcionaba con el servidor IIS de Microsoft y la versión CGI de PHP, debido a una limitación de IIS. Para que funcione a partir de PHP 4.3.3, debeis de editar vuestra configuración sobre "Seguridad en directorios" en IIS. Pulsar en 'Editar" y elegir solamente "acceso anonimo", todos los demas campos no se deben de elegir.

Otra limitación es, si estais usando el módulo de IIS (ISAPI), que no podeis usar las variables PHP_AUTH_*, en su lugar debeis utilizar la variable HTTP_AUTHORIZATION. Por ejemplo: list($user, $pw) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));

Nota para IIS:: Para que la autentificación HTTP funcione con IIS, la directiva de PHP cgi.rfc2616_headers debe de tener el valor 0 (valor por defecto).

Nota: Si safe mode está activado, el uid de el script es agregado a la cabecera WWW-Authenticate


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 matriz 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. (Siempre activada a partir de PHP 4.0.3.)

Para más detalles ver la función setcookie().


Capítulo 18. Manejo de XForms

XForms define una variación de los tradicionales formularios web que permite que éstos sean usados en una variedad más amplia de plataformas y navegadores, e incluso en medios no-tradicionales como documentos PDF.

La primera diferencia clave en XForms es el modo en que el formulario es enviado al cliente. XForms para Autores HTML contiene una descripción detallada de cómo crear XForms; para los propósitos de este tutorial, tan solo estaremos viendo un ejemplo sencillo.

Ejemplo 18-1. Un formulario XForms de búsqueda simple

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>B&uacute;squeda</h:title>
 <model>
  <submission action="http://example.com/buscar"
              method="post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Buscar</label></input>
  <submit submission="s"><label>Iniciar</label></submit>
 </h:p>
</h:body>
</h:html>

El anterior formulario despliega una caja de entrada de texto (llamada q), y un botón de enviar. Cuando el botón de enviar es pulsado, el formulario será enviado a la página indicada por action.

Aquí es en donde empieza a lucir diferente desde el punto de vista de su aplicación web. En un formulario HTML normal, los datos serían enviados como application/x-www-form-urlencoded, sin embargo, en el mundo de XForms, esta información es enviada como datos en formato XML.

Si ha tomado la decisión de trabajar con XForms, entonces probablemente quiera los datos en XML, en ese caso, debe echar un vistazo a $HTTP_RAW_POST_DATA en donde encontrará el documento XML generado por el navegador, el cual puede pasar a su motor XSLT o intérprete de documentos favorito.

Si no se encuentra interesado en dar formato, y sólo desea que los datos sean cargados en la variable $_POST tradicional, puede indicarle al navegador del cliente que envíe sus datos como application/x-www-form-urlencoded modificando el atributo method al valor urlencoded-post.

Ejemplo 18-2. Uso de un XForm para poblar $_POST

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>B&uacute;squeda</h:title>
 <model>
  <submission action="http://example.com/search"
              method="urlencoded-post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Buscar</label></input>
  <submit submission="s"><label>Iniciar</label></submit>
 </h:p>
</h:body>
</h:html>

Nota: Al momento en que se escriben estas líneas, muchos navegadores no ofrecen soporte para XForms. Revise la versión de su navegador si el anterior ejemplo falla.


Capítulo 19. Manejo de envío de archivos

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 19-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 19-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 19-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 20. Usando archivos remotos

Siempre que allow_url_fopen esté habilitado en php.ini, se pueden usar URLs HTTP y FTP con la mayoría de las funciones que toman un archivo como parámetro. Además URLs pueden ser usadas con include(), include_once(), require() y require_once(). Consultar Apéndice L para más información sobre los protocolos soportados por PHP.

Nota: En PHP 4.0.3 y versiones anteriores, para usar envolturas URL, habia que configurar PHP usando la opción de configuración --enable-url-fopen-wrapper.

Nota: Las versiones para windows de PHP, anteriores a PHP 4.3 no soportaban acceso remoto a ficheros en las funciones siguientes: include(), include_once(), require(), require_once(), y las funciones imagecreatefromXXX de la extensión Referencia XLII, Funciones para imágenes.

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 20-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 servidor FTP (siempre que se conecte como un usuario con los correctos derechos de acceso). Solamente se pueden crear nuevos ficheros usando este método; si se intenta sobreescribir un fichero ya existente, la función fopen() fallará

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 20-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, $_SERVER['HTTP_USER_AGENT'] . "\n");
fclose ($file);
?>

Nota: Podeis creer por el ejemplo anterior, que podeis usar esta tecnica para escribir en un fichero de registro remoto. Desgraciadamente no funcionaria porque la llamada fopen() fallaria si el fichero remoto existe. Para usar registros distribuidos de esa manera podeis consultar la funcion syslog().


Capítulo 21. 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 22. Conexiones persistentes a bases de datos

Las conexiones persistentes son enlaces 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).

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, 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 16 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!

Ver tambien fbsql_pconnect(), ibase_pconnect(), ifx_pconnect(), imap_popen(), ingres_pconnect(), msql_pconnect(), mssql_pconnect(), mysql_pconnect(), ociplogon(), odbc_pconnect(), ora_plogon(), pfsockopen(), pg_pconnect() y sybase_pconnect().


Capítulo 23. 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 23-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 23-2. Funciones limitadas por Modo Seguro

FunciónLimitaciones
dbmopen()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
dbase_open()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
filepro()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
filepro_rowcount()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
filepro_retrieve()Comprueba que los archivos/directorios que va a utilizar, tengan 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()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
posix_mkfifo()Comprueba si el directorio que vaa a utilizar, tiene 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()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
chdir()Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado.
dl()Esta función no está habilitada en safe-mode (modo-seguro)
backtick operatorEsta función no está habilitada en safe-mode (modo-seguro)
shell_exec() (equivalencia funcional de backticks)Esta función no está habilitada 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()Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado.
rmdir()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
rename()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado.
unlink()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado.
copy()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado. (en source y target)
chgrp()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
chown()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado.
chmod()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Además, Ud. no puede setear los bits de SUID, SGID y sticky
touch()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado.
symlink()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado. (Nota: sólo el target es comprobado)
link()Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene 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() Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene la misma UID que el script que está siendo ejecutado. (Nota: sólo afectado desde PHP 4.2.1)
parse_ini_file() Comprueba que los archivos/directorios que va a utilizar, tengan la misma UID que el script que está siendo ejecutado. Comprueba si el directorio que vaa a utilizar, tiene 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 24. Usando PHP desde la línea de comando

Desde la versión 4.3.0, PHP soporta un nuevo tipo de SAPI (Interfaz De Programación De Uso Del Servidor) llamada CLI que significa literalmente interfaz de línea de comando (Command Line Interface). Como el nombre implica, este tipo de SAPI se foca en la creación de aplicaciones que pueden correr desde la línea de comando (o desde el desktop también) con PHP. Hay algunas diferencias dentro del CLI SAPI y otros SAPI que son explicadas en este capítulo. Es importante mencionar que CLI y CGI son diferentes clases de SAPI y comparten algunas características.

La interfaz llamada CLI SAPI fue introducida con PHP 4.2.0, pero es todavía en estado experimental y tiene que ser activada explícitamente con --enable-cli cuando usando ./configure. Desde PHP 4.3.0 la interfaz CLI SAPI es activada automáticamente. Tu puedes usar --disable-cli para de-activarla.

Desde PHP 4.3.0, el nombre, locación, y existencia de los binarios CLI/CGI serán diferentes dependiendo en como Instales PHP en tu sistema. Cuando ejecutes make, CGI, y CLI son compilados automáticamente, y puestas como sapi/cgi/php y sapi/cli/php respectivamente, en el directorio "source" de PHP. Debes notar, que los dos son llamados php. Lo que ocurre durante el proceso make depende en tu línea de configuración (./configure). Si el modulo SAPI es seleccionado durante tu configuración, como por ejemplo apxs, o la opción --disable-cgi es usada, el CLI es copiado a {PREFIX}/bin/php durante la ejecución del comando make install de otras maneras el CGI es instalado aquí. Por ejemplo, si pones --with-apxs en tu configuración, entonces el CLI es copiado a {PREFIX}/bin/php durante make install. Si tu quieres sobrescribir la instalación del CGI binario, utiliza make install-cli después de usar make install. Alternativamente puedes especificar --disable-cgi en tu línea de configuración.

Nota: Por que ambos --enable-cli y --enable-cgi son activados automáticamente, simplemente teniendo --enable-cli en tu línea de configuración no necesariamente significa que CLI son copiados a {PREFIX}/bin/php durante make install.

Los archivos de PHP 4.2.0 y PHP 4.2.3 distribuían el CLI como php-cli.exe, y los mantenía en el mismo directorio que el CGI php.exe. Empezando con PHP 4.3.0 el archivo para windows distribuye el CLI como php.exe en un directorio llamado cli; o sea cli/php.exe.

Que versión de SAPI tengo?: Desde tu línea de comando, ejecutando php -v te dejara saber si php es CGI o CLI.

Diferencias remarcables del CLI SAPI comparadas con otros SAPIs: SAPIs:

  • En esta clase de CGI SAPI no hay cabeceras ("headers") escritas en el resultado ("output").

    Aunque el CGI SAPI provee una manera de suprimir HTTP cabeceras ("headers"), no existe una opción equivalente que los activa en el CLI SAPI.

    CLI automáticamente empieza en modo silencioso, la opción -q existe por compatibilidad con antiguos programas CGI.

    No cambia el directorio corriente, a ese en el cual el programa vive. La opción -C es mantenida por compatibilidad.

    Errores son reportados en texto, no en el formato HTML.

  • Hay ciertas directivas en el php.ini que son sobrescrita por el CLI SAPI por que estas no hacen mucho sentido en situaciones donde la línea de comando es usada:

    Tabla 24-1. Directivas sobrescrita en php.ini

    Directivas (directives)CLI SAPI evaluó automático (default value)Commentario (comment)
    html_errorsFALSE Cuando los resultados incorrectos aparecen en tu línea de comando, puede ser difícil hacer sentido de ellos con todas esas HTML tags, por esta razón, esta directiva es automáticamente FALSE.
    implicit_flushTRUE Es deseoso que los resultados de print (imprimir)(), echo (ecco)() y otras relacionadas, sean inmediatamente escritas como resultados y no mantenidas en ningún buffer. Tu todavía puedes usar output buffering si tu quieres manipular los resultados proveidos automáticamente.
    max_execution_time0 (unlimited) Debido un numero ilimitado de posibilidades de usar PHP en la línea de comando, el máximo tiempo de ejecución es ilimitado. Aunque aplicaciones escritas para el Internet, usualmente requieres una rápida ejecución, la clase de aplicación que es ejecutada desde la línea de comando, usualmente necesitan mas tiempo para ejecutar correctamente.
    register_argc_argvTRUE

    Por que estas opciones son TRUE tu siempre necesitaras acceso al argc (el numero de argumentos pasados a la aplicación) y argv (el array de argumentos) en el CLI SAPI.

    Desde la versión 4.3.0 de PHP, las variables $argc y $argv son registradas y llenadas con los resultados apropiados cuando usando CLI SAPI. Antes de esta versión, la creación de estas variables es similar a como en CGI y MODULE versiones que requiere la PHP directiva register_globals estar on (active). Sin importar la versión o la configuración de register_globals tu siempre puedes trabajar por medio de $_SERVER o $HTTP_SERVER_VARS. Por ejemplo: $_SERVER['argv']

    Nota: Estas instrucciones no pueden ser iniciadas con valores que son diferentes a los de la configuración en php.ini o el archivo correspondiente. Esta es una limitación dada por que esos valores automáticos, son aplicados después de que todos los archivos conteniendo parámetros de configuración an sido ejecutados; PERO, esto valores pueden ser cambiados mientras to programa esta ejecutando (esto no hace sentido para todas las directivas, como por ejemplo register_argc_argv).

  • Para facilitar trabajando en la línea de comando, las siguientes constantes son definidas:

    Tabla 24-2. constantes especificas de CLI

    Constant (constante)Description (descripción)
    STDIN Una stream abierta hacia stdin. Esto nos salva de abrirla con
    $stdin = fopen('php://stdin', 'r');
    STDOUT Una stream abierta hacia stdout. Esto nos salva de abrirla con
    $stdout = fopen('php://stdout', 'w');
    STDERR Una stream abierta hacia stderr. Esto nos salva de abrirla con
    $stderr = fopen('php://stderr', 'w');

    Dado lo anterior, tu no necesitas abrir, como por ejemplo, una stream hacia stderr manualmente, solamente necesitas usar la constante en vez de usar los recursos de la stream:
    php -r 'fwrite(STDERR, "stderr\n");'
    No necesitas cerrar estas stream explícitamente, desde que son cerradas automáticamente por PHP cuando tu programa termina.

  • El CLI SAPI no cambia el directorio en el cual to estas corrientemente, al directorio donde el programa ejecutado vive!

    Ejemplo mostrando la diferencia al CGI SAPI:
    <?php
        /* Nuestra aplicaci&oacute;n llamada.php*/
        echo getcwd(), "\n";
    ?>

    Cuando usas la versión CGI el resultado es:
    $ pwd
    /tmp
    
    $ php -q otro_directorio/test.php
    /tmp/otro_directorio
    Esto claramente muestra que PHP cambia su directorio al usado por el programa que ejecutas.

    Usando el CLI SAPI resulta:
    $ pwd
    /tmp
    
    $ php -f otro_directorio/test.php
    /tmp
    Esto no da mas flexibilidad cuando escribiendo utilidades en la línea de comando con PHP.

    Nota:

Puedes obtener acceso a la lista de opciones proveida por PHP ejecutando PHP con el -hswitch:
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
Aunque los resultados anteriores siempre serán dados en ingles, a continuación te daré una lista que probablemente sera muy útil:
Usage: php [options] [-f] <file> [args...]
         php [options] -r <code> [args...]
         php [options] [-- args...]
    -s               Display colour syntax highlighted source.  
                     (colorear el sintaxis en el c&oacute;digo)
    -w               Display source with stripped comments and whitespace.
                     (remueve los comentarios y espacios del c&oacute;digo) 
    -f <file>        Parse <file>.
                     (analiza <file>)
    -v               Version number
                     (la versi&oacute;n de PHP que estas usando)
    -c <path>|<file> Look for php.ini file in this directory
                     (usa el php.ini archivo localizado aqu&iacute;)
    -a               Run interactively
                     (interactivo)
    -d foo[=bar]     Define INI entry foo with value 'bar'
                     (define foo con el valor 'bar' en php.ini)
    -e               Generate extended information for debugger/profiler
                     (genera mas informaci&oacute;n para el debugger/profiler) 
    -z <file>        Load Zend extension <file>.
                     (inicia las exenciones Zend <archive>)
    -l               Syntax check only (lint)
                     (Mira al sintaxis (lint))
    -m               Show compiled in modules
                     (muestra los m&oacute;dulos compilados)
    -i               PHP information
                     (informaci&oacute;n PHP)
    -r <code>        Run PHP <code> without using script tags <?..?>
                     (ejecuta PHP <code> sin usar las tags <?..?> en el script
    -h               This help
                     (estas opciones)  
    args...          Arguments passed to script. Use -- args when first argument 
                     starts with - or script is read from stdin
                     (Argumentos pasados al programa. Usa -- args cuando el primer 
                     argumento empieza con - o tu programa es le&iacute;do directamente desde stdin)

El CLI SAPI tiene tres diferentes maneras de obtener el código PHP que tu quieres ejecutar:

  1. Puedes decir a PHP que ejecute ciertos archivos.

    php my_script.php
    
    php -f my_script.php
    En estos dos ejemplos (aunque utilices el switch -f o no) ejecutan el archivo my_script.php. Tu puedes escoger cualquier archivo para ejecutar - tus programas PHP no tienen que terminar con la exención .php y pueden tener cualquier otra exención tu desees.

  2. Pasa el código PHP para que sea ejecutado directamente en la línea de comando.

    php -r 'print_r(get_defined_constants());'
    Debes tener cuidado en reguardo a las substituciones variables en tu línea de comando y usando comillas(").

    Nota: Deves ponerle atención al ejemplo, y notaras que no tiene tags ni al principio ni al final, el comando -r simplemente no las usa. Usando las tags te dará un error cuando trates de ejecutar el programa.

  3. Provee el código PHP para ejecutar por medio de stdin

    Esto te da la habilidad de dinámicamente crear código PHP y mandarlo al programa, como por ejemplo a continuación:
    $ some_application | some_filter | php | sort -u >final_output.txt

Tu no puedes combinar ninguna de las tres formas de ejecutar el código.

Como cualquier aplicación ejecutada en la línea de comando, el PHP binario acepta un numero de argumentos y tu programa también puede recibir argumentos. El numero de argumentos que pueden ser pasados a tu programa no es limitado por PHP (la línea de comando tiene limitaciones en el numero de símbolos que pueden ser pasados; usualmente tu nunca alcanzarías este limite). Los argumentos pasados a tu programa, están disponibles en tu array global $argv. El índex cero ("0") siempre contiene el nombre de tu programa (que es - en caso de código que esta viniendo por medio del input estándar, o del switch en la línea de comando -r. La segunda variable global registrada es $argc y contiene el numero de elementos en el array $argv (no el numero de argumentos pasados as programa).

Mientras el argumento que tu quieres pasas a tu programa no comienza con -, no tienes que esperar por nada especial. Pero si el argumento empieza con -, te puede generar problemas, por que PHP pensara que tiene que procesarlo. Para prevenir esto, usa la lista separadora de argumentos: --. Después de que el separador a sido procesado, cada siguiente argumento es pasado sin tocar a tu programa.

# This will not execute the given code but will show the PHP usage
# Esto no ejecutara el c&oacute;digo pero PHP mostrara el uso
$ 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
# passaremos el argumento '-h' a tu programa y prevenira que PHP demuestre su uso 
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Pero, existe otra manera de usar PHP en la línea de comando. Tu puedes escribir un programa donde la primera línea empieza con #!/usr/bin/php (donde /usr/bin/php es la locación de php). Después de esto, tu puedes usar PHP común y corriente. Una vez que tu le as dado permiso de ejecución a tu programa (por ejemplo +x test) tu programa puede ser ejecutado como si fuera digamos un programa en perl:
#!/usr/bin/php
<?php
    var_dump($argv);
?>
Asumiremos que el archivo es llamado test, y esta en el mismo directorio en el cual to estas, en ese caso, podemos hacer lo siguiente.
$ chmod 755 test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}
Como puedes ver, en este caso no atención es dada a pasar los parámetros que comiensen con - en tu programa.

Tabla 24-3. Opciones en la línea de comando

OpcionesDescripcion
-s

colora el sintaxis de tu código

Esta opción usa un mecanismo interno para ejecutar el archivo, y produce una versión coloreada en HML y la escribe como output normal. Nota que todo lo que hace es generar un bloque de <code> [...] </code> HTML tags, no cabecera deHTML es creada.

Nota: Esta opción no trabaja en conjunto con -r.

-w

Te mostrara tu código sin comentarios ni espacios blancos.

Nota: Esta opción no trabaja en conjunto con -r.

-f

Ejecuta el archivo indicado en la opción -f. Esta opción es opcional y puede ser excluida. Solamente proveiendo el archivo que necesita ser ejecutado es suficiente.

-v

Escribe la version de PHP, PHP SAPI y Zend al output normal, por ejemplo:
$ 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

Con esta opción uno puede especificar el directorio donde encontraremos el php.ini archivo, o tu puedes especificar una versión única del mismo (la cual no tiene que ser llamada php.ini), por ejemplo:
$ php -c /costumatisado/directorio/ mi_programa.php

$ php -c /customatisado/directorio/customatisado-archivo.ini mi_programa.php

-a

Corre PHP interactivamente.

-d

Esta opción te hayudara a crear el valor de cualquier directiva de configuración permitidas en el php.ini archivo. El sintaxis es:
-d directiva__de_configuracion [=valor]

Ejemplos:
# Omitting the value part will set the given configuration directive to "1"
# Omitiendo la parte relacionada al valor, le asignara a la directiva de configuracion el valor # "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 ""
# Pasando un valor vac&iacute;o, le asignara a la directiva de configuraci&oacute;n el valor ""
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
# la directiva de configuraci&oacute;n sera asignada a todo pasada el "=" simbolo
$  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

Generando mas información para el debugger/profiler.

-z

Activa las extensiones Zend. Si solamente un archivo es dado, PHP tratará de activar estas extensiones directamente desde el directorio predeterminado donde esté la biblioteca en su sistema (Usualmente especificado /etc/ld.so.conf en Linux). Pasando el nombre del archivo con descripción absoluta de la ubicación de sus archivos, no usará las bibliotecas en su sistema. Un archivo conteniendo la información de estos directorios, le dira a PHP que solamente trate de activar las extensiones relativas al directorio donde te encuentras

-l

Esta opción proveerá una forma conveniente para marcar tu sintaxis en tu código. En caso de suceso, el texto "No sintax errors detected in <filename> (no errores de sintaxis fueron detectados) es escrito en tu output normal, y la línea de comando retornara el código 0. En caso de problemas, el texto Errors parsing <filename>, en adición al la forma interna de detectar errores, mensajes son escritos como output normal y tu línea de comando recibirá el código 255

Esta opción no encontrara errores fatales (como por ejemplo funciones indefinida), usa -f si tu quieres probar por esta clase de errores también.

Nota: Esta opción no trabaja en conjunción con -r

-m

Usando esta opción, PHP imprime sus módulos internos (y activados) usados por PHP y Zend:
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-i Esta opción llama phpinfo, e imprime los resultado. Si PHP no esta trabajando correctamente, es recomendable que uses esta opción observes si algún mensaje es imprimido antes de, o en medio de la información dada por esta opción. Es un detalle importante que entiendas que el mensaje imprimido es en HTML y por esta razón grandecito.
-r

Esta opción te ayudara a ejecutar PHP directamente desde la línea de comando. Las etiquetas que determinas el principio y al final de tu programa (<?php y ?>) no son necesarias y causaran errores si las pones en tu código.

Nota: Debes tener cuidado cuando usando esta forma de PHP para que no crees conflicto con la substitución de variables usada por la línea de comando.

Ejemplos de errores
$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
El problema aquí es que sh/bash esta haciendo una substitución de variables, aunque las comillas (") están presentes. Desde que la variable $foo probablemente no esta definida, esta no se inflara en ninguna dirección, el resultado es que el código pasado a PHP para que ejecute realmente lee:
$ php -r " = get_defined_constants();"
La forma correcta de hacer esto, seria usando solamente una comilla ('), variables usando solamente una comilla no son infladas por 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"]=>
  [...]
Si tu no estas usando sh/bash, también puedes encontrar otros problemas. Por favor reporta estos problemas mandando un e-mail a phpdocs@lists.php.net Tu también puedes tener problemas si tratas de poner variables en tu código o cuando usas "/" como símbolos de escape. Te hemos advertido

Nota: -r esta listo en CLI SAPI y no en el CGI SAPI.

-h Con esta opción, tu puedes obtener información acerca de las opciones describías anteriormente, y una breve descripción acerca de sus funciones.

PHP puede ejecutar tus programas absolutamente independiente de tu servidor de páginas de web. Si tu usas Unix, tu puedes añadir una línea especial al principio de tu programa, y hacerlo ejecutable, para que el sistema sepa que programa debe ejecutar tu nueva creación. Si usas windows, tu puedes asociar tu programa con php.exe para que solamente tengas que ejecutarlo como harías con otros programas bajo windows, también puedes crear un "batch" archivo para ejecutar tu programa por medio de PHP. La primera línea que usaste para hacer que tu programa funcione en Unix, no le ara daño a tu programa cuando ejecutad bajo windows, pero de esta manera puedes crear programas que puedes ser usados bajo las dos plataformas. A continuación te daremos un ejemplo:

Ejemplo 24-1. Programa para correr en la línea do comando (script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

Este es un programa en php entendido para la l&iacute;nea de 
comando con una opci&oacute;n. 

  Usage:
  <?php echo $argv[0]; ?> <option>

  <option> puede ser cualquier palabra que tu quieras
  imprimir. Con la opci&oacute;n --help, -help -h or -?, tu puedes
  obtener esta informaci&oacute;n

<?php
} else {
    echo $argv[1];
}
?>

En el programa anterior, usamos una línea especial como nuestra primera línea, para indicar que archivo deber ser ejecutado por PHP. Nosotros trabajamos con una versión de CLI aquí, por eso, no tendremos cabeceras de HTTP imprimidas. Hay dos variables que puedes usar cuando escribiendo aplicaciones en la línea de comando en PHP: $argc y $argv. La primera es el numero de argumentos mas uso (el nombre del programa siendo ejecutado). La segunda es un array conteniendo los argumentos, empezando con el programa nombre, y el numero cero "0" ($argv[0]).

En el programa anterior chequeamos si habían mas, o menos de dos argumentos. También trata de ver si --help, -help, -h o -?, son llamados, e imprime el mensaje de ayuda.

Si tu quieres ejecutar el programa anterior en Unix, tu tienes que hacerlo ejecutable, y simplemente llamado script.php echo this o script.php -h. En windows, tu puedes hacer un batch archivo para alcanzar estos resultados:

Ejemplo 24-2. Archivo batch para ejecutar el programa php (script.bat)

@c:\php\cli\php.exe script.php %1 %2 %3 %4

Asumiendo que llamaste el programa descrito anteriormente script.php , Y que tienes tu CLI php.exe en c:\php\cli\php.ese este archivo batch, lo ejecutara para ti con las funciones añadidas: script.bat echo this o script.bat -h.

Mira también la documentación de Readline para mas funciones que puedes usar para incrementar tus opciones en este sujeto.

V. 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. Funciones COM y .Net (Windows)
IX. Funciones de Clases/Objetos
X. Funciones ClibPDF
XI. Crack Functions
XII. Funciones CURL (Client URL Library)
XIII. Funciones de pago electrónico
XIV. Cyrus IMAP administration Functions
XV. Funciones de Tipo de Caracter
XVI. Funciones de la capa de abstraccion de bases de datos (dbm-style)
XVII. Funciones de Fecha y Hora
XVIII. Funciones para dBase
XIX. Funciones DBM Functions [obsoletas]
XX. dbx Functions
XXI. DB++ Functions
XXII. Funciones de acceso directo a E/S
XXIII. Funciones de Directorio
XXIV. DOM Functions
XXV. Funciones DOM XML
XXVI. .NET Functions
XXVII. Funciones de Gestión de Errores y Registros
XXVIII. File Alteration Monitor Functions
XXIX. FrontBase Functions
XXX. Funciones filePro
XXXI. Funciones del Sistema de Archivos
XXXII. Funciones del Formato de Datos de Formulario
XXXIII. FriBiDi Functions
XXXIV. Funciones FTP
XXXV. Funciones de Gestión de Funciones
XXXVI. Gettext
XXXVII. GMP Functions
XXXVIII. Funciones HTTP
XXXIX. Funciones para Hyperwave
XL. Hyperwave API Functions
XLI. iconv Functions
XLII. Funciones para imágenes
XLIII. Funciones IMAP, POP3 y NNTP
XLIV. Funciones de Informix
XLV. Funciones InterBase
XLVI. ID3 Functions
XLVII. Ingres II functions
XLVIII. IRC Gateway Functions
XLIX. Integración de Java y PHP
L. Funciones LDAP
LI. LZF Functions
LII. Funciones de Correo
LIII. Funciones mailparse
LIV. Funciones matemáticas
LV. Multibyte String Functions
LVI. MCAL functions
LVII. Funciones de Cifrado Mcrypt
LVIII. MCVE Payment Functions
LIX. Funciones Mhash
LX. Funciones Mimetype
LXI. Funciones de Microsoft SQL Server
LXII. Ming functions for Flash
LXIII. Funciones de Miscelánea
LXIV. mnoGoSearch Functions
LXV. Funciones mSQL
LXVI. Funciones MySQL
LXVII. Extensión mejorada de MySQL
LXVIII. Mohawk Software Session Handler Functions
LXIX. muscat Functions
LXX. Funciones de Red
LXXI. Funciones de Control de Pantalla con Terminal Ncurses
LXXII. Lotus Notes Functions
LXXIII. NSAPI-specific Functions
LXXIV. ODBC functions
LXXV. Object Aggregation/Composition Functions
LXXVI. Funciones de Oracle 8
LXXVII. OpenSSL Functions
LXXVIII. Funciones Oracle
LXXIX. Ovrimos SQL functions
LXXX. Funciones de Control de Salida
LXXXI. Object property and method call overloading
LXXXII. Funciones PDF
LXXXIII. Verisign Payflow Pro functions
LXXXIV. Opciones e Información de PHP
LXXXV. Funciones POSIX
LXXXVI. Funciones PostgreSQL
LXXXVII. Process Control Functions
LXXXVIII. Funciones de Ejecución de Programas
LXXXIX. Printer Functions
XC. Pspell Functions
XCI. GNU Readline
XCII. Funciones GNU Recode
XCIII. Funciones de Expresiones Regulares (Compatibles con Perl)
XCIV. qtdom Functions
XCV. Funciones de Expresiones Regulares (POSIX Extendido)
XCVI. Funciones Semáforo y de memoria compartida
XCVII. SESAM database functions
XCVIII. Funciones para el manejo de sesiones
XCIX. Funciones de Memoria Compartida
C. SimpleXML functions
CI. SOAP Functions
CII. SQLite
CIII. Shockwave Flash functions
CIV. Funciones SNMP
CV. Funciones de Socket
CVI. Standard PHP Library (SPL) Functions
CVII. Funciones de Secuencias
CVIII. Funciones de Cadenas
CIX. Funciones de Sybase
CX. TCP Wrappers Functions
CXI. Tidy Functions
CXII. Tokenizer Functions
CXIII. Funciones de URL
CXIV. Funciones de Variables
CXV. vpopmail Functions
CXVI. W32api Functions
CXVII. Funciones WDDX
CXVIII. Funciones de intérprete XML
CXIX. XML-RPC Functions
CXX. xdiff Functions
CXXI. XSL functions
CXXII. XSLT functions
CXXIII. YAZ
CXXIV. NIS funciona
CXXV. Funciones de manejo de archivos Zip (sólo lectura)
CXXVI. Funciones de Compresión Zlib

I. Funciones específicas de Apache

Introducción

Estas funciones están disponibles solamente cuando PHP se ejecuta como módulo de Apache 1.x.


Instalación

Información sobre la instalación de PHP con Apache se puede encontrar en el capítulo sobre instalación en la sección sobre Apache


Configuración en tiempo de ejecución

El comportamiento del módulo PHP de Apache está sujeto a los parámetros ajustados en php.ini. Los parámetros ajustados mediante php_flag en el archivo de configuración del servidor o archivos .htaccess locales, tendrán preferencia sobre aquellos ajustados en php.ini.

Ejemplo 1. Desactivar el intérprete PHP en un directorio utilizando .htaccess

php_flag engine off

Tabla 1. Opciones de configuración de Apache

NombrePor defectoModificableFunción
engineOnPHP_INI_ALLhabilita o desactiva el intérprete PHP
child_terminateOffPHP_INI_ALL especifica si los scripts PHP pueden requerir la terminación del proceso hijo al acabar un requerimiento. Véase también apache_child_terminate()
last_modifiedOffPHP_INI_ALLenviar la fecha de modificación de los scripts PHP como la fecha de la última modifición en la cabecera del requerimiento actual
xbithackOffPHP_INI_ALLinterpretar los archivos cuyo bit ejecutable esté fijado a PHP, independientemente de su extensión

A continuación se presenta una corta explicación de las directivas de configuración.

engine boolean

Esta directiva realmente sólo es útil cuando PHP es un módulo de Apache. Se utiliza para sitios que quieran activar o desactivar el intérprete de PHP en función del directorio o del host-virtual. Añadiendo engine off en los lugares apropiados del archivo httpd.conf, PHP puede ser habilitado o desactivado.


Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.


Constantes predefinidas

Esta extensión no tiene ninguna constante definida.

Tabla de contenidos
apache_child_terminate -- Terminar un proceso de apache una vez concluido el requerimiento en ejecució
apache_get_modules --  Obtiene una lista de los modulos cargados con el servidor Apache
apache_get_version --  Obtiene la version de Apache
apache_getenv --  Obtiene una variable subprocess_env de Apache
apache_lookup_uri --  Realiza una petición parcial por la URI especificada y devuelve toda la información sobre ella
apache_note -- Obtener y establecer las notas de petición de apache
apache_request_headers -- Obtener todas las cabeceras HTTP
apache_response_headers --  Obtener todas las cabeceras HTTP de respuesta
apache_setenv -- fijar una variable subprocess_env de Apache
ascii2ebcdic -- Traducir una cadena en ASCII a EBCDIC
ebcdic2ascii -- Traduce una cadena en EBCDIC a ASCII
getallheaders -- Recuperar todas las cabeceras de petición HTTP
virtual -- Realizar una sub-petición de Apache

apache_child_terminate

(PHP 4 >= 4.0.5, PHP 5)

apache_child_terminate -- Terminar un proceso de apache una vez concluido el requerimiento en ejecució

Descripcíon

bool apache_child_terminate ( void )

apache_child_terminate() registrará el proceso Apache que esté ejecutando el requeriminto PHP actual para su terminacióon una vez que la ejecución del código haya finalizado. Puede ser utilizado para terminar un proceso una vez que un script con un alto consumo de memoria haya sido ejecutado, dado que la memoria únicamente sera liberada de forma interna, pero no será devuelta al sistema operativo.

Nota: La disponibilidad de esta característica se controla mediante la directiva child_terminate php.ini, que por defecto está establecida como off (desactivada).

Esta característica tampoco está disponible en las versiones "multi-thread" de Apache, como por ejemplo la versión win32.

Véase también la función exit().

apache_get_modules

(PHP 4 >= 4.3.2, PHP 5)

apache_get_modules --  Obtiene una lista de los modulos cargados con el servidor Apache

Descripción

matrix apache_get_modules ( void )

Esta función regresa una matriz, con los modulos que han sido cargados por Apache.

Ejemplo 1. Ejemplo de apache_get_modules()

<?php
print_r(apache_get_modules());
?>

El ejemplo anterior ejemplo, producirá algo similar a:

Array
(
    [0] => core
    [1] => http_core
    [2] => mod_so
    [3] => sapi_apache2
    [4] => mod_mime
    [5] => mod_rewrite
)

apache_get_version

(PHP 4 >= 4.3.2, PHP 5)

apache_get_version --  Obtiene la version de Apache

Descripción

cadena apache_get_version ( void )

apache_get_version() regresa la version de Apache como una cadena, o FALSE en caso de que falle.

Ejemplo 1. Ejemplo de apache_get_version()

<?php
$version = apache_get_version();
echo "$version \n <br />";
?>

El ejemplo anterior producirá algo similar a:

Apache/1.3.29 (Unix) PHP/4.3.4

Vea también phpinfo().

apache_getenv

(PHP 4 >= 4.3.0, PHP 5)

apache_getenv --  Obtiene una variable subprocess_env de Apache

Descripción

cadena apache_getenv ( cadena variable [, bool walk_to_top])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

apache_lookup_uri

(PHP 3>= 3.0.4, PHP 4 , PHP 5)

apache_lookup_uri --  Realiza una petición parcial por la URI especificada y devuelve toda la información sobre ella

Descripción

object apache_lookup_uri ( string nombre_archivo)

Esta función realiza una petición parcial por una URI. Tan solo llega a obtener toda la información importante sobre el recurso dado y devuelve esta información en una clase. Las propiedades de la clase devuelta 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

Ejemplo 1. Ejemplo de apache_lookup_uri()

<?php
$info = apache_lookup_uri('index.php?var=valor');
print_r($info);

if (file_exists($info->filename)) {
    echo '&iexcl;el archivo existe!';
}
?>

El ejemplo anterior producirá una salida similar a:

stdClass Object
(
    [status] => 200
    [the_request] => GET /dir/archivo.php HTTP/1.1
    [method] => GET
    [mtime] => 0
    [clength] => 0
    [chunked] => 0
    [content_type] => application/x-httpd-php
    [no_cache] => 0
    [no_local_copy] => 1
    [unparsed_uri] => /dir/index.php?var=valor
    [uri] => /dir/index.php
    [filename] => /home/htdocs/dir/index.php
    [args] => var=valor
    [allowed] => 0
    [sent_bodyct] => 0
    [bytes_sent] => 0
    [request_time] => 1074282764
)
&iexcl;el archivo existe!

Nota: apache_lookup_uri() sólo funciona cuando PHP se encuentra instalado como un módulo de Apache.

apache_note

(PHP 3>= 3.0.2, PHP 4 , PHP 5)

apache_note -- Obtener y establecer las notas de petición de apache

Descripción

string apache_note ( string nombre_nota [, string valor_nota])

apache_note() es una función específica de Apache que obtiene y define valores en la tabla notes de una petición. Si es llamada con un argumento, devuelve el valor actual de la nota nombre_nota. Si es llamada con dos argumentos, define el valor de la nota nombre_nota a valor_nota y devuelve el valor previo de la nota nombre_nota.

apache_request_headers

(PHP 4 >= 4.3.0, PHP 5)

apache_request_headers -- Obtener todas las cabeceras HTTP

Descripción

array apache_request_headers ( void )

apache_request_headers() devuelve una matriz asociativa de todas las cabeceras HTTP en la petición actual. Esta función está disponible únicamente cuando PHP se ejecuta como un módulo de Apache.

Ejemplo 1. Ejemplo de apache_request_headers()

<?php
$headers = apache_request_headers();

foreach ($headers as $header => $value) {
    echo "$header: $value <br />\n";
}
?>

Nota: Con anterioridad a PHP 4.3.0, apache_request_headers() se denominaba getallheaders(). A partir de PHP 4.3.0, getallheaders() es un alias para apache_request_headers().

Nota: También se puede obtener el valor de las variables CGI comunes a partir de las variables de entorno, lo cual funciona independientemente de que se esté utilizando PHP como un módulo de Apache. Utiliza phpinfo() para ver una lista de todas las variables de entorno disponibles.

apache_response_headers

(PHP 4 >= 4.3.0, PHP 5)

apache_response_headers --  Obtener todas las cabeceras HTTP de respuesta

Descripción

array apache_response_headers ( void )

Devuelve una matriz con todas las cabeceras de respuesta de Apache. Esta característica sólo está disponible a partir de PHP 4.3.0.

Véase también getallheaders() y headers_sent().

apache_setenv

(PHP 4 >= 4.2.0, PHP 5)

apache_setenv -- fijar una variable subprocess_env de Apache

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 parámetros.

ascii2ebcdic

(PHP 3>= 3.0.17)

ascii2ebcdic -- Traducir una cadena en ASCII a EBCDIC

Descripción

int ascii2ebcdic ( string ascii_str)

ascii2ebcdic() es una función específica de Apache que únicamente está disponible en sistemas operativos basados en EBCDIC (OS/390, BS2000). Traduce la cadena ascii_str codificada en ASCII a su representació equivalente EBCDIC (a prueba de binario), y devuelve el resultado.

Véase también la función inversa ebcdic2ascii()

ebcdic2ascii

(PHP 3>= 3.0.17)

ebcdic2ascii -- Traduce una cadena en EBCDIC a ASCII

Descripción

int ebcdic2ascii ( string ebcdic_str)

ebcdic2ascii() es una función específica de Apache que únicamente está disponible en sistemas operativos basados en EBCDIC (OS/390, BS2000). Traduce la cadena ebcdic_str codificada en EBCDIC a su representació equivalente ASCII (a prueba de binario), y devuelve el resultado.

Véase también la función inversa ascii2ebcdic()

getallheaders

(PHP 3, PHP 4 , PHP 5)

getallheaders -- Recuperar todas las cabeceras de petición HTTP

Descripción

array getallheaders ( void )

getallheaders() es un alias para apache_request_headers(). Devolverá una matriz asociativa con todas las cabeceras HTTP en la petición actual. Por favor lea la documentación de apache_request_headers() para más información sobre cómo trabaja esta función.

Nota: En PHP 4.3.0, getallheaders() se hizo un alias de apache_request_headers(). Básicamente, fue renombrada. Esto debido a que esta función sólo trabaja cuando PHP es compilado como un módulo de Apache.

Nota: From PHP 4.3.3 on you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.

Vea también apache_request_headers().

virtual

(PHP 3, PHP 4 , PHP 5)

virtual -- Realizar una sub-petición de Apache

Descripción

int virtual ( string nombre_archivo)

virtual() es una función específica de Apache que es equivalente a <!--#include virtual...--> en mod_include. Realiza una sub-petición de Apache. Es útil para incluir scripts CGI o archivos .shtml, o cualquier otra cosa que quisiera procesar a través de Apache. Note que para un script CGI, el script debe generar cabeceras CGI válidas. Esto quiere decir que, por lo menos, debe generar una cabecera Content-type.

Para ejecutar la sub-petición, todos los búferes son terminados y volcados al navegador, y las cabeceras pendientes son enviadas también.

A partir de PHP 4.0.6, puede usar virtual() sobre archivos PHP. Sin embargo, típicamente es mejor usar include() o require() si desea incluier otro archivo PHP.

Nota: From PHP 4.3.3 on you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.

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

No se necesitan bibliotecas externas para construir esta extensión


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 tiene directivas de configuración en php.ini.


Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.


Constantes predefinidas

Las constantes listadas aqui están siempre disponibles a través del "núcleo PHP".

CASE_LOWER (integer)

CASE_LOWER se utiliza con array_change_key_case() y se utiliza para convertir las claves de una matriz a minúsculas. Este es el valor por defecto de array_change_key_case().

CASE_UPPER (integer)

CASE_UPPER se utiliza con array_change_key_case() para convertir claves de matriz a mayúsculas.

Flags de ordenación:

SORT_ASC (integer)

SORT_ASC se utiliza con array_multisort() para ordenar en sentido ascendente.

SORT_DESC (integer)

SORT_DESC se utiliza con array_multisort() para ordenar en sentido descendente.

Flags de tipo ordenación: utilizadas por varias funciones ordenación

SORT_REGULAR (integer)

SORT_REGULAR se utiliza para comparar elementos de forma normal.

SORT_NUMERIC (integer)

SORT_NUMERIC se utiliza para comparar elementos de forma numérica.

SORT_STRING (integer)

SORT_STRING se utiliza para comparar elementos como cadenas.

COUNT_NORMAL (integer)

COUNT_RECURSIVE (integer)

EXTR_OVERWRITE (integer)

EXTR_SKIP (integer)

EXTR_PREFIX_SAME (integer)

EXTR_PREFIX_ALL (integer)

EXTR_PREFIX_INVALID (integer)

EXTR_PREFIX_IF_EXISTS (integer)

EXTR_IF_EXISTS (integer)

EXTR_REFS (integer)

Tabla de contenidos
array_change_key_case -- Devuelve una matriz con todas las claves de las cadenas convertidas a mayúsculas o minúsculas
array_chunk -- Divide una matriz en segmentos
array_combine --  Crea una nueva matriz, usando una matriz para las claves y otra para sus valores
array_count_values -- Cuenta todos los valores de una matriz
array_diff_assoc -- Comprueba las diferencias entre matrices teniendo en cuenta los índices
array_diff_uassoc --  Computa la diferencia entre matrices con un chequeo adicional de índices, el cual es realizado por una llamada de retorno entregada por el usuario
array_diff -- Comprueba las diferencias entre matrices
array_fill -- Llena una matriz con valores
array_filter --  Filtra elementos de una matriz mediante una función "callback"
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 -- Comprueba si el índice o clave dada existe en la matriz
array_keys -- Devuelve todas las claves de una matriz
array_map --  Aplica la llamada de retorno especificada a los elementos de las matrices dadas
array_merge_recursive -- Une dos o más matrices recursivamente
array_merge -- Combina dos o más matrices
array_multisort -- Ordena múltiples matrices, o matrices multi-dimensionales
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 --  Selecciona una o más entradas aleatorias de una matriz
array_reduce --  Reduce iterativamente una matriz a un solo valor usando una función llamada de retorno
array_reverse --  Devuelve una matriz con los elementos en orden inverso
array_search --  Busca un valor determinado en una matriz y devuelve la clave correspondiente en caso de éxito
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 --  Calcula la suma de los valores en una matriz
array_udiff_assoc -- Computa la diferencia entre matrices con un chequeo de índices adicional. Los datos son comparados usando una llamada de retorno.
array_udiff_uassoc -- Computa la diferencia entre matrices con un chequeo de índices adicional. Los datos son comparados usando una llamada de retorno. El chequeo de índice es realizado por una llamada de retorno también.
array_udiff -- Computa la diferencia entre matrices, usando una llamada de retorno para la comparación de datos.
array_unique -- Remueve valores duplicados de una matriz
array_unshift -- Introduce uno o más elementos al principio de la matriz
array_values -- Devuelve todos los valores de una matriz
array_walk_recursive --  Aplicar una función de usuario recursivamente a cada miembro 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 --  Ordena una matriz usando un algoritmo de "orden natural" sin distinguir mayúsculas de minúsculas
natsort --  Ordena una matriz usando un algoritmo de "orden natural"
next --  Avanza el puntero interno de una matriz
pos -- Obtiene el elemento actual de una matriz
prev -- Rebobina el puntero interno de una matriz
range --  Crea una matriz que contiene un rango de elementos
reset --  Fija el puntero interno de una matriz a su primer elemento
rsort -- Ordena una matriz en orden inverso
shuffle -- Mezcla una matriz
sizeof -- Alias de count()
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 sus valores usando una función de comparación definida por el usuario

array_change_key_case

(PHP 4 >= 4.2.0, PHP 5)

array_change_key_case -- Devuelve una matriz con todas las claves de las cadenas convertidas a mayúsculas o minúsculas

Descripción

array array_change_key_case ( array input [, int case])

array_change_key_case() cambia las claves de la matriz input de forma que éstas sean todas mayúsculas o minúsculas. El cambio depende del parámetro opcional case, mediante el cual se pueden pasar dos constantes a la función: CASE_UPPER (mayúsculas) y CASE_LOWER (minúsculas). El valor por defecto es CASE_LOWER. La función no afectará a los índices numéricos.

Ejemplo 1. Ejemplo de array_change_key_case()

$input_array = array("PriMero" => 1, "SeGunDo" => 4);
print_r(array_change_key_case($input_array, CASE_UPPER));

La salida del programa anterior será:
Array
(
    [PRIMERO] => 1
    [SEGUNDO] => 4
)

array_chunk

(PHP 4 >= 4.2.0, PHP 5)

array_chunk -- Divide una matriz en segmentos

Descripción

array array_chunk ( array input, int size [, bool preserve_keys])

array_chunk() divide una matriz en varias matrices, cada una con un número de valores equivalente a size. La última matriz generada puede tener un número menor de valores. Las matrices se obtienen como miembros de una matriz multidimensional, que será indexada con números empezando por el cero.

Si al parámetro opcional preserve_keys se le da el valor de TRUE, se fuerza a PHP a preservar las claves originales de la matriz de entrada. Si se especifica FALSE, se utilizarán nuevos índices numéricos en cada matriz resultante. El valor por defecto es FALSE.

Ejemplo 1. Ejemplo de array_chunk()

$input_array = array('a', 'b', 'c', 'd', 'e');
print_r(array_chunk($input_array, 2));
print_r(array_chunk($input_array, 2, TRUE));

La salida del anterior programa será:
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_combine

(PHP 5)

array_combine --  Crea una nueva matriz, usando una matriz para las claves y otra para sus valores

Descripción

array array_combine ( array claves, array valores)

Devuelve un array usando los valores de la matriz claves como claves, y los valores de la matriz valores como los valores correspondientes.

Devuelve FALSE si el número de elementos de cada matriz no es equivalente o si las matrices están vacías.

Ejemplo 1. Un ejemplo simple de array_combine()

<?php
$a = array('verde', 'rojo', 'amarillo');
$b = array('aguacate', 'manzana', 'banano');
$c = array_combine($a, $b);

print_r($c);
?>

Genera la salida:

Array
(
    [verde]    => aguacate
    [rojo]     => manzana
    [amarillo] => banano
)

Vea también array_merge(), array_walk(), y array_values().

array_count_values

(PHP 4 , PHP 5)

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, PHP 5)

array_diff_assoc -- Comprueba las diferencias entre matrices teniendo en cuenta los índices

Descripción

array array_diff_assoc ( array array1, array array2 [, array ...])

array_diff_assoc() devuelve una matriz que contiene todos los valores de array1 que no estén presentes en ninguna de las otras matrices que se pasan como argumento. Hay que tener en cuenta que las claves de los valores se utilizan en la comparación, a diferencia de array_diff().

Ejemplo 1. Ejemplo de array_diff_assoc()

<?php
$array1 = array ("a" => "verde", "b" => "negro", "c" => "azul", "rojo");
$array2 = array ("a" => "verde", "amarillo", "rojo");
$result = array_diff_assoc ($array1, $array2);

/* El resultado es:
Array
(
    [b] => negro
    [c] => azul
    [0] => rojo
)
*/
?>

En el ejemplo anterior se ve que el par "a" => "verde" está presente en ambas matrices y por ello no aparece en la matriz resultado. Por el contrario, el par 0 => "rojo" sí aparece en el resultado puesto que en el segundo argumento el valor "red" tiene la clave 1.

Dos valores de pares clave => valor se consideran iguales si y sólo si (string) $elem1 === (string) $elem2, es decir, cuando la representación de cadena es la misma.

Nota: Hay que tener en cuenta que esta función sólo comprueba una dimensión de una matriz n-dimensional. Por supuesto, se pueden comprobar dimensiones sucesivas mediante: array_diff_assoc($array1[0], $array2[0]);.

Véase también array_diff(), array_intersect(), y array_intersect_assoc().

array_diff_uassoc

(PHP 5)

array_diff_uassoc --  Computa la diferencia entre matrices con un chequeo adicional de índices, el cual es realizado por una llamada de retorno entregada por el usuario

Descripción

array array_diff_uassoc ( array matriz1, array matriz2 [, array ..., callback func_comparacion_claves])

array_diff_uassoc() devuelve un array que contiene todos los valores de matriz1 que no están presentes en ninguno de los otros argumentos. Note que las claves son usadas en la comparación, a diferencia de array_diff(). Esta comparación es realizada por una llamada de retorno entregada por el usuario. La función debe devolver un entero menor que, igual, o mayor que cero si el primer argumento es considerado como menor, igual, o mayor que el segundo, respectivamente. Esto en contraste a array_diff_assoc() en donde es usada una función interna para la comparación de índices.

Ejemplo 1. Ejemplo de array_diff_uassoc()

<?php
function func_comparacion_claves($a, $b)
{
    if ($a === $b) {
        return 0;
    }
    return ($a > $b)? 1:-1;
}

$matriz1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
$matriz2 = array("a" => "green", "yellow", "red");
$resultado = array_diff_uassoc($matriz1, $matriz2, "func_comparacion_claves");
?>

El resultado es:

Array
(
    [b] => brown
    [c] => blue
    [0] => red
)

En nuestro ejemplo anterior, puede ver que la pareja "a" => "green" está presente en ambas matrices y por lo tanto no hace parte de la salida de la función. En contraste, la pareja 0 => "red" está en la salida ya que en el segundo argumento, "red" tiene una clave que es 1.

La igualdad de 2 índices es revisada por la llamada de retorno indicada por el usuario.

Nota: Por favor note que esta función sólo analiza una dimensión de una matriz n-dimensional. Por supuesto que puede analizar dimensiones más profundas usando, por ejemplo, array_diff_uassoc($matriz1[0], $matriz2[0], "func_comparacion_claves");.

Vea también array_diff(), array_diff_assoc(), array_udiff(), array_udiff_assoc(), array_udiff_uassoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() y array_uintersect_uassoc().

array_diff

(PHP 4 >= 4.0.1, PHP 5)

array_diff -- Comprueba las diferencias entre matrices

Descripción

array array_diff ( array array1, array array2 [, array ...])

array_diff() devuelve una matriz que contiene todos los valores de array1 que no aparezcan en ninguna de las otras matrices que se pasan a la función como argumento. Hay que tener en cuenta que las claves se mantienen.

Ejemplo 1. Ejemplo de array_diff()

$array1 = array ("a" => "verde", "rojo", "azul", "rojo");
$array2 = array ("b" => "verde", "amarillo", "rojo");
$resultado = array_diff ($array1, $array2);

Lo cual hace que $resultado contenga la matriz array ("azul");. Multiples ocurrencias en $array1 son tratadas todas de la misma forma.

Nota: Dos elementos se consideran equivalentes si y sólo si (string) $elem1 === (string) $elem2, es decir, cuando la representación de cadena es la misma.

Nota: Hay que tener en cuenta que esta función sólo comprueba una dimensión de una matriz n-dimensional. Por supuesto, se pueden comprobar dimensiones sucesivas mediante: array_diff($array1[0], $array2[0]);.

Aviso

Esta función se rompió en PHP 4.0.4!

Véase también array_diff_assoc(), array_intersect() y array_intersect_assoc().

array_fill

(PHP 4 >= 4.2.0, PHP 5)

array_fill -- Llena una matriz con valores

Descripción

array array_fill ( int start_index, int num, mixed value)

array_fill() introduce en una matriz tantas entradas como especifique el parámetro num, numerandolas a partir de start_index, y les asigna el valor del parámetro value.

Ejemplo 1. Ejemplo de array_fill()

$a = array_fill(5, 6, 'banana');
print_r($a);

$a contendrá ahora:
Array
(
    [5]  => banana
    [6]  => banana
    [7]  => banana
    [8]  => banana
    [9]  => banana
    [10] => banana
)

array_filter

(PHP 4 >= 4.0.6, PHP 5)

array_filter --  Filtra elementos de una matriz mediante una función "callback"

Descripción

array array_filter ( array input [, callback function])

array_filter() repasa cada valor en la matriz input y lo pasa a la función callback. Si la función callback devuelve verdadero, el valor es devuelto a la matriz resultado. Los índices de la matriz se mantienen.

Ejemplo 1. Ejemplo de array_filter()

<?php
function impar($var) {
    return ($var % 2 == 1);
}

function par($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 "Impares :\n";
print_r(array_filter($array1, "impar"));
echo "Pares:\n";
print_r(array_filter($array2, "par"));
?>

La salida en pantalla del programa anterior será:

Impares :
Array
(
    [a] => 1
    [c] => 3
    [e] => 5
)
Pares:
Array
(
    [0] => 6
    [2] => 8
    [4] => 10
    [6] => 12
)

No se debe modificar la matriz a la que array_filter() se aplica desde la función "callback", como p. ej. añadir o eliminar un elemento, o realizar un "unset()". Si la matriz es modificada el comportamiento de esta función no está definido.

Ver también array_map(), array_reduce(), y array_walk().

array_flip

(PHP 4 , PHP 5)

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, PHP 5)

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 its key is 0 while the key of "red" in $array2 is 1.

The two values from the key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In 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, PHP 5)

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

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

See also array_intersect_assoc(), array_diff(), and array_diff_assoc().

array_key_exists

(PHP 4 >= 4.1.0, PHP 5)

array_key_exists -- Comprueba si el índice o clave dada existe en la matriz

Descripción

bool array_key_exists ( mixed clave, array fuente)

array_key_exists() devuelve TRUE si la clave dada existe en la matriz. La clave puede ser cualquier valor válido como índice de una matriz.

Ejemplo 1. Ejemplo de array_key_exists()

<?php
$matriz_a_buscar = array("primero" => 1, "segundo" => 4);
if (array_key_exists("primero", $matriz_a_buscar)) {
    echo "El elemento 'primero' se encuentra en la matriz";
}
?>

Nota: El nombre de esta función es key_exists() en PHP 4.0.6.

Vea también isset(), array_keys(), y in_array().

array_keys

(PHP 4 , PHP 5)

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, PHP 5)

array_map --  Aplica la llamada de retorno especificada a los elementos de las matrices dadas

Descripción

array array_map ( mixed llamada_de_retorno, array matriz1 [, array ...])

array_map() devuelve una matriz que contiene todos los elementos de matriz1 después de haber aplicado la función llamada_de_retorno a cada uno de ellos. El número de parámetros que la función llamada_de_retorno acepte debería coincidir con el número de matrices que son pasadas como argumentos a array_map().

Ejemplo 1. Ejemplo de array_map()

<?php
function cubo($n)
{
    return($n * $n * $n);
}

$a = array(1, 2, 3, 4, 5);
$b = array_map("cubo", $a);
print_r($b);
?>

Esto hace que $b contenga:

Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)

Ejemplo 2. array_map() - usando más matrices

<?php
function mostrar_Castellano($n, $m)
{
    return("El n&uacute;mero $n es llamado $m en Castellano");
}

function map_Castellano($n, $m)
{
    return(array($n => $m));
}

$a = array(1, 2, 3, 4, 5);
$b = array("uno", "dos", "tres", "cuatro", "cinco");

$c = array_map("mostrar_Castellano", $a, $b);
print_r($c);

$d = array_map("map_Castellano", $a , $b);
print_r($d);
?>

Esto produce:

// salida correspondiente a $c
Array
(
    [0] => El n&uacute;mero 1 es llamado uno en Castellano
    [1] => El n&uacute;mero 2 es llamado dos en Castellano
    [2] => El n&uacute;mero 3 es llamado tres en Castellano
    [3] => El n&uacute;mero 4 es llamado cuatro en Castellano
    [4] => El n&uacute;mero 5 es llamado cinco en Castellano
)

// salida correspondiente a $d
Array
(
    [0] => Array
        (
            [1] => uno
        )

    [1] => Array
        (
            [2] => dos
        )

    [2] => Array
        (
            [3] => tres
        )

    [3] => Array
        (
            [4] => cuatro
        )

    [4] => Array
        (
            [5] => cinco
        )

)

Usualmente, cuando se usan dos o más matrices, éstas deberían ser de longitudes iguales ya que la llamada de retorno es aplicada en paralelo a los elementos correspondientes. Si las matrices son de longitudes diferentes, la más corta de ellas será extendida con elementos vacíos.

Un uso interesante de esta función es la construcción de una matriz de matrices, que puede ser llevada a cabo usando NULL como el nombre de la llamada de retorno.

Ejemplo 3. Creación de una matriz de matrices

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

La salida del anterior programa será:

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
        )

)

Vea también array_filter(), array_reduce(), y array_walk().

array_merge_recursive

(PHP 4 >= 4.0.1, PHP 5)

array_merge_recursive -- Une dos o más matrices recursivamente

Descripción

array array_merge_recursive ( array matriz1, array matriz2 [, array ...])

array_merge_recursive() une los elementos de dos o más matrices de modo tal que los valores de cada una sean añadidos al final de la matriz previa. Devuelve la matriz resultante.

Si las matrices de entrada tienen las mismas claves tipo cadena, entonces los valores de estas claves son unidas en una matriz, y esto es hecho recursivamente, de modo que si uno de los valores es una matriz misma, la función unirá también ésta con la correspondiente entrada de otra matriz. Sin embargo, si las matrices tienen la misma clave numérica, el valor más cercano al final no sobrescribirá el valor original, sino que será añadido al final.

Ejemplo 1. Ejemplo de array_merge_recursive()

<?php
$m1 = array("color" => array("favorito" => "rojo"), 5);
$m2 = array(10, "color" => array("favorito" => "verde", "azul"));
$resultado = array_merge_recursive($m1, $m2);
?>

El $resultado será:

Array
(
    [color] => Array
        (
            [favorito] => Array
                (
                    [0] => rojo
                    [1] => verde
                )

            [0] => azul
        )

    [0] => 5
    [1] => 10
)

Vea también array_merge().

array_merge

(PHP 4 , PHP 5)

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 , PHP 5)

array_multisort -- Ordena múltiples matrices, o matrices multi-dimensionales

Descripción

bool array_multisort ( array matriz1 [, mixed arg [, mixed ... [, array ...]]])

array_multisort() puede usarse para ordenar varias matrices al tiempo o una matriz multi-dimensional de acuerdo a una de sus varias dimensiones. Las llaves asociativas (tipo cadena) son conservadas, mientras que las llaves numéricas son re-indexadas.

Las matrices de entrada son tratadas como columnas de una tabla que deberá ser ordenada por filas - de forma similar a la funcionalidad de una sentencia SQL ORDER BY. La primera matriz es considerada la primaria para el ordenamiento. Las filas (valores) en esa matriz que sean comparadas como iguales son ordenadas por la siguiente matriz de entrada, y así sucesivamente.

La estructura de argumentos de esta función es un poco inusual, pero flexible. El primer argumento de todos debe ser una matriz. Subsecuentemente, cada argumento puede ser o una matriz o una bandera de ordenamiento de las siguientes.

Banderas de orientación del ordenamiento:

  • SORT_ASC - ordenar ascendentemente

  • SORT_DESC - ordenar descendentemente

Banderas de tipo de ordenamiento

  • SORT_REGULAR - comparar elementos normalmente

  • SORT_NUMERIC - comparar elementos numéricamente

  • SORT_STRING - comparar elementos como cadenas

No pueden especificarse dos banderas de ordenamiento del mismo tipo luego de cada matriz. Las banderas de ordenamiento especificadas a continuación de un argumento matriz se aplican sólo a esa matriz - estos valores son restablecidos de vuelta a SORT_ASC y SORT_REGULAR antes de cada nuevo argumento matriz.

Devuelve TRUE si todo se llevó a cabo correctamente, FALSE en caso de fallo.

Ejemplo 1. Ordenamiento de varias matrices

<?php
$matriz1 = array("10", 100, 100, "a");
$matriz2 = array(1, 3, "2", 1);
array_multisort($matriz1, $matriz2);
?>

En este ejemplo, después del ordenamiento, la primera matriz contendrá los valores 10, "a", 100, 100. La segunda matriz contendrá 1, 1, "2", 3. Las entradas en la segunda matriz que correspondían a las entradas idénticas de la primera matriz (100 y 100) fueron ordenadas también.

Ejemplo 2. Ordenamiento de una matriz multi-dimensional

<?php
$matriz = array(array("10", 100, 100, "a"), array(1, 3, "2", 1));
array_multisort($matriz[0], SORT_ASC, SORT_STRING,
                $matriz[1], SORT_NUMERIC, SORT_DESC);
?>

En este ejemplo, después del ordenamiento, la primera matriz contendrá 10, 100, 100, "a" (fue ordenada como cadenas en orden ascendente), y la segunda tendrá 1, 3, "2", 1 (ordenada como números, en orden descendiente).

array_pad

(PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

array_rand --  Selecciona una o más entradas aleatorias de una matriz

Descripción

mixed array_rand ( array entrada [, int num_req])

array_rand() es bastante útil cuando desea elegir una o más entradas aleatorias de una matriz. Recibe una matriz de entrada y un argumento opcional num_req que especifica cuántas entradas desea seleccionar; si no se precisa éste argumento, recibe un valor por defecto de 1.

Si está eligiendo únicamente una entrada, array_rand() devuelve la clave de una entrada al azar. De lo contrario, devuelve una matriz de claves para las entradas aleatorias. Esto se ha hecho de esta forma para que usted pueda elegir claves al igual que valores al azar de la matriz.

Nota: A partir de PHP 4.2.0, no es necesario inicializar el generador de números aleatorios con srand() ó mt_srand(), ya que esto se hace ahora automáticamente.

Ejemplo 1. Ejemplo de array_rand()

<?php
srand((float) microtime() * 10000000);
$entrada = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
$claves_aleatorias = array_rand($entrada, 2);
echo $entrada[$claves_aleatorias[0]] . "\n";
echo $entrada[$claves_aleatorias[1]] . "\n";
?>

Vea también shuffle().

array_reduce

(PHP 4 >= 4.0.5, PHP 5)

array_reduce --  Reduce iterativamente una matriz a un solo valor usando una función llamada de retorno

Descripción

mixed array_reduce ( array entrada, callback funcion [, int inicial])

array_reduce() aplica iterativamente la función funcion a los elementos de la matriz entrada, con el propósito de reducir la matriz a un solo valor. Si el argumento opcional inicial está disponible, éste será usado al inicio del proceso, o como resultado final en caso de que la matriz está vacía.

Ejemplo 1. Ejemplo de array_reduce()

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

Este ejemplo resultará en $b conteniendo el valor 15, $c conteniendo 1200 (= 1*2*3*4*5*10), y $d conteniendo 1.

Vea también array_filter(), array_map(), array_unique(), y array_count_values().

array_reverse

(PHP 4 , PHP 5)

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, PHP 5)

array_search --  Busca un valor determinado en una matriz y devuelve la clave correspondiente en caso de éxito

Descripción

mixed array_search ( mixed aguja, array pajar [, bool estricto])

Busca en el pajar por la aguja y retorna la clave de ésta si se encuentra en la matriz, o FALSE de lo contrario.

Nota: Si aguja es una cadena, la comparación es realizada de forma sensible a mayúsculas y minúsculas.

Nota: En versiones de PHP anteriores a 4.2.0, array_search() devuelve NULL en caso de fallo, en lugar de FALSE.

Si el opcional tercer argumento, estricto, se define como TRUE entonces la función array_search() también realizará un chequeo sobre los tipos de datos de aguja en el pajar.

Si la aguja es encontrada en el pajar más de una vez, la primera clave coincidente es devuelta. Para devolver las claves de todos los valores coincidentes, use en su lugar array_keys() con el parámetro opcional valor_busqueda.

Ejemplo 1. Ejemplo de array_search()

<?php
$matriz = array(0 => 'blue', 1 => 'red', 2 => 'green', 3 => 'red');

$clave = array_search('green', $matriz); // $clave = 2;
$clave = array_search('red', $matriz);   // $clave = 1;
?>

Aviso

Esta función puede devolver FALSE, pero también puede devolver un valor no-booleano 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.

Vea también array_keys(), array_values(), array_key_exists(), y in_array().

array_shift

(PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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, PHP 5)

array_sum --  Calcula la suma de los valores en una matriz

Descripción

mixed array_sum ( array matriz)

array_sum() devuelve la suma de los valores de una matriz como un entero o un valor de punto flotante.

Ejemplo 1. Ejemplos de array_sum()

<?php
$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";
?>

La salida del anterior programa será:

sum(a) = 20
sum(b) = 6.9

Nota: Las versiones de PHP anteriores a 4.2.1 modificaban la matriz misma pasada como argumento y convertía las cadenas a números (lo que en la mayoría de casos significaba convertirlas a cero, dependiendo de sus valores).

array_udiff_assoc

(PHP 5)

array_udiff_assoc -- Computa la diferencia entre matrices con un chequeo de índices adicional. Los datos son comparados usando una llamada de retorno.

Descripción

array array_udiff_assoc ( array matriz1, array matriz2 [, array ..., callback func_comparacion_datos])

array_udiff_assoc() devuelve un array que contiene todos los valores de matriz1 que no están presentes en ninguno de los otros argumentos. Note que las claves son usadas en la comparación, a diferencia de array_diff() y array_udiff(). La comparación entre datos de las matrices es realizada usando una llamada de retorno especificada por el usuario. En este sentido, el comportamiento de ésta función es opuesto al de array_diff_assoc(), la cual usa una función interna para la comparación.

Ejemplo 1. Ejemplo de array_udiff_assoc()

<?php
class cr {
    private $miembro_privado;
    function cr($val)
    {
        $this->miembro_privado = $val;
    }

    function func_comp_cr($a, $b)
    {
        if ($a->miembro_privado === $b->miembro_privado) return 0;
        return ($a->miembro_privado > $b->miembro_privado)? 1:-1;
    }
}

$a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
$b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);

$resultado = array_udiff_assoc($a, $b, array("cr", "func_comp_cr"));
print_r($resultado);
?>

El resultado es:

Array
(
    [0.1] => cr Object
        (
            [miembro_privado:private] => 9
        )

    [0.5] => cr Object
        (
            [miembro_privado:private] => 12
        )

    [0] => cr Object
        (
            [miembro_privado:private] => 23
        )
)

En nuestro ejemplo anterior puede observar la pareja "1" => new cr(4) presente en ambas matrices y por lo tanto no hace parte de la salida de la función.

Para la comparación es usada la llamada de retorno entregada por el usuario. Ésta debe devolver un entero menor que, igual, o mayor que cero si el primer argumento es considerado como menor, igual, o mayor que el segundo, respectivamente.

Nota: Por favor note que esta función sólo analiza una dimensión de una matriz n-dimensional. Por supuesto, puede analizar dimensiones más profundas usando, por ejemplo, array_udiff_assoc($matriz1[0], $matriz2[0], "func_alguna_comparacion");.

Vea también array_diff(), array_diff_assoc(), array_diff_uassoc(), array_udiff(), array_udiff_uassoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() y array_uintersect_uassoc().

array_udiff_uassoc

(PHP 5)

array_udiff_uassoc -- Computa la diferencia entre matrices con un chequeo de índices adicional. Los datos son comparados usando una llamada de retorno. El chequeo de índice es realizado por una llamada de retorno también.

Descripción

array array_udiff_uassoc ( array matriz1, array matriz2 [, array ..., callback func_comparacion_datos, callback func_comparacion_claves])

array_udiff_uassoc() devuelve un array que contiene todos los valores de matriz1 que no están presentes en ninguno de los otros argumentos. Note que las claves son usadas en la comparación, a diferencia de array_diff() y array_udiff(). La comparación de los datos de las matrices es realizada usando una llamada de retorno entregada por el usuario: func_comparacion_datos. En este sentido, su comportamiento es el opuesto del de array_diff_assoc(), quien usa una función interna para la comparación. La comparación de claves (índices) es realizada también por la llamada de retorno func_comparacion_claves. Este comportamiento contrasta con lo que hace array_udiff_assoc(), ya que ésta compara los índices usando una función interna.

Ejemplo 1. Ejemplo de array_udiff_uassoc()

<?php
class cr {
    private $miembro_privado;
    function cr($val)
    {
        $this->miembro_privado = $val;
    }

    function func_comp_cr($a, $b)
    {
        if ($a->miembro_privado === $b->miembro_privado) return 0;
        return ($a->miembro_privado > $b->miembro_privado)? 1:-1;
    }

    function func_comp_claves($a, $b)
    {
        if ($a === $b) return 0;
        return ($a > $b)? 1:-1;
    }
}
$a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
$b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);

$resultado = array_udiff_uassoc($a, $b, array("cr", "func_comp_cr"), array("cr", "func_comp_claves"));
print_r($resultado);
?>

El resultado es:

Array
(
    [0.1] => cr Object
        (
            [miembro_privado:private] => 9
        )

    [0.5] => cr Object
        (
            [miembro_privado:private] => 12
        )

    [0] => cr Object
        (
            [miembro_privado:private] => 23
        )
)

En nuestro ejemplo anterior, puede ver que la pareja "1" => new cr(4) está presente en ambas matrices, y por lo tanto no hace parte de la salida de la función. Tenga en cuenta que debe especificar 2 llamadas de retorno.

Para la comparación, se usa la llamada de retorno indicada por el usuario. Ésta debe devolver un entero menor que, igual, o mayor que cero si el primer argumento es considerado como menor, igual, o mayor que el segundo, respectivamente.

Nota: Por favor note que esta función únicamente chequea una dimensión de una matriz n-dimensional. Por supuesto, puede chequear dimensiones más profundas usando, por ejemplo, array_udiff_uassoc($matriz1[0], $matriz2[0], "func_comparacion_datos", "func_comparacion_claves");.

Vea también array_diff(), array_diff_assoc(), array_diff_uassoc(), array_udiff(), array_udiff_assoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() y array_uintersect_uassoc().

array_udiff

(PHP 5)

array_udiff -- Computa la diferencia entre matrices, usando una llamada de retorno para la comparación de datos.

Descripción

array array_udiff ( array matriz1, array matriz2 [, array ..., callback func_comparacion_datos])

array_udiff() devuelve una matriz que contiene todos los valores de matriz1 que no están presentes en ninguno de los otros argumentos. Note que las claves son preservadas. Para la comparación de datos, se usa func_comparacion_datos. Esta función debe devolver un entero menor que, igual, o mayor que cero si el primer argumento es considerado como menor, igual, o mayor que el segundo, respectivamente. Esto en contraste a array_diff(), la cual usa una función interna para la comparación de datos.

Ejemplo 1. Ejemplo de array_udiff()

<?php
class cr {
    private $miembro_privado;
    function cr($val)
    {
        $this->miembro_privado = $val;
    }

    function func_comp_cr($a, $b)
    {
        if ($a->miembro_privado === $b->miembro_privado) return 0;
        return ($a->miembro_privado > $b->miembro_privado)? 1:-1;
    }
}
$a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
$b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);

$resultado = array_udiff($a, $b, array("cr", "func_comp_cr"));
print_r($resultado);
?>

El resultado es:

Array
(
    [0.5] => cr Object
        (
            [miembro_privado:private] => 12
        )

    [0] => cr Object
        (
            [miembro_privado:private] => 23
        )

)

Nota: Dos elementos son considerados iguales si, y solo si (string) $elem1 === (string) $elem2. Esto es: cuando su representación tipo cadena es la misma.

Nota: Por favor note que esta función sólo analiza una dimensión de una matriz n-dimensional. Por supuesto, puede analizar dimensiones más profundas usando array_udiff($matriz1[0], $matriz2[0], "data_compare_func");.

Vea también array_diff(), array_diff_assoc(), array_diff_uassoc(), array_udiff_assoc(), array_udiff_uassoc(), array_intersect(), array_intersect_assoc(), array_uintersect(), array_uintersect_assoc() y array_uintersect_uassoc().

array_unique

(PHP 4 >= 4.0.1, PHP 5)

array_unique -- Remueve valores duplicados de una matriz

Descripción

array array_unique ( array matriz)

array_unique() toma la matriz de entrada y devuelve una nueva matriz sin los valores repetidos.

Note que las claves son preservadas. array_unique() ordena los valores tratados como cadenas inicialmente, y luego conservará la primera clave encontrada para cada valor, ignorando todas las claves posteriores. No quiere decir esto que la clave del primer valor relacionado de la matriz no-ordenada se conservará.

Nota: Dos elementos son considerados equivalentes si y solo si (string) $elem1 === (string) $elem2. En palabras: cuando la representación tipo cadena es la misma.

Se usará el primer elemento.

Ejemplo 1. Ejemplo de array_unique()

<?php
$entrada = array("a" => "verde", "rojo", "b" => "verde", "azul", "rojo");
$resultado = array_unique($entrada);
print_r($resultado);
?>

Esto producirá la salida:

Array
(
    [a] => verde
    [0] => rojo
    [1] => azul
)

Ejemplo 2. array_unique() y tipos de datos

<?php
$entrada = array(4, "4", "3", 4, 3, "3");
$resultado = array_unique($entrada);
var_dump($resultado);
?>

Este script resultará en la siguiente salida:

array(2) {
  [0] => int(4)
  [2] => string(1) "3"
}

array_unshift

(PHP 4 , PHP 5)

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 , PHP 5)

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_recursive

(PHP 5)

array_walk_recursive --  Aplicar una función de usuario recursivamente a cada miembro de una matriz

Descripción

bool array_walk_recursive ( array entrada, string nombre_func [, mixed datos_usuario])

Aviso

Esta función no está documentada actualmente, solamente se encuentra disponible la lista de parámetros.

array_walk

(PHP 3>= 3.0.3, PHP 4 , PHP 5)

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, PHP 5 )

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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, PHP 5 )

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 , PHP 5)

natcasesort --  Ordena una matriz usando un algoritmo de "orden natural" sin distinguir mayúsculas de minúsculas

Descripción

void natcasesort ( array matriz)

Esta función implementa un algoritmo de ordenamiento que ordena cadenas alfanuméricas en la forma en que un ser humano lo haría, al mismo tiempo que conserva las asociaciones clave/valor. Esta propiedad se conoce como "ordenamiento natural".

natcasesort() es una versión de natsort() que no distingue entre mayúsculas y minúsculas.

Ejemplo 1. Ejemplo de natcasesort()

<?php
$matriz1 = $matriz2 = array('IMG0.png', 'img12.png', 'img10.png', 'img2.png', 'img1.png', 'IMG3.png');

sort($matriz1);
echo "Ordenamiento est&aacute;ndar\n";
print_r($matriz1);

natcasesort($matriz2);
echo "\nOrden natural (insensible a may&uacute;sculas y min&uacute;sculas)\n";
print_r($array2);
?>

El código anterior generará la siguiente salida:

Ordenamiento est&aacute;ndar
Array
(
    [0] => IMG0.png
    [1] => IMG3.png
    [2] => img1.png
    [3] => img10.png
    [4] => img12.png
    [5] => img2.png
)

Orden natural (insensible a may&uacute;sculas y min&uacute;sculas)
Array
(
    [0] => IMG0.png
    [4] => img1.png
    [3] => img2.png
    [5] => IMG3.png
    [2] => img10.png
    [1] => img12.png
)

Para más información vea: la página de Comparación de Cadenas en Orden Natural de Martin Pool.

Vea también sort(), natsort(), strnatcmp(), y strnatcasecmp().

natsort

(PHP 4 , PHP 5)

natsort --  Ordena una matriz usando un algoritmo de "orden natural"

Descripción

void natsort ( array matriz)

Esta función implementa un algoritmo que ordena cadenas alfanuméricas en la forma en que lo haría un ser humano, al mismo tiempo que conserva las asociaciones clave/valor. Esta propiedad es conocida como "ordenamiento natural". Un ejemplo de la diferencia entre éste y el algoritmo computacional normal de ordenamiento de cadenas (usado en sort()) puede apreciarse a continuación:

Ejemplo 1. Ejemplo de natsort()

<?php
$matriz1 = $matriz2 = array("img12.png", "img10.png", "img2.png", "img1.png");

sort($matriz1);
echo "Ordenamiento est&aacute;ndar\n";
print_r($matriz1);

natsort($matriz2);
echo "\nOrdenamiento natural\n";
print_r($matriz2);
?>

El anterior fragmento de código genera la siguiente salida:

Ordenamiento est&aacute;ndar
Array
(
    [0] => img1.png
    [1] => img10.png
    [2] => img12.png
    [3] => img2.png
)

Ordenamiento natural
Array
(
    [3] => img1.png
    [2] => img2.png
    [1] => img10.png
    [0] => img12.png
)

Para más información vea: la página de Comparación de Cadenas en Orden Natural de Martin Pool.

Vea también natcasesort(), strnatcmp(), y strnatcasecmp().

next

(PHP 3, PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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

range

(PHP 3>= 3.0.8, PHP 4 , PHP 5)

range --  Crea una matriz que contiene un rango de elementos

Descripción

array range ( int bajo, int alto [, int paso])

rango() devuelve una matriz de elementos desde bajo hasta alto, ambos inclusive. Si bajo > alto, la secuencia será del mayor al menor.

Nuevo parámetro: El parámetro opcional paso fue añadido en 5.0.0.

Si un valor paso es dado, éste será usado como el incremento entre elementos en la secuencia. paso debería ser definido como un número positivo. Si no se especifica, paso tendrá un valor predeterminado de 1.

Ejemplo 1. Ejemplos de range()

<?php
// array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
foreach (range(0, 12) as $numero) {
    echo $numero;
}

// El parametro paso fue introducido en 5.0.0
// array(0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100)
foreach (range(0, 100, 10) as $numero) {
    echo $numero;
}

// Uso de secuencias de caracteres introducidas en 4.1.0
// array('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i');
foreach (range('a', 'i') as $letra) {
    echo $letra;
}
// array('c', 'b', 'a');
foreach (range('c', 'a') as $letra) {
    echo $letra;
}
?>

Nota: Antes de PHP 4.1.0, range() sólo generaba matrices de enteros incrementales. El soporte para secuencias de caracteres y matrices en decremento fue añadido en 4.1.0. Los valores de secuencia de caracteres esán limitados a una longitud de uno. Si una longitud superior a uno es ingresada, solo se usa el primer caracter.

Atención

En versiones de PHP desde 4.1.0 hasta 4.3.2, range() considera las cadenas numéricas como cadenas y no enteros. En su lugar, ellas serán usadas para secuencias de caracteres. Por ejemplo, "4242" es tratado como "4".

Vea también shuffle(), array_fill(), y foreach.

reset

(PHP 3, PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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

sizeof -- Alias de count()

Descripción

Esta función es un alias de count().

sort

(PHP 3, PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

usort --  Ordena una matriz por sus valores usando una función de comparación definida por el usuario

Descripción

bool usort ( array matriz, callback funcion_comp)

Esta función ordenará una matriz por sus valores usando una función de comparación definida por el usuario. Si la matriz que desea ordenar necesita ser ordenada mediante ciertos criterios especiales, es buena idea usar esta función.

La función de comparación debe devolver un entero menor que, igual, o mayor que cero si el primer argumento es considerado menor, igual, o mayor que el segundo, respectivamente.

Nota: Si dos miembros son comparados como iguales, su orden en la matriz resultante es indefinido. Hasta PHP 4.0.6, las funciones definidas por el usuario mantenían el orden original para esos elementos, pero con el nuevo algoritmo de ordenamiento introducido en 4.1.0 este ya no es el caso, ya que no hay forma de hacerlo de manera eficiente.

Devuelve TRUE si todo se llevó a cabo correctamente, FALSE en caso de fallo.

Ejemplo 1. Ejemplo de usort()

<?php
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 produciría la salida:

0: 1
1: 2
2: 3
3: 5
4: 6

Nota: Obviamente en este ejemplo trivial, la función sort() sería más apropiada.

Ejemplo 2. Ejemplo de usort() usando una matriz multi-dimensional

<?php
function cmp($a, $b) 
{
    return strcmp($a["fruta"], $b["fruta"]);
}

$frutas[0]["fruta"] = "limones";
$frutas[1]["fruta"] = "bananos";
$frutas[2]["fruta"] = "granadillas";

usort($frutas, "cmp");

while (list($clave, $valor) = each($frutas)) {
    echo "\$frutas[$clave]: " . $valor["fruta"] . "\n";
}
?>

Cuando se ordena una matriz multi-dimensional, $a y $b contienen referencias al primer índice de la matriz.

Este ejemplo produciría la salida:

$frutas[0]: bananos
$frutas[1]: granadillas
$frutas[2]: limones

Ejemplo 3. Ejemplo de usort() usando una función miembro de un objeto

<?php
class ObjPrueba {
    var $nombre;

    function ObjPrueba($nombre) 
    {
        $this->nombre = $nombre;
    }

    /* Esta es la funcion estatica de comparacion: */
    function cmp_obj($a, $b) 
    {
        $al = strtolower($a->nombre);
        $bl = strtolower($b->nombre);
        if ($al == $bl) {
            return 0;
        }
        return ($al > $bl) ? +1 : -1;
    }
}

$a[] = new ObjPrueba("c");
$a[] = new ObjPrueba("b");
$a[] = new ObjPrueba("d");

usort($a, array("ObjPrueba", "cmp_obj"));

foreach ($a as $item) {
    echo $item->nombre . "\n";
}
?>

Este ejemplo produciría la salida:

b
c
d

Vea también uasort(), uksort(), sort(), asort(), arsort(),ksort(), natsort(), and rsort().

III. Funciones Aspell [deprecated]

Introducción

La función aspell() permite comprobar la ortografía de una palabra y ofrece alternativas a la misma.

Nota: Esta extensión ha sido removida de PHP y no se encuentra disponible a partir de PHP 4.3.0. Si quereis utilizar capacidades de comprobación ortográfica en php, usar pspell. Utiliza la biblioteca pspell y funciona con versiones recientes de aspell.


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. Necesitais la biblioteca aspell, disponible en : http://aspell.sourceforge.net/.


Instalación

En PHP 4, estas funciones se encuentran disponibles únicamente si PHP fue configurado con --with-aspell=[DIR].


Ver también

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 solo están disponibles si PHP fue configurado con --enable-bcmath. En PHP 3, estas funciones sólo están disponibles si PHP NO fue configurado con --disable-bcmath.

La versión para Windows de PHP tiene soporte nativo para esta extensión. No se necesita cargar ninguna extensión adicional para usar estas funciones.


Configuración en tiempo de ejecución

El comportamiento de estas funciones está afectado por los valores definidos en php.ini.

Tabla 1. Opciones de configuración de BCMath

NombrePor defectoModificable
bcmath.scale0PHP_INI_ALL
Para más detalles y la definición de las constantes PHP_INI_*, consulte ini_set().

A continuación se presenta una corta explicación de las directivas de configuración.

bcmath.scale integer

Número de dígitos decimales para todas las funciones de bcmath. Vea también bcscale().


Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.


Constantes predefinidas

Esta extensión no tiene ninguna constante definida.

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 --  Eleva un número de precisión arbitraria a otro, reducido por un módulo especificado.
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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

bcpow -- Eleva un número de precisión arbitraria a otro.

Descripción

string bcpow ( string x, int 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 bcpowmod() y bcsqrt()

bcpowmod

(PHP 5)

bcpowmod --  Eleva un número de precisión arbitraria a otro, reducido por un módulo especificado.

Descripción

string bcpowmod ( string x, string y, string módulo [, int escala])

Utiliza el método de exponenciación-rápida para elevar x a la potencia y con respecto al módulo módulo. La escala opcional puede ser usada para establecer el número de dígitos después de la coma decimal en el resultado.

Las siguientes dos declaraciones son idénticas funcionalmente. Sin embargo, la versión que usa bcpowmod() se ejecuta en menos tiempo y puede aceptar parámetros más grandes.

<?php
$a = bcpowmod($x, $y, $mod);

$b = bcmod(bcpow($x, $y),$mod);

// $a y $b poseen valores iguales.
?>

Nota: Debido a que este método usa el módulo de la operación, los números no-naturales pueden arrojar resultados inesperados. Un número natural es cualquier entero positivo diferente de cero.

Vea también bcpow() y bcmod().

bcscale

(PHP 3, PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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. este módulo requiere bzip2/libbzip2 version >= 1.0.x.


Instalación

El soporte para bzip2 en PHP no está habilitado por defecto. Necesita usar el parámetro de configuración --with-bz2[=DIR] a la hora de compilar PHP para habilitar el soporte para bzip2.


Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración en php.ini.


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 tiene ninguna constante definida.


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 -- Cierra un archivo bzip2
bzcompress -- Comprime una cadena a una forma de datos codificados bzip2
bzdecompress -- Descomprime datos encodificados bzip2
bzerrno -- Regresa el número de error bzip2
bzerror -- Regresa el número de error y la cadena de error bzip2
bzerrstr -- Regresa la cadena de error bzip2
bzflush -- Forza la escritura de todos los datos en el almacenamiento intermedio
bzopen -- Abre un archivo comprimido bzip2
bzread -- Lectura segura de archivos binarios bzip2
bzwrite -- Escribe en forma segura a un archivo binario bzip2

bzclose

(PHP 4 >= 4.0.4, PHP 5)

bzclose -- Cierra un archivo bzip2

Descripción

int bzclose ( resource bz)

Cierra el archivo bzip2 referenciado por el apuntador bz.

Devuelve TRUE si todo se llevó a cabo correctamente, FALSE en caso de fallo.

El apuntador del archivo debe ser valido, y debe apuntar a un archivo exitosamente abierto por bzopen().

Ver también

bzopen().

bzcompress

(PHP 4 >= 4.0.4, PHP 5)

bzcompress -- Comprime una cadena a una forma de datos codificados bzip2

Descripción

cadena bzcompress ( cadena source [, int blocksize [, int workfactor]])

bzcompress() comprime la cadena representadada por el parámetro source y la regresa en forma de datos codificados bzip2.

El parámetro opciona blocksize específica el tamaño del bloque a ser usado durante la compresión y debe ser un número entre 1 y 9, con 9 se da la mejor compresión, pero usa más recursos para hacerlo. el parámetro tiene valor 4 por defecto.

El parámetro opcional workfactor controla como se debe actuar en la fase de compresión cuando se encuentre con el peor caso, altamente repetitiva entrada de datos. El valor puede estar entre 0 y 250, 0 es un caso especial y 30 es el valor por defecto. Sin importar el valor del workfactor, la salida generada será la misma.

Ver también

bzdecompress().

Ejemplo

Ejemplo 1. Comprimiendo datos

<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
echo $bzstr;
?>

bzdecompress

(PHP 4 >= 4.0.4, PHP 5)

bzdecompress -- Descomprime datos encodificados bzip2

Descripción

cadena bzdecompress ( cadena source [, int small])

bzdecompress() toma la cadena con datos codificados bzip2, representada por el parámetro source, y la regresa descodificada. Si el parámetro opcional small es TRUE, un algoritmo de descompresión alternativo será usado, el cual usa menos memoria (el máximo de memoria usada es al readedor de 2300K) pero trabaja dificilmente a la mitad de la velocidad. Vea la documentacion de bzip para más información acerca de esta caracterísitoca.

Ver también

bzcompress().

Ejemplo

Ejemplo 1. Descomprimir una cadena

<?php
$start_str = "This is not an honest face?";
$bzstr = bzcompress($start_str);

echo "Compressed String: ";
echo $bzstr;
echo "\n<br />\n";

$str = bzdecompress($bzstr);
echo "Decompressed String: ";
echo $str;
echo "\n<br />\n";
?>

bzerrno

(PHP 4 >= 4.0.4, PHP 5)

bzerrno -- Regresa el número de error bzip2

Descripción

int bzerrno ( resource bz)

Regresa el número de error regresado por el archivo apuntado por bz.

Ver también

bzerror(), bzerrstr().

bzerror

(PHP 4 >= 4.0.4, PHP 5)

bzerror -- Regresa el número de error y la cadena de error bzip2

Descripción

matriz bzerror ( resource bz)

Regresa el número de error y la cadena de error, en una matriz asociativa, obtenido por el archivo apuntado. bz.

Ejemplo 1. bzerror() ejemplo

<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>

See also bzerrno() and bzerrstr().

bzerrstr

(PHP 4 >= 4.0.4, PHP 5)

bzerrstr -- Regresa la cadena de error bzip2

Descripción

cadena bzerrstr ( resource bz)

Regresa la cadena de error de cualquier error regresado por el archivo apuntado por bz.

Vea también bzerrno(), bzerror().

bzflush

(PHP 4 >= 4.0.4, PHP 5)

bzflush -- Forza la escritura de todos los datos en el almacenamiento intermedio

Descripción

int bzflush ( resource bz)

Fuerza la escritura de todos los datos en almacenamiento intermedio para el apuntador bz.

Return values

Devuelve TRUE si todo se llevó a cabo correctamente, FALSE en caso de fallo.

Ver también

bzread(), bzwrite().

bzopen

(PHP 4 >= 4.0.4, PHP 5)

bzopen -- Abre un archivo comprimido bzip2

Descripción

resource bzopen ( cadena filename, cadena mode)

bzopen() abre un archivo bzip2 (.bz2) para lectura o escritura. filename es el nombre del archivo a abrir. mode es similar a la función fopen() (`r' para lectura, `w' para escritura, etc.).

Si falla la apertura del archivo, bzopen() regresa FALSE, en otro casi regresa un apuntador hacia el archivo recientemente abierto.

Ejemplo 1. Ejemplo

<?php

$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Couldn't open $file for reading");

bzclose($bz);

?>

vea también bzclose().

bzread

(PHP 4 >= 4.0.4, PHP 5)

bzread -- Lectura segura de archivos binarios bzip2

Descripción

cadena bzread ( resource bz [, int length])

bzread() lee hasta length en bytes del archivo bzip2 dado por el apuntador bz. La lectura se detiene cuando los bytes de datos sin comprimir alcanzan el tamaño de length o se encontr??? EOF, lo que ocurra primero. Si no se específica el parámetro opcional length, bzread() leerá 1024 bytes de datos ya descomprimidos cada vez.

Ejemplo 1. bzread() ejemplo

<?php

$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Couldn't open $file");

$decompressed_file = '';
while (!feof($bz)) {
    $decompressed_file .= bzread($bz, 4096);
}
bzclose($bz);

echo "The contents of $file are: <br />\n";
echo $decompressed_file;

?>

Vea también bzwrite(), feof(), bzopen().

bzwrite

(PHP 4 >= 4.0.4, PHP 5)

bzwrite -- Escribe en forma segura a un archivo binario bzip2

Descripción

int bzwrite ( resource bz, cadena data [, int length])

bzwrite() escribe el contenido de la cadena data al archivo bzip2 apuntado por el parámetro bz. Si se da el parámetro opcional length, la escritura se detendrá después de la longitud (en forma no comprimida) se haya alcanzado o que se haya encontrado el fin de la cadena, lo que ocurra primero.

Ejemplo 1. bzwrite() ejemplo

<?php
$str = "uncompressed data";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>

Vea también bzread(), 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://www.hermetic.ch/cal_stud/jdn.htm. Para más información sobre sistemas de calendario, visitar http://www.boogle.com/info/cal-overview.html. En estas instrucciones se han incluído extractos entrecomillados de dicha página.


Instalación

Para tener trabajando estas funciones, tiene que compilar PHP con --enable-calendar.

La versión para Windows de PHP tiene soporte nativo para esta extensión. No se necesita cargar ninguna extensión adicional para usar estas funciones.


Configuración en tiempo de ejecución

Esta extensión no tiene directivas de configuración en php.ini.


Tipos de recursos

Esta extensión no tiene ningún tipo de recurso definido.


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 dinámicamente 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)

Estas constantes están disponibles a partir de PHP 5.0.0 :

CAL_JEWISH_ADD_ALAFIM_GERESH (entero)

CAL_JEWISH_ADD_ALAFIM (entero)

CAL_JEWISH_ADD_GERESHAYIM (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.
cal_info -- Devuelve información sobre un calendario en particular.
cal_to_jd -- Convierte 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, PHP 5)

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, PHP 5)

cal_from_jd -- Convierte de Cuenta de Días Juliana a un calendario soportado.

Descripción

array cal_from_jd ( int jd, int calendario)

cal_from_jd() convierte el dia de Cuenta Juliana definido en jd a un dia del calendario especificado. Los valores de calendario soportados son CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH and CAL_FRENCH.

Ver también cal_to_jd().

cal_info

(PHP 4 >= 4.1.0, PHP 5)

cal_info -- Devuelve información sobre un calendario en particular.

Descripción

array cal_info ( [int calendario])

cal_info() devuelve información sobre el calendario especificado ó sobre todos los calendarios soportados si no se especifica el parametro calendario.

La información del calendario es devuelta en una matriz conteniendo los elementos calname, calsymbol, month, abbrevmonth y maxdaysinmonth.

Si no se especifica calendario, se devuelve una matriz con informacion sobre todos los calendarios soportados. Esta funcionalidad estará disponible en PHP 5.

cal_to_jd

(PHP 4 >= 4.1.0, PHP 5)

cal_to_jd -- Convierte un calendario soportado a Cuenta de Días Juliana.

Descripción

int cal_to_jd ( int calendario, int mes, int dia, int año)

cal_to_jd() Calcula la Cuenta de Días Juliana para un dia en el calendario especificado por calendar. Los calendarios soportados son CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH y CAL_FRENCH.

Ver también cal_to_jd().

easter_date

(PHP 3>= 3.0.9, PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

jdtojewish -- Convierte de cuenta de días juliana a calendario judío

Descripción

string jdtojewish ( int diajuliano [, bool hebreo [, int fl]])

Convierte una cuenta de días juliana al calendario judío.

Los parámetros opcionales hebreo y fl está disponibles a partir de PHP 5.0.0

Si al parámetro hebreo se le asigna el valor TRUE, el parámetro fl se usa para el formato de salida hebreo. Los formatos disponibles son: CAL_JEWISH_ADD_ALAFIM_GERESH, CAL_JEWISH_ADD_ALAFIM, CAL_JEWISH_ADD_GERESHAYIM.

Ejemplo 1. Ejemplo jdtojewish()

<?php
echo jdtojewish(gregoriantojd(10,8,2002), true,
       CAL_JEWISH_ADD_GERESHAYIM + CAL_JEWISH_ADD_ALAFIM + CAL_JEWISH_ADD_ALAFIM_GERESH); 
?>

JDToJulian

(PHP 3, PHP 4 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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 , PHP 5)

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. Usando el módulo para PHP de CCVS, se pueden procesar tarjetas de crédito directamente desde vuestros scripts en PHP.

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.

Esta extensión ha sido removida de PHP y no se encuentra disponible a partir de PHP 4.3.0. Si quereis utilizar la capacidad de procesar tarjetas de crédito, usar MCVE.


Instalación

To enable CCVS Support in PHP, first verify your CCVS installation directory. You will then need to configure PHP with the --with-ccvs option. If you use this option without specifying the path to your CCVS installation, PHP will attempt to look in the default CCVS Install location (/usr/local/ccvs). If CCVS is in a non-standard location, run configure with: --with-ccvs=[DIR], where DIR is the path to your CCVS installation. Please note that CCVS support requires that DIR/lib and DIR/include exist, and include cv_api.h under the include directory and libccvs.a under the lib directory.

Additionally, a ccvsd process will need to be running for the configurations you intend to use in your PHP scripts. You will also need to make sure the PHP Processes are running under the same user as your CCVS was installed as (e.g. if you installed CCVS as user 'ccvs', your PHP processes must run as 'ccvs' as well.)


Ver también

RedHat ha dejado de soportar CCVS; De todas maneras un manual un poco anticuado está todavía disponible en http://redhat.com/docs/manuals/ccvs/.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

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 parámetros.

VIII. Funciones COM y .Net (Windows)

Introducción

COM es un acrónimo para Component Object Model (Modelo de Objetos por Componentes); es una capa orientada a objetos (asi como servicios asociados) que cubre la especificación DCE RPC (un estándar abierto) y define una convención común de llamado que permite que código escrito en cualquier lenguaje pueda llamar e inter-operar con código escrito en cualquier otro lenguaje (provisto que ambos lenguajes hagan uso de COM). No solo es posible escribir el código en cualquier lenguaje, también es cierto que no necesita ser parte del mismo ejecutable; el código puede ser cargado desde un recurso DLL, encontrarse en otro proceso corriendo en la misma máquina, o, mediante DCOM (COM Distribuido), encontrarse en otro proceso en una máquina remota, todo esto sin requerir que su código sepa siquiera en dónde reside el componente.

Existe un sub-conjunto de COM conocido como Automatización OLE que se compone de un grupo de interfaces OLE que permiten los enlaces flexibles con objetos COM, de modo que puedan ser susceptibles a introspección y llamados en tiempo de ejecución sin conocimientos en tiempo de compilación sobre el modo de operación del objeto. La extensión COM de PHP utiliza las interfaces de Automatización OLE para permitirle crear y llamar objetos compatibles desde sus scripts. Técnicamente hablando, ésta debería ser llamada la "Extensión de Automatización OLE para PHP", ya que no todos los objetos COM son compatibles con OLE.

Ahora bien, ¿porqué querría o debería usar COM? COM es una de las formas principales de unir aplicaciones y componentes en la plataforma Windows; mediante el usa de COM usted puede iniciar Microsoft Word, llenar una plantilla de documento y guardar el resultado como un documento Word y enviarlo a un visitante de su sitio web. También puede usar COM para realizar tareas administrativas para su red y para configurar su servidor web (IIS); tales son apenas los usos más comunes; usted puede hacer mucho más con COM.

A partir de PHP 5, esta extensión (y su documentación) fue re-escrita por completo y se ha eliminado gran parte del material confuso e inútil. Adicionalmente, se ofrece soporte para la creación de instancias y ensambles .Net usando la capa de interoperabilidad COM ofrecida por Microsoft.

Por favor lea este artículo para una vista general de los cambios en ésta extensión en PHP 5.


Requerimientos

Las funciones COM se encuentran disponibles únicamente para la versión Windows de PHP.

El soporte para .Net requiere PHP 5 y el entorno de desarrollo .Net.


Instalación

No se necesita ninguna instalación para usar estas funciones, son parte del núcleo de PHP.

La versión para Windows de PHP tiene soporte nativo para esta extensión. No se necesita cargar ninguna extensión adicional para usar estas funciones.

Usted es responsable de la instalación del soporte para los varios objetos COM que piensa usar (tales como MS Word); nosotros no incluimos todos éstos con PHP, ni podemos hacerlo.


For Each

A partir de PHP 5, usted puede usar la sentencia la sección de nombre foreach en Capítulo 11 de PHP para iterar sobre los contenidos de un IEnumVariant COM/OLE estándar. En términos más simples, esto quiere decir que puede usar foreach en aquellas situaciones en donde podría haber usado For Each en código VB/ASP.

Ejemplo 1. For Each en ASP

<%
Set objetoDominio = GetObject("WinNT://Domain")
For Each obj in objetoDominio
  Response.Write obj.Name & "<br />"
Next
%>

Ejemplo 2. while() ... Next() en PHP 4

<?php
$objetoDominio = new COM("WinNT://Domain");
while ($obj = $objetoDominio->Next()) {
   echo $obj->Name . "<br />";
} 
?>

Ejemplo 3. foreach en PHP 5

<?php
$objetoDominio = new COM("WinNT://Domain");
foreach ($objetoDominio as $obj) {
   echo $obj->Name . "<br />";
}
?>


Matrices y propiedades COM tipo-matriz

Muchos objetos COM exponen sus propiedades como matrices, o usando un acceso estilo-matriz. En PHP 4, es posible usar la sintaxis de matrices de PHP para leer/escribir tales propiedades, pero sólo es posible manipular una dimensión. Si desea leer una propiedad multi-dimensional, puede crear el acceso en forma de un llamado de función, en donde cada parámetro representa cada parámetro del acceso a la matriz, aunque no hay forma de escribir tal tipo de propiedad.

PHP 5 introduce las siguientes características nuevas para facilitar su vida:

  • Acceso a matrices multi-dimensionales, o propiedades COM que requieren múltiples parámetros usando la sintaxis de matrices de PHP. También puede escribir o definir propiedades usando ésta técnica.

  • Iterar a través de SafeArrays ("verdaderas" matrices) usando la estructura de control la sección de nombre foreach en Capítulo 11. Esto funciona ya que los SafeArrays incluyen información sobre su tamaño. Si una propiedad estilo-matriz implementa IEnumVariant, entonces también puede usar foreach para tales propiedades; eche un vistazo a la sección de nombre For Each para más información sobre este tema.


Excepciones (PHP 5)

Esta extensión arroja instancias de la clase com_exception siempre que se presente un error potencialmente fatal reportado por COM. Todas las excepciones COM tienen una propiedad code bien definida que corresponde con el valor de retorno HRESULT proveniente de las varias operaciones COM. Es posible usar éste código para tomar decisiones programáticas sobre cómo manejar la excepción.


Configuración en tiempo de ejecución

El comportamiento de estas funciones está afectado por los valores definidos en php.ini.

Tabla 1. Com configuration options

NameDefaultChangeable
com.allow_dcom"0"PHP_INI_SYSTEM
com.autoregister_typelib"0"PHP_INI_ALL
com.autoregister_verbose"0"PHP_INI_ALL
com.autoregister_casesensitive"1"PHP_INI_ALL
com.code_page""PHP_INI_ALL
com.typelib_file""PHP_INI_SYSTEM
For further details and definition of the PHP_INI_* constants see ini_set().

A continuación se presenta una corta explicación de las directivas de configuración.

com.allow_dcom

When this is turned on, PHP will be allowed to operate as a D-COM (Distributed COM) client and will allow the PHP script to instantiate COM objects on a remote server.

com.autoregister_typelib

When this is turned on, PHP will attempt to register constants from the typelibrary of objects that it instantiates, if those objects implement the interfaces required to obtain that information. The case sensitivity of the constants it registers is controlled by the com.autoregister_casesensitive configuration directive.

com.autoregister_verbose

When this is turned on, any problems with loading a typelibrary during object instantiation will be reported using the PHP error mechanism. The default is off, which does not emit any indication if there was an error finding or loading the type library.

com.autoregister_casesensitive

When this is turned on (the default), constants found in auto-loaded type libraries will be registered case sensitively. See com_load_typelib() for more details.

com.code_page

It controls the default character set code-page to use when passing strings to and from COM objects. If set to an empty string, PHP will assume that you want CP_ACP, which is the default system ANSI code page.

If the text in your scripts is encoded using a different encoding/character set by default, setting this directive will save you from having to pass the code page as a parameter to the COM class constructor. Please note that by using this directive (as with any PHP configuration directive), your PHP script becomes less portable; you should use the COM constructor parameter whenever possible.

Nota: This configuration directive was introduced with PHP 5.

com.typelib_file

When set, this should hold the path to a file that contains a list of typelibraries that should be loaded on startup. Each line of the file will be treated as the type library name and loaded as though you had called com_load_typelib(). The constants will be registered persistently, so that the library only needs to be loaded once. If a type library name ends with the string #cis or #case_insensitive, then the constants from that library will be registered case insensitively.


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 dinámicamente en tiempo de ejecución.

CLSCTX_INPROC_SERVER (integer)

CLSCTX_INPROC_HANDLER (integer)

CLSCTX_LOCAL_SERVER (integer)

CLSCTX_REMOTE_SERVER (integer)

CLSCTX_SERVER (integer)

CLSCTX_ALL (integer)

VT_NULL (integer)

VT_EMPTY (integer)

VT_UI1 (integer)

VT_I2 (integer)

VT_I4 (integer)

VT_R4 (integer)

VT_R8 (integer)

VT_BOOL (integer)

VT_ERROR (integer)

VT_CY (integer)

VT_DATE (integer)

VT_BSTR (integer)

VT_DECIMAL (integer)

VT_UNKNOWN (integer)

VT_DISPATCH (integer)

VT_VARIANT (integer)

VT_I1 (integer)

VT_UI2 (integer)

VT_UI4 (integer)

VT_INT (integer)

VT_UINT (integer)

VT_ARRAY (integer)

VT_BYREF (integer)

CP_ACP (integer)

CP_MACCP (integer)

CP_OEMCP (integer)

CP_UTF7 (integer)

CP_UTF8 (integer)

CP_SYMBOL (integer)

CP_THREAD_ACP (integer)

VARCMP_LT (integer)

VARCMP_EQ (integer)

VARCMP_GT (integer)

VARCMP_NULL (integer)

NORM_IGNORECASE (integer)

NORM_IGNORENONSPACE (integer)

NORM_IGNORESYMBOLS (integer)

NORM_IGNOREWIDTH (integer)

NORM_IGNOREKANATYPE (integer)

NORM_IGNOREKASHIDA (integer)

DISP_E_DIVBYZERO (integer)

DISP_E_OVERFLOW (integer)

MK_E_UNAVAILABLE (integer)


Ver también

Para más información sobre COM, lea la especificación COM o quizás eche un vistazo a la Otra Biblioteca COM Más (YACL por sus siglas en Inglés) de Don Box. Puede encontrar información adicional en nuestro FAQ sobre Capítulo 53. Si está pensando en usar aplicaciones MS Office en el lado del servidor, es buena idea que lea la información encontrada aquí: Consideraciones para la Automatización de Office en el Lado del Servidor.

Tabla de contenidos
COM -- COM class
DOTNET -- DOTNET class
VARIANT -- VARIANT class
com_addref --  Increases the components reference counter [deprecated]
com_create_guid --  Generate a globally unique identifier (GUID)
com_event_sink --  Connect events from a COM object to a PHP object
com_get_active_object --  Returns a handle to an already running instance of a COM object
com_get -- ???
com_invoke -- ???
com_isenum -- Indicates if a COM object has an IEnumVariant interface for iteration [deprecated]
com_load_typelib -- Loads a Typelib
com_load -- ???
com_message_pump --  Process COM messages, sleeping for up to timeoutms milliseconds
com_print_typeinfo --  Print out a PHP class definition for a dispatchable interface
com_propget -- ???
com_propput -- ???
com_propset -- ???
com_release --  Decreases the components reference counter [deprecated]
com_set -- ???
variant_abs --  Returns the absolute value of a variant
variant_add --  "Adds" two variant values together and returns the result
variant_and --  performs a bitwise AND operation between two variants and returns the result
variant_cast --  Convert a variant into a new variant object of another type
variant_cat --  concatenates two variant values together and returns the result
variant_cmp --  Compares two variants
variant_date_from_timestamp --  Returns a variant date representation of a unix timestamp
variant_date_to_timestamp --  Converts a variant date/time value to unix timestamp
variant_div --  Returns the result from dividing two variants
variant_eqv --  Performs a bitwise equivalence on two variants
variant_fix --  Returns the integer portion ? of a variant
variant_get_type -- Returns the type of a variant object
variant_idiv --  Converts variants to integers and then returns the result from dividing them
variant_imp --  Performs a bitwise implication on two variants
variant_int --  Returns the integer portion of a variant
variant_mod --  Divides two variants and returns only the remainder
variant_mul --  multiplies the values of the two variants and returns the result
variant_neg --  Performs logical negation on a variant
variant_not --  Performs bitwise not negation on a variant
variant_or --  Performs a logical disjunction on two variants
variant_pow --  Returns the result of performing the power function with two variants
variant_round --  Rounds a variant to the specified number of decimal places
variant_set_type --  Convert a variant into another type. Variant is modified "in-place"
variant_set --  Assigns a new value for a variant object
variant_sub --  subtracts the value of the right variant from the left variant value and returns the result
variant_xor --  Performs a logical exclusion on two variants

COM

(no version information, might be only in CVS)

COM -- COM class

Sinopsis

$obj = new COM("Application.ID")

Description

The COM class allows you to instantiate an OLE compatible COM object and call its methods and access its properties.

Methods

object COM::COM ( string module_name [, mixed server_name [, int codepage [, string typelib]]])

COM class constructor. The parameters have the following meanings:

module_name

Can be a ProgID, Class ID or Moniker that names the component to load.

A ProgID is typically the application or DLL name, followed by a period, followed by the object name. e.g: Word.Application.

A Class ID is the UUID that uniquely identifies a given class.

A Moniker is a special form of naming, similar in concept to a URL scheme, that identifies a resource and specifies how it should be loaded. As an example, you could load up Word and get an object representing a word document by specifying the full path to the word document as the module name, or you can use LDAP: as a moniker to use the ADSI interface to LDAP.

server_name

The name of the DCOM server on which the component should be loaded and run. If NULL, the object is run using the default for the application. The default is typically to run it on the local machine, although the administrator might have configured the application to launch on a different machine.

If you specify a non-NULL value for server, PHP will refuse to load the object unless the com.allow_dcom configuration option is set to TRUE.

If server_name is an array, it should contain the following elements (case sensitive!). Note that they are all optional (although you need to specify both Username and Password together); if you omit the Server setting, the default server will be used (as mentioned above), and the instantiation of the object will not be affected by the com.allow_dcom directive.

Tabla 1. DCOM server name

server_name keytypedescription
ServerstringThe name of the server.
UsernamestringThe username to connect as.
PasswordstringThe password for Username.
FlagsintegerOne or more of the following constants, logically OR'd together: CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER, CLSCTX_SERVER and CLSCTX_ALL. The default value if not specified here is CLSCTX_SERVER if you also omit Server, or CLSCTX_REMOTE_SERVER if you do specify a server. You should consult the Microsoft documentation for CoCreateInstance for more information on the meaning of these constants; you will typically never have to use them.

codepage

Specifies the codepage that is used to convert strings to unicode-strings and vice versa. The conversion is applied whenever a PHP string is passed as a parameter or returned from a method of this COM object. The code page is sticky in PHP 5, which means that it will propogate to objects and variants returned from the object.

Possible values are CP_ACP (use system default ANSI code page - the default if this parameter is omitted), CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP (use codepage/locale set for the current executing thread), CP_UTF7 and CP_UTF8. You may also use the number for a given codepage; consult the Microsoft documentation for more details on codepages and their numeric values.

Overloaded Methods

The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM.

Starting with PHP 5, PHP will automatically detect methods that accept parameters by reference, and will automatically convert regular PHP variables to a form that can be passed by reference. This means that you can call the method very naturally; you needn't go to any extra effort in your code.

In PHP 4, to pass parameters by reference you need to create an instance of the VARIANT class to wrap the byref parameters.

Pseudo Methods

In PHP versions prior to 5, a number of not very pleasant hacks meant that the following method names were not passed through to COM and were handled directly by PHP. PHP 5 eliminates these things; read the details below to determine how to fix your scripts. These magic method names are case insensitive.

void COM::AddRef ( void )

Artificially adds a reference count to the COM object.

Aviso

You should never need to use this method. It exists a logical complement to the Release() method below.

void COM::Release ( void )

Artificially removes a reference count from the COM object.

Aviso

You should never need to use this method. It's existence in PHP is a bug designed to work around a bug that keeps COM objects running longer than they should.

Pseudo Methods for Iterating

These pseudo methods are only available if com_isenum() returns TRUE, in which case, they hide any methods with the same names that might otherwise be provided by the COM object. These methods have all been eliminated in PHP 5, and you should use la sección de nombre For Each en Referencia VIII, Funciones COM y .Net (Windows) instead.

object COM::All ( void )

Returns a variant representing a SafeArray that has 10 elements; each element will be an empty/null variant. This function was supposed to return an array containing all the elements from the iterator, but was never completed. Do not use.

object COM::Next ( void )

Returns a variant representing the next element available from the iterator, or FALSE when there are no more elements.

object COM::Prev ( void )

Returns a variant representing the previous element available from the iterator, or FALSE when there are no more elements.

void COM::Reset ( void )

Rewinds the iterator back to the start.

COM examples

Ejemplo 1. COM example (1)

<?php
// starting word
$word = new COM("word.application") or die("Unable to instantiate Word");
echo "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 = null;
?>

Ejemplo 2. COM example (2)

<?php

$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 = null;
$conn = null;

?>

DOTNET

(no version information, might be only in CVS)

DOTNET -- DOTNET class

Sinopsis

$obj = new DOTNET("assembly", "classname")

Description

The DOTNET class allows you to instantiate a class from a .Net assembly and call its methods and access its properties.

Methods

string DOTNET::DOTNET ( string assembly name, string class_name [, int codepage])

DOTNET class constructor. assembly_name specifies which assembly should be loaded, and class_name specifices which class in that assembly to instantiate. You may optionally specify a codepage to use for unicode string transformations; see the COM class for more details on code pages.

The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM and from there to DOTNET. In other words, the .Net object is mapped through the COM interoperability layer provided by the .Net runtime.

Once you have created a DOTNET object, PHP treats it identically to any other COM object; all the same rules apply.

Ejemplo 1. DOTNET example

<?php
  $stack = new DOTNET("mscorlib", "System.Collections.Stack"); 
  $stack->Push(".Net"); 
  $stack->Push("Hello "); 
  echo $stack->Pop() . $stack->Pop(); 
?>

Nota: You need to install the .Net runtime on your web server to take advantage of this feature.

VARIANT

(no version information, might be only in CVS)

VARIANT -- VARIANT class

Sinopsis

$vVar = new VARIANT($var)

Description

The VARIANT is COM's equivalent of the PHP zval; it is a structure that can contain a value with a range of different possible types. The VARIANT class provided by the COM extension allows you to have more control over the way that PHP passes values to and from COM.

Methods

object VARIANT::VARIANT ( [mixed value [, int type [, int codepage]]])

VARIANT class constructor. Parameters:

value

initial value. if omitted, or set to NULL an VT_EMPTY object is created.

type

specifies the content type of the VARIANT object. Possible values are one of the VT_XXX la sección de nombre Constantes predefinidas en Referencia VIII, Funciones COM y .Net (Windows).

In PHP versions prior to PHP 5, you could force PHP to pass a variant object by reference by OR'ing VT_BYREF with the type. In PHP 5, this hack is not supported; instead, PHP 5 can detect parameters passed by reference automatically; they do not even need to be passed as VARIANT objects.

Consult the MSDN library for additional information on the VARIANT type.

codepage

specifies the codepage that is used to convert strings to unicode. See the parameter of the same name in the COM class for more information.

PHP versions prior to PHP 5 define a number of (undocumented) virtual properties for instances of the VARIANT class; these properties have all been removed in PHP 5 in favour of its more natural syntax; these differences are best highlighted by example:

Ejemplo 1. Variant example, PHP 4.x style

<?php
$v = new VARIANT(42);
print "The type is " . $v->type . "<br/>";
print "The value is " . $v->value . "<br/>";
?>

Ejemplo 2. Variant example, PHP 5 style

<?php
$v = new VARIANT(42);
print "The type is " . variant_get_type($v) . "<br/>";
print "The value is " . $v . "<br/>";
?>

The reason for the change is that, internally, the COM extension sees VARIANT, COM and DOTNET classes as the same thing, and the design philosophy for these classes is that all property and member accesses are passed through to COM with no interference. The new syntax is more natural and less effort, and most of the removed virtual properties didn't make any sense in a PHP context in any case.

Nota: PHP 5 takes a much simpler approach to handling VARIANTs; when returning a value or fetching a variant property, the variant is converted to a PHP value only when there is a direct mapping between the types that would not result in a loss of information. In all other cases, the result is returned as an instance of the VARIANT class. You can force PHP to convert or evaluate the variant as a PHP native type by using a casting operator explicitly, or implicitly casting to a string by print()ing it. You may use the wide range of variant functions to perform arithmetic operations on variants without forcing a conversion or risking a loss of data.

See also variant_get_type().

com_addref

(PHP 4 >= 4.1.0)

com_addref --  Increases the components reference counter [deprecated]

Description

void com_addref ( void )

Increases the components reference counter.

Aviso

You should never need to use this function.

Nota: This function has gone away in PHP 5.

com_create_guid

(PHP 5)

com_create_guid --  Generate a globally unique identifier (GUID)

Description

string com_create_guid ( void )

Generates a Globally Unique Identifier (GUID) and returns it as a string. A GUID is generated in the same way as DCE UUID's, except that the Microsoft convention is to enclose a GUID in curly braces.

See also uuid_create() in the PECL uuid extension.

com_event_sink

(PHP 4 >= 4.2.3, PHP 5)

com_event_sink --  Connect events from a COM object to a PHP object

Description

bool com_event_sink ( object comobject, object sinkobject [, mixed sinkinterface])

Instructs COM to sink events generated by comobject into the PHP object sinkobject. PHP will attempt to use the default dispinterface type specified by the typelibrary associated with comobject, but you may override this choice by setting sinkinterface to the name of the dispinterface that you want to use.

sinkobject should be an instance of a class with methods named after those of the desired dispinterface; you may use com_print_typeinfo() to help generate a template class for this purpose.

Be careful how you use this feature; if you are doing something similar to the example below, then it doesn't really make sense to run it in a web server context.

Ejemplo 1. COM event sink example

<?php
class IEEventSinker {
  var $terminated = false;

  function ProgressChange($progress, $progressmax) {
    echo "Download progress: $progress / $progressmax\n";
  }

  function DocumentComplete(&$dom, $url) {
    echo "Document $url complete\n";
  }

  function OnQuit() {
    echo "Quit!\n";
    $this->terminated = true;
  }
}
$ie = new COM("InternetExplorer.Application");
// note that you don't need the & for PHP 5!
$sink =& new IEEventSinker();
com_event_sink($ie, $sink, "DWebBrowserEvents2");
$ie->Visible = true;
$ie->Navigate("http://www.php.net");
while(!$sink->terminated) {
  com_message_pump(4000);
}
$ie = null;
?>

See also com_print_typeinfo(), com_message_pump().

com_get_active_object

(no version information, might be only in CVS)

com_get_active_object --  Returns a handle to an already running instance of a COM object

Description

object com_get_active_object ( string progid [, int code_page])

com_get_active_object() is similar to creating a new instance of a COM object, except that it will only return an object to your script if the object is already running. OLE applications use something known as the Running Object Table to allow well-known applications to be launched only once; this function exposes the COM library function GetActiveObject() to get a handle on a running instance.

progid must be either the ProgID or CLSID for the object that you want to access (for example Word.Application). code_page acts in precisely the same way that it does for the COM class.

If the requestested object is running, it will be returned to your script just like any other COM object. Otherwise a com_exception will be raised. There are a variety of reasons why this function might fail, the most common being that the object is not already running. In that situation, the exception error code will be MK_E_UNAVAILABLE; you can use the getCode method of the exception object to check the exception code.

Aviso

Using com_get_active_object() in a web server context is not always a smart idea. Most COM/OLE applications are not designed to handle more than one client concurrently, even (or especially!) Microsoft Office. You should read Considerations for Server-Side Automation of Office for more information on the general issues involved.

com_get

(PHP 3>= 3.0.3, PHP 4 >= 4.0.5)

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

(PHP 4 >= 4.1.0)

com_isenum -- Indicates if a COM object has an IEnumVariant interface for iteration [deprecated]

Description

boolean com_isenum ( object com_module)

Checks to see if a COM object can be enumerated using the Next() method hack. Returns TRUE if it can, FALSE if it cannot. See COM class for more details on these methods.

Nota: This function does not exist in PHP 5; use the more natural la sección de nombre foreach en Capítulo 11 statement to iterate over the contents of COM objects. See la sección de nombre For Each en Referencia VIII, Funciones COM y .Net (Windows) for more details.

com_load_typelib

(PHP 4 >= 4.1.0, PHP 5)

com_load_typelib -- Loads a Typelib

Description

bool com_load_typelib ( string typelib_name [, int case_insensitive])

Loads a type-library and registers its constants in the engine, as though they were defined using define(). The case_insensitive behaves in the same way as the parameter with the same name in the define() function.

typelib_name can be one of the following:

  • The filename of a .tlb file or the executable module that contains the type library.

  • The type library GUID, followed by its version number, for example {00000200-0000-0010-8000-00AA006D2EA4},2,0.

  • The type library name, e.g. Microsoft OLE DB ActiveX Data Objects 1.0 Library.

PHP will attempt to resolve the type library in this order, as the process gets more and more expensive as you progress down the list; searching for the type library by name is handled by physically enumerating the registry until we find a match.

Note that it is much more efficient to use the com.typelib_file configuration setting to pre-load and register the constants, although not so flexible.

If you have turned on com.autoregister_typelib , then PHP will attempt to automatically register the constants associated with a COM object when you instantiate it. This depends on the interfaces provided by the COM object itself, and may not always be possible.

com_load

(PHP 3>= 3.0.3)

com_load -- ???

Descripción

string com_load ( string module name [, string server name])

com_message_pump

(PHP 4 >= 4.2.3, PHP 5)

com_message_pump --  Process COM messages, sleeping for up to timeoutms milliseconds

Description

bool com_message_pump ( [int timeoutms])

This function will sleep for up to timeoutms milliseconds, or until a message arrives in the queue. If a message or messages arrives before the timeout, they will be dispatched, and the function will return TRUE. If the timeout occurs and no messages were processed, the return value will be FALSE. If you do not specify a value for timeoutms, then 0 will be assumed. A 0 value means that no waiting will be performed; if there are messages pending they will be dispatched as before; if there are no messages pending, the function will return FALSE immediately without sleeping.

The purpose of this function is to route COM calls between apartments and handle various synchronization issues. This allows your script to wait efficiently for events to be triggered, while still handling other events or running other code in the background. You should use it in a loop, as demonstrated by the example in the com_event_sink() function, until you are finished using event bound COM objects.

com_print_typeinfo

(PHP 4 >= 4.2.3, PHP 5)

com_print_typeinfo --  Print out a PHP class definition for a dispatchable interface

Description

bool com_print_typeinfo ( object comobject, string dispinterface, bool wantsink)

The purpose of this function is to help generate a skeleton class for use as an event sink. You may also use it to generate a dump of any COM object, provided that it supports enough of the introspection interfaces, and that you know the name of the interface you want to display.

comobject should be either an instance of a COM object, or be the name of a typelibrary (which will be resolved according to the rules set out in com_load_typelib()). dispinterface is the name of an IDispatch descendant interface that you want to display. If wantsink is TRUE, the corresponding sink interface will be displayed instead.

See also com_event_sink(), com_load_typelib().

com_propget

(PHP 3>= 3.0.3, PHP 4 >= 4.0.5)

com_propget -- ???

Descripción

mixed com_propget ( resource object, string property)

com_propput

(PHP 3>= 3.0.3, PHP 4 >= 4.0.5)

com_propput -- ???

Descripción

void com_propput ( resource object, string property, mixed value)

com_propset

(PHP 3>= 3.0.3, PHP 4 >= 4.0.5)

com_propset -- ???

Descripción

void com_propset ( resource object, string property, mixed value)

Esta función es un alias para com_propput().

com_release

(PHP 4 >= 4.1.0)

com_release --  Decreases the components reference counter [deprecated]

Description

void com_release ( void )

Decreases the components reference counter.

Aviso

You should never need to use this function.

Nota: This function has gone away in PHP 5.

com_set

(PHP 3>= 3.0.3, PHP 4 >= 4.0.5)

com_set -- ???

Descripción

void com_set ( resource object, string property, mixed value)

Esta función es un alias para com_set().

variant_abs

(PHP 5)

variant_abs --  Returns the absolute value of a variant

Description

mixed variant_abs ( mixed val)

Returns the absolute value of val.

See also abs().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_add

(PHP 5)

variant_add --  "Adds" two variant values together and returns the result

Description

mixed variant_add ( mixed left, mixed right)

Adds left to right using the following rules (taken from the MSDN library), which correspond to those of Visual Basic:

Tabla 1. Variant Addition Rules

IfThen
Both expressions are of the string typeConcatenation
One expression is a string type and the other a characterAddition
One expression is numeric and the other is a stringAddition
Both expressions are numericAddition
Either expression is NULLNULL is returned
Both expressions are emptyInteger subtype is returned

See also variant_sub().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_and

(PHP 5)

variant_and --  performs a bitwise AND operation between two variants and returns the result

Description

mixed variant_and ( mixed left, mixed right)

Performs a bitwise AND operation, according to the following truth table; note that this is slightly different from a regular AND operation.

Tabla 1. Variant AND Rules

If left isIf right isthen the result is
TRUETRUETRUE
TRUEFALSEFALSE
TRUENULLNULL
FALSETRUEFALSE
FALSEFALSEFALSE
FALSENULLFALSE
NULLTRUENULL
NULLFALSEFALSE
NULLNULLNULL

See also variant_or().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_cast

(PHP 5)

variant_cast --  Convert a variant into a new variant object of another type

Description

object variant_cast ( object variant, int type)

This function makes a copy of variant and then performs a variant cast operation to force the copy to have the type given by type. type should be one of the VT_XXX constants.

This function wraps VariantChangeType() in the COM library; consult MSDN for more information.

See also variant_set_type().

variant_cat

(PHP 5)

variant_cat --  concatenates two variant values together and returns the result

Description

mixed variant_cat ( mixed left, mixed right)

Concatenates left with right and returns the result.

See also la sección de nombre Operadores de Cadena en Capítulo 10 for the string concatenation operator; this function is notionally equivalent to $left . $right.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_cmp

(PHP 5)

variant_cmp --  Compares two variants

Description

int variant_cmp ( mixed left, mixed right [, int lcid [, int flags]])

Compares left with right and returns one of the following values:

Tabla 1. Variant Comparision Results

valuemeaning
VARCMP_LTleft is less than right
VARCMP_EQleft is equal to right
VARCMP_GTleft is greater than right
VARCMP_NULLEither left, right or both are NULL

This function will only compare scalar values, not arrays or variant records.

lcid is a valid Locale Identifier to use when comparing strings (this affects string collation). flags can be one or more of the following values OR'd together, and affects string comparisons:

Tabla 2. Variant Comparision Flags

valuemeaning
NORM_IGNORECASECompare case insensitively
NORM_IGNORENONSPACEIgnore nonspacing characters
NORM_IGNORESYMBOLSIgnore symbols
NORM_IGNOREWIDTHIgnore string width
NORM_IGNOREKANATYPEIgnore Kana type
NORM_IGNOREKASHIDAIgnore Arabic kashida characters

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_date_from_timestamp

(PHP 5)

variant_date_from_timestamp --  Returns a variant date representation of a unix timestamp

Description

object variant_date_from_timestamp ( int timestamp)

Converts timestamp from a unix timestamp value into a variant of type VT_DATE. This allows easier interopability between the unix-ish parts of PHP and COM.

See also variant_date_to_timestamp() for the inverse of this operation, mktime(), time().

variant_date_to_timestamp

(PHP 5)

variant_date_to_timestamp --  Converts a variant date/time value to unix timestamp

Description

int variant_date_to_timestamp ( object variant)

Converts variant from a VT_DATE (or similar) value into a unix timestamp. This allows easier interopability between the unix-ish parts of PHP and COM.

See also variant_date_from_timestamp() for the inverse of this operation, date(), strftime().

variant_div

(PHP 5)

variant_div --  Returns the result from dividing two variants

Description

mixed variant_div ( mixed left, mixed right)

Divides left by right and returns the result, subject to the following rules:

Tabla 1. Variant Division Rules

IfThen
Both expressions are of the string, date, character, boolean typeDouble is returned
One expression is a string type and the other a characterDivision and a double is returned
One expression is numeric and the other is a stringDivision and a double is returned.
Both expressions are numericDivision and a double is returned
Either expression is NULLNULL is returned
right is empty and left is anything but emptyA com_exception with code DISP_E_DIVBYZERO is thrown
left is empty and right is anything but empty.0 as type double is returned
Both expressions are emptyA com_exception with code DISP_E_OVERFLOW is thrown

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_eqv

(PHP 5)

variant_eqv --  Performs a bitwise equivalence on two variants

Description

mixed variant_eqv ( mixed left, mixed right)

If each bit in left is equal to the corresponding bit in right then TRUE is returned, otherwise FALSE is returned.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_fix

(PHP 5)

variant_fix --  Returns the integer portion ? of a variant

Description

mixed variant_fix ( mixed variant)

If variant is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of variant.

See also variant_int(), variant_round(), floor(), ceil(), round().

Aviso

This documentation is based on the MSDN documentation; it appears that this function is either the same as variant_int(), or that there is an error in the MSDN documentation.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_get_type

(PHP 5)

variant_get_type -- Returns the type of a variant object

Description

int variant_get_type ( object variant)

This function returns an integer value that indicates the type of variant, which can be an instance of COM, DOTNET or VARIANT classes. The return value can be compared to one of the VT_XXX constants.

The return value for COM and DOTNET objects will usually be VT_DISPATCH; the only reason this function works for those classes is because COM and DOTNET are descendants of VARIANT.

In PHP versions prior to 5, you could obtain this information from instances of the VARIANT class ONLY, by reading a fake type property. See the VARIANT class for more information on this.

variant_idiv

(PHP 5)

variant_idiv --  Converts variants to integers and then returns the result from dividing them

Description

mixed variant_idiv ( mixed left, mixed right)

Converts left and right to integer values, and then performs integer division according the following rules:

Tabla 1. Variant Integer Division Rules

IfThen
Both expressions are of the string, date, character, boolean typeDivision and integer is returned
One expression is a string type and the other a characterDivision
One expression is numeric and the other is a stringDivision
Both expressions are numericDivision
Either expression is NULLNULL is returned
Both expressions are emptyA com_exception with code DISP_E_DIVBYZERO is thrown

See also variant_div().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_imp

(PHP 5)

variant_imp --  Performs a bitwise implication on two variants

Description

mixed variant_imp ( mixed left, mixed right)

Performs a bitwise implication operation, according to the following truth table:

Tabla 1. Variant Implication Table

If left isIf right isthen the result is
TRUETRUETRUE
TRUEFALSETRUE
TRUENULLTRUE
FALSETRUETRUE
FALSEFALSETRUE
FALSENULLTRUE
NULLTRUETRUE
NULLFALSENULL
NULLNULLNULL

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_int

(PHP 5)

variant_int --  Returns the integer portion of a variant

Description

mixed variant_int ( mixed variant)

If variant is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of variant.

See also variant_fix(), variant_round(), floor(), ceil(), round().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_mod

(PHP 5)

variant_mod --  Divides two variants and returns only the remainder

Description

mixed variant_mod ( mixed left, mixed right)

Divides left by right and returns the remainder.

See also variant_div(), variant_idiv().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_mul

(PHP 5)

variant_mul --  multiplies the values of the two variants and returns the result

Description

mixed variant_mul ( mixed left, mixed right)

Multiplies left by right and returns the result, subject to the following rules:

Tabla 1. Variant Multiplication Rules

IfThen
Both expressions are of the string, date, character, boolean typeMultiplication
One expression is a string type and the other a characterMultiplication
One expression is numeric and the other is a stringMultiplication
Both expressions are numericMultiplication
Either expression is NULLNULL is returned
Both expressions are emptyEmpty string is returned

Boolean values are converted to -1 for FALSE and 0 for TRUE.

See also variant_div(), variant_idiv().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_neg

(PHP 5)

variant_neg --  Performs logical negation on a variant

Description

mixed variant_neg ( mixed variant)

Performs logical negation of variant and returns the result.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_not

(PHP 5)

variant_not --  Performs bitwise not negation on a variant

Description

mixed variant_not ( mixed variant)

Performs bitwise not negation on variant and returns the result. If variant is NULL, the result will also be NULL.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_or

(PHP 5)

variant_or --  Performs a logical disjunction on two variants

Description

mixed variant_or ( mixed left, mixed right)

Performs a bitwise OR operation, according to the following truth table; note that this is slightly different from a regular OR operation.

Tabla 1. Variant OR Rules

If left isIf right isthen the result is
TRUETRUETRUE
TRUEFALSETRUE
TRUENULLTRUE
FALSETRUETRUE
FALSEFALSEFALSE
FALSENULLNULL
NULLTRUETRUE
NULLFALSENULL
NULLNULLNULL

See also variant_and(), variant_xor().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_pow

(PHP 5)

variant_pow --  Returns the result of performing the power function with two variants

Description

mixed variant_pow ( mixed left, mixed right)

Returns the result of left to the power of right.

See also pow().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_round

(PHP 5)

variant_round --  Rounds a variant to the specified number of decimal places

Description

mixed variant_round ( mixed variant, int decimals)

Returns the value of variant rounded to decimals decimal places.

See also round().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_set_type

(PHP 5)

variant_set_type --  Convert a variant into another type. Variant is modified "in-place"

Description

void variant_set_type ( object variant, int type)

This function is similar to variant_cast() except that the variant is modified "in-place"; no new variant is created. The parameters for this function have identical meaning to those of variant_cast().

See also variant_cast().

variant_set

(PHP 5)

variant_set --  Assigns a new value for a variant object

Description

void variant_set ( object variant, mixed value)

Converts value to a variant and assigns it to the variant object; no new variant object is created, and the old value of variant is freed/released.

variant_sub

(PHP 5)

variant_sub --  subtracts the value of the right variant from the left variant value and returns the result

Description

mixed variant_sub ( mixed left, mixed right)

Subtracts right from left using the following rules:

Tabla 1. Variant Subtraction Rules

IfThen
Both expressions are of the string typeSubtraction
One expression is a string type and the other a characterSubtraction
One expression is numeric and the other is a stringSubtraction.
Both expressions are numericSubtraction
Either expression is NULLNULL is returned
Both expressions are emptyEmpty string is returned

See also variant_add().

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.

The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP